@lifeaitools/rdc-skills 0.9.37 → 0.10.0

package/scripts/validate-publish-manifests.js

@@ -0,0 +1,424 @@
+#!/usr/bin/env node
+/**
+ * validate-publish-manifests.js
+ * WP-6: PUBLISH.md convention validator for rdc-skills
+ *
+ * Queries app_deployments (active rows), checks PUBLISH.md presence + schema
+ * for each registered deployable target.
+ *
+ * Usage:
+ *   node scripts/validate-publish-manifests.js [--mode warn|fail] [--slug <name>] [--json] [--strict]
+ *
+ * Exit codes:
+ *   0 — all checks passed (or warn mode with only warnings)
+ *   1 — one or more FAIL lines (hard error)
+ *   2 — invocation error (bad args)
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const https = require('https');
+const http = require('http');
+
+// ---------------------------------------------------------------------------
+// CLI argument parsing
+// ---------------------------------------------------------------------------
+
+const args = process.argv.slice(2);
+let mode = 'warn';       // warn | fail
+let slugFilter = null;   // --slug <name>
+let jsonOutput = false;  // --json
+let strict = false;      // --strict (same as --mode fail)
+
+for (let i = 0; i < args.length; i++) {
+  const a = args[i];
+  if (a === '--mode') {
+    const v = args[++i];
+    if (v !== 'warn' && v !== 'fail') {
+      console.error('ERROR: --mode must be warn or fail');
+      process.exit(2);
+    }
+    mode = v;
+  } else if (a === '--slug') {
+    slugFilter = args[++i];
+    if (!slugFilter) {
+      console.error('ERROR: --slug requires a value');
+      process.exit(2);
+    }
+  } else if (a === '--json') {
+    jsonOutput = true;
+  } else if (a === '--strict') {
+    strict = true;
+    mode = 'fail';
+  } else {
+    console.error(`ERROR: unknown argument: ${a}`);
+    process.exit(2);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const MONOREPO_ROOT = 'C:/Dev/regen-root';
+const CLAUTH_BASE = 'http://127.0.0.1:52437';
+
+// Ordered list of root-relative prefixes to probe when looking for app source
+const MONOREPO_SEARCH_DIRS = ['apps', 'sites', 'models', 'mcp-servers', 'packages'];
+
+const REQUIRED_FRONTMATTER_FIELDS = ['schema_version', 'entity_slug', 'artifact_type', 'environments', 'status'];
+const ALLOWED_ARTIFACT_TYPES = ['website', 'api', 'package', 'worker', 'mcp-server'];
+const ALLOWED_STATUSES = ['active', 'draft', 'deprecated'];
+const ALLOWED_ENVIRONMENTS = ['dev', 'prod'];
+const ALLOWED_SCHEMA_VERSIONS = ['1.0'];
+
+// Supabase project and REST base
+const SUPABASE_PROJECT_HOST = 'uvojezuorjgqzmhhgluu.supabase.co';
+
+// ---------------------------------------------------------------------------
+// Result tracking
+// ---------------------------------------------------------------------------
+
+const results = [];
+let hasHardFail = false;
+
+function emit(level, slug, message, detail) {
+  const entry = { level, slug, message, detail: detail || null };
+  results.push(entry);
+  if (level === 'FAIL') hasHardFail = true;
+  if (!jsonOutput) {
+    const prefix = level === 'FAIL' ? '✗ FAIL' : level === 'WARN' ? '⚠ WARN' : '✓ PASS';
+    console.log(`${prefix} [${slug}] ${message}${detail ? ` — ${detail}` : ''}`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// HTTP helpers
+// ---------------------------------------------------------------------------
+
+/** Fetch plain text from clauth daemon (never prints value) */
+function fetchClauth(service) {
+  return new Promise((resolve, reject) => {
+    const req = http.get(`${CLAUTH_BASE}/v/${service}`, (res) => {
+      let buf = '';
+      res.on('data', (c) => (buf += c));
+      res.on('end', () => {
+        if (res.statusCode !== 200) {
+          reject(new Error(`clauth /v/${service} → HTTP ${res.statusCode}`));
+        } else {
+          resolve(buf.trim());
+        }
+      });
+    });
+    req.on('error', reject);
+    req.setTimeout(5000, () => { req.destroy(); reject(new Error('clauth timeout')); });
+  });
+}
+
+/** REST GET against Supabase with anon key */
+function supabaseGet(anonKey, path) {
+  return new Promise((resolve, reject) => {
+    const options = {
+      hostname: SUPABASE_PROJECT_HOST,
+      path,
+      method: 'GET',
+      headers: {
+        'apikey': anonKey,
+        'Authorization': `Bearer ${anonKey}`,
+        'Content-Type': 'application/json',
+        'Accept': 'application/json',
+      },
+    };
+    const req = https.request(options, (res) => {
+      let buf = '';
+      res.on('data', (c) => (buf += c));
+      res.on('end', () => {
+        if (res.statusCode !== 200) {
+          reject(new Error(`Supabase REST ${path} → HTTP ${res.statusCode}: ${buf.slice(0, 200)}`));
+        } else {
+          try {
+            resolve(JSON.parse(buf));
+          } catch (e) {
+            reject(new Error(`JSON parse error: ${e.message}`));
+          }
+        }
+      });
+    });
+    req.on('error', reject);
+    req.setTimeout(10000, () => { req.destroy(); reject(new Error('Supabase timeout')); });
+    req.end();
+  });
+}
+
+// ---------------------------------------------------------------------------
+// YAML frontmatter parser (minimal — no external dep required)
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse YAML frontmatter from a PUBLISH.md string.
+ * Only handles scalar values, arrays on same line ([a, b, c]), and quoted strings.
+ * Returns null if no frontmatter delimiters found.
+ */
+function parseFrontmatter(content) {
+  const fmMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!fmMatch) return null;
+
+  const yaml = fmMatch[1];
+  const result = {};
+
+  for (const line of yaml.split(/\r?\n/)) {
+    const kv = line.match(/^([a-zA-Z_][a-zA-Z0-9_]*):\s*(.*)$/);
+    if (!kv) continue;
+
+    const key = kv[1];
+    let value = kv[2].trim();
+
+    // Array: [a, b, c] or [a] or []
+    if (value.startsWith('[') && value.endsWith(']')) {
+      const inner = value.slice(1, -1).trim();
+      result[key] = inner ? inner.split(',').map((s) => s.trim().replace(/^["']|["']$/g, '')) : [];
+      continue;
+    }
+
+    // Quoted string
+    if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+      result[key] = value.slice(1, -1);
+      continue;
+    }
+
+    result[key] = value;
+  }
+
+  return result;
+}
+
+/**
+ * Extract surface section IDs from PUBLISH.md content.
+ * Looks for <!-- SURFACE:<id> --> markers.
+ */
+function parseSurfaceIds(content) {
+  const ids = [];
+  const re = /<!--\s*SURFACE:([a-zA-Z0-9_-]+)\s*-->/g;
+  let m;
+  while ((m = re.exec(content)) !== null) {
+    ids.push(m[1]);
+  }
+  return ids;
+}
+
+/**
+ * Extract watch_paths from a named surface section.
+ * Returns array of watch_path strings (may be empty).
+ */
+function parseSurfaceWatchPaths(content, surfaceId) {
+  const re = new RegExp(`<!--\\s*SURFACE:${surfaceId}\\s*-->[\\s\\S]*?<!--\\s*/SURFACE:${surfaceId}\\s*-->`, 'i');
+  const section = content.match(re);
+  if (!section) return [];
+
+  const block = section[0];
+  const watchPathsMatch = block.match(/watch_paths:\s*\r?\n((?:\s+-\s+.+\r?\n?)*)/);
+  if (!watchPathsMatch) return [];
+
+  return watchPathsMatch[1]
+    .split(/\r?\n/)
+    .map((l) => l.replace(/^\s+-\s+/, '').trim())
+    .filter(Boolean);
+}
+
+// ---------------------------------------------------------------------------
+// Path resolution
+// ---------------------------------------------------------------------------
+
+/**
+ * Derive the local filesystem path where we'd expect PUBLISH.md for a given app_slug.
+ * Probes MONOREPO_SEARCH_DIRS in order, returning the first hit.
+ * Returns null if no directory found (standalone or unknown).
+ */
+function resolveAppRoot(slug) {
+  for (const dir of MONOREPO_SEARCH_DIRS) {
+    const candidate = path.join(MONOREPO_ROOT, dir, slug);
+    if (fs.existsSync(candidate)) return candidate;
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Validation logic for a single app row
+// ---------------------------------------------------------------------------
+
+function validateApp(slug) {
+  const appRoot = resolveAppRoot(slug);
+
+  if (!appRoot) {
+    // Could be standalone repo — skip with note in v1
+    emit('WARN', slug, 'app root not found in monorepo — may be standalone repo, skipping (v1 scope)');
+    return null;
+  }
+
+  const publishPath = path.join(appRoot, 'PUBLISH.md');
+
+  if (!fs.existsSync(publishPath)) {
+    if (mode === 'fail') {
+      emit('FAIL', slug, 'PUBLISH.md missing', publishPath);
+    } else {
+      emit('WARN', slug, 'PUBLISH.md missing', publishPath);
+    }
+    return null;
+  }
+
+  // File exists — parse and validate
+  const content = fs.readFileSync(publishPath, 'utf8');
+  const fm = parseFrontmatter(content);
+
+  if (!fm) {
+    emit('FAIL', slug, 'PUBLISH.md has no YAML frontmatter (missing --- delimiters)', publishPath);
+    return null;
+  }
+
+  let ok = true;
+
+  // Check required fields
+  for (const field of REQUIRED_FRONTMATTER_FIELDS) {
+    if (fm[field] === undefined || fm[field] === null || fm[field] === '') {
+      emit('FAIL', slug, `PUBLISH.md missing required field: ${field}`, publishPath);
+      ok = false;
+    }
+  }
+
+  // schema_version
+  if (fm.schema_version && !ALLOWED_SCHEMA_VERSIONS.includes(fm.schema_version)) {
+    emit('FAIL', slug, `PUBLISH.md schema_version "${fm.schema_version}" not in allowed set: ${ALLOWED_SCHEMA_VERSIONS.join(', ')}`, publishPath);
+    ok = false;
+  }
+
+  // artifact_type
+  if (fm.artifact_type && !ALLOWED_ARTIFACT_TYPES.includes(fm.artifact_type)) {
+    emit('FAIL', slug, `PUBLISH.md artifact_type "${fm.artifact_type}" not in allowed set: ${ALLOWED_ARTIFACT_TYPES.join(', ')}`, publishPath);
+    ok = false;
+  }
+
+  // status
+  if (fm.status && !ALLOWED_STATUSES.includes(fm.status)) {
+    emit('FAIL', slug, `PUBLISH.md status "${fm.status}" not in allowed set: ${ALLOWED_STATUSES.join(', ')}`, publishPath);
+    ok = false;
+  }
+
+  // environments — must be array, at least one, each in allowed set
+  if (fm.environments !== undefined) {
+    if (!Array.isArray(fm.environments) || fm.environments.length === 0) {
+      emit('FAIL', slug, 'PUBLISH.md environments must be a non-empty array', publishPath);
+      ok = false;
+    } else {
+      for (const env of fm.environments) {
+        if (!ALLOWED_ENVIRONMENTS.includes(env)) {
+          emit('FAIL', slug, `PUBLISH.md environments contains unknown value: "${env}"`, publishPath);
+          ok = false;
+        }
+      }
+    }
+  }
+
+  // Surface sections — at least one required
+  const surfaceIds = parseSurfaceIds(content);
+  if (surfaceIds.length === 0) {
+    emit('FAIL', slug, 'PUBLISH.md has no <!-- SURFACE:<id> --> sections', publishPath);
+    ok = false;
+  } else {
+    // Each surface must have watch_paths
+    for (const sid of surfaceIds) {
+      const wp = parseSurfaceWatchPaths(content, sid);
+      if (wp.length === 0) {
+        emit('FAIL', slug, `PUBLISH.md surface "${sid}" has no watch_paths entries`, publishPath);
+        ok = false;
+      }
+    }
+  }
+
+  if (ok) {
+    emit('PASS', slug, 'PUBLISH.md valid', `${surfaceIds.length} surface(s): ${surfaceIds.join(', ')}`);
+  }
+
+  return { fm, surfaceIds, publishPath };
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+async function main() {
+  if (!jsonOutput) {
+    console.log(`\nvalidate-publish-manifests — mode=${mode}${slugFilter ? ` slug=${slugFilter}` : ''}\n`);
+  }
+
+  // 1. Get Supabase anon key from clauth
+  let anonKey;
+  try {
+    anonKey = await fetchClauth('supabase-anon');
+  } catch (err) {
+    console.error(`ERROR: cannot reach clauth daemon — ${err.message}`);
+    console.error('Fix: ensure clauth daemon is running at http://127.0.0.1:52437');
+    process.exit(1);
+  }
+
+  // 2. Query app_deployments for active rows
+  let rows;
+  try {
+    let qpath = '/rest/v1/app_deployments?status=eq.active&select=app_slug,environment,url&order=app_slug.asc';
+    if (slugFilter) {
+      qpath += `&app_slug=eq.${encodeURIComponent(slugFilter)}`;
+    }
+    rows = await supabaseGet(anonKey, qpath);
+  } catch (err) {
+    console.error(`ERROR: Supabase query failed — ${err.message}`);
+    process.exit(1);
+  }
+
+  if (!Array.isArray(rows) || rows.length === 0) {
+    if (!jsonOutput) {
+      console.log(slugFilter ? `No active app_deployments row found for slug: ${slugFilter}` : 'No active app_deployments rows found.');
+    }
+    process.exit(0);
+  }
+
+  // Deduplicate slugs (same app_slug may have dev + prod rows)
+  const slugsSeen = new Set();
+  const uniqueRows = rows.filter((r) => {
+    if (slugsSeen.has(r.app_slug)) return false;
+    slugsSeen.add(r.app_slug);
+    return true;
+  });
+
+  if (!jsonOutput) {
+    console.log(`Checking ${uniqueRows.length} unique app slug(s) from ${rows.length} active app_deployments row(s)...\n`);
+  }
+
+  // 3. Validate each slug
+  for (const row of uniqueRows) {
+    validateApp(row.app_slug);
+  }
+
+  // 4. Summary
+  const passCount = results.filter((r) => r.level === 'PASS').length;
+  const warnCount = results.filter((r) => r.level === 'WARN').length;
+  const failCount = results.filter((r) => r.level === 'FAIL').length;
+
+  if (jsonOutput) {
+    console.log(JSON.stringify({ mode, results, summary: { pass: passCount, warn: warnCount, fail: failCount } }, null, 2));
+  } else {
+    console.log(`\nSummary: ${passCount} PASS · ${warnCount} WARN · ${failCount} FAIL`);
+    if (hasHardFail) {
+      console.log('Result: FAIL\n');
+    } else {
+      console.log(warnCount > 0 ? 'Result: WARN (exit 0 in warn mode)\n' : 'Result: PASS\n');
+    }
+  }
+
+  process.exit(hasHardFail ? 1 : 0);
+}
+
+main().catch((err) => {
+  console.error(`FATAL: ${err.message}`);
+  process.exit(1);
+});

package/skills/build/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: rdc:build
-description: "Usage `rdc:build <epic-id>` — You have a planned epic with tasks ready to execute. Dispatches parallel typed agents, each commits atomically to develop, closes work items, and runs the validator gate. Call after rdc:plan or when told to build."
+description: "Usage `rdc:build <epic-id>` — You have a planned epic with tasks ready to execute. Dispatches parallel typed agents, each commits atomically to develop, runs a mandatory per-wave code-review gate (pr-review-toolkit:code-reviewer), closes work items, and runs the validator gate. Call after rdc:plan or when told to build."
 ---
 
 > **⚠️ OUTPUT CONTRACT (READ FIRST):** `guides/output-contract.md`
@@ -284,6 +284,7 @@ Read the task title and description, then:
      fi
      ```
    - Then run the post-wave test gate (Step 8) on the merged state
+   - Then run the code-review gate (Step 9b) before the next wave dispatches
    - Continue to next wave
 
    **If an agent fails (returns no worktree branch):**
@@ -293,6 +294,32 @@ Read the task title and description, then:
      BUILD_STATUS: { wave, tasks_done, tasks_failed, commits, escalated: true }
      ```
 
+9b. **Mandatory per-wave code-review gate (runs after merge + test gate, BEFORE next wave dispatches):**
+
+    ⛔ **NO wave may dispatch until the previous wave's code-review pass clears.** Memory `feedback_code_review_per_wave.md` — Davesend 2026-05-24 incident.
+
+    Dispatch ONE `pr-review-toolkit:code-reviewer` agent with the wave's merged diff:
+
+    ```
+    Agent({
+      subagent_type: "pr-review-toolkit:code-reviewer",
+      description: "Wave <N> code review",
+      prompt: "Review the diff `git diff <wave-base-sha>..HEAD` on develop.
+               Focus on: bugs, logic errors, security vulnerabilities, project-convention adherence
+               (.claude/rules/*, CLAUDE.md). Apply confidence-based filtering — high-confidence
+               findings only. Report severity per finding: critical | high | medium | low.
+               Return CODE_REVIEW_COMPLETE with: { critical_count, high_count, medium_count,
+               low_count, findings: [{severity, file:line, issue, suggested_fix}] }."
+    })
+    ```
+
+    **Severity gate (default — high+ blocks):**
+    - `critical` or `high` findings → reopen affected work items to `todo` with finding text in notes; fix in a new wave before continuing
+    - `medium` or `low` findings → append to each work item's `implementation_report.flags`; do NOT reopen; validator sees them
+    - Zero findings → log `CODE_REVIEW: CLEAN` and proceed to next wave
+
+    Under `RDC_TEST=1`: echo `[RDC_TEST] skipping code-review dispatch` and proceed.
+
 10. **Mandatory validator gate (runs after ALL waves complete — before any work item closes):**
 
     ⛔ **NO work item may be set to `done` without the validator passing it.**
@@ -301,8 +328,8 @@ Read the task title and description, then:
     ⚠️ The validator does NOT use `isolation: "worktree"` — it must read the fully merged develop branch. Omit the isolation parameter for this dispatch only.
 
     ```
-    "Read C:/Dev/regen-root/.rdc/guides/agent-bootstrap.md then C:/Dev/regen-root/.rdc/guides/verify.md.
-     Read C:/Dev/regen-root/.rdc/guides/engineering-behavior.md before validating scope, deviations, and evidence.
+    "Read {PROJECT_ROOT}/.rdc/guides/agent-bootstrap.md then {PROJECT_ROOT}/.rdc/guides/verify.md.
+     Read {PROJECT_ROOT}/.rdc/guides/engineering-behavior.md before validating scope, deviations, and evidence.
      Validate these work items: [list of IDs and titles].
      Apps touched: [list].
      Git diff since build start: [attach or reference].

package/skills/co-develop/SKILL.md

@@ -110,7 +110,7 @@ the source of truth.
   "skill": "rdc:review",
   "task": "Audit the current diff for regressions before merge.",
   "context": {
-    "repo": "C:\\Dev\\regen-root",
+    "repo": "{PROJECT_ROOT}",
     "work_item_id": "<optional-uuid>",
     "branch": "develop",
     "owned_files": []

package/skills/deploy/SKILL.md

@@ -44,6 +44,9 @@ rdc:deploy: <slug> → <domain>
 [ ] Build-id resolved (default: HEAD of watched branch)
 [ ] Env vars present in Coolify (compare to registry)
 [ ] Type-specific preflight (see docs/runbooks/coolify-deploy-checklist.md)
+[ ] Mandatory pre-deploy code-review (pr-review-toolkit:code-reviewer on `git diff <last-deployed-sha>..HEAD` for this app's paths). Block deploy on `critical`/`high` findings; record `medium`/`low` and proceed.
+[ ] PUBLISH.md read from app root (warn if absent; fail if present but invalid)
+[ ] watch_paths derived from PUBLISH.md surfaces (union of all surface watch_paths arrays) and updated in app_deployments
 [ ] Deploy triggered
 [ ] Deployment reached "finished" state
 [ ] Gate: HTTP 200
@@ -51,6 +54,7 @@ rdc:deploy: <slug> → <domain>
 [ ] Gate: cache headers correct on HTML
 [ ] Gate: container running on declared port
 [ ] Cloudflare cache purged (if proxied)
+[ ] artifact_registry INSERT per PUBLISH.md surface (if PUBLISH.md present)
 [ ] deployment_registry updated (last_deploy_at, status)
 ✅ rdc:deploy: <slug> deployed in Nm Ns
 ```
@@ -66,10 +70,10 @@ Template selection:
 
 ```
 rdc:deploy new: <slug>
-[ ] .dockerignore present at regen-root root (ls C:/Dev/regen-root/.dockerignore — STOP if missing)
+[ ] .dockerignore present at project root (`ls {PROJECT_ROOT}/.dockerignore` — STOP if missing)
 [ ] Template loaded from docs/runbooks/coolify-app-templates.json (pick nextjs-app / static-site / mcp-server)
 [ ] Required vars substituted: NAME, APP_PATH, DOMAIN, BRANCH, PROJECT_UUID, ENVIRONMENT_UUID [+ TURBO_FILTER / PORT]
-[ ] DNS path chosen (A: *.dev.place.fund  B: apex  C: other zone)
+[ ] DNS path chosen (A: staging wildcard  B: apex  C: other zone)
 [ ] DNS record verified or wildcard confirmed
 [ ] Cloudflare proxy setting correct for DNS path
 [ ] Application created via POST /applications/private-github-app (template payload)
@@ -117,7 +121,7 @@ rdc:deploy audit: fleet scan
 [ ] Env var drift (registry.env_vars_needed vs Coolify env)
 [ ] Branch mismatches (Coolify git_branch ≠ expected)
 [ ] Disk space on 64.237.54.189
-[ ] CF proxy misconfigs on *.dev.place.fund
+[ ] DNS/proxy misconfigs on configured staging wildcard
 [ ] Duplicate apps (same repo, multiple UUIDs)
 
 Findings:
@@ -134,6 +138,76 @@ Severity rules:
 
 `--fix` auto-remediates only: missing watch_paths, registry row updates, CF cache purges. Never touches env vars, DNS, or container config without explicit confirmation.
 
+## PUBLISH.md Integration
+
+Every deploy reads `PUBLISH.md` from the app's source root to derive `watch_paths` and to register surfaces in Studio `artifact_registry`.
+
+### Step 6 — Read PUBLISH.md from the app root
+
+```bash
+MONOREPO_PATH=$(get_app_deployments_monorepo_path "$SLUG")
+PUBLISH_MD="$MONOREPO_PATH/PUBLISH.md"
+
+if [ ! -f "$PUBLISH_MD" ]; then
+  echo "WARN: PUBLISH.md missing for $SLUG — using app_deployments.watch_paths only"
+  # Deploy continues; watch_paths derivation and artifact_registry INSERT are skipped
+fi
+```
+
+PUBLISH.md format: see `C:/Dev/rdc-skills/guides/publish-md-spec.md` (authoritative).
+
+Required frontmatter fields: `schema_version`, `entity_slug`, `artifact_type`, `environments`, `status`.
+One or more `<!-- SURFACE:<id> -->` … `<!-- /SURFACE:<id> -->` blocks per surface (each with `path`, `source_dir`, `build_type`, `visibility`, `cache`, `watch_paths`).
+
+If PUBLISH.md is **present but invalid** (missing required field, bad enum, no surface blocks): abort deploy with `BLOCKED: PUBLISH.md parse error for <slug> — <reason>`.
+
+### Step 7 — Derive watch_paths from PUBLISH.md surfaces
+
+Union all `watch_paths` arrays across every surface section in PUBLISH.md. Update `app_deployments.watch_paths` for the app slug to this derived union before triggering the Coolify deploy.
+
+```sql
+UPDATE app_deployments
+SET watch_paths = '<union-of-surface-watch_paths>'
+WHERE app_slug = '<slug>';
+```
+
+Also PATCH the Coolify application's `watch_paths` field:
+
+```bash
+_COOLIFY=$(curl -s http://127.0.0.1:52437/v/coolify-api)
+WATCH_PATHS_JSON=$(derive_watch_paths_union "$PUBLISH_MD")
+curl -s -X PATCH -H "Authorization: Bearer $_COOLIFY" \
+  -H "Content-Type: application/json" \
+  -d "{\"watch_paths\":\"$WATCH_PATHS_JSON\"}" \
+  "$DEPLOY_API_BASE/api/v1/applications/<uuid>"
+```
+
+### Step 15 — storeArtifact per surface (after successful deploy)
+
+After the deployment reaches "finished" state, INSERT one row into Studio `artifact_registry` for each surface declared in PUBLISH.md:
+
+| Column | Value |
+|--------|-------|
+| `entity_slug` | from PUBLISH.md frontmatter `entity_slug` |
+| `artifact_type` | from PUBLISH.md frontmatter `artifact_type` |
+| `canonical_url` | `https://<app_deployments.url><surface.path>` |
+| `surface_id` | surface name from `<!-- SURFACE:<id> -->` marker |
+| `commit_sha` | HEAD SHA of the deploy |
+| `published_at` | `now()` |
+
+Use the Supabase MCP (`mcp__claude_ai_Supabase__execute_sql`) from the supervisor session:
+
+```sql
+INSERT INTO artifact_registry (entity_slug, artifact_type, canonical_url, surface_id, commit_sha, published_at)
+VALUES ('<entity_slug>', '<artifact_type>', 'https://<url><path>', '<surface_id>', '<commit_sha>', now())
+ON CONFLICT (entity_slug, surface_id) DO UPDATE SET
+  canonical_url = EXCLUDED.canonical_url,
+  commit_sha = EXCLUDED.commit_sha,
+  published_at = EXCLUDED.published_at;
+```
+
+If the INSERT fails, surface the failure in the deploy output but **do NOT roll back the deploy**. The artifact registry is a post-deploy record, not a deploy gate.
+
 ## Coolify Access — clauth + REST API
 
 All Coolify operations use the clauth daemon and the Coolify REST API directly.
@@ -145,42 +219,64 @@ _COOLIFY=$(curl -s http://127.0.0.1:52437/v/coolify-api)
 
 # List applications
 curl -s -H "Authorization: Bearer $_COOLIFY" \
-  https://deploy.regendevcorp.com/api/v1/applications
+  "$DEPLOY_API_BASE/api/v1/applications"
 
 # Get application details
 curl -s -H "Authorization: Bearer $_COOLIFY" \
-  https://deploy.regendevcorp.com/api/v1/applications/<uuid>
+  "$DEPLOY_API_BASE/api/v1/applications/<uuid>"
 
 # Deploy (trigger)
 curl -s -X POST -H "Authorization: Bearer $_COOLIFY" \
-  https://deploy.regendevcorp.com/api/v1/applications/<uuid>/deploy
+  "$DEPLOY_API_BASE/api/v1/applications/<uuid>/deploy"
 
 # Get deployment logs
 curl -s -H "Authorization: Bearer $_COOLIFY" \
-  https://deploy.regendevcorp.com/api/v1/deployments/<deployment-id>
+  "$DEPLOY_API_BASE/api/v1/deployments/<deployment-id>"
 
 # Set env var
 curl -s -X POST -H "Authorization: Bearer $_COOLIFY" \
   -H "Content-Type: application/json" \
   -d '{"key":"<KEY>","value":"<VALUE>"}' \
-  https://deploy.regendevcorp.com/api/v1/applications/<uuid>/envs
+  "$DEPLOY_API_BASE/api/v1/applications/<uuid>/envs"
 
 # Set watch_paths
 curl -s -X PATCH -H "Authorization: Bearer $_COOLIFY" \
   -H "Content-Type: application/json" \
   -d '{"watch_paths":"apps/<name>/**\npackages/**"}' \
-  https://deploy.regendevcorp.com/api/v1/applications/<uuid>
+  "$DEPLOY_API_BASE/api/v1/applications/<uuid>"
 ```
 
 **Never print `$_COOLIFY` to stdout.** Inline from clauth only — do not assign raw strings.
 
 If clauth daemon is not responding (`curl -s http://127.0.0.1:52437/ping` fails):
 ```
-BLOCKED: clauth daemon is not responding.
-Fix: Run C:\Dev\regen-root\scripts\restart-clauth.bat, then unlock at http://127.0.0.1:52437
+BLOCKED: credential provider is not responding.
+Fix: start the project's credential provider or configure deployment credentials through env vars, then retry.
 I cannot proceed until this is resolved.
 ```
 
+## Deployment Event Log — `coolify_events`
+
+Every Coolify deploy emits a webhook → `coolify_events` row. Use this for last-N-deploys queries, debugging failed deploys, and reconciling local state with Coolify state.
+
+Query the last 5 events for an app:
+```sql
+SELECT created_at, event_type, status, branch, commit_hash, duration_seconds
+FROM coolify_events
+WHERE app_uuid = '<uuid>' OR app_name = '<slug>'
+ORDER BY created_at DESC LIMIT 5;
+```
+
+Fields:
+- `app_uuid` — Coolify application UUID (matches `app_deployments.coolify_uuid`)
+- `event_type` — `started | succeeded | failed | cancelled` (canonical values; consult webhook receiver for full enum)
+- `status` — overall deploy status
+- `branch`, `commit_hash`, `commit_message` — git context
+- `duration_seconds` — total deploy time
+- `payload` — full webhook payload (jsonb) for forensic debugging
+
+When diagnosing a broken deploy in Mode 3: query `coolify_events` FIRST before re-running the deploy — the most recent event row tells you whether the previous deploy actually triggered, whether it failed, and how long it ran. Faster than checking the Coolify UI.
+
 ## References
 
 - Type-specific checklists + DNS tree + gate commands: `docs/runbooks/coolify-deploy-checklist.md`
@@ -189,7 +285,7 @@ I cannot proceed until this is resolved.
   ```
   Server UUID:     ih386anenvvvn6fy1umtyow0
   Server IP:       64.237.54.189
-  Dashboard:       https://deploy.regendevcorp.com
+  Dashboard:       <deployment-dashboard-url>
   GitHub App UUID: xdmcy60putp5h9j7k4kwg9c3
   ```