@aifabrix/builder 2.58.0 → 2.60.0

package/lib/utils/docker-manifest-public-port.js

@@ -81,6 +81,41 @@ async function mergeDockerManifestPublishedPort(envVars, appDoc) {
   envVars[publicPortKey] = String(devIdNum > 0 ? pubBase + devIdNum * 100 : pubBase);
 }
 
+/**
+ * Publish `<NAME>_PUBLIC_PORT` for every `additionalPorts` entry.
+ *
+ * An application serving a second protocol needs to tell clients which port to use, and
+ * that is the *published* host port, not the one it listens on inside the container. The
+ * two differ by the developer-id offset, so a template that types the number by hand
+ * silently disagrees with the manifest the moment either changes — and the application
+ * then advertises a port nothing is listening on.
+ *
+ * Named after the port, so `additionalPorts: [{ name: ssh, hostPort: 2200 }]` gives
+ * `SSH_PUBLIC_PORT`, which an env.template consumes as `${SSH_PUBLIC_PORT}`.
+ *
+ * @param {Object} envVars - Mutated map from buildEnvVarMap
+ * @param {Object|null|undefined} appDoc - application.yaml root
+ * @returns {Promise<void>}
+ */
+async function mergeAdditionalPublishedPorts(envVars, appDoc) {
+  const entries = appDoc && Array.isArray(appDoc.additionalPorts) ? appDoc.additionalPorts : [];
+  if (entries.length === 0) {
+    return;
+  }
+  const devIdNum = await require('./env-map').getDeveloperIdNumber(null);
+  for (const entry of entries) {
+    if (!entry || typeof entry.name !== 'string') {
+      continue;
+    }
+    const base = Number(entry.hostPort);
+    if (!Number.isFinite(base)) {
+      continue;
+    }
+    const key = `${entry.name.trim().toUpperCase().replace(/-/g, '_')}_PUBLIC_PORT`;
+    envVars[key] = String(devIdNum > 0 ? base + devIdNum * 100 : base);
+  }
+}
+
 /**
  * Rewrite first line for the matched *_PUBLIC_PORT after interpolateEnvVars (early kv pass may have wrong value).
  * @param {string} resolved
@@ -111,6 +146,7 @@ function rewriteDockerManifestPublicPortEnvLine(resolved, envVars, appDoc) {
 module.exports = {
   findDockerHostKeyForAppKey,
   publicPortKeyForAppKey,
+  mergeAdditionalPublishedPorts,
   mergeDockerManifestPublishedPort,
   rewriteDockerManifestPublicPortEnvLine
 };

package/lib/utils/error-formatters/validation-errors.js

@@ -11,6 +11,26 @@ const { formatBlockingError } = require('../cli-test-layout-chalk');
 
 const chalk = require('chalk');
 
+/**
+ * Resolves legacy application lookup codes without replacing API explanations.
+ * @param {Object|string} error - Validation error entry
+ * @returns {{message: string, applicationNotFound: boolean}} Display information
+ */
+function getValidationMessage(error) {
+  const message = typeof error === 'string' ? error : error.msg || error.message;
+  const code = typeof error === 'object' ? error.code : undefined;
+  const applicationNotFound = message === 'APPLICATION_NOT_FOUND' || code === 'APPLICATION_NOT_FOUND';
+  if (applicationNotFound && (!message || message === 'APPLICATION_NOT_FOUND')) {
+    return {
+      message: 'The controller could not find the application. ' +
+        'Check that it is registered on the selected controller and that its application key matches. ' +
+        '(Error code: APPLICATION_NOT_FOUND)',
+      applicationNotFound
+    };
+  }
+  return { message: message || 'Invalid value', applicationNotFound };
+}
+
 /**
  * Adds main error message to lines array
  * @param {Array<string>} lines - Lines array to append to
@@ -52,7 +72,7 @@ function addValidationErrorsList(lines, errors) {
   lines.push(chalk.yellow('Validation errors:'));
   errors.forEach(err => {
     const field = err.field || err.path || err.loc?.join('.') || 'validation';
-    const message = err.msg || err.message || 'Invalid value';
+    const { message } = getValidationMessage(err);
     const value = err.value !== undefined ? ` (value: ${JSON.stringify(err.value)})` : '';
     if (field === 'validation' || field === 'unknown') {
       lines.push(chalk.gray(`  • ${message}${value}`));
@@ -91,10 +111,10 @@ function addConfigurationErrors(lines, configuration) {
 /**
  * Adds actionable guidance tips to lines
  * @param {Array<string>} lines - Lines array to append to
- * @param {boolean} hasErrors - Whether there are validation errors
+ * @param {Array<Object|string>} errors - Validation errors
  */
-function addValidationGuidance(lines, hasErrors) {
-  if (!hasErrors) {
+function addValidationGuidance(lines, errors) {
+  if (!Array.isArray(errors) || !errors.some(err => !getValidationMessage(err).applicationNotFound)) {
     return;
   }
   lines.push(chalk.gray('Tips:'));
@@ -117,7 +137,7 @@ function formatValidationError(errorData) {
   addValidationErrorMessage(lines, errorData);
   addValidationErrorsList(lines, errorData.errors);
   addConfigurationErrors(lines, errorData.configuration);
-  addValidationGuidance(lines, errorData.errors && errorData.errors.length > 0);
+  addValidationGuidance(lines, errorData.errors);
 
   if (errorData.instance) {
     lines.push(chalk.gray(`Endpoint: ${errorData.instance}`));

package/lib/utils/help-builder.js

@@ -17,6 +17,7 @@ const { Help } = require('commander');
  * @type {Array<{ name: string, commands: Array<{ name: string, term?: string }> }>}
  */
 const CATEGORIES = [
+  { name: 'Getting Started', commands: [{ name: 'help', term: 'help [command]' }, { name: 'onboarding' }] },
   {
     name: 'Infrastructure (Local Development)',
     commands: [
@@ -209,9 +210,9 @@ function formatCommandCategories(helper, program) {
     for (const { term, desc: d } of lines) out.push(`  ${term.padEnd(pad)}${d}`);
     out.push('');
   }
-  out.push('Help:');
-  out.push(`  ${'help [command]'.padEnd(pad)}display help for command`);
-  out.push('');
+  if (!program.commands.some(command => command.name() === 'help')) {
+    out.push('Help:', `  ${'help [command]'.padEnd(pad)}display help for command`, '');
+  }
   out.push(`  ${''.padEnd(pad)}Tip: aifabrix <command> --help for flags and examples`);
   out.push('');
   return out;

package/lib/utils/platform-resolution.js

@@ -0,0 +1,226 @@
+/**
+ * Platform and environment configuration resolution (plan 200.0).
+ *
+ * The deployment's Azure resource group is matched against the manifest `platforms` list, yielding
+ * `{platform}` and `{platform.name}`. Platform values expand from those, then the matching
+ * `environments` entry overrides by name. The result is one flat set of names that `env.template`
+ * references as `{NAME}`.
+ *
+ * Pure by contract: manifest + resource group + environment key in, resolved set out. No
+ * filesystem, no Azure, no network — the same function must be implementable in Miso and produce
+ * identical output for the shared test vectors.
+ *
+ * @fileoverview Resource-group driven configuration resolution
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+/** Local Docker has no resource group; every local run resolves as this platform. */
+const LOCAL_PLATFORM = 'dev';
+/** Capture for `*` in a resource pattern: one group-name segment. */
+const NAME_CAPTURE = '[A-Za-z0-9][A-Za-z0-9-]*';
+const NAME_WILDCARD = '*';
+
+function escapeLiteral(text) {
+  return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * Compiles a `resource` pattern into a matcher.
+ * `{platform}` matches one of `options`; `*` captures a name segment.
+ * @param {Object} entry - Platform entry
+ * @returns {{ regex: RegExp, order: string[] }} Matcher and the capture order
+ */
+function compileResourcePattern(entry) {
+  const order = [];
+  let source = '';
+  const pattern = String(entry.resource || '');
+  const tokens = pattern.split(/(\{platform\}|\*)/);
+  for (const token of tokens) {
+    if (token === '{platform}') {
+      const options = Array.isArray(entry.options) ? entry.options : [];
+      source += `(${options.map(escapeLiteral).join('|')})`;
+      order.push('platform');
+    } else if (token === NAME_WILDCARD) {
+      source += `(${NAME_CAPTURE})`;
+      order.push('name');
+    } else if (token) {
+      source += escapeLiteral(token);
+    }
+  }
+  return { regex: new RegExp(`^${source}$`), order };
+}
+
+/**
+ * @param {Object} entry - Platform entry
+ * @throws {Error} When the entry cannot yield a platform
+ */
+function assertPlatformDeclaration(entry) {
+  const hasToken = String(entry.resource || '').includes('{platform}');
+  const hasOptions = Array.isArray(entry.options) && entry.options.length > 0;
+  if (hasToken && !hasOptions) {
+    throw new Error(`Platform "${entry.resource}" uses {platform} but declares no options`);
+  }
+  if (!hasToken && !entry.platform) {
+    throw new Error(`Platform "${entry.resource}" has no {platform} token, so it must declare platform:`);
+  }
+  if (hasToken && entry.platform) {
+    throw new Error(`Platform "${entry.resource}" declares both {platform} and platform:; use one`);
+  }
+}
+
+function matchEntry(entry, resourceGroup) {
+  assertPlatformDeclaration(entry);
+  const { regex, order } = compileResourcePattern(entry);
+  const found = regex.exec(resourceGroup);
+  if (!found) return null;
+  const captured = {};
+  order.forEach((key, index) => {
+    captured[key] = found[index + 1];
+  });
+  const platform = captured.platform || entry.platform;
+  const name = entry.name === NAME_WILDCARD ? captured.name : entry.name;
+  if (!name) {
+    throw new Error(`Platform "${entry.resource}" uses name: * but the pattern captures no name segment`);
+  }
+  return { entry, platform, name };
+}
+
+/**
+ * Matches a resource group against the manifest platforms.
+ * @param {Array} platforms - Manifest `platforms`
+ * @param {string} resourceGroup - Target Azure resource group
+ * @returns {{ entry: Object, platform: string, name: string }} The single match
+ * @throws {Error} On no match or more than one match
+ */
+function matchPlatform(platforms, resourceGroup) {
+  const entries = Array.isArray(platforms) ? platforms : [];
+  const group = String(resourceGroup || '').trim();
+  if (!group) {
+    throw new Error('A resource group is required to resolve a platform');
+  }
+  const matches = entries.map(entry => matchEntry(entry, group)).filter(Boolean);
+  if (matches.length === 0) {
+    const tried = entries.map(entry => `"${entry.resource}"`).join(', ') || '(none declared)';
+    throw new Error(`Resource group "${group}" matches no platform. Patterns tried: ${tried}`);
+  }
+  if (matches.length > 1) {
+    const ambiguous = matches.map(match => `"${match.entry.resource}"`).join(', ');
+    throw new Error(`Resource group "${group}" matches more than one platform: ${ambiguous}. Make the patterns exclusive.`);
+  }
+  return matches[0];
+}
+
+/**
+ * Expands `{platform}`, `{platform.name}` and `{resourceGroup}` in a value.
+ * @param {string} value - Raw value
+ * @param {Object} context - `platform`, `name`, `resourceGroup`
+ * @returns {string}
+ * @throws {Error} On an unknown token
+ */
+function expandPlatformTokens(value, context) {
+  const text = value === undefined || value === null ? '' : String(value);
+  return text.replace(/\{([a-zA-Z][a-zA-Z.]*)\}/g, (match, token) => {
+    if (token === 'platform') return context.platform;
+    if (token === 'platform.name') return context.name;
+    if (token === 'resourceGroup') return context.resourceGroup;
+    throw new Error(`Unsupported token ${match}; use {platform}, {platform.name} or {resourceGroup}`);
+  });
+}
+
+function applyItems(target, items, context) {
+  for (const item of Array.isArray(items) ? items : []) {
+    target.set(item.name, expandPlatformTokens(item.value, context));
+  }
+}
+
+/**
+ * Local runs have no resource group, but still need platform values. The first entry that can
+ * produce the local platform supplies them; an `environments` entry still overrides by name.
+ * A `*` name cannot be captured without a group, so it resolves to ''.
+ * @param {Array} platforms - Manifest platforms
+ * @returns {{ entry: Object, platform: string, name: string }|null}
+ */
+function matchLocalPlatform(platforms) {
+  const entry = platforms.find(item =>
+    item.platform === LOCAL_PLATFORM ||
+    (Array.isArray(item.options) && item.options.includes(LOCAL_PLATFORM)));
+  if (!entry) return null;
+  return { entry, platform: LOCAL_PLATFORM, name: entry.name === NAME_WILDCARD ? '' : entry.name };
+}
+
+/**
+ * @param {Object} manifest - Application manifest
+ * @param {string} resourceGroup - Target resource group ('' for local Docker)
+ * @returns {{ entry: Object, platform: string, name: string }|null}
+ */
+function matchIfDeclared(manifest, resourceGroup, allowLocalPlatform) {
+  const platforms = manifest && Array.isArray(manifest.platforms) ? manifest.platforms : [];
+  if (platforms.length === 0) return null;
+  if (!resourceGroup) return allowLocalPlatform ? matchLocalPlatform(platforms) : null;
+  return matchPlatform(platforms, resourceGroup);
+}
+
+function environmentEntry(manifest, environment) {
+  const entries = manifest && Array.isArray(manifest.environments) ? manifest.environments : [];
+  return entries.find(item => item.environment === environment) || null;
+}
+
+function applyBuiltIns(values, context, environment) {
+  const builtIns = [
+    // PLATFORM is omitted when nothing determined it, so a consumer fails closed on {PLATFORM}
+    // rather than receiving a guess.
+    ...(context.platform ? [['PLATFORM', context.platform]] : []),
+    ['PLATFORM_NAME', context.name],
+    ['RESOURCE_GROUP', context.resourceGroup],
+    ['ENVIRONMENT', environment]
+  ];
+  // Built-ins never overwrite an authored name of the same spelling.
+  for (const [key, value] of builtIns) {
+    if (!values.has(key)) values.set(key, value);
+  }
+}
+
+/**
+ * Resolves the configuration set for one deployment.
+ * @param {Object} manifest - Application manifest with optional `platforms` / `environments`
+ * @param {Object} target - `resourceGroup` (omitted for local Docker), `environment`, and
+ *   `allowLocalPlatform` (default true). A caller that is not a local run — the Controller, which
+ *   knows the environment but may not know the group — passes false so a missing group resolves no
+ *   platform at all instead of silently claiming `dev`.
+ * @returns {{ platform: string|null, name: string|null, resourceGroup: string|null, values: Object }}
+ */
+function resolveConfiguration(manifest, target = {}) {
+  const resourceGroup = target.resourceGroup ? String(target.resourceGroup).trim() : '';
+  const environment = target.environment ? String(target.environment).trim() : '';
+  const allowLocalPlatform = target.allowLocalPlatform !== false;
+  const matched = matchIfDeclared(manifest, resourceGroup, allowLocalPlatform);
+  const localPlatform = allowLocalPlatform ? LOCAL_PLATFORM : '';
+  const context = {
+    platform: matched ? matched.platform : localPlatform,
+    name: matched ? matched.name : '',
+    resourceGroup
+  };
+
+  const values = new Map();
+  if (matched) applyItems(values, matched.entry.configuration, context);
+  const envEntry = environmentEntry(manifest, environment);
+  if (envEntry) applyItems(values, envEntry.configuration, context);
+  applyBuiltIns(values, context, environment);
+
+  return {
+    platform: context.platform || null,
+    name: matched && matched.name ? matched.name : null,
+    resourceGroup: resourceGroup || null,
+    values: Object.fromEntries(values)
+  };
+}
+
+module.exports = {
+  LOCAL_PLATFORM,
+  matchPlatform,
+  expandPlatformTokens,
+  resolveConfiguration
+};

package/lib/utils/resolve-docker-image-ref.js

@@ -148,16 +148,21 @@ function qualifyRepository(registry, repository) {
 }
 
 /**
- * Deployment/registration image reference (`registry/name:tag`) using the shared precedence.
+ * Deployment/registration image reference (`registry/name:tag`).
+ *
+ * Deliberately ignores the installation registry (`dev set-registry`): a generated manifest is a
+ * committed artifact shared by the team, so it must carry the application's own `image.registry`,
+ * not one developer's local default. `push` applies the installation registry when it publishes,
+ * and an explicit `options.registry` still wins here for CI that targets another registry.
  * @param {Object} variables - Application manifest
  * @param {string} fallbackName - Name when the manifest has no image name or app key
- * @param {Object} [options] - Same options as {@link resolveEffectiveRegistry}
+ * @param {Object} [options] - `registry` (explicit override only)
  * @returns {string}
  */
 function buildManifestImageReference(variables, fallbackName, options = {}) {
   const imageName = variables?.image?.name || variables?.app?.key || fallbackName;
   const tag = variables?.image?.tag || 'latest';
-  const { registry } = resolveEffectiveRegistry(variables, options);
+  const { registry } = resolveEffectiveRegistry(variables, { ...options, installationRegistry: '' });
   return `${qualifyRepository(registry, imageName)}:${tag}`;
 }
 

package/lib/utils/token-manager.js

@@ -11,6 +11,7 @@
 
 const config = require('../core/config');
 const logger = require('./logger');
+const { maskSensitiveData } = require('./log-redaction');
 const {
   refreshClientToken,
   refreshDeviceToken
@@ -99,55 +100,47 @@ async function getOrRefreshClientToken(environment, appName, controllerUrl) {
  * @returns {Promise<{token: string, controller: string}|null>} Token and controller URL, or null if not available
  */
 async function getOrRefreshDeviceToken(controllerUrl) {
-  // Try to get existing token
   const tokenInfo = await getDeviceToken(controllerUrl);
-
-  if (!tokenInfo) {
-    return null;
+  if (!tokenInfo) return null;
+  if (reusableDeviceToken(tokenInfo) && !shouldRefreshToken(tokenInfo.expiresAt)) {
+    return reusableDeviceToken(tokenInfo);
   }
-
-  // Check if token should be refreshed proactively (within 15 minutes of expiry)
-  // This ensures we refresh before Keycloak's SSO Session Idle timeout (30 minutes)
-  const needsRefresh = shouldRefreshToken(tokenInfo.expiresAt);
-
-  if (!needsRefresh) {
-    // Token is valid and doesn't need refresh yet
-    return {
-      token: tokenInfo.token,
-      controller: tokenInfo.controller
-    };
-  }
-
-  // Token needs refresh (expired or within 15 minutes of expiry)
-  // Try to refresh if refresh token exists
   if (!tokenInfo.refreshToken) {
-    const { isSetupPlatformFlow } = require('../commands/setup-run-context');
-    if (!isSetupPlatformFlow()) {
-      logger.warn(
-        'Access token expired and no refresh token available. Please login again using: aifabrix login'
-      );
+    const usable = reusableDeviceToken(tokenInfo);
+    if (!usable) {
+      warnRefreshFailureOnce(controllerUrl, 'No usable access token and no refresh token available. Please login again using: aifabrix login');
     }
-    return null;
+    return usable;
   }
-
   try {
     const refreshed = await refreshDeviceToken(controllerUrl, tokenInfo.refreshToken);
-    return {
-      token: refreshed.token,
-      controller: controllerUrl
-    };
+    return { token: refreshed.token, controller: controllerUrl };
   } catch (error) {
-    // Refresh failed - check if it's a refresh token expiry
-    const errorMessage = error.message || String(error);
-    if (errorMessage.includes('Refresh token has expired')) {
-      warnRefreshTokenExpiredOnce(controllerUrl, errorMessage);
+    let message = error.message || String(error);
+    for (const secret of [tokenInfo.token, tokenInfo.refreshToken]) {
+      if (secret) message = message.split(secret).join('***');
+    }
+    message = maskSensitiveData(message);
+    if (message.includes('Refresh token has expired')) {
+      warnRefreshTokenExpiredOnce(controllerUrl, message);
     } else {
-      warnRefreshFailureOnce(controllerUrl, errorMessage);
+      warnRefreshFailureOnce(controllerUrl, message);
     }
-    return null;
+    return reusableDeviceToken(tokenInfo);
   }
 }
 
+/**
+ * Reuse only a token whose actual expiry is known and still in the future.
+ * @param {Object} tokenInfo - Stored device token
+ * @returns {Object|null} Usable token, without refresh credentials
+ */
+function reusableDeviceToken(tokenInfo) {
+  const expiry = typeof tokenInfo.expiresAt === 'string' ? Date.parse(tokenInfo.expiresAt) : NaN;
+  return tokenInfo.token && Number.isFinite(expiry) && expiry > Date.now()
+    ? { token: tokenInfo.token, controller: tokenInfo.controller } : null;
+}
+
 /**
  * Validates deployment auth parameters
  * @function validateDeploymentAuthParams

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aifabrix/builder",
-  "version": "2.58.0",
+  "version": "2.60.0",
   "description": "AI Fabrix Builder — CLI and developer scripts (pnpm + af)",
   "main": "lib/index.js",
   "bin": {
@@ -131,8 +131,9 @@
     }
   },
   "dependencies": {
-    "@aifabrix/miso-client": "4.22.4",
-    "adm-zip": "^0.6.0",
+    "@aifabrix/miso-client": "4.23.1",
+    "@azure/identity": "4.11.1",
+    "adm-zip": "^0.6.1",
     "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1",
     "axios": "^1.18.1",

package/templates/README.md

@@ -23,9 +23,10 @@ Application templates are folder-based and located under `templates/applications
 | `aifabrix-miso/builder/miso-controller/` (`env.template`, `rbac.yaml`, `application.yaml`) | `templates/applications/miso-controller/` |
 | `aifabrix-miso/builder/keycloak/` (`env.template`, `application.yaml`, `Dockerfile`, `cimd-lenient-parse/`) | `templates/applications/keycloak/` |
 | `aifabrix-miso/infrastructure/marketplace/` (`main.json`, `createUiDefinition.json`) | `templates/marketplace/` |
+| `aifabrix-miso/packages/miso-controller/configs/infra.parameter.yaml` | `lib/schema/infra.parameter.yaml` |
 | `aifabrix-dataplane/builder/dataplane/` (`env.template`, `rbac.yaml`, `application.yaml`) | `templates/applications/dataplane/` |
 
-**Schema master (dataplane):** Also copies dataplane `app/schemas/json/` core integration schemas + `type/*` and `configs/deployment-rules.yaml` into `lib/schema/` (same contract as dataplane `make sync-json`). Do not hand-edit those mirrors — edit dataplane SSOT, then sync. Builder-owned schemas in `lib/schema/` (wizard, infra, etc.) are left alone.
+**Schema master (dataplane):** Also copies dataplane `app/schemas/json/` core integration schemas + `type/*` and `configs/deployment-rules.yaml` into `lib/schema/` (same contract as dataplane `make sync-json`). Do not hand-edit those mirrors — edit dataplane SSOT, then sync. `lib/schema/infra.parameter.yaml` is the Miso catalog mirror above; other Builder-owned schemas in `lib/schema/` (wizard and the rest) are left alone.
 
 Overrides: `AIFABRIX_MISO_SRC`, `AIFABRIX_DATAPLANE_SRC` / `AIFABRIX_DATAPLANE_ROOT` (repo roots). Install with `aifabrix up-platform` / `up-builder-api` — do not hand-edit the template copies as primary.
 

package/templates/agent-kit/agent-kit.yaml

@@ -1,5 +1,5 @@
 schemaVersion: "1"
-kitVersion: "1.1.2"
+kitVersion: "1.2.0"
 minimumBuilderVersion: "2.54.2"
 skills:
   - aifabrix-plan
@@ -26,6 +26,9 @@ managed:
   - source: workspace/README.md
     target: README.md
     mode: if-missing
+  - source: workspace/BUILDER_IMPROVEMENT_FINDINGS.md
+    target: BUILDER_IMPROVEMENT_FINDINGS.md
+    mode: if-missing
 optional:
   - source: adapters/cursor/commands
     target: .cursor/commands

package/templates/agent-kit/instructions/AGENTKIT.md

@@ -2,6 +2,35 @@
 
 Builder-owned. `aifabrix agent-kit update` refreshes this file. If workspace `README.md` is missing, install/update creates it. An existing README is never overwritten.
 
+## Onboard
+
+On an organisation-managed SSH workspace with a provisioned `config.yaml`:
+
+```bash
+af onboarding
+af onboarding --coding claude   # or codex or cursor for this run
+```
+
+For Claude, onboarding starts or reuses a detached tmux session and prints
+its attach command. For Codex or Cursor, open the printed workspace in the
+selected coding client over SSH, then say “Hi”. `--coding` selects a platform
+for one run without changing the provisioned default.
+The agent reads this workspace's `AGENTS.md` and `README.md`, checks which
+packages already exist, and guides you to a first delivery task.
+
+On a Linux or macOS terminal with Builder, Git, and tmux:
+
+```bash
+aifabrix agent-kit setup https://controller.example.com
+```
+
+This prepares a local workspace under the configured AI Fabrix work directory and starts
+Codex. Select Claude with `--code claude`. GitHub is optional: add `--repo owner/name`
+to reuse a matching local checkout, clone a remote, or create a private repository.
+The repository name becomes the folder name; unresolved access stops safely.
+Setup preserves existing agent permissions. Change environment afterward with
+`aifabrix auth --set-environment <environment>`.
+
 ## Install
 
 From this git repository (Builder CLI on PATH):
@@ -57,13 +86,18 @@ curl -fsSL https://claude.ai/install.sh | bash
 claude auth login
 ```
 
-**Run in tmux** from this workspace so closing the terminal does not kill Claude. The command enables Remote Control and this workspace's Claude auto-approval by default. Remote Control is the **same** session on this PC, [claude.ai/code](https://claude.ai/code), and the Claude mobile app (Code). That is not `claude --cloud` (a separate cloud VM). Claude `--tmux` is for worktrees only.
+**Optional terminal session in tmux:** run from this workspace so closing the
+terminal does not kill Claude. The command enables Remote Control and this
+workspace's Claude auto-approval by default. Remote Control is the **same**
+session on this PC, [claude.ai/code](https://claude.ai/code), and the Claude
+mobile app (Code). That is not `claude --cloud` (a separate cloud VM). Claude
+`--tmux` is for worktrees only.
 
 ```bash
 aifabrix agent-kit start claude
 ```
 
-tmux session name defaults to this folder. Remote Control name is `hostname-user-folder` (for example `builder01-dev03-aifabrix-docs`). Override with `--name`; opt out with `--no-remote-control` and/or `--skip-approve-all`. Detach: `Ctrl-b` then `d`. Reattach: `tmux attach -t <folder>`. Use `aifabrix agent-kit list` and `agent-kit kill <folder>` to manage sessions. Same account on phone and PC (`claude auth login`, Pro/Max/Team — not an API key). On the phone: Claude app → **Code**. Skills: `/aifabrix-plan` (and the other `/aifabrix-*` names). First `claude` must run inside this workspace, not your home directory. Full notes: `.agents/skills/shared/hosts.md`.
+tmux session name defaults to this folder. Remote Control name is `hostname-user-folder` (for example `devhost-alice-acme-workspace`). Override with `--name`; opt out with `--no-remote-control` and/or `--skip-approve-all`. Detach: `Ctrl-b` then `d`. Reattach: `tmux attach -t <folder>`. Use `aifabrix agent-kit list` and `agent-kit kill <folder>` to manage sessions. Same account on phone and PC (`claude auth login`, Pro/Max/Team — not an API key). On the phone: Claude app → **Code**. Skills: `/aifabrix-plan` (and the other `/aifabrix-*` names). First `claude` must run inside this workspace, not your home directory. Full notes: `.agents/skills/shared/hosts.md`.
 {{/if}}
 {{#if codex}}
 
@@ -76,7 +110,10 @@ npm install -g @openai/codex
 codex login
 ```
 
-**Run in tmux** from this workspace so the session stays if you close the terminal. The command starts native Codex Remote Control and writes this workspace's Codex auto-approval by default:
+**Optional terminal session in tmux:** run from this workspace so a terminal
+Codex session stays after SSH disconnects. This session is separate from a
+Codex app chat opened over SSH. The command requests native Codex Remote
+Control and writes workspace auto-approval by default:
 
 ```bash
 aifabrix agent-kit start codex

package/templates/agent-kit/instructions/root.AGENTS.md

@@ -14,6 +14,46 @@ Do not edit platform product source (`aifabrix-dataplane`, `aifabrix-miso`, `aif
 
 Vendor limits, tenant ids, credentials, PII stance, partitions, and the designated mutation subject live only in `integration/<systemKey>/README.md`.
 
+`agent-kit update` rewrites `.agents/skills/**`, `AGENTKIT.md`, and managed sections; `--force` discards local edits. Do not edit them: file gaps in `BUILDER_IMPROVEMENT_FINDINGS.md`, sanitized. Never weaken a gate to clear one. Routing: `.agents/skills/shared/feedback.md`.
+
+## First greeting
+
+On a first “Hi”, start with the business problem in plain language. Explain
+that their process, people, outcome, systems, and a real example become a plan,
+Connected Systems, a Role Assistant, and proof. Show these skills in a table:
+
+| Skill | How it helps |
+| --- | --- |
+| aifabrix-plan | Turn the business context or spec into a plan; ask about gaps |
+| aifabrix-connected-system | Validate, build, test, and publish needed systems |
+| aifabrix-role-assistant | Create or update a catalog role using published systems |
+| aifabrix-prove | Test a real business example and record the result |
+
+Render skill names with `$` in Codex and `/` in Claude Code or Cursor. Do not
+run CLI commands or lead with inventory, sign-in, or gates on this first reply.
+
+Ask one opening question: what business process or role should we help, and
+what should improve? Invite a spec, API document, sample payload, or example
+workflow if they have one. Say a plain-language description is enough to start;
+missing details will become explicit questions. Keep the greeting brief.
+
+## After the business context
+
+Before planning or using online Builder commands, check the workspace and
+sign-in. Run `aifabrix auth status`; if signed out, follow
+`.agents/skills/shared/login.md` and ask for the Controller URL only if needed.
+Read `README.md` and list package folder names under `integration/` and
+`role-assistant/`; do not open package data or secrets for discovery. If signed
+in, run `aifabrix list` to find remote systems. If listing fails, report the
+failure; do not infer that there are no systems. Distinguish local packages
+from remote entries, and published Connected Systems from drafts, Role
+Assistants, and Enterprise Knowledge. Never print tokens.
+
+Then suggest the relevant skill from the first table and explain its gate.
+Summarize sign-in and discovery only as needed for the chosen work; give at
+most two relevant remote examples unless asked for the
+full list. Do not print email, IDs, URLs, or versions in a routine status.
+
 ## Secrets
 
 Use `kv://` and `aifabrix secret`. Never store, print, ask for, or commit secret values.
@@ -27,7 +67,8 @@ Do not collapse these into a generic success boolean. Do not start the next life
 
 ## Coding hosts
 
-Cursor, Claude Code, and Codex — local machine or SSH (tmux, Claude Remote Control): `.agents/skills/shared/hosts.md`.
+Cursor, Claude Code, and Codex — local or remote SSH projects, with optional
+tmux terminal sessions: `.agents/skills/shared/hosts.md`.
 Install and sign-in: `AGENTKIT.md`. Builder CLI login from chat: `.agents/skills/shared/login.md`.
 
 ## Docs