@ours.network/install 1.2.1-nightly.42 → 1.2.1-nightly.43

package/lib/server-onboarding.mjs

@@ -5,6 +5,7 @@ import { join, resolve, isAbsolute } from 'node:path';
 import { randomUUID } from 'node:crypto';
 import { installationPaths } from './plan.mjs';
 import { validateHostProfile } from './target.mjs';
+import { isPluginOnly, PLUGIN_ONLY_INTEGRATIONS } from './product.mjs';
 /** Read by Fleet beside the profile credential; bound to one server installation. */
 export const NOTIFICATIONS_PRODUCER_FILE = 'notifications-producer.json';
 
@@ -23,6 +24,17 @@ function privatePath(path, directory = false) {
   }
   return stat;
 }
+/** True only when this server answers the saved credential with 401/403; unreachable is not proof. */
+export async function retainedCredentialRefused(profile, { fetchImpl = fetch, timeoutMs = 5000 } = {}) {
+  let token;
+  try { token = readFileSync(profile.credentialPath, 'utf8').trim(); } catch { return false; }
+  if (!token) return false;
+  try {
+    const response = await fetchImpl(`${profile.endpoint}/version`, { redirect: 'error', signal: AbortSignal.timeout(timeoutMs), headers: { 'x-ours-api-token': token } });
+    return response.status === 401 || response.status === 403;
+  } catch { return false; }
+}
+
 function validateRecord(record) {
   if (!record || !['packages', 'docker'].includes(record.mode) || typeof record.root !== 'string'
       || !isAbsolute(record.root) || resolve(record.root) !== record.root
@@ -213,12 +225,14 @@ else { await request('identity/profile', selection.human); process.stdout.write(
       validateRecord(record);
       if (!Array.isArray(integrations) || new Set(integrations).size !== integrations.length
           || integrations.some(name => !['codex', 'claude-code', 'fleet'].includes(name))) throw new Error('Client integrations must select codex, claude-code and/or fleet');
+      if (isPluginOnly(record) && integrations.some(name => !PLUGIN_ONLY_INTEGRATIONS.includes(name))) throw new Error('Collaboration tools connect Claude Code and Codex; Fleet is part of the complete workspace');
       if (fleetSettingsPath !== undefined) {
         if (typeof fleetSettingsPath !== 'string' || !isAbsolute(fleetSettingsPath) || resolve(fleetSettingsPath) !== fleetSettingsPath) throw new Error('Fleet settings path must be absolute');
         const settings = JSON.parse(readFileSync(fleetSettingsPath, 'utf8'));
         if (!settings || typeof settings !== 'object' || Array.isArray(settings)) throw new Error('Fleet settings must be a JSON object');
       }
-      const serverUrl = record.gateway ? gatewayAddress(record).base : undefined;
+      // Plugin-only clients reach the daemon's own client prefix on the published loopback port.
+      const serverUrl = record.gateway ? gatewayAddress(record).base : isPluginOnly(record) ? `http://127.0.0.1:${record.port}` : undefined;
       const endpoint = serverUrl ? `${serverUrl}/daemon` : `http://127.0.0.1:${record.port}`;
       const current = effects.readManagedClientProfile();
       if (current && (current.endpoint !== endpoint || current.expectedInstanceId !== record.instanceId)) throw new Error('Managed client already selects another server; no credential was issued');
@@ -230,16 +244,20 @@ else { await request('identity/profile', selection.human); process.stdout.write(
       const published = join(root, 'issued-' + randomUUID());
       const credential = join(stage, 'credential');
       try {
-        if (!current) {
+        // After `server access-replace` the retained credential is refused by this
+        // same server; a repeat setup replaces it rather than keeping a dead one.
+        const replace = current && effects.credentialRefused ? await effects.credentialRefused(current) : false;
+        if (replace) effects.out?.('The saved client credential is no longer accepted by this server; issuing a replacement.');
+        if (!current || replace) {
           effects.out?.('Issuing a separate local client credential with the retained server authority.');
           try { await effects.serverAccess(record, 'access-issue', { output: credential }); }
           catch (cause) { throw new Error('Client credential issuance failed; existing profiles were retained', { cause }); }
         }
-        const retainedCredential = current?.credentialPath ?? credential;
+        const retainedCredential = current && !replace ? current.credentialPath : credential;
         const stat = privatePath(retainedCredential);
         if (stat.size > 4096 || !readFileSync(retainedCredential, 'utf8').trim()) throw new Error('Issued client credential is empty or invalid');
         const profile = {
-          ...validateHostProfile({ ...(serverUrl ? { serverUrl } : {}), endpoint, expectedInstanceId: record.instanceId, credentialPath: current?.credentialPath ?? join(published, 'credential') }),
+          ...validateHostProfile({ ...(serverUrl ? { serverUrl } : {}), endpoint, expectedInstanceId: record.instanceId, credentialPath: current && !replace ? current.credentialPath : join(published, 'credential') }),
           installer: { integrations: [...integrations], ...(fleetSettingsPath !== undefined ? { fleetSettingsPath } : {}) },
         };
         writeFileSync(join(stage, 'profile.json'), JSON.stringify(profile, null, 2) + '\n', { flag: 'wx', mode: 0o600 });

package/lib/setup-options.mjs

@@ -1,6 +1,7 @@
 import { hostname } from 'node:os';
 import { serverBase } from './gateway.mjs';
 import { join, resolve, isAbsolute, dirname } from 'node:path';
+import { PRODUCTS, PLUGIN_ONLY, PLUGIN_ONLY_INTEGRATIONS } from './product.mjs';
 
 const scopes = ['all', 'server', 'client'];
 const integrations = ['codex', 'claude-code', 'fleet'];
@@ -11,7 +12,7 @@ const valueFlags = new Map(Object.entries({
   '--config': 'config', '--sources': 'sources', '--migrate-from': 'migrateFrom', '--port': 'port', '--cowork-port': 'coworkPort', '--messenger-port': 'messengerPort',
 }));
 const boolFlags = new Map([['--compatible', 'compatible'], ['--dry-run', 'dryRun'], ['--migrate', 'migrate'], ['--disable-fleet-agents-setup', 'disableFleetAgentsSetup']]);
-const allowed = new Set([...valueFlags.values(), ...boolFlags.values(), 'interactive', 'explicitPorts']);
+const allowed = new Set([...valueFlags.values(), ...boolFlags.values(), 'interactive', 'explicitPorts', 'product']);
 const defaults = { port: 3050, coworkPort: 3052, messengerPort: 8420 };
 const paths = ['stateDir', 'config', 'sources', 'fleetSettingsPath', 'migrateFrom'];
 const nonempty = value => typeof value === 'string' && value.trim().length > 0 && !/[\x00-\x1f\x7f]/.test(value);
@@ -63,6 +64,20 @@ export function validateSetupOptions(input, { interactive = input?.interactive =
     if (options.disableFleetAgentsSetup) throw new Error('--fleet-task-workflow conflicts with --disable-fleet-agents-setup: no agents are configured by this run');
     options.fleetTaskWorkflowAgents = [...agents];
   }
+  if (options.product !== undefined) {
+    if (!PRODUCTS.includes(options.product)) throw new Error('Product must be workspace or plugin-only');
+    if (options.product === PLUGIN_ONLY) {
+      if (!server) throw new Error('--plugin-only installs the daemon on this computer; it cannot be combined with client scope');
+      if (options.mode !== undefined && !['docker'].includes(options.mode)) throw new Error('--plugin-only runs the daemon in Docker or Podman; native packages are not supported for it');
+      if (options.integrations?.some?.(name => !PLUGIN_ONLY_INTEGRATIONS.includes(name))) throw new Error('--plugin-only connects Claude Code and/or Codex; Fleet is part of the complete workspace');
+      for (const [key, flag] of [['fleetSettingsPath', '--fleet-settings'], ['fleetTaskWorkflowAgents', '--fleet-task-workflow'], ['disableFleetAgentsSetup', '--disable-fleet-agents-setup'],
+        ['name', '--name'], ['surname', '--surname'], ['migrateFrom', '--migrate-from'], ['serverUrl', '--server-url']]) {
+        if (options[key] !== undefined && options[key] !== false) throw new Error(`${flag} belongs to the complete workspace and cannot be combined with --plugin-only`);
+      }
+      if (options.explicitPorts?.some?.(key => key !== 'port')) throw new Error('--plugin-only uses one port; --cowork-port and --messenger-port do not apply');
+      options.mode ??= 'docker';
+    }
+  }
   const missing = [];
   if (server) for (const [key, flag] of [['mode', '--mode'], ['stateDir', '--state-dir'], ...(options.migrateFrom === undefined ? [['identityName', '--identity-name']] : [])]) if (!nonempty(options[key])) missing.push(flag);
   if (client && options.integrations === undefined) missing.push('--integrations (use none to skip)');
@@ -135,6 +150,10 @@ export function parseSetupArgs(argv, { home, validate = true } = {}) {
     if (!arg.startsWith('-')) { positional.push(arg); continue; }
     const equal = arg.indexOf('=');
     const flag = equal < 0 ? arg : arg.slice(0, equal);
+    if (flag === '--plugin-only') {
+      if (equal >= 0) throw new Error(`${flag} takes no value`);
+      put('product', PLUGIN_ONLY); continue;
+    }
     if (boolFlags.has(flag)) {
       if (equal >= 0) throw new Error(`${flag} takes no value`);
       put(boolFlags.get(flag), true); continue;

package/lib/setup.mjs

@@ -12,6 +12,9 @@ import { USAGE } from './usage.mjs';
 import { validateIdentityName } from './server-onboarding.mjs';
 import { validateFleetSettings } from './fleet-settings.mjs';
 import { installerFailure } from './diagnostics.mjs';
+import { productOf, isPluginOnly, serverRole, PRODUCT_LABELS, PLUGIN_ONLY_INTEGRATIONS } from './product.mjs';
+import { collectWelcome, customHarnessGuidance, KEEPS_YOUR_SETUP } from './welcome.mjs';
+import { runRemoval } from './removal.mjs';
 
 const maintenance = new Set(['status', 'start', 'stop', 'restart', 'uninstall', 'rebuild', 'gateway-enable', 'access-issue', 'access-replace', 'backup', 'restore', 'reset']);
 
@@ -58,6 +61,10 @@ export async function prepareSetupPlan(options, effects) {
     const value = effects.readJson(join(options.stateDir, 'installation.json'));
     if (value) {
       plan.existing = validateInstallation(value, options.stateDir);
+      // The kind of installation is retained exactly; it is never widened or narrowed implicitly.
+      if (options.product !== undefined && options.product !== productOf(plan.existing))
+        throw new InstallUsageError(`This folder contains ${PRODUCT_LABELS[productOf(plan.existing)].toLowerCase()}. It is kept as it is; nothing was changed. Use a separate empty folder for the other kind of installation, or remove this one first.`);
+      plan.product = productOf(plan.existing);
       if (options.containerEngine && options.containerEngine !== (plan.existing.containerEngine ?? 'docker')) throw new InstallUsageError('Container engine conflicts with retained installation');
       if (options.mode !== plan.existing.mode) throw new InstallUsageError('The selected mode conflicts with the retained installation; choose its existing mode or a separate empty directory');
       for (const key of ['port', 'coworkPort', 'messengerPort']) {
@@ -71,9 +78,14 @@ export async function prepareSetupPlan(options, effects) {
     } else if (options.operation === 'update') {
       throw new InstallUsageError('Update requires an existing installation.json; choose install for a new installation');
     }
+    plan.product ??= options.product ?? 'workspace';
+    if (isPluginOnly(plan.product) && plan.integrations?.some(name => !PLUGIN_ONLY_INTEGRATIONS.includes(name)))
+      throw new InstallUsageError('Collaboration tools connect Claude Code and/or Codex; Fleet is part of the complete workspace. Nothing was changed.');
     // Reject a local client already attached to another server before changing the server.
     const saved = options.scope === 'all' ? effects.readManagedClientProfile() : null;
-    if (saved && (!plan.existing || saved.expectedInstanceId !== plan.existing.instanceId || saved.endpoint !== (plan.existing?.gateway ? gatewayAddress(plan.existing).base + '/daemon' : `http://127.0.0.1:${plan.port}`))) {
+    const savedEndpoint = plan.existing?.gateway ? gatewayAddress(plan.existing).base + '/daemon'
+      : isPluginOnly(plan.product) ? `http://127.0.0.1:${plan.port}/daemon` : `http://127.0.0.1:${plan.port}`;
+    if (saved && (!plan.existing || saved.expectedInstanceId !== plan.existing.instanceId || saved.endpoint !== savedEndpoint)) {
       throw new InstallUsageError('This user already has clients attached to a different server; their saved connection was not changed');
     }
   } else {
@@ -91,7 +103,7 @@ export async function prepareSetupPlan(options, effects) {
       const running = await effects.serverLifecycle(plan.existing, 'status', ['daemon']);
       if (!running.includes('daemon')) throw new InstallUsageError('Full-stack update requires the selected daemon to be running for client verification. Start it first, or use server update to preserve its stopped state.');
     }
-    if (options.scope !== 'client') await effects.resolveSourcePolicy(plan.sourcePolicy, 'server');
+    if (options.scope !== 'client') await effects.resolveSourcePolicy(plan.sourcePolicy, serverRole(plan.product));
     if (options.scope !== 'server') await effects.resolveSourcePolicy(plan.sourcePolicy, 'client', clientPackageNames(options.integrations));
   }
   return plan;
@@ -112,7 +124,7 @@ export async function executeSetupPlan(plan, effects, { server = runServerComman
   let clientPolicy = plan.sourcePolicy;
   if (plan.scope !== 'client') {
     effects.out(heading(plan.operation === 'update' ? 'Server update and identity restoration' : 'Server installation'));
-    const result = await server({ ...plan, role: 'server', operation: plan.operation, sourcePolicy: plan.sourcePolicy }, effects);
+    const result = await server({ ...plan, product: plan.product === 'workspace' ? undefined : plan.product, role: 'server', operation: plan.operation, sourcePolicy: plan.sourcePolicy }, effects);
     if (result !== 0) return result;
     const record = validateInstallation(effects.readJson(join(plan.stateDir, 'installation.json')), plan.stateDir);
     if (plan.name && plan.surname && plan.operation === 'install') {
@@ -140,33 +152,64 @@ export async function executeSetupPlan(plan, effects, { server = runServerComman
       preset: true, nonInteractive: !plan.interactive }, effects);
     if (result !== 0) return result;
   }
-  if (plan.disableFleetAgentsSetup && plan.integrations?.includes('fleet')) effects.out(info('Fleet is installed. Run ours-fleet setup-tunnel with the expiring one-use payload from the App command; a compatible Fleet prints the QR and connection code automatically. Configure agents and models in the App after linking.'));
+  if (plan.retainFleetConfiguration && plan.integrations?.includes('fleet')) effects.out(info('Fleet was updated; your existing Fleet agents and their configuration were kept. Restart running agents when convenient: ours-fleet restart'));
+  else if (plan.disableFleetAgentsSetup && plan.integrations?.includes('fleet')) effects.out(info('Fleet is installed. Run ours-fleet setup-tunnel with the expiring one-use payload from the App command; a compatible Fleet prints the QR and connection code automatically. Configure agents and models in the App after linking.'));
   effects.out(ok(`Requested ${plan.operation} completed. Existing identities were retained.`));
   if (plan.integrations?.includes('fleet') && !plan.disableFleetAgentsSetup) effects.out(info('Fleet is configured but stopped. Review its settings, then run ours-fleet doctor, ours-fleet config and ours-fleet up.'));
+  if (isPluginOnly(plan.product) && plan.scope === 'all') {
+    effects.out(info('Collaboration tools are ready. Restart Claude Code and start a new Codex session so they load the Ours tools; then ask your agent to create its Ours identity.'));
+    effects.out(info(KEEPS_YOUR_SETUP));
+  }
+  if (plan.customHarness) {
+    const release = plan.sourcePolicy?.release?.packages?.['@ours.network/claude-code'];
+    if (release?.version) for (const line of customHarnessGuidance({ version: release.version, profilePath: join(effects.home, '.ours-client', 'profile.json'),
+      marketplace: preparedClaudeMarketplace(effects) })) effects.out(info(line));
+    else effects.out(warn('This installer release does not pin an Ours plugin version, so no instructions for another agent app can be given safely.'));
+  }
+  if (plan.operation === 'install' || plan.operation === 'update') effects.out(info('To remove Ours completely later, run: ours-install remove'));
   return 0;
 }
 
+/** The exact local Claude Code marketplace this run prepared, when Claude Code was selected. */
+function preparedClaudeMarketplace(effects) {
+  const root = join(effects.home, '.ours-client-install');
+  for (const name of effects.list?.(root) ?? []) {
+    const path = join(root, name, 'marketplaces', 'claude-code');
+    if (effects.exists?.(join(path, 'plugins', 'ours', 'bin', 'proxy.mjs'))) return path;
+  }
+  return null;
+}
+
 /** The sole executable entry: manual answers and CLI presets share one plan/executor. */
 export async function runSetup(argv, effects) {
   try {
     if (argv.includes('--help') || argv.includes('-h')) { effects.out(USAGE); return 0; }
     if (argv.length === 1 && ['--version', '-V'].includes(argv[0])) { effects.out(effects.version ?? 'unknown'); return 0; }
     if (argv[0] === 'server' && maintenance.has(argv[1])) return await runServerCommand(parseNetworkArgs(argv), effects);
+    if (argv[0] === 'remove' || argv[0] === 'uninstall') return await runRemoval(argv.slice(1), effects);
     if (!argv.length && effects.env?.OURS_ASSUME_YES) throw new InstallUsageError('OURS_ASSUME_YES cannot fill an interactive setup plan. Supply complete CLI presets for unattended installation.');
-    if (!argv.length) { effects.out(banner()); effects.out(heading('Interactive setup')); }
     let options;
-    if (argv.length) {
+    let extra = {};
+    const welcome = !argv.length || (argv.length === 1 && argv[0] === 'update' && effects.interactive && !effects.env?.OURS_ASSUME_YES);
+    if (welcome) {
+      effects.out(banner());
+      const choice = await collectWelcome(effects, { update: argv[0] === 'update' });
+      if (choice.action === 'cancel') { effects.out(info('Nothing was changed.')); return 0; }
+      if (choice.action === 'remove') return await runRemoval([], effects);
+      if (choice.action === 'setup') { options = choice.options; extra = { customHarness: choice.customHarness, retainFleetConfiguration: choice.retainFleetConfiguration }; }
+      else options = await collectSetupOptions(effects, { ...choice.presets });
+    } else if (argv.length) {
       const presets = parseSetupArgs(argv, { home: effects.home, validate: false });
       try { options = validateSetupOptions(presets, { interactive: false }); }
       catch (error) {
         if (!effects.interactive || effects.env?.OURS_ASSUME_YES || !/^Missing (required setup options|human profile option):/.test(error.message)) throw error;
         options = await collectSetupOptions(effects, presets);
       }
-    } else options = await collectSetupOptions(effects);
-    const plan = await prepareSetupPlan(options, effects);
+    }
+    const plan = { ...await prepareSetupPlan(options, effects), ...extra };
     return await executeSetupPlan(plan, effects);
   } catch (error) {
-    if (isCancel(error)) { effects.out(warn('Installation cancelled.')); return 130; }
+    if (isCancel(error) || error?.cancelled) { effects.out(warn(error?.cancelled ? error.message : 'Installation cancelled.')); return 130; }
     effects.out(warn(`ours-install: ${installerFailure(error, effects.env)}`));
     return 2;
   }

package/lib/usage.mjs

@@ -2,11 +2,21 @@
 export const USAGE = `ours-install — interactive setup with optional CLI presets.
 
   ours-install
-    Opens the console form. Choose all (server + clients), server, or client;
-    runtime, installation directory, identity, integrations and Fleet settings.
+    Asks what you would like to do: add collaboration tools to the agent apps
+    you already use, install the complete Ours workspace, connect to a workspace
+    on another computer, or another setup. When Ours is already installed it
+    offers Update (recommended), Repair, Remove or Cancel instead, keeping the
+    installation's product, runtime and connected apps. Your existing agent
+    configuration, skills, plugins and settings are kept.
     Full setup runs the server in Docker or Podman, which provide the gateway local clients need.
     Native mode is offered for server-only setup. Windows uses WSL.
 
+  Collaboration tools only (one Ours service in Docker, plugins for Claude Code and Codex):
+    ours-install --plugin-only --state-dir ~/.ours-install --identity-name "Your Name" --integrations claude-code,codex
+
+  Remove Ours completely (lists everything first; asks you to type "remove ours"):
+    ours-install remove [--state-dir PATH] [--dry-run]
+
   Install now, configure Fleet agents in the App after linking:
     ours-install --username alex --name Alex --surname Taylor --disable-fleet-agents-setup
     Remaining installation choices are prompted on a terminal. No enrollment credentials or expiry.
@@ -24,6 +34,8 @@ export const USAGE = `ours-install — interactive setup with optional CLI prese
   Update a retained installation, preserving its identities:
     ours-install all update --mode docker --state-dir /private/ours --identity-name "Your Name" --integrations codex,fleet --fleet-settings /private/fleet.json --compatible
 
+  --plugin-only             collaboration tools only: the daemon service and the Claude Code/Codex
+                            plugins; no workspace apps, Fleet, Telegram or gateway (Docker or Podman)
   --scope all|server|client   preset which parts to configure (default all)
   --action install|update    equivalent to the positional operation
   --mode docker|native      packages is also accepted for native mode

package/lib/welcome.mjs

@@ -0,0 +1,219 @@
+// The first screen of `ours-install` with no arguments.
+//
+// It starts from what the person wants, not from how Ours is built: add
+// collaboration tools to the agent apps they already use, install the complete
+// workspace, or connect to a workspace that already runs elsewhere. When Ours is
+// already here, it offers to update, repair or remove what is installed, and
+// keeps the kind of installation the person chose.
+//
+// This file only asks and explains. It returns the same validated setup options
+// the CLI presets produce (or a removal request), so every path runs the same
+// installer underneath.
+
+import { join } from 'node:path';
+import { validateInstallation } from './plan.mjs';
+import { productOf, isPluginOnly, PLUGIN_ONLY, PRODUCT_LABELS, PLUGIN_ONLY_INTEGRATIONS } from './product.mjs';
+import { validateSetupOptions, defaultHostname } from './setup-options.mjs';
+import { validateIdentityName } from './server-onboarding.mjs';
+import { heading, info } from './ui.mjs';
+
+export const KEEPS_YOUR_SETUP = 'Your existing agent configuration, skills, plugins and custom settings stay as they are. Ours adds its own tools next to them; it does not replace or reconfigure your setup.';
+
+export const WORKSPACE_BENEFITS = [
+  'The complete Ours workspace adds, on this computer:',
+  '  - Rooms: a room of agents for each task, where they work on it together',
+  '  - Invitations: bring in agents and people from outside, with their own identities',
+  '  - Tracking: follow tasks and every agent\'s progress in one place',
+  '  - Mobile: reach your agents from the Ours app on your phone',
+  '  - Persistent agents: define agents that keep running and remember their role',
+  '  - Orchestration: Claude Code, Codex and other agent apps and vendors working together',
+];
+
+export const TOOLS_SUMMARY = [
+  'Collaboration tools give the agent apps you already use their own secure Ours identity,',
+  'so they can message other agents and people, share files and be woken when mail arrives.',
+  'It runs one small background service in Docker or Podman on this computer — nothing else.',
+];
+
+/** Managed installations on this computer, in the default and ~/.ours* folders. */
+export function findInstallations(effects, extra = []) {
+  const home = effects.home;
+  const names = typeof effects.list === 'function' ? effects.list(home) ?? [] : [];
+  const roots = [...new Set([join(home, '.ours-install'), ...names.filter(n => n.startsWith('.ours')).map(n => join(home, n)), ...extra])];
+  const found = [];
+  for (const root of roots) {
+    const value = effects.readJson(join(root, 'installation.json'));
+    if (!value) continue;
+    try {
+      const record = validateInstallation(value, root);
+      const journal = record.legacyMigrationSource ? effects.readJson(join(root, 'legacy-migration.json')) : null;
+      found.push({ root, record, product: productOf(record),
+        pending: record.buildTransition ? record.buildTransition.operation : record.layoutConversion ? 'install'
+          : record.legacyMigrationSource && journal?.phase !== 'complete' ? 'install' : null });
+    } catch { found.push({ root, invalid: true }); }
+  }
+  return found;
+}
+
+function describe(item) {
+  if (item.invalid) return `An Ours folder that could not be read: ${item.root}`;
+  const engine = item.record.mode === 'packages' ? 'directly on this computer' : item.record.containerEngine === 'podman' ? 'in Podman' : 'in Docker';
+  return `${PRODUCT_LABELS[item.product]} — folder ${item.root}, running ${engine}`;
+}
+
+const defaultIdentity = effects => `${String(effects.username?.() ?? 'me').toLowerCase().replace(/[^a-z0-9-]/g, '-').replace(/^-+/, '').slice(0, 30) || 'me'}@${defaultHostname()}`;
+
+async function askIdentity(effects) {
+  effects.out('Choose the name other people and agents will see for you. Your agents get their own identities under it later.');
+  for (;;) {
+    const name = (await effects.askLine('Your name in Ours: ', defaultIdentity(effects))).trim();
+    try { validateIdentityName(name); return name; }
+    catch { effects.out('Use 1–64 characters without slashes or control characters.'); }
+  }
+}
+
+async function askFolder(effects) {
+  const recommended = join(effects.home, '.ours-install');
+  effects.out(`Ours keeps its service and your data in one folder. The recommended folder is ${recommended}.`);
+  const where = await effects.select('Where should Ours keep its data?', [
+    { value: 'recommended', label: `Use the recommended folder (${recommended})` },
+    { value: 'custom', label: 'Choose another folder' },
+  ], 'recommended');
+  return where === 'recommended' ? recommended : await effects.askLine('Folder for Ours: ', recommended);
+}
+
+async function askEngine(effects) {
+  let podman = false;
+  try { podman = (await effects.run('sh', ['-c', 'command -v podman'], { allowCodes: [1, 127] })).code === 0; } catch { podman = false; }
+  if (!podman) return {};
+  effects.out('Ours runs its service in containers. Docker is recommended; choose Podman if that is what you use.');
+  const engine = await effects.select('Which container app should run Ours?', [
+    { value: 'docker', label: 'Docker (recommended)' }, { value: 'podman', label: 'Podman' },
+  ], 'docker');
+  return engine === 'podman' ? { containerEngine: 'podman' } : {};
+}
+
+/** Collaboration tools for existing agent apps: the plugin-only installation. */
+async function collectTools(effects) {
+  effects.out(heading('Collaboration tools for your agent apps'));
+  for (const line of TOOLS_SUMMARY) effects.out(line);
+  effects.out(KEEPS_YOUR_SETUP);
+  const detected = typeof effects.detectHarnesses === 'function' ? await effects.detectHarnesses() : [];
+  const found = name => detected.some(item => item.name === name && item.status === 'ok');
+  const choices = [
+    ...PLUGIN_ONLY_INTEGRATIONS.filter(found).map(name => ({ value: name, label: name === 'claude-code' ? 'Claude Code (found on this computer)' : 'Codex (found on this computer)' })),
+    { value: 'custom', label: 'Another agent app — show me how to connect it' },
+  ];
+  const missing = PLUGIN_ONLY_INTEGRATIONS.filter(name => !found(name)).map(name => name === 'claude-code' ? 'Claude Code' : 'Codex');
+  effects.out(`Choose the agent apps that should get the Ours tools. Use Space to select and Enter to continue.${missing.length ? ` Not found on this computer: ${missing.join(' and ')} — install it first and run ours-install again to connect it.` : ''}`);
+  const selected = await effects.multiselect('Which agent apps should get the Ours tools?', choices, choices.filter(c => c.value !== 'custom').map(c => c.value));
+  const integrations = selected.filter(name => name !== 'custom');
+  const customHarness = selected.includes('custom');
+  if (!integrations.length && !customHarness) throw Object.assign(new Error('Setup cancelled; no agent app was selected and nothing was changed'), { cancelled: true });
+  const engine = await askEngine(effects);
+  const stateDir = await askFolder(effects);
+  const identityName = await askIdentity(effects);
+  const options = validateSetupOptions({ scope: 'all', operation: 'install', product: PLUGIN_ONLY, mode: 'docker', ...engine, stateDir, identityName, integrations, interactive: true, explicitPorts: [] }, { interactive: true });
+  effects.out(`Ready to install: collaboration tools for ${[...integrations.map(n => n === 'claude-code' ? 'Claude Code' : 'Codex'), ...(customHarness ? ['another agent app (instructions at the end)'] : [])].join(', ')}; data in ${stateDir}; your name: ${identityName}.`);
+  effects.out('Nothing is changed until you continue. You can remove everything later with: ours-install remove');
+  if (!await effects.ask('Install now?', true)) throw Object.assign(new Error('Setup cancelled; nothing was changed'), { cancelled: true });
+  return { action: 'setup', options, customHarness };
+}
+
+/** Update, repair or remove what is already installed. */
+async function collectExisting(effects, installations) {
+  effects.out(heading('Ours is already set up on this computer'));
+  for (const item of installations) effects.out(info(describe(item)));
+  const usable = installations.filter(item => !item.invalid);
+  let item = usable[0];
+  if (usable.length > 1) {
+    effects.out('Choose the installation to work with.');
+    const root = await effects.select('Which installation?', usable.map(i => ({ value: i.root, label: describe(i) })), usable[0].root);
+    item = usable.find(i => i.root === root);
+  }
+  if (!item) {
+    effects.out('Its record could not be read, so it is not changed automatically. You can remove Ours completely, which lists everything first.');
+    const next = await effects.select('What would you like to do?', [{ value: 'remove', label: 'Remove Ours from this computer' }, { value: 'cancel', label: 'Cancel' }], 'cancel');
+    return { action: next };
+  }
+  const saved = (() => { try { return effects.readManagedClientProfile?.() ?? null; } catch { return null; } })();
+  const clientBound = saved?.expectedInstanceId === item.record.instanceId;
+  if (item.pending) {
+    effects.out('An earlier update or setup step did not finish. Finishing it keeps your identities and data and repairs the installation.');
+  } else {
+    effects.out(`Update brings this ${item.product === PLUGIN_ONLY ? 'installation' : 'workspace'} to installer ${effects.version ?? 'this version'}, keeping your identities, data, connected agent apps and their settings. Repair runs setup again with the same choices. To switch between collaboration tools and the complete workspace, remove this installation first.`);
+  }
+  const action = await effects.select('What would you like to do?', [
+    ...(item.pending ? [{ value: item.pending, label: 'Finish the earlier update or setup (recommended)' }]
+      : [{ value: 'update', label: 'Update Ours (recommended)' }, { value: 'install', label: 'Repair: run setup again with the same choices' }]),
+    { value: 'remove', label: 'Remove Ours from this computer' },
+    { value: 'cancel', label: 'Cancel' },
+  ], item.pending ?? 'update');
+  if (action === 'remove' || action === 'cancel') return { action };
+  const record = item.record;
+  const product = productOf(record);
+  const integrations = clientBound ? (saved.installer?.integrations ?? []).filter(name => !isPluginOnly(product) || PLUGIN_ONLY_INTEGRATIONS.includes(name)) : undefined;
+  const fleetConfigured = integrations?.includes('fleet') && effects.readText?.(join(effects.home, 'fleet.yaml')) != null;
+  if (action === 'update') {
+    effects.out('An update keeps a recovery backup of your stored data before changing it. Newer releases are checked for compatibility, but older data cannot be guaranteed to work with every release automatically.');
+    if (!await effects.ask('Update now and keep a recovery backup?', true)) return { action: 'cancel' };
+  }
+  const options = {
+    scope: clientBound ? 'all' : 'server', operation: action, ...(product === PLUGIN_ONLY ? { product } : {}),
+    mode: record.mode, ...(record.containerEngine ? { containerEngine: record.containerEngine } : {}),
+    stateDir: item.root, identityName: record.messengerIdentity ?? defaultIdentity(effects),
+    ...(clientBound ? { integrations } : {}),
+    ...(action === 'update' ? { compatible: true } : {}),
+    ...(fleetConfigured ? { disableFleetAgentsSetup: true } : {}),
+    interactive: true, explicitPorts: [],
+  };
+  return { action: 'setup', options: validateSetupOptions(options, { interactive: true }), existing: item, retainFleetConfiguration: Boolean(fleetConfigured) };
+}
+
+/** The goal-first screen. Returns { action: 'setup' | 'remove' | 'cancel' | 'advanced', ... }. */
+export async function collectWelcome(effects) {
+  const installations = findInstallations(effects);
+  if (installations.length) return collectExisting(effects, installations);
+  effects.out(heading('Welcome to Ours'));
+  effects.out('Ours is where people and AI agents work together: each agent gets its own secure identity and can message, share files and coordinate with other agents and people.');
+  effects.out('Choose what you would like to set up. Collaboration tools add Ours to the agent apps you already use. The complete workspace adds rooms, task tracking, mobile access and persistent agents.');
+  effects.out(KEEPS_YOUR_SETUP);
+  const goal = await effects.select('What would you like to do?', [
+    { value: 'tools', label: 'Add collaboration tools to my agent apps (Claude Code, Codex or another app)' },
+    { value: 'workspace', label: 'Install the complete Ours workspace' },
+    { value: 'join', label: 'Connect my agent apps to an Ours workspace that runs on another computer' },
+    { value: 'advanced', label: 'Other setups (server only, custom ports or packages)' },
+  ], 'tools');
+  if (goal === 'tools') return collectTools(effects);
+  if (goal === 'workspace') {
+    effects.out(heading('The complete Ours workspace'));
+    for (const line of WORKSPACE_BENEFITS) effects.out(line);
+    effects.out(KEEPS_YOUR_SETUP);
+    return { action: 'advanced', presets: { scope: 'all' } };
+  }
+  if (goal === 'join') return { action: 'advanced', presets: { scope: 'client' } };
+  return { action: 'advanced', presets: {} };
+}
+
+/** Exact, verified guidance for an agent app the installer cannot configure itself. */
+export function customHarnessGuidance({ version, profilePath, marketplace }) {
+  const folder = marketplace ? `${marketplace}/plugins/ours` : null;
+  return [
+    'Connect another agent app:',
+    '  Ours provides its tools as an MCP server (stdio) plus instructions for the agent. Any agent app that can',
+    '  run a local stdio MCP server can use them; apps that cannot run MCP servers cannot use Ours this way.',
+    ...(folder ? [
+      `  Ready on this computer: ${folder}`,
+      '  Add this MCP server in the agent app\'s settings:',
+      `    command: node   arguments: ${folder}/bin/proxy.mjs`,
+      '    environment: CLAUDE_CODE_SESSION_ID = a value unique to each agent session (for example a new UUID).',
+      '    Without it the Ours tools refuse to act, because they keep each session\'s identity separate.',
+      `  Give the agent ${folder}/skills/ours/SKILL.md as its instructions for the Ours tools.`,
+    ] : []),
+    `  It connects to Ours on this computer through ${profilePath}; no other settings are needed.`,
+    `  The same plugin is published as npm package @ours.network/claude-code@${version}`,
+    `  (https://www.npmjs.com/package/@ours.network/claude-code/v/${version}); after npm install in its folder it is used`,
+    '  the same way. Use this exact version: the public GitHub marketplace adapt-toolkit/ours-claude-marketplace',
+    '  currently selects an older plugin that does not work with this release.',
+  ];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ours.network/install",
-  "version": "1.2.1-nightly.42",
+  "version": "1.2.1-nightly.43",
   "private": false,
   "description": "The all-in-one ours.network installer: one shared daemon, MCP, cowork, Telegram, Fleet initialization, harness plugins, Human identity, progress UI, and guided next steps.",
   "type": "module",