madarx 2.12.1 → 2.14.0

package/lib/process/spec-validator.js

@@ -116,6 +116,46 @@ function validateAgentRun(stage, errors, prefix, opts, stageSlugs) {
   }
 }
 
+// Predicate operator sets (mirror lib/process/policy-predicates.js).
+const PREDICATE_LOGICAL_OPS = new Set(['and', 'or']);
+const PREDICATE_COMPARE_OPS = new Set(['eq', 'neq', 'lt', 'lte', 'gt', 'gte', 'in', 'nin']);
+const PREDICATE_MAX_DEPTH = 20;
+
+// Validate a JSON predicate tree structurally. Mirrors the evaluator so an
+// invalid predicate is rejected at authoring time, not at case run time.
+function validatePredicate(pred, errors, prefix, depth = 0) {
+  if (depth > PREDICATE_MAX_DEPTH) {
+    pushErr(errors, prefix, 'predicate nesting too deep');
+    return;
+  }
+  if (!isPlainObject(pred)) {
+    pushErr(errors, prefix, 'predicate must be an object');
+    return;
+  }
+  const op = pred.op;
+  if (PREDICATE_LOGICAL_OPS.has(op)) {
+    if (!Array.isArray(pred.rules) || pred.rules.length === 0) {
+      pushErr(errors, `${prefix}.rules`, `"${op}" requires a non-empty rules[] array`);
+    } else {
+      pred.rules.forEach((r, i) => validatePredicate(r, errors, `${prefix}.rules[${i}]`, depth + 1));
+    }
+  } else if (op === 'not') {
+    if (!isPlainObject(pred.rule)) pushErr(errors, `${prefix}.rule`, '"not" requires a rule object');
+    else validatePredicate(pred.rule, errors, `${prefix}.rule`, depth + 1);
+  } else if (PREDICATE_COMPARE_OPS.has(op)) {
+    if (typeof pred.path !== 'string' || !pred.path.trim()) {
+      pushErr(errors, `${prefix}.path`, 'required (non-empty string)');
+    }
+    if (!('value' in pred)) {
+      pushErr(errors, `${prefix}.value`, 'required');
+    } else if ((op === 'in' || op === 'nin') && !Array.isArray(pred.value)) {
+      pushErr(errors, `${prefix}.value`, `"${op}" requires an array value`);
+    }
+  } else {
+    pushErr(errors, `${prefix}.op`, `unknown predicate op "${op}"`);
+  }
+}
+
 function validatePolicyGate(stage, errors, prefix) {
   const config = stage.config || {};
   if (!Array.isArray(config.rules) || config.rules.length === 0) {
@@ -125,13 +165,18 @@ function validatePolicyGate(stage, errors, prefix) {
   config.rules.forEach((rule, i) => {
     const rpath = `${prefix}.config.rules[${i}]`;
     if (typeof rule === 'string') {
+      // Legacy string DSL (deprecated; accepted one release for migration).
       if (!rule.trim()) pushErr(errors, rpath, 'empty rule expression');
+    } else if (isPlainObject(rule) && typeof rule.op === 'string') {
+      // JSON predicate (canonical form).
+      validatePredicate(rule, errors, rpath);
     } else if (isPlainObject(rule)) {
+      // Legacy { expr, label } wrapper.
       if (!rule.expr || typeof rule.expr !== 'string' || !rule.expr.trim()) {
         pushErr(errors, `${rpath}.expr`, 'required (non-empty string)');
       }
     } else {
-      pushErr(errors, rpath, 'rule must be a string or { expr, label } object');
+      pushErr(errors, rpath, 'rule must be a JSON predicate, a string, or { expr, label }');
     }
   });
 }

package/lib/process/stages/policy-dsl-legacy.js

@@ -0,0 +1,178 @@
+// lib/process/stages/policy-dsl-legacy.js — DEPRECATED string-expression DSL.
+//
+// The hand-rolled tokenizer/parser kept for ONE release as a back-compat path
+// while string rules migrate to JSON predicates (`../policy-predicates.js`).
+// New workflows must author predicate JSON; the spec-validator accepts both
+// forms for now and the policy_gate handler routes per-rule. Do not extend
+// this grammar — it is on a removal track.
+//
+// Rule grammar:
+//   - intake.<field>
+//   - prior_stage('<slug>').<field>
+//   - Comparison: ==, !=, <, <=, >, >=
+//   - Logical: && ||, parens
+//   - String literals: 'foo'
+//   - Number literals: 1, 0.5
+//   - Membership: <left> IN [<lit>, <lit>, ...]
+
+function readPath(obj, path) {
+  if (!obj || !path) return undefined;
+  return path.split('.').reduce((acc, key) => (acc == null ? acc : acc[key]), obj);
+}
+
+function tokenize(expr) {
+  const tokens = [];
+  let i = 0;
+  while (i < expr.length) {
+    const ch = expr[i];
+    if (/\s/.test(ch)) { i++; continue; }
+    if (ch === '(' || ch === ')' || ch === '[' || ch === ']' || ch === ',') {
+      tokens.push({ type: ch }); i++; continue;
+    }
+    if (ch === '&' && expr[i + 1] === '&') { tokens.push({ type: '&&' }); i += 2; continue; }
+    if (ch === '|' && expr[i + 1] === '|') { tokens.push({ type: '||' }); i += 2; continue; }
+    if (ch === '=' && expr[i + 1] === '=') { tokens.push({ type: 'op', value: '==' }); i += 2; continue; }
+    if (ch === '!' && expr[i + 1] === '=') { tokens.push({ type: 'op', value: '!=' }); i += 2; continue; }
+    if (ch === '<' && expr[i + 1] === '=') { tokens.push({ type: 'op', value: '<=' }); i += 2; continue; }
+    if (ch === '>' && expr[i + 1] === '=') { tokens.push({ type: 'op', value: '>=' }); i += 2; continue; }
+    if (ch === '<' || ch === '>') { tokens.push({ type: 'op', value: ch }); i++; continue; }
+    if (ch === "'" || ch === '"') {
+      const end = expr.indexOf(ch, i + 1);
+      if (end === -1) throw new Error(`policy-gate: unterminated string at ${i}`);
+      tokens.push({ type: 'string', value: expr.slice(i + 1, end) });
+      i = end + 1; continue;
+    }
+    if (/[0-9.]/.test(ch)) {
+      let j = i;
+      while (j < expr.length && /[0-9.]/.test(expr[j])) j++;
+      tokens.push({ type: 'number', value: Number(expr.slice(i, j)) });
+      i = j; continue;
+    }
+    if (/[A-Za-z_]/.test(ch)) {
+      let j = i;
+      while (j < expr.length && /[A-Za-z0-9_.]/.test(expr[j])) j++;
+      const word = expr.slice(i, j);
+      if (word === 'IN' || word === 'in') { tokens.push({ type: 'IN' }); }
+      else if (word === 'true') { tokens.push({ type: 'boolean', value: true }); }
+      else if (word === 'false') { tokens.push({ type: 'boolean', value: false }); }
+      else if (word === 'prior_stage' && expr[j] === '(') {
+        // Parse prior_stage('slug').field
+        const closeQuote = expr.indexOf(')', j);
+        const inner = expr.slice(j + 1, closeQuote).trim().replace(/^['"]|['"]$/g, '');
+        let k = closeQuote + 1;
+        // Expect .field
+        if (expr[k] !== '.') throw new Error("policy-gate: expected '.' after prior_stage(...)");
+        let m = k + 1;
+        while (m < expr.length && /[A-Za-z0-9_.]/.test(expr[m])) m++;
+        tokens.push({ type: 'ref', kind: 'prior_stage', stage: inner, path: expr.slice(k + 1, m) });
+        i = m; continue;
+      } else {
+        tokens.push({ type: 'ref', kind: 'path', path: word });
+      }
+      i = j; continue;
+    }
+    throw new Error(`policy-gate: unexpected character "${ch}" at ${i}`);
+  }
+  return tokens;
+}
+
+function resolveRef(token, ctx) {
+  if (token.kind === 'prior_stage') {
+    return readPath(ctx.context?.[token.stage], token.path);
+  }
+  // path like intake.email or stage_output.foo.bar
+  if (token.path.startsWith('intake.')) {
+    return readPath(ctx.intake, token.path.slice('intake.'.length));
+  }
+  if (token.path.startsWith('context.')) {
+    return readPath(ctx.context, token.path.slice('context.'.length));
+  }
+  return readPath(ctx, token.path);
+}
+
+function evalTokens(tokens, ctx) {
+  // Pratt-ish recursive descent. Grammar:
+  //   expr := or
+  //   or := and ('||' and)*
+  //   and := cmp ('&&' cmp)*
+  //   cmp := value (op value)?
+  //        | value IN '[' values ']'
+  //   value := ref | number | string | boolean | '(' or ')'
+  let pos = 0;
+  function peek() { return tokens[pos]; }
+  function consume(type) {
+    const t = tokens[pos];
+    if (!t || t.type !== type) throw new Error(`policy-gate: expected ${type}, got ${t?.type || 'EOF'}`);
+    pos++;
+    return t;
+  }
+  function value() {
+    const t = peek();
+    if (!t) throw new Error('policy-gate: unexpected end of expression');
+    if (t.type === '(') { pos++; const e = or(); consume(')'); return e; }
+    if (t.type === 'number' || t.type === 'string' || t.type === 'boolean') {
+      pos++;
+      return t.value;
+    }
+    if (t.type === 'ref') {
+      pos++;
+      return resolveRef(t, ctx);
+    }
+    throw new Error(`policy-gate: unexpected token ${t.type}`);
+  }
+  function cmp() {
+    const left = value();
+    const t = peek();
+    if (!t) return Boolean(left);
+    if (t.type === 'op') {
+      pos++;
+      const right = value();
+      switch (t.value) {
+        case '==': return left == right; // eslint-disable-line eqeqeq
+        case '!=': return left != right; // eslint-disable-line eqeqeq
+        case '<': return Number(left) < Number(right);
+        case '<=': return Number(left) <= Number(right);
+        case '>': return Number(left) > Number(right);
+        case '>=': return Number(left) >= Number(right);
+      }
+    }
+    if (t.type === 'IN') {
+      pos++;
+      consume('[');
+      const list = [];
+      while (peek() && peek().type !== ']') {
+        const v = value();
+        list.push(v);
+        if (peek() && peek().type === ',') pos++;
+      }
+      consume(']');
+      return list.includes(left);
+    }
+    return Boolean(left);
+  }
+  function and() {
+    let left = cmp();
+    while (peek() && peek().type === '&&') { pos++; const right = cmp(); left = Boolean(left) && Boolean(right); }
+    return left;
+  }
+  function or() {
+    let left = and();
+    while (peek() && peek().type === '||') { pos++; const right = and(); left = Boolean(left) || Boolean(right); }
+    return left;
+  }
+  const result = or();
+  if (pos !== tokens.length) throw new Error(`policy-gate: unexpected trailing token at ${pos}`);
+  return result;
+}
+
+// DEPRECATED — evaluate a legacy string-DSL rule. Returns { result, error }.
+export function evaluateRule(rule, { intake, context }) {
+  if (!rule || typeof rule !== 'string') return { result: true, error: null };
+  try {
+    const tokens = tokenize(rule);
+    const result = Boolean(evalTokens(tokens, { intake, context }));
+    return { result, error: null };
+  } catch (err) {
+    return { result: false, error: err?.message || String(err) };
+  }
+}

package/lib/process/stages/policy-gate.js

@@ -1,14 +1,13 @@
 // lib/process/stages/policy-gate.js — handler for policy_gate stages.
 //
 // Evaluates declarative rules against the case's intake + accumulated context.
-// Rule grammar is a small expression dialect supporting:
-//   - intake.<field>
-//   - prior_stage('<slug>').<field>
-//   - Comparison: ==, !=, <, <=, >, >=
-//   - Logical: && ||, parens
-//   - String literals: 'foo'
-//   - Number literals: 1, 0.5
-//   - Membership: <left> IN [<lit>, <lit>, ...]
+// Each entry in `config.rules` is one of:
+//   - a JSON predicate     → `../policy-predicates.js` (the canonical form)
+//   - a string expression  → legacy DSL (`./policy-dsl-legacy.js`, deprecated,
+//     kept one release for back-compat; routed per-rule)
+//   - { expr, label }      → legacy DSL wrapper
+//
+// All rules must pass (implicit AND across the array) for the gate to pass.
 //
 // Outcomes:
 //   - rules all pass         → kind=pass
@@ -17,166 +16,25 @@
 //     downstream human_approval handles this)
 
 import { createApprovalRequest } from '../../approvals.js';
+import { evaluatePredicateSafe, isPredicateRule, describePredicate } from '../policy-predicates.js';
+import { evaluateRule } from './policy-dsl-legacy.js';
 
-function readPath(obj, path) {
-  if (!obj || !path) return undefined;
-  return path.split('.').reduce((acc, key) => (acc == null ? acc : acc[key]), obj);
-}
-
-function tokenize(expr) {
-  const tokens = [];
-  let i = 0;
-  while (i < expr.length) {
-    const ch = expr[i];
-    if (/\s/.test(ch)) { i++; continue; }
-    if (ch === '(' || ch === ')' || ch === '[' || ch === ']' || ch === ',') {
-      tokens.push({ type: ch }); i++; continue;
-    }
-    if (ch === '&' && expr[i + 1] === '&') { tokens.push({ type: '&&' }); i += 2; continue; }
-    if (ch === '|' && expr[i + 1] === '|') { tokens.push({ type: '||' }); i += 2; continue; }
-    if (ch === '=' && expr[i + 1] === '=') { tokens.push({ type: 'op', value: '==' }); i += 2; continue; }
-    if (ch === '!' && expr[i + 1] === '=') { tokens.push({ type: 'op', value: '!=' }); i += 2; continue; }
-    if (ch === '<' && expr[i + 1] === '=') { tokens.push({ type: 'op', value: '<=' }); i += 2; continue; }
-    if (ch === '>' && expr[i + 1] === '=') { tokens.push({ type: 'op', value: '>=' }); i += 2; continue; }
-    if (ch === '<' || ch === '>') { tokens.push({ type: 'op', value: ch }); i++; continue; }
-    if (ch === "'" || ch === '"') {
-      const end = expr.indexOf(ch, i + 1);
-      if (end === -1) throw new Error(`policy-gate: unterminated string at ${i}`);
-      tokens.push({ type: 'string', value: expr.slice(i + 1, end) });
-      i = end + 1; continue;
-    }
-    if (/[0-9.]/.test(ch)) {
-      let j = i;
-      while (j < expr.length && /[0-9.]/.test(expr[j])) j++;
-      tokens.push({ type: 'number', value: Number(expr.slice(i, j)) });
-      i = j; continue;
-    }
-    if (/[A-Za-z_]/.test(ch)) {
-      let j = i;
-      while (j < expr.length && /[A-Za-z0-9_.]/.test(expr[j])) j++;
-      const word = expr.slice(i, j);
-      if (word === 'IN' || word === 'in') { tokens.push({ type: 'IN' }); }
-      else if (word === 'true') { tokens.push({ type: 'boolean', value: true }); }
-      else if (word === 'false') { tokens.push({ type: 'boolean', value: false }); }
-      else if (word === 'prior_stage' && expr[j] === '(') {
-        // Parse prior_stage('slug').field
-        const closeQuote = expr.indexOf(')', j);
-        const inner = expr.slice(j + 1, closeQuote).trim().replace(/^['"]|['"]$/g, '');
-        let k = closeQuote + 1;
-        // Expect .field
-        if (expr[k] !== '.') throw new Error("policy-gate: expected '.' after prior_stage(...)");
-        let m = k + 1;
-        while (m < expr.length && /[A-Za-z0-9_.]/.test(expr[m])) m++;
-        tokens.push({ type: 'ref', kind: 'prior_stage', stage: inner, path: expr.slice(k + 1, m) });
-        i = m; continue;
-      } else {
-        tokens.push({ type: 'ref', kind: 'path', path: word });
-      }
-      i = j; continue;
-    }
-    throw new Error(`policy-gate: unexpected character "${ch}" at ${i}`);
-  }
-  return tokens;
-}
-
-function resolveRef(token, ctx) {
-  if (token.kind === 'prior_stage') {
-    return readPath(ctx.context?.[token.stage], token.path);
-  }
-  // path like intake.email or stage_output.foo.bar
-  if (token.path.startsWith('intake.')) {
-    return readPath(ctx.intake, token.path.slice('intake.'.length));
-  }
-  if (token.path.startsWith('context.')) {
-    return readPath(ctx.context, token.path.slice('context.'.length));
-  }
-  return readPath(ctx, token.path);
-}
-
-function evalTokens(tokens, ctx) {
-  // Pratt-ish recursive descent. Grammar:
-  //   expr := or
-  //   or := and ('||' and)*
-  //   and := cmp ('&&' cmp)*
-  //   cmp := value (op value)?
-  //        | value IN '[' values ']'
-  //   value := ref | number | string | boolean | '(' or ')'
-  let pos = 0;
-  function peek() { return tokens[pos]; }
-  function consume(type) {
-    const t = tokens[pos];
-    if (!t || t.type !== type) throw new Error(`policy-gate: expected ${type}, got ${t?.type || 'EOF'}`);
-    pos++;
-    return t;
-  }
-  function value() {
-    const t = peek();
-    if (!t) throw new Error('policy-gate: unexpected end of expression');
-    if (t.type === '(') { pos++; const e = or(); consume(')'); return e; }
-    if (t.type === 'number' || t.type === 'string' || t.type === 'boolean') {
-      pos++;
-      return t.value;
-    }
-    if (t.type === 'ref') {
-      pos++;
-      return resolveRef(t, ctx);
-    }
-    throw new Error(`policy-gate: unexpected token ${t.type}`);
-  }
-  function cmp() {
-    const left = value();
-    const t = peek();
-    if (!t) return Boolean(left);
-    if (t.type === 'op') {
-      pos++;
-      const right = value();
-      switch (t.value) {
-        case '==': return left == right; // eslint-disable-line eqeqeq
-        case '!=': return left != right; // eslint-disable-line eqeqeq
-        case '<': return Number(left) < Number(right);
-        case '<=': return Number(left) <= Number(right);
-        case '>': return Number(left) > Number(right);
-        case '>=': return Number(left) >= Number(right);
-      }
-    }
-    if (t.type === 'IN') {
-      pos++;
-      consume('[');
-      const list = [];
-      while (peek() && peek().type !== ']') {
-        const v = value();
-        list.push(v);
-        if (peek() && peek().type === ',') pos++;
-      }
-      consume(']');
-      return list.includes(left);
-    }
-    return Boolean(left);
-  }
-  function and() {
-    let left = cmp();
-    while (peek() && peek().type === '&&') { pos++; const right = cmp(); left = Boolean(left) && Boolean(right); }
-    return left;
-  }
-  function or() {
-    let left = and();
-    while (peek() && peek().type === '||') { pos++; const right = and(); left = Boolean(left) || Boolean(right); }
-    return left;
-  }
-  const result = or();
-  if (pos !== tokens.length) throw new Error(`policy-gate: unexpected trailing token at ${pos}`);
-  return result;
-}
+// Re-exported for back-compat: tests and any callers still importing the
+// legacy string-DSL evaluator from this module keep working during the
+// deprecation window.
+export { evaluateRule };
 
-export function evaluateRule(rule, { intake, context }) {
-  if (!rule || typeof rule !== 'string') return { result: true, error: null };
-  try {
-    const tokens = tokenize(rule);
-    const result = Boolean(evalTokens(tokens, { intake, context }));
-    return { result, error: null };
-  } catch (err) {
-    return { result: false, error: err?.message || String(err) };
+// Evaluate one rule entry — predicate JSON or legacy string — returning a
+// uniform { result, error, label } record for the trace.
+function evaluateRuleEntry(rule, ctx) {
+  if (isPredicateRule(rule)) {
+    const { result, error } = evaluatePredicateSafe(rule, ctx);
+    return { result, error, label: rule.label || describePredicate(rule) };
   }
+  const expr = typeof rule === 'string' ? rule : rule?.expr;
+  const label = typeof rule === 'string' ? rule : (rule?.label || rule?.expr);
+  const { result, error } = evaluateRule(expr, ctx);
+  return { result, error, label };
 }
 
 export async function executeStage({ case: c, stage }) {
@@ -187,9 +45,7 @@ export async function executeStage({ case: c, stage }) {
   const trace = [];
   let allPass = true;
   for (const rule of rules) {
-    const expr = typeof rule === 'string' ? rule : rule?.expr;
-    const label = typeof rule === 'string' ? rule : (rule?.label || rule?.expr);
-    const { result, error } = evaluateRule(expr, { intake, context });
+    const { result, error, label } = evaluateRuleEntry(rule, { intake, context });
     trace.push({ rule: label, result, error });
     if (!result) allPass = false;
   }

package/lib/runtime.js

@@ -13,6 +13,7 @@ import { defaultModelForEngine, normalizeAgentEngine } from './agent-engines.js'
 import { DEFAULT_PROJECT_ID, appendProjectChangelog, getProject } from './projects.js';
 import { listActivity, listTasks, reportingSnapshot } from './delegation.js';
 import { getMainAgentTrustMode } from './tools/registry.js';
+import { defaultSkillsMarkdown } from './marketplace-seeds.js';
 import { publishLiveEvent, publishStateChanged } from './live-events.js';
 import { resolveTargetSpace } from './dashboard-spaces.js';
 
@@ -777,9 +778,17 @@ function writeAgentFiles(agent) {
   fs.writeFileSync(path.join(dir, 'AGENTS.md'),
     `# ${agent.name}\n\nParent orchestrator: madarX Main Agent.\n\n## Mission\n${agent.mission}\n\n## Runtime\n- Engine: ${agent.engine}\n- Model: ${agent.model || 'default'}\n- Schedule: ${agent.schedule}\n- Approval: human-in-loop before external sends/posts/deployments.\n\n## Operating rules\n1. Work only inside the approved local project/workspace unless the orchestrator grants a path.\n2. Use web/social/email tools in read or draft mode first.\n3. Save artifacts under your project's artifacts folder (workspace/projects/<slug>/artifacts/).\n4. Never send emails, WhatsApp messages, social posts, deployments, purchases, or destructive commands without explicit approval.\n5. Update heartbeat.json after each run.\n`);
 
-  const skillsMarkdown = typeof agent.skills_markdown === 'string' && agent.skills_markdown.trim()
-    ? agent.skills_markdown.trim() + '\n'
-    : `# ${agent.name} Skills\n\n## Mission\n${agent.mission}\n\n## Core playbooks\n- Plan each run from the mission, then execute against the ${agent.schedule} window.\n- Use only the approved tools (${(agent.tools || []).join(', ') || 'web-search, browser, files'}); never reach for tools the owner has not enabled.\n- Save every output as a local artifact under your project's artifacts folder (workspace/projects/<slug>/artifacts/).\n- Hand off any external send, post, deployment, or destructive command to the main agent for approval.\n- After each run, update heartbeat.json with status, summary, and next-run plan.\n`;
+  let skillsMarkdown;
+  if (typeof agent.skills_markdown === 'string' && agent.skills_markdown.trim()) {
+    skillsMarkdown = agent.skills_markdown.trim() + '\n';
+  } else {
+    // Default skills.md: mission + core playbooks + the business-default skill
+    // pack so a fresh agent can do real work out of the box (the runtime reads
+    // this file into the prompt; the default skills are gated by the same tools).
+    let defaultSkills = '';
+    try { defaultSkills = '\n' + defaultSkillsMarkdown(); } catch { /* optional */ }
+    skillsMarkdown = `# ${agent.name} Skills\n\n## Mission\n${agent.mission}\n\n## Core playbooks\n- Plan each run from the mission, then execute against the ${agent.schedule} window.\n- Use only the approved tools (${(agent.tools || []).join(', ') || 'web-search, browser, files'}); never reach for tools the owner has not enabled.\n- Save every output as a local artifact under your project's artifacts folder (workspace/projects/<slug>/artifacts/).\n- Hand off any external send, post, deployment, or destructive command to the main agent for approval.\n- After each run, update heartbeat.json with status, summary, and next-run plan.\n${defaultSkills}`;
+  }
   fs.writeFileSync(path.join(dir, 'skills.md'), skillsMarkdown);
 
   fs.writeFileSync(path.join(dir, 'tools.md'),
@@ -806,6 +815,46 @@ function writeAgentFiles(agent) {
   return files;
 }
 
+/**
+ * One-time migration: refresh the business-default skills block in existing
+ * agents' skills.md. Only touches files that are the GENERATED DEFAULT (they
+ * carry the `## Core playbooks` header) — a user-customized skills.md is left
+ * untouched. Idempotent: re-running replaces an existing `## Default skills`
+ * section in place rather than appending, and is a no-op once current.
+ *
+ * @returns {{ scanned: number, updated: number }}
+ */
+export function migrateDefaultAgentSkills() {
+  let scanned = 0;
+  let updated = 0;
+  let block;
+  try { block = defaultSkillsMarkdown().trimEnd() + '\n'; } catch { return { scanned, updated }; }
+  let dirs = [];
+  try { dirs = fs.readdirSync(AGENTS_DIR, { withFileTypes: true }).filter(d => d.isDirectory()); } catch { return { scanned, updated }; }
+
+  for (const d of dirs) {
+    const p = path.join(AGENTS_DIR, d.name, 'skills.md');
+    let body;
+    try { body = fs.readFileSync(p, 'utf8'); } catch { continue; }
+    scanned++;
+    // Only refresh the generated-default shape; never overwrite custom content.
+    if (!body.includes('## Core playbooks')) continue;
+
+    let next;
+    const marker = '\n## Default skills';
+    const idx = body.indexOf(marker);
+    if (idx >= 0) {
+      next = body.slice(0, idx).trimEnd() + '\n\n' + block; // replace old section
+    } else {
+      next = body.trimEnd() + '\n\n' + block;               // append, was missing
+    }
+    if (next !== body) {
+      try { fs.writeFileSync(p, next); updated++; } catch { /* best-effort */ }
+    }
+  }
+  return { scanned, updated };
+}
+
 export function createAgent(payload = {}) {
   const db = getDb();
   const name = payload.name || 'Client Workspace Custom Agent';

package/lib/seeds.js

@@ -5,7 +5,7 @@ import { ROOT } from './paths.js';
 import { seedMarketplaceItems } from './marketplace-seeds.js';
 import { ensureDefaultProject } from './projects.js';
 import { seedAgentTemplates, installAgentTemplate } from './agent-templates.js';
-import { ensureOpsAgent, createArtifact } from './runtime.js';
+import { ensureOpsAgent, createArtifact, migrateDefaultAgentSkills } from './runtime.js';
 import { renderChangelogHtml } from './artifact-format.js';
 import { migrateArtifactsToProjects } from './artifact-migration.js';
 import { runAuthV1Migration } from '../scripts/migrate-auth-v1.mjs';
@@ -538,6 +538,10 @@ export function seedDefaults(db) {
   // Auto-seed the Tool Smith agent so request_capability delegation has a target.
   seedToolSmithAgentIfMissing(db);
 
+  // Refresh the business-default skills in existing default-shaped skills.md
+  // files (no-op for fresh installs and user-customized agents). Idempotent.
+  try { migrateDefaultAgentSkills(); } catch (err) { console.warn('[seeds] migrateDefaultAgentSkills failed:', err?.message || err); }
+
   // Dashboard spaces: seed the 'default' space and backfill any NULL-space
   // artifacts so the dashboard never has to reconcile orphans client-side.
   // Idempotent. Must run after schema migration adds artifacts.space_id.

package/lib/tools/registry.js

@@ -1971,6 +1971,26 @@ export function listPrimitiveToolMeta() {
   return { names, riskByName };
 }
 
+/**
+ * Static tool catalog grouped by category — pure read of MARKETPLACE_TOOLS, no
+ * DB, no install state. Used by the CLI banner (which runs in the DB-free
+ * supervisor) to render a grouped capability list à la Hermes.
+ *
+ * @returns {Array<{category: string, count: number, names: string[]}>}
+ *          sorted by descending count.
+ */
+export function listToolCategories() {
+  const byCat = new Map();
+  for (const t of MARKETPLACE_TOOLS) {
+    const cat = t.category || 'other';
+    if (!byCat.has(cat)) byCat.set(cat, []);
+    byCat.get(cat).push(t.name);
+  }
+  return [...byCat.entries()]
+    .map(([category, names]) => ({ category, count: names.length, names }))
+    .sort((a, b) => b.count - a.count || a.category.localeCompare(b.category));
+}
+
 /**
  * Dynamic tool descriptors (composites + connector endpoints), normalized into
  * the SAME shape as a static row so every downstream consumer (executeRegistryTool

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "madarx",
-  "version": "2.12.1",
+  "version": "2.14.0",
   "type": "module",
   "description": "Madarx OS — Next.js product with SQLite-backed runtime, scheduled cron daemon, and approval-gated local runners.",
   "license": "MIT",
@@ -44,6 +44,9 @@
     "prepublishOnly": "npm run build",
     "build": "NODE_OPTIONS=--no-warnings next build",
     "postbuild": "node --no-warnings scripts/postbuild-standalone.mjs",
+    "postinstall": "node --no-warnings scripts/postinstall-splash.mjs",
+    "splash": "MADARX_FORCE_SPLASH=1 FORCE_COLOR=1 node --no-warnings scripts/postinstall-splash.mjs",
+    "banner": "FORCE_COLOR=1 node --no-warnings scripts/preview-banner.mjs",
     "start": "next start -p 8787 -H 127.0.0.1",
     "test": "node --no-warnings --test tests/*.test.js",
     "daemon": "node --no-warnings --env-file-if-exists=.env.local scripts/cron-daemon.mjs",

package/scripts/postbuild-standalone.mjs

@@ -38,4 +38,13 @@ if (!fs.existsSync(STANDALONE)) {
 
 copyInto(path.join('.next', 'static'), path.join('.next', 'static'));
 copyInto('public', 'public');
+
+for (const envName of ['.env', '.env.local', '.env.development', '.env.production', '.env.test']) {
+  const envPath = path.join(STANDALONE, envName);
+  if (fs.existsSync(envPath)) {
+    fs.rmSync(envPath, { force: true });
+    console.log(`[postbuild] removed ${path.join('.next', 'standalone', envName)} from publish bundle`);
+  }
+}
+
 console.log('[postbuild] standalone bundle is self-serving.');