@aifabrix/builder 2.58.0 → 2.60.0

package/lib/api/types/dev.types.js

@@ -30,7 +30,7 @@
  * @property {string} aifabrix-secrets - Local filesystem path or https URL for shared secrets (file vs remote API)
  * @property {string} aifabrix-env-config - Env config path
  * @property {string} remote-server - Builder-server base URL
- * @property {string} docker-endpoint - Docker API endpoint
+ * @property {string} [docker-endpoint] - Docker API endpoint; omit for SSH-only/integrator users
  * @property {string} [developer-root-domain] - App hostname root (e.g. aifabrix.dev → dev01.aifabrix.dev)
  * @property {boolean} [docker-tls-skip-verify] - When true, Docker uses DOCKER_TLS_VERIFY=0 even if ca.pem exists (client mTLS unchanged)
  * @property {string} sync-ssh-user - SSH user for Mutagen
@@ -46,7 +46,7 @@
  * @property {string} createdAt - ISO 8601
  * @property {boolean} certificateIssued - Whether cert was issued
  * @property {string} [certificateValidNotAfter] - Cert validity end (optional)
- * @property {string[]} groups - Access groups (admin, secret-manager, secret-reader, developer, docker)
+ * @property {string[]} groups - Access groups (admin, secret-manager, secret-reader, developer, docker, integrator)
  */
 
 /**
@@ -55,7 +55,7 @@
  * @property {string} developerId - Unique developer ID (numeric string)
  * @property {string} name - Display name
  * @property {string} email - Email
- * @property {string[]} [groups] - Default [developer]; tokens: admin, secret-manager, secret-reader, developer, docker
+ * @property {string[]} [groups] - Default [developer]; tokens: admin, secret-manager, secret-reader, developer, docker, integrator
  */
 
 /**

package/lib/api/work-search.api.js

@@ -121,16 +121,23 @@ async function getWorkRoles(dataplaneUrl, authConfig) {
 
 /**
  * GET-equivalent work.skills for one roleRef.
- * Requests detail=full so search.resourceTypes (executable grammar) is present.
- * Compact summary omits that slice and cannot evaluate named viewpoint ops.
+ * Defaults to detail=full so search.resourceTypes (executable grammar) is present.
+ * A caller may request progressive resource/operation detail for skills-only checks.
  * @requiresPermission {Dataplane} Authenticated (oauth2: [])
  * @async
  */
-async function getWorkSkills(dataplaneUrl, authConfig, roleRef) {
-  return executeLayerBTool(dataplaneUrl, authConfig, LAYER_B_TOOLS.skills, {
+async function getWorkSkills(dataplaneUrl, authConfig, roleRef, options = {}) {
+  const args = {
     roleRef: String(roleRef || '').trim(),
-    detail: 'full'
-  });
+    detail: String(options.detail || 'full').trim()
+  };
+  if (typeof options.resourceType === 'string' && options.resourceType.trim()) {
+    args.resourceType = options.resourceType.trim();
+  }
+  if (typeof options.operation === 'string' && options.operation.trim()) {
+    args.operation = options.operation.trim();
+  }
+  return executeLayerBTool(dataplaneUrl, authConfig, LAYER_B_TOOLS.skills, args);
 }
 
 /**

package/lib/app/deploy.js

@@ -18,7 +18,6 @@ const {
 
 const fs = require('fs').promises;
 const chalk = require('chalk');
-const pushUtils = require('../deployment/push');
 
 const SEP = chalk.gray('────────────────────────────────────────');
 const logger = require('../utils/logger');
@@ -56,106 +55,6 @@ function validateAppName(appName) {
   }
 }
 
-/**
- * Validates push prerequisites
- * @async
- * @function validatePushPrerequisites
- * @param {string} appName - Application name
- * @param {string} registry - Registry URL
- * @throws {Error} If prerequisites are not met
- */
-async function validatePushPrerequisites(appName, registry) {
-  if (!pushUtils.validateRegistryURL(registry)) {
-    throw new Error(`Invalid registry URL format: ${registry}. Expected format: *.azurecr.io`);
-  }
-
-  if (!await pushUtils.checkLocalImageExists(appName, 'latest')) {
-    throw new Error(`Docker image ${appName}:latest not found locally.\nRun 'aifabrix build ${appName}' first`);
-  }
-
-  if (!await pushUtils.checkAzureCLIInstalled()) {
-    throw new Error('Azure CLI is not installed. Install from: https://docs.microsoft.com/cli/azure/install-azure-cli');
-  }
-}
-
-/**
- * Executes push operations
- * @async
- * @function executePush
- * @param {string} appName - Application name
- * @param {string} registry - Registry URL
- * @param {string[]} tags - Tags to push
- * @throws {Error} If push fails
- */
-async function executePush(appName, registry, tags) {
-  if (await pushUtils.checkACRAuthentication(registry)) {
-    logger.log(formatSuccessLine(`Already authenticated with ${registry}`));
-  } else {
-    await pushUtils.authenticateACR(registry);
-  }
-
-  await Promise.all(tags.map(async(tag) => {
-    await pushUtils.tagImage(`${appName}:latest`, `${registry}/${appName}:${tag}`);
-    await pushUtils.pushImage(`${registry}/${appName}:${tag}`, registry);
-  }));
-}
-
-/**
- * Verifies push result
- * @function verifyPushResult
- * @param {string[]} tags - Tags that were pushed
- * @param {string} registry - Registry URL
- * @param {string} appName - Application name
- */
-function verifyPushResult(tags, registry, appName) {
-  logger.log(formatSuccessParagraph(`Successfully pushed ${tags.length} tag(s) to ${registry}`));
-  logger.log(chalk.gray(`Image: ${registry}/${appName}:*`));
-  logger.log(chalk.gray(`Tags: ${tags.join(', ')}`));
-}
-
-/**
- * Pushes application image to Azure Container Registry
- * @async
- * @function pushApp
- * @param {string} appName - Name of the application
- * @param {Object} options - Push options (registry, tag)
- * @returns {Promise<void>} Resolves when push is complete
- */
-async function pushApp(appName, options = {}) {
-  try {
-    validateAppName(appName);
-
-    const { getBuilderPath, resolveApplicationConfigPath } = require('../utils/paths');
-    const { loadConfigFile } = require('../utils/config-format');
-    const builderPath = getBuilderPath(appName);
-    let config;
-    try {
-      const configPath = resolveApplicationConfigPath(builderPath);
-      config = loadConfigFile(configPath);
-    } catch (error) {
-      throw new Error(`Failed to load configuration: ${error.message}\nRun 'aifabrix create ${appName}' first`);
-    }
-
-    const registry = options.registry || config.image?.registry;
-    if (!registry) {
-      throw new Error('Registry URL is required. Provide via --registry flag or configure in application.yaml under image.registry');
-    }
-
-    if (!/^[^.]+\.azurecr\.io$/.test(registry)) {
-      throw new Error(`Invalid ACR URL format: ${registry}. Expected format: *.azurecr.io`);
-    }
-
-    const tags = options.tag ? options.tag.split(',').map(t => t.trim()) : ['latest'];
-
-    await validatePushPrerequisites(appName, registry);
-    await executePush(appName, registry, tags);
-    verifyPushResult(tags, registry, appName);
-
-  } catch (error) {
-    throw new Error(`Failed to push application: ${error.message}`);
-  }
-}
-
 /**
  * Generates and validates deployment manifest
  * @async
@@ -369,7 +268,14 @@ async function executeStandardDeployment(appName, options) {
   const controllerUrl = config.controllerUrl || 'unknown';
   const appExists = await checkApplicationExists(appName, controllerUrl, config.envKey, config.auth);
 
-  const { manifest, manifestPath } = await generateAndValidateManifest(appName, options);
+  // A controller deployment ships tokens plus the platforms/environments sections, so the
+  // Controller resolves them per installation and can promote dev -> tst without regenerating.
+  // Local runs and an explicit --resource-group resolve here instead.
+  const resolveHere = Boolean(options.local || options.resourceGroup);
+  const { manifest, manifestPath } = await generateAndValidateManifest(appName, {
+    ...options,
+    ...(resolveHere ? { target: { environment: config.envKey, resourceGroup: options.resourceGroup } } : {})
+  });
   applyManifestOverrides(manifest, options);
   validateImageIsPullable(manifest.image, appName);
   displayDeploymentInfo(manifest, manifestPath);
@@ -492,7 +398,6 @@ async function deployApp(appName, options = {}) {
 }
 
 module.exports = {
-  pushApp,
   deployApp,
   validateAppName,
   validateImageIsPullable

package/lib/app/show-display.js

@@ -234,6 +234,7 @@ function logExternalSystemMain(ext) {
   logger.log(`  Version:       ${ext.version ?? '—'}`);
   logger.log(`  Credential:    ${formatCredentialShowLine(ext)}`);
   logger.log(`  Status:        ${formatDataplaneStatusDisplay(ext.status)}`);
+  logger.log(`  System link:   ${ext.systemUrl ?? '—'}`);
   logger.log(`  API docs:      ${ext.openApiDocsPageUrl ?? ext.apiDocumentUrl ?? '—'}`);
   logger.log(`  MCP server:    ${ext.mcpServerUrl ?? '—'}`);
   logger.log(`  OpenAPI spec:  ${ext.apiDocumentUrl ?? '—'}`);

package/lib/app/show-online.js

@@ -89,6 +89,7 @@ function buildOnlineSummaryFromDataplane(appKey, controllerUrl, dataplaneUrl, ex
 
 async function finishOnlineShow(summary, appKey, json, permissionsOnly, verifyCert, authBundle) {
   await enrichExternalShowSummary(summary, appKey, verifyCert, authBundle);
+  attachSystemUrl(summary);
   attachRunDefaultsFromUserConfig(summary, appKey, await getConfig());
   await attachDeclarativeUrlsToShowApplication(summary, appKey);
   if (json) {
@@ -100,6 +101,20 @@ async function finishOnlineShow(summary, appKey, json, permissionsOnly, verifyCe
   displayShow(summary, { permissionsOnly: !!permissionsOnly });
 }
 
+/**
+ * Expose the Dataplane system browser route for humans and agents.
+ * Preserve the deployment base path (for example /data).
+ * @param {Object} summary - Online application summary
+ */
+function attachSystemUrl(summary) {
+  const ext = summary.externalSystem;
+  if (!summary.isExternal || !ext || ext.error || !ext.dataplaneUrl) return;
+  const baseUrl = ext.dataplaneUrl.replace(/\/+$/, '');
+  const systemKey = ext.systemKey || summary.appKey;
+  const section = /^(ra-|ek-)/.test(systemKey) ? 'enterprise-knowledge' : 'connected-systems';
+  ext.systemUrl = `${baseUrl}/${section}/${encodeURIComponent(systemKey)}`;
+}
+
 async function runOnlineFromDataplane(appKey, json, permissionsOnly, verifyCert, authConfig, authResult) {
   const environment = await resolveEnvironment();
   const dataplaneUrl = await resolveDataplaneUrl(authResult.actualControllerUrl, environment, authConfig);

package/lib/build/standard-docker-build.js

@@ -81,13 +81,16 @@ async function executeDockerImageBuild(appName, options, buildConfig) {
   await ensureRunSecretsForApp(appName);
   const buildArgs = await resolveDockerBuildArgsForApp(appName, contextPath);
   const { primary, aliases, tags } = options.tagPlan;
+  // `build.target` selects a stage of a multi-stage Dockerfile, so one source tree can
+  // produce more than one image. Absent, Docker builds the last stage as before.
+  const target = buildConfig && buildConfig.target;
   await dockerBuild.executeDockerBuildWithTag(
     effectiveImageName,
     imageName,
     dockerfilePath,
     contextPath,
     primary,
-    { ...options, buildArgs, tagAliases: aliases }
+    { ...options, buildArgs, tagAliases: aliases, target }
   );
   await postBuildTasks(appName, buildConfig);
   logger.log(formatSuccessParagraph('Build completed successfully!'));

package/lib/cli/index.js

@@ -41,6 +41,8 @@ const { setupChannelCommands } = require('../commands/channel');
 const { setupManifestCommands } = require('../commands/manifest');
 const { setupNpmCommands } = require('./setup-npm');
 const { setupListCommand } = require('./setup-list');
+const { setupHelpCommand } = require('./setup-help');
+const { setupOnboardingCommand } = require('./setup-onboarding');
 
 /**
  * Dev, secrets, parameters, and platform commands (keeps setupCommands under statement limit).
@@ -101,6 +103,8 @@ function setupExtendedCliCommands(program) {
  * @param {Command} program - Commander program instance
  */
 function setupCommands(program) {
+  setupHelpCommand(program);
+  setupOnboardingCommand(program);
   setupCoreCliCommands(program);
   setupExtendedCliCommands(program);
   setupDevAndPlatformCommands(program);

package/lib/cli/setup-app.js

@@ -362,7 +362,7 @@ function setupDockerfileGenerateCommand(program) {
 }
 
 function setupDeployCommand(program) {
-  program.command('deploy <appKey|systemKey>')
+  addDeployTargetOptions(program.command('deploy <appKey|systemKey>'))
     .description('Deploy builder app or external system via Miso Controller (Azure or --local)')
     .addHelpText('after', DEPLOY_HELP_AFTER)
     .option('--local', 'Send manifest to controller then run app locally (app: same as aifabrix run <app>; external: restart dataplane)')
@@ -410,6 +410,19 @@ function setupDeployCommand(program) {
     });
 }
 
+/**
+ * Deployment-target options. A controller deployment normally ships {NAME} tokens plus the
+ * platforms/environments sections; these flags force local resolution instead.
+ * @param {Command} command - Commander command
+ * @returns {Command} The command
+ */
+function addDeployTargetOptions(command) {
+  return command.option(
+    '-g, --resource-group <name>',
+    'Target Azure resource group; resolves platforms values in the generated manifest instead of shipping tokens'
+  );
+}
+
 function setupPushDeployDockerfileCommands(program) {
   program.command('push <appKey>')
     .description('Push builder appKey image to Azure Container Registry')

package/lib/cli/setup-dev-path-commands.js

@@ -134,6 +134,10 @@ function addPrintHomeWorkCommands(dev) {
       }
     });
 
+  addShellEnvCommand(dev);
+}
+
+function addShellEnvCommand(dev) {
   dev
     .command('shell-env')
     .description(

package/lib/cli/setup-dev.js

@@ -44,8 +44,11 @@ const DEV_ADD_HELP_AFTER = `
 Examples:
   $ aifabrix dev add --developer-id 02 --name "Jane Doe" --email jane@example.com
   $ aifabrix dev add --developer-id 03 --name "Build admin" --email admin@example.com --groups admin,developer
-  $ aifabrix dev add --developer-id 04 --name "CI user" --email ci@example.com --groups secret-manager,developer
-  $ aifabrix dev add --developer-id 05 --name "Integrator" --email integrator@example.com --groups developer,secret-reader
+  $ aifabrix dev add --developer-id 04 --name "Docker developer" --email docker-dev@example.com --groups developer,docker
+  $ aifabrix dev add --developer-id 05 --name "Integrator" --email integrator@example.com --groups integrator
+
+Groups: integrator is for SSH onboarding without Docker. Use developer,docker for host Docker access (root-equivalent; grant sparingly).
+When --groups is supplied, it replaces the default developer group; developer is not added automatically.
 
 Requires a configured remote Builder Server and an admin client certificate (same machine setup as dev list / dev pin). After add, run dev pin <id> once to create a PIN for aifabrix dev init.
 `;
@@ -318,7 +321,7 @@ function setupDevListAddCommands(dev) {
     .requiredOption('--developer-id <id>', 'Unique id, digits only (e.g. 02); used with dev init --developer-id')
     .requiredOption('--name <name>', 'Display name')
     .requiredOption('--email <email>', 'Email address')
-    .option('--groups <items>', 'Comma-separated roles: admin, secret-manager, secret-reader, developer, docker', 'developer')
+    .option('--groups <items>', 'Comma-separated roles: admin, secret-manager, secret-reader, developer, docker, integrator', 'developer')
     .option('--no-provision', 'Create user in database only (skip host provision job)')
     .option('--builder-version <ver>', 'Builder CLI version for provision job')
     .option('--admin-email <email>', 'Platform admin email for provision job')
@@ -373,7 +376,7 @@ function setupDevUpdatePinDeleteCommands(dev) {
     .option('--developer-id <id>', 'Developer ID (same as dev add)')
     .option('--name <name>', 'Display name')
     .option('--email <email>', 'Email address')
-    .option('--groups <items>', 'Comma-separated groups (admin, secret-manager, secret-reader, developer, docker)')
+    .option('--groups <items>', 'Comma-separated groups (admin, secret-manager, secret-reader, developer, docker, integrator)')
     .addHelpText('after', DEV_UPDATE_HELP_AFTER)
     .action(async(developerId, options) => {
       try {

package/lib/cli/setup-help.js

@@ -0,0 +1,86 @@
+/** Read-only onboarding guide; command reference remains available through --help. */
+'use strict';
+
+const ONBOARDING_GUIDE = `Welcome to AI Fabrix
+
+On a managed workspace host with provisioned config, run:
+
+  af onboarding
+  af onboarding --coding claude
+  af onboarding --coding codex
+  af onboarding --coding cursor
+  af onboarding --coding claude --name sales-workspace
+  af onboarding --coding claude --name finance-workspace
+  af onboarding --repo example-org/example-workspace
+  af onboarding --repo my-org/new-repo
+
+This prepares the coding platform selected by your organisation, or the one
+you pass for this run. Claude starts in a detached tmux session; Codex and
+Cursor use their own SSH clients. It does not install the local AI Fabrix platform.
+Use --name <folder> for separate workspaces; each Claude workspace has its own
+tmux session. Use --repo owner/name to clone an accessible GitHub repository
+or create a new private one. agent-kit remote create creates a new GitHub
+repository for the current local workspace; --name sets that remote name.
+
+Start your integration workspace with Codex:
+
+  aifabrix agent-kit setup <controller-url>
+
+Ask your administrator for the Controller URL.
+Setup guides you through sign-in, installs the Agent Kit,
+and starts your coding agent.
+
+Run setup in a Linux/macOS terminal with Builder, Git and tmux installed.
+On Windows, connect to your organisation's Builder Server first.
+Your files stay under the AI Fabrix work directory on the machine running setup.
+No GitHub account or Docker is required for the default local workspace.
+
+Optional:
+  Use GitHub (requires gh):
+    aifabrix agent-kit setup <controller-url> --repo owner/project
+
+  Use Claude:
+    aifabrix agent-kit setup <controller-url> --code claude
+
+Already have a project?
+  Open its Git repository folder and install the Agent Kit:
+    aifabrix agent-kit install --host codex
+
+Using your organisation's Builder Server?
+  On your own computer, use the onboarding command your administrator gives you:
+    aifabrix dev init --developer-id <id> --server <builder-server-url> --pin <pin>
+
+  Use the SSH command printed after successful onboarding to connect.
+  Once connected to a managed workspace, run af onboarding.
+  For a portable server without managed config, use agent-kit setup above.
+  Integrator accounts use the integrator group; Docker is not needed.
+
+Controller URL: connects your workspace to AI Fabrix.
+Builder Server URL: connects your computer to the remote workspace host.
+These are different services; ask your administrator for the correct URLs.
+
+Explore:
+  aifabrix --help
+  aifabrix agent-kit --help
+  aifabrix <command> --help
+
+This guide does not sign you in, install software, or change configuration.
+`;
+
+function setupHelpCommand(program) {
+  program.addHelpCommand(false);
+  program.command('help [command]')
+    .description('Show the onboarding guide, or help for a command')
+    .addHelpText('after', '\nExamples:\n  $ aifabrix help\n  $ aifabrix help agent-kit\n')
+    .action((name, options, command) => {
+      if (!name) {
+        command.configureOutput().writeOut(ONBOARDING_GUIDE);
+        return;
+      }
+      const target = program.commands.find(item => item.name() === name || item.aliases().includes(name));
+      if (!target) command.error(`Unknown command '${name}'. Run aifabrix --help to list commands.`);
+      target.outputHelp();
+    });
+}
+
+module.exports = { setupHelpCommand, ONBOARDING_GUIDE };

package/lib/cli/setup-onboarding.js

@@ -0,0 +1,37 @@
+/** Top-level managed Agent Kit onboarding command. */
+'use strict';
+
+const logger = require('../utils/logger');
+const { formatBlockingError } = require('../utils/cli-layout-chalk');
+const { maskSensitiveData } = require('../utils/log-redaction');
+const { runManagedOnboarding } = require('../agent-kit/setup');
+
+function setupOnboardingCommand(program) {
+  program.command('onboarding')
+    .description('Prepare your provisioned Agent Kit workspace for the selected coding platform')
+    .option('--coding <platform>', 'Use claude, codex, or cursor for this run')
+    .option('--name <folder>', 'Create or reuse this workspace folder under the managed work root')
+    .option('--repo <owner/name>', 'Reuse or clone this GitHub repository, or create it privately')
+    .addHelpText('after', '\nRun on your managed workspace host after connecting by SSH.\n' +
+      'Reads ~/.aifabrix/config.yaml; --coding overrides its codingPlatform for this run only.\n' +
+      'For portable onboarding use aifabrix agent-kit setup <controllerUrl>.\n\n' +
+      'Examples:\n' +
+      '  $ af onboarding\n' +
+      '  $ af onboarding --coding claude\n' +
+      '  $ af onboarding --coding claude --name sales-workspace\n' +
+      '  $ af onboarding --coding claude --name finance-workspace\n' +
+      '  $ af onboarding --repo example-org/example-workspace\n' +
+      '  $ af onboarding --repo my-org/new-repo\n' +
+      '  $ af onboarding --coding codex\n' +
+      '  $ af onboarding --coding cursor\n')
+    .action(async(options) => {
+      try {
+        await runManagedOnboarding(options);
+      } catch (error) {
+        logger.error(formatBlockingError(maskSensitiveData(error.message)));
+        process.exitCode = 1;
+      }
+    });
+}
+
+module.exports = { setupOnboardingCommand };

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

@@ -99,7 +99,9 @@ function logRepairDryRunOutcome(options, result, changedFiles) {
  */
 function logRepairSuccessOutcome(result, changedFiles) {
   if (result.updated) {
-    logger.log(formatSuccessParagraph('Repaired external integration config.'));
+    logger.log(formatSuccessParagraph(result.applicationReadme
+      ? 'Regenerated README.md from application configuration.'
+      : 'Repaired external integration config.'));
     logRepairChangedFiles(changedFiles, false);
     logRepairNextActions(changedFiles, result.warnings);
     return;
@@ -166,7 +168,7 @@ async function handleRepairCommand(appName, options) {
  */
 function setupRepairCommand(program) {
   program.command('repair <systemKey>')
-    .description('Fix external integration drift (files, RBAC, manifest, …)')
+    .description('Fix external integration drift or regenerate application documentation (--doc)')
     .option('--all', 'Run all repair actions (api, doc, expose, rbac, sync, test)')
     .option(
       '--api',
@@ -176,10 +178,10 @@ function setupRepairCommand(program) {
       '--auth <method>',
       'Set authentication method (oauth2, aad, apikey, bearerToken, basic, queryParam, oidc, hmac, none); updates system file and env.template'
     )
-    .option('--doc', 'Regenerate README.md from deployment manifest')
+    .option('--doc', 'Regenerate README.md from application config or external integration deployment manifest')
     .option('--expose', 'Set exposed.schema on each datasource from all fieldMappings.attributes keys (metadata.<key>); removes deprecated exposed.attributes if present')
     .option('--rbac', 'Ensure RBAC permissions per datasource and add default Admin/Reader roles if none exist; warns when capabilities lack openapi.operations (auto-syncs operations)')
-    .option('--sync', 'Add default sync section to datasources that lack it')
+    .option('--sync', 'Add enabled monthly UTC sync defaults when the sync section is absent')
     .option(
       '--auth-webhook',
       'Ensure authentications[] slot usage=webhookInbound (454 webhook inbound auth)'
@@ -197,7 +199,7 @@ function setupRepairCommand(program) {
       '--rbac-preset <preset>',
       'RBAC preset for facade APIs (e.g. platform — dataplane role catalog)'
     )
-    .option('--no-backup', 'Skip timestamped copies under integration/<systemKey>/backup/')
+    .option('--no-backup', 'Skip timestamped copies under the application folder backup/')
     .option('--dry-run', 'Report changes only; do not write')
     .addHelpText('after', REPAIR_HELP_AFTER)
     .action(async(appName, options) => {

package/lib/cli/setup-utility.js

@@ -65,6 +65,23 @@ async function handleSplitJsonCommand(appName, options) {
   return generator.splitDeployJson(deployJsonPath, outputDir);
 }
 
+/**
+ * Deployment target for manifest generation. A resource group resolves platform values; the
+ * environment key resolves the environments layer. Without either, {NAME} tokens are preserved.
+ * @param {Object} options - Command options
+ * @returns {Promise<{ resourceGroup: string|undefined, environment: string }>}
+ */
+async function buildGenerationTarget(options = {}) {
+  // Only an explicit target resolves. The default artifact keeps {NAME} tokens and carries the
+  // platforms/environments sections, so the Controller resolves them per installation.
+  if (!options.resourceGroup && !options.env) return undefined;
+  const { resolveEnvironment } = require('../core/config');
+  const environment = options.env
+    ? String(options.env).trim().toLowerCase()
+    : await resolveEnvironment();
+  return { resourceGroup: options.resourceGroup, environment };
+}
+
 /**
  * Logs split-json results
  * @param {Object} result - Generated file paths
@@ -93,6 +110,11 @@ function logSplitJsonResult(result) {
 function setupJsonCommand(program) {
   program.command('json <appKey|systemKey>')
     .description('Write deployment JSON to disk for version control')
+    .option(
+      '-g, --resource-group <name>',
+      'Target Azure resource group; resolves platforms/environments values instead of leaving {NAME} tokens'
+    )
+    .option('-e, --env <env>', 'Deployment environment key for environments resolution (default: current environment)')
     .addHelpText('after', JSON_HELP_AFTER)
     .action(async(appName, options) => {
       try {
@@ -105,7 +127,8 @@ function setupJsonCommand(program) {
           json: false
         });
         const result = await generator.generateDeployJsonWithValidation(appName, {
-          ...options
+          ...options,
+          target: await buildGenerationTarget(options)
         });
         if (result.success) {
           const fileName = result.path.includes('application-schema.json') ? 'application-schema.json' : 'deployment JSON';

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

@@ -16,6 +16,7 @@ Coding hosts (--host) are Cursor, Claude Code, and/or Codex in this workspace.
 GitHub remotes are a separate command (agent-kit remote create).
 
 Examples:
+  $ aifabrix agent-kit setup https://controller.example.com
   $ aifabrix agent-kit init cust-demo --host all --approve-all --yes
   $ aifabrix agent-kit install --host claude --approve-all --yes
   $ aifabrix agent-kit install --host all --approve-all claude --yes
@@ -94,10 +95,12 @@ Silent remote: --host all --remote --org <owner> --yes
 const REMOTE_GROUP_HELP = `
 This is GitHub only: create origin and push this workspace.
 It does not choose Cursor, Claude Code, or Codex.
+For an existing GitHub repository on a managed host, use af onboarding --repo owner/name.
 
 Examples:
-  $ aifabrix agent-kit remote create
-  $ aifabrix agent-kit remote create --org my-org --yes
+  $ cd ~/agent-kit-workspace && af agent-kit remote create --org my-org --name my-repo --yes
+  $ af onboarding --repo my-org/existing-repo
+  $ af onboarding --repo my-org/new-repo
   $ aifabrix agent-kit install --host claude --approve-all --yes
   $ aifabrix agent-kit install --host codex --approve-all --yes
   $ aifabrix agent-kit install --host all --approve-all claude --yes
@@ -105,12 +108,16 @@ Examples:
 
 const REMOTE_HELP = `
 Creates a GitHub repository (origin) and pushes this workspace.
+Run inside the local workspace. --name sets the new GitHub repository name;
+omit it to use the workspace folder name. This command does not clone an
+existing GitHub repository.
 Not coding-host selection — use --host on install/update for Claude or Codex.
 
 Examples:
-  $ cd cust-demo && aifabrix agent-kit remote create
-  $ aifabrix agent-kit remote create --org my-org --yes
-  $ aifabrix agent-kit remote create --org my-org --dry-run --json
+  $ cd ~/agent-kit-workspace && af agent-kit remote create --org my-org --name my-repo --yes
+  $ af agent-kit remote create --org my-org --name my-repo --dry-run --json
+  $ af onboarding --repo my-org/existing-repo
+  $ af onboarding --repo my-org/new-repo
 
 Interactive (TTY): omit flags to be prompted. Silent: --org <owner> --yes
 `;
@@ -134,7 +141,10 @@ Examples:
 `;
 
 const LIST_HELP = `
-Lists every active tmux session visible to the current Unix user.
+Lists active tmux sessions and direct Codex app servers owned by the current
+Unix user. On a terminal, choose a tmux session to attach or Close. Codex app
+servers are shown as information and cannot be selected from this menu.
+--json and non-interactive output print the report without a prompt.
 
 Examples:
   $ aifabrix agent-kit list
@@ -142,9 +152,13 @@ Examples:
 `;
 
 const KILL_HELP = `
-Stops exactly one tmux session. Use agent-kit list to find its name.
+Stops exactly one tmux session by name. Omit the name in an interactive
+terminal to choose a tmux session or Codex app server. Stopping a Codex app
+server requires confirmation and may disconnect an active desktop chat.
+Pass an exact tmux name for scripts or --json.
 
 Examples:
+  $ aifabrix agent-kit kill
   $ aifabrix agent-kit kill aifabrix-miso
   $ aifabrix agent-kit kill aifabrix-miso --json
 `;