@aifabrix/builder 2.45.5 → 2.47.0

package/lib/cli/setup-app.js

@@ -31,8 +31,34 @@ Prefer aifabrix wizard [systemKey] for guided external setup.
 
 const DEPLOY_HELP_AFTER = `
 Examples:
-  $ aifabrix deploy myapp              # builder appKey → builder/myapp/
-  $ aifabrix deploy hubspot --local    # systemKey → integration/hubspot/
+  # Local — builder app (builder/<appKey>/)
+  $ aifabrix deploy myapp
+  $ aifabrix deploy myapp --local
+
+  # Local — external system (integration/<systemKey>/); manifest regenerated on deploy
+  $ aifabrix deploy hubspot-demo
+  $ aifabrix deploy hubspot-demo --local
+  $ aifabrix deploy hubspot-demo --probe
+
+  # CI/CD — builder app (GitHub Actions / Azure DevOps; pipeline client credentials in secrets)
+  $ aifabrix validate myapp
+  $ aifabrix build myapp
+  $ aifabrix push myapp --registry $ACR_REGISTRY --tag $IMAGE_TAG
+  $ aifabrix deploy myapp \\
+      --client-id "$DEV_MISO_CLIENTID" \\
+      --client-secret "$DEV_MISO_CLIENTSECRET" \\
+      --no-poll
+
+  # CI/CD — external integration (after upload/tests; promote to controller)
+  $ aifabrix validate hubspot-demo
+  $ aifabrix upload hubspot-demo --probe
+  $ aifabrix deploy hubspot-demo --probe --no-poll
+
+Notes:
+  - Login or set MISO_CONTROLLER_URL + environment (aifabrix login / aifabrix auth).
+  - CI: register once (aifabrix app register <appKey>), store DEV_MISO_CLIENTID and DEV_MISO_CLIENTSECRET in pipeline secrets.
+  - upload = dataplane publish for dev iteration; deploy = controller validate + deploy (Azure or local Docker).
+  - --repository-url overrides repo URL for pipeline validate (default: application.yaml repository.repositoryUrl).
 `;
 
 const PUSH_HELP_AFTER = `
@@ -86,6 +112,49 @@ function normalizeExternalOptions(options) {
   return normalized;
 }
 
+/**
+ * Whether normalized options include all external CLI fields for headless create.
+ * @param {Object} normalized - Normalized external create options
+ * @returns {boolean}
+ */
+function hasFullExternalCliOptions(normalized) {
+  return Boolean(
+    normalized.systemKey &&
+    normalized.systemDisplayName &&
+    normalized.systemDescription &&
+    normalized.systemType &&
+    normalized.authType &&
+    normalized.entityType &&
+    normalized.datasourceCount
+  );
+}
+
+/**
+ * Map positional systemKey and apply headless defaults for external create.
+ * @param {string} appName - Positional appKey or systemKey from CLI
+ * @param {Object} options - Raw CLI options
+ * @returns {Object} Normalized options ready for createApp
+ */
+function prepareExternalCreateOptions(appName, options) {
+  const normalized = normalizeExternalOptions(options);
+  const isExternalType = options.type === 'external' || !options.type;
+
+  if (isExternalType && appName) {
+    normalized.systemKey = appName;
+  }
+
+  if (isExternalType && hasFullExternalCliOptions(normalized)) {
+    if (!Object.prototype.hasOwnProperty.call(normalized, 'github')) {
+      normalized.github = false;
+    }
+    if (!Object.prototype.hasOwnProperty.call(normalized, 'controller')) {
+      normalized.controller = false;
+    }
+  }
+
+  return normalized;
+}
+
 /**
  * Validate required options for non-interactive external creation
  * @param {Object} normalizedOptions - Normalized options
@@ -123,7 +192,7 @@ async function handleCreateCommand(appName, options) {
   }
 
   const wizardOptions = { app: appName, ...options };
-  const normalizedOptions = normalizeExternalOptions(options);
+  const normalizedOptions = prepareExternalCreateOptions(appName, options);
 
   const isExternalType = options.type === 'external' || !options.type;
   const isNonInteractive = process.stdin && process.stdin.isTTY === false;
@@ -253,7 +322,10 @@ function setupBuildRunLogsDownCommands(program) {
     .option('-f, --force-template', 'Force rebuild from template')
     .option('--no-cache', 'Full Docker rebuild (disable layer cache); use after Dockerfile or context fixes')
     .option('-t, --tag <tag>', 'Image tag (default: latest). Set image.tag in application.yaml to match for deploy.')
-    .option('--base', 'Also tag the manifest base image name (after developer-scoped build when developer id > 0)')
+    .option(
+      '--base',
+      'When manifest omits image: also tag the base repository after a developer-scoped build (ignored when application.yaml defines image)'
+    )
     .action(async(appName, options) => {
       try {
         const imageTag = await app.buildApp(appName, options);
@@ -411,4 +483,9 @@ function setupAppCommands(program) {
   setupPushDeployDockerfileCommands(program);
 }
 
-module.exports = { setupAppCommands };
+module.exports = {
+  setupAppCommands,
+  normalizeExternalOptions,
+  prepareExternalCreateOptions,
+  validateNonInteractiveExternalOptions
+};

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

@@ -10,9 +10,7 @@ const { handleCommandError } = require('../utils/cli-utils');
 const { cliOptsSkipCertSync } = require('../certification/cli-cert-sync-skip');
 const {
   TEST_HELP_AFTER,
-  TEST_E2E_HELP_AFTER,
-  TEST_TRUST_HELP_AFTER,
-  TEST_GOVERNANCE_HELP_AFTER
+  TEST_E2E_HELP_AFTER
 } = require('./setup-app.help');
 
 function setupTestCommand(program) {
@@ -177,6 +175,10 @@ function setupTestE2eCommand(program) {
       '--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(
@@ -222,64 +224,10 @@ function setupLintCommand(program) {
     });
 }
 
-function collectScenarioId(value, previous) {
-  return previous.concat([value]);
-}
-
-function setupTestGovernanceCommand(program) {
-  const { testGovernanceCommandHandler } = require('../commands/test-governance-command-action');
-  program
-    .command('test-governance <appKey|systemKey>')
-    .description(
-      'Governance scenario acceptance: ABAC visibility via governed search (key sets only)'
-    )
-    .option('-e, --env <env>', 'Environment: dev, tst, or pro', 'dev')
-    .option('--pack <path>', 'Scenario pack YAML (default: scenarios/default.yaml or <systemKey>-v1.yaml)')
-    .option('-a, --app <path>', 'Integration folder override')
-    .option(
-      '--scenario <id>',
-      'Run subset of scenario ids (repeatable)',
-      collectScenarioId,
-      []
-    )
-    .option('--no-sync', 'Skip publishing local integration files before run')
-    .option('-v, --verbose', 'Per-scenario verdict lines with subject and counts')
-    .option('--json', 'Machine-readable redacted result (same allowlist as API)')
-    .addHelpText('after', TEST_GOVERNANCE_HELP_AFTER)
-    .action((appName, options, cmd) => testGovernanceCommandHandler(appName, options, cmd));
-}
-
-function setupTestTrustCommand(program) {
-  const { testTrustCommandHandler } = require('../commands/test-trust-command-action');
-  program
-    .command('test-trust <appKey|systemKey>')
-    .description(
-      'Semantic agent metadata validation for external system (all datasources via dataplane 404.5)'
-    )
-    .option('-e, --env <env>', 'Environment: dev, tst, or pro', 'dev')
-    .option('-v, --verbose', 'Show findings and observed business model')
-    .option('-d, --debug', 'Write debug log under integration/<systemKey>/logs/')
-    .option('--no-sync', 'Skip publishing local integration files before validate')
-    .option('--revalidate', 'Force new validation for each datasource')
-    .option(
-      '--timeout <ms>',
-      'HTTP timeout for validate/latest requests (ms)',
-      '120000'
-    )
-    .option('--strict', 'Exit 1 unless every datasource is trusted')
-    .option('--warnings-as-errors', 'Exit 1 when any datasource is usableWithWarnings')
-    .option('--json', 'Print JSON array of trust runs')
-    .option('--summary', 'One line per datasource')
-    .addHelpText('after', TEST_TRUST_HELP_AFTER)
-    .action((appName, options, cmd) => testTrustCommandHandler(appName, options, cmd));
-}
-
 function setupInstallTestE2eLintCommands(program) {
   setupInstallCommand(program);
   setupTestCommand(program);
   setupTestE2eCommand(program);
-  setupTestGovernanceCommand(program);
-  setupTestTrustCommand(program);
   setupLintCommand(program);
 }
 

package/lib/cli/setup-auth.js

@@ -31,11 +31,31 @@ Aliases:
 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
@@ -152,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);
@@ -168,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);

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
+};