@aifabrix/builder 2.45.0 → 2.46.0

package/lib/cli/setup-app.test-commands.js

@@ -8,11 +8,14 @@ const chalk = require('chalk');
 const logger = require('../utils/logger');
 const { handleCommandError } = require('../utils/cli-utils');
 const { cliOptsSkipCertSync } = require('../certification/cli-cert-sync-skip');
-const { TEST_HELP_AFTER, TEST_E2E_HELP_AFTER } = require('./setup-app.help');
+const {
+  TEST_HELP_AFTER,
+  TEST_E2E_HELP_AFTER
+} = require('./setup-app.help');
 
 function setupTestCommand(program) {
-  program.command('test <app>')
-    .description('Tests: builder in container; external = local validation')
+  program.command('test <appKey|systemKey>')
+    .description('Tests: builder appKey in container; external systemKey = local validation')
     .option('-e, --env <env>', 'For builder app: dev (running container) or tst (ephemeral)', 'dev')
     .option('-v, --verbose', 'Verbose output')
     .option('-d, --debug', 'Write debug log to integration/<systemKey>/logs/ (external only)')
@@ -84,14 +87,16 @@ function firstIssuanceFailureHintFromE2eResults(results) {
  * @param {Object} options
  * @returns {Promise<void>}
  */
-async function runExternalIntegrationE2EAndCertSync(appName, options) {
+async function runExternalIntegrationE2EAndCertSync(appName, options, cmd) {
+  const { cliOptsSkipSync } = require('../utils/cli-sync-options');
   const { runTestE2EForExternalSystem } = require('../commands/test-e2e-external');
+  const noSync = cliOptsSkipSync(options, cmd);
   const { success, results } = await runTestE2EForExternalSystem(appName, {
     env: options.env,
     debug: options.debug,
     verbose: options.verbose,
     async: options.async !== false,
-    noSync: options.noSync === true
+    noSync
   });
   const { displayIntegrationTestResults } = require('../utils/external-system-display');
   const datasourceResults = results.map(r => ({
@@ -118,17 +123,19 @@ async function runExternalIntegrationE2EAndCertSync(appName, options) {
   await trySyncCertificationFromDataplaneForExternalApp(appName, 'test-e2e', { issuanceFailureHint });
 }
 
-async function runTestE2ECommand(appName, options) {
+async function runTestE2ECommand(appName, options, cmd) {
+  const { cliOptsSkipSync } = require('../utils/cli-sync-options');
+  const noSync = cliOptsSkipSync(options, cmd);
   const pathsUtil = require('../utils/paths');
   const appType = await pathsUtil.detectAppType(appName).catch(() => null);
-  if (options.noSync === true && appType && appType.baseDir === 'builder') {
+  if (noSync && appType && appType.baseDir === 'builder') {
     throw new Error(
       'Option --no-sync applies only to external integration E2E (integration/<systemKey>/). ' +
         'Remove --no-sync for builder app E2E.'
     );
   }
   if (appType && appType.baseDir === 'integration') {
-    await runExternalIntegrationE2EAndCertSync(appName, options);
+    await runExternalIntegrationE2EAndCertSync(appName, options, cmd);
     return;
   }
   const { runAppTestE2e } = require('../commands/app-test');
@@ -136,8 +143,8 @@ async function runTestE2ECommand(appName, options) {
 }
 
 function setupInstallCommand(program) {
-  program.command('install <app>')
-    .description('Install deps in container (builder apps only)')
+  program.command('install <appKey>')
+    .description('Install deps in container (builder appKey only)')
     .option('--env <env>', 'dev (running container) or tst (ephemeral with .env)', 'dev')
     .action(async(appName, options) => {
       try {
@@ -145,7 +152,7 @@ function setupInstallCommand(program) {
         const appType = await pathsUtil.detectAppType(appName).catch(() => null);
         if (appType && appType.baseDir === 'integration') {
           logger.log(
-            chalk.gray('Install is for builder applications only. Use aifabrix shell <app> to run commands in external setups.')
+            chalk.gray('Install is for builder appKey only. Use aifabrix shell <appKey> for builder apps or External Systems commands for integrations.')
           );
           return;
         }
@@ -159,19 +166,19 @@ function setupInstallCommand(program) {
 }
 
 function setupTestE2eCommand(program) {
-  program.command('test-e2e <app>')
-    .description('E2E: builder in container; external = all datasources via dataplane')
+  program.command('test-e2e <appKey|systemKey>')
+    .description('E2E: builder appKey in container; external systemKey = all datasources via dataplane')
     .option('-e, --env <env>', 'Environment: dev, tst, or pro (builder: dev/tst for container)', 'dev')
     .option('-v, --verbose', 'Show detailed step output and poll progress')
     .option('-d, --debug', 'Include debug output and write log to integration/<systemKey>/logs/')
-    .option(
-      '--sync',
-      '(Deprecated; no-op.) Local integration files are published before E2E by default; use --no-sync to skip.'
-    )
     .option(
       '--no-sync',
       'Skip publishing local integration files; E2E uses the system config already on the dataplane (external integration only)'
     )
+    .option(
+      '--force',
+      'With default sync, pass force to upload (bypass active-datasource schema replacement guards; same as aifabrix upload --force)'
+    )
     .option('--warnings-as-errors', 'Treat aggregate warn as failure (exit 1)')
     .option('--require-cert', 'Require certification passed on every datasource (exit 2 if not)')
     .option(
@@ -188,7 +195,7 @@ function setupTestE2eCommand(program) {
           env: envExplicit ? options.env : undefined,
           async: true // system-level command surface omits --no-async; always poll for completeness
         };
-        await runTestE2ECommand(appName, externalOpts);
+        await runTestE2ECommand(appName, externalOpts, cmd);
       } catch (error) {
         handleCommandError(error, 'test-e2e');
         process.exit(1);
@@ -197,15 +204,15 @@ function setupTestE2eCommand(program) {
 }
 
 function setupLintCommand(program) {
-  program.command('lint <app>')
-    .description('Lint in container (builder apps only)')
+  program.command('lint <appKey>')
+    .description('Lint in container (builder appKey only)')
     .option('--env <env>', 'dev (running container) or tst (ephemeral with .env)', 'dev')
     .action(async(appName, options) => {
       try {
         const pathsUtil = require('../utils/paths');
         const appType = await pathsUtil.detectAppType(appName).catch(() => null);
         if (appType && appType.baseDir === 'integration') {
-          logger.log(chalk.gray('lint is for builder applications only. Use aifabrix shell <app> then make lint or pnpm lint.'));
+          logger.log(chalk.gray('lint is for builder appKey only. Use aifabrix shell <appKey> then make lint or pnpm lint.'));
           return;
         }
         const { runAppLint } = require('../commands/app-test');

package/lib/cli/setup-auth.js

@@ -28,7 +28,53 @@ For details on omitting the URL: aifabrix auth set-controller -h
 Aliases:
   aifabrix auth set-controller [url]
   aifabrix auth set-environment <env>
-Subcommand: auth status [--validate] for CI/scripts.
+Subcommand: auth status [--validate] for CI/scripts (exit codes 0/1/3).
+`;
+
+const LOGOUT_HELP_AFTER = `
+Examples:
+  $ aifabrix logout
+  $ aifabrix logout -c http://localhost:3600
+  $ aifabrix logout -e dev
+  $ aifabrix logout -e dev -a hubspot-e2e
+
+Notes:
+  - With no flags: clears all device tokens and all client tokens in config.yaml.
+  - Device tokens are keyed by controller URL (-c).
+  - Client tokens are per environment and app (-e and optional -a).
+  - Run aifabrix auth status to list stored app tokens and copy-paste logout commands.
+`;
+
+const AUTH_STATUS_HELP_AFTER = `
+Examples:
+  $ aifabrix auth status
+  $ aifabrix auth status --validate
+
+Client token refresh:
+  - Expired application tokens are refreshed automatically when client id/secret
+    exist in ~/.aifabrix/secrets.local.yaml (pattern <app>-client-idKeyVault) or env
+    (MISO_CLIENTID / MISO_CLIENTSECRET).
+  - Lists each stored app token with aifabrix logout -e <env> -a <app> to clear it.
+
+Exit codes (--validate only):
+  0  Authenticated and Builder CLI meets dataplane minimum (or no minimum configured)
+  1  Not authenticated — run aifabrix login
+  3  Authenticated but Builder CLI is older than dataplane minimum
+
+Config cache (written on status when dataplane is reachable):
+  ~/.aifabrix/config.yaml → device.<controllerUrl>:
+    dataplane-version         — last dataplane version from health
+    dataplane-min-cli-version — minimum Builder CLI required (when enforced)
+
+What is blocked when CLI is too old:
+  Dataplane commands (upload, wizard, datasource upload, deploy to dataplane, …)
+What still works:
+  Local validate, aifabrix run, up-infra, file generation without dataplane API calls
+
+Troubleshooting:
+  • "Upgrade required" but you upgraded — run auth status again to refresh cache
+  • No min version shown — dataplane MIN_BUILDER_CLI_VERSION not set (ops)
+  • CI exit 3 — pin @aifabrix/builder version in pipeline to ≥ dataplane-min-cli-version
 `;
 
 const AUTH_SET_CONTROLLER_HELP_AFTER = `
@@ -126,6 +172,10 @@ function setupLoginCommand(program) {
     .option('-e, --environment <env>', 'Environment key (updates root-level environment in config.yaml, e.g., miso, dev, tst, pro)')
     .option('--online', 'Request online-only token (excludes offline_access scope, device flow only)')
     .option('--scope <scopes>', 'Custom OAuth2 scope string (device flow only, default: "openid profile email offline_access")')
+    .option(
+      '--skip-version-cache',
+      'Skip post-login dataplane version cache refresh (faster exit when controller/dataplane URLs are slow)'
+    )
     .action(async(options) => {
       try {
         await handleLogin(options);
@@ -142,6 +192,7 @@ function setupLogoutCommand(program) {
     .option('-c, --controller <url>', 'Clear device tokens for specific controller')
     .option('-e, --environment <env>', 'Clear client tokens for specific environment')
     .option('-a, --app <app>', 'Clear client tokens for specific app (requires --environment)')
+    .addHelpText('after', LOGOUT_HELP_AFTER)
     .action(async(options) => {
       try {
         await handleLogout(options);
@@ -168,7 +219,8 @@ function setupAuthSubcommands(program) {
 
   auth.command('status')
     .description('Show tokens/session for current controller and environment')
-    .option('--validate', 'Exit with code 1 when not authenticated (for scripted use, e.g. manual test setup)')
+    .addHelpText('after', AUTH_STATUS_HELP_AFTER)
+    .option('--validate', 'Exit 1 when not authenticated, 3 when Builder CLI < dataplane minimum, 0 otherwise (for CI/scripts)')
     .action(createAuthStatusAction());
 }
 
@@ -182,4 +234,4 @@ function setupAuthCommands(program) {
   setupAuthSubcommands(program);
 }
 
-module.exports = { setupAuthCommands };
+module.exports = { setupAuthCommands, AUTH_STATUS_HELP_AFTER };

package/lib/cli/setup-certification-commands.js

@@ -0,0 +1,147 @@
+/**
+ * @fileoverview Enterprise AI Certification CLI commands (plan 150.0).
+ */
+
+'use strict';
+
+const {
+  VERIFY_OPERATIONS_HELP_AFTER,
+  VERIFY_TRUST_HELP_AFTER,
+  VERIFY_GOVERNANCE_HELP_AFTER,
+  LIFECYCLE_HELP_AFTER
+} = require('./setup-certification.help');
+const { collectString } = require('../commands/governance');
+
+function setupVerifyOperationsCommand(program) {
+  const { verifyOperationsCommandHandler } = require('../commands/verify-operations-command-action');
+  program
+    .command('verify-operations <systemKey>')
+    .description('Operational readiness: validate, unit, integration, and E2E (system scope)')
+    .option('-e, --env <env>', 'Environment: dev, tst, or pro', 'dev')
+    .option('-v, --verbose', 'Readiness breakdown and verification step checklist')
+    .option('-d, --debug', 'Write debug logs under integration/<systemKey>/logs/')
+    .option('--no-sync', 'Skip publishing local integration files before dataplane steps')
+    .option(
+      '--force',
+      'With default sync, pass force to upload (same as aifabrix upload --force)'
+    )
+    .option('--continue', 'Continue after a failed step (still reports FAILED verdict)')
+    .option('--json', 'Machine-readable product envelope')
+    .addHelpText('after', VERIFY_OPERATIONS_HELP_AFTER)
+    .action((systemKey, options, cmd) => verifyOperationsCommandHandler(systemKey, options, cmd));
+}
+
+function setupVerifyTrustCommand(program) {
+  const { verifyTrustCommandHandler } = require('../commands/verify-trust-command-action');
+  program
+    .command('verify-trust <systemKey>')
+    .description('AI business context confidence for every datasource (semantic metadata trust)')
+    .option('-e, --env <env>', 'Environment: dev, tst, or pro', 'dev')
+    .option('-v, --verbose', 'Per-datasource breakdown')
+    .option('-d, --debug', 'Write debug log under integration/<systemKey>/logs/')
+    .option('--no-sync', 'Skip publishing local integration files before validate')
+    .option(
+      '--force',
+      'With default sync, pass force to upload (same as aifabrix upload --force)'
+    )
+    .option('--revalidate', 'Force new validation for each datasource')
+    .option('--timeout <ms>', 'HTTP timeout for validate/latest requests (ms)', '120000')
+    .option('--json', 'Machine-readable product envelope')
+    .addHelpText('after', VERIFY_TRUST_HELP_AFTER)
+    .action((systemKey, options, cmd) => verifyTrustCommandHandler(systemKey, options, cmd));
+}
+
+function setupVerifyGovernanceCommand(program) {
+  const { verifyGovernanceCommandHandler } = require('../commands/verify-governance-command-action');
+  program
+    .command('verify-governance <systemKey>')
+    .description(
+      'Generate integration validation packs, then verify governance (upload local YAML when present)'
+    )
+    .option('-e, --env <env>', 'Environment: dev, tst, or pro', 'dev')
+    .option('-v, --verbose', 'Per-datasource breakdown and pipeline detail')
+    .option('-d, --debug', 'Write debug logs under integration/<systemKey>/logs/')
+    .option('--no-sync', 'Skip publishing local integration files before dataplane steps')
+    .option(
+      '--force',
+      'With default sync, pass force to upload (same as aifabrix upload --force)'
+    )
+    .option(
+      '--certification-profile <profile>',
+      'Certification profile for generate (bronze, silver, gold, …)',
+      'bronze'
+    )
+    .option(
+      '--subject-user-id <id>',
+      'Subject user id for generated scenarios (repeatable)',
+      collectString,
+      []
+    )
+    .option(
+      '--subject-email <email>',
+      'Subject email for generated scenarios (repeatable)',
+      collectString,
+      []
+    )
+    .option(
+      '--max-samples-per-partition <n>',
+      'Max keys per mustInclude/mustExclude partition',
+      '25'
+    )
+    .option(
+      '--pack <path>',
+      'Authoring override: local YAML only (skips generate and local upload)'
+    )
+    .option('-a, --app <path>', 'Integration folder override (with --pack)')
+    .option('--scenario <id>', 'Scenario subset when using --pack (repeatable)', collectString, [])
+    .option('--json', 'Machine-readable product envelope')
+    .addHelpText('after', VERIFY_GOVERNANCE_HELP_AFTER)
+    .action((systemKey, options, cmd) => verifyGovernanceCommandHandler(systemKey, options, cmd));
+}
+
+function setupLifecycleCommand(program) {
+  const { lifecycleCommandHandler } = require('../commands/lifecycle-command-action');
+  program
+    .command('lifecycle <systemKey>')
+    .description('Enterprise AI certification report (default: read persisted results from dataplane)')
+    .option('-e, --env <env>', 'Environment: dev, tst, or pro', 'dev')
+    .option('-v, --verbose', 'Per-datasource breakdown in the report')
+    .option('-d, --debug', 'Write debug logs under integration/<systemKey>/logs/ when --run')
+    .option('--run', 'Run missing verify steps, then print certification report')
+    .option('--no-sync', 'With --run, skip publishing local integration files before verify')
+    .option(
+      '--force',
+      'With default sync on --run, pass force to upload (same as aifabrix upload --force)'
+    )
+    .option(
+      '--subject-user-id <id>',
+      'Subject user id for governance generate when --run (repeatable)',
+      collectString,
+      []
+    )
+    .option(
+      '--subject-email <email>',
+      'Subject email for governance generate when --run (repeatable)',
+      collectString,
+      []
+    )
+    .option(
+      '--certification-profile <profile>',
+      'Certification profile for governance generate on --run (bronze, silver, gold, …)',
+      'bronze'
+    )
+    .option('--json', 'Machine-readable certification envelope')
+    .addHelpText('after', LIFECYCLE_HELP_AFTER)
+    .action((systemKey, options, cmd) => lifecycleCommandHandler(systemKey, options, cmd));
+}
+
+function setupCertificationCommands(program) {
+  setupVerifyOperationsCommand(program);
+  setupVerifyTrustCommand(program);
+  setupVerifyGovernanceCommand(program);
+  setupLifecycleCommand(program);
+}
+
+module.exports = {
+  setupCertificationCommands
+};

package/lib/cli/setup-certification.help.js

@@ -0,0 +1,141 @@
+/**
+ * @fileoverview Help text for Enterprise AI Certification CLI commands (plan 150.0).
+ */
+
+'use strict';
+
+const VERIFY_OPERATIONS_HELP_AFTER = `
+Examples:
+  $ aifabrix verify-operations hubspot
+  $ aifabrix verify-operations hubspot -v
+  $ aifabrix verify-operations hubspot --no-sync
+
+Notes:
+  - Orchestrates validate → test → test-integration → test-e2e for the system.
+  - Default output shows Operational Readiness % and OPERATIONS VERIFIED/FAILED only.
+  - -v / --verbose adds readiness breakdown and verification step checklist at the end.
+  - -v does not enable upload sidecar logs or inner E2E poll spinners (use aifabrix upload -v for upload detail).
+  - Low-level commands (validate, test, test-integration, test-e2e) remain for debugging.
+  - Generate or upload integration validation packs: aifabrix governance generate|upload <systemKey>
+`;
+
+const VERIFY_TRUST_HELP_AFTER = `
+Examples:
+  $ aifabrix verify-trust hubspot
+  $ aifabrix verify-trust hubspot -v --revalidate
+  $ aifabrix verify-trust hubspot --no-sync --json
+
+Notes:
+  - For one datasource: aifabrix datasource verify-trust <datasourceKey>
+  - Does not call external vendor APIs (use verify-operations / test-e2e for connectivity).
+  - Local integration files are published before run unless --no-sync.
+`;
+
+const VERIFY_GOVERNANCE_HELP_AFTER = `
+Examples:
+  $ aifabrix verify-governance hubspot-e2e --subject-email us.sales@example.com
+  $ aifabrix verify-governance hubspot-e2e --subject-email a@x.com,b@y.com -v
+  $ aifabrix verify-governance hubspot-e2e --certification-profile gold --json
+
+Notes:
+  - All-in-one: publishes local integration (unless --no-sync), generates packs on the dataplane,
+    then runs governance verification (dataplane-first; no local YAML upload).
+  - Requires at least one --subject-user-id or --subject-email (repeatable or comma-separated).
+  - Prefer this over separate generate + verify when certifying an integration.
+  - --pack skips generate and runs a single local YAML override (authoring only).
+  - Granular steps: aifabrix governance generate|verify|upload|download <systemKey>
+`;
+
+const GOVERNANCE_GENERATE_HELP_AFTER = `
+Examples:
+  $ aifabrix governance generate hubspot-e2e --subject-email us.sales@example.com
+  $ aifabrix governance generate hubspot-e2e --subject-user-id user-a --subject-user-id user-b -v
+  $ aifabrix governance generate hubspot-e2e --certification-profile gold --no-sync
+
+Notes:
+  - Dataplane generates keys, coverage, and generationState; the CLI never authors partitions locally.
+  - Requires at least one --subject-user-id or --subject-email per datasource fan-out.
+  - Publishes local integration files before generate unless --no-sync.
+`;
+
+const GOVERNANCE_VERIFY_HELP_AFTER = `
+Examples:
+  $ aifabrix governance verify hubspot-e2e
+  $ aifabrix governance verify hubspot-e2e -v
+  $ aifabrix governance verify hubspot-e2e --pack scenarios/custom.yaml
+
+Notes:
+  - Default: runs persisted scenario packs from the dataplane (after governance generate).
+  - --pack is an authoring override only; product path uses DB packs per datasource.
+  - Does not call vendor APIs (use verify-operations for connectivity).
+  - All-in-one cert path: aifabrix verify-governance <systemKey> --subject-email <email>
+`;
+
+const GOVERNANCE_UPLOAD_HELP_AFTER = `
+Examples:
+  $ aifabrix governance upload hubspot-e2e
+  $ aifabrix governance upload hubspot-e2e --no-sync
+
+Notes:
+  - Expert path: pushes integration/<systemKey>/scenarios/*.yaml to the dataplane.
+  - Packs must satisfy the 424.0 schema (spec.coverage, metadata.generationState). Use governance generate
+    or verify-governance for dataplane-first packs.
+`;
+
+const GOVERNANCE_DOWNLOAD_HELP_AFTER = `
+Examples:
+  $ aifabrix governance download hubspot-e2e
+  $ aifabrix governance download hubspot-e2e --json
+
+Notes:
+  - Pulls active packs to integration/<systemKey>/scenarios/<datasourceKey>.yaml.
+  - Does not publish the integration (read-only against the dataplane).
+  - When no pack exists, lists datasources and suggests governance generate.
+`;
+
+const LIFECYCLE_HELP_AFTER = `
+Examples:
+  $ aifabrix lifecycle hubspot
+  $ aifabrix lifecycle hubspot -v
+  $ aifabrix lifecycle hubspot --run
+  $ aifabrix lifecycle hubspot --run --no-sync
+  $ aifabrix lifecycle hubspot-e2e --run --subject-email us.sales@example.com
+  $ aifabrix lifecycle hubspot-e2e --run --subject-email a@x.com,b@y.com -v
+
+Notes:
+  - Default: certification report only (GET persisted pillar results from dataplane).
+  - --run executes missing verify steps, then prints the report (publishes local files first unless --no-sync).
+  - With --run, --subject-email / --subject-user-id generate and verify governance packs (same as verify-governance).
+  - Repeat the flag or use comma-separated values: --subject-email a@x.com,b@y.com
+  - One-shot cert path: lifecycle <systemKey> --run --subject-email <email>
+  - Tier is never inflated — incomplete pillars show NOT VERIFIED and actionable recommendations.
+`;
+
+const GOVERNANCE_PARENT_HELP_AFTER = `
+Subcommands:
+  generate   Create versioned packs on the dataplane (dataplane-first)
+  verify     Run persisted packs (governance:evaluate)
+  upload     Push local scenarios/*.yaml (expert path)
+  download   Pull active packs to integration/<systemKey>/scenarios/
+
+All-in-one certification:
+  $ aifabrix verify-governance <systemKey> --subject-email <email>
+
+Per-command help:
+  $ aifabrix governance generate --help
+  $ aifabrix governance verify --help
+  $ aifabrix governance upload --help
+  $ aifabrix governance download --help
+`;
+
+module.exports = {
+  VERIFY_OPERATIONS_HELP_AFTER,
+  VERIFY_TRUST_HELP_AFTER,
+  VERIFY_GOVERNANCE_HELP_AFTER,
+  GOVERNANCE_GENERATE_HELP_AFTER,
+  GOVERNANCE_VERIFY_HELP_AFTER,
+  GOVERNANCE_UPLOAD_HELP_AFTER,
+  GOVERNANCE_DOWNLOAD_HELP_AFTER,
+  GOVERNANCE_PARENT_HELP_AFTER,
+  LIFECYCLE_HELP_AFTER
+};

package/lib/cli/setup-environment.js

@@ -26,10 +26,27 @@ function setupEnvironmentCommands(program) {
   const deployExamples = `
 Examples:
   $ aifabrix env deploy dev
-  $ aifabrix env deploy tst --preset m
-  $ aifabrix env deploy dev --config ./env-config.json --no-poll`;
+  $ aifabrix env deploy tst
+  $ aifabrix env deploy pro --preset m
+  $ aifabrix env deploy dev --preset xl
+  $ aifabrix env deploy dev --config ./env-config.json
+  $ aifabrix env deploy dev --no-poll
+
+Prerequisites: aifabrix login (device token; controller permission controller:deploy).
+Environment keys: miso, dev, tst, pro. Default size preset: s (use --preset s|m|l|xl).
+Run this before aifabrix deploy <app> — the environment must exist first.`;
 
   const ENV_GROUP_HELP_AFTER = `
+Examples:
+  $ aifabrix env deploy dev
+  $ aifabrix env deploy dev --preset m
+  $ aifabrix env deploy dev --help
+
+Typical workflow:
+  1. aifabrix login
+  2. aifabrix env deploy dev
+  3. aifabrix deploy <app>
+
 Subcommands:
   deploy <env>   Provision/update environment in Miso Controller (see env deploy --help)
 `;

package/lib/cli/setup-external-system-help.js

@@ -0,0 +1,62 @@
+/**
+ * @fileoverview Help-after blocks for external system lifecycle CLI commands.
+ */
+
+'use strict';
+
+const UPLOAD_HELP_AFTER = `
+Examples:
+  # Publish integration/<systemKey>/ to the dataplane (typical lab flow after validate + resolve)
+  $ aifabrix upload hubspot-demo
+  $ aifabrix upload hubspot-demo --verbose
+  $ aifabrix upload hubspot-demo --probe
+
+  # Build and validate payload only (no API calls)
+  $ aifabrix upload hubspot-demo --dry-run
+
+  # Short summary after publish
+  $ aifabrix upload hubspot-demo --minimal
+
+  # Protection manifests (integration/.protection/ at repo root)
+  $ aifabrix upload .protection
+  $ aifabrix upload .protection --warnings-as-errors --no-sync
+
+Notes:
+  - Requires login (aifabrix auth status).
+  - Reads files under integration/<systemKey>/ (system JSON, datasources, credentials).
+  - --probe runs dataplane runtime checks after publish (slower; common in Session 1).
+  - test-e2e and test-integration publish local files first by default; use --no-sync on those commands to skip.
+  - After dimension/FK edits on active datasources, use --force (or test-e2e / test-integration / datasource test-* with --sync --force).
+  - For one datasource only: aifabrix datasource upload <datasourceKey>
+`;
+
+const DOWNLOAD_HELP_AFTER = `
+Examples:
+  # Pull an existing system from the dataplane into integration/<systemKey>/
+  $ aifabrix download hubspot-demo
+  $ aifabrix download hubspot-demo --format yaml
+
+  # Preview without writing files
+  $ aifabrix download hubspot-demo --dry-run
+
+Notes:
+  - Requires login and a system that already exists on the dataplane.
+  - Overwrite prompts apply when integration/<systemKey>/ already exists (--force for README).
+`;
+
+const DELETE_HELP_AFTER = `
+Examples:
+  # Remove system and datasources from the dataplane
+  $ aifabrix delete hubspot-demo
+  $ aifabrix delete hubspot-demo --yes
+
+Notes:
+  - Does not delete local files under integration/<systemKey>/.
+  - Use when cleaning up test systems or fixing upload schema overlap (then re-run wizard).
+`;
+
+module.exports = {
+  UPLOAD_HELP_AFTER,
+  DOWNLOAD_HELP_AFTER,
+  DELETE_HELP_AFTER
+};