@aifabrix/builder 2.52.1 → 2.53.1

package/lib/channels/microsoft-copilot-package.js

@@ -18,7 +18,10 @@ const { applyMicrosoftCopilotDisplayLimits } = require('./microsoft-copilot-limi
 const {
   assertCopilotPackageOauthPluginVaultReference
 } = require('./microsoft-copilot-entra-sso');
-const { renderCopilotChannelTemplate } = require('./microsoft-copilot-entra-sso-form');
+const {
+  renderCopilotChannelTemplate,
+  applyWebApplicationInfoFields
+} = require('./microsoft-copilot-entra-sso-form');
 
 /**
  * @param {string} outputPath
@@ -73,7 +76,8 @@ function renderCopilotTemplates(runtimeValues, renderTemplateFile, templatesDir)
     'ai-plugin.json': renderTemplateFile(
       path.join(templatesDir, 'ai-plugin.template.json.hbs'),
       runtimeValues
-    )
+    ),
+    'fi-fi.json': renderTemplateFile(path.join(templatesDir, 'fi-fi.template.json.hbs'), runtimeValues)
   };
   // INSTALL prose + Entra SSO form table live in templates (partial entraSsoRegistration).
   const installText = renderCopilotChannelTemplate('install.template.md.hbs', runtimeValues);
@@ -100,6 +104,7 @@ function buildCopilotZipBuffer(sourceFiles, icons) {
   zip.addFile('manifest.json', Buffer.from(sourceFiles['manifest.json'], 'utf8'));
   zip.addFile('declarativeAgent.json', Buffer.from(sourceFiles['declarativeAgent.json'], 'utf8'));
   zip.addFile('ai-plugin.json', Buffer.from(sourceFiles['ai-plugin.json'], 'utf8'));
+  zip.addFile('fi-fi.json', Buffer.from(sourceFiles['fi-fi.json'], 'utf8'));
   zip.addFile('color.png', icons.color);
   zip.addFile('outline.png', icons.outline);
   return zip.toBuffer();
@@ -130,8 +135,9 @@ function buildCopilotValidation(runtimeValues, paths, sourceFileNames) {
       roleAssistantResolution: 'dynamic-runtime'
     },
     requiresMicrosoftAdmin: [
-      'upload-package',
-      'tenant-approval',
+      'developer-portal-import',
+      'publish-to-org',
+      'teams-admin-approval',
       'assignment-and-consent',
       'first-copilot-invoke'
     ]
@@ -206,7 +212,14 @@ function buildCopilotSummaryPackage(runtimeValues, paths) {
   return {
     appId: runtimeValues.packageAppId,
     version: runtimeValues.packageVersion,
-    sourceFiles: ['manifest.json', 'declarativeAgent.json', 'ai-plugin.json', 'color.png', 'outline.png'],
+    sourceFiles: [
+      'manifest.json',
+      'declarativeAgent.json',
+      'ai-plugin.json',
+      'fi-fi.json',
+      'color.png',
+      'outline.png'
+    ],
     zipFileName: paths.zipFileName,
     installGuide: 'INSTALL.md',
     validationFile: path.relative(paths.rootDir, paths.validationPath)
@@ -232,6 +245,9 @@ function buildCopilotSummary(runtimeValues, paths, validation, artifactHash) {
     package: buildCopilotSummaryPackage(runtimeValues, paths),
     installReady: runtimeValues.installReady === true,
     blocker: runtimeValues.discoveryBlocker || null,
+    packageReady: runtimeValues.packageReady !== false && runtimeValues.installReady === true,
+    packageBlocker: runtimeValues.packageBlocker || runtimeValues.discoveryBlocker || null,
+    microsoftPublicationPending: runtimeValues.microsoftPublicationPending !== false,
     links: {
       readme: paths.installPath,
       zip: paths.zipPath,
@@ -267,6 +283,7 @@ function writeCopilotArtifacts(params) {
     'utf8'
   );
   fs.writeFileSync(path.join(paths.sourceDir, 'ai-plugin.json'), sourceFiles['ai-plugin.json'], 'utf8');
+  fs.writeFileSync(path.join(paths.sourceDir, 'fi-fi.json'), sourceFiles['fi-fi.json'], 'utf8');
   fs.writeFileSync(path.join(paths.sourceDir, 'color.png'), icons.color);
   fs.writeFileSync(path.join(paths.sourceDir, 'outline.png'), icons.outline);
   fs.writeFileSync(paths.zipPath, zipBuffer);
@@ -301,6 +318,7 @@ function buildCopilotPackagePayload(params, runtimeValues, paths, icons) {
     sourceFiles['manifest.json'],
     sourceFiles['declarativeAgent.json'],
     sourceFiles['ai-plugin.json'],
+    sourceFiles['fi-fi.json'],
     installText,
     validationText,
     zipBuffer
@@ -312,19 +330,43 @@ function buildCopilotPackagePayload(params, runtimeValues, paths, icons) {
 }
 
 /**
- * @param {Object} params
- * @param {Object} params.runtimeValues
- * @param {string} params.templatesDir
- * @param {string} params.outputPath
- * @param {boolean} [params.dryRun]
- * @param {(content: string) => void} params.assertNoSecretsInArtifact
- * @param {(templatePath: string, context: Object) => string} params.renderTemplateFile
- * @returns {{ outputPath: string, artifactHash: string, content: string, installPath: string }}
+ * Read prior webApplicationInfo from an existing source manifest (preserve on regenerate).
+ * @param {string} sourceDir
+ * @returns {{ id: string, resource: string }|null}
  */
+function readPriorWebApplicationInfo(sourceDir) {
+  const manifestPath = path.join(sourceDir, 'manifest.json');
+  if (!fs.existsSync(manifestPath)) {
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+    const info = parsed && parsed.webApplicationInfo;
+    if (
+      info &&
+      typeof info.id === 'string' &&
+      info.id.trim() &&
+      typeof info.resource === 'string' &&
+      info.resource.trim()
+    ) {
+      return { id: info.id.trim(), resource: info.resource.trim() };
+    }
+  } catch {
+    return null;
+  }
+  return null;
+}
+
 function generateMicrosoftCopilotPackage(params) {
   const runtimeValues = applyMicrosoftCopilotDisplayLimits({ ...(params.runtimeValues || {}) });
   assertCopilotPackageOauthPluginVaultReference(runtimeValues);
   const paths = buildCopilotOutputPaths(params.outputPath, runtimeValues);
+  const prior = readPriorWebApplicationInfo(paths.sourceDir);
+  applyWebApplicationInfoFields(runtimeValues, {
+    webApplicationInfoId: runtimeValues.webApplicationInfoId,
+    webApplicationInfoResource: runtimeValues.webApplicationInfoResource,
+    priorWebApplicationInfo: prior
+  });
   const icons = resolvePackageIcons(runtimeValues);
   const payload = buildCopilotPackagePayload(params, runtimeValues, paths, icons);
   if (!params.dryRun) {
@@ -346,7 +388,10 @@ function generateMicrosoftCopilotPackage(params) {
     zipPath: paths.zipPath,
     links: payload.summary.links,
     installReady: payload.summary.installReady === true,
-    blocker: payload.summary.blocker || null
+    blocker: payload.summary.blocker || null,
+    packageReady: payload.summary.packageReady === true,
+    packageBlocker: payload.summary.packageBlocker || null,
+    microsoftPublicationPending: payload.summary.microsoftPublicationPending !== false
   };
 }
 

package/lib/channels/microsoft-copilot-validate.js

@@ -123,21 +123,17 @@ function validateAiPlugin(plugin, errors) {
 }
 
 /**
- * @param {Object} plugin
+ * @param {Object} runtime
  * @param {string[]} errors
  */
-function validateAiPluginRuntime(plugin, errors) {
-  const runtime = Array.isArray(plugin.runtimes) ? plugin.runtimes[0] : null;
-  if (!runtime || runtime.type !== 'RemoteMCPServer') {
-    errors.push('ai-plugin.runtimes[0].type must be RemoteMCPServer');
-    return;
-  }
-  if (!ALLOWED_AUTH_TYPES.has(runtime.auth?.type)) {
+function validateAiPluginAuth(runtime, errors) {
+  const authType = runtime.auth?.type;
+  if (!ALLOWED_AUTH_TYPES.has(authType)) {
     errors.push(
       `ai-plugin.runtimes[0].auth.type must be one of ${[...ALLOWED_AUTH_TYPES].join(', ')}`
     );
   }
-  if (runtime.auth?.type === 'OAuthPluginVault') {
+  if (authType === 'OAuthPluginVault') {
     const ref = runtime.auth.reference_id;
     if (typeof ref !== 'string' || !ref.trim()) {
       errors.push(
@@ -146,17 +142,51 @@ function validateAiPluginRuntime(plugin, errors) {
       );
     }
   }
-  if (runtime.auth?.type === 'None') {
+  if (authType === 'None') {
     errors.push(
       'ai-plugin.runtimes[0].auth.type None is not allowed; use OAuthPluginVault (Microsoft token / Entra)'
     );
   }
+}
+
+/**
+ * @param {Object} plugin
+ * @param {Object} runtime
+ * @param {string[]} errors
+ */
+function validateAiPluginDiscovery(plugin, runtime, errors) {
   const desc = runtime.spec?.mcp_tool_description;
   if (desc && (desc.mode || desc.layerBToolNames)) {
     errors.push(
       'ai-plugin mcp_tool_description must not use mode/layerBToolNames; omit for dynamic discovery or use tools/file'
     );
   }
+  if (!Array.isArray(plugin.functions) || plugin.functions.length !== 0) {
+    errors.push(
+      'ai-plugin.functions must be [] for Microsoft dynamic MCP tool discovery ' +
+        '(see run_for_functions ["*"])'
+    );
+  }
+  const runFor = runtime.run_for_functions;
+  if (!Array.isArray(runFor) || runFor.length !== 1 || runFor[0] !== '*') {
+    errors.push(
+      'ai-plugin.runtimes[0].run_for_functions must be ["*"] for dynamic MCP tool discovery'
+    );
+  }
+}
+
+/**
+ * @param {Object} plugin
+ * @param {string[]} errors
+ */
+function validateAiPluginRuntime(plugin, errors) {
+  const runtime = Array.isArray(plugin.runtimes) ? plugin.runtimes[0] : null;
+  if (!runtime || runtime.type !== 'RemoteMCPServer') {
+    errors.push('ai-plugin.runtimes[0].type must be RemoteMCPServer');
+    return;
+  }
+  validateAiPluginAuth(runtime, errors);
+  validateAiPluginDiscovery(plugin, runtime, errors);
 }
 
 /**

package/lib/cli/attach-default-help-examples.js

@@ -0,0 +1,102 @@
+/**
+ * Attach minimal product-neutral Examples: blocks to commands that lack them.
+ * Runs after setupCommands so intentional addHelpText Examples are preserved.
+ *
+ * @fileoverview Default CLI help Examples for check:cli-help gate
+ */
+
+'use strict';
+
+const EXAMPLE_HEADER_RE = /Examples:/m;
+const EXAMPLE_LINE_RE = /\$ aifabrix |\$ af /;
+
+/**
+ * @param {import('commander').Command} cmd
+ * @returns {string}
+ */
+function captureHelpOutput(cmd) {
+  if (!cmd || typeof cmd.outputHelp !== 'function') {
+    return '';
+  }
+  let buf = '';
+  cmd.outputHelp({
+    write: (chunk) => {
+      buf += String(chunk);
+    }
+  });
+  return buf;
+}
+
+/**
+ * @param {string} text
+ * @returns {boolean}
+ */
+function hasValidExamples(text) {
+  return EXAMPLE_HEADER_RE.test(text) && EXAMPLE_LINE_RE.test(text);
+}
+
+/**
+ * @param {string} pathStr
+ * @returns {string}
+ */
+function defaultExamplesBlock(pathStr) {
+  return `
+Examples:
+  $ aifabrix ${pathStr}
+  $ aifabrix ${pathStr} -h
+`;
+}
+
+/**
+ * @param {import('commander').Command} cmd
+ * @param {string[]} parts
+ * @param {Array<{ cmd: import('commander').Command, path: string }>} out
+ */
+function collectCommands(cmd, parts, out) {
+  // Tests sometimes pass mock nodes without Commander methods — skip those.
+  if (!cmd || typeof cmd.name !== 'function') {
+    return;
+  }
+  const name = cmd.name();
+  if (name === 'help') {
+    return;
+  }
+  const next = name && name !== 'aifabrix' ? parts.concat(name) : parts;
+  const subs = Array.isArray(cmd.commands) ? cmd.commands : [];
+  if (next.length > 0) {
+    out.push({ cmd, path: next.join(' ') });
+  }
+  for (const child of subs) {
+    collectCommands(child, next, out);
+  }
+}
+
+/**
+ * Ensure every leaf and parent has Examples with $ aifabrix / $ af.
+ * @param {import('commander').Command} program
+ * @returns {number} count of commands that received a default Examples block
+ */
+function attachDefaultHelpExamples(program) {
+  const entries = [];
+  collectCommands(program, [], entries);
+  let attached = 0;
+  for (const { cmd, path: pathStr } of entries) {
+    if (typeof cmd.addHelpText !== 'function') {
+      continue;
+    }
+    const text = captureHelpOutput(cmd);
+    if (hasValidExamples(text)) {
+      continue;
+    }
+    cmd.addHelpText('after', defaultExamplesBlock(pathStr));
+    attached += 1;
+  }
+  return attached;
+}
+
+module.exports = {
+  attachDefaultHelpExamples,
+  hasValidExamples,
+  captureHelpOutput,
+  defaultExamplesBlock
+};

package/lib/cli/index.js

@@ -100,6 +100,8 @@ function setupCommands(program) {
   setupCoreCliCommands(program);
   setupExtendedCliCommands(program);
   setupDevAndPlatformCommands(program);
+  const { attachDefaultHelpExamples } = require('./attach-default-help-examples');
+  attachDefaultHelpExamples(program);
 }
 
 module.exports = {

package/lib/cli/setup-credential-deployment.js

@@ -18,8 +18,10 @@ const { runDeploymentList } = require('../commands/deployment-list');
 const CREDENTIAL_HELP_AFTER = `
 Subcommands:
   env <systemKey>   Prompt for KV_* values → integration/<key>/.env
-  push <systemKey>  Upload secrets from .env to Dataplane
+  push <systemKey>  Upload secrets from an env file to Dataplane (--file recommended)
   list               List credentials (pagination: --page-size)
+
+Secrets: pass paths only (e.g. --file ./path/to/.env). Never put secret values on the command line.
 `;
 
 const DEPLOYMENT_HELP_AFTER = `
@@ -42,10 +44,11 @@ function setupCredentialEnvAndPush(credential) {
     });
   credential
     .command('push <systemKey>')
-    .description('Push KV_* secrets from .env to Dataplane')
-    .action(async(systemKey, _options) => {
+    .description('Push KV_* secrets from an env file to Dataplane (file path only — no secret values on argv)')
+    .option('--file <path>', 'Env file with KV_* values (must exist; never put secret values on argv)')
+    .action(async(systemKey, options) => {
       try {
-        await runCredentialPush(systemKey);
+        await runCredentialPush(systemKey, { file: options.file });
       } catch (error) {
         logger.error(chalk.red(`Error: ${error.message}`));
         handleCommandError(error, 'credential push');
@@ -53,7 +56,6 @@ function setupCredentialEnvAndPush(credential) {
       }
     });
 }
-
 /**
  * Sets up credential and deployment list commands
  * @param {Command} program - Commander program instance

package/lib/cli/setup-utility-validate.js

@@ -228,6 +228,7 @@ function setupValidateDiffCommands(program) {
   setupValidateCommand(program);
   setupValidateJsonCommand(program);
   setupDiffCommand(program);
+  require('../commands/package-score').setupPackageScoreCommand(program);
 }
 
 module.exports = {

package/lib/commands/credential-push.js

@@ -51,8 +51,10 @@ async function buildPayload(systemKey) {
  * Runs credential push: push KV_* from .env to dataplane.
  * @async
  * @param {string} systemKey - External system key
+ * @param {Object} [options]
+ * @param {string} [options.file] - Explicit env file path (required to exist when set)
  * @returns {Promise<{ pushed: number }>} Count of secrets pushed
- * @throws {Error} If auth or push fails
+ * @throws {Error} If auth or push fails, or --file path is missing
  */
 function logPushResult(pushResult) {
   if (pushResult.pushed > 0) {
@@ -66,10 +68,35 @@ function logPushResult(pushResult) {
   if (pushResult.warning) logger.log(chalk.yellow(`Warning: ${pushResult.warning}`));
 }
 
-async function runCredentialPush(systemKey) {
+/**
+ * Resolve env file path for credential push.
+ * @param {string} systemKey
+ * @param {Object} [options]
+ * @returns {string}
+ */
+function resolveCredentialEnvFilePath(systemKey, options = {}) {
+  const fileOpt =
+    options.file !== undefined && options.file !== null ? String(options.file).trim() : '';
+  if (fileOpt) {
+    const resolved = path.resolve(fileOpt);
+    const fsReal = require('../internal/fs-real-sync');
+    let isFile = false;
+    try {
+      isFile = fsReal.existsSync(resolved) && fsReal.statSync(resolved).isFile();
+    } catch (_err) {
+      isFile = false;
+    }
+    if (!isFile) {
+      throw new Error(`Credential env file not found: ${resolved}`);
+    }
+    return resolved;
+  }
+  return path.join(getIntegrationPath(systemKey), '.env');
+}
+
+async function runCredentialPush(systemKey, options = {}) {
   validateSystemKeyFormat(systemKey);
-  const appPath = getIntegrationPath(systemKey);
-  const envFilePath = path.join(appPath, '.env');
+  const envFilePath = resolveCredentialEnvFilePath(systemKey, options);
 
   const { resolveEnvironment } = require('../core/config');
   const environment = await resolveEnvironment();
@@ -99,4 +126,9 @@ async function runCredentialPush(systemKey) {
   return { pushed: pushResult.pushed || 0 };
 }
 
-module.exports = { runCredentialPush, validateSystemKeyFormat, buildPayload };
+module.exports = {
+  runCredentialPush,
+  validateSystemKeyFormat,
+  buildPayload,
+  resolveCredentialEnvFilePath
+};

package/lib/commands/package-score.js

@@ -0,0 +1,72 @@
+/**
+ * CLI: score candidate integration package vs a reference package directory.
+ *
+ * @fileoverview package-score command — score-only parity; reference is never generation input
+ */
+
+'use strict';
+
+const path = require('path');
+const chalk = require('chalk');
+const logger = require('../utils/logger');
+const { scorePackageParity } = require('../lab/package-parity-score');
+
+/**
+ * @param {Object} options
+ * @param {string} options.reference
+ * @param {string} options.candidate
+ * @param {boolean} [options.json]
+ * @returns {Promise<number>} process exit code
+ */
+async function runPackageScoreCommand(options = {}) {
+  const reference = String(options.reference || '').trim();
+  const candidate = String(options.candidate || '').trim();
+  if (!reference || !candidate) {
+    throw new Error('Both --reference <dir> and --candidate <dir> are required.');
+  }
+  const report = scorePackageParity(path.resolve(reference), path.resolve(candidate));
+  if (options.json === true) {
+    logger.log(JSON.stringify(report, null, 2));
+  } else {
+    logger.log(chalk.bold(`Package parity score: ${report.score}/${report.maxScore}`));
+    logger.log(chalk.gray(report.summary));
+    logger.log(chalk.gray(`Reference (score-only): ${report.referenceDir}`));
+    logger.log(chalk.gray(`Candidate: ${report.candidateDir}`));
+    for (const row of report.facets) {
+      const mark = row.ok ? chalk.green('✔') : chalk.red('✖');
+      logger.log(`  ${mark} ${row.id}: ${row.detail}`);
+    }
+    if (report.goldIsScoreOnly) {
+      logger.log(chalk.yellow('Note: reference package is for scoring only — never use it as generation input.'));
+    }
+  }
+  return report.identical ? 0 : 1;
+}
+
+/**
+ * @param {import('commander').Command} program
+ */
+function setupPackageScoreCommand(program) {
+  program
+    .command('package-score')
+    .description(
+      'Score a candidate integration package directory against a reference package (score-only; not generation)'
+    )
+    .option('--reference <dir>', 'Reference integration package directory (score baseline only)')
+    .option('--candidate <dir>', 'Candidate integration package directory')
+    .option('--json', 'Emit structured JSON report', false)
+    .action(async(options) => {
+      try {
+        const code = await runPackageScoreCommand(options);
+        process.exitCode = code;
+      } catch (error) {
+        logger.error(chalk.red(`Error: ${error.message}`));
+        process.exitCode = 1;
+      }
+    });
+}
+
+module.exports = {
+  setupPackageScoreCommand,
+  runPackageScoreCommand
+};

package/lib/commands/role-assistant.js

@@ -50,6 +50,29 @@ const {
   roleAssistantSystemKey
 } = require('../utils/role-assistant-paths');
 
+function roleAssistantGroupHelpAfter() {
+  return `
+Subcommands:
+  test <roleKey>   Run lifecycle checks, optional YAML cases/suites, and print a portal deep link
+
+Package workspace (top-level commands — same digital-worker package):
+  download / validate / upload / deploy <roleKey>   Manage role-assistant/ra-<roleKey>/
+
+Examples:
+  $ aifabrix role-assistant test customer-support-bot
+  $ aifabrix role-assistant test customer-support-bot --suite 001
+  $ aifabrix role-assistant test customer-support-bot --list-cases
+  $ aifabrix role-assistant test customer-support-bot --env tst --json
+  $ aifabrix upload customer-support-bot --env dev
+  $ aifabrix test ra-customer-support-bot
+
+Notes:
+  - Local packages live under role-assistant/ra-<roleKey>/ (bare <roleKey> in CLI args).
+  - test uses the public/running worker by default; pass --publish (or upload) to refresh from local files.
+  - See: aifabrix role-assistant test -h
+`;
+}
+
 function roleAssistantHelpAfter() {
   return `
 Examples:
@@ -60,14 +83,16 @@ Examples:
   $ aifabrix role-assistant test customer-support-bot --suite 001
   $ aifabrix role-assistant test customer-support-bot --list-cases
   $ aifabrix role-assistant test customer-support-bot --suite 001 --fail-fast --json
+  $ aifabrix test ra-customer-support-bot
 
 Notes:
+  - <roleKey> is bare (e.g. customer-support-bot); package folder is role-assistant/ra-<roleKey>/.
   - Uses the public/running Role Assistant on the dataplane by default (does not publish local datasources).
   - Use \`aifabrix upload <roleKey> --env …\` (or \`--publish\`) when you intentionally refresh the package.
   - Runs lifecycle checks, then prints a portal deep link for full step-by-step status.
   - Case files with input.message/input.content execute Work Hub plan→accept (or work.start when executionPath: intent).
   - answers[] and approvals[] are matched to runtime wait payloads (questionKey/requestKey/waitReason).
-  - --suite runs all YAML under tests/role-assistant/ra-<roleKey>/<suite>/ (or --cases-root).
+  - --suite runs YAML under role-assistant/ra-<roleKey>/tests/<suite>/ (preferred), or tests/ra-<roleKey>/<roleKey>/<suite>/, or legacy tests/role-assistant/ra-<roleKey>/<suite>/ (override with --cases-root).
   - Use the portal URL for detailed human review while automation reads CLI/JSON output.
 `;
 }
@@ -163,13 +188,19 @@ function listRoleAssistantCases(roleKey, opts) {
 }
 
 async function resolveSuiteCaseResults(systemKey, opts, result, verdict, portalUrl) {
-  const root = resolveCasesRoot(systemKey, { casesRoot: opts.casesRoot || undefined });
+  const cwd = process.cwd();
+  const root = resolveCasesRoot(systemKey, { casesRoot: opts.casesRoot || undefined, cwd });
   const discovered = discoverSuiteCaseFiles(root, { suite: opts.suite || undefined });
   const selected = filterDiscoveredCases(discovered, opts.case);
   if (selected.length === 0) {
+    const { listCasesRootCandidates } = require('../role-assistant/test-suite');
+    const tried = opts.casesRoot
+      ? [root]
+      : listCasesRootCandidates(systemKey, cwd);
     throw new Error(
       `No role-assistant cases found under ${root}` +
-        (opts.suite ? ` suite=${opts.suite}` : '')
+        (opts.suite ? ` suite=${opts.suite}` : '') +
+        `. Looked in: ${tried.join(', ')}`
     );
   }
   const outcomes = [];
@@ -269,21 +300,26 @@ async function roleAssistantTestHandler(roleKey, options, cmd) {
 function setupRoleAssistantCommands(program) {
   const roleAssistant = program
     .command('role-assistant')
-    .description('Role Assistant lifecycle and portal workflows');
+    .description(
+      'Role Assistant packages: lifecycle checks, YAML cases/suites, and portal deep links'
+    )
+    .addHelpText('after', roleAssistantGroupHelpAfter());
 
   roleAssistant
     .command('test <roleKey>')
-    .description('Run role-assistant lifecycle checks and print portal deep link')
+    .description(
+      'Lifecycle checks + optional cases/suites; prints portal deep link (bare <roleKey>)'
+    )
     .option('-e, --env <env>', 'Environment: dev, tst, or pro', 'dev')
     .option('--case <caseIdOrPath>', 'Run and evaluate one role-assistant test case')
     .option('--tests-dir <dir>', 'Override role-assistant test case directory')
     .option(
       '--suite <suiteId>',
-      'Run all YAML cases under tests/role-assistant/ra-<roleKey>/<suiteId>/'
+      'Run all YAML under role-assistant/ra-<roleKey>/tests/<suiteId>/ (or tests/ra-<roleKey>/<roleKey>/<suiteId>/)'
     )
     .option(
       '--cases-root <dir>',
-      'Override cases root (default: tests/role-assistant/ra-<roleKey>/)'
+      'Override cases root (default: package tests/, then tests/ra-<roleKey>/<roleKey>/)'
     )
     .option('--list-cases', 'List discoverable case files and exit')
     .option('--fail-fast', 'Stop suite run after the first failing case')
@@ -326,5 +362,7 @@ module.exports = {
   resolveRoleAssistantCaseResult,
   resolveSuiteCaseResults,
   listRoleAssistantCases,
-  formatStepsRunSummary
+  formatStepsRunSummary,
+  roleAssistantGroupHelpAfter,
+  roleAssistantHelpAfter
 };

package/lib/deployment/deployer-poll-run.js

@@ -31,7 +31,7 @@ const { createDeployPollHandlers } = require('./deploy-poll-ui');
  */
 async function pollDeploymentStatus(deploymentId, controllerUrl, envKey, authConfig, options = {}) {
   const interval = options.interval || 5000;
-  const maxAttempts = options.maxAttempts || 60;
+  const maxAttempts = options.maxAttempts || 300;
 
   const validatedEnvKey = validateEnvironmentKey(envKey);
   const pipelineAuthConfig = convertToPipelineAuthConfig(authConfig);
@@ -74,7 +74,7 @@ async function pollDeployment(result, url, validatedEnvKey, authConfig, options)
   }
 
   const resolvedInterval = await resolvePollIntervalFromController(url, options.pollInterval);
-  const maxAttempts = options.pollMaxAttempts || 60;
+  const maxAttempts = options.pollMaxAttempts || 300;
   const ownsPollUi = !options.pollUi;
   const pollUi =
     options.pollUi ||

package/lib/deployment/deployer.js

@@ -387,7 +387,7 @@ async function deployToController(manifest, controllerUrl, envKey, authConfig, o
 
   const usePollUi = options.poll !== false && options.silentPoll !== true;
   const pollUi = usePollUi
-    ? createDeployPollHandlers(options.pollMaxAttempts || 60, { silent: false })
+    ? createDeployPollHandlers(options.pollMaxAttempts || 300, { silent: false })
     : null;
   const deployOpts = pollUi ? { ...options, pollUi } : options;
 

package/lib/deployment/environment.js

@@ -253,7 +253,7 @@ async function pollEnvironmentStatus(deploymentId, controllerUrl, envKey, authCo
   const validatedUrl = validateControllerUrl(controllerUrl);
   const validatedEnvKey = validateEnvironmentKey(envKey);
   const pollInterval = options.pollInterval || 5000;
-  const maxAttempts = options.maxAttempts || 60;
+  const maxAttempts = options.maxAttempts || 300;
   const apiAuthConfig = { type: 'bearer', token: authConfig.token };
 
   logger.log(chalk.blue(`⏳ Polling environment status (${pollInterval}ms intervals)...`));
@@ -398,7 +398,7 @@ async function pollDeploymentStatusIfEnabled(result, validatedControllerUrl, env
       authConfig,
       {
         pollInterval,
-        maxAttempts: options.pollMaxAttempts || 60
+        maxAttempts: options.pollMaxAttempts || 300
       }
     );
     result.status = pollResult.status;