@aifabrix/builder 2.58.0 → 2.60.0

package/lib/commands/agent-kit-sessions.js

@@ -0,0 +1,126 @@
+/** CLI actions for listing, attaching, and stopping Agent Kit sessions. */
+'use strict';
+
+const inquirer = require('inquirer');
+const logger = require('../utils/logger');
+const { handleCommandError } = require('../utils/cli-utils');
+const { formatSuccessLine } = require('../utils/cli-layout-chalk');
+const { runList, runKill, runAttach } = require('../agent-kit/tmux-sessions');
+const { listCodexAppServers, stopCodexAppServer } = require('../agent-kit/codex-app-server');
+const { formatSessionList, formatMissingKillName } = require('../agent-kit/session-report');
+const { LIST_HELP, KILL_HELP } = require('./agent-kit-help');
+
+function emitListReport(report, asJson) {
+  logger.log(asJson ? JSON.stringify(report, null, 2) : formatSessionList(report));
+}
+
+function emitKillReport(report, asJson) {
+  logger.log(asJson ? JSON.stringify(report, null, 2)
+    : formatSuccessLine(report.kind === 'codex-app-server'
+      ? `Sent stop signal to Codex app server PID ${report.pid}`
+      : `Stopped tmux session ${report.session}`));
+}
+
+function listSessions(options = {}) {
+  const report = (options.runList || runList)(options);
+  const codexServers = (options.listCodexAppServers || listCodexAppServers)(options);
+  return { ...report, codexServers, serverCount: codexServers.length };
+}
+
+async function runListLeaf(options = {}) {
+  try {
+    const report = listSessions(options);
+    emitListReport(report, Boolean(options.json));
+    const tty = options.isTTY === undefined
+      ? Boolean(process.stdin.isTTY && process.stdout.isTTY) : options.isTTY;
+    if (!tty || options.json || report.sessions.length === 0) return;
+    const choices = report.sessions.map(session => ({
+      name: `${session.name} (${session.attached ? 'attached' : 'detached'})`, value: session.name
+    }));
+    choices.push({ name: 'Close', value: null });
+    const answer = await (options.prompt || inquirer.prompt)([{
+      type: 'list', name: 'name', message: 'Attach to a tmux session:', choices
+    }]);
+    if (answer.name) (options.runAttach || runAttach)({ ...options, name: answer.name });
+  } catch (error) {
+    handleCommandError(error, 'agent-kit list');
+    process.exitCode = 1;
+  }
+}
+
+async function selectKillSession(options = {}) {
+  const tty = options.isTTY === undefined
+    ? Boolean(process.stdin.isTTY && process.stdout.isTTY) : options.isTTY;
+  if (!tty || options.json) return { state: 'missing' };
+  const report = listSessions(options);
+  emitListReport(report, false);
+  if (report.sessions.length + report.codexServers.length === 0) return { state: 'empty' };
+  const choices = report.sessions.map(session => ({
+    name: `tmux: ${session.name} (${session.attached ? 'attached' : 'detached'})`,
+    value: { kind: 'tmux', name: session.name }
+  }));
+  report.codexServers.forEach(server => choices.push({
+    name: `Codex app server (PID ${server.pid})`,
+    value: { kind: 'codex-app-server', ...server }
+  }));
+  choices.push({ name: 'Cancel', value: null });
+  const answer = await (options.prompt || inquirer.prompt)([{
+    type: 'list', name: 'selection', message: 'Select one session to stop:', choices
+  }]);
+  if (!answer.selection) return { state: 'cancelled' };
+  if (answer.selection.kind === 'codex-app-server') {
+    const confirm = await (options.prompt || inquirer.prompt)([{
+      type: 'confirm', name: 'stop', default: false,
+      message: `Stop Codex app server PID ${answer.selection.pid}? This may disconnect this chat; the client may reconnect.`
+    }]);
+    if (!confirm.stop) return { state: 'cancelled' };
+  }
+  return { state: 'selected', ...answer.selection };
+}
+
+function addListCommand(group) {
+  group.command('list')
+    .description('List sessions and choose a tmux session to attach')
+    .option('--json', 'Machine-readable output')
+    .addHelpText('after', LIST_HELP)
+    .action(runListLeaf);
+}
+
+function addKillCommand(group) {
+  group.command('kill [name]')
+    .description('Stop a tmux session by name, or choose a session interactively')
+    .option('--json', 'Machine-readable output')
+    .addHelpText('after', KILL_HELP)
+    .action(runKillLeaf);
+}
+
+async function runKillLeaf(name, options = {}) {
+  try {
+    const selection = name ? { state: 'selected', kind: 'tmux', name } : await selectKillSession(options);
+    if (selection.state === 'missing') {
+      const report = formatMissingKillName(Boolean(options.json));
+      logger.error(report.stderr);
+      if (report.stdout) logger.log(report.stdout);
+      process.exitCode = 1;
+      return;
+    }
+    if (selection.state === 'empty' || selection.state === 'cancelled') {
+      logger.log('No session stopped.');
+      return;
+    }
+    const report = selection.kind === 'codex-app-server'
+      ? (options.stopCodexAppServer || stopCodexAppServer)(selection, options)
+      : (options.runKill || runKill)({ ...options, name: selection.name });
+    emitKillReport(report, Boolean(options.json));
+  } catch (error) {
+    handleCommandError(error, 'agent-kit kill');
+    process.exitCode = 1;
+  }
+}
+
+function addSessionCommands(group) {
+  addListCommand(group);
+  addKillCommand(group);
+}
+
+module.exports = { addSessionCommands, listSessions, runListLeaf, selectKillSession, runKillLeaf };

package/lib/commands/agent-kit-setup.js

@@ -0,0 +1,44 @@
+/** Minimal setup command: controller required, local Codex workspace by default. */
+'use strict';
+
+const logger = require('../utils/logger');
+const { formatBlockingError } = require('../utils/cli-layout-chalk');
+const { maskSensitiveData } = require('../utils/log-redaction');
+const { runSetup } = require('../agent-kit/setup');
+
+const SETUP_HELP = `
+Start onboarding with only a Controller URL. Defaults to Codex and a local Git
+workspace under the AI Fabrix work directory; GitHub is not required.
+If the work directory is unset, setup asks once and saves it.
+
+Examples:
+  $ aifabrix agent-kit setup https://controller.example.com
+  $ aifabrix agent-kit setup https://controller.example.com --code claude
+  $ aifabrix agent-kit setup https://controller.example.com --repo example-org/example-workspace
+
+With --repo owner/name, setup reuses a matching local checkout, clones an accessible
+remote, or creates a private repository and pushes. Unresolved access stops safely.
+Without --repo, files stay local and no GitHub login or push occurs.
+Folder name is the repository name, or workspace without --repo. Change environment with
+aifabrix auth --set-environment <environment>.
+Requires an interactive Linux/macOS terminal, git and tmux (gh only for GitHub).
+Installing a missing Claude CLI through npm requires Node.js 22+.
+`;
+
+function addSetupCommand(group) {
+  group.command('setup <controllerUrl>')
+    .description('Onboard a local Codex workspace; optionally use Claude or GitHub')
+    .option('--repo <owner/name>', 'GitHub repository to reuse, clone, or create privately')
+    .option('--code <agent>', 'Coding agent: codex or claude', 'codex')
+    .addHelpText('after', SETUP_HELP)
+    .action(async(controllerUrl, options) => {
+      try {
+        await runSetup({ ...options, controllerUrl });
+      } catch (error) {
+        logger.error(formatBlockingError(maskSensitiveData(error.message)));
+        process.exitCode = 1;
+      }
+    });
+}
+
+module.exports = { addSetupCommand, SETUP_HELP };

package/lib/commands/agent-kit.js

@@ -1,5 +1,4 @@
 /** `aifabrix agent-kit` command group. */
-
 'use strict';
 
 const logger = require('../utils/logger');
@@ -11,8 +10,8 @@ const {
 } = require('../utils/cli-layout-chalk');
 const { runInstall, runUpdate } = require('../agent-kit/run');
 const { runStart } = require('../agent-kit/start');
-const { runList, runKill } = require('../agent-kit/tmux-sessions');
-const { formatSessionList, formatMissingKillName } = require('../agent-kit/session-report');
+const { addSetupCommand } = require('./agent-kit-setup');
+const { addSessionCommands } = require('./agent-kit-sessions');
 const path = require('path');
 const { runInit, runRemoteCreate } = require('../agent-kit/init');
 const { enrichInitHostOptions, enrichInitRemoteOptions, enrichRemoteOptions, enrichApproveAllOptions } = require('../agent-kit/remote-prompts');
@@ -33,8 +32,6 @@ const {
   REMOTE_GROUP_HELP,
   REMOTE_HELP,
   START_HELP,
-  LIST_HELP,
-  KILL_HELP,
   HOST_OPTION_HELP,
   APPROVE_ALL_OPTION_HELP
 } = require('./agent-kit-help');
@@ -131,32 +128,6 @@ function emitStartReport(json, asJson) {
   logger.log(formatSuccessLine(json.dryRun ? 'Dry-run complete' : 'Ready'));
 }
 
-/**
- * @param {object} json
- * @param {boolean} asJson
- * @returns {void}
- */
-function emitListReport(json, asJson) {
-  if (asJson) {
-    logger.log(JSON.stringify(json, null, 2));
-    return;
-  }
-  logger.log(formatSessionList(json));
-}
-
-/**
- * @param {object} json
- * @param {boolean} asJson
- * @returns {void}
- */
-function emitKillReport(json, asJson) {
-  if (asJson) {
-    logger.log(JSON.stringify(json, null, 2));
-    return;
-  }
-  logger.log(formatSuccessLine(`Stopped tmux session ${json.session}`));
-}
-
 /**
  * @param {Function} runner
  * @param {object} options
@@ -185,6 +156,7 @@ function setupAgentKitCommands(program) {
     .description('Install, init, and update the AI Fabrix Agent Kit in a customer workspace')
     .addHelpText('after', GROUP_HELP);
 
+  addSetupCommand(group);
   addInitCommand(group);
   addInstallCommand(group);
   addStatusCommand(group);
@@ -192,8 +164,7 @@ function setupAgentKitCommands(program) {
   addValidateCommand(group);
   addRemoteCommand(group);
   addStartCommand(group);
-  addListCommand(group);
-  addKillCommand(group);
+  addSessionCommands(group);
 }
 
 /**
@@ -254,7 +225,7 @@ function addRemoteCommand(group) {
     .command('create')
     .description('Create a private GitHub repository (origin) and push this workspace')
     .option('--org <owner>', 'Hosting org or user (required when non-TTY)')
-    .option('--name <repo>', 'Remote repository name (default: directory basename)')
+    .option('--name <repo>', 'New GitHub repository name (default: workspace folder name)')
     .option('--visibility <mode>', 'private or public', 'private')
     .option('--yes', 'Silent: skip TTY confirmation (pair with --org)')
     .option('--dry-run', 'Plan without creating the remote')
@@ -451,49 +422,4 @@ function addStartCommand(group) {
     });
 }
 
-/**
- * @param {import('commander').Command} group
- */
-function addListCommand(group) {
-  group
-    .command('list')
-    .description('List active tmux sessions for the current user')
-    .option('--json', 'Machine-readable output')
-    .addHelpText('after', LIST_HELP)
-    .action(async(options) => {
-      try {
-        emitListReport(runList(options), Boolean(options.json));
-      } catch (error) {
-        handleCommandError(error, 'agent-kit list');
-        process.exitCode = 1;
-      }
-    });
-}
-
-/**
- * @param {import('commander').Command} group
- */
-function addKillCommand(group) {
-  group
-    .command('kill [name]')
-    .description('Stop one tmux session by exact name')
-    .option('--json', 'Machine-readable output')
-    .addHelpText('after', KILL_HELP)
-    .action(async(name, options) => {
-      if (!name) {
-        const report = formatMissingKillName(Boolean(options.json));
-        logger.error(report.stderr);
-        if (report.stdout) logger.log(report.stdout);
-        process.exitCode = 1;
-        return;
-      }
-      try {
-        emitKillReport(runKill({ ...options, name }), Boolean(options.json));
-      } catch (error) {
-        handleCommandError(error, 'agent-kit kill');
-        process.exitCode = 1;
-      }
-    });
-}
-
 module.exports = { setupAgentKitCommands };

package/lib/commands/dev-init.js

@@ -29,13 +29,13 @@ const {
   isLinuxCaSudoRequiredError
 } = require('../utils/dev-ca-install');
 const { runOptionalHostsSetup } = require('../utils/dev-hosts-helper');
-const { mergeDevSshConfigAfterInit } = require('../utils/dev-init-ssh-merge');
+const { mergeDevSshConfigAfterInit, hostnameFromBaseUrl } = require('../utils/dev-init-ssh-merge');
 const { resolveInitOptions } = require('../utils/dev-init-resolve');
 const {
   isHealthHttpServerError,
   formatEnsureServerTrustedFailure
 } = require('../utils/dev-init-health-messages');
-const { getBadRequestHint, logCertTroubleshootingHint } = require('../utils/dev-init-cert-hints');
+const { getBadRequestHint } = require('../utils/dev-init-cert-hints');
 const { augmentAndSaveCaPemForRemoteDocker } = require('../utils/dev-ca-docker-augment');
 
 /**
@@ -249,7 +249,7 @@ async function _runSshKeyRegistrationStep(baseUrl, issueResponse, keyPem, config
   } catch (err) {
     const msg = err.status === 400 ? getBadRequestHint() : (err.message || String(err));
     logger.log(chalk.yellow('  ⚠ Could not register SSH key: ' + msg));
-    logCertTroubleshootingHint(configDir, devId, baseUrl);
+    throw new Error(`Onboarding incomplete for developer ${devId}: SSH key registration failed. Ask the server administrator to check role access, then retry dev init with a new PIN.`);
   }
 }
 
@@ -262,24 +262,23 @@ async function _runSshKeyRegistrationStep(baseUrl, issueResponse, keyPem, config
  * @param {string} [serverCaPem] - Dev root CA for Node TLS
  */
 async function applySettingsFromServer(baseUrl, devId, issueResponse, keyPem, serverCaPem) {
-  const configDir = getConfigDirForPaths();
-  if (issueResponse.settings && typeof issueResponse.settings === 'object') {
-    await config.mergeRemoteSettings(issueResponse.settings);
-    logger.log(chalk.green('  ') + formatSuccessLine('Config updated from server (issue-cert response)'));
-    return;
-  }
-  logger.log(chalk.gray('  Fetching settings...'));
   try {
-    if (keyPem && typeof keyPem === 'string') {
-      logger.log(chalk.gray('  Using client certificate for TLS'));
+    let settings = issueResponse.settings;
+    if (!settings) {
+      logger.log(chalk.gray('  Fetching settings...'));
+      settings = await devApi.getSettings(baseUrl, issueResponse.certificate, keyPem, serverCaPem);
     }
-    const settings = await devApi.getSettings(baseUrl, issueResponse.certificate, keyPem, serverCaPem);
-    await config.mergeRemoteSettings(settings);
+    if (!settings || typeof settings !== 'object' || Array.isArray(settings)) throw new Error('Server settings are missing or invalid.');
+    const fresh = { ...settings, 'developer-id': devId, 'remote-server': baseUrl,
+      'sync-ssh-user': settings['sync-ssh-user'] || `dev${devId}`,
+      'sync-ssh-host': settings['sync-ssh-host'] || hostnameFromBaseUrl(baseUrl) };
+    await config.mergeRemoteSettings(fresh);
     logger.log(chalk.green('  ') + formatSuccessLine('Config updated from server'));
+    return fresh;
   } catch (err) {
     const msg = err.status === 400 ? getBadRequestHint() : (err.message || String(err));
-    logger.log(chalk.yellow('  ⚠ Could not fetch settings (server may not support cert yet): ' + msg));
-    logCertTroubleshootingHint(configDir, devId, baseUrl);
+    logger.log(chalk.yellow('  ⚠ Could not fetch settings: ' + msg));
+    throw new Error(`Onboarding incomplete for developer ${devId}: current server settings could not be applied. Saved settings from another developer will not be used. Ask the server administrator to check role access, then retry dev init with a new PIN.`);
   }
 }
 
@@ -317,7 +316,7 @@ async function resolveServerCaPemForTls(baseUrl, options) {
  * @param {{ hostAlias: string|null, syncUser: string, syncHost: string|null }} p
  */
 function logOnboardingFinished({ hostAlias, syncUser, syncHost }) {
-  logger.log(formatSuccessParagraph('Onboarding complete. You can use remote Docker and Mutagen sync.'));
+  logger.log(formatSuccessParagraph('Certificate, server settings and SSH key registration complete. Access depends on your server permissions.'));
   if (hostAlias) {
     logger.log(
       chalk.gray('  You can also open an SSH session on the builder with ') +
@@ -367,14 +366,13 @@ async function runDevInit(options) {
   );
   await saveCertAndConfig(configDir, devId, issueResponse.certificate, keyPem, caPem);
 
-  await applySettingsFromServer(baseUrl, devId, issueResponse, keyPem, serverCaPemForTls || undefined);
-  await augmentAndSaveCaPemForRemoteDocker(configDir, devId, caPem, {
-    settings: issueResponse.settings,
-    remoteServerUrl: baseUrl,
+  const settings = await applySettingsFromServer(baseUrl, devId, issueResponse, keyPem, serverCaPemForTls || undefined);
+  await _runSshKeyRegistrationStep(baseUrl, issueResponse, keyPem, configDir, devId, serverCaPemForTls || undefined);
+  if (settings['docker-endpoint']) await augmentAndSaveCaPemForRemoteDocker(configDir, devId, caPem, {
+    settings,
     warn: (msg) => logger.log(chalk.yellow(`  ⚠ ${msg}`))
   });
-  await _runSshKeyRegistrationStep(baseUrl, issueResponse, keyPem, configDir, devId, serverCaPemForTls || undefined);
-  const sshInfo = await mergeDevSshConfigAfterInit(baseUrl, devId);
+  const sshInfo = await mergeDevSshConfigAfterInit(baseUrl, devId, settings);
   logOnboardingFinished(sshInfo);
 }
 

package/lib/commands/dev-refresh.js

@@ -82,9 +82,9 @@ async function runCertificateRefresh(auth) {
   const issueResponse = await requestCertificate(auth.serverUrl, devId, pin, csrPem, serverCaPem);
   const caPem = mergeCaPemBlocks(serverCaPem, issueResponse.caCertificate, issueResponse.ca);
   await saveCertAndConfig(configDir, devId, issueResponse.certificate, keyPem, caPem);
-  await applySettingsFromServer(auth.serverUrl, devId, issueResponse, keyPem, serverCaPem);
+  const settings = await applySettingsFromServer(auth.serverUrl, devId, issueResponse, keyPem, serverCaPem);
   await augmentAndSaveCaPemForRemoteDocker(configDir, devId, caPem, {
-    settings: issueResponse.settings,
+    settings,
     remoteServerUrl: auth.serverUrl,
     warn: (msg) => logger.log(chalk.yellow(`  ⚠ ${msg}`))
   });

package/lib/commands/governance-verify-external.js

@@ -10,7 +10,7 @@ const {
   aggregateCoverage,
   buildPackOverrideResult
 } = require('./verify-governance-result-builders');
-const { VERDICT, verdictFromPassed } = require('../lifecycle/product-model');
+const { VERDICT } = require('../lifecycle/product-model');
 
 /**
  * @async
@@ -43,14 +43,21 @@ async function runGovernanceVerifyForExternalSystem(systemKey, options = {}) {
     };
   }
 
-  const allVerified = datasourceRows.every(r => r.verdict === VERDICT.VERIFIED);
+  const allNotApplicable = datasourceRows.every(
+    r => r.verdict === VERDICT.NOT_APPLICABLE
+  );
+  const allClosed = datasourceRows.every(
+    r => r.verdict === VERDICT.VERIFIED || r.verdict === VERDICT.NOT_APPLICABLE
+  );
   const coverage = aggregateCoverage(datasourceRows);
   return {
     systemKey: resolvedKey,
     command: 'governance verify',
-    verdict: verdictFromPassed(allVerified),
-    policyCoveragePercent: coverage.policy ?? (allVerified ? 100 : 0),
-    dimensionCoveragePercent: coverage.dimension ?? (allVerified ? 100 : 0),
+    verdict: allNotApplicable
+      ? VERDICT.NOT_APPLICABLE
+      : (allClosed ? VERDICT.VERIFIED : VERDICT.FAILED),
+    policyCoveragePercent: coverage.policy ?? (allClosed ? 100 : 0),
+    dimensionCoveragePercent: coverage.dimension ?? (allClosed ? 100 : 0),
     enforcementScenarios: sumEnforcementScenarios(datasourceRows),
     datasourceRows
   };

package/lib/commands/repair-datasource.js

@@ -16,11 +16,12 @@ const {
   repairNoneLlmToServiceContract,
   stripDeprecatedServiceCategory
 } = require('./repair-datasource-service-contract');
+const {
+  DEFAULT_DATASOURCE_SYNC,
+  createDefaultDatasourceSync
+} = require('../datasource/sync-defaults');
 
-const DEFAULT_SYNC = {
-  mode: 'pull',
-  batchSize: 500
-};
+const DEFAULT_SYNC = DEFAULT_DATASOURCE_SYNC;
 
 const MINIMAL_METADATA_SCHEMA = {
   type: 'object',
@@ -348,7 +349,7 @@ function repairExposeFromAttributes(parsed, changes) {
 }
 
 /**
- * Adds default sync section if missing or empty. Not applied for entityType 'none'.
+ * Adds a default sync section only when absent. Not applied for entityType 'none'.
  *
  * @param {Object} parsed - Parsed datasource (mutated)
  * @param {string[]} changes - Change log
@@ -356,10 +357,9 @@ function repairExposeFromAttributes(parsed, changes) {
  */
 function repairSyncSection(parsed, changes) {
   if (isNoneEntityType(parsed?.entityType)) return false;
-  const sync = parsed.sync;
-  if (sync && typeof sync === 'object' && Object.keys(sync).length > 0) return false;
-  parsed.sync = { ...DEFAULT_SYNC };
-  changes.push('Added default sync section (mode: pull, batchSize: 500)');
+  if (Object.prototype.hasOwnProperty.call(parsed, 'sync')) return false;
+  parsed.sync = createDefaultDatasourceSync();
+  changes.push('Added default sync section (enabled: true, mode: pull, schedule: @monthly UTC, batchSize: 500)');
   return true;
 }
 

package/lib/commands/repair.js

@@ -1,11 +1,11 @@
 /**
- * Repair external integration config: fix drift between config and files on disk.
+ * Repair application documentation and external integration configuration drift.
  *
  * Aligns application.yaml with actual system/datasource files, fixes system key mismatch,
  * creates missing externalIntegration block, extracts rbac.yaml from system when needed,
  * and regenerates the deployment manifest.
  *
- * @fileoverview Repair external integration drift
+ * @fileoverview Repair application README or external integration drift
  * @author AI Fabrix Team
  * @version 2.0.0
  */
@@ -13,6 +13,10 @@
 'use strict';
 
 const fs = require('fs');
+const path = require('path');
+const { generateReadmeMd } = require('../app/readme');
+const { backupIntegrationFile } = require('../utils/integration-file-backup');
+const { trackRepairWrite } = require('./repair-changed-files');
 const { detectAppType } = require('../utils/paths');
 const { resolveApplicationConfigPath } = require('../utils/app-config-resolver');
 const { loadConfigFile, isYamlPath } = require('../utils/config-format');
@@ -43,7 +47,7 @@ function loadConfigAndDiscover(appPath, configPath) {
  * Validates repair inputs and resolves app path and config path.
  * @param {string} appName - Application name
  * @param {Object} options - Command options (auth)
- * @returns {Promise<{ appPath: string, configPath: string, dryRun: boolean, authOption: string|undefined }>}
+ * @returns {Promise<{ appPath: string, configPath: string, dryRun: boolean, authOption: string|undefined, isExternal: boolean }>}
  */
 async function validateAndResolveRepairPaths(appName, options) {
   if (!appName || typeof appName !== 'string') throw new Error('App name is required');
@@ -52,10 +56,42 @@ async function validateAndResolveRepairPaths(appName, options) {
     throw new Error('Option --auth must be a string');
   }
   const { appPath, isExternal } = await detectAppType(appName, options);
-  if (!isExternal) throw new Error(`App '${appName}' is not an external integration`);
+  if (!isExternal) validateApplicationRepairOptions(appName, options);
   const configPath = resolveApplicationConfigPath(appPath);
   if (!fs.existsSync(configPath)) throw new Error(`Application config not found: ${configPath}`);
-  return { appPath, configPath, dryRun, authOption };
+  return { appPath, configPath, dryRun, authOption, isExternal };
+}
+
+/** Validate the documentation-only repair supported for normal applications. */
+function validateApplicationRepairOptions(appName, options) {
+  const integrationOptions = ['all', 'api', 'auth', 'rbac', 'expose', 'sync', 'test',
+    'splitDatasources', 'rbacPreset', 'authWebhook', 'authSync'];
+  if (!options.doc || integrationOptions.some(key => options[key] !== undefined && options[key] !== false && options[key] !== null)) {
+    throw new Error(`App '${appName}' is not an external integration. Normal applications support repair --doc only (with --dry-run or --no-backup).`);
+  }
+}
+
+/** Regenerate a normal application's README using its current local configuration. */
+function repairApplicationReadme(appName, appPath, configPath, backupCtx) {
+  const variables = loadConfigFile(configPath);
+  const content = generateReadmeMd(appName, { ...variables, ...variables.app });
+  const readmePath = path.join(appPath, 'README.md');
+  trackRepairWrite(readmePath, backupCtx);
+  if (!backupCtx.dryRun) {
+    backupIntegrationFile(readmePath, backupCtx);
+    fs.writeFileSync(readmePath, content, { mode: 0o644, encoding: 'utf8' });
+  }
+  return {
+    updated: true,
+    applicationReadme: true,
+    actionsPerformed: true,
+    readmeRegenerated: true,
+    manifestRegenerated: false,
+    changes: ['Regenerated README.md from application configuration'],
+    changedFiles: backupCtx.dryRun ? backupCtx.wouldChangeFiles : backupCtx.changedFiles,
+    backupPaths: backupCtx.backupPaths,
+    warnings: []
+  };
 }
 
 /**
@@ -79,17 +115,18 @@ function createRepairBackupContext(options, dryRun) {
 }
 
 /**
- * Repairs external integration config: syncs files, aligns keys, creates rbac, regenerates manifest
+ * Repairs external integration config or regenerates a normal application's README.
  * @async
  * @param {string} appName - Application/integration name
  * @param {Object} [options] - Options
  * @param {boolean} [options.dryRun] - If true, only report changes; do not write
- * @param {boolean} [options.doc] - If true, regenerate README.md from deployment manifest
+ * @param {boolean} [options.doc] - Regenerate README.md from application config or integration deployment manifest
  * @returns {Promise<Object>}
  */
 async function repairExternalIntegration(appName, options = {}) {
-  const { appPath, configPath, dryRun, authOption } = await validateAndResolveRepairPaths(appName, options);
+  const { appPath, configPath, dryRun, authOption, isExternal } = await validateAndResolveRepairPaths(appName, options);
   const { backupPaths, backupCtx } = createRepairBackupContext(options, dryRun);
+  if (!isExternal) return repairApplicationReadme(appName, appPath, configPath, backupCtx);
   const loaded = loadConfigAndDiscover(appPath, configPath);
   return runRepairExternalIntegration({
     appName,

package/lib/commands/role-assistant.js

@@ -41,6 +41,10 @@ const {
   patchCaseStatusAfterRun
 } = require('../role-assistant/test-pack-sync');
 const { collectString } = require('./governance');
+const {
+  hasRoleAssistantTestSubject,
+  runPublishedCaseAsSubject
+} = require('../role-assistant/test-job-runner');
 const {
   sectionTitle,
   headerKeyValue,
@@ -338,6 +342,9 @@ async function resolveExecutableCaseResult(roleKey, roleCase, opts, result, verd
     run: false,
     noPublish: true
   });
+  if (hasRoleAssistantTestSubject(opts)) {
+    return runPublishedCaseAsSubject(roleKey, roleCase, opts, authContext);
+  }
   const evidencePreflight = await assertRoleAssistantEvidencePreflight(roleCase, authContext);
   const executionResult = await runRoleAssistantCaseLifecycle(roleKey, roleCase, authContext, opts);
   const executionVerdict = lifecycleVerdictFromCaseExecution(executionResult, verdict);