@sparkerp/plugin-sdk 0.1.0

package/erp-cli/erp.mjs

@@ -0,0 +1,4065 @@
+#!/usr/bin/env node
+/**
+ * `erp` — the ERP Developer Platform CLI, per
+ * `low-code-docs/AI Native/AI_NATIVE_Developer platform.md` §8-10.
+ * See `ai/domains/ai-native-developer-platform-gap-analysis.md` for the
+ * full gap analysis; every command below is marked with its real status.
+ *
+ * Every command wraps a REAL mechanism already in this codebase (the real
+ * `/api/v1/auth/login` endpoint (and, since mcp-08, the real
+ * `/api/v1/auth/device/{code,approve,token}` device-authorization endpoints
+ * `erp login` now uses by default — see that command's own header comment),
+ * `PluginInstallationController`, spark.js's
+ * package/create/publish, the page-validator, the MCP server's schema map)
+ * — nothing here talks to a service that doesn't exist. Commands whose
+ * upstream capability is narrower than the doc's own mockup are marked
+ * [THIN] with a one-line note on the trim; nothing is marked done that
+ * isn't real.
+ *
+ * Credentials/env config: `~/.erp/config.json` — `{ envs: {name: {baseUrl}},
+ * currentEnv, sessions: {envName: {tenantId, userId, sessionToken,
+ * accessToken, expiresAt}} }`. Never printed/logged in full (see
+ * feedback-plugins-must-be-environment-portable's sibling concern — a
+ * session token is exactly the kind of environment-specific secret that
+ * must never leak into a committed plugin file).
+ */
+import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync, copyFileSync, unlinkSync, statSync, createReadStream, rmSync, chmodSync, realpathSync } from "node:fs";
+import { spawnSync, spawn } from "node:child_process";
+import path from "node:path";
+import os from "node:os";
+import http from "node:http";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import readline from "node:readline";
+import { EXAMPLE_PATTERNS } from "./example-patterns.mjs";
+import {
+  SCHEMA_REGISTRY,
+  detectMode,
+  isPackaged,
+  requireMonorepo,
+  bundleDir,
+  cacheDir,
+  schemaPathByName,
+  schemaPathByRepoRel,
+  docsSearchRoots,
+  examplesModulesRoot,
+  exampleFileAbs,
+  frozenCatalog,
+  blockEngineModuleUrl,
+  pageEngineModuleUrl,
+  blocksCatalogPath,
+  readLiveJson,
+  readManifest,
+} from "./authoring-root.mjs";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(__dirname, "..", "..");
+const CONFIG_DIR = path.join(os.homedir(), ".erp");
+const CONFIG_FILE = path.join(CONFIG_DIR, "config.json");
+
+// ---------------------------------------------------------------------------
+// Config / credential store
+// ---------------------------------------------------------------------------
+function loadConfig() {
+  if (!existsSync(CONFIG_FILE)) {
+    return { envs: { local: { baseUrl: "http://localhost:8080" } }, currentEnv: "local", sessions: {} };
+  }
+  return JSON.parse(readFileSync(CONFIG_FILE, "utf8"));
+}
+
+function saveConfig(cfg) {
+  mkdirSync(CONFIG_DIR, { recursive: true });
+  writeFileSync(CONFIG_FILE, JSON.stringify(cfg, null, 2), { mode: 0o600 });
+  // The `mode` option is a no-op if the file already existed — force it, then verify.
+  try {
+    chmodSync(CONFIG_FILE, 0o600);
+    const mode = statSync(CONFIG_FILE).mode & 0o777;
+    // Windows POSIX mode bits are not meaningful; only warn on a real Unix over-share.
+    if (process.platform !== "win32" && (mode & 0o077) !== 0) {
+      console.error(`warning: ${CONFIG_FILE} is mode ${mode.toString(8)} — expected 600 (contains access tokens). Run: chmod 600 ${CONFIG_FILE}`);
+    }
+  } catch { /* best effort */ }
+}
+
+function currentEnv(cfg) {
+  const name = cfg.currentEnv || "local";
+  const env = cfg.envs[name];
+  if (!env) throw new Error(`unknown env "${name}" — run: erp env list`);
+  return { name, ...env };
+}
+
+function currentSession(cfg) {
+  const env = currentEnv(cfg);
+  const session = cfg.sessions?.[env.name];
+  if (!session) throw new Error(`not logged in to env "${env.name}" — run: erp login`);
+  return { env, session };
+}
+
+// Real gap found + fixed 2026-09-03 (user flagged `erp login`'s UX as too
+// thin): a raw network failure (server down, wrong --base-url, DNS/refused)
+// surfaced as Node's own bare `fetch failed` with zero context — no target
+// URL, no hint of what actually went wrong. Every login/session/whoami call
+// site now routes through this so the failure at least names WHERE it tried
+// to reach and WHY (refused vs. unknown-host vs. something else), instead of
+// a caller having to re-derive it from a one-line Node error.
+async function fetchOrExplain(url, init) {
+  try {
+    return await fetch(url, init);
+  } catch (e) {
+    const cause = e?.cause?.code || e?.code || (e instanceof Error ? e.message : String(e));
+    throw new Error(`could not reach ${url} (${cause}) — is the server up? check the env's base URL with \`erp env list\`.`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// authHeaders(cfg) — the single Authorization/session header builder for every
+// networked CLI command (2026-09-10, remote plugin SDK).
+//   * ERP_TOKEN env var wins (CI path): sent verbatim as `Authorization:
+//     Bearer <ERP_TOKEN>`, no stored creds needed / consulted.
+//   * otherwise the stored `{accessToken, refreshToken/sessionToken, expiresAt}`
+//     for the current env; when the access token is within 60s of expiry it's
+//     silently refreshed via POST /api/v1/auth/device/refresh (the opaque
+//     session token is the refresh token) and the new value persisted 0600.
+// Returns {} (unauthenticated) only when neither ERP_TOKEN nor a session exists.
+// ---------------------------------------------------------------------------
+async function refreshAccessToken(cfg, envName) {
+  const env = cfg.envs[envName];
+  const session = cfg.sessions?.[envName];
+  const refreshToken = session?.refreshToken || session?.sessionToken;
+  if (!refreshToken) return null;
+  try {
+    const res = await fetch(env.baseUrl.replace(/\/$/, "") + "/api/v1/auth/device/refresh", {
+      method: "POST",
+      headers: { "Content-Type": "application/json", "X-Tenant-Id": String(session.tenantId ?? 2) },
+      body: JSON.stringify({ refreshToken }),
+    });
+    if (!res.ok) return null;
+    const json = await res.json();
+    const accessToken = json.access_token || json.accessToken;
+    if (!accessToken) return null;
+    session.accessToken = accessToken;
+    session.expiresAt = new Date(Date.now() + (json.expires_in ? json.expires_in * 1000 : 15 * 60 * 1000)).toISOString();
+    saveConfig(cfg);
+    return accessToken;
+  } catch {
+    return null;
+  }
+}
+
+async function authHeaders(cfg, { tenantIdOverride } = {}) {
+  const env = currentEnv(cfg);
+  if (process.env.ERP_TOKEN) {
+    return { "X-Tenant-Id": String(tenantIdOverride ?? 2), Authorization: `Bearer ${process.env.ERP_TOKEN}` };
+  }
+  const session = cfg.sessions?.[env.name];
+  if (!session) return { "X-Tenant-Id": String(tenantIdOverride ?? 2) };
+  const soonMs = Date.parse(session.expiresAt || 0) - Date.now();
+  if (!Number.isNaN(soonMs) && soonMs < 60_000) {
+    await refreshAccessToken(cfg, env.name);
+  }
+  return {
+    "X-Tenant-Id": String(tenantIdOverride ?? session.tenantId ?? 2),
+    "X-Actor": session.userId,
+    "X-Session-Token": session.sessionToken,
+    Authorization: `Bearer ${session.accessToken}`,
+  };
+}
+
+async function api(cfg, method, urlPath, { body, headers, requireAuth = true, tenantIdOverride } = {}) {
+  const env = currentEnv(cfg);
+  const session = requireAuth ? cfg.sessions?.[env.name] : null;
+  if (requireAuth && !session && !process.env.ERP_TOKEN) throw new Error(`not logged in to env "${env.name}" — run: erp login`);
+  const h = {
+    "Content-Type": "application/json",
+    ...(requireAuth || session || process.env.ERP_TOKEN
+      ? await authHeaders(cfg, { tenantIdOverride })
+      : { "X-Tenant-Id": String(tenantIdOverride ?? 2) }),
+    ...headers,
+  };
+  const res = await fetchOrExplain(env.baseUrl + urlPath, { method, headers: h, body: body ? JSON.stringify(body) : undefined });
+  const text = await res.text();
+  let json;
+  try {
+    json = text ? JSON.parse(text) : null;
+  } catch {
+    json = text;
+  }
+  if (!res.ok) {
+    const msg = typeof json === "object" && json?.message ? json.message : text;
+    throw new Error(`${method} ${urlPath} -> HTTP ${res.status}: ${msg}`);
+  }
+  return json;
+}
+
+function prompt(question, { hidden = false } = {}) {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    if (hidden) {
+      // Minimal masked-input read (no external dep) — good enough for a local dev CLI, not a hardened terminal UI.
+      rl._writeToOutput = () => {};
+    }
+    rl.question(question, (answer) => {
+      rl.close();
+      if (hidden) process.stdout.write("\n");
+      resolve(answer);
+    });
+  });
+}
+
+// ---------------------------------------------------------------------------
+// erp login / logout / whoami
+// [REAL, 2026-09-03 mcp-08] — default path is the real OAuth-device-
+// authorization-shaped flow: POST /api/v1/auth/device/code (unauthenticated,
+// DeviceAuthController), print the verification URL + user code, open the
+// browser, then poll POST /api/v1/auth/device/token at the server-given
+// interval until a human completes the REAL login (AuthController#login)
+// on `platform-launcher.device` and that page's own call to
+// /api/v1/auth/device/approve stamps the resulting tokens onto the pending
+// row. `--direct` keeps the original one-shot username/password call to
+// /api/v1/auth/login for anyone who prefers it (or whose account needs the
+// MFA step this device flow doesn't support either — same disclosed gap).
+// ---------------------------------------------------------------------------
+function openBrowser(url) {
+  try {
+    const plat = process.platform;
+    if (plat === "win32") spawnSync("cmd", ["/c", "start", "", url], { stdio: "ignore" });
+    else if (plat === "darwin") spawnSync("open", [url], { stdio: "ignore" });
+    else spawnSync("xdg-open", [url], { stdio: "ignore" });
+  } catch { /* best-effort only — the printed URL is the real fallback */ }
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function loginDeviceCommand(opts) {
+  const cfg = loadConfig();
+  const env = currentEnv(cfg);
+  // The device-authorization row lives under the one well-known "platform"
+  // tenant (same real tenant `platform-launcher.login`/`.device` are always
+  // reachable under pre-auth, per PlatformTenantResolutionController's own
+  // doc comment) — NOT the target tenant the user will actually land on,
+  // which is only known once AuthController#login's own real cross-tenant
+  // resolution runs inside the browser step. `--tenant` is accepted but
+  // unused here for exactly that reason (kept only so `--direct`'s flag
+  // shape stays familiar); the real destination tenant comes back from the
+  // server's own approved-token response.
+  const platformTenant = await fetchOrExplain(env.baseUrl + "/api/v1/platform-tenant").then((r) => r.json());
+  const tenantId = String(platformTenant.tenantId);
+  const codeRes = await fetchOrExplain(env.baseUrl + "/api/v1/auth/device/code", {
+    method: "POST",
+    headers: { "Content-Type": "application/json", "X-Tenant-Id": tenantId },
+  });
+  const code = await codeRes.json();
+  if (!codeRes.ok) throw new Error(`device/code failed: HTTP ${codeRes.status}: ${JSON.stringify(code)}`);
+
+  console.log(`\nTo authorize this CLI, open:\n\n  ${code.verificationUriComplete}\n`);
+  console.log(`(or go to ${code.verificationUri} and enter code: ${code.userCode})\n`);
+  console.log(`Waiting for you to sign in and approve in the browser...`);
+  if (!opts.noBrowser) openBrowser(code.verificationUriComplete);
+
+  let intervalMs = Math.max(code.interval || 5, 2) * 1000;
+  const deadline = Date.now() + (code.expiresIn || 600) * 1000;
+  while (Date.now() < deadline) {
+    await sleep(intervalMs);
+    const pollRes = await fetchOrExplain(env.baseUrl + "/api/v1/auth/device/token", {
+      method: "POST",
+      headers: { "Content-Type": "application/json", "X-Tenant-Id": tenantId },
+      body: JSON.stringify({ deviceCode: code.deviceCode }),
+    });
+    const poll = await pollRes.json();
+    if (!pollRes.ok) throw new Error(`device/token failed: HTTP ${pollRes.status}: ${JSON.stringify(poll)}`);
+    if (poll.status === "approved") {
+      cfg.sessions = cfg.sessions || {};
+      cfg.sessions[env.name] = {
+        tenantId: poll.tenantId ?? Number(tenantId),
+        userId: poll.userId,
+        sessionToken: poll.sessionToken,
+        refreshToken: poll.refresh_token ?? poll.sessionToken,
+        accessToken: poll.access_token ?? poll.accessToken,
+        expiresAt: poll.expiresAt,
+      };
+      saveConfig(cfg);
+      const mode = (statSync(CONFIG_FILE).mode & 0o777).toString(8);
+      console.log(`\nLogged in to ${env.name} (${env.baseUrl}) as ${poll.userId} on tenant ${poll.tenantId} — session expires ${poll.expiresAt}.`);
+      console.log(`Credentials stored in ${CONFIG_FILE} (mode ${mode}).`);
+      return;
+    }
+    if (poll.status === "denied" || poll.error === "access_denied") throw new Error("authorization was denied.");
+    if (poll.status === "expired" || poll.error === "expired_token") throw new Error("the device code expired before it was approved — run `erp login` again.");
+    if (poll.error === "slow_down") intervalMs += 5000; // RFC 8628 §3.5
+    // "authorization_pending" — keep polling.
+  }
+  throw new Error("timed out waiting for browser approval — run `erp login` again.");
+}
+
+async function loginDirectCommand(opts) {
+  const cfg = loadConfig();
+  const env = currentEnv(cfg);
+  const tenantId = opts.tenant || (await prompt(`Tenant id [2]: `)) || "2";
+  const userId = opts.user || (await prompt("User id / email: "));
+  const password = opts.password || (await prompt("Password: ", { hidden: true }));
+  const res = await fetchOrExplain(env.baseUrl + "/api/v1/auth/login", {
+    method: "POST",
+    headers: { "Content-Type": "application/json", "X-Tenant-Id": String(tenantId) },
+    body: JSON.stringify({ userId, password, sourceApp: "erp-cli" }),
+  });
+  const json = await res.json();
+  if (!res.ok) {
+    // Real gap found + fixed 2026-09-03: this used to throw the server's raw
+    // message verbatim with no interpretation — a wrong tenant id (a real,
+    // easy-to-make mistake, e.g. `--tenant 999999`) came back as a bare
+    // `HTTP 500: Failed to obtain JDBC Connection`, which reads like an
+    // infra outage, not "that tenant doesn't exist". The underlying 500 is a
+    // genuine, separate backend gap (SchemaScopedDataSource leaking a raw
+    // JDBC error instead of a clean 404/400 for an unresolvable tenant
+    // schema — out of scope to fix here, a platform-runtime change) but the
+    // CLI can at least stop presenting it as an unexplained crash.
+    const serverMsg = json?.message ?? JSON.stringify(json);
+    const hint =
+      res.status === 500 && /JDBC Connection|Connection.*refused|schema/i.test(String(serverMsg))
+        ? ` (tenant ${tenantId} may not exist on this server — check the id and try again)`
+        : "";
+    throw new Error(`login failed: HTTP ${res.status}: ${serverMsg}${hint}`);
+  }
+  if (json.mfaRequired) throw new Error("this account requires MFA — `erp login` does not yet support the MFA challenge step (disclosed gap, not silently ignored).");
+  cfg.sessions = cfg.sessions || {};
+  cfg.sessions[env.name] = {
+    tenantId: json.tenantId ?? Number(tenantId),
+    userId: json.userId,
+    sessionToken: json.sessionToken,
+    accessToken: json.accessToken,
+    expiresAt: json.expiresAt,
+  };
+  saveConfig(cfg);
+  console.log(`Logged in to ${env.name} (${env.baseUrl}) as ${json.userId} on tenant ${json.tenantId} — session expires ${json.expiresAt}.`);
+}
+
+async function loginCommand(opts) {
+  if (opts.direct) return loginDirectCommand(opts);
+  return loginDeviceCommand(opts);
+}
+
+async function logoutCommand() {
+  const cfg = loadConfig();
+  const env = currentEnv(cfg);
+  const session = cfg.sessions?.[env.name];
+  if (session) {
+    try {
+      await fetch(env.baseUrl + "/api/v1/auth/logout", {
+        method: "DELETE",
+        headers: { "X-Tenant-Id": String(session.tenantId), "X-Session-Token": session.sessionToken },
+      });
+    } catch { /* server may already be down/unreachable — still clear local credentials */ }
+    delete cfg.sessions[env.name];
+  }
+  saveConfig(cfg);
+  console.log(`Logged out of ${env.name}.`);
+}
+
+async function whoamiCommand(opts) {
+  const cfg = loadConfig();
+  const { env, session } = currentSession(cfg);
+  const res = await api(cfg, "GET", "/api/v1/auth/session", { tenantIdOverride: opts.tenant });
+  // Real gap found + fixed 2026-09-03 (user flagged `erp login`'s thinness):
+  // GET /api/v1/auth/session itself returns no expiry field at all — `res`
+  // never carried one, so `whoami` had no way to tell you your session was
+  // about to lapse (or already had) short of it failing outright on the
+  // NEXT command. The CLI already stores `expiresAt` locally from the
+  // original login response (~/.erp/config.json) — surfaced here instead of
+  // left unused.
+  const expiresAt = session.expiresAt ? new Date(session.expiresAt) : null;
+  const expiryStatus = expiresAt
+    ? expiresAt.getTime() < Date.now()
+      ? `EXPIRED ${Math.round((Date.now() - expiresAt.getTime()) / 60000)}m ago — run \`erp login\` again`
+      : `valid for ~${Math.round((expiresAt.getTime() - Date.now()) / 60000)}m more`
+    : "unknown (no expiresAt on record — a device-flow or older session)";
+  console.log(
+    JSON.stringify(
+      {
+        env: env.name,
+        baseUrl: env.baseUrl,
+        tenantId: opts.tenant ? Number(opts.tenant) : session.tenantId,
+        ...res,
+        localSessionExpiresAt: session.expiresAt ?? null,
+        localSessionStatus: expiryStatus,
+      },
+      null,
+      2,
+    ),
+  );
+}
+
+// ---------------------------------------------------------------------------
+// erp api get/post — [REAL, added 2026-09-04] a real gap found and fixed:
+// after deploying a plugin, verifying what actually landed (an entity's real
+// records, a live menu's real nodes, a workflow instance's real state) had
+// no CLI path at all — every prior verification pass in this session had to
+// fall back to hand-written curl with manually-typed X-Tenant-Id/X-Actor
+// headers, which is exactly the kind of guessing (wrong endpoint shapes,
+// wrong header names) the SDK/CLI-only discovery rule exists to prevent.
+// This reuses the SAME authenticated `api()` helper every other command
+// already uses (session tenant/actor/bearer from `erp login`, not
+// hand-typed), so a verification call is indistinguishable in trust from
+// any other real CLI call. Deliberately generic (method + path + optional
+// body) rather than one bespoke subcommand per resource type — an entity's
+// `/api/v1/entities/<name>/records`, an artifact list's
+// `/api/v1/authoring/<kind>`, a specific artifact's `/api/v1/authoring/<kind>/<id>`,
+// a Data Service's `/api/v1/data-services/<name>/execute` are all just paths.
+// ---------------------------------------------------------------------------
+async function apiCallCommand(method, urlPath, opts) {
+  if (!urlPath) throw new Error(`usage: erp api ${method.toLowerCase()} <path> [--tenant <id>] [--body <json-string-or-@file>]`);
+  const cfg = loadConfig();
+  currentSession(cfg); // throws a clear "not logged in" error early if there's no session yet
+  let body;
+  if (opts.body) {
+    const raw = opts.body.startsWith("@") ? readFileSync(opts.body.slice(1), "utf8") : opts.body;
+    body = JSON.parse(raw);
+  }
+  const result = await api(cfg, method, urlPath, { body, tenantIdOverride: opts.tenant });
+  console.log(JSON.stringify(result, null, 2));
+}
+
+// ---------------------------------------------------------------------------
+// erp logs tail — [REAL, added 2026-09-04] a real gap found and fixed:
+// engine-api logged to console ONLY (see application.yml's own `logging`
+// section, edited alongside this) — whatever stack trace explained a real
+// 500 existed nowhere durable/queryable once that terminal scrolled past.
+// Neither a developer nor an AI driving purely through the SDK/CLI/MCP had
+// ANY way to see server-side error detail beyond whatever text happened to
+// land in the HTTP response body — exactly the failure mode that led to
+// misdiagnosing a real BadSqlGrammarException as a missing-column error
+// during HCM Talent Batch 1 (see ai/domains/hcm-talent-management.md) before
+// actually reading the engine source to find the real cause. Every real API
+// response now carries a real `X-Correlation-Id` response header
+// (CorrelationIdFilter, engine-api) that matches the log's own `[cid=...]`
+// token on every line for that request — the join key this command exists
+// to search on: call an endpoint, note the correlationId, `erp logs tail
+// --grep <correlationId>` to see the exact request's real server-side trace.
+// Default log path is this repo's own dev convention (relative
+// `logs/engine-api.log` under erp-suite's own working directory when run
+// via `mvn spring-boot:run`) — `--file` overrides for any other environment.
+// ---------------------------------------------------------------------------
+function logsTailCommand(opts) {
+  requireMonorepo("erp logs tail");
+  const logPath = opts.file
+    ? path.resolve(opts.file)
+    : path.join(REPO_ROOT, "backend/platform-runtime/erp-suite/logs/engine-api.log");
+  if (!existsSync(logPath)) {
+    throw new Error(
+      `no log file at ${path.relative(REPO_ROOT, logPath)} — engine-api needs \`logging.file.name\` set (already is, in application.yml) ` +
+        `and must have been restarted since; pass --file <path> if your log lives elsewhere.`,
+    );
+  }
+  const lines = Number(opts.lines || 200);
+  const printMatching = (allLines) => {
+    let matched = allLines;
+    if (opts.grep) {
+      const needle = opts.grep;
+      matched = matched.filter((l) => l.includes(needle));
+    }
+    if (matched.length === 0) {
+      console.log(opts.grep ? `(no log lines matched "${opts.grep}")` : "(log file is empty)");
+      return;
+    }
+    console.log(matched.slice(-lines).join("\n"));
+  };
+  if (!opts.follow) {
+    printMatching(readFileSync(logPath, "utf8").split("\n"));
+    return;
+  }
+  console.log(`(following ${path.relative(REPO_ROOT, logPath)}${opts.grep ? ` for "${opts.grep}"` : ""} — Ctrl+C to stop)\n`);
+  printMatching(readFileSync(logPath, "utf8").split("\n"));
+  let lastSize = statSync(logPath).size;
+  return new Promise((resolve) => {
+    const interval = setInterval(() => {
+      let stat;
+      try {
+        stat = statSync(logPath);
+      } catch {
+        return;
+      }
+      if (stat.size > lastSize) {
+        const stream = createReadStream(logPath, { start: lastSize, end: stat.size });
+        let buf = "";
+        stream.on("data", (chunk) => (buf += chunk));
+        stream.on("end", () => {
+          const newLines = buf.split("\n").filter(Boolean);
+          const toPrint = opts.grep ? newLines.filter((l) => l.includes(opts.grep)) : newLines;
+          if (toPrint.length) console.log(toPrint.join("\n"));
+        });
+        lastSize = stat.size;
+      } else if (stat.size < lastSize) {
+        lastSize = 0; // log rotated/truncated underneath us — resync from the start next tick
+      }
+    }, 1000);
+    process.on("SIGINT", () => {
+      clearInterval(interval);
+      resolve();
+      process.exit(0);
+    });
+  });
+}
+
+// ---------------------------------------------------------------------------
+// erp org list / erp env list / erp env use
+// [THIN] — this platform has no ERP-Cloud-style multi-org directory above
+// tenant (tenant IS the top-level org boundary here, confirmed via source
+// read); `org list` reports the current session's own tenant rather than
+// a cross-tenant directory (that would be a platform-admin operation, out
+// of scope for a developer CLI). `env`/`env use` ARE fully real — a local
+// named base-URL profile switch, useful today (e.g. local vs a staging
+// engine-api).
+// ---------------------------------------------------------------------------
+async function orgListCommand(opts) {
+  const cfg = loadConfig();
+  const { env, session } = currentSession(cfg);
+  console.log(`[THIN — see erp.mjs header] This platform has no multi-org directory above tenant; reporting the current session's tenant only.`);
+  console.log(JSON.stringify({ env: env.name, tenantId: opts.tenant ? Number(opts.tenant) : session.tenantId }, null, 2));
+}
+
+function envListCommand() {
+  const cfg = loadConfig();
+  for (const [name, e] of Object.entries(cfg.envs)) {
+    console.log(`${name === cfg.currentEnv ? "*" : " "} ${name}  ${e.baseUrl}${cfg.sessions?.[name] ? "  (logged in)" : ""}`);
+  }
+}
+
+function envUseCommand(name, opts) {
+  const cfg = loadConfig();
+  if (opts.baseUrl || !cfg.envs[name]) {
+    cfg.envs[name] = { baseUrl: opts.baseUrl || cfg.envs[name]?.baseUrl || "http://localhost:8080" };
+  }
+  cfg.currentEnv = name;
+  saveConfig(cfg);
+  console.log(`Switched to env "${name}" (${cfg.envs[name].baseUrl}).`);
+}
+
+// ---------------------------------------------------------------------------
+// erp plugin list / search / install / pull / diff
+// [REAL] list/install — GET/POST /api/v1/authoring/plugins
+// (PluginInstallationController), the actual manifest-row install path —
+// this is INSTALLED-on-this-tenant state, a different bounded context from
+// the registry below (per PackageManifestController's own doc comment).
+// [REAL, 2026-09-03] search — now queries the REAL hosted registry first
+// (`GET /api/v1/marketplace/packages?packageType=plugin`,
+// engine-marketplace's PackageManifestController — a genuine catalog of
+// registered/published packages, distinct from install state), falling
+// back to / also including the local-repo-scoped substring match over
+// `backend/modules/*/spk-assembly/plugin.json` (still useful for plugins
+// that exist on disk but were never registered in the catalog).
+// [THIN] pull — reconstructs manifest+config+version state (everything
+// PluginInstallationController's GET actually returns) into a local file;
+// does NOT reconstruct the full spk-assembly page/workflow/entity source
+// tree (those live in per-artifact authoring controllers with different
+// shapes each — a genuinely separate, larger integration per artifact type,
+// disclosed as future work, not attempted here to avoid a half-correct
+// reconstruction). If the plugin is ALSO a registered registry package,
+// `erp registry get` (below) returns richer metadata (description,
+// license, dependencies, changelog) than the bare install-state row.
+// ---------------------------------------------------------------------------
+async function pluginListCommand(opts) {
+  const cfg = loadConfig();
+  const list = await api(cfg, "GET", "/api/v1/authoring/plugins", { tenantIdOverride: opts.tenant });
+  console.log(JSON.stringify(list, null, 2));
+}
+
+async function pluginSearchCommand(term, opts) {
+  const cfg = loadConfig();
+  let registryHits = [];
+  try {
+    const catalog = await api(cfg, "GET", "/api/v1/marketplace/packages?packageType=plugin", { requireAuth: false, tenantIdOverride: opts.tenant });
+    registryHits = catalog.filter(
+      (p) => p.packageId.toLowerCase().includes(term.toLowerCase()) || (p.name || "").toLowerCase().includes(term.toLowerCase())
+    );
+  } catch (e) {
+    console.log(`(registry search unavailable: ${e.message})`);
+  }
+  console.log(`Registry (hosted, published) — ${registryHits.length} match(es):`);
+  console.log(JSON.stringify(registryHits.map((p) => ({ packageId: p.packageId, version: p.version, name: p.name, author: p.authorName, license: p.license })), null, 2));
+
+  const modulesDir = path.join(REPO_ROOT, "backend", "modules");
+  const localHits = [];
+  for (const dir of readdirSync(modulesDir, { withFileTypes: true }).filter((d) => d.isDirectory())) {
+    const manifestPath = path.join(modulesDir, dir.name, "spk-assembly", "plugin.json");
+    if (!existsSync(manifestPath)) continue;
+    const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+    if (dir.name.toLowerCase().includes(term.toLowerCase()) || (manifest.name || "").toLowerCase().includes(term.toLowerCase())) {
+      localHits.push({ id: manifest.id || dir.name, name: manifest.name, version: manifest.version, dir: dir.name });
+    }
+  }
+  console.log(`\nLocal repo (on disk, not necessarily registered) — ${localHits.length} match(es):`);
+  console.log(JSON.stringify(localHits, null, 2));
+}
+
+// ---------------------------------------------------------------------------
+// erp registry list / mine / get / publish
+// [REAL] — the genuine hosted registry (engine-marketplace's
+// PackageManifestController, `/api/v1/marketplace/packages`) — a real
+// catalog distinct from PluginInstallationController's install-state.
+// `publish` does register+publish in one call (two real API calls under
+// the hood: POST to draft, then POST .../publish). Package TYPES this
+// endpoint actually knows how to auto-INSTALL are narrower than the
+// catalog itself (only "theme"/"template-pack" today, per that
+// controller's own doc comment — a "plugin"-type package is catalog
+// metadata only; the real .spk binary still installs through
+// `erp plugin install`/`spark publish`, a deliberately separate mechanism
+// this pass does not merge).
+// ---------------------------------------------------------------------------
+async function registryListCommand(opts) {
+  const cfg = loadConfig();
+  const qs = opts.type ? `?packageType=${encodeURIComponent(opts.type)}` : "";
+  const list = await api(cfg, "GET", `/api/v1/marketplace/packages${qs}`, { requireAuth: false, tenantIdOverride: opts.tenant });
+  console.log(JSON.stringify(list, null, 2));
+}
+
+async function registryMineCommand(opts) {
+  const cfg = loadConfig();
+  const qs = opts.type ? `?packageType=${encodeURIComponent(opts.type)}` : "";
+  const list = await api(cfg, "GET", `/api/v1/marketplace/packages/mine${qs}`, { tenantIdOverride: opts.tenant });
+  console.log(JSON.stringify(list, null, 2));
+}
+
+async function registryGetCommand(packageId, version, opts) {
+  const cfg = loadConfig();
+  const row = await api(cfg, "GET", `/api/v1/marketplace/packages/${encodeURIComponent(packageId)}/${encodeURIComponent(version)}`, { requireAuth: false, tenantIdOverride: opts.tenant });
+  console.log(JSON.stringify(row, null, 2));
+}
+
+async function registryPublishCommand(packageId, version, opts) {
+  const cfg = loadConfig();
+  const body = {
+    packageId,
+    version,
+    packageType: opts.type || "plugin",
+    name: opts.name || packageId,
+    erpVersion: opts.erpVersion || "*",
+    authorName: opts.author || "unknown",
+    authorEmail: opts.authorEmail || null,
+    license: opts.license || "Proprietary",
+    description: opts.description || "",
+    dependencies: [],
+    payloadJson: opts.payloadFile ? readFileSync(opts.payloadFile, "utf8") : "{}",
+    screenshots: [],
+    changelog: opts.changelog || "",
+    pricingJson: "{}",
+    supportedCountries: [],
+    supportedIndustries: [],
+  };
+  const draft = await api(cfg, "POST", "/api/v1/marketplace/packages", { body, tenantIdOverride: opts.tenant });
+  console.log(`Registered draft: ${draft.packageId}@${draft.version} (status: ${draft.status})`);
+  const published = await api(cfg, "POST", `/api/v1/marketplace/packages/${encodeURIComponent(packageId)}/${encodeURIComponent(version)}/publish`, { tenantIdOverride: opts.tenant });
+  console.log(`Published: ${published.packageId}@${published.version} (status: ${published.status})`);
+}
+
+/**
+ * mcp-15 (2026-09-03) — `POST /api/v1/marketplace/packages/{id}/{version}/install`
+ * (`PackageManifestController#install`), real for `template-pack`/`theme`/
+ * `plugin` package types. For `plugin`, the package's own `payloadJson` must
+ * carry `{"spkFileId": <id>}` — a real DMS fileId (`erp registry publish
+ * --payload-file` with a JSON file containing that field, the id returned by
+ * a prior `POST /api/v1/files` upload of the real `.spk` bytes) — never the
+ * raw `.spk` bytes inlined into the payload itself. The server resolves that
+ * file, verifies it, and installs through the EXACT SAME pipeline the real
+ * `erp plugin publish`/multipart-upload path uses — this command does not
+ * reimplement any install logic itself, only the two real HTTP calls.
+ */
+async function registryInstallCommand(packageId, version, opts) {
+  const cfg = loadConfig();
+  const installed = await api(cfg, "POST", `/api/v1/marketplace/packages/${encodeURIComponent(packageId)}/${encodeURIComponent(version)}/install`, { tenantIdOverride: opts.tenant });
+  console.log(JSON.stringify(installed, null, 2));
+}
+
+async function pluginInstallCommand(pluginId, opts) {
+  const cfg = loadConfig();
+  const manifestPath = opts.manifest || path.join(REPO_ROOT, "backend/modules", pluginId, "spk-assembly/plugin.json");
+  const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+  const res = await api(cfg, "POST", "/api/v1/authoring/plugins", {
+    body: { pluginId: manifest.id || pluginId, version: manifest.version, manifestJson: JSON.stringify(manifest), configJson: "{}", grantedCapabilitiesJson: "[]" },
+    tenantIdOverride: opts.tenant,
+  });
+  console.log(JSON.stringify(res, null, 2));
+}
+
+async function pluginPullCommand(pluginId, opts) {
+  const cfg = loadConfig();
+  const list = await api(cfg, "GET", "/api/v1/authoring/plugins", { tenantIdOverride: opts.tenant });
+  const found = list.find((p) => p.pluginId === pluginId);
+  if (!found) throw new Error(`no installed plugin "${pluginId}" on this tenant — run: erp plugin list`);
+  const outDir = opts.out || path.join(process.cwd(), pluginId);
+  mkdirSync(outDir, { recursive: true });
+  writeFileSync(path.join(outDir, "plugin.json"), found.manifestJson, "utf8");
+  writeFileSync(path.join(outDir, "config.json"), found.configJson || "{}", "utf8");
+  writeFileSync(path.join(outDir, "installation-state.json"), JSON.stringify(found, null, 2), "utf8");
+  console.log(`[THIN — manifest+config+state only, see erp.mjs header] Wrote ${outDir}/{plugin.json,config.json,installation-state.json}`);
+}
+
+async function pluginDiffCommand(pluginId, opts) {
+  const cfg = loadConfig();
+  const list = await api(cfg, "GET", "/api/v1/authoring/plugins", { tenantIdOverride: opts.tenant });
+  const installed = list.find((p) => p.pluginId === pluginId);
+  const localManifestPath = path.join(REPO_ROOT, "backend/modules", pluginId, "spk-assembly/plugin.json");
+  if (!existsSync(localManifestPath)) throw new Error(`no local plugin at backend/modules/${pluginId}/spk-assembly/plugin.json`);
+  const local = JSON.parse(readFileSync(localManifestPath, "utf8"));
+  console.log(JSON.stringify({
+    pluginId,
+    installedVersion: installed?.version ?? "(not installed)",
+    localVersion: local.version,
+    upToDate: installed?.version === local.version,
+  }, null, 2));
+}
+
+// ---------------------------------------------------------------------------
+// erp spec generate — (2026-09-03, hcm-learning Batch 2)
+// [REAL] — introspects a plugin's REAL on-disk metadata (plugin.json roles,
+// spk-assembly/metadata/{entities,rules,page,provider,menu,workflow}/*.json)
+// and emits a starter architecture/spec markdown document: entity/field
+// list, rule trigger/condition/action summary, page/route list, permission
+// list, a "real vs disclosed-deferred" placeholder section left for a human
+// (or an agent) to fill in. This does NOT replace the human-curated
+// narrative quality of ai/domains/*.md — the deferred/trimmed/disclosed-gap
+// reasoning still needs a person or an agent to write — it only auto-derives
+// the mechanically-derivable inventory part so a developer starts from real
+// data instead of a blank page. Reads local files only (same convention as
+// `erp plugin diff`'s backend/modules/<id>/spk-assembly lookup) — no network
+// call, so it works against a plugin that has never been installed anywhere.
+// ---------------------------------------------------------------------------
+function specGenerateCommand(pluginId, opts) {
+  if (!pluginId) throw new Error("usage: erp spec generate <plugin-id> [--out <file>]");
+  const base = path.join(REPO_ROOT, "backend/modules", pluginId, "spk-assembly");
+  const manifestPath = path.join(base, "plugin.json");
+  if (!existsSync(manifestPath)) throw new Error(`no local plugin at backend/modules/${pluginId}/spk-assembly/plugin.json`);
+  const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+
+  const readDirJson = (sub) => {
+    const dir = path.join(base, "metadata", sub);
+    if (!existsSync(dir)) return [];
+    return readdirSync(dir).filter((f) => f.endsWith(".json")).map((f) => {
+      try { return { file: f, json: JSON.parse(readFileSync(path.join(dir, f), "utf8")) }; }
+      catch (e) { return { file: f, error: e.message }; }
+    });
+  };
+
+  const entities = readDirJson("entities");
+  const rules = readDirJson("rules");
+  const pages = readDirJson("page");
+  const providers = readDirJson("provider");
+  const menus = readDirJson("menu");
+  const workflows = readDirJson("workflow");
+
+  const lines = [];
+  const push = (s = "") => lines.push(s);
+
+  push(`# ${manifest.name || pluginId} — generated spec inventory`);
+  push();
+  push(`Plugin id: \`${pluginId}\` · version: \`${manifest.version}\` · generated by \`erp spec generate ${pluginId}\` on ${new Date().toISOString()}.`);
+  push();
+  push("This is a MECHANICALLY-DERIVED inventory of this plugin's real, on-disk metadata — entities, rules, pages, providers, permissions, menu contributions. It is a starting point, not a finished architecture doc: the \"real vs disclosed-deferred\" reasoning, scope trims, and platform-bug history a hand-curated `ai/domains/*.md` doc carries still need a person (or an agent) to add below.");
+  push();
+
+  push("## Entities");
+  push();
+  if (entities.length === 0) push("_(none found under metadata/entities/)_");
+  for (const { file, json, error } of entities) {
+    if (error) { push(`### ${file} — **parse error**: ${error}`); continue; }
+    const e = json.entity || {};
+    push(`### \`${e.name || file}\``);
+    push(`- table: \`${e.tableName || "?"}\` · label: ${e.label || "?"} · soft-delete: ${e.softDeleteEnabled ?? "?"}`);
+    if (e.description) push(`- ${e.description}`);
+    push("");
+    push("| field | type | required | notes |");
+    push("|---|---|---|---|");
+    for (const f of json.fields || []) {
+      const notes = [f.isUnique && "unique", f.isIndexed && "indexed", f.isReadOnly && "read-only", f.isDisplayField && "display-field"].filter(Boolean).join(", ");
+      push(`| ${f.fieldName} | ${f.dataType}${f.typeParams ? ` (${f.typeParams})` : ""} | ${f.required ? "yes" : "no"} | ${notes} |`);
+    }
+    push();
+  }
+
+  push("## Rules");
+  push();
+  if (rules.length === 0) push("_(none found under metadata/rules/)_");
+  push("| name | entity | trigger | priority | summary |");
+  push("|---|---|---|---|---|");
+  for (const { file, json, error } of rules) {
+    if (error) { push(`| ${file} | | | | **parse error**: ${error} |`); continue; }
+    let actionSummary = "?";
+    try {
+      const actions = typeof json.actions === "string" ? JSON.parse(json.actions) : json.actions;
+      actionSummary = (actions || []).map((a) => a.type + (a.field ? `(${a.field})` : "")).join(", ");
+    } catch { /* leave as ? */ }
+    push(`| ${json.name || file} | ${json.entityType || "?"} | ${json.triggerEvent || "?"} | ${json.priority ?? "?"} | ${actionSummary} |`);
+  }
+  push();
+
+  push("## Pages");
+  push();
+  if (pages.length === 0) push("_(none found under metadata/page/)_");
+  for (const { file, json, error } of pages) {
+    if (error) { push(`- ${file} — **parse error**: ${error}`); continue; }
+    const def = json.definition || {};
+    const variants = (def.variants || []).map((v) => v.rule?.deviceClass).filter(Boolean);
+    push(`- **${json.name || file}** — route \`${def.route?.pattern || "?"}\`, id \`${def.id || "?"}\`, deviceClass variants: ${variants.length ? variants.join(", ") : "(desktop only)"}`);
+    if (json.metadata?.entityDefinition) push(`  - entity: \`${json.metadata.entityDefinition}\`, records: \`${json.metadata.recordsBasePath || "?"}\``);
+  }
+  push();
+
+  push("## Providers");
+  push();
+  if (providers.length === 0) push("_(none found under metadata/provider/)_");
+  for (const { file, json, error } of providers) {
+    if (error) { push(`- ${file} — **parse error**: ${error}`); continue; }
+    push(`- **${json.name || file}** — ${json.definition?.kind || "?"} \`${json.definition?.basePath || "?"}\` (${(json.definition?.supports || []).join(", ")})`);
+  }
+  push();
+
+  if (workflows.length) {
+    push("## Workflows");
+    push();
+    for (const { file, json, error } of workflows) {
+      push(error ? `- ${file} — **parse error**: ${error}` : `- **${json.name || file}**`);
+    }
+    push();
+  }
+
+  push("## Permissions (from plugin.json roles[])");
+  push();
+  if (!manifest.roles || manifest.roles.length === 0) push("_(no roles declared)_");
+  for (const role of manifest.roles || []) {
+    push(`### ${role.name} (\`${role.code}\`)`);
+    if (role.description) push(role.description);
+    push();
+    for (const key of role.permissionKeys || []) push(`- \`${key}\``);
+    push();
+  }
+
+  push("## Menu contributions");
+  push();
+  if (menus.length === 0) push("_(none found under metadata/menu/)_");
+  for (const { file, json, error } of menus) {
+    if (error) { push(`- ${file} — **parse error**: ${error}`); continue; }
+    const flatten = (nodes, depth = 0) => {
+      for (const n of nodes || []) {
+        const enabled = n.visibility?.enabled ? "enabled" : "disabled";
+        push(`${"  ".repeat(depth)}- ${n.displayName || n.id} (${enabled}${n.navigation?.route ? `, route: ${n.navigation.route}` : ""})`);
+        flatten(n.children, depth + 1);
+      }
+    };
+    flatten(json.definition?.nodes);
+  }
+  push();
+
+  push("## Real vs disclosed-deferred (fill in before treating this as a finished spec)");
+  push();
+  push("_This section is intentionally left for a human or an agent to complete — which of the above is fully real end-to-end (verified via curl/Playwright), which is a scope trim, and why. `erp spec generate` cannot derive this part; see `ai/domains/*.md` for the hand-curated convention this repo uses._");
+  push();
+
+  const output = lines.join("\n");
+  if (opts.out) {
+    writeFileSync(opts.out, output, "utf8");
+    console.log(`wrote ${opts.out} (${entities.length} entities, ${rules.length} rules, ${pages.length} pages, ${providers.length} providers, ${(manifest.roles || []).length} roles)`);
+  } else {
+    console.log(output);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// erp platform catalog — [REAL, added 2026-09-04] the fix for a real,
+// demonstrated tooling gap: `erp docs search` (and the MCP `erp_search_docs`
+// tool) only ever grepped hand-written `ai/domains/*.md` narrative docs, with
+// no mechanism to check a claim against the actual platform-runtime source.
+// This let a false "no report-builder infrastructure exists anywhere in this
+// codebase" claim propagate unverified across five separate module docs, even
+// though a real, working report-definition/execution engine
+// (ReportDefinitionService/BiReportDefinitionService, engine-form +
+// engine-entity, backed by V33__report_definition.sql/V86__bi_report_definition.sql)
+// existed the whole time — see ai/domains/*.md's own corrected lines.
+//
+// This is `erp spec generate`'s own mechanical-extraction idea (grep/parse
+// on-disk metadata, don't hand-maintain an inventory), just scoped to the
+// CORE `backend/platform-runtime/engine-*` modules instead of a plugin's
+// spk-assembly. It is a lightweight static/regex scan, not a real Java AST
+// parser (same disclosed-heuristic posture as `lintPageSemantics` below) —
+// good enough to answer "does a class/table/endpoint like this exist", not a
+// full call-graph/type-checker.
+//
+// Cached at ai/platform/engine-capability-catalog.json (regenerate with
+// `--refresh`) since a live full-repo regex scan of every engine-* module on
+// every `docs search` call would be slow — `erp platform catalog --refresh`
+// is deliberately cheap (a few hundred ms) so this cache has no excuse to go
+// stale the way the hand-written docs did.
+// ---------------------------------------------------------------------------
+const ENGINE_CATALOG_CACHE = path.join(REPO_ROOT, "ai/platform/engine-capability-catalog.json");
+const PLATFORM_RUNTIME_ROOT = path.join(REPO_ROOT, "backend/platform-runtime");
+
+function walkFilesFiltered(dir, matchFn, excludeDirNames = new Set(["target", "node_modules", ".git"])) {
+  const out = [];
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return out;
+  }
+  for (const e of entries) {
+    if (e.isDirectory()) {
+      if (excludeDirNames.has(e.name)) continue;
+      out.push(...walkFilesFiltered(path.join(dir, e.name), matchFn, excludeDirNames));
+    } else if (matchFn(e.name)) {
+      out.push(path.join(dir, e.name));
+    }
+  }
+  return out;
+}
+
+// Split a CamelCase/snake_case identifier into lowercase word tokens, e.g.
+// "BiReportDefinitionService" -> ["bi","report","definition","service"],
+// "bi_report_definition" -> ["bi","report","definition"]. Tokens <4 chars are
+// dropped (too many false-positive overlaps otherwise — "id", "get", "api").
+function tokenize(identifier) {
+  return identifier
+    .replace(/[_.]/g, " ")
+    .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+    .replace(/([A-Z]+)([A-Z][a-z])/g, "$1 $2")
+    .toLowerCase()
+    .split(/\s+/)
+    .filter((t) => t.length >= 4);
+}
+
+function extractJavaCapabilities(javaFiles) {
+  const classes = []; // {name, kind, file}
+  const controllerPaths = []; // {path, file}
+  const classDeclRe = /^\s*(?:@\w+(?:\([^)]*\))?\s*)*public\s+(?:abstract\s+|final\s+|static\s+)*(class|interface|enum|record)\s+(\w+)/gm;
+  const mappingRe = /@(?:RequestMapping|GetMapping|PostMapping|PutMapping|DeleteMapping|PatchMapping)\s*\(\s*(?:value\s*=\s*)?"([^"]*)"/g;
+  for (const file of javaFiles) {
+    let text;
+    try { text = readFileSync(file, "utf8"); } catch { continue; }
+    const rel = path.relative(REPO_ROOT, file);
+    let m;
+    classDeclRe.lastIndex = 0;
+    while ((m = classDeclRe.exec(text))) classes.push({ name: m[2], kind: m[1], file: rel });
+    mappingRe.lastIndex = 0;
+    while ((m = mappingRe.exec(text))) if (m[1]) controllerPaths.push({ path: m[1], file: rel });
+  }
+  return { classes, controllerPaths };
+}
+
+function buildEngineCatalog({ refresh = false } = {}) {
+  // Packaged SDK mode: the Java source scan NEVER runs on the client — serve
+  // the frozen catalog.json shipped in the authoring bundle (computed once at
+  // `erp bundle build` time). `--refresh` is a no-op here.
+  if (isPackaged()) return frozenCatalog();
+  if (!refresh && existsSync(ENGINE_CATALOG_CACHE)) {
+    try { return JSON.parse(readFileSync(ENGINE_CATALOG_CACHE, "utf8")); } catch { /* fall through and regenerate */ }
+  }
+
+  let engineDirNames;
+  try {
+    engineDirNames = readdirSync(PLATFORM_RUNTIME_ROOT, { withFileTypes: true })
+      .filter((d) => d.isDirectory() && d.name.startsWith("engine-"))
+      .map((d) => d.name)
+      .sort();
+  } catch {
+    engineDirNames = [];
+  }
+
+  // All Flyway migrations under backend/platform-runtime, wherever they live
+  // (many, e.g. V33__report_definition.sql/V86__bi_report_definition.sql,
+  // live in the shared `metadata` module rather than per-engine — confirmed
+  // by direct scan, not assumed).
+  const migrationFiles = walkFilesFiltered(PLATFORM_RUNTIME_ROOT, (name) => /^V\d+__.*\.sql$/.test(name))
+    .filter((f) => f.includes(`${path.sep}db${path.sep}migration${path.sep}`));
+  const migrations = migrationFiles.map((file) => {
+    const rel = path.relative(REPO_ROOT, file);
+    const versionMatch = path.basename(file).match(/^V(\d+)__/);
+    let text = "";
+    try { text = readFileSync(file, "utf8"); } catch { /* unreadable, leave tables empty */ }
+    const tables = new Set();
+    const tableRe = /create\s+table\s+(?:if\s+not\s+exists\s+)?"?([a-zA-Z0-9_.]+)"?/gi;
+    let tm;
+    while ((tm = tableRe.exec(text))) tables.add(tm[1].replace(/^public\./, ""));
+    const ownerMatch = rel.match(new RegExp(`(engine-[a-z-]+)[\\/]`));
+    return { file: rel, version: versionMatch ? Number(versionMatch[1]) : null, tables: [...tables], owner: ownerMatch ? ownerMatch[1] : null };
+  });
+  const ownedMigrations = migrations.filter((m) => m.owner);
+  const sharedMigrations = migrations.filter((m) => !m.owner);
+
+  const engines = {};
+  for (const engineName of engineDirNames) {
+    const javaRoot = path.join(PLATFORM_RUNTIME_ROOT, engineName, "src/main/java");
+    const javaFiles = walkFilesFiltered(javaRoot, (name) => name.endsWith(".java"));
+    const { classes, controllerPaths } = extractJavaCapabilities(javaFiles);
+    const classTokens = new Set();
+    for (const c of classes) for (const t of tokenize(c.name)) classTokens.add(t);
+
+    const ownMigrations = ownedMigrations.filter((m) => m.owner === engineName).map(({ owner, ...rest }) => rest);
+    // Shared (non-engine-owned) migrations attributed by class-name/table-name
+    // token overlap — heuristic, not authoritative package ownership; each
+    // entry is labeled as such below so a consumer never mistakes it for a
+    // confirmed `@Table`/repository binding.
+    const relatedShared = sharedMigrations
+      .filter((m) => m.tables.some((t) => tokenize(t).some((tok) => classTokens.has(tok))))
+      .map((m) => ({ file: m.file, version: m.version, tables: m.tables, note: "keyword-matched to this module's class names, not a confirmed repository binding" }));
+
+    engines[engineName] = {
+      module: engineName,
+      classCount: classes.length,
+      classes: classes.sort((a, b) => a.name.localeCompare(b.name)),
+      controllerBasePaths: [...new Set(controllerPaths.map((c) => c.path))].sort(),
+      controllerPathDetails: controllerPaths,
+      ownedMigrations: ownMigrations,
+      relatedSharedMigrations: relatedShared,
+    };
+  }
+
+  const catalog = {
+    generatedAt: new Date().toISOString(),
+    generatedBy: "erp platform catalog --refresh (tools/erp-cli/erp.mjs buildEngineCatalog)",
+    note: "Mechanically-derived from backend/platform-runtime/engine-*/src/main/java (regex class/interface/enum/record + @*Mapping scan) and every V*__*.sql Flyway migration under backend/platform-runtime — NOT a hand-maintained inventory, NOT a full Java AST parse. Regenerate with `erp platform catalog --refresh` whenever engine-* source changes.",
+    engineCount: engineDirNames.length,
+    engines,
+    sharedMigrationsModule: "backend/platform-runtime/metadata (Flyway migrations shared across engine-* modules; attribution above to a specific engine is keyword-based, not authoritative)",
+    contracts: buildContractsCatalog(),
+  };
+
+  try {
+    mkdirSync(path.dirname(ENGINE_CATALOG_CACHE), { recursive: true });
+    writeFileSync(ENGINE_CATALOG_CACHE, JSON.stringify(catalog, null, 2), "utf8");
+  } catch (e) {
+    console.error(`(warning: could not write cache ${ENGINE_CATALOG_CACHE}: ${e.message} — continuing with in-memory catalog)`);
+  }
+  return catalog;
+}
+
+// Search the (cached-or-fresh) engine catalog for a substring across module
+// names, class names, controller paths, and migration table names — the
+// mechanism `erp docs search`/`erp_search_docs` now also calls so a stale
+// "doesn't exist" doc claim can never again be the ONLY answer returned.
+function searchEngineCatalog(query, { refresh = false } = {}) {
+  const catalog = buildEngineCatalog({ refresh });
+  const q = query.toLowerCase();
+  // A multi-word query (e.g. "report builder", "pluggable provider") rarely
+  // appears verbatim in a class/table name — real classes are named
+  // "ReportDefinitionService", not "ReportBuilder". Matching on the whole
+  // phrase would return nothing for exactly the queries this fix exists to
+  // answer, so a candidate also hits if it contains ANY significant
+  // (>=4-char) word from the query — an OR-of-tokens match, same spirit as a
+  // search engine's own term matching, not just a single frozen substring.
+  const queryTokens = q.split(/\s+/).filter((t) => t.length >= 4);
+  const isHit = (s) => {
+    const low = s.toLowerCase();
+    return low.includes(q) || queryTokens.some((t) => low.includes(t));
+  };
+  const hits = [];
+  for (const [engineName, e] of Object.entries(catalog.engines)) {
+    if (isHit(engineName)) hits.push({ engine: engineName, kind: "module", match: engineName });
+    for (const c of e.classes) {
+      if (isHit(c.name)) hits.push({ engine: engineName, kind: c.kind, match: c.name, file: c.file });
+    }
+    for (const p of e.controllerBasePaths) {
+      if (isHit(p)) hits.push({ engine: engineName, kind: "rest-mapping", match: p });
+    }
+    for (const m of [...e.ownedMigrations, ...e.relatedSharedMigrations]) {
+      for (const t of m.tables) {
+        if (isHit(t)) hits.push({ engine: engineName, kind: "migration-table", match: t, file: m.file });
+      }
+    }
+  }
+  // Curated extension-point/gateway-client contracts (real method
+  // signatures/fields, see buildContractsCatalog) — searched separately from
+  // the plain class-name scan above so a query for e.g. "PendingHumanTask"
+  // surfaces the ACTUAL fields/methods, not just "yes, this class exists".
+  const contractHits = [];
+  for (const u of catalog.contracts?.units ?? []) {
+    const nameHit = isHit(u.name);
+    const memberHit = !nameHit && (u.fields.some((f) => isHit(f.name)) || u.methods.some((mo) => isHit(mo.name)));
+    if (nameHit || memberHit) contractHits.push({ engine: u.group, kind: "java-contract", match: u.name, file: u.file, unit: u });
+  }
+  // Class/interface/module hits are the actual answer to "does X exist" —
+  // put them ahead of migration-table hits, which fan out noisily across
+  // many engines once a shared migration's table name shares a token with
+  // several modules' own class names (disclosed heuristic, see relatedShared
+  // above). Contract hits (the richest data — real fields/signatures) sort
+  // first of all. Keeps a capped result (docs search shows the top 30) useful.
+  const kindRank = { "java-contract": -1, module: 0, class: 1, interface: 1, record: 1, enum: 1, "rest-mapping": 2, "migration-table": 3 };
+  const allHits = [...contractHits, ...hits];
+  allHits.sort((a, b) => (kindRank[a.kind] ?? 9) - (kindRank[b.kind] ?? 9));
+  return { query, catalogGeneratedAt: catalog.generatedAt, hits: allHits };
+}
+
+function platformCatalogCommand(opts) {
+  const catalog = buildEngineCatalog({ refresh: Boolean(opts.refresh) });
+  if (opts.engine) {
+    const e = catalog.engines[opts.engine];
+    if (!e) throw new Error(`unknown engine "${opts.engine}". Known: ${Object.keys(catalog.engines).join(", ")}`);
+    console.log(JSON.stringify(e, null, 2));
+    return;
+  }
+  console.log(`Engine capability catalog — generated ${catalog.generatedAt} (${Object.keys(catalog.engines).length} engine-* modules; cache: ${path.relative(REPO_ROOT, ENGINE_CATALOG_CACHE)})`);
+  for (const [name, e] of Object.entries(catalog.engines)) {
+    console.log(`  ${name} — ${e.classCount} classes, ${e.controllerBasePaths.length} REST mapping(s), ${e.ownedMigrations.length + e.relatedSharedMigrations.length} migration(s)`);
+  }
+  console.log(`\nUse --engine <name> for one module's full detail, --refresh to regenerate the cache.`);
+}
+
+// ---------------------------------------------------------------------------
+// erp platform describe <ClassName> — [REAL, added 2026-09-04, closes a real
+// gap surfaced live this session]. `erp platform catalog` (above) only ever
+// inventoried CLASS NAMES/REST PATHS/TABLES — a real third-party plugin
+// developer (or this session's own agents) had to open Java source
+// (WorkflowGatewayClient, PendingHumanTask, DmsGatewayClient, the
+// `*Contribution` family) to learn actual method signatures/field lists
+// before writing plugin code against them. That defeats the point of an SDK:
+// nothing about "what does PendingHumanTask actually contain" was
+// discoverable without this repo's own source.
+//
+// Extends the SAME catalog mechanism (mechanically regex-scanned Java
+// source, cached at ai/platform/engine-capability-catalog.json, same
+// disclosed-heuristic rigor as buildEngineCatalog above — not a real AST
+// parser) with a `contracts` section: real method signatures (name/params/
+// returnType) and real field lists for a CURATED set of genuinely-reusable
+// extension points:
+//   - every `*Contribution` interface in engine-plugin-api (the actual
+//     plugin extension-point family — RestContribution, WorkflowTaskContribution, ...)
+//   - the canonical `WorkflowGatewayClient` (engine-plugin-client) + its
+//     real nested response records (InstanceView, InstanceHumanTask,
+//     HistoryEntry, PendingHumanTask, DecidedCount) — the exact class that
+//     caused this session's real bug
+//   - every per-plugin `DmsGatewayClient`/`WorkflowGatewayClient`/
+//     `CommunicationGatewayClient` COPY under backend/modules (confirmed via
+//     grep these are hand-copied per plugin, not a shared library — each
+//     copy is catalogued separately, tagged by its owning module, so a
+//     developer can see they're independent and may drift)
+// ---------------------------------------------------------------------------
+
+// Split a raw parameter/record-component list on top-level commas only —
+// i.e. never inside a generic's <...> or a nested (...) — so
+// "Long id, Map<String, Object> context" splits into exactly 2 entries, not 3.
+function splitTopLevelCommas(raw) {
+  const out = [];
+  let depth = 0;
+  let cur = "";
+  for (const ch of raw) {
+    if (ch === "<" || ch === "(" || ch === "[") depth++;
+    else if (ch === ">" || ch === ")" || ch === "]") depth--;
+    if (ch === "," && depth === 0) {
+      out.push(cur.trim());
+      cur = "";
+    } else {
+      cur += ch;
+    }
+  }
+  if (cur.trim()) out.push(cur.trim());
+  return out;
+}
+
+// One "Type name" entry (a method param or record component) -> {type, name}.
+// Strips leading annotations (@NotNull, @RequestParam(...) etc) heuristically.
+function parseTypedEntry(entry) {
+  const stripped = entry.replace(/@\w+(\([^)]*\))?\s*/g, "").trim();
+  const m = stripped.match(/^(.*[\s>\]])(\w+)$/);
+  if (!m) return { type: stripped, name: "" };
+  return { type: m[1].trim().replace(/\s+/g, " "), name: m[2] };
+}
+
+// Strip Java comments (block and line) before scanning for methods/fields —
+// otherwise javadoc prose ("See Also DmsGatewayClient#asLong doc comment")
+// can false-positive-match the bare-identifier-then-paren method regex used
+// for interface bodies below.
+function stripJavaComments(text) {
+  return text.replace(/\/\*[\s\S]*?\*\//g, "").replace(/\/\/[^\n]*/g, "");
+}
+
+// Find the index of the character matching the opening bracket at `openIdx`
+// (text[openIdx] must be openCh) — simple depth counter, good enough for
+// well-formed source (same disclosed-heuristic posture as the rest of this
+// scanner, not a real parser).
+function findMatchingBracket(text, openIdx, openCh, closeCh) {
+  let depth = 0;
+  for (let i = openIdx; i < text.length; i++) {
+    if (text[i] === openCh) depth++;
+    else if (text[i] === closeCh) {
+      depth--;
+      if (depth === 0) return i;
+    }
+  }
+  return -1;
+}
+
+// Mechanically extract every class/interface/enum/record declared in one
+// Java file (including nested ones, e.g. WorkflowGatewayClient's nested
+// public records) as a "contract unit": {name, kind, file, fields, methods}.
+// Regex-based, same rigor as extractJavaCapabilities above — not a real AST
+// parser, but real enough to answer "what does this class actually contain"
+// without opening the file.
+function extractJavaContracts(file) {
+  let text;
+  try { text = readFileSync(file, "utf8"); } catch { return []; }
+  const rel = path.relative(REPO_ROOT, file);
+  // Strip comments from the WHOLE file up front — javadoc routinely contains
+  // stray braces/parens (`{@code Foo(...)}`) that would otherwise throw off
+  // the brace/paren matching below.
+  text = stripJavaComments(text);
+  const units = [];
+  const typeDeclRe = /(?:public|private|protected)?\s*(?:static\s+)?(?:final\s+|abstract\s+)*(class|interface|enum|record)\s+(\w+)/g;
+  let m;
+  while ((m = typeDeclRe.exec(text))) {
+    const kind = m[1];
+    const name = m[2];
+    const afterName = m.index + m[0].length;
+
+    let fields = [];
+    let bodyStart;
+    if (kind === "record") {
+      const parenIdx = text.indexOf("(", afterName);
+      if (parenIdx === -1 || parenIdx - afterName > 40) continue; // not really a record header (generic type param etc)
+      const closeParen = findMatchingBracket(text, parenIdx, "(", ")");
+      if (closeParen === -1) continue;
+      const componentsRaw = text.slice(parenIdx + 1, closeParen);
+      fields = splitTopLevelCommas(componentsRaw).filter(Boolean).map(parseTypedEntry);
+      bodyStart = text.indexOf("{", closeParen);
+    } else {
+      bodyStart = text.indexOf("{", afterName);
+    }
+    if (bodyStart === -1) continue;
+    const bodyEnd = findMatchingBracket(text, bodyStart, "{", "}");
+    if (bodyEnd === -1) continue;
+    const body = stripJavaComments(text.slice(bodyStart + 1, bodyEnd));
+
+    // Methods declared directly in this body (public/protected, or — since
+    // an interface's abstract methods carry no explicit modifier at all —
+    // any bare `ReturnType name(` for a `kind === "interface"` unit), not a
+    // constructor (name !== this unit's own name).
+    const methods = [];
+    const modifierPrefix = kind === "interface" ? "(?:public\\s+|protected\\s+|default\\s+)?" : "(?:public|protected)\\s+";
+    const methodRe = new RegExp(`${modifierPrefix}(?:static\\s+)?(?:final\\s+)?(?:abstract\\s+)?(?:<[^>]*>\\s*)?([\\w$.\\[\\]<>,?\\s]+?)\\s+(\\w+)\\s*\\(`, "g");
+    let mm;
+    while ((mm = methodRe.exec(body))) {
+      const returnType = mm[1].trim().replace(/\s+/g, " ");
+      const methodName = mm[2];
+      if (methodName === name) continue; // constructor
+      const parenIdx = mm.index + mm[0].length - 1;
+      const closeParen = findMatchingBracket(body, parenIdx, "(", ")");
+      if (closeParen === -1) continue;
+      const paramsRaw = body.slice(parenIdx + 1, closeParen).trim();
+      const params = paramsRaw ? splitTopLevelCommas(paramsRaw).map(parseTypedEntry) : [];
+      // Confirm what follows is really a method decl (`{`/`;`/`throws`), not
+      // a false-positive match inside e.g. a lambda or comment.
+      const after = body.slice(closeParen + 1, closeParen + 60).trimStart();
+      if (!/^(throws\b|\{|;)/.test(after)) continue;
+      methods.push({ name: methodName, returnType, params });
+    }
+
+    units.push({ name, kind, file: rel, fields, methods });
+  }
+  return units;
+}
+
+const CONTRACT_TARGET_GROUPS = [
+  {
+    group: "engine-plugin-api contribution interfaces (plugin extension points)",
+    files: () => walkFilesFiltered(path.join(PLATFORM_RUNTIME_ROOT, "engine-plugin-api/src/main/java"), (n) => n.endsWith("Contribution.java")),
+  },
+  {
+    group: "canonical WorkflowGatewayClient (engine-plugin-client — the shared client new plugins should depend on)",
+    files: () => {
+      const f = path.join(PLATFORM_RUNTIME_ROOT, "engine-plugin-client/src/main/java/com/erp/platform/engine/plugin/client/WorkflowGatewayClient.java");
+      return existsSync(f) ? [f] : [];
+    },
+  },
+  {
+    group: "per-plugin DmsGatewayClient copies (backend/modules — hand-copied pattern, not a shared library)",
+    files: () => walkFilesFiltered(path.join(REPO_ROOT, "backend/modules"), (n) => n === "DmsGatewayClient.java"),
+  },
+  {
+    group: "per-plugin WorkflowGatewayClient copies (backend/modules — pre-date the canonical engine-plugin-client class above)",
+    files: () => walkFilesFiltered(path.join(REPO_ROOT, "backend/modules"), (n) => n === "WorkflowGatewayClient.java"),
+  },
+  {
+    group: "per-plugin CommunicationGatewayClient copies (backend/modules — hand-copied pattern, not a shared library)",
+    files: () => walkFilesFiltered(path.join(REPO_ROOT, "backend/modules"), (n) => n === "CommunicationGatewayClient.java"),
+  },
+];
+
+function buildContractsCatalog() {
+  const units = [];
+  for (const { group, files } of CONTRACT_TARGET_GROUPS) {
+    for (const file of files()) {
+      for (const unit of extractJavaContracts(file)) {
+        units.push({ ...unit, group });
+      }
+    }
+  }
+  return {
+    note: "Mechanically-derived from the curated extension-point/gateway-client Java source listed in CONTRACT_TARGET_GROUPS (tools/erp-cli/erp.mjs) — real method signatures and record field lists, NOT a hand-maintained inventory, NOT a full AST parse (same disclosed-heuristic posture as the rest of this catalog). Look up one by (partial) name with `erp platform describe <name>`.",
+    unitCount: units.length,
+    units,
+  };
+}
+
+// Look up one class/interface/record by partial, case-insensitive name —
+// the concrete answer to "what does PendingHumanTask actually contain"
+// without opening a file.
+function describeContract(name, { refresh = false } = {}) {
+  const catalog = buildEngineCatalog({ refresh });
+  const q = name.toLowerCase();
+  return (catalog.contracts?.units ?? []).filter((u) => u.name.toLowerCase().includes(q));
+}
+
+function formatContractUnit(u) {
+  const lines = [];
+  lines.push(`${u.kind} ${u.name}  (${u.file})`);
+  lines.push(`  from: ${u.group}`);
+  if (u.fields.length) {
+    lines.push(`  fields:`);
+    for (const f of u.fields) lines.push(`    ${f.type} ${f.name}`);
+  }
+  if (u.methods.length) {
+    lines.push(`  methods:`);
+    for (const m of u.methods) {
+      const params = m.params.map((p) => `${p.type} ${p.name}`).join(", ");
+      lines.push(`    ${m.returnType} ${m.name}(${params})`);
+    }
+  }
+  if (!u.fields.length && !u.methods.length) lines.push(`  (no public fields/methods found by the scan)`);
+  return lines.join("\n");
+}
+
+function platformDescribeCommand(name, opts) {
+  if (!name) throw new Error("usage: erp platform describe <ClassName>");
+  const matches = describeContract(name, { refresh: Boolean(opts.refresh) });
+  if (!matches.length) {
+    console.log(`No contract found matching "${name}". Run \`erp platform catalog --refresh\` if this class was added/renamed recently, or \`erp platform catalog\` to browse module/class names first — this command only covers the curated extension-point/gateway-client set (contribution interfaces, WorkflowGatewayClient, DmsGatewayClient, CommunicationGatewayClient), not every class in the repo.`);
+    return;
+  }
+  console.log(matches.map(formatContractUnit).join("\n\n"));
+}
+
+// ---------------------------------------------------------------------------
+// erp plugin scaffold <extension-point> — [REAL, added 2026-09-04]. Emits a
+// minimal, correctly-typed Java skeleton for one curated extension point,
+// pulled from a REAL existing implementation in this codebase (never
+// invented syntax) — currently only `rest-contribution`, modeled on
+// hello-plugin's own real HelloRestContribution.java (the simplest genuine
+// example: @Extension/@RestController/@RequestMapping/controllerBean()).
+// ---------------------------------------------------------------------------
+const SCAFFOLD_TEMPLATES = {
+  "rest-contribution": {
+    describe: "A plugin-contributed REST controller (RestContribution) — modeled on backend/modules/hello-plugin/src/main/java/com/example/helloplugin/HelloRestContribution.java, the simplest real shipped example.",
+    render: ({ packageName, className, pluginId }) => `package ${packageName};
+
+import com.erp.platform.engine.plugin.api.RestContribution;
+import org.pf4j.Extension;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+import java.util.Map;
+
+/**
+ * Scaffolded by \`erp plugin scaffold rest-contribution\` — modeled on the
+ * real HelloRestContribution.java. The base path MUST start with
+ * /api/v1/plugins/${pluginId}/ — the host's PluginRestBridge rejects any
+ * other prefix (see RestContribution's own doc comment,
+ * \`erp platform describe RestContribution\`).
+ */
+@Extension
+@RestController
+@RequestMapping("/api/v1/plugins/${pluginId}")
+public class ${className} implements RestContribution {
+
+    @GetMapping("/ping")
+    public Map<String, Object> ping() {
+        return Map.of("pluginId", "${pluginId}", "status", "ok");
+    }
+
+    @Override
+    public Object controllerBean() {
+        return this;
+    }
+}
+`,
+  },
+  "seed-data-config": {
+    describe: "An install-lifecycle seed-data file (metadata/seed-data/<name>.json) that ships config rows into the shared platform job-config entities so they travel with the .spk (PluginDataSeedInstaller, idempotent upsert by keyFields). Covers a day_offset reminder, an aggregation roll-up, and a cadence generator. Write the output to backend/modules/<plugin>/spk-assembly/metadata/seed-data/<plugin>-job-configs.json. Schemas: erp_get_schema plugin-seed-data | entity-status-date-sweep-config | entity-aggregation-config | entity-cadence-config. Doc: ai/patterns/plugin-install-data-seeding.md + ai/patterns/generic-aggregation-and-cadence-jobs.md.",
+    render: ({ pluginId }) => JSON.stringify({
+      "//": `Seed file for ${pluginId}. One file per target entity. keyFields = the natural key so re-install upserts, never duplicates. Also ship metadata/entities/*.json for any new column and metadata/rules/*.json AFTER_CREATE {type:EXECUTE_SERVICE,service:ensure<Job>Registered}.`,
+      entity: "entity_status_date_sweep_config",
+      keyFields: ["entity_name", "date_field", "set_field", "set_status_to", "day_offset"],
+      source: pluginId,
+      rows: [
+        { entity_name: "REPLACE_entity", status_field: "status", when_status_in: "ACTIVE", date_field: "REPLACE_expiry_date", compare_op: "lte", day_offset: 30, set_field: "REPLACE_alert_30d", set_status_to: "true", active: true },
+        { "//": "day_offset:0 (or omitted) keeps the original 'date already passed' behavior", entity_name: "REPLACE_entity", status_field: "status", when_status_in: "ACTIVE", date_field: "REPLACE_expiry_date", compare_op: "lt", set_field: "REPLACE_expired_flag", set_status_to: "true", active: true },
+      ],
+      "// see also": {
+        "entity_aggregation_config": { sweep_code: `${pluginId}-rollup`, source_entity: "REPLACE_entity", aggregation: "count", group_by_field: "status", target_entity: "REPLACE_summary_entity", target_key_field: "metric_key", target_key_prefix: "status:", target_value_field: "metric_value", target_timestamp_field: "last_reconciled_at", active: true },
+        "entity_cadence_config": { cadence_code: `${pluginId}-generate`, target_entity: "REPLACE_target_entity", interval_days: 30, dedupe_target_field: "cadence_marker", template_json: { status: "DRAFT", ref_number: "REF-${date}-${ts}" }, active: true },
+      },
+    }, null, 2),
+  },
+};
+
+function pluginScaffoldCommand(extensionPoint, opts) {
+  if (!extensionPoint || !SCAFFOLD_TEMPLATES[extensionPoint]) {
+    console.log(`usage: erp plugin scaffold <extension-point> [--package <pkg>] [--class <Name>] [--plugin-id <id>] [--out <file.java>]\nKnown extension points: ${Object.keys(SCAFFOLD_TEMPLATES).join(", ")}`);
+    return;
+  }
+  const tpl = SCAFFOLD_TEMPLATES[extensionPoint];
+  const pluginId = opts.pluginId || "my-plugin";
+  const packageName = opts.package || `com.example.${pluginId.replace(/[^a-zA-Z0-9]/g, "")}`;
+  const className = opts.class || "MyRestContribution";
+  const rendered = tpl.render({ packageName, className, pluginId });
+  if (opts.out) {
+    mkdirSync(path.dirname(opts.out), { recursive: true });
+    writeFileSync(opts.out, rendered, "utf8");
+    console.log(`Wrote ${opts.out}`);
+  } else {
+    console.log(rendered);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// erp plugin create / validate / build / test / publish / push
+// [REAL] — thin wrappers around tools/spark-cli/spark.js's own
+// create/validate/package/publish (already-real, already-used-by-agents
+// commands this whole session) plus tools/page-validator's semantic
+// validator, so `erp` becomes the one entrypoint per the doc's vision
+// without duplicating spark.js's logic.
+// ---------------------------------------------------------------------------
+function runSpark(args) {
+  const res = spawnSync(process.execPath, [path.join(REPO_ROOT, "tools/spark-cli/spark.js"), ...args], { stdio: "inherit" });
+  if (res.status !== 0) process.exitCode = res.status || 1;
+}
+
+function pluginCreateCommand(pluginId, opts) {
+  const args = ["create", pluginId];
+  if (opts.name) args.push("--name", opts.name);
+  if (opts.schema) args.push("--schema", opts.schema);
+  if (opts.category) args.push("--category", opts.category);
+  // type/runtime-mode/service-port (2026-09-03, real gap closed) — `spark create` used
+  // to hardcode type:"business-application" and never set runtimeModes at all, so a
+  // scaffolded plugin silently got the implicit ["embedded"] default with no way to
+  // opt into "service" mode at creation time — see PluginManifest#runtimeModes'
+  // Javadoc (engine-plugin-api) for what these fields actually do at runtime.
+  if (opts.type) args.push("--type", opts.type);
+  if (opts.runtimeMode) args.push("--runtime-mode", opts.runtimeMode);
+  if (opts.servicePort) args.push("--service-port", opts.servicePort);
+  runSpark(args);
+}
+
+// ---------------------------------------------------------------------------
+// erp plugin set-runtime-mode — [REAL, added 2026-09-03, closes a real gap]
+// `--runtime-mode` on `plugin create` only helps at scaffold time — there was
+// no way at all for a developer to decide an ALREADY-EXISTING module should
+// switch to standalone-service deployment via the CLI; the only path was
+// hand-editing plugin.json's runtimeModes/serviceDeployment fields from
+// memory (easy to get the nested PluginServiceDeploymentSpec shape wrong —
+// see engine-plugin-api's own Javadoc). This mutates an existing plugin.json
+// in place, then re-validates it against the corrected schema before
+// declaring success — so a malformed edit is caught immediately, not at the
+// next `erp plugin build`.
+//
+// Disclosed, honestly: this only sets the DECLARATION (what the plugin says
+// it CAN run as, plus its recommended service-mode defaults). Declaring
+// "service" here does not itself switch anything live — the actual running
+// mode is chosen per-plugin in Studio's Plugin Runtime toggle
+// (erp_core.application.deployment_type, V28), same as
+// PluginManifest#runtimeModes' own Javadoc states. And docker/kubernetes/
+// cloud fields, if set, are real persisted DATA for a future Deployment
+// Manager — not wired to any live Docker/Kubernetes/cloud-provider API by
+// this codebase today (per PluginServiceDeploymentSpec's own doc comment) —
+// this command will not silently imply otherwise.
+// ---------------------------------------------------------------------------
+async function pluginSetRuntimeModeCommand(pluginDir, opts) {
+  if (!pluginDir || !opts.mode) throw new Error("usage: erp plugin set-runtime-mode <plugin-dir> --mode embedded|service [--port <n>] [--health-path <path>] [--timeout-ms <n>]");
+  if (!["embedded", "service"].includes(opts.mode)) throw new Error(`--mode must be "embedded" or "service", got "${opts.mode}"`);
+  const manifestPath = findManifestPath(pluginDir);
+  const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+  const previousModes = manifest.runtimeModes || ["embedded"];
+  manifest.runtimeModes = [opts.mode];
+  if (opts.mode === "service") {
+    const existing = manifest.serviceDeployment || {};
+    manifest.serviceDeployment = {
+      process: { port: opts.port ? Number(opts.port) : existing.process?.port ?? null, startupCommand: existing.process?.startupCommand ?? null, workingDirectory: existing.process?.workingDirectory ?? null, env: existing.process?.env ?? {} },
+      docker: existing.docker ?? null,
+      kubernetes: existing.kubernetes ?? null,
+      cloud: existing.cloud ?? null,
+      healthPath: opts.healthPath || existing.healthPath || "/actuator/health",
+      timeoutMs: opts.timeoutMs ? Number(opts.timeoutMs) : existing.timeoutMs ?? 5000,
+      heartbeatIntervalSeconds: existing.heartbeatIntervalSeconds ?? 10,
+    };
+  }
+  // embedded keeps serviceDeployment as-is (real recommended defaults some admin may
+  // want back if they flip to service again later) rather than deleting it — same
+  // "don't destroy data on a mode toggle" posture as everything else in this file.
+  const schema = JSON.parse(readFileSync(schemaPathByName("plugin-manifest"), "utf8"));
+  const issues = simpleSchemaCheck(manifest, schema, "$");
+  if (issues.length > 0) {
+    throw new Error(`Refusing to write ${manifestPath} — the resulting manifest fails plugin-manifest schema validation:\n  ${issues.join("\n  ")}`);
+  }
+  writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + "\n", "utf8");
+  console.log(`Updated ${manifestPath}: runtimeModes ${JSON.stringify(previousModes)} -> ${JSON.stringify(manifest.runtimeModes)}`);
+  if (opts.mode === "service") console.log(`  serviceDeployment.process.port = ${manifest.serviceDeployment.process.port ?? "(not set — pass --port <n>)"}`);
+  console.log(`  Note: this only declares what the plugin CAN run as — the actual live mode is chosen per-plugin in Studio's Plugin Runtime toggle; docker/kubernetes/cloud fields (if you add them) are recorded data only, not acted on by this platform.`);
+}
+
+function findManifestPath(pluginDir) {
+  const candidates = [path.join(path.resolve(pluginDir), "plugin.json"), path.join(path.resolve(pluginDir), "spk-assembly", "plugin.json")];
+  for (const c of candidates) if (existsSync(c)) return c;
+  throw new Error(`no plugin.json found at ${candidates.join(" or ")}`);
+}
+
+function pluginValidateCommand(dir) {
+  requireMonorepo("erp plugin validate");
+  runSpark(["validate", dir]);
+}
+
+// ---------------------------------------------------------------------------
+// erp plugin compile — Code Plugin v0 (2026-09-02)
+// [REAL] — a thin wrapper around tools/erp-code-plugin-compiler/compile.mjs,
+// which does the actual TSX -> page-definition JSON compile (TypeScript
+// Compiler API transpile + sandboxed vm evaluation of @erp/ui's real
+// runtime — see that file's own doc comment). See
+// ai/patterns/code-plugin-sdk.md for the full v0 contract/boundary.
+// ---------------------------------------------------------------------------
+async function pluginCompileCommand(sourcePath, opts) {
+  if (!sourcePath) {
+    console.error("Usage: erp plugin compile <source.tsx> [--out <page.json>]");
+    process.exitCode = 1;
+    return;
+  }
+  const mod = await import(pathToFileURL(path.join(REPO_ROOT, "tools/erp-code-plugin-compiler/compile.mjs")).href);
+  const result = await mod.compilePlugin(sourcePath);
+  if (result.diagnostics.length) {
+    console.error("Diagnostics:");
+    for (const d of result.diagnostics) console.error(`  - ${d}`);
+  }
+  if (opts.out && result.pages.length === 1) {
+    writeFileSync(opts.out, JSON.stringify(result.pages[0].definition, null, 2));
+    console.log(`Wrote ${opts.out}`);
+  } else {
+    if (opts.out) console.error(`${result.pages.length} pages compiled — --out only writes a single-page result; printing all pages instead.`);
+    console.log(JSON.stringify(result.pages, null, 2));
+  }
+}
+
+function pluginBuildCommand(dir, opts) {
+  const args = ["package", dir];
+  if (opts.out) args.push("-o", opts.out);
+  runSpark(args);
+}
+
+// ---------------------------------------------------------------------------
+// erp plugin install-bundle — [REAL, added 2026-09-14] real bug found live:
+// seeding an ApplicationCatalog bundle (e.g. "hcm", 38 real plugin ids) onto
+// a tenant used to mean 38 individual `erp plugin build` + manual multipart
+// uploads, in a hand-maintained dependency order that was wrong more than
+// once. This computes the real order from each plugin's own declared
+// `plugin.json` `dependencies` (a real topological sort, not a guess) and
+// drives the SAME real upload endpoint (`POST /api/v1/authoring/plugins/
+// upload`) every other install path in this file already uses — no new
+// backend install mechanism, just automation over the existing one.
+// ---------------------------------------------------------------------------
+
+/**
+ * Kahn's-algorithm topological sort restricted to the given `pluginIds` set —
+ * a dependency on something NOT in that set (e.g. `hcm-foundation` already
+ * installed some other way) is simply ignored, not an error: this only needs
+ * to order what it's actually about to install relative to each other.
+ * Throws with the exact cycle's members named — a silent infinite loop on
+ * real (never-expected) bad data is worse than a clear error.
+ */
+function resolveInstallOrder(pluginIds, dependenciesOf) {
+  const idSet = new Set(pluginIds);
+  const inDegree = new Map(pluginIds.map((id) => [id, 0]));
+  const dependents = new Map(pluginIds.map((id) => [id, []]));
+  for (const id of pluginIds) {
+    for (const dep of dependenciesOf(id)) {
+      if (!idSet.has(dep)) continue;
+      inDegree.set(id, inDegree.get(id) + 1);
+      dependents.get(dep).push(id);
+    }
+  }
+  const queue = pluginIds.filter((id) => inDegree.get(id) === 0);
+  const order = [];
+  while (queue.length > 0) {
+    const id = queue.shift();
+    order.push(id);
+    for (const dependent of dependents.get(id)) {
+      inDegree.set(dependent, inDegree.get(dependent) - 1);
+      if (inDegree.get(dependent) === 0) queue.push(dependent);
+    }
+  }
+  if (order.length !== pluginIds.length) {
+    const stuck = pluginIds.filter((id) => !order.includes(id));
+    throw new Error(`dependency cycle detected among: ${stuck.join(", ")}`);
+  }
+  return order;
+}
+
+async function pluginBundleInstallCommand(applicationKey, opts) {
+  if (!applicationKey) throw new Error("usage: erp plugin install-bundle <applicationKey> [--tenant <id>] [--continue-on-error]");
+  const cfg = loadConfig();
+  const env = currentEnv(cfg);
+  const baseUrl = opts.url || env.baseUrl;
+
+  let tenantId = opts.tenant;
+  if (!tenantId) {
+    const platformTenant = await api(cfg, "GET", "/api/v1/platform-tenant", { requireAuth: false });
+    tenantId = platformTenant.tenantId;
+    console.log(`No --tenant given — defaulting to the platform tenant (id ${tenantId}).`);
+  }
+
+  const catalog = await api(cfg, "GET", `/tenants/application-catalog/${encodeURIComponent(applicationKey)}`, { requireAuth: false, tenantIdOverride: tenantId });
+  const pluginIds = catalog.pluginIds;
+  if (!pluginIds || pluginIds.length === 0) {
+    console.log(`Application catalog key "${applicationKey}" has no plugin members — nothing to install.`);
+    return;
+  }
+  console.log(`"${applicationKey}" bundle: ${pluginIds.length} plugins.`);
+
+  const manifestOf = (id) => JSON.parse(readFileSync(path.join(REPO_ROOT, "backend/modules", id, "spk-assembly/plugin.json"), "utf8"));
+  const order = resolveInstallOrder(pluginIds, (id) => manifestOf(id).dependencies || []);
+  console.log(`Install order (dependency-resolved): ${order.join(" -> ")}`);
+
+  const actor = opts.actor || "erp-plugin-bundle-install";
+  const results = [];
+  for (const id of order) {
+    const moduleDir = path.join(REPO_ROOT, "backend/modules", id, "spk-assembly");
+    const manifest = manifestOf(id);
+    const spkPath = path.join(os.tmpdir(), `${id}-${manifest.version}.spk`);
+    process.stdout.write(`Building ${id} v${manifest.version}... `);
+    runSpark(["package", moduleDir, "-o", spkPath]);
+    if (!existsSync(spkPath)) {
+      const message = `spark package did not produce ${spkPath}`;
+      console.log(`BUILD FAILED: ${message}`);
+      results.push({ id, ok: false, message });
+      if (!opts.continueOnError) break;
+      continue;
+    }
+    const form = new FormData();
+    form.set("file", new Blob([readFileSync(spkPath)]), path.basename(spkPath));
+    const res = await fetch(`${baseUrl}/api/v1/authoring/plugins/upload`, {
+      method: "POST",
+      headers: { "X-Tenant-Id": String(tenantId), "X-Actor": actor },
+      body: form,
+    });
+    const text = await res.text();
+    if (res.ok) {
+      console.log(`OK`);
+      results.push({ id, ok: true });
+    } else if (res.status === 409) {
+      // Already installed at this exact version — the platform's own
+      // idempotency, not a failure. Same "resume = just re-run" posture
+      // every other install path in this codebase already relies on.
+      console.log(`already installed (skipped)`);
+      results.push({ id, ok: true, skipped: true });
+    } else {
+      let message = text;
+      try {
+        message = JSON.parse(text).message || text;
+      } catch {
+        // plain text body — use as-is
+      }
+      console.log(`FAILED (HTTP ${res.status}): ${message}`);
+      results.push({ id, ok: false, message });
+      if (!opts.continueOnError) break;
+    }
+  }
+
+  const succeeded = results.filter((r) => r.ok).length;
+  const failed = results.filter((r) => !r.ok);
+  const pending = order.length - results.length;
+  console.log(`\n${succeeded}/${order.length} succeeded${pending > 0 ? `, ${pending} not attempted` : ""}${failed.length > 0 ? `, ${failed.length} failed` : ""}.`);
+  if (failed.length > 0) {
+    console.log(`Failed: ${failed.map((r) => r.id).join(", ")}`);
+    console.log(`Re-run the same command to resume — already-installed plugins are skipped automatically.`);
+    process.exitCode = 1;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// lintPageSemantics — [REAL, added 2026-09-03] catches the exact bug-class a
+// live hcm-learning module shipped module-wide: pages that are 100% schema-
+// valid (pass validate-page-properties.mjs) but semantically wrong because a
+// field uses the wrong block for its job. Structural validation checks "is
+// this legal"; this checks "is this the right block" — three checks, each
+// tied to a real, confirmed platform convention:
+//   1. A field whose name ends in `_id` (a foreign-key-shaped column, per
+//      the entity's own `_id` naming convention already used everywhere in
+//      this codebase) rendered as core.text-input/core.number-input instead
+//      of core.lookup/core.select/core.autocomplete.
+//   2. A field on an entity column typed date/datetime (cross-referenced
+//      against the plugin's own entity-definition JSON when metadata.entityDefinition
+//      names one) rendered as core.text-input instead of core.date-picker.
+//   3. A page with a filter-bar-shaped control (a core.text-input/core.select
+//      outside the grid whose committed handler writes `page.filter*`) whose
+//      core.grid sibling never binds `search`/`externalFilter` — the exact
+//      "filters are decorative" bug.
+// Heuristic, not exhaustive — false negatives are expected (this catches the
+// known bug shapes, it is not a general AI reviewer); it reports WARN, not
+// FAIL, since a real exception (a genuinely free-text external reference id,
+// a deliberately unfiltered grid) is legitimate and this cannot tell the
+// difference — a human/agent reviews each WARN, same as any lint tool.
+// ---------------------------------------------------------------------------
+function lintPageSemantics(pageJson, entityFieldTypes) {
+  const warnings = [];
+  const instances = [];
+  (function walk(node) {
+    if (!node || typeof node !== "object") return;
+    if (node.blockType) instances.push(node);
+    for (const v of Object.values(node)) {
+      if (Array.isArray(v)) v.forEach(walk);
+      else if (v && typeof v === "object") walk(v);
+    }
+  })(pageJson.rows || pageJson.definition?.rows || pageJson);
+
+  const bindingKeyOf = (props, name) => {
+    const p = props?.[name];
+    if (p?.source === "binding" && p.binding?.scope === "page") return p.binding.key;
+    return undefined;
+  };
+  const filterKeys = new Set();
+  let gridInstance = null;
+  for (const inst of instances) {
+    const props = inst.properties || {};
+    if (inst.blockType === "core.grid") gridInstance = inst;
+    if ((inst.blockType === "core.text-input" || inst.blockType === "core.select") && inst.instanceId?.startsWith("filter-")) {
+      const key = bindingKeyOf(props, "value");
+      if (key) filterKeys.add(key);
+    }
+    if (inst.blockType === "core.text-input" || inst.blockType === "core.number-input") {
+      const key = bindingKeyOf(props, "value");
+      if (!key) continue;
+      const fieldName = String(key).replace(/^form/, "").replace(/^./, (c) => c.toLowerCase());
+      const entityType = entityFieldTypes?.[toSnakeGuess(fieldName)] || entityFieldTypes?.[toSnakeGuess(key)];
+      if (/_?[Ii]d$/.test(key) && key !== "id") {
+        warnings.push(`WARN [lookup-missing] "${inst.instanceId}" (${inst.blockType}, bound to page.${key}) looks like a foreign-key field (name ends in Id) but isn't core.lookup/core.select/core.autocomplete — see \`erp examples patterns\` "related-record-lookup-field".`);
+      } else if (entityType === "date" || entityType === "datetime") {
+        warnings.push(`WARN [date-as-text] "${inst.instanceId}" (${inst.blockType}, bound to page.${key}) is a date/datetime field rendered as plain text — use core.date-picker instead.`);
+      }
+    }
+  }
+  if (filterKeys.size > 0) {
+    const props = gridInstance?.properties || {};
+    const hasSearch = props.search !== undefined;
+    const hasExternalFilter = props.externalFilter !== undefined;
+    if (!gridInstance) warnings.push(`WARN [filters-decorative] page has ${filterKeys.size} filter control(s) (${[...filterKeys].join(", ")}) but no core.grid block was found to wire them to.`);
+    else if (!hasSearch && !hasExternalFilter) warnings.push(`WARN [filters-decorative] core.grid "${gridInstance.instanceId}" has no search/externalFilter property bound — ${filterKeys.size} filter control(s) (${[...filterKeys].join(", ")}) currently do nothing to the grid's data. See crm-leads.json's grid block for the real wiring.`);
+  }
+  return warnings;
+}
+function toSnakeGuess(camel) { return String(camel).replace(/([a-z0-9])([A-Z])/g, "$1_$2").toLowerCase(); }
+
+function loadEntityFieldTypes(absDir, entityDefName) {
+  if (!entityDefName) return {};
+  const p = path.join(absDir, "metadata", "entities", `${entityDefName}.json`);
+  if (!existsSync(p)) return {};
+  try {
+    const j = JSON.parse(readFileSync(p, "utf8"));
+    const fields = j.definition?.fields || j.fields || [];
+    const out = {};
+    for (const f of fields) if (f.fieldName) out[f.fieldName] = String(f.dataType || "").toLowerCase();
+    return out;
+  } catch { return {}; }
+}
+
+// lintDataServiceSemantics — [REAL, added 2026-09-04] catches, at author
+// time, the exact class of bug found live building HCM Talent Batch 1
+// (ai/domains/hcm-talent-management.md): an entity-backed Data Service
+// filter with a literal `"true"`/`"false"` value targeting a field the
+// entity itself declares `dataType: boolean` used to be bound as a raw
+// String against a real boolean column — BiReportQueryExecutor's own
+// type-coercion bug, now fixed at the platform level (see that same domain
+// doc), but a mismatched literal is also just as easily a genuine AUTHORING
+// mistake (e.g. `"1"` against a boolean field, or `"true"` against a text
+// field that happens to store the words "true"/"false") that the platform
+// fix does nothing to prevent going forward. This is the static,
+// pre-deploy half of that fix — per the standing "validation, not just
+// runtime debugging" principle: whatever can be checked from the JSON
+// alone, should be, before a developer ever needs `erp logs tail` to find
+// out something was wrong. Heuristic like lintPageSemantics — WARNs, since
+// a legitimately non-boolean field storing literal "true"/"false" text is
+// rare but not impossible.
+function lintDataServiceSemantics(dsJson, entityFieldTypes) {
+  const warnings = [];
+  const def = dsJson.definition;
+  if (!def) return warnings;
+  const filterSets = [];
+  if (Array.isArray(def.filters)) filterSets.push(def.filters);
+  if (Array.isArray(def.steps)) {
+    // A composite data-service's own steps don't carry filters directly in
+    // this JSON (they reference another named data-service) — nothing to
+    // check here without resolving the referenced file, which this plugin-
+    // local lint deliberately doesn't do (out of scope: cross-file
+    // resolution). Composite services are skipped, not falsely flagged.
+  }
+  for (const filters of filterSets) {
+    for (const f of filters) {
+      if (!f.field || f.value === undefined || f.value === null) continue;
+      const fieldType = entityFieldTypes[f.field];
+      if (!fieldType) continue; // unknown field (not this entity's own, or entity type not resolvable here) — not this lint's job
+      const looksBoolean = f.value === "true" || f.value === "false";
+      if (fieldType === "boolean" && !looksBoolean && typeof f.value === "string" && !f.value.startsWith("${param.")) {
+        warnings.push(`WARN [filter-type-mismatch] filter on "${f.field}" (a boolean field) has literal value ${JSON.stringify(f.value)} — expected "true"/"false".`);
+      } else if (looksBoolean && fieldType !== "boolean") {
+        warnings.push(`WARN [filter-type-mismatch] filter on "${f.field}" (declared dataType "${fieldType}", not boolean) has literal value ${JSON.stringify(f.value)}, which looks like a boolean literal — confirm this is intentional.`);
+      }
+    }
+  }
+  return warnings;
+}
+
+// lintI18nSemantics — I18N-001 [REAL, added 2026-09-03, HCM Compensation
+// Batch 2] catches, at author time, the exact bug class found live building
+// this very batch: a page JSON referencing an i18n key (`labelKey`,
+// `headerKey`, `textKey`, `titleKey`, `displayNameKey`, `descriptionKey`, or
+// a `select`/`lookup` option's own `labelKey`) that has NO entry at all in
+// the plugin's own `metadata/i18n/*.json` locale files — the runtime then
+// renders the raw key wrapped in `⟦...⟧` delimiters instead of real text,
+// exactly what shipped (briefly) on this batch's own allowances/benefits
+// pages before being caught by Playwright, not by any pre-deploy tool. This
+// closes that gap the same way `DS-001` (`lintDataServiceSemantics`) closed
+// its own: a static, pre-deploy, JSON-only check — no server round-trip
+// needed to know a key is missing.
+//
+// A second, heuristic check (still under the I18N-001 umbrella, reported as
+// its own `[i18n-placeholder]` tag) flags a value that is EXACTLY the
+// mechanical Title-Case-with-spaces rendering of the key's own last
+// camelCase/dotted segment — e.g. `"newBtn": "New Btn"` or
+// `"chart.distributionHeading": "Distribution Heading"` — the real
+// regression class found in HCM Talent Management Batch 2 (see
+// ai/domains/hcm-talent-management-module-deferred-backlog.md). This is
+// necessarily a heuristic (a field like `column.status` legitimately having
+// the value "Status" looks identical to a lazy placeholder) so it WARNs,
+// never FAILs, exactly like every other semantic lint in this file — a
+// human/agent reviews each WARN and decides whether the real copy already
+// happens to match, same posture as `lintPageSemantics`/`lintDataServiceSemantics`.
+function extractI18nKeyRefs(node, out) {
+  if (Array.isArray(node)) { for (const v of node) extractI18nKeyRefs(v, out); return; }
+  if (!node || typeof node !== "object") return;
+  const KEY_PROPS = ["labelKey", "headerKey", "textKey", "titleKey", "displayNameKey", "descriptionKey"];
+  for (const [k, v] of Object.entries(node)) {
+    if (KEY_PROPS.includes(k)) {
+      // Every block property in this contract is wrapped
+      // {"source":"static"|"binding"|"expression", "value"/"binding":...} —
+      // a bare string here would mean a hand-authored page skipped the
+      // wrapper, so both shapes are accepted defensively.
+      if (typeof v === "string" && v.length > 0) out.add(v);
+      else if (v && typeof v === "object" && v.source === "static" && typeof v.value === "string" && v.value.length > 0) out.add(v.value);
+    }
+    extractI18nKeyRefs(v, out);
+  }
+}
+function mechanicalPlaceholder(key, value) {
+  const lastSegment = key.split(".").pop();
+  // Only camelCase-compound tails ending in a known abbreviation/compound
+  // suffix (Btn, Heading, Msg, Label, Toast) are worth flagging — these are
+  // the shapes that actually shipped as real regressions ("newBtn" -> "New
+  // Btn", "distributionHeading" -> "Distribution Heading"). A single plain
+  // word tail ("status" -> "Status", "category" -> "Category") is normal,
+  // correct field-label copy, not a placeholder bug — never flagged.
+  if (!/[a-z](Btn|Heading|Msg|Label|Toast)$/.test(lastSegment)) return false;
+  const words = lastSegment
+    .replace(/([a-z0-9])([A-Z])/g, "$1 $2") // camelCase -> spaced
+    .replace(/[_-]+/g, " ")
+    .trim()
+    .split(/\s+/)
+    .filter(Boolean);
+  if (words.length < 2) return false;
+  const mechanical = words.map((w) => w.charAt(0).toUpperCase() + w.slice(1).toLowerCase()).join(" ");
+  return value === mechanical;
+}
+// showToast's `message` config is LITERAL display text — never resolved through i18n
+// (only labelKey/headerKey/textKey/titleKey/displayNameKey/descriptionKey are). Authoring
+// a dotted key there (e.g. "my-plugin.page.toast.saved") renders that raw key string to the
+// user verbatim, with no error anywhere pre-deploy — found live authoring hcm-communications
+// (25 occurrences across all 5 pages, invisible until a real Playwright click surfaced the
+// raw key text in a toast). Flag any showToast `message` that both looks like a dotted key
+// AND actually resolves in this plugin's own i18n map (strong signal of exactly this mistake,
+// not a coincidental literal string with dots in it).
+function extractToastMessageMistakes(node, i18nKeys, warnings) {
+  if (Array.isArray(node)) { for (const v of node) extractToastMessageMistakes(v, i18nKeys, warnings); return; }
+  if (!node || typeof node !== "object") return;
+  if (node.type === "showToast" && node.config && typeof node.config.message === "string") {
+    const msg = node.config.message;
+    if (/^[a-z][a-z0-9-]*(\.[a-zA-Z0-9_-]+){2,}$/.test(msg) && i18nKeys.has(msg)) {
+      warnings.push(`WARN [i18n-toast-key-not-resolved] showToast config.message = "${msg}" looks like an i18n key and one exists with that name in metadata/i18n/*.json, but showToast's "message" is literal display text (no i18n lookup) — it will render as the raw key string "${msg}" to the user. Use the actual text directly, e.g. ${JSON.stringify(i18nKeys.get(msg))}.`);
+    }
+  }
+  for (const v of Object.values(node)) extractToastMessageMistakes(v, i18nKeys, warnings);
+}
+function lintI18nSemantics(pageJson, i18nKeys) {
+  const warnings = [];
+  extractToastMessageMistakes(pageJson.rows || pageJson.definition?.rows || pageJson, i18nKeys, warnings);
+  const refs = new Set();
+  extractI18nKeyRefs(pageJson.rows || pageJson.definition?.rows || pageJson, refs);
+  const topLevel = pageJson.definition || pageJson;
+  if (typeof topLevel.title === "string") refs.add(topLevel.title);
+  if (topLevel.designer) {
+    for (const k of ["displayNameKey", "descriptionKey"]) {
+      if (typeof topLevel.designer[k] === "string") refs.add(topLevel.designer[k]);
+    }
+  }
+  for (const key of refs) {
+    if (!i18nKeys.has(key)) {
+      warnings.push(`WARN [i18n-missing-key] page references i18n key "${key}" which has no entry in metadata/i18n/*.json — will render as a raw ⟦${key}⟧ placeholder at runtime.`);
+      continue;
+    }
+    const value = i18nKeys.get(key);
+    if (typeof value === "string" && mechanicalPlaceholder(key, value)) {
+      warnings.push(`WARN [i18n-placeholder] "${key}" = ${JSON.stringify(value)} looks like a mechanically Title-Cased key tail, not real copy (the "New Btn"/"X Heading" regression class) — consider a real label ("New Btn" -> "New Allowance", "X Heading" -> real section heading).`);
+    }
+  }
+  return warnings;
+}
+function loadI18nKeys(absDir) {
+  const i18nDir = path.join(absDir, "metadata", "i18n");
+  const map = new Map();
+  let files = [];
+  try { files = readdirSync(i18nDir).filter((f) => f.endsWith(".json")); } catch { return map; }
+  for (const f of files) {
+    try {
+      const j = JSON.parse(readFileSync(path.join(i18nDir, f), "utf8"));
+      for (const [k, v] of Object.entries(j)) if (!map.has(k)) map.set(k, v);
+    } catch { /* malformed locale file — reported separately, not this lint's job */ }
+  }
+  return map;
+}
+
+// lintPageDataSourceSemantics — PAGE-DS-001 [REAL, added 2026-09-04] closes
+// the exact gap disclosed in
+// ai/domains/ai-native-developer-platform-gap-analysis.md's "core.grid's
+// real data-source wiring" section: `core.grid`'s own block-property
+// contract has NO `dataSource`/`entity`/`recordType` property at all — the
+// real wiring is a PAGE-level top-level `"metadata": {"dataSource":
+// "<provider-name>"}` field (a sibling of "definition", not nested inside
+// it). A page with a core.grid block that omits/empties this field, or
+// names a provider that doesn't resolve, silently renders "0 rows" with
+// ZERO error — this shipped for real, three separate times, on the
+// hcm-employee-documents plugin alone before a live Playwright run caught
+// it. `erp plugin test`/`erp validate`/`erp workflow validate` all passed
+// cleanly every one of those times; this is the static, pre-deploy check
+// that would have caught it — same "validation, not just runtime
+// debugging" posture DS-001/I18N-001 already established.
+//
+// Two checks:
+//   1. [page-ds-missing] — a page whose rows (INCLUDING every responsive
+//      variant's own rows) contain a core.grid block instance, but whose
+//      top-level metadata.dataSource is missing or an empty string.
+//   2. [page-ds-unresolved] — metadata.dataSource IS set, but no
+//      metadata/provider/*.json file (same plugin, or any OTHER already-
+//      shipped plugin under backend/modules/ — a cross-plugin provider is
+//      a real, valid case) has a "name" field matching it byte-for-byte.
+// Both WARN, not FAIL, for the same reason every other semantic lint in
+// this file does: a provider genuinely supplied by an install-time/runtime
+// mechanism this static scan can't see is a legitimate (if rare) exception,
+// and a human/agent should review each warning rather than have the build
+// hard-fail on it.
+function pageHasCoreGrid(pageJson) {
+  let found = false;
+  (function walk(node) {
+    if (found || !node || typeof node !== "object") return;
+    if (node.blockType === "core.grid") { found = true; return; }
+    for (const v of Object.values(node)) {
+      if (found) return;
+      if (Array.isArray(v)) v.forEach(walk);
+      else if (v && typeof v === "object") walk(v);
+    }
+  })(pageJson);
+  return found;
+}
+function lintPageDataSourceSemantics(pageJson, providerNamesSamePlugin, providerNamesRepoWide) {
+  const warnings = [];
+  if (!pageHasCoreGrid(pageJson)) return warnings;
+  const dataSource = pageJson.metadata?.dataSource;
+  if (typeof dataSource !== "string" || dataSource.length === 0) {
+    warnings.push(
+      `WARN [page-ds-missing] page has a core.grid block but its top-level "metadata.dataSource" is missing/empty — ` +
+        `the grid has no provider to resolve, so it will silently render 0 rows at runtime with NO error (not a ` +
+        `validation failure). Set metadata.dataSource to a real metadata/provider/*.json "name". See ai/patterns/grid-data-source-wiring.md.`,
+    );
+    return warnings;
+  }
+  const resolvedSamePlugin = providerNamesSamePlugin.has(dataSource);
+  const resolvedElsewhere = providerNamesRepoWide?.has(dataSource) ?? false;
+  if (!resolvedSamePlugin && !resolvedElsewhere) {
+    warnings.push(
+      `WARN [page-ds-unresolved] page's metadata.dataSource "${dataSource}" does not match any metadata/provider/*.json ` +
+        `"name" field in this plugin (checked every other shipped plugin under backend/modules/ too, still unresolved) — ` +
+        `a byte-for-byte name mismatch here produces the identical silent "0 rows, no error" symptom as a missing dataSource. ` +
+        `See ai/patterns/grid-data-source-wiring.md.`,
+    );
+  }
+  return warnings;
+}
+function loadProviderNamesFrom(providerDir) {
+  const names = new Set();
+  let files = [];
+  try { files = readdirSync(providerDir).filter((f) => f.endsWith(".json")); } catch { return names; }
+  for (const f of files) {
+    try {
+      const j = JSON.parse(readFileSync(path.join(providerDir, f), "utf8"));
+      if (typeof j.name === "string" && j.name.length > 0) names.add(j.name);
+    } catch { /* malformed provider file — not this lint's job */ }
+  }
+  return names;
+}
+// Cheap, cache-once, purely local (no live API call — an honest scope trim
+// disclosed in the gap-analysis doc's own PAGE-DS-001 item 2) scan of every
+// OTHER already-shipped plugin's own provider names, so a real cross-plugin
+// dataSource reference isn't false-flagged as unresolved.
+let _allRepoProviderNamesCache = null;
+function loadAllRepoProviderNames() {
+  if (_allRepoProviderNamesCache) return _allRepoProviderNamesCache;
+  const names = new Set();
+  const modulesDir = path.join(REPO_ROOT, "backend", "modules");
+  let moduleDirs = [];
+  try { moduleDirs = readdirSync(modulesDir, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name); } catch { /* not a full checkout */ }
+  for (const m of moduleDirs) {
+    const providerDir = path.join(modulesDir, m, "spk-assembly", "metadata", "provider");
+    for (const n of loadProviderNamesFrom(providerDir)) names.add(n);
+  }
+  _allRepoProviderNamesCache = names;
+  return names;
+}
+
+// lintJobContributionUsage — JOB-001 [REAL, added 2026-09-04] — standing rule
+// [[feedback-json-first-scheduled-jobs]] / ai/domains/project-generic-erp-job-engine-target-architecture.md:
+// "one generic config-driven sweep handler, not a job class per need." A new
+// bespoke `@Extension implements ErpJobContribution` class is the sanctioned
+// escape hatch for genuinely complex job logic (same "Java is the escape
+// hatch for real complexity" posture as everywhere else in this codebase),
+// but it should be a deliberate choice, not a silent default — this makes
+// that tradeoff visible in `erp plugin test` output instead of only living
+// in a human's memory of the standing rule. Scan is deliberately a plain
+// regex over each plugin's OWN `src/main/java/**/*.java` (same rigor as
+// PAGE-DS-001/DS-001/I18N-001 — no AST, no "is this logic complex enough"
+// classifier; that judgment call is for the reader, per the warning's own
+// message). WARN, not FAIL — several real jobs in this codebase (the
+// *EffectiveDateJob family, generic sweep engines themselves) legitimately
+// need custom Java; this only asks the author to have actually considered
+// the JSON-first alternative first.
+function lintJobContributionUsage(javaDir) {
+  const warnings = [];
+  const javaFiles = walkFilesFiltered(javaDir, (name) => name.endsWith(".java"));
+  for (const file of javaFiles) {
+    let src;
+    try { src = readFileSync(file, "utf8"); } catch { continue; }
+    if (!/\bimplements\b[^{;]*\bErpJobContribution\b/.test(src)) continue;
+    const classMatch = src.match(/\bclass\s+(\w+)\s+implements\b[^{;]*\bErpJobContribution\b/);
+    const className = classMatch ? classMatch[1] : path.basename(file, ".java");
+    warnings.push(
+      `WARN [JOB-001] New scheduled-job class found: \`${className}\` (${path.relative(REPO_ROOT, file)}). Prefer a JSON job ` +
+        `definition against the generic sweep engine (see ai/domains/project-generic-erp-job-engine-target-architecture.md / ` +
+        `[[feedback-json-first-scheduled-jobs]] — e.g. EntityStatusDateSweepJob's entity_status_date_sweep_config for an ` +
+        `"entity status/date -> flip a field" shape, WorkflowReminderSweepJob's workflow_reminder_config for a "remind on a ` +
+        `stale workflow task" shape) unless this job's logic is genuinely too complex to express declaratively — if so, ` +
+        `document why in a comment on the class.`,
+    );
+  }
+  return warnings;
+}
+
+async function pluginTestCommand(dir) {
+  requireMonorepo("erp plugin test");
+  // [REAL, narrow] — the doc's own §10 mockup ("Schema validation / Page
+  // validation / Permission validation / ... 42 passed"). This runs the
+  // REAL checks that exist today (page schema+semantics via
+  // validate-page-properties.mjs, plugin.json JSON-validity) and reports
+  // them in that shape; checks the doc lists that have no real engine yet
+  // (workflow validation beyond structural JSON, security-rule scanning,
+  // responsive-configuration linting, AI-tool-permission checks, full
+  // regression tests) are reported as SKIPPED, not fabricated as passing.
+  const absDir = path.resolve(dir);
+  const mod = await import(pathToFileURL(path.join(REPO_ROOT, "tools/page-validator/validate-page-properties.mjs")).href);
+  const registry = await mod.buildRegistry();
+  const pageDir = path.join(absDir, "metadata", "page");
+  let pageFiles = [];
+  try {
+    pageFiles = readdirSync(pageDir).filter((f) => f.endsWith(".json"));
+  } catch { /* no pages */ }
+  let passed = 0, failed = 0, warned = 0;
+  const results = [];
+  const i18nKeys = loadI18nKeys(absDir);
+  const providerNamesSamePlugin = loadProviderNamesFrom(path.join(absDir, "metadata", "provider"));
+  for (const f of pageFiles) {
+    const issues = mod.validatePage(path.join(pageDir, f), registry);
+    if (issues.length === 0) { passed++; results.push({ check: `page:${f}`, status: "PASS" }); }
+    else { failed++; results.push({ check: `page:${f}`, status: "FAIL", issues }); }
+    // page-semantic-lint (2026-09-03, REAL — replaces the old always-SKIPPED
+    // "responsive-configuration-lint" placeholder below with an actual check):
+    // catches schema-valid-but-semantically-wrong field choices (plain text
+    // instead of core.lookup/core.date-picker, decorative filter bars) — see
+    // lintPageSemantics' own doc comment for the exact bug class this closes.
+    try {
+      const pageJson = JSON.parse(readFileSync(path.join(pageDir, f), "utf8"));
+      const entityTypes = loadEntityFieldTypes(absDir, pageJson.metadata?.entityDefinition);
+      const warnings = lintPageSemantics(pageJson, entityTypes);
+      if (warnings.length > 0) { warned += warnings.length; results.push({ check: `page-semantic-lint:${f}`, status: "WARN", issues: warnings }); }
+    } catch (e) {
+      results.push({ check: `page-semantic-lint:${f}`, status: "SKIPPED", note: `could not lint: ${e.message}` });
+    }
+    // i18n-semantic-lint (I18N-001, 2026-09-03, REAL) — see lintI18nSemantics'
+    // own doc comment for the exact bug class this catches pre-deploy: a
+    // page referencing an i18n key with no en.json entry (renders as a raw
+    // ⟦key⟧ at runtime), or a mechanically Title-Cased placeholder value.
+    try {
+      const pageJson = JSON.parse(readFileSync(path.join(pageDir, f), "utf8"));
+      const warnings = lintI18nSemantics(pageJson, i18nKeys);
+      if (warnings.length > 0) { warned += warnings.length; results.push({ check: `i18n-semantic-lint:${f}`, status: "WARN", issues: warnings }); }
+    } catch (e) {
+      results.push({ check: `i18n-semantic-lint:${f}`, status: "SKIPPED", note: `could not lint: ${e.message}` });
+    }
+    // page-datasource-lint (PAGE-DS-001, 2026-09-04, REAL) — see
+    // lintPageDataSourceSemantics' own doc comment for the exact bug class
+    // this catches pre-deploy: a core.grid block whose page never sets (or
+    // mis-names) the page-level metadata.dataSource that actually wires it
+    // to a real Data Provider — silently 0 rows, no error, at runtime.
+    try {
+      const pageJson = JSON.parse(readFileSync(path.join(pageDir, f), "utf8"));
+      const warnings = lintPageDataSourceSemantics(pageJson, providerNamesSamePlugin, loadAllRepoProviderNames());
+      if (warnings.length > 0) { warned += warnings.length; results.push({ check: `page-datasource-lint:${f}`, status: "WARN", issues: warnings }); }
+    } catch (e) {
+      results.push({ check: `page-datasource-lint:${f}`, status: "SKIPPED", note: `could not lint: ${e.message}` });
+    }
+  }
+  // data-service-semantic-lint (2026-09-04, REAL) — see lintDataServiceSemantics'
+  // own doc comment for the exact bug class this catches pre-deploy.
+  const dsDir = path.join(absDir, "metadata", "data_service");
+  let dsFiles = [];
+  try {
+    dsFiles = readdirSync(dsDir).filter((f) => f.endsWith(".json"));
+  } catch { /* no data services */ }
+  for (const f of dsFiles) {
+    try {
+      const dsJson = JSON.parse(readFileSync(path.join(dsDir, f), "utf8"));
+      const entityName = dsJson.definition?.source?.kind === "entity" ? dsJson.definition.source.entityName : null;
+      const entityTypes = loadEntityFieldTypes(absDir, entityName);
+      const warnings = lintDataServiceSemantics(dsJson, entityTypes);
+      if (warnings.length > 0) { warned += warnings.length; results.push({ check: `data-service-semantic-lint:${f}`, status: "WARN", issues: warnings }); }
+    } catch (e) {
+      results.push({ check: `data-service-semantic-lint:${f}`, status: "SKIPPED", note: `could not lint: ${e.message}` });
+    }
+  }
+  // job-contribution-lint (JOB-001, 2026-09-04, REAL) — see
+  // lintJobContributionUsage's own doc comment for the standing rule this
+  // makes visible pre-deploy: a new bespoke ErpJobContribution class instead
+  // of a JSON job definition against an already-generic sweep engine.
+  const javaDir = path.join(absDir, "..", "src", "main", "java");
+  try {
+    const warnings = lintJobContributionUsage(javaDir);
+    if (warnings.length > 0) { warned += warnings.length; results.push({ check: "job-contribution-lint", status: "WARN", issues: warnings }); }
+  } catch (e) {
+    results.push({ check: "job-contribution-lint", status: "SKIPPED", note: `could not lint: ${e.message}` });
+  }
+  const manifestPath = path.join(absDir, "plugin.json");
+  if (existsSync(manifestPath)) {
+    try {
+      JSON.parse(readFileSync(manifestPath, "utf8"));
+      passed++; results.push({ check: "plugin.json:valid-json", status: "PASS" });
+    } catch (e) {
+      failed++; results.push({ check: "plugin.json:valid-json", status: "FAIL", issues: [e.message] });
+    }
+  }
+  for (const skipped of ["security-rule-scan", "ai-tool-permission-check", "regression-suite"]) {
+    results.push({ check: skipped, status: "SKIPPED", note: "no real engine for this check exists yet — see ai/domains/ai-native-developer-platform-gap-analysis.md" });
+  }
+  console.log(`Plugin Tests`);
+  console.log("─".repeat(40));
+  for (const r of results) {
+    const icon = r.status === "PASS" ? "✓" : r.status === "FAIL" ? "✗" : r.status === "WARN" ? "⚠" : "○";
+    console.log(`${icon} ${r.check}${r.status === "FAIL" || r.status === "WARN" ? " — " + JSON.stringify(r.issues, null, 2) : ""}`);
+  }
+  console.log("");
+  const skipped = results.filter((r) => r.status === "SKIPPED").length;
+  console.log(`${passed} passed, ${failed} failed, ${warned} semantic warning(s), ${skipped} skipped`);
+  if (failed > 0) process.exitCode = 1;
+}
+
+// erp plugin publish-frontend — dynamic frontend-plugin-loading (2026-09-03)
+// [REAL] — uploads a plugin's compiled, self-contained browser bundle
+// (`<frontend-package>/dist/browser.js`, see `tools/erp-code-plugin-compiler`'s
+// sibling doc `ai/patterns/code-plugin-sdk.md` for the tsup/esbuild `alias`
+// convention that bundle must be built with) via the real, generic
+// `engine-file` upload endpoint (`POST /api/v1/files`), stamps the resulting
+// real fileId onto `<backend-module-dir>/spk-assembly/plugin.json`'s new
+// `frontendBundle` field, repackages the module (`spark package`), and
+// re-installs it via the real, already-existing upgrade path (`POST
+// /api/v1/authoring/plugins/{pluginId}/upload`) — no new install/upgrade
+// mechanism invented, every step reuses a real, pre-existing endpoint.
+async function pluginPublishFrontendCommand(backendModuleDir, opts) {
+  const cfg = loadConfig();
+  const env = currentEnv(cfg);
+  const session = cfg.sessions?.[env.name];
+  const baseUrl = opts.url || env.baseUrl;
+  const tenantId = String(opts.tenant || session?.tenantId || 2);
+  const actor = opts.actor || session?.userId || "erp-cli";
+  const authHeaders = session?.sessionToken
+    ? { "X-Session-Token": session.sessionToken, Authorization: `Bearer ${session.accessToken}` }
+    : {};
+
+  const absDir = path.resolve(backendModuleDir);
+  const manifestPath = path.join(absDir, "spk-assembly", "plugin.json");
+  if (!existsSync(manifestPath)) throw new Error(`no spk-assembly/plugin.json found under ${absDir}`);
+  const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+
+  const frontendPkgDir = opts.frontendDir
+    ? path.resolve(opts.frontendDir)
+    : path.join(REPO_ROOT, "frontend/packages", manifest.id);
+  const bundlePath = path.join(frontendPkgDir, "dist", "browser.js");
+  if (!existsSync(bundlePath)) {
+    throw new Error(
+      `no browser bundle at ${bundlePath} — build it first (e.g. \`pnpm --filter <pkg> build:browser\`), ` +
+        `producing a self-contained ESM bundle per ai/patterns/code-plugin-sdk.md's dynamic-loading convention`,
+    );
+  }
+  const bundleBytes = readFileSync(bundlePath);
+
+  console.log(`Uploading ${bundlePath} (${bundleBytes.length} bytes) to ${baseUrl}/api/v1/files (cabinet ${opts.cabinetId})...`);
+  const uploadForm = new FormData();
+  uploadForm.set("cabinetId", String(opts.cabinetId));
+  uploadForm.set("file", new Blob([bundleBytes], { type: "text/javascript" }), `${manifest.id}-browser.js`);
+  const uploadRes = await fetch(`${baseUrl}/api/v1/files`, {
+    method: "POST",
+    headers: { "X-Tenant-Id": tenantId, "X-Actor": actor, ...authHeaders },
+    body: uploadForm,
+  });
+  const uploadText = await uploadRes.text();
+  if (!uploadRes.ok) throw new Error(`file upload failed: HTTP ${uploadRes.status} — ${uploadText}`);
+  const fileId = String(JSON.parse(uploadText).id);
+  console.log(`Uploaded — fileId ${fileId}.`);
+
+  manifest.frontendBundle = { fileId, entrypointExport: opts.entrypointExport || "default" };
+  if (opts.bumpVersion !== false) {
+    const parts = String(manifest.version).split(".").map(Number);
+    parts[2] = (parts[2] || 0) + 1;
+    manifest.version = parts.join(".");
+  }
+  writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + "\n");
+  console.log(`Stamped frontendBundle onto ${manifestPath} (version now ${manifest.version}).`);
+
+  const spkPath = path.join(os.tmpdir(), `${manifest.id}-${manifest.version}.spk`);
+  runSpark(["package", path.join(absDir, "spk-assembly"), "-o", spkPath]);
+  if (!existsSync(spkPath)) throw new Error(`spark package did not produce ${spkPath}`);
+
+  console.log(`Upgrading "${manifest.id}" via ${baseUrl}/api/v1/authoring/plugins/${manifest.id}/upload...`);
+  const spkForm = new FormData();
+  spkForm.set("file", new Blob([readFileSync(spkPath)]), path.basename(spkPath));
+  const upgradeRes = await fetch(`${baseUrl}/api/v1/authoring/plugins/${encodeURIComponent(manifest.id)}/upload`, {
+    method: "POST",
+    headers: { "X-Tenant-Id": tenantId, "X-Actor": actor, ...authHeaders },
+    body: spkForm,
+  });
+  const upgradeText = await upgradeRes.text();
+  if (!upgradeRes.ok) throw new Error(`plugin upgrade failed: HTTP ${upgradeRes.status} — ${upgradeText}`);
+  console.log(`Upgraded:`);
+  console.log(upgradeText);
+}
+
+// laptop -> VPS: publishes to the configured env's base_url with a device-flow
+// access token (never a hardcoded localhost:8080). `--env <name>` targets a
+// specific configured env; `--url` still overrides outright; ERP_TOKEN works for CI.
+async function pluginPublishCommand(target, opts) {
+  const cfg = loadConfig();
+  if (opts.env) {
+    if (!cfg.envs[opts.env]) throw new Error(`unknown env "${opts.env}" — run: erp env list`);
+    cfg.currentEnv = opts.env;
+  }
+  const env = currentEnv(cfg);
+  const session = cfg.sessions?.[env.name];
+  const h = await authHeaders(cfg, { tenantIdOverride: opts.tenant });
+  const bearer = process.env.ERP_TOKEN || session?.accessToken;
+  if (!bearer && !opts.dryRun) {
+    throw new Error(`not logged in to env "${env.name}" — run \`erp login\` (or set ERP_TOKEN) before publishing.`);
+  }
+  const args = ["publish", target, "--url", opts.url || env.baseUrl, "--tenant", h["X-Tenant-Id"]];
+  if (opts.actor || session?.userId) args.push("--actor", opts.actor || session.userId);
+  if (session?.sessionToken) args.push("--session", session.sessionToken);
+  if (bearer) args.push("--bearer", bearer);
+  if (opts.dryRun) args.push("--dry-run");
+  console.log(`erp plugin publish: ${target} -> ${opts.url || env.baseUrl} (env "${env.name}", tenant ${h["X-Tenant-Id"]})`);
+  if (opts.force) args.push("--force");
+  runSpark(args);
+}
+
+// erp plugin force-unload <id> — rough-edge (b) recovery. Force-clears a
+// WEDGED fleet-wide PF4J load (plugin still STARTED in-process while its
+// install row is already `uninstalled`) without a backend restart. Safe and
+// idempotent when nothing is actually wedged.
+async function pluginForceUnloadCommand(pluginId, opts) {
+  if (!pluginId) throw new Error("usage: erp plugin force-unload <pluginId> [--tenant <id>]");
+  const cfg = loadConfig();
+  const result = await api(cfg, "POST", `/api/v1/authoring/plugins/${encodeURIComponent(pluginId)}/force-unload`, {
+    tenantIdOverride: opts.tenant,
+  });
+  console.log(JSON.stringify(result, null, 2));
+  if (result?.loaded) {
+    console.log(`\nWARNING: "${pluginId}" is still loaded (pf4jState=${result.pf4jState}). A backend restart may be needed.`);
+    process.exitCode = 1;
+  } else {
+    console.log(`\n"${pluginId}" is now cleared from PF4J (pf4jState=${result.pf4jState}). Re-publish to reinstall.`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// erp workflow list / instance / tasks / history — [REAL] live inspection of
+// a running workflow instance, against engine-api's own base URL. In this
+// deployment engine-workflow's REST runs as a separate service, so these hit
+// the read-proxy engine-api re-exposes at /api/v1/workflows/* (see
+// WorkflowReadProxyController). No workflow-service URL needed.
+// ---------------------------------------------------------------------------
+async function workflowListCommand(opts) {
+  const definition = opts.definition || opts.def;
+  if (!definition) throw new Error("usage: erp workflow list --definition <workflowName> [--record <id>] [--tenant <id>]");
+  const cfg = loadConfig();
+  const instances = await api(cfg, "GET", `/api/v1/workflows/instances?definitionName=${encodeURIComponent(definition)}`, {
+    tenantIdOverride: opts.tenant,
+  });
+  let rows = Array.isArray(instances) ? instances : [];
+  if (opts.record != null && opts.record !== true) {
+    const needle = String(opts.record);
+    const matched = [];
+    for (const i of rows) {
+      const id = i.instanceId ?? i.id;
+      let detail = i;
+      try {
+        detail = await api(cfg, "GET", `/api/v1/workflows/instances/${encodeURIComponent(id)}`, { tenantIdOverride: opts.tenant });
+      } catch {
+        /* fall back to the summary row */
+      }
+      const ctx = detail.context || detail.contextJson || {};
+      const idFieldName = (typeof ctx === "object" && ctx.idField) || "id";
+      const ctxId = typeof ctx === "object" ? ctx[idFieldName] : undefined;
+      const corr = String(i.correlationId ?? "");
+      if (
+        String(ctxId ?? "") === needle ||
+        corr === needle ||
+        corr.endsWith(`:${needle}`) ||
+        JSON.stringify(ctx).includes(`"${needle}"`)
+      ) {
+        matched.push({ ...i, context: typeof ctx === "object" ? ctx : undefined });
+      }
+    }
+    rows = matched;
+  }
+  console.log(JSON.stringify(rows, null, 2));
+  console.log(`\n${rows.length} instance(s)${opts.record && opts.record !== true ? ` for record ${opts.record}` : ""} of "${definition}".`);
+}
+
+async function workflowInstanceCommand(instanceId, opts) {
+  if (!instanceId) throw new Error("usage: erp workflow instance <instanceId> [--tenant <id>]");
+  const cfg = loadConfig();
+  const instance = await api(cfg, "GET", `/api/v1/workflows/instances/${encodeURIComponent(instanceId)}`, { tenantIdOverride: opts.tenant });
+  console.log(JSON.stringify(instance, null, 2));
+}
+
+async function workflowTasksCommand(instanceId, opts) {
+  if (!instanceId) throw new Error("usage: erp workflow tasks <instanceId> [--tenant <id>]");
+  const cfg = loadConfig();
+  const tasks = await api(cfg, "GET", `/api/v1/workflows/instances/${encodeURIComponent(instanceId)}/human-tasks`, { tenantIdOverride: opts.tenant });
+  console.log(JSON.stringify(tasks, null, 2));
+}
+
+async function workflowHistoryCommand(instanceId, opts) {
+  if (!instanceId) throw new Error("usage: erp workflow history <instanceId> [--tenant <id>]");
+  const cfg = loadConfig();
+  const history = await api(cfg, "GET", `/api/v1/workflows/instances/${encodeURIComponent(instanceId)}/history`, { tenantIdOverride: opts.tenant });
+  console.log(JSON.stringify(history, null, 2));
+}
+
+// ---------------------------------------------------------------------------
+// erp schema pull / erp schema validate
+// [REAL] — the exact same schema map the MCP server (tools/erp-mcp-server)
+// serves, reused here so `erp schema pull` and Claude Code's MCP tool call
+// return byte-identical schemas — one source of truth, not two.
+// ---------------------------------------------------------------------------
+// Derived from the shared SCHEMA_REGISTRY (tools/erp-cli/authoring-root.mjs) so
+// the CLI, the MCP server, and the bundle emitter can never carry drifted copies.
+// dashboard: no separate schema — a dashboard's definitionJson is the same
+// PageDefinition shape as `page`; use `page`.
+const SCHEMA_FILES = Object.fromEntries(Object.entries(SCHEMA_REGISTRY).map(([k, v]) => [k, v.file]));
+
+function schemaPullCommand(name, opts) {
+  const rel = SCHEMA_FILES[name];
+  if (!rel) throw new Error(`unknown schema "${name}". Known: ${Object.keys(SCHEMA_FILES).join(", ")}`);
+  const content = readFileSync(schemaPathByName(name), "utf8");
+  const outPath = opts.out || `${name}.schema.json`;
+  writeFileSync(outPath, content, "utf8");
+  console.log(`Wrote ${outPath}`);
+}
+
+async function schemaValidateCommand(file, opts) {
+  if (!opts.schema) throw new Error("usage: erp schema validate <file> --schema <name>");
+  const rel = SCHEMA_FILES[opts.schema];
+  if (!rel) throw new Error(`unknown schema "${opts.schema}". Known: ${Object.keys(SCHEMA_FILES).join(", ")}`);
+  const schema = JSON.parse(readFileSync(schemaPathByName(opts.schema), "utf8"));
+  const data = JSON.parse(readFileSync(file, "utf8"));
+  const issues = simpleSchemaCheck(data, schema, "$");
+  if (issues.length === 0) console.log(`OK — ${file} matches schema "${opts.schema}"`);
+  else {
+    console.log(`FAIL — ${file} against schema "${opts.schema}"`);
+    for (const i of issues) console.log(`  ${i}`);
+    process.exitCode = 1;
+  }
+}
+
+/** A deliberately small structural checker (required/type/enum only) — NOT a full
+ * draft-07 implementation. [THIN, disclosed]: a complete JSON-Schema validator
+ * (oneOf/allOf/$ref/pattern/etc.) is a real, separate library-shaped undertaking;
+ * pulling in an npm dependency (ajv) would be the right real fix but conflicts
+ * with this tool family's own zero-new-dependency, standalone-script convention
+ * — flagged here as the one place that convention costs real completeness. */
+function simpleSchemaCheck(data, schema, pathLabel) {
+  const issues = [];
+  if (schema.required) {
+    for (const req of schema.required) {
+      if (data == null || !(req in data)) issues.push(`${pathLabel}: missing required property "${req}"`);
+    }
+  }
+  if (schema.type === "object" && schema.properties && data && typeof data === "object") {
+    for (const [key, value] of Object.entries(data)) {
+      const propSchema = schema.properties[key];
+      if (propSchema?.enum && !propSchema.enum.includes(value)) {
+        issues.push(`${pathLabel}.${key}: "${value}" not in allowed values [${propSchema.enum.join(", ")}]`);
+      }
+    }
+  }
+  return issues;
+}
+
+// ---------------------------------------------------------------------------
+// erp workflow validate / erp workflow test
+// [REAL, narrow] structural check against workflow-definition.schema.json
+// plus a real graph check (every transition's from/to is a declared stage,
+// every stage is reachable from the first). Not a live engine-workflow
+// dry-run (that needs a real tenant+DB instance) — disclosed.
+// ---------------------------------------------------------------------------
+/** Parses the REAL on-disk shape — stagesJson/tasksJson/transitionsJson are
+ * themselves JSON-encoded strings (confirmed against live shipped files,
+ * e.g. employee.transfer.json), not nested objects. See
+ * workflow-definition.schema.json's own $comment for why. */
+function parseWorkflowArtifact(file) {
+  const raw = JSON.parse(readFileSync(file, "utf8"));
+  return {
+    raw,
+    stages: JSON.parse(raw.stagesJson || "[]"),
+    tasks: JSON.parse(raw.tasksJson || "[]"),
+    transitions: JSON.parse(raw.transitionsJson || "[]"),
+    approvalPermissions: raw.approvalPermissions || [],
+  };
+}
+
+function workflowValidateCommand(file) {
+  const schema = JSON.parse(readFileSync(schemaPathByName("workflow-definition"), "utf8"));
+  const raw = JSON.parse(readFileSync(file, "utf8"));
+  const issues = simpleSchemaCheck(raw, schema, "$");
+  let def;
+  try {
+    def = parseWorkflowArtifact(file);
+  } catch (e) {
+    issues.push(`one of stagesJson/tasksJson/transitionsJson is not valid JSON: ${e.message}`);
+  }
+  if (def) {
+    const stages = new Set(def.stages);
+    for (const t of def.transitions) {
+      if (!stages.has(t.fromStage)) issues.push(`transition references unknown "fromStage" "${t.fromStage}"`);
+      if (!stages.has(t.toStage)) issues.push(`transition references unknown "toStage" "${t.toStage}"`);
+    }
+    for (const task of def.tasks) {
+      if (!stages.has(task.stage)) issues.push(`task "${task.taskKey}" references unknown stage "${task.stage}"`);
+    }
+    const approvalObjects = new Set(def.tasks.map((t) => t.payload?.approvalObject).filter(Boolean));
+    for (const perm of def.approvalPermissions) {
+      if (!approvalObjects.has(perm.approvalObject)) issues.push(`approvalPermissions entry references unknown approvalObject "${perm.approvalObject}" (no task declares it)`);
+    }
+  }
+  if (issues.length === 0) console.log(`OK — ${file}`);
+  else { console.log(`FAIL — ${file}`); for (const i of issues) console.log(`  ${i}`); process.exitCode = 1; }
+}
+
+function workflowTestCommand(file) {
+  const def = parseWorkflowArtifact(file);
+  console.log(`Workflow "${def.raw.name}" — ${def.stages.length} stage(s): ${def.stages.join(" → ")}`);
+  const reachable = new Set([def.stages[0]]);
+  let changed = true;
+  while (changed) {
+    changed = false;
+    for (const t of def.transitions) {
+      if (reachable.has(t.fromStage) && !reachable.has(t.toStage)) { reachable.add(t.toStage); changed = true; }
+    }
+  }
+  const unreachable = def.stages.filter((s) => !reachable.has(s));
+  if (unreachable.length > 0) {
+    console.log(`FAIL — unreachable stage(s) from "${def.stages[0]}": ${unreachable.join(", ")}`);
+    process.exitCode = 1;
+  } else {
+    console.log(`OK — every stage reachable from "${def.stages[0]}"`);
+  }
+  const noTransitionOut = def.stages.filter((s) => !def.transitions.some((t) => t.fromStage === s));
+  console.log(`Stage(s) with no outgoing transition (instance completes here): ${noTransitionOut.join(", ") || "(none)"}`);
+  for (const stage of def.stages) {
+    const perms = def.approvalPermissions.filter((p) => def.tasks.some((t) => t.stage === stage && t.payload?.approvalObject === p.approvalObject));
+    console.log(`  stage "${stage}": approvers = ${perms.map((p) => p.roleCode).join(", ") || "(none declared)"}`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// erp connector create/validate/list/test — [REAL, added 2026-09-04] the
+// SDK/CLI-only authoring surface for engine-provider-connector's generic
+// external_provider_definition rows (backend/platform-runtime/engine-provider-connector).
+// Mirrors `erp workflow validate/test`'s split: `validate` is a pure local
+// schema check (connector-definition.schema.json), `create` PUTs the
+// validated file to the real backend (ExternalProviderDefinitionController),
+// `list` and `test` are real authenticated calls against that same live
+// endpoint via the shared `api()` helper — no hand-typed curl for any of
+// this, matching the standing SDK-CLI-only rule.
+// ---------------------------------------------------------------------------
+function connectorValidateFile(file) {
+  const schema = JSON.parse(readFileSync(schemaPathByName("connector-definition"), "utf8"));
+  const data = JSON.parse(readFileSync(file, "utf8"));
+  const issues = simpleSchemaCheck(data, schema, "$");
+  if (data.connectorKind === "HTTP" && !data.baseUrl) issues.push('connectorKind="HTTP" requires "baseUrl"');
+  return { data, issues };
+}
+
+function connectorValidateCommand(file) {
+  const { issues } = connectorValidateFile(file);
+  if (issues.length === 0) console.log(`OK — ${file} matches schema "connector-definition"`);
+  else { console.log(`FAIL — ${file}`); for (const i of issues) console.log(`  ${i}`); process.exitCode = 1; }
+}
+
+async function connectorCreateCommand(file, opts) {
+  const { data, issues } = connectorValidateFile(file);
+  if (issues.length > 0) {
+    console.log(`FAIL — ${file} did not pass connector-definition validation, not sending to backend`);
+    for (const i of issues) console.log(`  ${i}`);
+    process.exitCode = 1;
+    return;
+  }
+  const cfg = loadConfig();
+  currentSession(cfg);
+  const { domain, providerKey, ...body } = data;
+  const result = await api(cfg, "PUT", `/api/v1/provider-connectors/definitions/${encodeURIComponent(domain)}/${encodeURIComponent(providerKey)}`,
+    { body, tenantIdOverride: opts.tenant });
+  console.log(JSON.stringify(result, null, 2));
+}
+
+async function connectorListCommand(opts) {
+  if (!opts.domain) throw new Error("usage: erp connector list --domain <domain>");
+  const cfg = loadConfig();
+  currentSession(cfg);
+  const result = await api(cfg, "GET", `/api/v1/provider-connectors/definitions?domain=${encodeURIComponent(opts.domain)}`, { tenantIdOverride: opts.tenant });
+  console.log(JSON.stringify(result, null, 2));
+}
+
+async function connectorTestCommand(domain, providerKey, opts) {
+  if (!domain || !providerKey) throw new Error("usage: erp connector test <domain> <providerKey> [--body <json-string-or-@file>]");
+  const cfg = loadConfig();
+  currentSession(cfg);
+  let fieldValues = {};
+  if (opts.body) {
+    const raw = opts.body.startsWith("@") ? readFileSync(opts.body.slice(1), "utf8") : opts.body;
+    fieldValues = JSON.parse(raw);
+  }
+  const result = await api(cfg, "POST", `/api/v1/provider-connectors/definitions/${encodeURIComponent(domain)}/${encodeURIComponent(providerKey)}/invoke`,
+    { body: { fieldValues }, tenantIdOverride: opts.tenant });
+  console.log(JSON.stringify(result, null, 2));
+}
+
+// ---------------------------------------------------------------------------
+// erp docs search — thin wrapper reusing the same walk the MCP server uses.
+// [FIXED 2026-09-04, real gap] — this used to grep ONLY hand-written
+// ai/domains/*.md narrative docs, with zero way to check a doc's claim
+// against the actual platform-runtime source. That let a false "no
+// report-builder infrastructure exists anywhere in this codebase" claim
+// propagate unverified across five module docs even though a real
+// ReportDefinitionService/BiReportDefinitionService engine existed the whole
+// time. Every result is now labeled `[ai/domains doc]` (a human-curated
+// narrative claim — may be stale) or `[live engine-* source]` (mechanically
+// re-derived from `erp platform catalog`, just scanned — cannot be stale in
+// the same way) so a search never again returns ONLY the possibly-stale half.
+// ---------------------------------------------------------------------------
+function docsSearchCommand(query) {
+  const hits = [];
+  for (const root of docsSearchRoots()) {
+    (function walk(dir) {
+      let entries;
+      try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return; }
+      for (const e of entries) {
+        const full = path.join(dir, e.name);
+        if (e.isDirectory()) walk(full);
+        else if (e.name.endsWith(".md")) {
+          const lines = readFileSync(full, "utf8").split("\n");
+          lines.forEach((line, i) => { if (line.toLowerCase().includes(query.toLowerCase())) hits.push(`[${root.source}] ${path.relative(root.relBase, full)}:${i + 1}: ${line.trim()}`); });
+        }
+      }
+    })(root.dir);
+  }
+
+  let engineHits = [];
+  try {
+    engineHits = searchEngineCatalog(query).hits.map((h) => {
+      const loc = h.file ? ` (${h.file})` : "";
+      const label = h.kind === "java-contract" ? "[java contract]" : "[live engine-* source]";
+      return `${label} ${h.engine}: ${h.kind} \`${h.match}\`${loc}`;
+    });
+  } catch (e) {
+    engineHits = [`[live engine-* source] (catalog unavailable: ${e.message})`];
+  }
+
+  const out = [...hits.slice(0, 30), ...engineHits.slice(0, 30)];
+  console.log(out.join("\n") || "(no matches)");
+}
+
+// ---------------------------------------------------------------------------
+// erp examples search — [REAL, added 2026-09-03] real shipped metadata JSON
+// (page/workflow/entities/provider) across every backend/modules/* plugin,
+// matched by filename or plugin name. This is the exact same logic as the
+// MCP server's `erp_search_examples` tool (tools/erp-mcp-server/index.mjs) —
+// added here as a pure-CLI mirror because a developer working strictly
+// through the CLI (no MCP client available, or the MCP server not wired in)
+// had no way to discover real precedent for authoring a WorkflowDefinition
+// (or any other kind) without reading another plugin's source directly.
+// `erp docs search` only greps ai/*.md narrative docs — it never searched
+// shipped example JSON, which is the actual gap this closes.
+// ---------------------------------------------------------------------------
+// ---------------------------------------------------------------------------
+// erp examples patterns — [REAL, added 2026-09-03] a curated catalog of named
+// SHAPES (not just filenames) for the kinds a developer most often has to
+// reinvent from scratch, each pointing at a real shipped file confirmed to
+// actually have that shape (grep-verified against the file's own
+// stagesJson/transitionsJson at the time this catalog was written — if a
+// referenced file is ever deleted/renamed, `erp examples patterns` degrades
+// to printing the pattern description without a dead path, it never throws).
+// This exists because `erp examples search <term>` returns every filename
+// matching a substring, which still requires reading N files to find the
+// ONE real precedent for e.g. "single-actor self-decide workflow" — this
+// catalog names that shape directly.
+// ---------------------------------------------------------------------------
+
+
+function examplesPatternsCommand(opts) {
+  const kind = opts.kind;
+  const kinds = kind ? [kind] : Object.keys(EXAMPLE_PATTERNS);
+  for (const k of kinds) {
+    const patterns = EXAMPLE_PATTERNS[k];
+    if (!patterns) { console.log(`(no curated patterns for kind "${k}" — known kinds: ${Object.keys(EXAMPLE_PATTERNS).join(", ")})`); continue; }
+    console.log(`\n== ${k} ==`);
+    for (const p of patterns) {
+      const exists = existsSync(exampleFileAbs(p.file));
+      console.log(`\n[${p.name}]${exists ? "" : " (referenced file missing — repo may have moved/renamed it since this catalog was written)"}`);
+      console.log(p.description);
+      console.log(`Real example: ${p.file}`);
+    }
+  }
+  console.log("");
+}
+
+// ---------------------------------------------------------------------------
+// erp menu create — [REAL, added 2026-09-03, closes a real gap] `spark create`
+// makes an empty spk-assembly/metadata/menu/ directory but writes zero starter
+// content, and there was no way at all to add a NEW menu artifact to an
+// EXISTING plugin without hand-writing the full nested MenuNode shape from
+// memory (id/name/displayName/sequence/children/navigation/visibility all
+// required per backend/platform-runtime/schema/menu-definition.schema.json).
+// This scaffolds one real, schema-valid root node — disabled by default (a
+// developer must deliberately flip visibility.enabled + set navigation.route
+// once a real page exists, same convention every shipped module's own
+// pre-build menu stub already follows) — into <pluginDir>/spk-assembly/
+// metadata/menu/<menuId>.json, refusing to overwrite an existing file.
+// ---------------------------------------------------------------------------
+function menuCreateCommand(pluginDir, menuId, opts) {
+  if (!pluginDir || !menuId) throw new Error("usage: erp menu create <plugin-dir> <menu-id> [--display-name <name>] [--route <path>] [--icon <name>]");
+  const menuDir = path.join(path.resolve(pluginDir), "spk-assembly", "metadata", "menu");
+  const outPath = path.join(menuDir, `${menuId}.json`);
+  if (existsSync(outPath)) throw new Error(`${outPath} already exists — refusing to overwrite. Edit it directly, or pick a different menu id.`);
+  if (!existsSync(menuDir)) mkdirSync(menuDir, { recursive: true });
+  const displayName = opts.displayName || menuId.replace(/[-.]/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
+  const rootNodeId = `${menuId}.root`;
+  const menu = {
+    name: menuId,
+    description: `Scaffolded by \`erp menu create\`. One disabled root node — set navigation.route and flip visibility.enabled once a real page exists at that route.`,
+    definition: {
+      contractVersion: 1,
+      name: menuId,
+      description: null,
+      tags: [],
+      nodes: [
+        {
+          id: rootNodeId,
+          name: menuId.split(/[.-]/).pop(),
+          displayName,
+          displayNameKey: null,
+          description: null,
+          icon: opts.icon || null,
+          color: null,
+          tags: [],
+          sequence: 1,
+          children: [],
+          navigation: { route: opts.route || null, targetPage: null, openMode: "current-tab", externalUrl: null },
+          visibility: { visible: true, enabled: Boolean(opts.route), devices: [] }
+        }
+      ]
+    },
+    metadata: {},
+    modules: []
+  };
+  writeFileSync(outPath, JSON.stringify(menu, null, 2) + "\n", "utf8");
+  console.log(`Wrote ${outPath}`);
+  console.log(`  Root node id: ${rootNodeId}${opts.route ? ` (route: ${opts.route}, enabled)` : " (no --route given — visibility.enabled left false; set navigation.route and flip it true once a real page exists)"}`);
+  console.log(`  Validate: node tools/erp-cli/erp.mjs schema validate ${outPath} --schema menu`);
+}
+
+function examplesSearchCommand(pattern, opts) {
+  if (!pattern) throw new Error("usage: erp examples search <pattern> [--kind page|workflow|entities|provider|data-service|data-view|rules|menu]");
+  const kind = opts.kind || "page";
+  // 2026-09-03, real gap found and fixed: data-service/data-view/rules/menu were
+  // entirely unsearchable — a developer looking for a real "employee search lookup"
+  // Data Service precedent (the exact core.lookup optionsSourceKey recipe) had no way
+  // to find one via this command at all, even though the shipped directory
+  // (spk-assembly/metadata/data_service/) has real examples in multiple modules.
+  const kindDirs = { page: "page", workflow: "workflow", entities: "entities", provider: "provider", "data-service": "data_service", "data-view": "data_view", rules: "rules", menu: "menu" };
+  const sub = kindDirs[kind];
+  if (!sub) throw new Error(`unknown kind "${kind}". Known kinds: ${Object.keys(kindDirs).join(", ")}`);
+  const modulesDir = examplesModulesRoot();
+  let moduleDirs;
+  try {
+    moduleDirs = readdirSync(modulesDir, { withFileTypes: true }).filter((d) => d.isDirectory());
+  } catch {
+    console.log("(no backend/modules directory found)");
+    return;
+  }
+  const p = pattern.toLowerCase();
+  const results = [];
+  const maxResults = Number(opts.max || 10);
+  for (const mod of moduleDirs) {
+    const target = path.join(modulesDir, mod.name, "spk-assembly", "metadata", sub);
+    let files;
+    try {
+      files = readdirSync(target).filter((f) => f.endsWith(".json"));
+    } catch {
+      continue;
+    }
+    for (const f of files) {
+      if (f.toLowerCase().includes(p) || mod.name.toLowerCase().includes(p)) {
+        results.push(path.join("backend", "modules", path.relative(modulesDir, path.join(target, f))).replace(/\\/g, "/"));
+      }
+      if (results.length >= maxResults) break;
+    }
+    if (results.length >= maxResults) break;
+  }
+  console.log(results.length ? results.join("\n") : `(no ${kind} examples matched "${pattern}" — try a broader pattern or a different --kind: ${Object.keys(kindDirs).join(", ")})`);
+}
+
+// ---------------------------------------------------------------------------
+// erp blocks list — [REAL, added 2026-09-04] the real widget/block catalog,
+// derived directly from @erp/block-engine's own `coreBlockTypes()` registry
+// (frontend/packages/block-engine/dist/index.js — the built dist, same
+// resolution convention as block-adapter-mui's own dist-only requirement),
+// never hand-maintained. Real gap found and fixed: before this, a developer
+// building a plugin purely through this CLI/MCP had NO way to discover "what
+// widgets exist and what properties/events does each one accept" without
+// either already knowing a widget's name (to `erp examples search` for real
+// usage) or reading block-engine source directly — a real violation of the
+// standing "SDK/CLI-only discovery, never read platform source" rule this
+// exact gap forced developers into. `erp_list_schemas`/`erp_get_schema`'s
+// `block-definition`/`block-instance` schemas only describe the GENERIC
+// contract shape every block instance must follow, not a per-type catalog of
+// the ~124 real registered types (core.grid, core.lookup, core.date-picker,
+// core.file-upload, etc.) and what each specifically accepts.
+//
+// `coreBlockTypes()` takes several optional runtime data-source arguments
+// (gridDataSource, selectOptionsSource, ...) that only affect each entry's
+// `.logic` (the live behavior) — calling it with none supplied still returns
+// every entry's full `.definition` (properties/events/outputs/designer
+// metadata), which is all this catalog needs; `.logic` is deliberately never
+// touched or invoked here.
+// ---------------------------------------------------------------------------
+async function loadBlockDefinitions() {
+  // Packaged mode: the frozen blocks.json in the authoring bundle (emitted by
+  // `erp bundle build` from this same registry). Monorepo mode: derived live
+  // from @erp/block-engine's own built dist.
+  const catalogPath = blocksCatalogPath();
+  if (catalogPath) {
+    return JSON.parse(readFileSync(catalogPath, "utf8"));
+  }
+  const mod = await import(blockEngineModuleUrl());
+  return mod.coreBlockTypes().map((bt) => bt.definition);
+}
+
+function summarizeBlockDefinition(def) {
+  return {
+    type: def.type,
+    category: def.designer?.category ?? null,
+    displayNameKey: def.designer?.displayNameKey ?? null,
+    descriptionKey: def.designer?.descriptionKey ?? null,
+    icon: def.designer?.icon ?? null,
+    allowedTargets: def.designer?.allowedTargets ?? [],
+    inputClass: !!def.inputClass,
+    properties: (def.properties ?? []).map((p) => ({
+      name: p.name,
+      type: p.type,
+      sources: p.sources ?? [],
+      editor: p.designer?.editor ?? null,
+    })),
+    outputs: (def.outputs ?? []).map((o) => ({ name: o.name, type: o.type })),
+    events: (def.events ?? []).map((e) => ({ name: e.name, catalogType: e.catalogType ?? null })),
+  };
+}
+
+async function blocksListCommand(opts) {
+  const defs = await loadBlockDefinitions();
+  let filtered = defs;
+  if (opts.type) {
+    const needle = opts.type.toLowerCase();
+    filtered = filtered.filter((d) => d.type.toLowerCase().includes(needle));
+  }
+  if (opts.category) {
+    const needle = opts.category.toLowerCase();
+    filtered = filtered.filter((d) => (d.designer?.category ?? "").toLowerCase() === needle);
+  }
+  if (filtered.length === 0) {
+    console.log(`(no block type matched — ${defs.length} total registered; try a broader --type substring or omit --category)`);
+    return;
+  }
+  if (opts.type && filtered.length === 1) {
+    // A single exact-ish match: print the FULL definition (every property's
+    // designer group/labelKey, every event's full shape) — the detail a
+    // developer actually needs when they already know which widget they want.
+    console.log(JSON.stringify(filtered[0], null, 2));
+    return;
+  }
+  console.log(`${filtered.length} block type(s)${opts.type ? ` matching "${opts.type}"` : ""}${opts.category ? ` in category "${opts.category}"` : ""} (of ${defs.length} total):\n`);
+  for (const def of filtered.map(summarizeBlockDefinition)) {
+    const propNames = def.properties.map((p) => `${p.name}:${p.type}`).join(", ") || "(none)";
+    const eventNames = def.events.map((e) => e.name).join(", ") || "(none)";
+    console.log(`${def.type}  [${def.category ?? "uncategorized"}]`);
+    console.log(`  properties: ${propNames}`);
+    console.log(`  events:     ${eventNames}`);
+    console.log(`  targets:    ${def.allowedTargets.join(", ") || "(unrestricted)"}`);
+    console.log("");
+  }
+  console.log(`Pass --type <exact-or-partial-name> for one type's full definition (all designer/labelKey detail), e.g. \`erp blocks list --type core.lookup\`.`);
+}
+
+// ---------------------------------------------------------------------------
+// erp ai init / erp mcp install
+// [REAL] — scaffolds a plugin's ai/ subtree (agents.json/tools.json/
+// prompts.json, per the doc's own plugin layout) and ensures a .mcp.json
+// pointing at tools/erp-mcp-server exists at the invoking directory.
+// ---------------------------------------------------------------------------
+function aiInitCommand(dir) {
+  const target = dir || process.cwd();
+  const aiDir = path.join(target, "ai");
+  mkdirSync(aiDir, { recursive: true });
+  const files = {
+    "agents.json": { agents: [] },
+    "tools.json": { tools: [] },
+    "prompts.json": { prompts: [] },
+  };
+  for (const [name, content] of Object.entries(files)) {
+    const fp = path.join(aiDir, name);
+    if (!existsSync(fp)) writeFileSync(fp, JSON.stringify(content, null, 2) + "\n", "utf8");
+  }
+  console.log(`Scaffolded ${aiDir}/{agents,tools,prompts}.json`);
+}
+
+function mcpInstallCommand(opts) {
+  const target = opts.dir || process.cwd();
+  const mcpPath = path.join(target, ".mcp.json");
+  // erp-mcp-server/index.mjs is always this file's sibling directory — true
+  // in the monorepo (tools/erp-cli + tools/erp-mcp-server under tools/) AND
+  // in a packaged @erp/plugin-sdk install (erp-cli/ + erp-mcp-server/ under
+  // the package root) — so resolve relative to __dirname, never REPO_ROOT,
+  // which is meaningless once this file is npm-installed outside the repo.
+  const mcpEntryAbs = path.join(__dirname, "..", "erp-mcp-server", "index.mjs");
+  const entry = { command: "node", args: [path.relative(target, mcpEntryAbs).replace(/\\/g, "/")] };
+  let cfg = { mcpServers: {} };
+  if (existsSync(mcpPath)) cfg = JSON.parse(readFileSync(mcpPath, "utf8"));
+  cfg.mcpServers = cfg.mcpServers || {};
+  cfg.mcpServers["erp-plugin-language"] = entry;
+  writeFileSync(mcpPath, JSON.stringify(cfg, null, 2) + "\n", "utf8");
+  console.log(`Wrote/updated ${mcpPath}`);
+}
+
+// ===========================================================================
+// erp bundle build — the authoring-bundle emitter
+// ---------------------------------------------------------------------------
+// Produces a single self-contained directory (erp-authoring-bundle/) holding
+// everything the MCP server + CLI need to ground a third-party plugin
+// developer who has NO access to the platform monorepo, and NOTHING secret.
+//
+// CLASSIFICATION BOUNDARY = the secret-code boundary. A file enters the bundle
+// only if it is on the explicit allowlist below AND (if a doc) its frontmatter
+// says `audience: tenant` or `audience: all`. Everything under ai/, all Java,
+// low-code-docs/, docs-platform/, and any internal gap-analysis doc is excluded.
+// ===========================================================================
+
+// The ONLY things that ever go into the bundle. Grep this list to audit it.
+const BUNDLE_ALLOWLIST = [
+  { name: "schemas", into: "schemas/", from: "SCHEMA_REGISTRY (authoring-root.mjs) — the *.schema.json files only" },
+  { name: "catalog", into: "catalog.json", from: "buildEngineCatalog({refresh:true}) frozen output — the Java source scan runs HERE at build time, never on the client" },
+  { name: "examples", into: "examples/", from: "tools/erp-cli/example-patterns.mjs + the backend/modules/**/metadata/**.json files each pattern references" },
+  { name: "docs", into: "docs/", from: "developer-docs/**/*.md whose frontmatter declares `audience: tenant|all`, plus developer-docs/docs.json" },
+  { name: "blocks", into: "blocks.json", from: "@erp/block-engine coreBlockTypes() .definition list — the ~124 core block property/event contracts, frozen for packaged-mode `erp blocks list` / erp_list_blocks" },
+  { name: "validators", into: "validators/", from: "self-contained esbuild bundles of @erp/block-engine + @erp/page-engine dist entrypoints (every workspace dep inlined) — the REAL validateInstanceConfig/validatePageDefinition, so packaged-mode page validation is the same code, not a re-derivation" },
+  { name: "manifest", into: "manifest.json", from: "generated at build time" },
+];
+
+// Hard denylist — a path matching any of these is NEVER copied, whatever its source.
+const BUNDLE_DENY = [
+  /\.java$/i,
+  /(^|[/\\])ai[/\\]/,
+  /(^|[/\\])low-code-docs[/\\]/,
+  /(^|[/\\])docs-platform[/\\]/,
+  /gap-analysis/i,
+  /\.env(\.|$)/i,
+  /(^|[/\\])src[/\\]main[/\\]java[/\\]/,
+];
+
+function bundleDenied(p) {
+  const s = p.replace(/\\/g, "/");
+  return BUNDLE_DENY.find((re) => re.test(s)) || null;
+}
+
+/** A markdown doc is bundle-public only if its YAML frontmatter says audience: tenant|all. */
+function docAudienceIsPublic(text) {
+  const m = text.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!m) return false;
+  const a = m[1].match(/^\s*audience:\s*["']?([a-z]+)["']?\s*$/im);
+  return !!a && (a[1].toLowerCase() === "tenant" || a[1].toLowerCase() === "all");
+}
+
+function walkAll(dir, out = []) {
+  let entries;
+  try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return out; }
+  for (const e of entries) {
+    const full = path.join(dir, e.name);
+    if (e.isDirectory()) walkAll(full, out);
+    else out.push(full);
+  }
+  return out;
+}
+
+function findExternalRefs(node, acc = []) {
+  if (Array.isArray(node)) node.forEach((n) => findExternalRefs(n, acc));
+  else if (node && typeof node === "object") {
+    for (const [k, v] of Object.entries(node)) {
+      if (k === "$ref" && typeof v === "string" && !v.startsWith("#")) acc.push(v);
+      else findExternalRefs(v, acc);
+    }
+  }
+  return acc;
+}
+
+function copyInto(srcAbs, destAbs) {
+  const deny = bundleDenied(srcAbs);
+  if (deny) throw new Error(`refusing to bundle ${srcAbs} — matches denylist ${deny}`);
+  mkdirSync(path.dirname(destAbs), { recursive: true });
+  copyFileSync(srcAbs, destAbs);
+}
+
+function dirSizeBytes(dir) {
+  return walkAll(dir).reduce((n, f) => n + statSync(f).size, 0);
+}
+
+/**
+ * esbuild one frontend engine's dist entrypoint into a single self-contained
+ * ESM file (every @erp/* workspace dep inlined) so packaged-mode SDK installs
+ * run the REAL validators with no repo, no npm install, no build step. esbuild
+ * is resolved from frontend/node_modules — only reached in monorepo mode
+ * (`erp bundle build` is requireMonorepo), where it is always present.
+ */
+async function esbuildEngine(engineRelDir, outFileAbs) {
+  const pkgDir = path.join(REPO_ROOT, engineRelDir);
+  const entry = path.join(pkgDir, "dist", "index.js");
+  if (!existsSync(entry)) throw new Error(`${engineRelDir}/dist/index.js not found — build the frontend packages first.`);
+  const pnpmRoot = path.join(REPO_ROOT, "frontend", "node_modules", ".pnpm");
+  let esbuildMain = null;
+  try {
+    esbuildMain = readdirSync(pnpmRoot)
+      .filter((d) => /^esbuild@/.test(d))
+      .map((d) => path.join(pnpmRoot, d, "node_modules", "esbuild", "lib", "main.js"))
+      .find((p) => existsSync(p));
+  } catch { /* no pnpm store */ }
+  if (!esbuildMain) throw new Error(`esbuild not found under ${pnpmRoot} — run \`pnpm install\` in frontend/ first.`);
+  const esbuild = await import(pathToFileURL(esbuildMain).href);
+  await esbuild.build({
+    entryPoints: [entry],
+    bundle: true,
+    format: "esm",
+    platform: "node",
+    absWorkingDir: pkgDir,
+    outfile: outFileAbs,
+    logLevel: "silent",
+    banner: { js: "// GENERATED by `erp bundle build` (esbuild of @erp/*-engine dist) — do not edit." },
+  });
+  return statSync(outFileAbs).size;
+}
+
+async function bundleBuildCommand(opts) {
+  requireMonorepo("erp bundle build");
+  const outDir = opts.out ? path.resolve(opts.out) : bundleDir();
+  const t0 = Date.now();
+  console.log(`Building authoring bundle -> ${outDir}`);
+
+  // Wipe the generated subtree (never touches anything outside outDir).
+  for (const sub of ["schemas", "examples", "docs", "validators", "blocks.json", "catalog.json", "manifest.json", "README.md"]) {
+    const p = path.join(outDir, sub);
+    if (existsSync(p)) rmSync(p, { recursive: true, force: true });
+  }
+  mkdirSync(outDir, { recursive: true });
+
+  // 1. schemas/
+  const externalRefFlags = [];
+  let schemaCount = 0;
+  for (const [name, entry] of Object.entries(SCHEMA_REGISTRY)) {
+    const srcAbs = path.join(REPO_ROOT, entry.file);
+    const raw = readFileSync(srcAbs, "utf8");
+    const ext = findExternalRefs(JSON.parse(raw));
+    if (ext.length) externalRefFlags.push({ schema: name, externalRefs: [...new Set(ext)] });
+    if (bundleDenied(srcAbs)) throw new Error(`schema ${name} source is denylisted: ${srcAbs}`);
+    mkdirSync(path.join(outDir, "schemas"), { recursive: true });
+    writeFileSync(path.join(outDir, "schemas", `${name}.schema.json`), raw, "utf8");
+    schemaCount++;
+  }
+
+  // 2. catalog.json — the frozen engine-capability catalog. THE JAVA SCAN RUNS HERE.
+  const catalog = buildEngineCatalog({ refresh: true });
+  writeFileSync(path.join(outDir, "catalog.json"), JSON.stringify(catalog, null, 2), "utf8");
+
+  // 3. examples/ — the curated pattern data + every real file it references.
+  copyInto(path.join(__dirname, "example-patterns.mjs"), path.join(outDir, "examples", "example-patterns.mjs"));
+  let exampleFileCount = 0;
+  const missingExamples = [];
+  for (const patterns of Object.values(EXAMPLE_PATTERNS)) {
+    for (const p of patterns) {
+      const srcAbs = path.join(REPO_ROOT, p.file);
+      if (!existsSync(srcAbs)) { missingExamples.push(p.file); continue; }
+      copyInto(srcAbs, path.join(outDir, "examples", p.file));
+      exampleFileCount++;
+    }
+  }
+
+  // 4. docs/ — ONLY developer-docs/*.md with audience: tenant|all.
+  const devDocsRoot = path.join(REPO_ROOT, "developer-docs");
+  let docCount = 0;
+  const skippedDocs = [];
+  if (existsSync(devDocsRoot)) {
+    for (const abs of walkAll(devDocsRoot)) {
+      const rel = path.relative(devDocsRoot, abs);
+      if (path.basename(abs) === "docs.json") { copyInto(abs, path.join(outDir, "docs", rel)); continue; }
+      if (!abs.endsWith(".md")) continue;
+      if (bundleDenied(abs)) { skippedDocs.push(rel + " (denylist)"); continue; }
+      if (!docAudienceIsPublic(readFileSync(abs, "utf8"))) { skippedDocs.push(rel + " (no audience: tenant|all)"); continue; }
+      copyInto(abs, path.join(outDir, "docs", rel));
+      docCount++;
+    }
+  }
+
+  // 5. blocks.json — the frozen core block catalog (property/event contracts).
+  let blockCount = 0;
+  {
+    const defs = (await import(blockEngineModuleUrl())).coreBlockTypes().map((bt) => bt.definition);
+    blockCount = defs.length;
+    writeFileSync(path.join(outDir, "blocks.json"), JSON.stringify(defs, null, 2), "utf8");
+  }
+
+  // 6. validators/ — self-contained esbuild of the two real engine validators.
+  mkdirSync(path.join(outDir, "validators"), { recursive: true });
+  const blockValidatorBytes = await esbuildEngine("frontend/packages/block-engine", path.join(outDir, "validators", "block-engine.mjs"));
+  const pageValidatorBytes = await esbuildEngine("frontend/packages/page-engine", path.join(outDir, "validators", "page-engine.mjs"));
+
+  // 7. manifest.json
+  const manifest = {
+    bundleVersion: opts.bundleVersion || new Date().toISOString().slice(0, 10) + ".1",
+    platformVersion: detectPlatformVersion(),
+    generatedAt: new Date().toISOString(),
+    generatedBy: "erp bundle build (tools/erp-cli/erp.mjs bundleBuildCommand)",
+    schemaCount,
+    docCount,
+    exampleFileCount,
+    blockCount,
+    catalogGeneratedAt: catalog.generatedAt,
+    catalogEngineCount: catalog.engineCount,
+    catalogContractUnitCount: catalog.contracts?.unitCount ?? 0,
+    sdkMode: "packaged",
+  };
+  writeFileSync(path.join(outDir, "manifest.json"), JSON.stringify(manifest, null, 2), "utf8");
+
+  writeFileSync(
+    path.join(outDir, "README.md"),
+    `# erp-authoring-bundle (generated)\n\nGenerated by \`erp bundle build\`. Do not hand-edit. This is the offline grounding\nthe ERP plugin SDK (CLI + MCP server) reads when \`ERP_SDK_MODE=packaged\` or no\nplatform repo is present. Contains ONLY tenant-public material — see\n\`BUNDLE_ALLOWLIST\` / \`BUNDLE_DENY\` in tools/erp-cli/erp.mjs.\n\n- schemas/     ${schemaCount} JSON Schemas\n- catalog.json engine-capability catalog, frozen at build time (no client-side Java scan)\n- examples/    curated pattern catalog + ${exampleFileCount} referenced real files\n- blocks.json  ${blockCount} core block property/event contracts\n- validators/  self-contained esbuild of @erp/block-engine + @erp/page-engine (real page validation, packaged mode)\n- docs/        ${docCount} tenant-public developer docs\n- live/        (populated by \`erp env sync\` from a deployed env — installed entity + theme names)\n- manifest.json\n`,
+    "utf8",
+  );
+
+  // 6. Verify. HARD FAIL: any file in the bundle that IS a .java file, or whose
+  // path is denylisted (i.e. an internal doc/source file got copied in).
+  // ADVISORY only: a public schema/example whose text merely *mentions* an
+  // internal doc path in a $comment/doc-string — a pointer, not leaked content.
+  const leaks = [];
+  const advisories = [];
+  for (const abs of walkAll(outDir)) {
+    const rel = path.relative(outDir, abs).replace(/\\/g, "/");
+    if (rel === "catalog.json" || rel === "manifest.json") continue; // catalog legitimately names .java contract files
+    const deny = bundleDenied(rel);
+    if (deny) { leaks.push(`${rel} (path matches ${deny})`); continue; }
+    if (/\.(json|md|mjs)$/.test(rel)) {
+      const txt = readFileSync(abs, "utf8");
+      if (/\bai\/(domains|platform)\//.test(txt)) advisories.push(`${rel} references an ai/ doc path in its text`);
+      if (/gap-analysis/i.test(txt)) advisories.push(`${rel} mentions "gap-analysis" in its text`);
+    }
+  }
+
+  const bytes = dirSizeBytes(outDir);
+  console.log(`\nBundle built in ${Date.now() - t0}ms`);
+  console.log(`  schemas:       ${schemaCount}`);
+  console.log(`  catalog:       ${catalog.engineCount} engines, ${catalog.contracts?.unitCount ?? 0} contract units (frozen ${catalog.generatedAt})`);
+  console.log(`  example files: ${exampleFileCount}${missingExamples.length ? ` (missing: ${missingExamples.join(", ")})` : ""}`);
+  console.log(`  blocks.json:   ${blockCount} core block definitions`);
+  console.log(`  validators:    block-engine.mjs ${(blockValidatorBytes / 1024).toFixed(0)} KiB, page-engine.mjs ${(pageValidatorBytes / 1024).toFixed(0)} KiB (self-contained esbuild)`);
+  console.log(`  docs:          ${docCount} public${skippedDocs.length ? `, ${skippedDocs.length} skipped` : ""}`);
+  if (skippedDocs.length) skippedDocs.forEach((d) => console.log(`     - skipped ${d}`));
+  if (externalRefFlags.length) {
+    console.log(`  WARNING external $refs (must be inlined before shipping):`);
+    externalRefFlags.forEach((f) => console.log(`     - ${f.schema}: ${f.externalRefs.join(", ")}`));
+  } else {
+    console.log(`  external $refs: none (all schemas self-contained)`);
+  }
+  console.log(`  total size:    ${(bytes / 1024).toFixed(1)} KiB`);
+  if (advisories.length) {
+    console.log(`  advisory (public files that mention an internal doc path — pointer, not leaked content):`);
+    advisories.forEach((a) => console.log(`     - ${a}`));
+  }
+  if (leaks.length) {
+    console.log(`\nFAIL — a .java file or denylisted path leaked into the bundle:`);
+    leaks.forEach((l) => console.log(`  - ${l}`));
+    process.exitCode = 1;
+  } else {
+    console.log(`\nOK — no .java files, no denylisted paths in the bundle (catalog.json's contract-file references excepted).`);
+  }
+}
+
+function detectPlatformVersion() {
+  for (const rel of ["frontend/package.json", "package.json"]) {
+    try {
+      const j = JSON.parse(readFileSync(path.join(REPO_ROOT, rel), "utf8"));
+      if (j.version) return j.version;
+    } catch { /* keep looking */ }
+  }
+  try {
+    return spawnSync("git", ["-C", REPO_ROOT, "rev-parse", "--short", "HEAD"], { encoding: "utf8" }).stdout.trim() || "unknown";
+  } catch { return "unknown"; }
+}
+
+// ---------------------------------------------------------------------------
+// erp env sync — pull this environment's authoring bundle from the deployed
+// GET /api/v1/dev/bundle (DevBundleController, engine-api) and extract it into
+// the packaged-mode cache overlay ~/.erp/cache/<envKey>/ that authoring-root.mjs
+// reads first. `--check` = manifest only, report drift, download nothing.
+//
+// envKey: ERP_ENV_KEY if set (per-env isolation), else "default" — matching
+// authoring-root.mjs's cacheDir(). The URL slug is printed so it can be set.
+// ---------------------------------------------------------------------------
+function envSlug(baseUrl) {
+  return baseUrl.replace(/^https?:\/\//, "").replace(/[^a-zA-Z0-9]+/g, "-").replace(/^-+|-+$/g, "").toLowerCase() || "env";
+}
+
+async function envSyncCommand(opts = {}) {
+  const cfg = loadConfig();
+  const env = currentEnv(cfg);
+  const base = env.baseUrl.replace(/\/$/, "");
+  const tenantId = String(cfg.sessions?.[env.name]?.tenantId ?? 2);
+  // Gated behind a device-flow access token (or ERP_TOKEN) — DevBundleController
+  // resolves the tenant from the token claim. Falls back to a bare X-Tenant-Id
+  // only against a monorepo/dev backend that sets erp.dev-bundle.allow-tenant-header.
+  const headers = await authHeaders(cfg, { tenantIdOverride: tenantId });
+  const unauthedHint = () => {
+    console.log(`  -> run \`erp login\` first (this environment requires an authenticated SDK), or set ERP_TOKEN for CI.`);
+    process.exitCode = 1;
+  };
+  const slug = envSlug(base);
+  const cache = cacheDir();
+
+  const localManifest = readManifest();
+  const localBundleVersion = localManifest?.bundleVersion ?? "(none)";
+
+  const manifestUrl = `${base}/api/v1/dev/bundle/manifest`;
+  console.log(`erp env sync: ${env.name} (${base}) — tenant ${tenantId}, cache key "${process.env.ERP_ENV_KEY || "default"}" (url slug: ${slug})`);
+
+  let mres;
+  try {
+    mres = await fetch(manifestUrl, { headers });
+  } catch (e) {
+    console.log(`  network error reaching ${manifestUrl}: ${e.cause?.code || e.message}`);
+    console.log(`  Nothing synced. The bundled snapshot at ${bundleDir()} is used as-is.`);
+    process.exitCode = 1;
+    return;
+  }
+  if (mres.status === 404) {
+    console.log(`  this ERP does not expose /api/v1/dev/bundle (HTTP 404) — it predates the DevBundleController, or no bundle is built on it.`);
+    console.log(`  Nothing synced. The bundled snapshot at ${bundleDir()} is used as-is.`);
+    process.exitCode = 1;
+    return;
+  }
+  if (mres.status === 401 || mres.status === 403) {
+    console.log(`  GET /api/v1/dev/bundle/manifest -> HTTP ${mres.status} (not authenticated).`);
+    unauthedHint();
+    return;
+  }
+  if (!mres.ok) {
+    console.log(`  GET /api/v1/dev/bundle/manifest -> HTTP ${mres.status}. Nothing synced.`);
+    process.exitCode = 1;
+    return;
+  }
+  const remoteManifest = await mres.json();
+  const drift = [];
+  if (remoteManifest.bundleVersion !== localBundleVersion) drift.push(`bundleVersion ${localBundleVersion} -> ${remoteManifest.bundleVersion}`);
+  if (remoteManifest.platformVersion !== localManifest?.platformVersion) drift.push(`platformVersion ${localManifest?.platformVersion ?? "(none)"} -> ${remoteManifest.platformVersion}`);
+  if ((remoteManifest.schemaCount ?? 0) !== (localManifest?.schemaCount ?? 0)) drift.push(`schemaCount ${localManifest?.schemaCount ?? 0} -> ${remoteManifest.schemaCount}`);
+  console.log(`  remote manifest: bundleVersion ${remoteManifest.bundleVersion}, platformVersion ${remoteManifest.platformVersion}, ` +
+    `${remoteManifest.schemaCount} schemas, ${remoteManifest.docCount ?? 0} docs, ${remoteManifest.blockCount ?? "?"} blocks; ` +
+    `live: ${remoteManifest.live?.entityCount ?? 0} entities, ${remoteManifest.live?.themeCount ?? 0} themes`);
+  console.log(drift.length ? `  drift vs bundled snapshot: ${drift.join("; ")}` : `  no drift vs the bundled snapshot.`);
+
+  if (opts.check) {
+    console.log(`  --check: manifest only, nothing downloaded.`);
+    return;
+  }
+
+  let bres;
+  try {
+    bres = await fetch(`${base}/api/v1/dev/bundle`, { headers });
+  } catch (e) {
+    console.log(`  network error downloading the bundle: ${e.cause?.code || e.message}`);
+    process.exitCode = 1;
+    return;
+  }
+  if (bres.status === 401 || bres.status === 403) {
+    console.log(`  GET /api/v1/dev/bundle -> HTTP ${bres.status} (not authenticated).`);
+    unauthedHint();
+    return;
+  }
+  if (!bres.ok) {
+    console.log(`  GET /api/v1/dev/bundle -> HTTP ${bres.status}. Nothing extracted.`);
+    process.exitCode = 1;
+    return;
+  }
+  let envelope;
+  try {
+    envelope = await bres.json();
+  } catch (e) {
+    console.log(`  response was not valid JSON (${e.message}) — is something proxying this endpoint? Nothing extracted.`);
+    process.exitCode = 1;
+    return;
+  }
+  if (!envelope || typeof envelope.files !== "object" || !envelope.manifest) {
+    console.log(`  response was not a bundle envelope ({manifest, files}) — nothing extracted.`);
+    process.exitCode = 1;
+    return;
+  }
+
+  // Fresh overlay: wipe the generated subtree under the cache dir, then write.
+  for (const sub of ["schemas", "examples", "docs", "validators", "live", "blocks.json", "catalog.json", "manifest.json"]) {
+    const p = path.join(cache, sub);
+    if (existsSync(p)) rmSync(p, { recursive: true, force: true });
+  }
+  mkdirSync(cache, { recursive: true });
+  let written = 0;
+  let schemaN = 0;
+  let docN = 0;
+  let liveN = 0;
+  for (const [rel, content] of Object.entries(envelope.files)) {
+    if (rel.includes("..") || path.isAbsolute(rel)) continue; // path-traversal guard
+    const dest = path.join(cache, rel);
+    mkdirSync(path.dirname(dest), { recursive: true });
+    writeFileSync(dest, typeof content === "string" ? content : JSON.stringify(content, null, 2), "utf8");
+    written++;
+    if (rel.startsWith("schemas/")) schemaN++;
+    else if (rel.startsWith("docs/") && rel.endsWith(".md")) docN++;
+    else if (rel.startsWith("live/")) liveN++;
+  }
+  writeFileSync(path.join(cache, "manifest.json"), JSON.stringify(envelope.manifest, null, 2), "utf8");
+
+  console.log(`  extracted ${written} files -> ${cache}`);
+  console.log(`    schemas: ${schemaN}, docs: ${docN}, live/: ${liveN}, validators: ${envelope.files["validators/block-engine.mjs"] ? "yes" : "no"}, blocks.json: ${envelope.files["blocks.json"] ? "yes" : "no"}`);
+  console.log(`    platformVersion ${envelope.manifest.platformVersion}, bundleVersion ${envelope.manifest.bundleVersion}`);
+  console.log(`    live entities: ${(envelope.manifest.liveEntityNames || []).length}, live themes: ${(envelope.manifest.liveThemeNames || []).length}`);
+  if (!process.env.ERP_ENV_KEY) {
+    console.log(`  (set ERP_ENV_KEY=${slug} to keep this env's cache separate from other environments.)`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// erp docs gen-reference — turn the bundle's schemas/ into one Markdown page each
+// ---------------------------------------------------------------------------
+function renderSchemaMarkdown(name, schema) {
+  const desc = SCHEMA_REGISTRY[name]?.description || schema.description || "";
+  const lines = [
+    "---",
+    `title: ${name} schema`,
+    "audience: tenant",
+    "generated: true",
+    "---",
+    "",
+    `# \`${name}\` schema`,
+    "",
+    desc,
+    "",
+    `Pull the full JSON Schema: \`erp schema pull ${name}\` &nbsp;·&nbsp; MCP: \`erp_get_schema {"name":"${name}"}\``,
+    "",
+  ];
+  const props = schema.properties && typeof schema.properties === "object" ? schema.properties : null;
+  if (props) {
+    const required = new Set(schema.required || []);
+    lines.push("## Top-level properties", "", "| Property | Type | Required | Notes |", "| --- | --- | --- | --- |");
+    for (const [k, v] of Object.entries(props)) {
+      const type = v.type ? (Array.isArray(v.type) ? v.type.join(" \\| ") : v.type) : v.$ref ? `\`${v.$ref}\`` : v.enum ? "enum" : "—";
+      const notesParts = [];
+      if (v.enum) notesParts.push("one of: " + v.enum.map((e) => `\`${e}\``).join(", "));
+      if (v.description) notesParts.push(String(v.description).replace(/\n+/g, " ").trim());
+      lines.push(`| \`${k}\` | ${type} | ${required.has(k) ? "yes" : ""} | ${notesParts.join(" — ") || ""} |`);
+    }
+    lines.push("");
+  } else {
+    lines.push("_This schema's root is not a plain object (see the full schema for its shape)._", "");
+  }
+  const defs = schema.$defs || schema.definitions;
+  if (defs && Object.keys(defs).length) {
+    lines.push("## Named sub-definitions", "", Object.keys(defs).map((d) => `\`${d}\``).join(", "), "");
+  }
+  return lines.join("\n");
+}
+
+function docsGenReferenceCommand(opts) {
+  const schemasDir = path.join(bundleDir(), "schemas");
+  if (!existsSync(schemasDir)) throw new Error(`no bundle schemas at ${schemasDir} — run \`erp bundle build\` first.`);
+  const outDir = opts.out ? path.resolve(opts.out) : path.join(REPO_ROOT, "developer-docs", "reference");
+  mkdirSync(outDir, { recursive: true });
+  const files = readdirSync(schemasDir).filter((f) => f.endsWith(".schema.json"));
+  const names = [];
+  for (const f of files) {
+    const nm = f.replace(/\.schema\.json$/, "");
+    const schema = JSON.parse(readFileSync(path.join(schemasDir, f), "utf8"));
+    writeFileSync(path.join(outDir, `${nm}.md`), renderSchemaMarkdown(nm, schema) + "\n", "utf8");
+    names.push(nm);
+  }
+  writeFileSync(
+    path.join(outDir, "index.md"),
+    `---\ntitle: Schema reference\naudience: tenant\ngenerated: true\n---\n\n# Schema reference\n\nOne page per authoring artifact schema, generated by \`erp docs gen-reference\` from the SDK authoring bundle. Regenerate after \`erp bundle build\`.\n\n${names.map((n) => `- [\`${n}\`](./${n}.md)`).join("\n")}\n`,
+    "utf8",
+  );
+  console.log(`Wrote ${files.length} reference pages + index.md -> ${outDir}`);
+}
+
+// ---------------------------------------------------------------------------
+// erp docs serve — local dev-preview of developer-docs/, offline.
+// Roots: monorepo -> REPO_ROOT/developer-docs (byte-identical live tree);
+// packaged -> the bundle's own docs/ (bundle/docs, synced overlay first via
+// cacheDir()/docs) so a tenant developer with no repo access can still
+// browse the exact docs their installed SDK shipped with. Renders docs.json's
+// nav as the sidebar (never hand-duplicated) and each .md file via a small
+// dependency-free Markdown-to-HTML pass — good enough for a dev-preview, not
+// a production renderer (the real one is the future hosted website, see
+// low-code-docs/REMOTE-SDK-BATCH-C-D-STATUS.md).
+// ---------------------------------------------------------------------------
+function docsRoot() {
+  if (!isPackaged()) return path.join(REPO_ROOT, "developer-docs");
+  const cache = path.join(cacheDir(), "docs");
+  if (existsSync(cache)) return cache;
+  return path.join(bundleDir(), "docs");
+}
+
+function mdToHtml(md) {
+  // Strip YAML frontmatter, then a minimal Markdown subset: headings, code
+  // fences, links, bold/italic, lists, paragraphs. Not a full CommonMark
+  // implementation — deliberately small, zero deps, for a local dev preview.
+  const body = md.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/, "");
+  const esc = (s) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+  const lines = body.split(/\r?\n/);
+  let html = "";
+  let inCode = false;
+  let inList = false;
+  for (const line of lines) {
+    if (/^```/.test(line)) {
+      inCode = !inCode;
+      html += inCode ? "<pre><code>" : "</code></pre>\n";
+      continue;
+    }
+    if (inCode) { html += esc(line) + "\n"; continue; }
+    const h = line.match(/^(#{1,6})\s+(.*)$/);
+    if (h) {
+      if (inList) { html += "</ul>\n"; inList = false; }
+      html += `<h${h[1].length}>${inlineMd(esc(h[2]))}</h${h[1].length}>\n`;
+      continue;
+    }
+    const li = line.match(/^[-*]\s+(.*)$/);
+    if (li) {
+      if (!inList) { html += "<ul>\n"; inList = true; }
+      html += `<li>${inlineMd(esc(li[1]))}</li>\n`;
+      continue;
+    }
+    if (inList && line.trim() === "") { html += "</ul>\n"; inList = false; continue; }
+    if (line.trim() === "") { html += "\n"; continue; }
+    html += `<p>${inlineMd(esc(line))}</p>\n`;
+  }
+  if (inList) html += "</ul>\n";
+  return html;
+}
+
+function inlineMd(s) {
+  return s
+    .replace(/`([^`]+)`/g, "<code>$1</code>")
+    .replace(/\*\*([^*]+)\*\*/g, "<strong>$1</strong>")
+    .replace(/\[([^\]]+)\]\(([^)]+)\)/g, (m, text, href) => `<a href="${href.replace(/\.md$/, "")}">${text}</a>`);
+}
+
+function docsServeCommand(opts) {
+  const root = docsRoot();
+  if (!existsSync(root)) throw new Error(`no docs at ${root} — in packaged mode run \`erp env sync\`, or ship the bundle's docs/.`);
+  const navPath = path.join(root, "docs.json");
+  const nav = existsSync(navPath) ? JSON.parse(readFileSync(navPath, "utf8")) : { title: "Developer docs", nav: [] };
+  const port = Number(opts.port) || 4400;
+
+  const sidebarHtml = nav.nav
+    .map((section) => `<h4>${section.section}</h4><ul>` +
+      section.items.map((it) => `<li><a href="/${it.path.replace(/\.md$/, "")}">${it.title}</a></li>`).join("") +
+      `</ul>`)
+    .join("\n");
+
+  const page = (title, contentHtml) => `<!doctype html><html><head><meta charset="utf-8">
+<title>${title} — ${nav.title || "ERP Developer Docs"}</title>
+<style>
+body{font-family:system-ui,sans-serif;display:flex;margin:0;color:#1a1a1a;background:#fff}
+nav{width:280px;padding:16px;border-right:1px solid #ddd;height:100vh;overflow:auto;box-sizing:border-box;position:sticky;top:0}
+nav h4{margin:16px 0 4px;font-size:12px;text-transform:uppercase;color:#888}
+nav ul{list-style:none;padding-left:0;margin:0}
+nav li{margin:2px 0}
+nav a{color:#333;text-decoration:none;font-size:13px}
+nav a:hover{text-decoration:underline}
+main{padding:24px 40px;max-width:800px}
+pre{background:#f5f5f5;padding:12px;overflow:auto;border-radius:4px}
+code{background:#f5f5f5;padding:1px 4px;border-radius:3px}
+pre code{background:none;padding:0}
+</style></head><body><nav><h3>${nav.title || "Developer docs"}</h3>${sidebarHtml}</nav><main>${contentHtml}</main></body></html>`;
+
+  const server = http.createServer((req, res) => {
+    const urlPath = decodeURIComponent(req.url.split("?")[0]);
+    if (urlPath === "/") {
+      res.writeHead(200, { "Content-Type": "text/html" });
+      res.end(page("Home", `<h1>${nav.title || "ERP Developer Docs"}</h1><p>Pick a page from the sidebar. Served from <code>${root}</code>.</p>`));
+      return;
+    }
+    const rel = urlPath.replace(/^\//, "") + ".md";
+    const abs = path.join(root, rel);
+    if (!abs.startsWith(root) || !existsSync(abs)) {
+      res.writeHead(404, { "Content-Type": "text/html" });
+      res.end(page("Not found", `<h1>Not found</h1><p><code>${urlPath}</code> has no matching doc under ${root}.</p>`));
+      return;
+    }
+    const md = readFileSync(abs, "utf8");
+    const titleMatch = md.match(/^#\s+(.*)$/m);
+    res.writeHead(200, { "Content-Type": "text/html" });
+    res.end(page(titleMatch?.[1] || rel, mdToHtml(md)));
+  });
+  server.listen(port, () => {
+    console.log(`erp docs serve: ${root}`);
+    console.log(`  http://localhost:${port}/`);
+    if (!opts.open) console.log(`  (Ctrl+C to stop)`);
+  });
+}
+
+// ---------------------------------------------------------------------------
+// erp dev — local static preview server for one page JSON.
+// [THIN, disclosed] — NOT a full mock-database + workflow-engine + AI-tools
+// local runtime (the doc's §9 "ERP Local Development Environment" mockup);
+// that needs the real Spring Boot backend + Postgres this platform actually
+// runs on, which a static Node server cannot stand in for without becoming
+// a second, divergent runtime implementation (a real anti-pattern — see
+// render-adapter-framework-agnostic/ui-unit-named-block's own "don't build
+// a parallel mechanism" discipline). What IS real and useful: a local HTTP
+// server that serves a page's JSON + the real, already-built
+// @erp/block-adapter-mui/@erp/page-engine dist bundles so the page renders
+// in a browser against LIVE data from whatever `erp env`/`erp login`
+// session is active — i.e. local static hosting + real remote data, not a
+// local mock backend.
+//
+// [REAL, 2026-09-03 mcp-10] — the piece above was honestly disclosed as not
+// orchestrating a real backend at all; it now does. Before serving, this
+// probes the REAL `engine-api` (`GET {baseUrl}/actuator/health`, same probe
+// this session ran via curl throughout, e.g. against the live instance on
+// :8080). If it's down, `erp dev` offers (or, with `--yes`/`--start`, just
+// does) launching the REAL Spring Boot process — not a mock — using the
+// exact two-step command this session's own
+// maven-spring-boot-run-am-fails-on-root-pom finding requires (a root-level
+// `-am spring-boot:run` reproducibly fails against the aggregator root pom):
+// (1) `mvn -o install -DskipTests` from `backend/` once, then (2) `mvn -o
+// spring-boot:run` from `backend/platform-runtime/erp-suite/` directly (the
+// S5 cutover retired engine-api's own entrypoint; erp-suite is canonical). Step 2 is `spawn`ed (not
+// `spawnSync`) and left running detached from this call so `erp dev` doesn't
+// block on the server's own lifetime; both steps stream real stdout/stderr
+// back out prefixed `[engine-api]` line by line — real Maven/Spring Boot
+// boot log, not a canned message. Health is then polled for up to 5 minutes
+// (a cold boot is genuinely that slow) before falling through to the exact
+// same preview-serving code path as the already-healthy case. Postgres/Redis
+// being down is NOT auto-remediated here (out of scope per this pass's own
+// brief) — a boot failure's own stderr is surfaced as-is, with a pointer to
+// this repo's local Postgres notes.
+// ---------------------------------------------------------------------------
+// S5 cutover: the standalone engine-api entrypoint was retired; erp-suite is
+// the canonical single-process deployable. `spring-boot:run` runs from here.
+const SUITE_DIR = path.join(REPO_ROOT, "backend", "platform-runtime", "erp-suite");
+const BACKEND_ROOT = path.join(REPO_ROOT, "backend");
+
+async function checkHealth(baseUrl, timeoutMs = 3000) {
+  try {
+    const ctrl = new AbortController();
+    const t = setTimeout(() => ctrl.abort(), timeoutMs);
+    const res = await fetch(`${baseUrl}/actuator/health`, { signal: ctrl.signal });
+    clearTimeout(t);
+    if (!res.ok) return { healthy: false };
+    const body = await res.json();
+    return { healthy: body.status === "UP", body };
+  } catch {
+    return { healthy: false };
+  }
+}
+
+/** Runs a command to completion, streaming stdout/stderr prefixed `[engine-api]`. Rejects on non-zero exit. */
+function runStreamingToCompletion(cmd, args, cwd) {
+  return new Promise((resolve, reject) => {
+    console.log(`[engine-api] $ ${cmd} ${args.join(" ")}  (cwd: ${cwd})`);
+    const child = spawn(cmd, args, { cwd, shell: true });
+    const pipe = (stream) => stream.on("data", (buf) => {
+      for (const line of buf.toString().split(/\r?\n/)) if (line) console.log(`[engine-api] ${line}`);
+    });
+    pipe(child.stdout);
+    pipe(child.stderr);
+    child.on("error", reject);
+    child.on("exit", (code) => (code === 0 ? resolve() : reject(new Error(`${cmd} ${args.join(" ")} exited with code ${code}`))));
+  });
+}
+
+/** Spawns the long-lived `spring-boot:run` process, streaming its output, and returns the child (left running — not awaited to exit). */
+function spawnEngineApi() {
+  const cmd = "mvn";
+  const args = ["-o", "spring-boot:run"];
+  console.log(`[erp-suite] $ ${cmd} ${args.join(" ")}  (cwd: ${SUITE_DIR})`);
+  const child = spawn(cmd, args, { cwd: SUITE_DIR, shell: true });
+  const pipe = (stream) => stream.on("data", (buf) => {
+    for (const line of buf.toString().split(/\r?\n/)) if (line) console.log(`[engine-api] ${line}`);
+  });
+  pipe(child.stdout);
+  pipe(child.stderr);
+  child.on("exit", (code) => console.log(`[engine-api] process exited with code ${code}`));
+  child.unref();
+  return child;
+}
+
+async function ensureBackendUp(baseUrl, opts) {
+  const initial = await checkHealth(baseUrl);
+  if (initial.healthy) return;
+  console.log(`erp dev: engine-api at ${baseUrl} is NOT reachable (GET /actuator/health failed).`);
+  const autoStart = opts.yes || opts.start;
+  if (!autoStart) {
+    const answer = await prompt(`Start the real Spring Boot engine-api now? [Y/n] `);
+    if (answer && !/^y/i.test(answer)) {
+      throw new Error("engine-api not running and not started — re-run with --start/--yes to skip this prompt, or start it yourself.");
+    }
+  }
+  console.log(`erp dev: starting engine-api for real. This is the exact command a developer would run by hand:`);
+  console.log(`  (1) cd ${BACKEND_ROOT} && mvn -o install -DskipTests`);
+  console.log(`  (2) cd ${SUITE_DIR} && mvn -o spring-boot:run`);
+  console.log(`See maven-spring-boot-run-am-fails-on-root-pom: the README's own root-level -am spring-boot:run reproducibly fails against the aggregator pom — this two-step, module-directory form is the real working command.`);
+  await runStreamingToCompletion("mvn", ["-o", "install", "-DskipTests"], BACKEND_ROOT);
+  spawnEngineApi();
+  console.log(`erp dev: polling ${baseUrl}/actuator/health — cold Spring Boot boots can genuinely take a few minutes; waiting up to 5 minutes.`);
+  const deadline = Date.now() + 5 * 60 * 1000;
+  while (Date.now() < deadline) {
+    const { healthy } = await checkHealth(baseUrl, 3000);
+    if (healthy) {
+      console.log(`erp dev: engine-api is healthy.`);
+      return;
+    }
+    await sleep(5000);
+  }
+  throw new Error(
+    `engine-api did not become healthy within 5 minutes. If the boot log above shows a DB connection failure, ` +
+    `start local Postgres first (this repo's local setup: pg_ctl start against its data dir — see this session's ` +
+    `postgres-local-setup notes; starting Postgres itself is out of scope for \`erp dev\`).`
+  );
+}
+
+async function devCommand(pagePath, opts) {
+  const port = Number(opts.port || 4300);
+  const cfg = loadConfig();
+  const env = currentEnv(cfg);
+  await ensureBackendUp(env.baseUrl, opts);
+  const session = cfg.sessions?.[env.name];
+  const abs = path.resolve(pagePath);
+  const pageJson = readFileSync(abs, "utf8");
+  const html = `<!doctype html><html><head><meta charset="utf-8"><title>erp dev — ${path.basename(abs)}</title></head>
+<body style="margin:0;font-family:system-ui">
+<div id="banner" style="background:#111;color:#fff;padding:8px 16px;font:13px monospace">erp dev — ${path.basename(abs)} — env: ${env.name} (${env.baseUrl}) — ${session ? "logged in as " + session.userId : "NOT logged in (run: erp login)"}</div>
+<pre id="page" style="padding:16px;white-space:pre-wrap">${pageJson.replace(/</g, "&lt;")}</pre>
+<p style="padding:0 16px;color:#666;font:13px system-ui">[THIN] Full block-tree rendering here (rather than this raw-JSON preview) requires wiring @erp/page-engine + @erp/block-adapter-mui's built dist bundles into this static page — same dist-only-resolution caveat as Studio's own TenantPageHost. Not wired in this pass; the JSON above is the real, current file content, live-reloaded on save.</p>
+</body></html>`;
+  const server = http.createServer((req, res) => {
+    if (req.url === "/") {
+      res.writeHead(200, { "Content-Type": "text/html" });
+      res.end(html);
+    } else if (req.url === "/page.json") {
+      res.writeHead(200, { "Content-Type": "application/json" });
+      res.end(readFileSync(abs, "utf8"));
+    } else {
+      res.writeHead(404);
+      res.end("not found");
+    }
+  });
+  server.listen(port, () => console.log(`erp dev preview: http://localhost:${port}  (Ctrl+C to stop)`));
+}
+
+// ---------------------------------------------------------------------------
+// erp sdk list / download / download-all
+// [REAL, disclosed shape] — the 7 real `@erp/*` Code Plugin SDK packages
+// (`frontend/packages/erp-{ui,data,auth,permissions,workflows,
+// notifications,ai}`) are `"private": true` pnpm workspace packages with
+// `workspace:*` deps — not installable from any registry today (this
+// platform runs no private npm registry of its own). "download" here means
+// exactly what `npm pack` produces: a real, standard, redistributable
+// `.tgz` a developer `npm install`s locally into their own plugin
+// workspace — NOT a hosted `npm install -g @erp/x`. Building first
+// (`pnpm --filter @erp/<name> build`, same `spawnSync` shape as
+// `runSpark`) means the `.tgz` always contains a real, current `dist/`.
+// ---------------------------------------------------------------------------
+const SDK_PACKAGES = ["ui", "data", "auth", "permissions", "workflows", "notifications", "ai"];
+
+function sdkPackageJson(name) {
+  const dir = path.join(REPO_ROOT, "frontend/packages", `erp-${name}`);
+  const pkgPath = path.join(dir, "package.json");
+  if (!existsSync(pkgPath)) throw new Error(`unknown SDK package "${name}" — known: ${SDK_PACKAGES.join(", ")}`);
+  return { dir, pkg: JSON.parse(readFileSync(pkgPath, "utf8")) };
+}
+
+function sdkListCommand() {
+  console.log(`The 7 real @erp/* Code Plugin SDK packages (see ai/patterns/code-plugin-sdk.md):\n`);
+  for (const name of SDK_PACKAGES) {
+    const { pkg } = sdkPackageJson(name);
+    console.log(`  ${pkg.name}@${pkg.version}`);
+    console.log(`    ${pkg.description || "(no description)"}\n`);
+  }
+}
+
+function runPnpm(args, cwd) {
+  // `shell: true` (not a bare `.cmd` invocation) — Windows' spawnSync throws EINVAL calling a .cmd
+  // shim directly without a shell, found live running this exact command.
+  const res = spawnSync("pnpm", args, { stdio: "inherit", cwd, shell: true });
+  if (res.status !== 0) throw new Error(`pnpm ${args.join(" ")} failed (exit ${res.status})`);
+}
+
+/** Builds `@erp/<name>`, `npm pack`s it, and copies the resulting `.tgz` into `outDir`. Returns the copied path. */
+function sdkDownloadOne(name, outDir) {
+  const { dir, pkg } = sdkPackageJson(name);
+  console.log(`Building ${pkg.name}...`);
+  runPnpm(["--filter", pkg.name, "build"], path.join(REPO_ROOT, "frontend"));
+  console.log(`Packing ${pkg.name}...`);
+  const packRes = spawnSync("npm", ["pack", "--json"], { cwd: dir, encoding: "utf8", shell: true });
+  if (packRes.status !== 0) throw new Error(`npm pack failed for ${pkg.name}: ${packRes.stderr || packRes.stdout}`);
+  const [{ filename }] = JSON.parse(packRes.stdout);
+  mkdirSync(outDir, { recursive: true });
+  const dest = path.join(outDir, filename);
+  copyFileSync(path.join(dir, filename), dest);
+  unlinkSync(path.join(dir, filename));
+  return dest;
+}
+
+function sdkDownloadCommand(name, opts) {
+  if (!name) throw new Error("usage: erp sdk download <name> [--out <dir>] — see `erp sdk list` for names");
+  const outDir = path.resolve(opts.out || process.cwd());
+  const dest = sdkDownloadOne(name, outDir);
+  console.log(`\nWrote ${dest}`);
+  console.log(`\nTo use it in another project:\n\n  npm install ${dest}\n`);
+  const { pkg } = sdkPackageJson(name);
+  const workspaceDeps = Object.entries(pkg.dependencies || {}).filter(([, v]) => v === "workspace:*").map(([n]) => n);
+  if (workspaceDeps.length > 0) {
+    console.log(`${pkg.name} depends on ${workspaceDeps.join(", ")} — download and \`npm install\` those .tgz files FIRST (dependency order), or just run \`erp sdk download-all\`.`);
+  }
+}
+
+function sdkDownloadAllCommand(opts) {
+  const outDir = path.resolve(opts.out || process.cwd());
+  console.log(`Downloading all 7 @erp/* SDK packages, in dependency order, into ${outDir}...\n`);
+  const installLines = [];
+  for (const name of SDK_PACKAGES) {
+    const dest = sdkDownloadOne(name, outDir);
+    installLines.push(`npm install ${dest}`);
+    console.log(`Wrote ${dest}\n`);
+  }
+  console.log(`To use the whole SDK in another project, run these IN ORDER:\n`);
+  console.log(installLines.join("\n"));
+}
+
+// ---------------------------------------------------------------------------
+// Arg parsing + dispatch
+// ---------------------------------------------------------------------------
+// Short-flag aliases for the handful of single-dash flags this CLI's own
+// help text documents (e.g. `erp plugin build <dir> [-o out.spk]`). Real bug
+// fixed here: parseArgs previously only recognized `--long` flags, so a
+// documented `-o foo.spk` was silently treated as a stray positional arg —
+// opts.out stayed undefined, pluginBuildCommand/packageCommand fell back to
+// their own default filename, and the .spk landed in cwd instead of the
+// path the user asked for, with zero error or warning. Found live via
+// `erp plugin build ... -o backend/modules/hcm-learning/hcm-learning-1.0.10.spk`
+// writing to `hcm-learning-1.0.10.spk` at the repo root instead.
+const SHORT_FLAG_ALIASES = { "-o": "out" };
+
+function parseArgs(argv) {
+  const opts = {};
+  const positional = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith("--")) {
+      const key = a.slice(2).replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+      const next = argv[i + 1];
+      if (next && !next.startsWith("--")) { opts[key] = next; i++; } else { opts[key] = true; }
+    } else if (Object.prototype.hasOwnProperty.call(SHORT_FLAG_ALIASES, a)) {
+      const key = SHORT_FLAG_ALIASES[a];
+      const next = argv[i + 1];
+      if (next && !next.startsWith("-")) { opts[key] = next; i++; } else { opts[key] = true; }
+    } else positional.push(a);
+  }
+  return { opts, positional };
+}
+
+const HELP = `erp — ERP Developer Platform CLI
+
+  Global: any command below that talks to the backend also accepts
+  --tenant <id> to run against a tenant other than the current session's own
+  (sent as X-Tenant-Id, overriding the logged-in tenant for that one call —
+  note this only actually works where the session's own token is valid
+  against that tenant too; it does not re-authenticate you as someone else).
+
+  Auth: 'erp login' stores an access + refresh token per env in ~/.erp/config.json
+  (mode 0600); networked commands auto-refresh an expired access token. Set
+  ERP_TOKEN=<access token> to override the stored creds entirely (CI path).
+
+  erp login [--tenant <id>] [--no-browser]           (real OAuth 2.0 device authorization grant, RFC 8628 — default)
+  erp login --direct [--tenant <id>] [--user <id>] [--password <pw>]   (original one-shot username/password)
+  erp logout
+  erp whoami
+  erp org list
+  erp env list
+  erp env use <name> [--base-url <url>]
+  erp env sync [--check]                          (pull this env's authoring bundle from {baseUrl}/api/v1/dev/bundle into ~/.erp/cache/<envKey>/ — schemas/catalog/docs/blocks/validators + live entity+theme names; --check = manifest drift only, no download)
+
+  erp bundle build [--out <dir>] [--bundle-version <v>]   (emit erp-authoring-bundle/ — schemas + frozen engine catalog + curated examples + tenant-public docs + blocks.json + self-contained validators/ — the offline grounding a packaged SDK install reads; the Java source scan + esbuild run HERE, never on the client)
+  erp docs gen-reference [--out <dir>]            (turn the built bundle's schemas/ into one Markdown reference page each, under developer-docs/reference/)
+
+  erp plugin list
+  erp plugin search <term>
+  erp plugin install <pluginId> [--manifest <path>]
+  erp plugin pull <pluginId> [--out <dir>]
+  erp plugin create <pluginId> [--name] [--schema] [--category] [--type <type>] [--runtime-mode embedded|service] [--service-port <n>]
+  erp menu create <plugin-dir> <menu-id> [--display-name <name>] [--route <path>] [--icon <name>]   (scaffolds a real, schema-valid menu artifact — spark create leaves metadata/menu/ empty)
+  erp plugin diff <pluginId>
+  erp spec generate <pluginId> [--out <file.md>]   (mechanically-derived entity/rule/page/permission inventory from LOCAL backend/modules/<id>/spk-assembly metadata — a starting point for ai/domains/*.md, not a replacement for its hand-curated narrative)
+  erp platform catalog [--engine <engine-name>] [--refresh]   (mechanically-derived class/REST-mapping/Flyway-table inventory of every backend/platform-runtime/engine-* module — cached at ai/platform/engine-capability-catalog.json; erp docs search also searches this, labeled [live engine-* source], so a stale doc claim is never the only answer)
+  erp platform describe <ClassName> [--refresh]   (real method signatures/field lists for a curated set of extension-point/gateway-client classes — *Contribution interfaces, WorkflowGatewayClient+PendingHumanTask/InstanceView/etc, DmsGatewayClient/CommunicationGatewayClient per-plugin copies — the concrete "what does this class actually contain" answer without opening the file; erp docs search also surfaces these, labeled [java contract])
+  erp plugin scaffold <extension-point> [--package <pkg>] [--class <Name>] [--plugin-id <id>] [--out <file.java>]   (emits a minimal, correctly-typed Java skeleton for a curated extension point, pulled from a real shipped implementation — currently: rest-contribution)
+  erp plugin validate <dir>
+  erp plugin compile <source.tsx> [--out <page.json>]
+  erp plugin test <dir>
+  erp plugin build <dir> [-o out.spk]
+  erp plugin install-bundle <applicationKey> [--tenant <id>] [--continue-on-error]   (builds+installs an ENTIRE ApplicationCatalog bundle, e.g. "hcm", in one command — real dependency order computed from each plugin's own plugin.json, not hand-maintained; already-installed members are skipped, so re-running after a partial failure safely resumes)
+  erp plugin set-runtime-mode <plugin-dir> --mode embedded|service [--port <n>] [--health-path <path>] [--timeout-ms <n>]   (lets a developer decide an EXISTING module should run standalone as its own service — declares runtimeModes+serviceDeployment on plugin.json, re-validated before writing; does not itself start/deploy anything — see the command's own note)
+  erp plugin publish <dir-or-.spk> [--env <name>] [--url <base>] [--tenant <id>] [--dry-run]
+                                                    (publishes to the configured env's base_url with your 'erp login' token — never a hardcoded host)
+  erp plugin push <dir-or-.spk>        (alias of publish; --force runs force-unload first if a prior load is wedged)
+  erp plugin force-unload <pluginId> [--tenant <id>]   (recovery: force-clears a wedged fleet-wide PF4J load — plugin still STARTED in-process while its install row is 'uninstalled' — without a backend restart; idempotent)
+  erp plugin publish-frontend <backend-module-dir> --cabinet-id <id> [--entrypoint-export <name>] [--frontend-dir <dir>]
+
+  erp registry list [--type <plugin|theme|template-pack|...>]   (hosted catalog, published only)
+  erp registry mine [--type <...>]                              (your tenant's own listings, any status)
+  erp registry get <packageId> <version>
+  erp registry publish <packageId> <version> [--type plugin] [--name] [--author] [--license] [--description] [--payload-file <file>]
+  erp registry install <packageId> <version>                   (plugin type: payload's spkFileId -> the real PluginInstallPipeline)
+
+  erp schema pull <name> [--out <file>]
+  erp schema validate <file> --schema <name>
+  erp workflow validate <file>
+  erp workflow test <file>
+  erp workflow list --definition <workflowName> [--record <id>] [--tenant <id>]   (live: every running instance of a definition, optionally filtered to one record's correlation/context id — via engine-api's workflow read-proxy, no workflow-service URL needed)
+  erp workflow instance <instanceId> [--tenant <id>]     (live: full instance view — stage, status, context)
+  erp workflow tasks <instanceId> [--tenant <id>]        (live: the instance's human tasks, incl. pending approver)
+  erp workflow history <instanceId> [--tenant <id>]      (live: the instance's step/transition history)
+  erp connector validate <file>   (schema-check a connector-definition JSON file against engine-provider-connector's real schema, e.g. spk-assembly/metadata/connector/*.json)
+  erp connector create <file> [--tenant <id>]        (validates, then PUTs to the real, live ExternalProviderDefinitionController — creates/updates one external_provider_definition row)
+  erp connector list --domain <domain> [--tenant <id>]  (lists real registered rows for a domain, e.g. "hcm-employee-documents.signature")
+  erp connector test <domain> <providerKey> [--body <json-string-or-@file>] [--tenant <id>]  (invokes the real GenericProviderConnectorExecutor for that row — DIRECT rows return a synthesized pending-confirm result, HTTP rows make a real outbound call)
+  erp --version | erp version                     (prints @erp/plugin-sdk's installed version, or 0.0.0-monorepo in a repo checkout)
+  erp docs search <query>
+  erp docs serve [--port 4400]                     (local offline dev-preview of developer-docs/ — monorepo: the live tree; packaged: the bundle's/synced docs/, sidebar from docs.json's nav)
+  erp examples search <pattern> [--kind page|workflow|entities|provider] [--max <n>]  (real shipped metadata JSON across every backend/modules/* plugin, matched by filename/plugin name — pure-CLI mirror of the MCP erp_search_examples tool)
+  erp examples patterns [--kind workflow]   (curated named SHAPES, not just filenames — e.g. single-stage-self-decide, multi-stage-linear, multi-stage-conditional-branching — each pointing at a real shipped file confirmed to have that shape)
+  erp blocks list [--type <name>] [--category <cat>]  (the real widget/block catalog, derived live from @erp/block-engine's own registry — every property/event/output any block type accepts, no source reading needed; pass --type for one type's full definition)
+  erp api get|post|put|delete <path> [--tenant <id>] [--body <json-string-or-@file>]   (authenticated call against ANY real backend endpoint using your logged-in session — for post-deploy verification: browse real entity records, live menu/workflow/artifact state, Data Service output. Never hand-write curl with guessed headers for this.)
+  erp logs tail [--lines <n>] [--grep <text>] [--follow] [--file <path>]   (real server-side log, incl. full stack traces — join a failed call's own X-Correlation-Id response header against --grep to see exactly what the server saw for that request; default path is engine-api's own logs/engine-api.log)
+  erp ai init [dir]
+  erp mcp install [--dir <dir>]
+  erp sdk list                                    (the 7 real @erp/* Code Plugin SDK packages)
+  erp sdk download <name> [--out <dir>]           (builds + npm-packs one into a local .tgz — no hosted registry)
+  erp sdk download-all [--out <dir>]              (all 7, in dependency order, into one dir)
+  erp dev <page.json> [--port 4300] [--yes|--start]  (auto-detects/starts real engine-api if down)
+
+Every command's real vs. thin/disclosed status is documented at the top of
+tools/erp-cli/erp.mjs and in ai/domains/ai-native-developer-platform-gap-analysis.md.
+`;
+
+// ---------------------------------------------------------------------------
+// erp extension create-service <name> — [REAL, Tenant-Safe Plugin & Extension
+// Architecture E1/E3, spec §55]. Copies the hardened, real, runnable skeleton
+// at extensions/archetype/ (see its own README — the request/response wire
+// contract EXACTLY matches ExtensionRouter/ExtensionContext, including the
+// HMAC service-auth bearer token E3 added) rather than hand-emitting a
+// second, divergent template — this used to write its own inline template
+// (POST /extension-api/${name}/invoke, a nested "context" body key) which
+// did NOT match ExtensionRouter's real contract (POST /extension-api/{code},
+// a FLAT body) — fixed by making this command a copy + light rename of the
+// one real archetype instead of a second hand-maintained copy.
+// ---------------------------------------------------------------------------
+function extensionCreateServiceCommand(name, opts) {
+  if (!name || !/^[a-z][a-z0-9-]*$/.test(name)) {
+    throw new Error('usage: erp extension create-service <name>   (lowercase, e.g. "tenant-c-payroll") [--out <dir>]');
+  }
+  const artifactId = `${name}-extension-service`;
+  const namespace = `tenant-${name}`;
+  const archetypeDir = path.join(REPO_ROOT, "extensions", "archetype");
+  if (!existsSync(archetypeDir)) throw new Error(`Archetype not found at ${archetypeDir} — repo layout changed?`);
+  const parent = opts.out ? path.resolve(opts.out) : path.join(REPO_ROOT, "extensions");
+  const root = path.join(parent, artifactId);
+  if (existsSync(root)) throw new Error(`${root} already exists — pick another name or delete it first.`);
+
+  const TEXT_EXT = new Set([".java", ".xml", ".yml", ".yaml", ".md", "", ".properties"]);
+  const copied = [];
+  const copyDir = (src, dest) => {
+    mkdirSync(dest, { recursive: true });
+    for (const entry of readdirSync(src, { withFileTypes: true })) {
+      if (entry.name === "target") continue; // never copy a stale local build
+      const srcPath = path.join(src, entry.name);
+      const destPath = path.join(dest, entry.name.startsWith("Dockerfile") ? entry.name : entry.name);
+      if (entry.isDirectory()) {
+        copyDir(srcPath, destPath);
+      } else {
+        const ext = path.extname(entry.name);
+        if (TEXT_EXT.has(ext)) {
+          let body = readFileSync(srcPath, "utf8");
+          // Namespace token first (contains "extension-archetype" as a substring) so it
+          // doesn't get mangled by the shorter artifactId replacement below.
+          body = body.replaceAll("tenant-extension-archetype", namespace);
+          body = body.replaceAll("extension-archetype", artifactId);
+          writeFileSync(destPath, body);
+        } else {
+          copyFileSync(srcPath, destPath);
+        }
+        copied.push(path.relative(root, destPath));
+      }
+    }
+  };
+  copyDir(archetypeDir, root);
+
+  console.log(`Scaffolded ${root} (copied from extensions/archetype/)`);
+  copied.sort().forEach((f) => console.log(`  ${f}`));
+  console.log(`\nJava package/class names kept as the archetype's own (com.tenant.extension.archetype /`);
+  console.log(`ExtensionApiController) — rename them yourself if you want a project-specific package.`);
+  console.log(`\nNext: cd ${path.relative(process.cwd(), root) || root} && mvn spring-boot:run`);
+  console.log(`Then: erp tenant plugin install <tenantId> ${name} --runtime service --endpoint https://<host>:8480 --application <APP>`);
+}
+
+// ---------------------------------------------------------------------------
+// erp tenant plugin install|enable|disable|list <tenant> <extensionCode>
+// [REAL, E1, spec §56] — drives the tenant_extension API
+// (TenantExtensionController, /api/v1/platform/tenant-extensions).
+// ---------------------------------------------------------------------------
+async function tenantPluginCommand(positional, opts) {
+  const [action, tenant, extensionCode] = positional;
+  const usage = "usage: erp tenant plugin <install|enable|disable|list> <tenant> [<extensionCode>] "
+    + "[--application HCM] [--version <v>] [--runtime service|shared] [--endpoint <url>]";
+  if (!action || !tenant) throw new Error(usage);
+  const cfg = loadConfig();
+  const application = opts.application || opts.app || "HCM";
+  const base = `/api/v1/platform/tenant-extensions/${encodeURIComponent(tenant)}`;
+
+  if (action === "list") {
+    const rows = await api(cfg, "GET", base, { tenantIdOverride: opts.tenant });
+    console.log(JSON.stringify(rows, null, 2));
+    console.log(`\n${Array.isArray(rows) ? rows.length : 0} extension binding(s) for tenant ${tenant}.`);
+    return;
+  }
+  if (!extensionCode) throw new Error(usage);
+
+  if (action === "install") {
+    const runtimeType = (opts.runtime || "service").toUpperCase();
+    if (runtimeType === "SERVICE" && !opts.endpoint) {
+      throw new Error("a --runtime service binding needs --endpoint <url> (where the extension service listens).");
+    }
+    const body = {
+      applicationId: application,
+      extensionCode,
+      extensionType: opts.type || "java-extension",
+      version: opts.version || null,
+      runtimeType,
+      endpoint: opts.endpoint || null,
+      status: "INSTALLED",
+    };
+    const row = await api(cfg, "POST", base, { body, tenantIdOverride: opts.tenant });
+    console.log(JSON.stringify(row, null, 2));
+    console.log(`\nInstalled "${extensionCode}" for tenant ${tenant} / ${application} (status INSTALLED — run \`erp tenant plugin enable\` to activate).`);
+    return;
+  }
+  if (action === "enable" || action === "disable") {
+    const status = action === "enable" ? "ENABLED" : "DISABLED";
+    const url = `${base}/${encodeURIComponent(application)}/${encodeURIComponent(extensionCode)}/status?status=${status}`;
+    const row = await api(cfg, "PUT", url, { tenantIdOverride: opts.tenant });
+    console.log(JSON.stringify(row, null, 2));
+    console.log(`\n"${extensionCode}" -> ${status} for tenant ${tenant} / ${application}.`);
+    return;
+  }
+  throw new Error(usage);
+}
+
+// Reads the package.json that ships alongside this file when installed as
+// @erp/plugin-sdk (packages/erp-plugin-sdk/package.json, one dir up from
+// erp-cli/). In the monorepo checkout no such file exists at that path —
+// falls back to "0.0.0-monorepo" so `erp --version` never throws.
+function cliVersion() {
+  try {
+    const p = path.join(__dirname, "..", "package.json");
+    if (existsSync(p)) return JSON.parse(readFileSync(p, "utf8")).version || "0.0.0";
+  } catch { /* fall through */ }
+  return "0.0.0-monorepo";
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+  if (argv[0] === "--version" || argv[0] === "-v" || argv[0] === "version") {
+    console.log(`@erp/plugin-sdk ${cliVersion()}`);
+    return;
+  }
+  const command = argv[0];
+  const sub = argv[1];
+  const twoWordKey = sub && !sub.startsWith("--") ? `${command} ${sub}` : null;
+
+  let opts = {};
+  let positional = [];
+
+  const table = {
+    login: () => loginCommand(opts),
+    logout: () => logoutCommand(),
+    whoami: () => whoamiCommand(opts),
+    "org list": () => orgListCommand(opts),
+    "env list": () => envListCommand(),
+    "env use": () => envUseCommand(positional[0], opts),
+    "plugin list": () => pluginListCommand(opts),
+    "plugin search": () => pluginSearchCommand(positional[0], opts),
+    "plugin install": () => pluginInstallCommand(positional[0], opts),
+    "plugin pull": () => pluginPullCommand(positional[0], opts),
+    "plugin create": () => pluginCreateCommand(positional[0], opts),
+    "plugin diff": () => pluginDiffCommand(positional[0], opts),
+    "spec generate": () => specGenerateCommand(positional[0], opts),
+    "platform catalog": () => platformCatalogCommand(opts),
+    "platform describe": () => platformDescribeCommand(positional[0], opts),
+    "plugin scaffold": () => pluginScaffoldCommand(positional[0], opts),
+    "extension create-service": () => extensionCreateServiceCommand(positional[0], opts),
+    "tenant plugin": () => tenantPluginCommand(positional, opts),
+    "registry list": () => registryListCommand(opts),
+    "registry mine": () => registryMineCommand(opts),
+    "registry get": () => registryGetCommand(positional[0], positional[1], opts),
+    "registry publish": () => registryPublishCommand(positional[0], positional[1], opts),
+    "registry install": () => registryInstallCommand(positional[0], positional[1], opts),
+    "plugin validate": () => pluginValidateCommand(positional[0]),
+    "plugin compile": () => pluginCompileCommand(positional[0], opts),
+    "plugin test": () => pluginTestCommand(positional[0]),
+    "plugin build": () => pluginBuildCommand(positional[0], opts),
+    "plugin install-bundle": () => pluginBundleInstallCommand(positional[0], opts),
+    "plugin set-runtime-mode": () => pluginSetRuntimeModeCommand(positional[0], opts),
+    "plugin publish": () => pluginPublishCommand(positional[0], opts),
+    "plugin publish-frontend": () => pluginPublishFrontendCommand(positional[0], opts),
+    "plugin push": () => pluginPublishCommand(positional[0], opts),
+    "plugin force-unload": () => pluginForceUnloadCommand(positional[0], opts),
+    "schema pull": () => schemaPullCommand(positional[0], opts),
+    "schema validate": () => schemaValidateCommand(positional[0], opts),
+    "workflow validate": () => workflowValidateCommand(positional[0]),
+    "workflow test": () => workflowTestCommand(positional[0]),
+    "workflow list": () => workflowListCommand(opts),
+    "workflow instance": () => workflowInstanceCommand(positional[0], opts),
+    "workflow tasks": () => workflowTasksCommand(positional[0], opts),
+    "workflow history": () => workflowHistoryCommand(positional[0], opts),
+    "connector validate": () => connectorValidateCommand(positional[0]),
+    "connector create": () => connectorCreateCommand(positional[0], opts),
+    "connector list": () => connectorListCommand(opts),
+    "connector test": () => connectorTestCommand(positional[0], positional[1], opts),
+    "bundle build": () => bundleBuildCommand(opts),
+    "env sync": () => envSyncCommand(opts),
+    "docs search": () => docsSearchCommand(positional.join(" ")),
+    "docs gen-reference": () => docsGenReferenceCommand(opts),
+    "docs serve": () => docsServeCommand(opts),
+    "examples search": () => examplesSearchCommand(positional[0], opts),
+    "examples patterns": () => examplesPatternsCommand(opts),
+    "blocks list": () => blocksListCommand(opts),
+    "api get": () => apiCallCommand("GET", positional[0], opts),
+    "api post": () => apiCallCommand("POST", positional[0], opts),
+    "api put": () => apiCallCommand("PUT", positional[0], opts),
+    "api delete": () => apiCallCommand("DELETE", positional[0], opts),
+    "logs tail": () => logsTailCommand(opts),
+    "menu create": () => menuCreateCommand(positional[0], positional[1], opts),
+    "ai init": () => aiInitCommand(positional[0]),
+    "mcp install": () => mcpInstallCommand(opts),
+    "sdk list": () => sdkListCommand(),
+    "sdk download": () => sdkDownloadCommand(positional[0], opts),
+    "sdk download-all": () => sdkDownloadAllCommand(opts),
+    dev: () => devCommand(positional[0], opts),
+  };
+
+  const key = twoWordKey && table[twoWordKey] ? twoWordKey : command;
+  const argsForParsing = key === twoWordKey ? argv.slice(2) : argv.slice(1);
+  ({ opts, positional } = parseArgs(argsForParsing));
+
+  const fn = table[key];
+  if (!fn) {
+    console.log(HELP);
+    process.exitCode = key ? 1 : 0;
+    return;
+  }
+  await fn();
+}
+
+// Guarded (2026-09-03, added for I18N-001's MCP wiring): erp.mjs used to run
+// `main()` unconditionally at module-load time, which made it unsafe to
+// `import()` from anywhere else (e.g. the MCP server) — importing it would
+// re-parse THAT process's own argv and potentially execute a CLI command as
+// a side effect. Only invoking `main()` when this file is the actual entry
+// point (`node erp.mjs ...`) — not when another ESM module imports it for
+// its exported functions — makes it a safely reusable module too, the same
+// "provider exposes a real capability, consumers get a thin wrapper"
+// convention already used for `ReferenceResolutionService`/`DmsGatewayClient`
+// elsewhere in this codebase.
+// Real gap found + fixed while proving @erp/plugin-sdk's npm portability
+// (packages/erp-plugin-sdk, Batch C): a plain string compare of
+// import.meta.url vs argv[1]'s file URL breaks for ANY symlinked/junction
+// install — `npm install -g <local-dir>` and pnpm's global installs both
+// link rather than copy, so import.meta.url resolves through the symlink to
+// its target while argv[1] (as the invoking shim passed it) stays on the
+// link path. The two URLs then never match, the guard is silently false,
+// and `erp` exits 0 having done nothing — no error, just a no-op. Compare
+// realpaths (falls back to the raw path if realpath fails, e.g. it's already
+// gone) so a linked global install behaves exactly like a copied one.
+function samePath(a, b) {
+  try { return realpathSync(a) === realpathSync(b); } catch { return a === b; }
+}
+if (process.argv[1] && samePath(fileURLToPath(import.meta.url), process.argv[1])) {
+  main().catch((err) => {
+    console.error(`error: ${err.message}`);
+    process.exitCode = 1;
+  });
+}
+
+export { lintPageSemantics, lintDataServiceSemantics, lintI18nSemantics, lintPageDataSourceSemantics, lintJobContributionUsage, loadEntityFieldTypes, loadI18nKeys, loadProviderNamesFrom, loadAllRepoProviderNames, simpleSchemaCheck, buildEngineCatalog, searchEngineCatalog, describeContract, pluginScaffoldCommand, SCAFFOLD_TEMPLATES };