npm - @rashidee/co2 - Versions diffs - 1.3.16 → 1.3.18 - Mend

@rashidee/co2 1.3.16 → 1.3.18

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (9) hide show

package/dist/.co2-dat/app.db-shm +0 -0
package/dist/.co2-dat/app.db-wal +0 -0
package/dist/index.js +5 -1
package/drizzle/0020_cicd_guard_token.sql +4 -0
package/drizzle/meta/_journal.json +8 -1
package/package.json +1 -1
package/plugin/skills/util-gencicdscript/SKILL.md +13 -19
package/plugin/skills/util-gencicdscript/references/cicd-app-template.md +23 -90
package/plugin/skills/util-plancicd/SKILL.md +305 -310

package/dist/.co2-dat/app.db-shm CHANGED Viewed

Binary file

package/dist/.co2-dat/app.db-wal CHANGED Viewed

Binary file

package/dist/index.js CHANGED Viewed

@@ -6809,7 +6809,7 @@ var {
 // package.json
 var package_default = {
   name: "@rashidee/co2",
-  version: "1.3.16",
+  version: "1.3.18",
   description: "Compound Context Studio \u2014 self-hosted team context authoring for CO2 projects",
   type: "module",
   license: "MIT",
@@ -14735,6 +14735,10 @@ var cicdSetups = sqliteTable(
     // project_configs.updatedAt at generation
     appPort: integer("app_port"),
     // last spawned port of the generated app
+    // Guard token issued to the last spawned app (also kept in memory). Persisted so an app
+    // that outlives a studio restart still passes /api/cicd-guard — otherwise its develop
+    // gate reads "studio unreachable" and every control stays disabled until a manual bounce.
+    guardToken: text("guard_token"),
     createdBy: integer("created_by").notNull(),
     // soft ref → users.id
     createdAt: text("created_at").notNull(),

package/drizzle/0020_cicd_guard_token.sql ADDED Viewed

@@ -0,0 +1,4 @@
+-- v2.3.1: Persist the generated CI/CD app's guard token. The token was in-memory only, so a
+-- studio restart orphaned a still-running app: its spawn-env token no longer validated against
+-- /api/cicd-guard, the develop gate read "studio unreachable" and every control stayed disabled.
+ALTER TABLE `cicd_setups` ADD `guard_token` text;

package/drizzle/meta/_journal.json CHANGED Viewed

@@ -141,6 +141,13 @@
       "when": 1785000000000,
       "tag": "0019_git_provider",
       "breakpoints": true
+    },
+    {
+      "idx": 20,
+      "version": "6",
+      "when": 1785100000000,
+      "tag": "0020_cicd_guard_token",
+      "breakpoints": true
     }
   ]
-}
+}

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@rashidee/co2",
-  "version": "1.3.16",
+  "version": "1.3.18",
   "description": "Compound Context Studio — self-hosted team context authoring for CO2 projects",
   "type": "module",
   "license": "MIT",

package/plugin/skills/util-gencicdscript/SKILL.md CHANGED Viewed

@@ -21,12 +21,12 @@ description: >
   copy, docker run or kubectl apply, or none). Controls are disabled for any application that
   has never completed a conductor-develop workflow run (checked against the studio's
   /api/cicd-guard endpoint using the spawn-env token). Health/port probing marks apps already
-  running — even ones started outside this app. The top bar carries a version selector (fed by
-  the studio guard's versions, latest preselected) whose choice replaces the {VERSION} token in
-  commands — docker images are tagged <repo>/<app>:<version> when the plan's Docker section is
-  active (managed Dockerfiles materialized before Build when missing; Build never pushes) — and
-  Build All / Start All / Stop All buttons operating every eligible application at once
-  (sequential builds). When the approved plan declares an `## Infrastructure` list, the
+  running — even ones started outside this app. There is NO version selector and there are NO
+  Build All / Start All / Stop All buttons — every control operates per application on the
+  current working tree, and the plan's commands run verbatim (no {VERSION} or other token
+  substitution) — docker images are tagged <repo>/<app>:latest when the plan's Docker section
+  is active (managed Dockerfiles materialized before Build when missing; Build never
+  pushes). When the approved plan declares an `## Infrastructure` list, the
   main page shows an "Infrastructure" link that opens a separate status-only page listing every
   supporting 3rd-party service with a live TCP-reachability indicator and a console link. Writes cicd/CICD_GENERATION.md with `**Status**:` IN PROGRESS →
   COMPLETED so the studio watcher detects completion. Idempotent — re-running regenerates
@@ -75,8 +75,8 @@ Read `references/cicd-app-template.md` for the complete file templates. Produce:
    `{ "path": "Dockerfile", "content": "<body>" }` for a `managed` Dockerfile from the plan's
    `## Dockerfiles` section, or `{ "path": "Dockerfile", "content": null }` for an `existing`
    one (`null` entirely when the app has no image). Copy managed Dockerfile bodies verbatim.
-   Commands may carry the literal `{VERSION}` token — copy it verbatim; the generated app
-   substitutes it at execution. `deployMethod` is the plan's Deploy Method column
+   Commands are copied verbatim from the plan and run as-is — there is NO `{VERSION}` token
+   or any other placeholder substitution. `deployMethod` is the plan's Deploy Method column
    (`none|web-server|docker|kubernetes`) and `deploy` its command (`null` when the method is
    `none`). The `infra` array comes from the plan's `## Infrastructure` table (one entry per
    row); `url` is `null` when the Console URL cell is `-`. Emit `"infra": []` when the plan's
@@ -163,21 +163,15 @@ port, application count) and STOP — the studio starts/embeds the app.
   (`<project>/<folder>`) as working directory — command paths are relative to the application
   folder (e.g. `java -jar target\app.jar`), never to the project root. Deploy renders only
   when the plan assigned a deploy method other than `none`.
-- **Version selector (topbar)**: the page's top bar carries a version dropdown fed by the
-  studio guard response's `versions` array (already polled every 30 s; latest first —
-  preselected). When the studio is unreachable the selector holds a single `latest` entry.
-  The selected semver, minus its `v` prefix, replaces every literal `{VERSION}` in
-  build/start/stop/deploy commands at execution time (fallback `latest`). Tag-only
-  semantics: the code built is always the working tree — the selector never checks out code.
+- **NO version UI, NO All-apps buttons, NO command substitution**: the page carries NO
+  version dropdown or any other version choice, and NO Build All / Start All / Stop All
+  buttons — Build/Start/Stop/Deploy are per-application only and always operate on the
+  CURRENT working tree, running the plan's commands verbatim (no `{VERSION}` or other token
+  substitution). Never render a version control and never check out code.
 - **Dockerfile materialization**: before Build, when an app's `dockerfile.content` is set and
   no file exists at its path in the application folder, the server writes it (never
   overwriting an existing Dockerfile — mirror of the managed-config rule). Build never
   pushes an image; pushing belongs to a `docker` deploy command.
-- **All-apps controls**: the top bar carries **Build All**, **Start All** and **Stop All**
-  buttons. Build All builds eligible apps SEQUENTIALLY (one at a time — honest logs, no CPU
-  storm); Start All starts every eligible stopped app; Stop All stops every running app.
-  Eligible = develop-gate not failed, not busy, and (for build/start) not already running;
-  ineligible apps are skipped silently — per-tab badges show progress.
 - Develop gate: controls stay disabled for an application that never completed a
   conductor-develop run — checked via `${CO2_STUDIO_URL}/api/cicd-guard/${CO2_PROJECT_ID}`
   with the CO2_GUARD_TOKEN from the spawn env (refreshed every 30 s, last answer cached).

package/plugin/skills/util-gencicdscript/references/cicd-app-template.md CHANGED Viewed

@@ -66,7 +66,6 @@ function currentBranch() {
 // its tab controls are disabled. Refreshed every 30 s; the last known answer is kept when the
 // studio is briefly unreachable, and `null` (never fetched) disables controls with a hint.
 let guardApps = null // Map lower(name|folder) -> developedOnce
-let guardVersions = [] // project versions (semver strings, studio order — latest first)
 async function refreshGuard() {
   if (!PROJECT_ID) return
   try {
@@ -77,8 +76,6 @@ async function refreshGuard() {
       guardApps = new Map()
       for (const a of g.applications) guardApps.set(String(a.name).toLowerCase(), !!a.developedOnce)
     }
-    // The topbar version selector's choices — the {VERSION} tag substituted into commands.
-    if (Array.isArray(g.versions)) guardVersions = g.versions.map((v) => String(v.semver)).filter(Boolean)
   } catch {}
 }
 function developedOnce(app) {
@@ -229,13 +226,6 @@ function tcpProbe(host, port, timeout = 1000) {
   })
 }
-// {VERSION} token substitution — the version comes from the page's topbar selector (the
-// studio guard's versions, latest preselected). Tag-only: never checks out code. The `v`
-// prefix is stripped so docker tags read `1.2.0`, not `v1.2.0`.
-function subst(cmd, version) {
-  return String(cmd || '').replaceAll('{VERSION}', String(version || 'latest').replace(/^v/, ''))
-}
 // Managed Dockerfile from the plan's ## Dockerfiles — written before Build only when the
 // application folder has none (an existing Dockerfile is never overwritten).
 function ensureDockerfile(app) {
@@ -249,38 +239,37 @@ function ensureDockerfile(app) {
   } catch (e) { logLine(app, `dockerfile: FAILED to write — ${e.message}`) }
 }
-function buildApp(app, version, onDone) {
-  if (activity.has(app.name)) { onDone && onDone(); return }
+function buildApp(app) {
+  if (activity.has(app.name)) return
   activity.set(app.name, 'building'); lastError.delete(app.name)
   ensureConfigs(app)
   ensureDockerfile(app)
-  runLogged(app, subst(app.build, version), (code) => {
+  runLogged(app, app.build, (code) => {
     activity.delete(app.name)
     if (code !== 0) lastError.set(app.name, `build exited ${code} — see log`)
     else logLine(app, 'build OK')
-    onDone && onDone()
   })
 }
-function deployApp(app, version) {
+function deployApp(app) {
   if (activity.has(app.name) || !app.deploy) return
   activity.set(app.name, 'deploying'); lastError.delete(app.name)
-  runLogged(app, subst(app.deploy, version), (code) => {
+  runLogged(app, app.deploy, (code) => {
     activity.delete(app.name)
     if (code !== 0) lastError.set(app.name, `deploy exited ${code} — see log`)
     else logLine(app, `deploy OK (${app.deployMethod})`)
   })
 }
-function startApp(app, version) {
+function startApp(app) {
   if (running.get(app.name) || activity.has(app.name)) return
   failed.delete(app.name); lastError.delete(app.name)
   ensureConfigs(app)
   if (app.method === 'container') {
-    runLogged(app, subst(app.start, version), () => {})
+    runLogged(app, app.start, () => {})
     saveState(); return
   }
-  const child = runLogged(app, subst(app.start, version), (code) => {
+  const child = runLogged(app, app.start, (code) => {
     running.delete(app.name)
     // A user-requested Stop exits nonzero (killed) — that is not a failure.
     if (code !== 0 && !stopping.delete(app.name)) {
@@ -327,9 +316,9 @@ function killByPort(port) {
   } catch { return false }
 }
-function stopApp(app, version) {
+function stopApp(app) {
   if (app.method === 'container' && app.stop && app.stop !== 'process-kill') {
-    const stopCmd = subst(app.stop, version)
+    const stopCmd = app.stop
     try { execFileSync(stopCmd.split(' ')[0], stopCmd.split(' ').slice(1), { cwd: PROJECT_DIR }) } catch {}
   } else {
     const child = running.get(app.name)
@@ -368,7 +357,6 @@ body{font-family:system-ui,sans-serif;margin:0;background:#f6f7f9;color:#1c2128;
 .badge.running{background:#1c8a4a}.badge.failed{background:#c23b3b}.badge.building,.badge.deploying{background:#c9922a}
 .url{font-size:12px;color:#1a66d0;text-decoration:underline;word-break:break-all}
 button{background:#fff;color:#1c2128;border:1px solid #c6cdd6;border-radius:6px;padding:4px 12px;font-size:12px;cursor:pointer}
-select{background:#fff;color:#1c2128;border:1px solid #c6cdd6;border-radius:6px;padding:3px 6px;font-size:12px}
 button:hover:enabled{background:#eef1f5}
 button:disabled{opacity:.4;cursor:default}
 .notice{padding:4px 12px;font-size:11px;color:#8a5a00;background:#fff7e6;display:none}
@@ -389,10 +377,6 @@ button:disabled{opacity:.4;cursor:default}
 .cfg pre{background:#0f1216;color:#d7dde4;font-size:11px;padding:8px 10px;border-radius:6px;overflow:auto;max-height:320px;white-space:pre-wrap;margin:4px 0 0}
 </style></head><body>
 <div class="top"><strong>CI/CD</strong><span id="branch" class="meta"></span>
-<span class="meta">version</span><select id="ver" title="Tag substituted into {VERSION} in commands (docker image tag)"><option value="">latest</option></select>
-<button onclick="actAll('build')" title="Build every eligible application, one at a time">Build All</button>
-<button onclick="actAll('start')" title="Start every eligible stopped application">Start All</button>
-<button onclick="actAll('stop')" title="Stop every running application">Stop All</button>
 <span style="flex:1"></span><a id="infralink" class="url" href="infra" target="_blank" rel="noreferrer" style="display:none">Infrastructure ↗</a></div>
 <div class="tabs" id="tabs"></div>
 <div class="bar" id="bar"></div>
@@ -431,7 +415,7 @@ function renderBar(){
     <a class="url" href="\${url}" target="_blank" rel="noreferrer">\${url}</a>
     <span style="flex:1"></span>
     <button onclick="openConfig()" title="Show this application's runtime configuration files">Config</button>
-    <button onclick="act('build')" \${!gate||busy||a.phase==='running'?'disabled':''} title="\${a.image?'Builds the app AND the docker image '+a.image+':<version>':'Runs the plan build command'}">Build</button>
+    <button onclick="act('build')" \${!gate||busy||a.phase==='running'?'disabled':''} title="\${a.image?'Builds the app AND the docker image '+a.image+':latest':'Runs the plan build command'}">Build</button>
     <button onclick="act('start')" \${!gate||busy||a.phase==='running'?'disabled':''}>Start</button>
     <button onclick="act('stop')" \${a.phase!=='running'?'disabled':''}>Stop</button>
     \${a.deploy?\`<button onclick="act('deploy')" \${!gate||busy?'disabled':''}>Deploy (\${a.deployMethod})</button>\`:''}\`
@@ -461,7 +445,10 @@ function setActive(name){
 function openWs(name){
   // Path-relative + scheme-aware so the stream works direct (:5000/) AND behind the studio's
   // /api/cicd/<id>/app-proxy/ prefix (which tunnels the upgrade), also under HTTPS.
-  ws = new WebSocket((location.protocol==='https:'?'wss://':'ws://')+location.host+location.pathname.replace(/\/$/,'')+'/ws?app='+encodeURIComponent(name))
+  // NO backslash/regex here on purpose: this string is inside server.js's PAGE template literal,
+  // where a client-side regex like /\/$/ cooks to //$/ (a line comment) and kills the script.
+  var base = location.pathname.endsWith('/') ? location.pathname.slice(0, -1) : location.pathname
+  ws = new WebSocket((location.protocol==='https:'?'wss://':'ws://')+location.host+base+'/ws?app='+encodeURIComponent(name))
   ws.onmessage = e => appendLog(e.data)
   ws.onclose = () => { ws = null; if (active === name) wsTimer = setTimeout(() => openWs(name), 2000) }
 }
@@ -501,35 +488,17 @@ async function openConfig(){
 function closeConfig(){ document.getElementById('cfgModal').classList.remove('open') }
 document.addEventListener('keydown', e => { if (e.key === 'Escape') closeConfig() })
-// Topbar version selector — the studio guard's project versions (latest first). Repopulated
-// only when the list changes so the user's selection survives the 3 s poll.
-let verChoices = ''
-function renderVersions(versions){
-  const sel = document.getElementById('ver')
-  const list = (versions && versions.length ? versions : []).join('|')
-  if (list === verChoices) return
-  verChoices = list
-  sel.innerHTML = (versions && versions.length ? versions : ['latest'])
-    .map((v, i) => '<option value="'+esc(v)+'"'+(i===0?' selected':'')+'>'+esc(v)+'</option>').join('')
-}
-function selectedVersion(){ return document.getElementById('ver').value || '' }
 async function refresh(){
   const s = await fetch('api/state').then(r => r.json()).catch(() => null)
   if (!s) return
   state = s
   document.getElementById('branch').textContent = s.currentBranch ? 'branch: '+s.currentBranch : ''
   document.getElementById('infralink').style.display = s.hasInfra ? 'inline' : 'none'
-  renderVersions(s.versions)
   if (!active && s.apps.length) setActive(s.apps[0].name)
   renderTabs(); renderBar()
 }
 async function act(op){
-  await fetch('api/apps/'+encodeURIComponent(active)+'/'+op+'?version='+encodeURIComponent(selectedVersion()), { method: 'POST' })
-  refresh()
-}
-async function actAll(op){
-  await fetch('api/all/'+op+'?version='+encodeURIComponent(selectedVersion()), { method: 'POST' })
+  await fetch('api/apps/'+encodeURIComponent(active)+'/'+op, { method: 'POST' })
   refresh()
 }
 // Rescan immediately when the user returns to this page (tab focus / regained visibility), so
@@ -614,7 +583,6 @@ const server = http.createServer(async (req, res) => {
     return json(res, 200, {
       currentBranch: currentBranch(),
       hasInfra: (loadConfig().infra || []).length > 0,
-      versions: guardVersions,
       apps,
     })
   }
@@ -624,10 +592,6 @@ const server = http.createServer(async (req, res) => {
     if (!app) return json(res, 404, { error: 'unknown app' })
     return json(res, 200, { configs: (app.configs || []).map((c) => readConfig(app, c)) })
   }
-  // ?version=<semver> on every action — the topbar selection, substituted into {VERSION}.
-  const reqVersion = (() => {
-    try { return new URL(req.url, 'http://x').searchParams.get('version') || '' } catch { return '' }
-  })()
   const path = (req.url || '').split('?')[0]
   const m = path.match(/^\/api\/apps\/([^/]+)\/(build|start|stop|deploy)$/)
   if (m && req.method === 'POST') {
@@ -636,42 +600,12 @@ const server = http.createServer(async (req, res) => {
     if (m[2] !== 'stop' && developedOnce(app) === false) {
       return json(res, 409, { error: 'application has not completed a develop workflow run' })
     }
-    if (m[2] === 'build') buildApp(app, reqVersion)
-    else if (m[2] === 'start') startApp(app, reqVersion)
-    else if (m[2] === 'deploy') deployApp(app, reqVersion)
-    else stopApp(app, reqVersion)
+    if (m[2] === 'build') buildApp(app)
+    else if (m[2] === 'start') startApp(app)
+    else if (m[2] === 'deploy') deployApp(app)
+    else stopApp(app)
     return json(res, 200, { ok: true })
   }
-  // All-apps controls. Eligible = develop gate not failed and not mid-build/deploy; build and
-  // start additionally skip apps already running. Builds run SEQUENTIALLY (honest logs, no
-  // CPU storm); start/stop fire together. Ineligible apps are skipped silently.
-  const all = path.match(/^\/api\/all\/(build|start|stop)$/)
-  if (all && req.method === 'POST') {
-    const op = all[1]
-    const apps = loadConfig().apps
-    if (op === 'stop') {
-      for (const a of apps) {
-        if (running.has(a.name)) stopApp(a, reqVersion)
-        else probe(a).then((up) => { if (up) stopApp(a, reqVersion) })
-      }
-      return json(res, 200, { ok: true })
-    }
-    const eligible = []
-    for (const a of apps) {
-      if (developedOnce(a) === false || activity.has(a.name)) continue
-      if (await probe(a)) continue // already running — skip for build AND start
-      eligible.push(a)
-    }
-    if (op === 'start') {
-      for (const a of eligible) startApp(a, reqVersion)
-      return json(res, 200, { ok: true, count: eligible.length })
-    }
-    // op === 'build' — sequential chain: each build starts when the previous one exits.
-    const queue = [...eligible]
-    const next = () => { const a = queue.shift(); if (a) buildApp(a, reqVersion, next) }
-    next()
-    return json(res, 200, { ok: true, count: eligible.length })
-  }
   json(res, 404, { error: 'not found' })
 })
@@ -718,9 +652,8 @@ Docker fields (from the plan's `## Docker` / `## Dockerfiles` sections): top-lev
 `"dockerfile"` is `{ "path": "Dockerfile", "content": "<managed body>" }` for a `managed`
 Dockerfile (materialized before Build when missing — never overwriting), or
 `{ "path": "Dockerfile", "content": null }` for an `existing` one (`null` entirely when the
-app has no image). Commands may carry the literal `{VERSION}` token — copied verbatim; the
-server substitutes the topbar-selected version (semver sans `v`, fallback `latest`) at
-execution time.
+app has no image). Commands are copied verbatim from the plan and run as-is — no `{VERSION}`
+or any other token substitution.
 Each app also carries a `configs` array — the runtime config files the application reads at start,
 from the plan's `## Application Configs` section (one entry per file). Fields:
@@ -743,7 +676,7 @@ verbatim (this is a local dev CI/CD app).
       "folder": "my-app",
       "method": "process",
       "port": 3000,
-      "build": "pnpm install && pnpm build && docker build -t registry.example.com/team/my-app:{VERSION} .",
+      "build": "pnpm install && pnpm build && docker build -t registry.example.com/team/my-app:latest .",
       "start": "node dist/index.js",
       "stop": "process-kill",
       "deployMethod": "kubernetes",

package/plugin/skills/util-plancicd/SKILL.md CHANGED Viewed

@@ -1,310 +1,305 @@
----
-name: util-plancicd
-model: claude-opus-4-8
-effort: high
-description: >
-  Infer a local-deployment plan for every custom application of a CO2 project and write it to
-  cicd/CICD_PLAN.md for human review in Compound Context Studio. Reads the project's
-  ENVIRONMENT.md and DEVTOOL.md, CLAUDE.md (# Custom Applications, # Port Allocation) and each
-  application's context/specification/SPECIFICATION.md, then decides per application: deployment
-  method (container vs bare process), build command (e.g. Spring Boot jar vs Docker image),
-  start command, stop mechanism, deploy method + command (none / web-server copy / docker run /
-  kubectl apply — only when the environment calls for one), port and health-check URL, plus a
-  port for the generated CI/CD app itself. When Docker AND a docker repo/registry are both
-  configured (DEVTOOL.md + ENVIRONMENT.md), it additionally plans the docker-image build path:
-  per-application image names under the repo, Build commands extended with
-  `docker build -t <image>:{VERSION}` (the {VERSION} token is resolved by the generated CI/CD
-  app from its topbar version selector), and a managed Dockerfile authored into the plan's
-  `## Dockerfiles` section for any dockerized application lacking one (materialized before
-  Build, never overwriting an existing file). It also infers each application's RUNTIME CONFIG — the
-  config files its start command reads (e.g. `.env`), deciding per file whether the values come
-  from ENVIRONMENT.md or from an existing `.env` / `.env-*` file already in the app folder, listing
-  the required keys and, for ENVIRONMENT.md-sourced files, the resolved content — so the generated
-  CI/CD app can complete the config before start (guaranteeing the app comes up) and show it in a
-  per-application Config modal for troubleshooting. It also enumerates the project's supporting
-  infrastructure (3rd-party services from CLAUDE.md's `# Supporting 3rd Party Applications` and
-  ENVIRONMENT.md — host, port and optional console URL) into an `## Infrastructure` section so
-  the generated CI/CD app can surface a status-only Infrastructure page. The plan carries a
-  top-level
-  `**Status**: IN PROGRESS` header flipped to `COMPLETED` when done — the studio's watcher reads
-  it. This skill NEVER generates the CI/CD app (that is util-gencicdscript, which runs only
-  after the studio stamps an **Approved**: line into the plan). Trigger on keywords: "plan
-  cicd", "plan deployment", "cicd plan", "infer deployment", "deployment plan", "plan ci/cd".
-  Accepts one MANDATORY argument: the project-relative path of the plan-request markdown the
-  studio generated (e.g., /util-plancicd execution/cicd-plan-3-1753000000000.md).
----
-# Util Plan CI/CD
-## Inputs
-```
-/util-plancicd <path-to-plan-request-md>
-```
-| Argument | Required | Description |
-|---|---|---|
-| path | yes | Project-relative path of the studio-generated plan-request markdown under `execution/` |
-If the argument is missing or the file does not exist, STOP and tell the user to click
-**Plan deployment** in the studio's CI/CD screen first.
-### Auto-Resolved Paths
-| Logical file | Path |
-|---|---|
-| Plan request | `<argument>` |
-| Environment | `ENVIRONMENT.md` (project root) |
-| Dev tools | `DEVTOOL.md` (project root) |
-| Project context | `CLAUDE.md` (project root; `source/CLAUDE.md` fallback) |
-| App specification | `<app_folder>/context/specification/SPECIFICATION.md` |
-| App config files | `<app_folder>/.env`, `<app_folder>/.env-*` (and stack-conventional config files) |
-| Infrastructure | `CLAUDE.md` `# Supporting 3rd Party Applications` + `ENVIRONMENT.md` |
-| Output plan | `cicd/CICD_PLAN.md` |
-## Phase 1 — Gather
-1. Read the plan-request markdown; its `## Applications` list is the authoritative application set.
-2. Read `ENVIRONMENT.md` (registries, credentials, external services) and `DEVTOOL.md`
-   (installed tools + paths: node/pnpm/docker/kubectl/python versions).
-2a. **Docker facts**: record whether Docker is installed (DEVTOOL.md) AND whether
-   ENVIRONMENT.md names a **docker repo/registry** — a registry URL or namespace the images
-   are tagged for (e.g. `registry.example.com/team`, a Docker Hub org, an ECR/GCR path).
-   The docker-image build path (below) activates ONLY when BOTH are present; Docker without
-   a configured repo keeps today's behavior (no image builds).
-3. Read `CLAUDE.md`: `# Custom Applications` (folder names, Depends on), `# Port Allocation`
-   (per-application ports), and `# Supporting 3rd Party Applications` (the infrastructure the
-   applications depend on — databases, caches, object storage, SSO, mail, message brokers, etc.).
-4. For each application, read its SPECIFICATION.md tech-stack section if present; otherwise
-   infer the stack from build files (`package.json` → node, `pom.xml` → spring-boot,
-   `composer.json` → laravel).
-4a. For each application, discover its RUNTIME CONFIG files: list any existing `.env` / `.env-*`
-   in the application folder AND the stack-conventional config the start command reads (node/
-   laravel → `.env`; Spring Boot → `application.properties` / `application-<profile>.yml` or a
-   `.env` when the app loads one). Read the content of each existing file (values may be reused).
-   Cross-reference ENVIRONMENT.md for the per-application config values (DB/cache/broker hosts and
-   ports, external-service URLs, credentials, secrets, the app's own PORT) and the Infrastructure
-   list from step 5 for the hosts/ports the app must point at.
-5. Build the **infrastructure list**: one entry per supporting 3rd-party service the project
-   declares. For each, resolve `host` (default `127.0.0.1`), `port` and — when it exposes a web
-   console/UI — a `url`, cross-referencing ENVIRONMENT.md for the actual host/port/endpoint. A
-   service with no host:port to probe (or a purely external SaaS with no local endpoint) is
-   omitted. If the project declares no supporting 3rd-party services, the infrastructure list is
-   empty and the plan's `## Infrastructure` section is written empty.
-## Phase 2 — Decide (per application)
-- **Working directory (CRITICAL)**: the generated CI/CD app executes every command with the
-  **application folder** (`<project>/<folder>`) as its working directory — NEVER the project
-  root. All paths inside build/start/stop/deploy commands must therefore be relative to the
-  application folder (`mvn -q package`, `java -jar target\app.jar`) — never prefixed with the
-  application folder itself (`skolafund_middleware\target\...` is WRONG).
-- **Method**: `container` only when Docker appears in DEVTOOL.md AND the stack has a sensible
-  container path; otherwise `process` (bare local process — the default for a dev VM).
-- **Build command**: from the stack (e.g. `pnpm install && pnpm build`, `mvn -q package`,
-  `composer install`). Use tool paths from DEVTOOL.md when the tool is not on PATH.
-- **Start command**: the stack's production-ish local start (e.g. `node dist/index.js`,
-  `java -jar target/<artifact>.jar`, `php artisan serve --port <port>`); `docker build`/
-  `docker run` pair when method=container. For jar-based stacks, resolve the EXACT artifact
-  filename — read the pom/gradle build config: a Maven `<finalName>` means
-  `target/<finalName>.jar` with NO version suffix (Spring Boot repackage keeps that name and
-  leaves a `.jar.original` beside it — never reference the `.original`). Never guess
-  `<app>-<version>.jar` and never use a `target/*.jar` glob (shell-dependent, breaks on
-  Windows cmd).
-- **Stop**: `process-kill` for bare processes; `docker stop <name>` for containers.
-- **Deploy** (method + command): only when ENVIRONMENT.md/DEVTOOL.md show a deployment target —
-  `kubernetes` (`kubectl apply -f <app>/k8s/` when kubectl + a cluster/kubeconfig appear),
-  `docker` (`docker run`/`docker compose up -d` when the image is the deliverable),
-  `web-server` (copy the built artifact into the configured web/app server, e.g. nginx html
-  root or Tomcat webapps, when one is configured). Default **`none`** — a bare local process
-  needs no deploy step beyond Start; never invent a target the config does not name.
-- **Docker image** (only when Gather 2a found Docker + a docker repo — otherwise skip this
-  bullet entirely):
-  - **Image name**: `<repo>/<app_folder>` — the application folder name, lowercased, with
-    any character docker rejects replaced by `-` (keep a leading `<number>_` prefix as-is;
-    e.g. `registry.example.com/team/skolafund_web`).
-  - **Build**: append the image build to the app build —
-    `<app build> && docker build -t <image>:{VERSION} .` The literal `{VERSION}` token is
-    the contract: the generated CI/CD app substitutes the version selected in its topbar
-    (semver without the `v` prefix; `latest` fallback) into commands at execution time.
-    Build never pushes — pushing belongs to a `docker` Deploy method.
-  - **Container start/deploy**: when method=container, reference `<image>:{VERSION}` in the
-    start/deploy commands too, so the selected tag is what runs.
-  - **Dockerfile**: if the application folder already has a `Dockerfile`, use it as-is
-    (`existing`). Otherwise author a stack-appropriate Dockerfile (node / spring-boot /
-    laravel — same stack detection as depgen-k8s) into the plan's `## Dockerfiles` section
-    (`managed`); the generated CI/CD app materializes it before Build only when the file is
-    still missing on disk.
-- **Port**: from `# Port Allocation`; if absent, assign sequentially from 3000 avoiding
-  collisions with the studio (3001) and the CI/CD app port.
-- **Health / running-detection**: the endpoint the generated CI/CD app uses to tell whether the
-  application is already running. Detection is a **raw TCP connect to the app's port on loopback**
-  — the generated app probes BOTH IPv4 (`127.0.0.1`) and IPv6 (`::1`) loopback, plus the host
-  named in this Health value — so it does not matter which family the framework binds. This
-  matters because dev servers differ: Spring Boot binds `127.0.0.1`, but **Vite / Next preview
-  servers bind IPv6 `::1` (localhost) only** and are invisible to an IPv4-only probe. Therefore
-  set the Health host to **`localhost`** (not `127.0.0.1`) for any Node/Vite/Next dev-server app
-  so the detection host set includes the interface it actually binds; use `127.0.0.1` for JVM
-  apps. Value form: `http://localhost:<port>/` or a documented health path from the spec (the
-  path is informational — detection keys on the port, not the path).
-- **CI/CD app port**: 5000 unless taken in `# Port Allocation`; record it in the plan.
-### Application config (per application)
-Decide the runtime config the application needs so it STARTS SUCCESSFULLY, and where each value
-comes from. For every config file the start command reads (`path`, relative to the application
-folder):
-- **source** — classify each file:
-  - `env-file` — an existing `.env` / `.env-*` in the app folder already holds the runtime values;
-    use it as-is on disk (do NOT re-materialize it). Set `managed: no`, no resolved content.
-  - `environment` — there is no complete runtime file; resolve the required values from
-    ENVIRONMENT.md (and the Infrastructure hosts/ports) and record the fully-resolved file content.
-    Set `managed: yes` so the CI/CD app writes it before Build/Start when missing.
-  - `derived` — the runtime file is chosen/combined from existing material (e.g. copy the target
-    env's `.env-<env>` to the canonical `.env` the start command reads, or merge an existing
-    `.env-*` with ENVIRONMENT.md values). Set `managed: yes` and record the resolved content.
-- **required keys** — enumerate every key the app must have to boot: its own PORT, datastore/cache/
-  broker connection strings, external-service URLs, credentials/secrets. Cross-check them against
-  ENVIRONMENT.md and the Infrastructure list.
-- **completeness (the point of this)** — every required key MUST be satisfiable from ENVIRONMENT.md
-  or an existing env file. If a required key cannot be resolved, still emit the config entry but
-  call out the unresolved key in that application's Rationale as a GAP (so the human fixes
-  ENVIRONMENT.md before approving) — never silently drop it.
-- **managed content** — for a `managed: yes` file, write the resolved body verbatim into the plan
-  as a fenced block (`path=<file>`). Values (including credentials) are emitted verbatim under the
-  dev-environment plaintext rule; they must never appear in the Rationale narrative.
-Only list files the app actually reads at runtime — do not invent config files. An app that needs
-no config file gets an empty config list.
-### Infrastructure (status-only)
-Supporting 3rd-party services are **not** built/started/deployed by the CI/CD app — they are
-surfaced status-only. For each service resolved in Gather step 5, decide:
-- **id**: a stable kebab-case key unique within the plan (e.g. `postgres-main`, `keycloak`).
-- **name**: display name (e.g. `PostgreSQL (skf_main)`, `Keycloak`).
-- **host** / **port**: the address the CI/CD app TCP-probes for reachability; default host
-  `127.0.0.1`. Use the values ENVIRONMENT.md documents.
-- **url**: the web console/UI opened in a new tab, when the service has one (Keycloak admin,
-  MinIO console, Mailcatcher inbox); `-` for headless services (PostgreSQL, Redis).
-- **description**: a short blurb (e.g. `Shared app database`, `S3-compatible object storage`).
-Never emit credentials into the infrastructure entries — status and links only.
-## Phase 3 — Write the plan
-Create `cicd/` if missing and write `cicd/CICD_PLAN.md` (shown here in a 4-backtick fence so the
-inner ```env config block renders — the plan file itself uses a normal 3-backtick env fence):
-````markdown
-# CI/CD Deployment Plan — <Project Name>
-**Generated**: <ISO date>
-**Status**: IN PROGRESS
-## CI/CD App
-- **Port**: <port>
-- **Folder**: cicd/app
-## Deployment Decisions
-| Application | Folder | Method | Port | Build | Start | Stop | Deploy Method | Deploy | Health |
-|---|---|---|---|---|---|---|---|---|---|
-| <name> | <folder> | process|container | <port> | `<cmd>` | `<cmd>` | process-kill|docker stop | none|web-server|docker|kubernetes | `<cmd or ->` | <url> |
-> **Running-detection**: the generated CI/CD app determines "is it running?" by a TCP connect to
-> each application's **Port** on both IPv4 (`127.0.0.1`) and IPv6 (`::1`) loopback plus the
-> **Health** host — so an app is detected whichever family it binds. Use a `localhost` Health host
-> for Node/Vite/Next apps (they bind IPv6 `::1`) and `127.0.0.1` for JVM apps.
-> **`{VERSION}` token**: Build/Start/Deploy commands may contain the literal `{VERSION}`;
-> the generated CI/CD app replaces it with the version selected in its topbar (semver
-> without the `v` prefix, `latest` when unknown) at execution time. Used by the docker-image
-> path to tag images; tag-only — the code built is always the working tree.
-## Docker
-Written only from Gather 2a. When Docker or a docker repo is absent, write the section as:
-`_Not dockerized — Docker and/or a docker repo are not configured in DEVTOOL.md/ENVIRONMENT.md._`
-**Registry**: <repo, e.g. `registry.example.com/team`>
-| Application | Image | Dockerfile |
-|---|---|---|
-| <name> | `<repo>/<app_folder>` | existing \| managed |
-## Dockerfiles
-One fenced block per `managed` Dockerfile (omit the section body — `_All Dockerfiles exist._`
-— when every dockerized app already has one; `_Not dockerized._` when the Docker section is
-inactive). The generated CI/CD app writes each body to `<app_folder>/Dockerfile` before Build
-only when the file is missing on disk — an existing Dockerfile is never overwritten.
-```dockerfile path=<app_folder>/Dockerfile
-FROM node:22-slim
-WORKDIR /app
-COPY package*.json ./
-RUN npm ci --omit=dev
-COPY . .
-EXPOSE <port>
-CMD ["node", "dist/index.js"]
-```
-## Application Configs
-The runtime config each application needs to START SUCCESSFULLY. The generated CI/CD app writes any
-`managed=yes` file into the application folder before Build/Start when it is missing, and shows
-every file (source, status, required keys, live content) in the per-application Config modal for
-troubleshooting. One table per application; `Path` is relative to the application folder.
-### <App Name> (<folder>)
-| Path | Source | Managed | Required Keys |
-|---|---|---|---|
-| .env | environment | yes | DATABASE_URL, REDIS_HOST, PORT |
-| .env-uat | env-file | no | DATABASE_URL, REDIS_HOST |
-For each `Managed=yes` row, follow it with the resolved file body (verbatim — credentials allowed
-under the dev-plaintext rule):
-```env path=.env
-DATABASE_URL=postgres://app:app@127.0.0.1:5432/appdb
-REDIS_HOST=127.0.0.1
-PORT=3000
-```
-Omit the fenced block for `env-file` rows (the file is used as-is on disk). If an application needs
-no config file, write `_No runtime config files._` under its heading.
-## Infrastructure
-Supporting 3rd-party services shown status-only (TCP reachability) on the CI/CD app's
-Infrastructure page. Leave the table body empty when the project declares no supporting services.
-| Id | Service | Host | Port | Console URL | Description |
-|---|---|---|---|---|---|
-| <id> | <name> | <host> | <port> | `<url or ->` | <blurb> |
-## Rationale
-- <per-application: why this method/commands, citing ENVIRONMENT.md/DEVTOOL.md evidence>
-````
-Then flip `**Status**: IN PROGRESS` to `**Status**: COMPLETED`. The studio watcher advances
-only on COMPLETED.
-## STOP — Hand Back to the Human
-Print a one-paragraph summary and STOP. Never invoke util-gencicdscript or any other skill —
-the human reviews and approves the plan in the studio's CI/CD screen first.
-## Important Rules
-- Never write the CI/CD app; never modify PRD.md/CLAUDE.md/BUG.md.
-- Never delete an existing `**Approved**:` line if re-planning over a previous plan — overwrite
-  the whole file WITHOUT any Approved line (a re-plan always requires fresh approval).
-- Credentials from ENVIRONMENT.md may be referenced in commands verbatim (dev-environment
-  plaintext rule) but never echoed into the Rationale narrative.
+---
+name: util-plancicd
+model: claude-opus-4-8
+effort: high
+description: >
+  Infer a local-deployment plan for every custom application of a CO2 project and write it to
+  cicd/CICD_PLAN.md for human review in Compound Context Studio. Reads the project's
+  ENVIRONMENT.md and DEVTOOL.md, CLAUDE.md (# Custom Applications, # Port Allocation) and each
+  application's context/specification/SPECIFICATION.md, then decides per application: deployment
+  method (container vs bare process), build command (e.g. Spring Boot jar vs Docker image),
+  start command, stop mechanism, deploy method + command (none / web-server copy / docker run /
+  kubectl apply — only when the environment calls for one), port and health-check URL, plus a
+  port for the generated CI/CD app itself. When Docker AND a docker repo/registry are both
+  configured (DEVTOOL.md + ENVIRONMENT.md), it additionally plans the docker-image build path:
+  per-application image names under the repo, Build commands extended with
+  `docker build -t <image>:latest` (no version token — the generated CI/CD app runs commands
+  verbatim on the current working tree), and a managed Dockerfile authored into the plan's
+  `## Dockerfiles` section for any dockerized application lacking one (materialized before
+  Build, never overwriting an existing file). It also infers each application's RUNTIME CONFIG — the
+  config files its start command reads (e.g. `.env`), deciding per file whether the values come
+  from ENVIRONMENT.md or from an existing `.env` / `.env-*` file already in the app folder, listing
+  the required keys and, for ENVIRONMENT.md-sourced files, the resolved content — so the generated
+  CI/CD app can complete the config before start (guaranteeing the app comes up) and show it in a
+  per-application Config modal for troubleshooting. It also enumerates the project's supporting
+  infrastructure (3rd-party services from CLAUDE.md's `# Supporting 3rd Party Applications` and
+  ENVIRONMENT.md — host, port and optional console URL) into an `## Infrastructure` section so
+  the generated CI/CD app can surface a status-only Infrastructure page. The plan carries a
+  top-level
+  `**Status**: IN PROGRESS` header flipped to `COMPLETED` when done — the studio's watcher reads
+  it. This skill NEVER generates the CI/CD app (that is util-gencicdscript, which runs only
+  after the studio stamps an **Approved**: line into the plan). Trigger on keywords: "plan
+  cicd", "plan deployment", "cicd plan", "infer deployment", "deployment plan", "plan ci/cd".
+  Accepts one MANDATORY argument: the project-relative path of the plan-request markdown the
+  studio generated (e.g., /util-plancicd execution/cicd-plan-3-1753000000000.md).
+---
+# Util Plan CI/CD
+## Inputs
+```
+/util-plancicd <path-to-plan-request-md>
+```
+| Argument | Required | Description |
+|---|---|---|
+| path | yes | Project-relative path of the studio-generated plan-request markdown under `execution/` |
+If the argument is missing or the file does not exist, STOP and tell the user to click
+**Plan deployment** in the studio's CI/CD screen first.
+### Auto-Resolved Paths
+| Logical file | Path |
+|---|---|
+| Plan request | `<argument>` |
+| Environment | `ENVIRONMENT.md` (project root) |
+| Dev tools | `DEVTOOL.md` (project root) |
+| Project context | `CLAUDE.md` (project root; `source/CLAUDE.md` fallback) |
+| App specification | `<app_folder>/context/specification/SPECIFICATION.md` |
+| App config files | `<app_folder>/.env`, `<app_folder>/.env-*` (and stack-conventional config files) |
+| Infrastructure | `CLAUDE.md` `# Supporting 3rd Party Applications` + `ENVIRONMENT.md` |
+| Output plan | `cicd/CICD_PLAN.md` |
+## Phase 1 — Gather
+1. Read the plan-request markdown; its `## Applications` list is the authoritative application set.
+2. Read `ENVIRONMENT.md` (registries, credentials, external services) and `DEVTOOL.md`
+   (installed tools + paths: node/pnpm/docker/kubectl/python versions).
+2a. **Docker facts**: record whether Docker is installed (DEVTOOL.md) AND whether
+   ENVIRONMENT.md names a **docker repo/registry** — a registry URL or namespace the images
+   are tagged for (e.g. `registry.example.com/team`, a Docker Hub org, an ECR/GCR path).
+   The docker-image build path (below) activates ONLY when BOTH are present; Docker without
+   a configured repo keeps today's behavior (no image builds).
+3. Read `CLAUDE.md`: `# Custom Applications` (folder names, Depends on), `# Port Allocation`
+   (per-application ports), and `# Supporting 3rd Party Applications` (the infrastructure the
+   applications depend on — databases, caches, object storage, SSO, mail, message brokers, etc.).
+4. For each application, read its SPECIFICATION.md tech-stack section if present; otherwise
+   infer the stack from build files (`package.json` → node, `pom.xml` → spring-boot,
+   `composer.json` → laravel).
+4a. For each application, discover its RUNTIME CONFIG files: list any existing `.env` / `.env-*`
+   in the application folder AND the stack-conventional config the start command reads (node/
+   laravel → `.env`; Spring Boot → `application.properties` / `application-<profile>.yml` or a
+   `.env` when the app loads one). Read the content of each existing file (values may be reused).
+   Cross-reference ENVIRONMENT.md for the per-application config values (DB/cache/broker hosts and
+   ports, external-service URLs, credentials, secrets, the app's own PORT) and the Infrastructure
+   list from step 5 for the hosts/ports the app must point at.
+5. Build the **infrastructure list**: one entry per supporting 3rd-party service the project
+   declares. For each, resolve `host` (default `127.0.0.1`), `port` and — when it exposes a web
+   console/UI — a `url`, cross-referencing ENVIRONMENT.md for the actual host/port/endpoint. A
+   service with no host:port to probe (or a purely external SaaS with no local endpoint) is
+   omitted. If the project declares no supporting 3rd-party services, the infrastructure list is
+   empty and the plan's `## Infrastructure` section is written empty.
+## Phase 2 — Decide (per application)
+- **Working directory (CRITICAL)**: the generated CI/CD app executes every command with the
+  **application folder** (`<project>/<folder>`) as its working directory — NEVER the project
+  root. All paths inside build/start/stop/deploy commands must therefore be relative to the
+  application folder (`mvn -q package`, `java -jar target\app.jar`) — never prefixed with the
+  application folder itself (`skolafund_middleware\target\...` is WRONG).
+- **Method**: `container` only when Docker appears in DEVTOOL.md AND the stack has a sensible
+  container path; otherwise `process` (bare local process — the default for a dev VM).
+- **Build command**: from the stack (e.g. `pnpm install && pnpm build`, `mvn -q package`,
+  `composer install`). Use tool paths from DEVTOOL.md when the tool is not on PATH.
+- **Start command**: the stack's production-ish local start (e.g. `node dist/index.js`,
+  `java -jar target/<artifact>.jar`, `php artisan serve --port <port>`); `docker build`/
+  `docker run` pair when method=container. For jar-based stacks, resolve the EXACT artifact
+  filename — read the pom/gradle build config: a Maven `<finalName>` means
+  `target/<finalName>.jar` with NO version suffix (Spring Boot repackage keeps that name and
+  leaves a `.jar.original` beside it — never reference the `.original`). Never guess
+  `<app>-<version>.jar` and never use a `target/*.jar` glob (shell-dependent, breaks on
+  Windows cmd).
+- **Stop**: `process-kill` for bare processes; `docker stop <name>` for containers.
+- **Deploy** (method + command): only when ENVIRONMENT.md/DEVTOOL.md show a deployment target —
+  `kubernetes` (`kubectl apply -f <app>/k8s/` when kubectl + a cluster/kubeconfig appear),
+  `docker` (`docker run`/`docker compose up -d` when the image is the deliverable),
+  `web-server` (copy the built artifact into the configured web/app server, e.g. nginx html
+  root or Tomcat webapps, when one is configured). Default **`none`** — a bare local process
+  needs no deploy step beyond Start; never invent a target the config does not name.
+- **Docker image** (only when Gather 2a found Docker + a docker repo — otherwise skip this
+  bullet entirely):
+  - **Image name**: `<repo>/<app_folder>` — the application folder name, lowercased, with
+    any character docker rejects replaced by `-` (keep a leading `<number>_` prefix as-is;
+    e.g. `registry.example.com/team/skolafund_web`).
+  - **Build**: append the image build to the app build —
+    `<app build> && docker build -t <image>:latest .` Commands carry NO `{VERSION}` token or
+    any other placeholder — the generated CI/CD app runs them verbatim; only the current
+    working tree is ever built and images are always tagged `latest`.
+    Build never pushes — pushing belongs to a `docker` Deploy method.
+  - **Container start/deploy**: when method=container, reference `<image>:latest` in the
+    start/deploy commands too, so the freshly built tag is what runs.
+  - **Dockerfile**: if the application folder already has a `Dockerfile`, use it as-is
+    (`existing`). Otherwise author a stack-appropriate Dockerfile (node / spring-boot /
+    laravel — same stack detection as depgen-k8s) into the plan's `## Dockerfiles` section
+    (`managed`); the generated CI/CD app materializes it before Build only when the file is
+    still missing on disk.
+- **Port**: from `# Port Allocation`; if absent, assign sequentially from 3000 avoiding
+  collisions with the studio (3001) and the CI/CD app port.
+- **Health / running-detection**: the endpoint the generated CI/CD app uses to tell whether the
+  application is already running. Detection is a **raw TCP connect to the app's port on loopback**
+  — the generated app probes BOTH IPv4 (`127.0.0.1`) and IPv6 (`::1`) loopback, plus the host
+  named in this Health value — so it does not matter which family the framework binds. This
+  matters because dev servers differ: Spring Boot binds `127.0.0.1`, but **Vite / Next preview
+  servers bind IPv6 `::1` (localhost) only** and are invisible to an IPv4-only probe. Therefore
+  set the Health host to **`localhost`** (not `127.0.0.1`) for any Node/Vite/Next dev-server app
+  so the detection host set includes the interface it actually binds; use `127.0.0.1` for JVM
+  apps. Value form: `http://localhost:<port>/` or a documented health path from the spec (the
+  path is informational — detection keys on the port, not the path).
+- **CI/CD app port**: 5000 unless taken in `# Port Allocation`; record it in the plan.
+### Application config (per application)
+Decide the runtime config the application needs so it STARTS SUCCESSFULLY, and where each value
+comes from. For every config file the start command reads (`path`, relative to the application
+folder):
+- **source** — classify each file:
+  - `env-file` — an existing `.env` / `.env-*` in the app folder already holds the runtime values;
+    use it as-is on disk (do NOT re-materialize it). Set `managed: no`, no resolved content.
+  - `environment` — there is no complete runtime file; resolve the required values from
+    ENVIRONMENT.md (and the Infrastructure hosts/ports) and record the fully-resolved file content.
+    Set `managed: yes` so the CI/CD app writes it before Build/Start when missing.
+  - `derived` — the runtime file is chosen/combined from existing material (e.g. copy the target
+    env's `.env-<env>` to the canonical `.env` the start command reads, or merge an existing
+    `.env-*` with ENVIRONMENT.md values). Set `managed: yes` and record the resolved content.
+- **required keys** — enumerate every key the app must have to boot: its own PORT, datastore/cache/
+  broker connection strings, external-service URLs, credentials/secrets. Cross-check them against
+  ENVIRONMENT.md and the Infrastructure list.
+- **completeness (the point of this)** — every required key MUST be satisfiable from ENVIRONMENT.md
+  or an existing env file. If a required key cannot be resolved, still emit the config entry but
+  call out the unresolved key in that application's Rationale as a GAP (so the human fixes
+  ENVIRONMENT.md before approving) — never silently drop it.
+- **managed content** — for a `managed: yes` file, write the resolved body verbatim into the plan
+  as a fenced block (`path=<file>`). Values (including credentials) are emitted verbatim under the
+  dev-environment plaintext rule; they must never appear in the Rationale narrative.
+Only list files the app actually reads at runtime — do not invent config files. An app that needs
+no config file gets an empty config list.
+### Infrastructure (status-only)
+Supporting 3rd-party services are **not** built/started/deployed by the CI/CD app — they are
+surfaced status-only. For each service resolved in Gather step 5, decide:
+- **id**: a stable kebab-case key unique within the plan (e.g. `postgres-main`, `keycloak`).
+- **name**: display name (e.g. `PostgreSQL (skf_main)`, `Keycloak`).
+- **host** / **port**: the address the CI/CD app TCP-probes for reachability; default host
+  `127.0.0.1`. Use the values ENVIRONMENT.md documents.
+- **url**: the web console/UI opened in a new tab, when the service has one (Keycloak admin,
+  MinIO console, Mailcatcher inbox); `-` for headless services (PostgreSQL, Redis).
+- **description**: a short blurb (e.g. `Shared app database`, `S3-compatible object storage`).
+Never emit credentials into the infrastructure entries — status and links only.
+## Phase 3 — Write the plan
+Create `cicd/` if missing and write `cicd/CICD_PLAN.md` (shown here in a 4-backtick fence so the
+inner ```env config block renders — the plan file itself uses a normal 3-backtick env fence):
+````markdown
+# CI/CD Deployment Plan — <Project Name>
+**Generated**: <ISO date>
+**Status**: IN PROGRESS
+## CI/CD App
+- **Port**: <port>
+- **Folder**: cicd/app
+## Deployment Decisions
+| Application | Folder | Method | Port | Build | Start | Stop | Deploy Method | Deploy | Health |
+|---|---|---|---|---|---|---|---|---|---|
+| <name> | <folder> | process|container | <port> | `<cmd>` | `<cmd>` | process-kill|docker stop | none|web-server|docker|kubernetes | `<cmd or ->` | <url> |
+> **Running-detection**: the generated CI/CD app determines "is it running?" by a TCP connect to
+> each application's **Port** on both IPv4 (`127.0.0.1`) and IPv6 (`::1`) loopback plus the
+> **Health** host — so an app is detected whichever family it binds. Use a `localhost` Health host
+> for Node/Vite/Next apps (they bind IPv6 `::1`) and `127.0.0.1` for JVM apps.
+## Docker
+Written only from Gather 2a. When Docker or a docker repo is absent, write the section as:
+`_Not dockerized — Docker and/or a docker repo are not configured in DEVTOOL.md/ENVIRONMENT.md._`
+**Registry**: <repo, e.g. `registry.example.com/team`>
+| Application | Image | Dockerfile |
+|---|---|---|
+| <name> | `<repo>/<app_folder>` | existing \| managed |
+## Dockerfiles
+One fenced block per `managed` Dockerfile (omit the section body — `_All Dockerfiles exist._`
+— when every dockerized app already has one; `_Not dockerized._` when the Docker section is
+inactive). The generated CI/CD app writes each body to `<app_folder>/Dockerfile` before Build
+only when the file is missing on disk — an existing Dockerfile is never overwritten.
+```dockerfile path=<app_folder>/Dockerfile
+FROM node:22-slim
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci --omit=dev
+COPY . .
+EXPOSE <port>
+CMD ["node", "dist/index.js"]
+```
+## Application Configs
+The runtime config each application needs to START SUCCESSFULLY. The generated CI/CD app writes any
+`managed=yes` file into the application folder before Build/Start when it is missing, and shows
+every file (source, status, required keys, live content) in the per-application Config modal for
+troubleshooting. One table per application; `Path` is relative to the application folder.
+### <App Name> (<folder>)
+| Path | Source | Managed | Required Keys |
+|---|---|---|---|
+| .env | environment | yes | DATABASE_URL, REDIS_HOST, PORT |
+| .env-uat | env-file | no | DATABASE_URL, REDIS_HOST |
+For each `Managed=yes` row, follow it with the resolved file body (verbatim — credentials allowed
+under the dev-plaintext rule):
+```env path=.env
+DATABASE_URL=postgres://app:app@127.0.0.1:5432/appdb
+REDIS_HOST=127.0.0.1
+PORT=3000
+```
+Omit the fenced block for `env-file` rows (the file is used as-is on disk). If an application needs
+no config file, write `_No runtime config files._` under its heading.
+## Infrastructure
+Supporting 3rd-party services shown status-only (TCP reachability) on the CI/CD app's
+Infrastructure page. Leave the table body empty when the project declares no supporting services.
+| Id | Service | Host | Port | Console URL | Description |
+|---|---|---|---|---|---|
+| <id> | <name> | <host> | <port> | `<url or ->` | <blurb> |
+## Rationale
+- <per-application: why this method/commands, citing ENVIRONMENT.md/DEVTOOL.md evidence>
+````
+Then flip `**Status**: IN PROGRESS` to `**Status**: COMPLETED`. The studio watcher advances
+only on COMPLETED.
+## STOP — Hand Back to the Human
+Print a one-paragraph summary and STOP. Never invoke util-gencicdscript or any other skill —
+the human reviews and approves the plan in the studio's CI/CD screen first.
+## Important Rules
+- Never write the CI/CD app; never modify PRD.md/CLAUDE.md/BUG.md.
+- Never delete an existing `**Approved**:` line if re-planning over a previous plan — overwrite
+  the whole file WITHOUT any Approved line (a re-plan always requires fresh approval).
+- Credentials from ENVIRONMENT.md may be referenced in commands verbatim (dev-environment
+  plaintext rule) but never echoed into the Rationale narrative.