@kody-ade/kody-engine 0.2.47 → 0.2.49

package/dist/bin/kody2.js

@@ -3,7 +3,7 @@
 // package.json
 var package_default = {
   name: "@kody-ade/kody-engine",
-  version: "0.2.47",
+  version: "0.2.49",
   description: "kody2 \u2014 autonomous development engine. Single-session Claude Code agent behind a generic executor + declarative executable profiles.",
   license: "MIT",
   type: "module",
@@ -51,8 +51,8 @@ var package_default = {
 
 // src/chat-cli.ts
 import { execFileSync as execFileSync20 } from "child_process";
-import * as fs19 from "fs";
-import * as path16 from "path";
+import * as fs22 from "fs";
+import * as path19 from "path";
 
 // src/chat/events.ts
 import * as fs from "fs";
@@ -529,8 +529,8 @@ async function emit(sink, type, sessionId, suffix, payload) {
 
 // src/kody2-cli.ts
 import { execFileSync as execFileSync19 } from "child_process";
-import * as fs18 from "fs";
-import * as path15 from "path";
+import * as fs21 from "fs";
+import * as path18 from "path";
 
 // src/dispatch.ts
 import * as fs5 from "fs";
@@ -572,6 +572,9 @@ function autoDispatch(opts) {
     if (/\bresolve\b/.test(afterTag)) {
       return { executable: "resolve", cliArgs: { pr: targetNum }, target: targetNum };
     }
+    if (/\bui-review\b/.test(afterTag)) {
+      return { executable: "ui-review", cliArgs: { pr: targetNum }, target: targetNum };
+    }
     if (/\breview\b/.test(afterTag)) {
       return { executable: "review", cliArgs: { pr: targetNum }, target: targetNum };
     }
@@ -633,8 +636,8 @@ function extractFeedback(afterTag) {
 }
 
 // src/executor.ts
-import * as fs17 from "fs";
-import * as path14 from "path";
+import * as fs20 from "fs";
+import * as path17 from "path";
 
 // src/litellm.ts
 import { execFileSync, spawn } from "child_process";
@@ -1097,29 +1100,11 @@ function noteFromAction(action) {
 }
 function renderStateComment(state) {
   const lines = [];
-  lines.push(STATE_BEGIN);
-  lines.push("");
-  lines.push("```json");
-  lines.push(
-    JSON.stringify(
-      {
-        schemaVersion: state.schemaVersion,
-        core: state.core,
-        artifacts: state.artifacts ?? {},
-        executables: state.executables,
-        history: state.history,
-        ...state.flow ? { flow: state.flow } : {}
-      },
-      null,
-      2
-    )
-  );
-  lines.push("```");
-  lines.push("");
-  lines.push(STATE_END);
-  lines.push("");
-  lines.push("## kody2 task state");
+  lines.push("## \u{1F4CB} kody2 task state");
   lines.push("");
+  if (state.flow) {
+    lines.push(`- **Flow:** \`${state.flow.name}\` (step: \`${state.flow.step}\`)`);
+  }
   lines.push(`- **Phase:** \`${state.core.phase}\`  **Status:** \`${state.core.status}\``);
   if (state.core.currentExecutable) {
     lines.push(`- **Last executable:** \`${state.core.currentExecutable}\``);
@@ -1146,6 +1131,31 @@ function renderStateComment(state) {
     }
     lines.push("");
   }
+  lines.push("<details>");
+  lines.push("<summary>Raw state (JSON)</summary>");
+  lines.push("");
+  lines.push(STATE_BEGIN);
+  lines.push("");
+  lines.push("```json");
+  lines.push(
+    JSON.stringify(
+      {
+        schemaVersion: state.schemaVersion,
+        core: state.core,
+        artifacts: state.artifacts ?? {},
+        executables: state.executables,
+        history: state.history,
+        ...state.flow ? { flow: state.flow } : {}
+      },
+      null,
+      2
+    )
+  );
+  lines.push("```");
+  lines.push("");
+  lines.push(STATE_END);
+  lines.push("");
+  lines.push("</details>");
   return lines.join("\n");
 }
 function readTaskState(target, number, cwd) {
@@ -1816,6 +1826,491 @@ function formatToolsUsage(profile) {
   return lines.join("\n");
 }
 
+// src/scripts/discoverQaContext.ts
+import * as fs13 from "fs";
+import * as path12 from "path";
+
+// src/scripts/frameworkDetectors.ts
+import * as fs12 from "fs";
+import * as path11 from "path";
+function detectFrameworks(cwd) {
+  const out = [];
+  let deps = {};
+  try {
+    const pkg = JSON.parse(fs12.readFileSync(path11.join(cwd, "package.json"), "utf-8"));
+    deps = { ...pkg.dependencies, ...pkg.devDependencies };
+  } catch {
+    return out;
+  }
+  if (deps.payload || deps["@payloadcms/next"]) {
+    out.push({
+      name: "payload-cms",
+      version: deps.payload ?? deps["@payloadcms/next"] ?? null,
+      configFile: findFile(cwd, ["payload.config.ts", "payload-config.ts", "src/payload.config.ts"])
+    });
+  }
+  if (deps["next-auth"]) {
+    out.push({
+      name: "nextauth",
+      version: deps["next-auth"] ?? null,
+      configFile: findFile(cwd, ["auth.ts", "auth.config.ts", "src/auth.ts", "src/auth.config.ts"])
+    });
+  }
+  if (deps.prisma || deps["@prisma/client"]) {
+    out.push({
+      name: "prisma",
+      version: deps.prisma ?? deps["@prisma/client"] ?? null,
+      configFile: findFile(cwd, ["prisma/schema.prisma"])
+    });
+  }
+  if (deps.next) {
+    out.push({
+      name: "nextjs",
+      version: deps.next ?? null,
+      configFile: findFile(cwd, ["next.config.ts", "next.config.mjs", "next.config.js"])
+    });
+  }
+  return out;
+}
+function findFile(cwd, candidates) {
+  for (const c of candidates) {
+    if (fs12.existsSync(path11.join(cwd, c))) return c;
+  }
+  return null;
+}
+var COLLECTION_DIRS = [
+  "src/server/payload/collections",
+  "src/payload/collections",
+  "src/collections",
+  "payload/collections"
+];
+function discoverPayloadCollections(cwd) {
+  const out = [];
+  for (const dir of COLLECTION_DIRS) {
+    const full = path11.join(cwd, dir);
+    if (!fs12.existsSync(full)) continue;
+    let files;
+    try {
+      files = fs12.readdirSync(full).filter((f) => f.endsWith(".ts") || f.endsWith(".tsx"));
+    } catch {
+      continue;
+    }
+    for (const file of files) {
+      try {
+        const filePath = path11.join(full, file);
+        const content = fs12.readFileSync(filePath, "utf-8").slice(0, 1e4);
+        const slugMatch = content.match(/slug:\s*['"]([a-z0-9-]+)['"]/);
+        if (!slugMatch) continue;
+        const slug = slugMatch[1];
+        const name = file.replace(/\.(ts|tsx)$/, "");
+        const fields = [];
+        const fieldMatches = content.matchAll(/name:\s*['"]([a-zA-Z_][a-zA-Z0-9_]*)['"]/g);
+        for (const m of fieldMatches) {
+          if (!fields.includes(m[1])) fields.push(m[1]);
+        }
+        const hasAdmin = /components:\s*\{/.test(content) || /Field:\s*['"]/.test(content) || /Cell:\s*['"]/.test(content) || /views:\s*\{/.test(content);
+        out.push({
+          name,
+          slug,
+          filePath: path11.relative(cwd, filePath),
+          fields: fields.slice(0, 20),
+          hasAdmin
+        });
+      } catch {
+      }
+    }
+  }
+  return out;
+}
+var ADMIN_COMPONENT_DIRS = ["src/ui/admin", "src/admin/components", "src/components/admin"];
+function discoverAdminComponents(cwd, collections) {
+  const out = [];
+  for (const dir of ADMIN_COMPONENT_DIRS) {
+    const full = path11.join(cwd, dir);
+    if (!fs12.existsSync(full)) continue;
+    let entries;
+    try {
+      entries = fs12.readdirSync(full, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      const entryPath = path11.join(full, entry.name);
+      let name;
+      let filePath;
+      if (entry.isDirectory()) {
+        const indexFile = ["index.tsx", "index.ts", "index.jsx", "index.js"].find(
+          (f) => fs12.existsSync(path11.join(entryPath, f))
+        );
+        if (!indexFile) continue;
+        name = entry.name;
+        filePath = path11.relative(cwd, path11.join(entryPath, indexFile));
+      } else if (/\.(tsx?|jsx?)$/.test(entry.name)) {
+        name = entry.name.replace(/\.(tsx?|jsx?)$/, "");
+        filePath = path11.relative(cwd, entryPath);
+      } else {
+        continue;
+      }
+      let usedInCollection = null;
+      if (collections) {
+        for (const col of collections) {
+          try {
+            const colContent = fs12.readFileSync(path11.join(cwd, col.filePath), "utf-8");
+            if (colContent.includes(name)) {
+              usedInCollection = col.slug;
+              break;
+            }
+          } catch {
+          }
+        }
+      }
+      out.push({ name, filePath, usedInCollection });
+    }
+  }
+  return out;
+}
+var HTTP_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"];
+function scanApiRoutes(cwd) {
+  const out = [];
+  const appDirs = ["src/app", "app"];
+  for (const appDir of appDirs) {
+    const apiDir = path11.join(cwd, appDir, "api");
+    if (!fs12.existsSync(apiDir)) continue;
+    walkApiRoutes(apiDir, "/api", cwd, out);
+    break;
+  }
+  return out;
+}
+function walkApiRoutes(dir, prefix, cwd, out) {
+  let entries;
+  try {
+    entries = fs12.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  const routeFile = entries.find((e) => e.isFile() && /^route\.(ts|js|tsx|jsx)$/.test(e.name));
+  if (routeFile) {
+    try {
+      const content = fs12.readFileSync(path11.join(dir, routeFile.name), "utf-8").slice(0, 5e3);
+      const methods = HTTP_METHODS.filter((m) => new RegExp(`export\\s+(?:async\\s+)?function\\s+${m}\\b`).test(content));
+      if (methods.length > 0) {
+        out.push({
+          path: prefix,
+          methods,
+          filePath: path11.relative(cwd, path11.join(dir, routeFile.name))
+        });
+      }
+    } catch {
+    }
+  }
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    if (entry.name === "node_modules" || entry.name === ".next") continue;
+    let segment = entry.name;
+    if (segment.startsWith("(") && segment.endsWith(")")) {
+      walkApiRoutes(path11.join(dir, entry.name), prefix, cwd, out);
+      continue;
+    }
+    if (segment.startsWith("[[") && segment.endsWith("]]")) {
+      segment = `:${segment.slice(2, -2)}?`;
+    } else if (segment.startsWith("[") && segment.endsWith("]")) {
+      segment = `:${segment.slice(1, -1)}`;
+    }
+    walkApiRoutes(path11.join(dir, entry.name), `${prefix}/${segment}`, cwd, out);
+  }
+}
+var BUILTIN_ENV_VARS = /* @__PURE__ */ new Set([
+  "NODE_ENV",
+  "HOME",
+  "PATH",
+  "USER",
+  "SHELL",
+  "TERM",
+  "LANG",
+  "PWD",
+  "HOSTNAME",
+  "PORT",
+  "CI",
+  "GITHUB_ACTIONS"
+]);
+function scanEnvVars(cwd) {
+  const candidates = [".env.example", ".env.local.example", ".env.template"];
+  for (const envFile of candidates) {
+    const envPath = path11.join(cwd, envFile);
+    if (!fs12.existsSync(envPath)) continue;
+    try {
+      const content = fs12.readFileSync(envPath, "utf-8");
+      const vars = [];
+      for (const line of content.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith("#")) continue;
+        const match = trimmed.match(/^([A-Z][A-Z0-9_]*)=/);
+        if (match && !BUILTIN_ENV_VARS.has(match[1])) vars.push(match[1]);
+      }
+      return vars;
+    } catch {
+      return [];
+    }
+  }
+  return [];
+}
+
+// src/scripts/discoverQaContext.ts
+var MAX_SERIALIZED_LENGTH = 8e3;
+function runQaDiscovery(cwd) {
+  const out = {
+    routes: [],
+    authFiles: [],
+    loginPage: null,
+    adminPath: null,
+    roles: [],
+    devCommand: "",
+    devPort: 3e3,
+    frameworks: [],
+    collections: [],
+    adminComponents: [],
+    apiRoutes: [],
+    envVars: []
+  };
+  detectDevServer(cwd, out);
+  scanFrontendRoutes(cwd, out);
+  detectAuthFiles(cwd, out);
+  detectRoles(cwd, out);
+  out.frameworks = detectFrameworks(cwd);
+  const hasPayload = out.frameworks.some((f) => f.name === "payload-cms");
+  if (hasPayload) out.collections = discoverPayloadCollections(cwd);
+  out.adminComponents = discoverAdminComponents(cwd, out.collections.length > 0 ? out.collections : void 0);
+  out.apiRoutes = scanApiRoutes(cwd);
+  out.envVars = scanEnvVars(cwd);
+  if (hasPayload && !out.adminPath) out.adminPath = "/admin";
+  return out;
+}
+function detectDevServer(cwd, out) {
+  try {
+    const pkg = JSON.parse(fs13.readFileSync(path12.join(cwd, "package.json"), "utf-8"));
+    const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
+    const pm = fs13.existsSync(path12.join(cwd, "pnpm-lock.yaml")) ? "pnpm" : fs13.existsSync(path12.join(cwd, "yarn.lock")) ? "yarn" : fs13.existsSync(path12.join(cwd, "bun.lockb")) ? "bun" : "npm";
+    if (pkg.scripts?.dev) out.devCommand = `${pm} dev`;
+    if (allDeps.next || allDeps.nuxt) out.devPort = 3e3;
+    else if (allDeps.vite) out.devPort = 5173;
+  } catch {
+  }
+}
+function scanFrontendRoutes(cwd, out) {
+  const appDirs = ["src/app", "app"];
+  for (const appDir of appDirs) {
+    const full = path12.join(cwd, appDir);
+    if (!fs13.existsSync(full)) continue;
+    walkFrontendRoutes(full, "", out);
+    break;
+  }
+}
+function walkFrontendRoutes(dir, prefix, out) {
+  let entries;
+  try {
+    entries = fs13.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  const hasPage = entries.some((e) => e.isFile() && /^page\.(tsx?|jsx?)$/.test(e.name));
+  if (hasPage) {
+    const routePath = prefix || "/";
+    const group = prefix.startsWith("/admin") ? "admin" : prefix.includes("/login") || prefix.includes("/signup") ? "auth" : prefix.includes("/api") ? "api" : "frontend";
+    out.routes.push({ path: routePath, group });
+    if (prefix.includes("/login") && !out.loginPage) out.loginPage = routePath;
+    if (prefix.startsWith("/admin") && !out.adminPath) out.adminPath = prefix;
+  }
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    if (entry.name === "node_modules" || entry.name === ".next") continue;
+    let segment = entry.name;
+    if (segment.startsWith("(") && segment.endsWith(")")) {
+      walkFrontendRoutes(path12.join(dir, entry.name), prefix, out);
+      continue;
+    }
+    if (segment.startsWith("[[") && segment.endsWith("]]")) {
+      segment = `:${segment.slice(2, -2)}?`;
+    } else if (segment.startsWith("[") && segment.endsWith("]")) {
+      segment = `:${segment.slice(1, -1)}`;
+    }
+    walkFrontendRoutes(path12.join(dir, entry.name), `${prefix}/${segment}`, out);
+  }
+}
+function detectAuthFiles(cwd, out) {
+  const candidates = [
+    "middleware.ts",
+    "middleware.js",
+    "src/middleware.ts",
+    "src/middleware.js",
+    "src/app/api/auth",
+    "src/auth",
+    "src/lib/auth",
+    "auth.config.ts",
+    "auth.ts",
+    "src/app/api/oauth"
+  ];
+  for (const c of candidates) {
+    if (fs13.existsSync(path12.join(cwd, c))) out.authFiles.push(c);
+  }
+}
+function detectRoles(cwd, out) {
+  const rolePaths = ["src/types", "src/lib", "src/utils", "src/constants", "src/access", "src/collections"];
+  for (const rp of rolePaths) {
+    const dir = path12.join(cwd, rp);
+    if (!fs13.existsSync(dir)) continue;
+    let files;
+    try {
+      files = fs13.readdirSync(dir).filter((f) => f.endsWith(".ts") || f.endsWith(".tsx"));
+    } catch {
+      continue;
+    }
+    for (const f of files) {
+      try {
+        const content = fs13.readFileSync(path12.join(dir, f), "utf-8").slice(0, 5e3);
+        const roleMatches = content.match(/(?:role|Role|ROLE)\s*[=:]\s*['"](\w+)['"]/g);
+        if (roleMatches) {
+          for (const m of roleMatches) {
+            const val = m.match(/['"](\w+)['"]/);
+            if (val && !out.roles.includes(val[1])) out.roles.push(val[1]);
+          }
+        }
+        const enumMatch = content.match(/(?:enum|type)\s+\w*[Rr]ole\w*\s*[={]([^}]+)/s);
+        if (enumMatch) {
+          const vals = enumMatch[1].match(/['"](\w+)['"]/g);
+          if (vals) {
+            for (const v of vals) {
+              const clean = v.replace(/['"]/g, "");
+              if (!out.roles.includes(clean)) out.roles.push(clean);
+            }
+          }
+        }
+      } catch {
+      }
+    }
+  }
+}
+function serializeDiscoveryForLLM(d) {
+  const sections = [];
+  sections.push(`Dev server: ${d.devCommand || "pnpm dev"} at http://localhost:${d.devPort}`);
+  if (d.loginPage) sections.push(`Login page: ${d.loginPage}`);
+  if (d.adminPath) sections.push(`Admin panel: ${d.adminPath}`);
+  if (d.roles.length > 0) sections.push(`Roles: ${d.roles.join(", ")}`);
+  if (d.frameworks.length > 0) {
+    sections.push(
+      `
+Frameworks: ${d.frameworks.map((f) => `${f.name}${f.version ? ` (${f.version})` : ""}`).join(", ")}`
+    );
+  }
+  if (d.collections.length > 0) {
+    sections.push("\nCollections (Payload CMS):");
+    for (const col of d.collections.slice(0, 15)) {
+      const fields = col.fields.slice(0, 10).join(", ");
+      let line = `- ${col.slug}: fields=[${fields}]`;
+      if (col.hasAdmin) line += " (has custom admin components)";
+      line += ` \u2014 ${col.filePath}`;
+      sections.push(line);
+    }
+    if (d.collections.length > 15) sections.push(`- ... and ${d.collections.length - 15} more collections`);
+  }
+  if (d.adminComponents.length > 0) {
+    sections.push("\nCustom Admin Components:");
+    for (const comp of d.adminComponents.slice(0, 10)) {
+      let line = `- ${comp.name} (${comp.filePath})`;
+      if (comp.usedInCollection) line += ` \u2192 used in "${comp.usedInCollection}" collection`;
+      sections.push(line);
+    }
+  }
+  if (d.apiRoutes.length > 0) {
+    sections.push("\nAPI Routes:");
+    for (const route of d.apiRoutes.slice(0, 20)) {
+      sections.push(`- ${route.methods.join("/")} ${route.path} \u2014 ${route.filePath}`);
+    }
+    if (d.apiRoutes.length > 20) sections.push(`- ... and ${d.apiRoutes.length - 20} more routes`);
+  }
+  if (d.routes.length > 0) {
+    sections.push("\nFrontend Routes:");
+    for (const route of d.routes.slice(0, 30)) {
+      sections.push(`- [${route.group}] ${route.path}`);
+    }
+    if (d.routes.length > 30) sections.push(`- ... and ${d.routes.length - 30} more routes`);
+  }
+  if (d.envVars.length > 0) sections.push(`
+Required env vars: ${d.envVars.join(", ")}`);
+  let result = sections.join("\n");
+  if (result.length > MAX_SERIALIZED_LENGTH) {
+    const cutoff = result.lastIndexOf("\n", MAX_SERIALIZED_LENGTH - 20);
+    result = result.slice(0, cutoff > 0 ? cutoff : MAX_SERIALIZED_LENGTH - 20) + "\n... (truncated)";
+  }
+  return result;
+}
+function generateQaGuideTemplate(d) {
+  const lines = [];
+  lines.push("# QA guide");
+  lines.push("");
+  lines.push("This file is read by `kody2 ui-review`. Fill in the credential placeholders");
+  lines.push("below and commit \u2014 the agent uses them to log in to your preview deployment.");
+  lines.push("");
+  lines.push("## Test accounts");
+  lines.push("");
+  lines.push("<!-- Replace CHANGE_ME with real credentials for your preview environment.");
+  lines.push("     Remove any role row you don't have an account for. -->");
+  lines.push("");
+  lines.push("| Role | Email | Password |");
+  lines.push("|------|-------|----------|");
+  if (d.roles.length > 0) {
+    for (const role of d.roles) {
+      lines.push(`| ${role} | CHANGE_ME | CHANGE_ME |`);
+    }
+  } else {
+    lines.push("| admin | admin@example.com | CHANGE_ME |");
+    lines.push("| user | user@example.com | CHANGE_ME |");
+  }
+  lines.push("");
+  lines.push("## Login");
+  lines.push("");
+  lines.push(`- Login page: \`${d.loginPage ?? "/login"}\``);
+  if (d.adminPath) lines.push(`- Admin panel: \`${d.adminPath}\``);
+  lines.push("");
+  lines.push("### Steps");
+  lines.push(`1. Navigate to \`${d.loginPage ?? "/login"}\``);
+  lines.push("2. Enter credentials from the table above");
+  lines.push("3. Submit the login form");
+  lines.push("4. Verify the redirect lands on the expected page");
+  lines.push("");
+  if (d.roles.length > 0) {
+    lines.push("## Roles");
+    lines.push("");
+    for (const role of d.roles) lines.push(`- \`${role}\``);
+    lines.push("");
+  }
+  if (d.routes.length > 0) {
+    lines.push("## Key pages");
+    lines.push("");
+    const groups = {};
+    for (const r of d.routes) {
+      if (!groups[r.group]) groups[r.group] = [];
+      groups[r.group].push(r.path);
+    }
+    for (const [group, routes] of Object.entries(groups)) {
+      lines.push(`### ${group[0].toUpperCase()}${group.slice(1)}`);
+      for (const r of routes.slice(0, 15).sort()) lines.push(`- \`${r}\``);
+      if (routes.length > 15) lines.push(`- \u2026 and ${routes.length - 15} more`);
+      lines.push("");
+    }
+  }
+  lines.push("## Notes for the reviewer");
+  lines.push("");
+  lines.push("<!-- Add any repo-specific quirks the UI-review agent should know:");
+  lines.push("     seed data assumptions, feature flags, preview-only behaviors, etc. -->");
+  lines.push("");
+  return lines.join("\n");
+}
+var discoverQaContext = async (ctx) => {
+  const discovery = runQaDiscovery(ctx.cwd);
+  ctx.data.qaDiscovery = discovery;
+  ctx.data.qaContext = serializeDiscoveryForLLM(discovery);
+};
+
 // src/scripts/dispatch.ts
 import { execFileSync as execFileSync7 } from "child_process";
 var API_TIMEOUT_MS3 = 3e4;
@@ -2293,7 +2788,7 @@ function ensureFeatureBranch(issueNumber, title, defaultBranch, cwd) {
 
 // src/gha.ts
 import { execFileSync as execFileSync11 } from "child_process";
-import * as fs12 from "fs";
+import * as fs14 from "fs";
 function getRunUrl() {
   const server = process.env.GITHUB_SERVER_URL;
   const repo = process.env.GITHUB_REPOSITORY;
@@ -2304,10 +2799,10 @@ function getRunUrl() {
 function reactToTriggerComment(cwd) {
   if (process.env.GITHUB_EVENT_NAME !== "issue_comment") return;
   const eventPath = process.env.GITHUB_EVENT_PATH;
-  if (!eventPath || !fs12.existsSync(eventPath)) return;
+  if (!eventPath || !fs14.existsSync(eventPath)) return;
   let event = null;
   try {
-    event = JSON.parse(fs12.readFileSync(eventPath, "utf-8"));
+    event = JSON.parse(fs14.readFileSync(eventPath, "utf-8"));
   } catch {
     return;
   }
@@ -2533,35 +3028,35 @@ function tryPostPr2(prNumber, body, cwd) {
 
 // src/scripts/initFlow.ts
 import { execFileSync as execFileSync13 } from "child_process";
-import * as fs14 from "fs";
-import * as path12 from "path";
+import * as fs17 from "fs";
+import * as path15 from "path";
 
 // src/registry.ts
-import * as fs13 from "fs";
-import * as path11 from "path";
+import * as fs15 from "fs";
+import * as path13 from "path";
 function getExecutablesRoot() {
-  const here = path11.dirname(new URL(import.meta.url).pathname);
+  const here = path13.dirname(new URL(import.meta.url).pathname);
   const candidates = [
-    path11.join(here, "executables"),
+    path13.join(here, "executables"),
     // dev: src/
-    path11.join(here, "..", "executables"),
+    path13.join(here, "..", "executables"),
     // built: dist/bin → dist/executables
-    path11.join(here, "..", "src", "executables")
+    path13.join(here, "..", "src", "executables")
     // fallback
   ];
   for (const c of candidates) {
-    if (fs13.existsSync(c) && fs13.statSync(c).isDirectory()) return c;
+    if (fs15.existsSync(c) && fs15.statSync(c).isDirectory()) return c;
   }
   return candidates[0];
 }
 function listExecutables(root = getExecutablesRoot()) {
-  if (!fs13.existsSync(root)) return [];
-  const entries = fs13.readdirSync(root, { withFileTypes: true });
+  if (!fs15.existsSync(root)) return [];
+  const entries = fs15.readdirSync(root, { withFileTypes: true });
   const out = [];
   for (const ent of entries) {
     if (!ent.isDirectory()) continue;
-    const profilePath = path11.join(root, ent.name, "profile.json");
-    if (fs13.existsSync(profilePath) && fs13.statSync(profilePath).isFile()) {
+    const profilePath = path13.join(root, ent.name, "profile.json");
+    if (fs15.existsSync(profilePath) && fs15.statSync(profilePath).isFile()) {
       out.push({ name: ent.name, profilePath });
     }
   }
@@ -2569,8 +3064,8 @@ function listExecutables(root = getExecutablesRoot()) {
 }
 function hasExecutable(name, root = getExecutablesRoot()) {
   if (!isSafeName(name)) return false;
-  const profilePath = path11.join(root, name, "profile.json");
-  return fs13.existsSync(profilePath) && fs13.statSync(profilePath).isFile();
+  const profilePath = path13.join(root, name, "profile.json");
+  return fs15.existsSync(profilePath) && fs15.statSync(profilePath).isFile();
 }
 function isSafeName(name) {
   return /^[a-z][a-z0-9-]*$/.test(name) && !name.includes("..");
@@ -2597,11 +3092,31 @@ function parseGenericFlags(argv) {
   return args;
 }
 
+// src/scripts/loadQaGuide.ts
+import * as fs16 from "fs";
+import * as path14 from "path";
+var QA_GUIDE_REL_PATH = ".kody2/qa-guide.md";
+var loadQaGuide = async (ctx) => {
+  const full = path14.join(ctx.cwd, QA_GUIDE_REL_PATH);
+  if (!fs16.existsSync(full)) {
+    ctx.data.qaGuide = "";
+    ctx.data.qaGuidePath = "";
+    return;
+  }
+  try {
+    ctx.data.qaGuide = fs16.readFileSync(full, "utf-8");
+    ctx.data.qaGuidePath = QA_GUIDE_REL_PATH;
+  } catch {
+    ctx.data.qaGuide = "";
+    ctx.data.qaGuidePath = "";
+  }
+};
+
 // src/scripts/initFlow.ts
 function detectPackageManager(cwd) {
-  if (fs14.existsSync(path12.join(cwd, "pnpm-lock.yaml"))) return "pnpm";
-  if (fs14.existsSync(path12.join(cwd, "yarn.lock"))) return "yarn";
-  if (fs14.existsSync(path12.join(cwd, "bun.lockb"))) return "bun";
+  if (fs17.existsSync(path15.join(cwd, "pnpm-lock.yaml"))) return "pnpm";
+  if (fs17.existsSync(path15.join(cwd, "yarn.lock"))) return "yarn";
+  if (fs17.existsSync(path15.join(cwd, "bun.lockb"))) return "bun";
   return "npm";
 }
 function qualityCommandsFor(pm) {
@@ -2722,24 +3237,36 @@ function performInit(cwd, force) {
   const pm = detectPackageManager(cwd);
   const ownerRepo = detectOwnerRepo(cwd);
   const defaultBranch = defaultBranchFromGit(cwd);
-  const configPath = path12.join(cwd, "kody.config.json");
-  if (fs14.existsSync(configPath) && !force) {
+  const configPath = path15.join(cwd, "kody.config.json");
+  if (fs17.existsSync(configPath) && !force) {
     skipped.push("kody.config.json");
   } else {
     const cfg = makeConfig(pm, ownerRepo, defaultBranch);
-    fs14.writeFileSync(configPath, `${JSON.stringify(cfg, null, 2)}
+    fs17.writeFileSync(configPath, `${JSON.stringify(cfg, null, 2)}
 `);
     wrote.push("kody.config.json");
   }
-  const workflowDir = path12.join(cwd, ".github", "workflows");
-  const workflowPath = path12.join(workflowDir, "kody2.yml");
-  if (fs14.existsSync(workflowPath) && !force) {
+  const workflowDir = path15.join(cwd, ".github", "workflows");
+  const workflowPath = path15.join(workflowDir, "kody2.yml");
+  if (fs17.existsSync(workflowPath) && !force) {
     skipped.push(".github/workflows/kody2.yml");
   } else {
-    fs14.mkdirSync(workflowDir, { recursive: true });
-    fs14.writeFileSync(workflowPath, WORKFLOW_TEMPLATE);
+    fs17.mkdirSync(workflowDir, { recursive: true });
+    fs17.writeFileSync(workflowPath, WORKFLOW_TEMPLATE);
     wrote.push(".github/workflows/kody2.yml");
   }
+  const hasUi = fs17.existsSync(path15.join(cwd, "src/app")) || fs17.existsSync(path15.join(cwd, "app")) || fs17.existsSync(path15.join(cwd, "pages"));
+  if (hasUi) {
+    const qaGuidePath = path15.join(cwd, QA_GUIDE_REL_PATH);
+    if (fs17.existsSync(qaGuidePath) && !force) {
+      skipped.push(QA_GUIDE_REL_PATH);
+    } else {
+      fs17.mkdirSync(path15.dirname(qaGuidePath), { recursive: true });
+      const discovery = runQaDiscovery(cwd);
+      fs17.writeFileSync(qaGuidePath, generateQaGuideTemplate(discovery));
+      wrote.push(QA_GUIDE_REL_PATH);
+    }
+  }
   for (const exe of listExecutables()) {
     let profile;
     try {
@@ -2748,12 +3275,12 @@ function performInit(cwd, force) {
       continue;
     }
     if (profile.kind !== "scheduled" || !profile.schedule) continue;
-    const target = path12.join(workflowDir, `kody2-${exe.name}.yml`);
-    if (fs14.existsSync(target) && !force) {
+    const target = path15.join(workflowDir, `kody2-${exe.name}.yml`);
+    if (fs17.existsSync(target) && !force) {
       skipped.push(`.github/workflows/kody2-${exe.name}.yml`);
       continue;
     }
-    fs14.writeFileSync(target, renderScheduledWorkflow(exe.name, profile.schedule));
+    fs17.writeFileSync(target, renderScheduledWorkflow(exe.name, profile.schedule));
     wrote.push(`.github/workflows/kody2-${exe.name}.yml`);
   }
   return { wrote, skipped };
@@ -3029,19 +3556,27 @@ var postPlanComment = async (ctx) => {
   const targetNumber = Number(ctx.data.commentTargetNumber ?? 0);
   const plan = ctx.data.prSummary?.trim();
   if (targetType !== "issue" || !targetNumber || !plan) return;
-  const body = renderPlanComment(targetNumber, plan);
+  const flowActive = Boolean(ctx.data.taskState?.flow);
+  const body = renderPlanComment(targetNumber, plan, { flowActive });
   try {
     postIssueComment(targetNumber, body, ctx.cwd);
   } catch {
   }
 };
-function renderPlanComment(issueNumber, plan) {
-  return `## Plan for issue #${issueNumber}
+function renderPlanComment(issueNumber, plan, opts) {
+  const head = `## Plan for issue #${issueNumber}
 
-${plan}
+${plan}`;
+  if (opts?.flowActive) {
+    return `${head}
 
 ---
-Comment \`@kody2 run\` to execute this plan.`;
+_Orchestrator will advance to the next step automatically._`;
+  }
+  return `${head}
+
+---
+Comment \`kody2 run\` (prefixed with \`@\`) to execute this plan.`;
 }
 
 // src/scripts/postResearchComment.ts
@@ -3128,8 +3663,8 @@ REVIEW_POSTED=https://github.com/${ctx.config.github.owner}/${ctx.config.github.
 
 // src/scripts/releaseFlow.ts
 import { execFileSync as execFileSync14, spawnSync } from "child_process";
-import * as fs15 from "fs";
-import * as path13 from "path";
+import * as fs18 from "fs";
+import * as path16 from "path";
 function bumpVersion(current, bump) {
   const m = current.match(/^(\d+)\.(\d+)\.(\d+)(.*)$/);
   if (!m) throw new Error(`cannot parse version '${current}' (expected x.y.z[-suffix])`);
@@ -3145,12 +3680,12 @@ function bumpVersion(current, bump) {
   return `${major}.${minor}.${patch}`;
 }
 function updateVersionInFile(file, newVersion, cwd) {
-  const abs = path13.join(cwd, file);
-  if (!fs15.existsSync(abs)) return false;
-  const content = fs15.readFileSync(abs, "utf-8");
+  const abs = path16.join(cwd, file);
+  if (!fs18.existsSync(abs)) return false;
+  const content = fs18.readFileSync(abs, "utf-8");
   const updated = content.replace(/"version"\s*:\s*"[^"]+"/, `"version": "${newVersion}"`);
   if (updated === content) return false;
-  fs15.writeFileSync(abs, updated);
+  fs18.writeFileSync(abs, updated);
   return true;
 }
 function generateChangelog(cwd, newVersion, lastTag) {
@@ -3198,19 +3733,19 @@ function generateChangelog(cwd, newVersion, lastTag) {
   return parts.join("\n");
 }
 function prependChangelog(cwd, entry) {
-  const p = path13.join(cwd, "CHANGELOG.md");
+  const p = path16.join(cwd, "CHANGELOG.md");
   const header = "# Changelog\n\nAll notable changes to this project will be documented in this file.\n\n";
-  if (fs15.existsSync(p)) {
-    const prior = fs15.readFileSync(p, "utf-8");
+  if (fs18.existsSync(p)) {
+    const prior = fs18.readFileSync(p, "utf-8");
     if (/^#\s*Changelog\b/m.test(prior)) {
       const idx = prior.indexOf("\n", prior.indexOf("# Changelog"));
-      fs15.writeFileSync(p, `${prior.slice(0, idx + 1)}
+      fs18.writeFileSync(p, `${prior.slice(0, idx + 1)}
 ${entry}${prior.slice(idx + 1)}`);
     } else {
-      fs15.writeFileSync(p, `${header}${entry}${prior}`);
+      fs18.writeFileSync(p, `${header}${entry}${prior}`);
     }
   } else {
-    fs15.writeFileSync(p, `${header}${entry}`);
+    fs18.writeFileSync(p, `${header}${entry}`);
   }
 }
 function git3(args, cwd, timeout = 6e4) {
@@ -3261,13 +3796,13 @@ var releaseFlow = async (ctx) => {
 };
 async function runPrepare(args) {
   const { cwd, bump, dryRun, versionFiles, ctx } = args;
-  const pkgPath = path13.join(cwd, "package.json");
-  if (!fs15.existsSync(pkgPath)) {
+  const pkgPath = path16.join(cwd, "package.json");
+  if (!fs18.existsSync(pkgPath)) {
     ctx.output.exitCode = 99;
     ctx.output.reason = "release prepare: package.json not found";
     return;
   }
-  const pkg = JSON.parse(fs15.readFileSync(pkgPath, "utf-8"));
+  const pkg = JSON.parse(fs18.readFileSync(pkgPath, "utf-8"));
   if (typeof pkg.version !== "string") {
     ctx.output.exitCode = 99;
     ctx.output.reason = "release prepare: package.json has no version";
@@ -3338,8 +3873,8 @@ Merge this and then run \`kody2 release --mode finalize\`.`;
 }
 async function runFinalize(args) {
   const { cwd, dryRun, timeoutMs, releaseCfg, ctx } = args;
-  const pkgPath = path13.join(cwd, "package.json");
-  const pkg = JSON.parse(fs15.readFileSync(pkgPath, "utf-8"));
+  const pkgPath = path16.join(cwd, "package.json");
+  const pkg = JSON.parse(fs18.readFileSync(pkgPath, "utf-8"));
   if (typeof pkg.version !== "string") {
     ctx.output.exitCode = 99;
     ctx.output.reason = "release finalize: package.json has no version";
@@ -3606,6 +4141,25 @@ function tryPostPr3(prNumber, body, cwd) {
   }
 }
 
+// src/scripts/resolvePreviewUrl.ts
+var DEFAULT_PREVIEW_URL = "http://localhost:3000";
+var resolvePreviewUrl = async (ctx) => {
+  const fromFlag = typeof ctx.args.previewUrl === "string" ? ctx.args.previewUrl.trim() : "";
+  if (fromFlag.length > 0) {
+    ctx.data.previewUrl = fromFlag;
+    ctx.data.previewUrlSource = "flag";
+    return;
+  }
+  const fromEnv = (process.env.PREVIEW_URL ?? "").trim();
+  if (fromEnv.length > 0) {
+    ctx.data.previewUrl = fromEnv;
+    ctx.data.previewUrlSource = "env";
+    return;
+  }
+  ctx.data.previewUrl = DEFAULT_PREVIEW_URL;
+  ctx.data.previewUrlSource = "default";
+};
+
 // src/scripts/reviewFlow.ts
 var reviewFlow = async (ctx) => {
   const prNumber = ctx.args.pr;
@@ -3990,7 +4544,7 @@ var watchStalePrsFlow = async (ctx) => {
 };
 
 // src/scripts/writeRunSummary.ts
-import * as fs16 from "fs";
+import * as fs19 from "fs";
 var writeRunSummary = async (ctx, profile) => {
   const summaryPath = process.env.GITHUB_STEP_SUMMARY;
   if (!summaryPath) return;
@@ -4012,7 +4566,7 @@ var writeRunSummary = async (ctx, profile) => {
   if (reason) lines.push(`- **Reason:** ${reason}`);
   lines.push("");
   try {
-    fs16.appendFileSync(summaryPath, `${lines.join("\n")}
+    fs19.appendFileSync(summaryPath, `${lines.join("\n")}
 `);
   } catch {
   }
@@ -4033,8 +4587,11 @@ var preflightScripts = {
   loadIssueContext,
   loadConventions,
   loadCoverageRules,
+  loadQaGuide,
   buildSyntheticPlugin,
   resolveArtifacts,
+  discoverQaContext,
+  resolvePreviewUrl,
   composePrompt,
   skipAgent
 };
@@ -4167,9 +4724,9 @@ async function runExecutable(profileName, input) {
     data: {},
     output: { exitCode: 0 }
   };
-  const ndjsonDir = path14.join(input.cwd, ".kody2");
+  const ndjsonDir = path17.join(input.cwd, ".kody2");
   const invokeAgent = async (prompt) => {
-    const externalPlugins = (profile.claudeCode.plugins ?? []).map((p) => path14.isAbsolute(p) ? p : path14.resolve(profile.dir, p)).filter((p) => p.length > 0);
+    const externalPlugins = (profile.claudeCode.plugins ?? []).map((p) => path17.isAbsolute(p) ? p : path17.resolve(profile.dir, p)).filter((p) => p.length > 0);
     const syntheticPath = ctx.data.syntheticPluginPath;
     const pluginPaths = [...externalPlugins, ...syntheticPath ? [syntheticPath] : []];
     return runAgent({
@@ -4236,17 +4793,17 @@ async function runExecutable(profileName, input) {
   }
 }
 function resolveProfilePath(profileName) {
-  const here = path14.dirname(new URL(import.meta.url).pathname);
+  const here = path17.dirname(new URL(import.meta.url).pathname);
   const candidates = [
-    path14.join(here, "executables", profileName, "profile.json"),
+    path17.join(here, "executables", profileName, "profile.json"),
     // same-dir sibling (dev)
-    path14.join(here, "..", "executables", profileName, "profile.json"),
+    path17.join(here, "..", "executables", profileName, "profile.json"),
     // up one (prod: dist/bin → dist/executables)
-    path14.join(here, "..", "src", "executables", profileName, "profile.json")
+    path17.join(here, "..", "src", "executables", profileName, "profile.json")
     // fallback
   ];
   for (const c of candidates) {
-    if (fs17.existsSync(c)) return c;
+    if (fs20.existsSync(c)) return c;
   }
   return candidates[0];
 }
@@ -4422,9 +4979,9 @@ function resolveAuthToken(env = process.env) {
   return token;
 }
 function detectPackageManager2(cwd) {
-  if (fs18.existsSync(path15.join(cwd, "pnpm-lock.yaml"))) return "pnpm";
-  if (fs18.existsSync(path15.join(cwd, "yarn.lock"))) return "yarn";
-  if (fs18.existsSync(path15.join(cwd, "bun.lockb"))) return "bun";
+  if (fs21.existsSync(path18.join(cwd, "pnpm-lock.yaml"))) return "pnpm";
+  if (fs21.existsSync(path18.join(cwd, "yarn.lock"))) return "yarn";
+  if (fs21.existsSync(path18.join(cwd, "bun.lockb"))) return "bun";
   return "npm";
 }
 function shellOut(cmd, args, cwd, stream = true) {
@@ -4504,11 +5061,11 @@ function configureGitIdentity(cwd) {
 }
 function postFailureTail(issueNumber, cwd, reason) {
   if (!issueNumber) return;
-  const logPath = path15.join(cwd, ".kody2", "last-run.jsonl");
+  const logPath = path18.join(cwd, ".kody2", "last-run.jsonl");
   let tail = "";
   try {
-    if (fs18.existsSync(logPath)) {
-      const content = fs18.readFileSync(logPath, "utf-8");
+    if (fs21.existsSync(logPath)) {
+      const content = fs21.readFileSync(logPath, "utf-8");
       tail = content.slice(-3e3);
     }
   } catch {
@@ -4533,7 +5090,7 @@ async function runCi(argv) {
     return 0;
   }
   const args = parseCiArgs(argv);
-  const cwd = args.cwd ? path15.resolve(args.cwd) : process.cwd();
+  const cwd = args.cwd ? path18.resolve(args.cwd) : process.cwd();
   let earlyConfig;
   try {
     earlyConfig = loadConfig(cwd);
@@ -4666,9 +5223,9 @@ function parseChatArgs(argv, env = process.env) {
   return result;
 }
 function commitChatFiles(cwd, sessionId, verbose) {
-  const sessionFile = path16.relative(cwd, sessionFilePath(cwd, sessionId));
-  const eventsFile = path16.relative(cwd, eventsFilePath(cwd, sessionId));
-  const paths = [sessionFile, eventsFile].filter((p) => fs19.existsSync(path16.join(cwd, p)));
+  const sessionFile = path19.relative(cwd, sessionFilePath(cwd, sessionId));
+  const eventsFile = path19.relative(cwd, eventsFilePath(cwd, sessionId));
+  const paths = [sessionFile, eventsFile].filter((p) => fs22.existsSync(path19.join(cwd, p)));
   if (paths.length === 0) return;
   const opts = { cwd, stdio: verbose ? "inherit" : "pipe" };
   try {
@@ -4706,7 +5263,7 @@ async function runChat(argv) {
 ${CHAT_HELP}`);
     return 64;
   }
-  const cwd = args.cwd ? path16.resolve(args.cwd) : process.cwd();
+  const cwd = args.cwd ? path19.resolve(args.cwd) : process.cwd();
   const sessionId = args.sessionId;
   const unpackedSecrets = unpackAllSecrets();
   if (unpackedSecrets > 0) {

package/dist/executables/ui-review/profile.json

@@ -0,0 +1,75 @@
+{
+  "name": "ui-review",
+  "describe": "UI/UX review of an open PR: browses the running preview with Playwright, compares behavior to diff intent, posts one structured review comment. Read-only on the repo (no commits); writes a throwaway Playwright spec under .kody2/.",
+  "kind": "oneshot",
+  "inputs": [
+    {
+      "name": "pr",
+      "flag": "--pr",
+      "type": "int",
+      "required": true,
+      "describe": "GitHub PR number to review."
+    },
+    {
+      "name": "previewUrl",
+      "flag": "--preview-url",
+      "type": "string",
+      "required": false,
+      "describe": "Base URL the agent should browse. Falls back to $PREVIEW_URL, then http://localhost:3000."
+    }
+  ],
+  "claudeCode": {
+    "model": "inherit",
+    "permissionMode": "acceptEdits",
+    "maxTurns": null,
+    "maxThinkingTokens": null,
+    "systemPromptAppend": null,
+    "tools": [
+      "Read",
+      "Grep",
+      "Glob",
+      "Bash",
+      "Write",
+      "Edit"
+    ],
+    "hooks": [],
+    "skills": [],
+    "commands": [],
+    "subagents": [],
+    "plugins": [],
+    "mcpServers": []
+  },
+  "cliTools": [
+    {
+      "name": "playwright",
+      "install": {
+        "required": false,
+        "checkCommand": "npx --no-install playwright --version",
+        "installCommand": "npx --yes playwright install --with-deps chromium"
+      },
+      "verify": "npx --no-install playwright --version",
+      "usage": "Use `npx playwright test <file>` to run a Playwright spec. Write ad-hoc specs under `.kody2/ui-review/*.spec.ts`. If `npx playwright test` errors with `Cannot find package '@playwright/test'`, install it once with `npm install -D @playwright/test` (or the repo's package-manager equivalent) before retrying — the `playwright` browser binaries are already set up by preflight, but the per-repo test framework may not be. Prefer `page.goto(process.env.UI_REVIEW_BASE_URL)` — the base URL is injected as `UI_REVIEW_BASE_URL` at run time. Capture screenshots with `await page.screenshot({ path: '.kody2/ui-review/<name>.png' })` and reference those paths in your final review.",
+      "allowedUses": [
+        "test",
+        "--version"
+      ]
+    }
+  ],
+  "inputArtifacts": [],
+  "outputArtifacts": [],
+  "scripts": {
+    "preflight": [
+      { "script": "reviewFlow" },
+      { "script": "loadTaskState" },
+      { "script": "loadConventions" },
+      { "script": "discoverQaContext" },
+      { "script": "loadQaGuide" },
+      { "script": "resolvePreviewUrl" },
+      { "script": "composePrompt" }
+    ],
+    "postflight": [
+      { "script": "postReviewResult" },
+      { "script": "saveTaskState" }
+    ]
+  }
+}

package/dist/executables/ui-review/prompt.md

@@ -0,0 +1,103 @@
+You are Kody, a senior UI/UX reviewer. Review PR #{{pr.number}} by reading the diff AND browsing the running app with Playwright. Post ONE structured review comment. Do NOT edit any tracked source files. Do NOT run any `git` or `gh` commands.
+
+You MAY write throwaway Playwright specs and screenshots under `.kody2/ui-review/` — that directory is ignored by the repo.
+
+# PR #{{pr.number}}: {{pr.title}}
+
+Base: {{pr.baseRefName}} ← Head: {{pr.headRefName}}
+
+{{pr.body}}
+
+# Preview URL
+
+`{{previewUrl}}` (resolved from: {{previewUrlSource}})
+
+Before you do anything else, run:
+
+```bash
+curl -sS -o /dev/null -w "%{http_code}\n" --max-time 10 {{previewUrl}}
+```
+
+If the response is not 2xx or 3xx, the preview is unreachable. In that case, SKIP browsing, note the failure in your review under "Browsing", and base your verdict on the diff alone.
+
+# QA context (auto-discovered from the repo)
+
+```
+{{qaContext}}
+```
+
+# QA guide (committed in the repo — authoritative over the auto-discovery above)
+
+{{qaGuide}}
+
+# Diff
+
+```diff
+{{prDiff}}
+```
+
+{{conventionsBlock}}
+
+{{toolsUsage}}
+
+# What to do
+
+1. **Identify UI-affecting changes.** Read the diff. Which pages / components / forms / styles did this PR change? Which user-visible behavior should be verified in the browser? If the diff has no UI surface (pure backend, pure config, pure tests), say so and produce a diff-only review — do not spin up Playwright for nothing.
+
+2. **Plan the browse session.** For each UI-affecting change, pick 1–3 routes from the QA context that exercise it. If the change requires an authenticated role, grab credentials from the QA guide above. If no credentials are available for a role the change depends on, note that as a gap and browse only public pages.
+
+3. **Write a Playwright spec.** Create exactly one file at `.kody2/ui-review/browse.spec.ts`. Use `process.env.UI_REVIEW_BASE_URL` as the base URL. For each route you plan to check, write a test that:
+   - navigates there,
+   - performs the minimum interaction to exercise the change (click, submit, fill),
+   - takes a screenshot at `.kody2/ui-review/<slug>.png`,
+   - asserts at least one piece of visible content so the test fails loudly on a blank / error page.
+
+   Include a `playwright.config.ts` at `.kody2/ui-review/playwright.config.ts` only if you need custom config; otherwise rely on defaults (headless chromium).
+
+4. **Run it.** Invoke:
+
+   ```bash
+   UI_REVIEW_BASE_URL={{previewUrl}} npx playwright test .kody2/ui-review/browse.spec.ts --reporter=line
+   ```
+
+   Capture both stdout and exit code. If Playwright is not installed, the executor will have tried to install it in preflight — if it still fails, report the install error and fall back to a diff-only review.
+
+5. **Inspect screenshots.** Use the Read tool on each `.png` under `.kody2/ui-review/` so the visual state is in your context. Note anything that looks broken, empty, misaligned, or inconsistent with the diff's intent.
+
+6. **Write the review.** Your FINAL MESSAGE must be the markdown review comment — no preamble, no DONE / COMMIT_MSG markers. The entire final message is posted verbatim to the PR.
+
+# Required output format
+
+```
+## Verdict: PASS | CONCERNS | FAIL
+
+_UI review by kody2 — browsed {{previewUrl}}_
+
+### Summary
+<2-3 sentences: what this PR changes in the UI, and whether the running app matches that intent>
+
+### What I browsed
+- `<route>` — <what was checked, with screenshot path>
+- ... (omit this section entirely if the diff had no UI surface)
+
+### UI findings
+- <bullet — cite file:line for code issues; cite route + screenshot for visual issues; say "None." if truly none>
+
+### Code findings
+- <bullets from reading the diff — correctness, a11y, performance, component structure; say "None." if none>
+
+### Gaps
+- <anything you could NOT verify (missing creds, unreachable page, preview down) and why — say "None." if you verified everything relevant>
+
+### Bottom line
+<one sentence>
+```
+
+# Rules
+
+- No commits. No `git` / `gh` invocations. No edits to files outside `.kody2/ui-review/`.
+- Verdict **FAIL** only for clear visual regressions, broken flows, or correctness/accessibility issues that block merge.
+- Verdict **CONCERNS** for clarity/polish/edge-case gaps that shouldn't block.
+- Verdict **PASS** when the PR's UI changes work as intended and nothing obvious is broken.
+- If the preview URL is unreachable, PASS/FAIL should be based on the diff alone, and the "Gaps" section must call that out.
+- Be specific: every finding gets a route + screenshot reference, or a file:line reference. No generic advice.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kody-ade/kody-engine",
-  "version": "0.2.47",
+  "version": "0.2.49",
   "description": "kody2 — autonomous development engine. Single-session Claude Code agent behind a generic executor + declarative executable profiles.",
   "license": "MIT",
   "type": "module",