@aifabrix/builder 2.58.0 → 2.59.0

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

@@ -0,0 +1,52 @@
+/** Machine-local onboarding progress, outside the repository and without credentials. */
+'use strict';
+
+const path = require('path');
+const fs = require('../internal/fs-real-sync');
+const { randomUUID } = require('crypto');
+const { assertDirectory } = require('./setup-context');
+
+function readState(file) {
+  if (!fs.existsSync(file)) return null;
+  if (!fs.lstatSync(file).isFile()) throw new Error('Onboarding state must be a regular file.');
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    throw new Error('Onboarding state is invalid; preserve the workspace and inspect its state file.');
+  }
+}
+
+function acquireWorkspace(context) {
+  const dir = path.join(context.root, '.aifabrix-onboarding');
+  assertDirectory(dir);
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const file = path.join(dir, `${context.name}.json`);
+  const lock = `${file}.lock`;
+  let descriptor;
+  try {
+    descriptor = fs.openSync(lock, 'wx', 0o600);
+  } catch {
+    throw new Error(`Workspace setup is locked. If no setup is running, remove the stale lock: ${lock}`);
+  }
+  fs.closeSync(descriptor);
+  const release = () => fs.unlinkSync(lock);
+  try {
+    const state = readState(file);
+    if (state && (state.controller !== context.controller || state.fullName !== context.fullName || state.target !== context.target)) {
+      throw new Error('This workspace belongs to a different Controller or repository. Use a different AI Fabrix work directory.');
+    }
+    return { file, release, state: state || { controller: context.controller, fullName: context.fullName, target: context.target } };
+  } catch (error) {
+    release();
+    throw error;
+  }
+}
+
+function saveProgress(progress, patch) {
+  Object.assign(progress.state, patch);
+  const temporary = `${progress.file}.${randomUUID()}.tmp`;
+  fs.writeFileSync(temporary, `${JSON.stringify(progress.state, null, 2)}\n`, { flag: 'wx', mode: 0o600 });
+  fs.renameSync(temporary, progress.file);
+}
+
+module.exports = { acquireWorkspace, saveProgress };

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

@@ -0,0 +1,113 @@
+/** Local workspace preparation and optional GitHub clone/create with safe resumability. */
+'use strict';
+
+const fs = require('../internal/fs-real-sync');
+const { runInit } = require('./init');
+const { runInstall, runUpdate } = require('./run');
+const { resolveGitRoot } = require('./repo-guard');
+const { ensureInitialCommit } = require('./scm/git');
+const { capture, checked } = require('./setup-process');
+const github = require('./setup-github');
+const { saveProgress } = require('./setup-state');
+
+function validateExisting(context, progress, options) {
+  if (progress.state.initializing || progress.state.cloning) {
+    throw new Error('Workspace initialization or clone was interrupted. Inspect the preserved folder and onboarding state before retrying.');
+  }
+  if (!fs.existsSync(context.target) || fs.readdirSync(context.target).length === 0) return false;
+  if (resolveGitRoot(context.target) !== context.target) throw new Error('Workspace must be its own Git repository.');
+  if (context.fullName) {
+    const origin = github.originIdentity(context.target, options);
+    if (origin || !progress.state.initialized) github.assertOrigin(context, options);
+  } else if (!progress.state.initialized || github.originIdentity(context.target, options)) {
+    throw new Error('Local workspace is not an existing local-only onboarding workspace. No files were changed.');
+  }
+  return true;
+}
+
+function checkKit(result) {
+  if (result.conflicts && result.conflicts.length) {
+    throw new Error('Agent Kit files have local conflicts. Resolve them with agent-kit status/update before retrying setup.');
+  }
+}
+
+function initializeLocal(context, progress, options) {
+  // Persist the operation first so an interrupted partial init cannot be adopted on retry.
+  saveProgress(progress, { initializing: true });
+  runInit({ nameOrPath: context.target, host: context.code, noRemote: true, approveAll: false,
+    interactive: false, execFileSync: options.execFileSync });
+  saveProgress(progress, { initialized: true, initializing: false });
+}
+
+function finishNewRemote(context, progress, options) {
+  const opts = { ...options, cwd: context.target };
+  if (!progress.state.initialCommit) {
+    ensureInitialCommit(context.target, opts);
+    const initialCommit = String(capture('git', ['rev-parse', 'HEAD'], opts)).trim();
+    saveProgress(progress, { initialCommit });
+  }
+  if (!progress.state.remoteCreated) {
+    github.createRepository(context.fullName, options);
+    saveProgress(progress, { remoteCreated: true });
+  }
+  if (!github.originIdentity(context.target, options)) {
+    checked('git', ['remote', 'add', 'origin', `https://github.com/${context.fullName}.git`],
+      'Could not configure the GitHub origin. Local files are preserved.', opts);
+  }
+  github.pushInitialCommit(context, progress, saveProgress, options);
+}
+
+function cloneWorkspace(context, progress, options) {
+  if (progress.state.initialized) throw new Error('Previously initialized workspace is missing. Restore it before retrying.');
+  saveProgress(progress, { cloning: true });
+  github.cloneRepository(context, options);
+  saveProgress(progress, { initialized: true, cloning: false });
+}
+
+function prepareGithub(context, progress, options, existing) {
+  if (existing && github.originIdentity(context.target, options)) {
+    if (progress.state.remoteCreated && !progress.state.pushed) finishNewRemote(context, progress, options);
+    return false;
+  }
+  const remote = github.lookupRepository(context.fullName, options);
+  if (!remote) {
+    if (progress.state.remoteCreated) {
+      throw new Error('The existing remote is no longer accessible. Restore access before retrying.');
+    }
+    if (existing && !progress.state.initialCommit) {
+      throw new Error('Initialization stopped before recording the initial commit. Inspect the preserved workspace before creating its remote.');
+    }
+    if (!existing) initializeLocal(context, progress, options);
+    finishNewRemote(context, progress, options);
+    return true;
+  }
+  if (!existing) {
+    cloneWorkspace(context, progress, options);
+  } else if (!progress.state.remoteCreated) {
+    throw new Error('Repository appeared during creation. Inspect the local workspace and remote before connecting them.');
+  }
+  if (progress.state.remoteCreated && !progress.state.pushed) finishNewRemote(context, progress, options);
+  github.assertOrigin(context, options);
+  return false;
+}
+
+function prepareWorkspace(context, progress, options = {}) {
+  const existing = validateExisting(context, progress, options);
+  let installed = false;
+  if (context.fullName) installed = prepareGithub(context, progress, options, existing);
+  else if (!existing) {
+    if (progress.state.initialized) throw new Error('Previously initialized workspace is missing. Restore it before retrying.');
+    initializeLocal(context, progress, options);
+    installed = true;
+  }
+  if (!installed) {
+    const install = options.managed ? runUpdate : runInstall;
+    const preview = install({ cwd: context.target, host: context.code, approveAll: false, dryRun: true });
+    checkKit(preview);
+    checkKit(install({ cwd: context.target, host: context.code, approveAll: false }));
+  }
+  if (!fs.existsSync(context.target)) throw new Error('Workspace preparation did not create its directory.');
+  saveProgress(progress, { initialized: true, ready: true });
+}
+
+module.exports = { validateExisting, prepareWorkspace, checkKit };

package/lib/agent-kit/setup.js

@@ -0,0 +1,84 @@
+/** Portable local-first agent onboarding. */
+'use strict';
+
+const { randomUUID } = require('crypto');
+const logger = require('../utils/logger');
+const { formatSuccessLine } = require('../utils/cli-layout-chalk');
+const { auditLog } = require('../core/audit-logger');
+const { normalizeSetup, preflight, resolveWork } = require('./setup-context');
+const { acquireWorkspace } = require('./setup-state');
+const { ensureController, ensureGithubLogin, ensureProvider } = require('./setup-auth');
+const { prepareWorkspace, validateExisting } = require('./setup-workspace');
+const { prepareSession, attachSession } = require('./setup-session');
+const { managedSetupOptions } = require('./setup-managed');
+
+async function authenticate(context, options, setPhase) {
+  setPhase('controller-login');
+  logger.log('Connecting to AI Fabrix...');
+  await ensureController(context);
+  if (context.fullName) {
+    setPhase('github-login');
+    ensureGithubLogin(options);
+  }
+  if (context.code === 'cursor') return null;
+  setPhase('agent-login');
+  return ensureProvider(context, options);
+}
+
+async function prepareOnboarding(context, progress, options) {
+  const correlationId = randomUUID();
+  let provider;
+  let session;
+  let phase = 'workspace-check';
+  try {
+    validateExisting(context, progress, options);
+    provider = await authenticate(context, options, value => {
+      phase = value;
+    });
+    phase = 'workspace';
+    prepareWorkspace(context, progress, options);
+    if (!options.managed || context.code === 'claude') {
+      phase = 'agent-start';
+      session = prepareSession(context, provider, options);
+    }
+    await auditLog('AUDIT', 'Agent workspace onboarding ready', { correlationId, path: context.target, agent: context.code });
+  } catch (error) {
+    await auditLog('ERROR', 'Agent workspace onboarding failed', { correlationId, phase });
+    throw error;
+  } finally {
+    progress.release();
+  }
+  return { session, provider };
+}
+
+async function runSetup(options = {}) {
+  const input = normalizeSetup(options);
+  preflight(input, options);
+  const context = await resolveWork(input, options);
+  const progress = acquireWorkspace(context);
+  const { session, provider } = await prepareOnboarding(context, progress, options);
+  logger.log(formatSuccessLine(`Workspace ready: ${context.target}`));
+  if (options.managed) {
+    const host = options.remoteHost || new URL(context.controller).hostname;
+    if (context.code === 'claude') {
+      logger.log(`Claude Code running in tmux session ${session}. Attach: tmux attach -t ${session}`);
+      logger.log(`Next: Open Claude Code Remote Control on ${host}, or attach to ${session}.`);
+      return { path: context.target, code: context.code, session };
+    }
+    const next = {
+      cursor: `In Cursor, connect with Remote SSH to ${host}, then open ${context.target}.`,
+      codex: `In Codex, add the SSH project ${context.target} on ${host}.`
+    }[context.code];
+    logger.log(`Next: ${next} Say "Hi" to begin.`);
+  } else {
+    attachSession(session, provider, options);
+  }
+  return { path: context.target, code: context.code, session };
+}
+
+async function runManagedOnboarding(options = {}) {
+  const managed = await managedSetupOptions(options);
+  return runSetup({ ...options, ...managed });
+}
+
+module.exports = { runSetup, runManagedOnboarding };

package/lib/agent-kit/start.js

@@ -129,7 +129,7 @@ function buildTmuxSpec(p) {
   const remote = p.app === 'claude' && p.remoteControl;
   return {
     bin: 'tmux',
-    args: [...mode, spec.bin, ...extra],
+    args: [...mode, ...(p.binary ? ['env', p.binary] : [spec.bin]), ...extra],
     session: p.session,
     appBin: spec.bin,
     needTmux: true,
@@ -287,16 +287,17 @@ function resolveStartContext(options) {
   const cwd = resolveGitRoot(options.cwd || process.cwd());
   const session = resolveSessionName(options.name, cwd);
   const remoteControlPrefix = hostUserPrefix(options);
-  const remoteControlName = resolveRemoteControlName(remoteControlPrefix, session);
+  const remoteControlName = options.remoteControlName || resolveRemoteControlName(remoteControlPrefix, session);
   const remoteControl = options.remoteControl !== false;
   const spec = buildLaunchSpec({
     app, cwd, session, remoteControlPrefix, remoteControlName,
-    detach: Boolean(options.detach), remoteControl
+    detach: Boolean(options.detach), remoteControl, binary: options.binary
   });
   spec.cwd = cwd;
   const remoteSpec = app === 'codex' && remoteControl
     ? buildCodexRemoteSpec(cwd)
     : undefined;
+  if (remoteSpec && options.binary) remoteSpec.bin = options.binary;
   return { app, cwd, session, remoteControl, spec, remoteSpec };
 }
 

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

@@ -5,7 +5,7 @@
 
 'use strict';
 
-const { execFileSync } = require('child_process');
+const { execFileSync, spawnSync } = require('child_process');
 
 const LIST_FORMAT = [
   '#{session_name}',
@@ -66,7 +66,7 @@ function isNoTmuxServer(error) {
     .filter(Boolean)
     .map(String)
     .join(' ');
-  return /no server running|failed to connect to server/i.test(message);
+  return /no server running|failed to connect to server|error connecting to .*\/tmux-\d+\/.*No such file or directory/i.test(message);
 }
 
 /**
@@ -150,6 +150,22 @@ function runKill(options) {
   return { command: 'kill', session, killed: true };
 }
 
+function runAttach(options) {
+  const exec = options.execFileSync || execFileSync;
+  const session = normalizeExactSessionName(options.name);
+  requireTmux(exec);
+  if (!tmuxSessionExists(session, exec)) {
+    throw new Error(`tmux session "${session}" is not running. Run: aifabrix agent-kit list`);
+  }
+  const insideTmux = Boolean((options.env || process.env).TMUX);
+  const args = [insideTmux ? 'switch-client' : 'attach-session', '-t', `=${session}`];
+  const result = (options.spawnSync || spawnSync)('tmux', args, { stdio: 'inherit' });
+  if (!result || result.error || result.signal || result.status !== 0) {
+    throw new Error(`Could not attach to tmux session "${session}".`);
+  }
+  return { command: 'attach', session, attached: true };
+}
+
 module.exports = {
   LIST_FORMAT,
   hasOnPath,
@@ -159,5 +175,6 @@ module.exports = {
   tmuxSessionExists,
   parseSessionLine,
   runList,
-  runKill
+  runKill,
+  runAttach
 };

package/lib/api/dev.api.js

@@ -198,7 +198,7 @@ async function listUsers(serverUrl, clientCertPem, serverCaPem) {
  * @requiresPermission {BuilderServer} Client certificate (X-Client-Cert)
  * @param {string} serverUrl - Builder Server base URL
  * @param {string} clientCertPem - PEM client certificate
- * @param {Object} body - CreateUserDto: developerId, name, email, optional groups (admin | secret-manager | secret-reader | developer | docker)
+ * @param {Object} body - CreateUserDto: developerId, name, email, optional groups (admin | secret-manager | secret-reader | developer | docker | integrator)
  * @param {string} [serverCaPem] - Dev root CA PEM
  * @returns {Promise<Object>} UserResponseDto
  */

package/lib/api/miso-health.api.js

@@ -0,0 +1,26 @@
+/**
+ * Application-token health proof through the public Miso SDK transport.
+ * @fileoverview Never reads or returns the application token itself.
+ */
+'use strict';
+
+/**
+ * POST /api/v1/auth/validate-client-token
+ * @requiresPermission {Controller} Client token
+ * @param {Object} client Initialized runtime client
+ * @param {AbortSignal} signal Probe cancellation
+ * @returns {Promise<void>} Resolves only for an authenticated application
+ */
+async function validateMisoApplicationToken(client, signal) {
+  const response = await client.requestWithAuthStrategy(
+    'POST', '/api/v1/auth/validate-client-token', { methods: ['client-token'] },
+    {}, { signal, timeout: 3000, maxRedirects: 0 }
+  );
+  if (response?.success === false || response?.data?.authenticated !== true) {
+    const error = new Error('Miso application authentication failed');
+    error.statusCode = 401;
+    throw error;
+  }
+}
+
+module.exports = { validateMisoApplicationToken };

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/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
@@ -492,7 +391,6 @@ async function deployApp(appName, options = {}) {
 }
 
 module.exports = {
-  pushApp,
   deployApp,
   validateAppName,
   validateImageIsPullable

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