zigrix 0.1.0-alpha.8 → 0.1.0

package/dist/onboard.js

@@ -1,15 +1,20 @@
+import { execSync } from 'node:child_process';
 import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { addAgent } from './agents/registry.js';
+import { inferStandardAgentRole, STANDARD_AGENT_ROLES } from './agents/roles.js';
+import { LEGACY_DEFAULT_GATEWAY_URL, resolveAbsolutePath } from './config/defaults.js';
 import { loadConfig, writeConfigFile, writeDefaultConfig } from './config/load.js';
 import { ensureBaseState, resolvePaths } from './state/paths.js';
 import { rebuildIndex } from './state/tasks.js';
 // ─── OpenClaw detection ───────────────────────────────────────────────────────
 export function detectOpenClawHome() {
+    const fallbackHome = process.env.HOME ?? os.homedir();
     return process.env.OPENCLAW_HOME
-        ? path.resolve(process.env.OPENCLAW_HOME)
-        : path.join(process.env.HOME ?? '~', '.openclaw');
+        ? resolveAbsolutePath(process.env.OPENCLAW_HOME)
+        : path.join(fallbackHome, '.openclaw');
 }
 export function loadOpenClawConfig(openclawHome) {
     const configPath = path.join(openclawHome, 'openclaw.json');
@@ -23,12 +28,120 @@ export function loadOpenClawConfig(openclawHome) {
         return null;
     }
 }
+function normalizeGatewayUrl(input) {
+    const trimmed = input?.trim() ?? '';
+    if (!trimmed)
+        return '';
+    const withScheme = /^[a-z]+:\/\//i.test(trimmed) ? trimmed : `http://${trimmed}`;
+    const parsed = new URL(withScheme);
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+        throw new Error(`unsupported gateway url protocol: ${parsed.protocol}`);
+    }
+    return parsed.toString().replace(/\/+$/, '');
+}
+function coerceGatewayPort(value) {
+    const n = typeof value === 'string' && value.trim().length > 0 ? Number(value) : typeof value === 'number' ? value : NaN;
+    if (!Number.isFinite(n) || n <= 0 || n > 65535)
+        return null;
+    return Math.trunc(n);
+}
+export function resolveOpenClawGatewayUrl(openclawConfig) {
+    if (!openclawConfig || typeof openclawConfig !== 'object')
+        return null;
+    const directUrl = openclawConfig.gateway?.url;
+    if (typeof directUrl === 'string' && directUrl.trim().length > 0) {
+        return normalizeGatewayUrl(directUrl);
+    }
+    const port = coerceGatewayPort(openclawConfig.gateway?.port);
+    if (port) {
+        return `http://127.0.0.1:${port}`;
+    }
+    return null;
+}
+export function resolveOpenClawGatewayToken(openclawConfig) {
+    const token = openclawConfig?.gateway?.auth?.token;
+    return typeof token === 'string' && token.trim().length > 0 ? token : null;
+}
+function shouldReplaceStoredGatewayUrl(stored, detected) {
+    const trimmed = stored.trim();
+    if (!trimmed)
+        return Boolean(detected);
+    if (!detected)
+        return false;
+    return trimmed === LEGACY_DEFAULT_GATEWAY_URL;
+}
+/**
+ * Discover the openclaw binary path.
+ * Strategy order:
+ *   1. `which openclaw` — available in current PATH
+ *   2. Common nvm/volta/fnm managed paths
+ *   3. Well-known locations: /usr/local/bin, ~/.local/bin
+ *   4. Walk node_modules/.bin from openclaw home
+ *
+ * Returns the resolved absolute path or null.
+ */
+export function resolveOpenClawBin(openclawHome) {
+    // Strategy 1: which/where
+    try {
+        const result = execSync('which openclaw', { encoding: 'utf8', timeout: 3000 }).trim();
+        if (result && fs.existsSync(result))
+            return path.resolve(result);
+    }
+    catch {
+        // not in PATH
+    }
+    // Strategy 2: nvm/volta/fnm managed global bin dirs
+    const home = process.env.HOME ?? '';
+    const nodeVersion = process.versions.node;
+    const majorMinorPatch = nodeVersion; // e.g., "25.5.0"
+    const nvmCandidate = path.join(home, '.nvm', 'versions', 'node', `v${majorMinorPatch}`, 'bin', 'openclaw');
+    if (fs.existsSync(nvmCandidate))
+        return path.resolve(nvmCandidate);
+    // Also try nvm current symlink
+    const nvmCurrent = path.join(home, '.nvm', 'current', 'bin', 'openclaw');
+    if (fs.existsSync(nvmCurrent))
+        return path.resolve(nvmCurrent);
+    // Volta
+    const voltaCandidate = path.join(home, '.volta', 'bin', 'openclaw');
+    if (fs.existsSync(voltaCandidate))
+        return path.resolve(voltaCandidate);
+    // fnm
+    const fnmCandidate = path.join(home, '.fnm', 'node-versions', `v${majorMinorPatch}`, 'installation', 'bin', 'openclaw');
+    if (fs.existsSync(fnmCandidate))
+        return path.resolve(fnmCandidate);
+    // Strategy 3: well-known system paths
+    for (const dir of ['/usr/local/bin', path.join(home, '.local', 'bin')]) {
+        const candidate = path.join(dir, 'openclaw');
+        if (fs.existsSync(candidate))
+            return path.resolve(candidate);
+    }
+    // Strategy 4: node global lib path (npm root -g)
+    try {
+        const globalRoot = execSync('npm root -g', { encoding: 'utf8', timeout: 3000 }).trim();
+        if (globalRoot) {
+            const candidate = path.join(path.dirname(globalRoot), 'bin', 'openclaw');
+            if (fs.existsSync(candidate))
+                return path.resolve(candidate);
+        }
+    }
+    catch {
+        // npm not available or timed out
+    }
+    // Strategy 5: from openclaw home
+    if (openclawHome) {
+        // Some installations place a bin reference inside the home dir
+        const homeBin = path.join(openclawHome, 'bin', 'openclaw');
+        if (fs.existsSync(homeBin))
+            return path.resolve(homeBin);
+    }
+    return null;
+}
 // ─── Agent filtering ──────────────────────────────────────────────────────────
 export function filterAgents(agents) {
     return agents.filter((a) => a.id !== 'main');
 }
 // ─── Agent registration ───────────────────────────────────────────────────────
-export function registerAgents(config, agents) {
+export function registerAgents(config, agents, roleAssignments) {
     let current = structuredClone(config);
     const registered = [];
     const skipped = [];
@@ -38,7 +151,10 @@ export function registerAgents(config, agents) {
             skipped.push(agent.id);
             continue;
         }
-        const role = agent.identity?.theme ?? 'assistant';
+        const role = roleAssignments?.[agent.id] ?? inferStandardAgentRole({
+            agentId: agent.id,
+            theme: agent.identity?.theme ?? null,
+        });
         const result = addAgent(current, {
             id: agent.id,
             role,
@@ -73,6 +189,28 @@ export function resolveBundledRulesDir() {
     }
     return null;
 }
+export function resolveRuleSeedSource(projectDir) {
+    const searched = [];
+    const base = projectDir?.trim();
+    if (base) {
+        const resolvedBase = resolveAbsolutePath(base);
+        const candidates = [
+            path.join(resolvedBase, 'rules', 'defaults'),
+            path.join(resolvedBase, 'rules'),
+        ];
+        searched.push(...candidates);
+        for (const candidate of candidates) {
+            if (fs.existsSync(candidate) && fs.statSync(candidate).isDirectory()) {
+                return { sourceDir: candidate, source: 'external', searched };
+            }
+        }
+    }
+    const bundled = resolveBundledRulesDir();
+    if (bundled) {
+        return { sourceDir: bundled, source: 'bundled', searched };
+    }
+    return { sourceDir: null, source: 'none', searched };
+}
 export function seedRules(sourceDir, targetDir) {
     const copied = [];
     const skipped = [];
@@ -102,9 +240,9 @@ export function seedRules(sourceDir, targetDir) {
     return { copied, skipped, source: effectiveSource === sourceDir ? 'external' : 'bundled' };
 }
 // ─── PATH check and stabilization ─────────────────────────────────────────────
-export function checkZigrixInPath() {
-    const pathEnv = process.env.PATH ?? '';
-    const dirs = pathEnv.split(path.delimiter).filter(Boolean);
+export const STABLE_SHELL_PATHS = ['/usr/local/bin', '/usr/bin', '/bin', '/usr/sbin', '/sbin'];
+export function checkZigrixInPath(opts) {
+    const dirs = opts?._overrideStablePaths ?? STABLE_SHELL_PATHS;
     for (const dir of dirs) {
         try {
             if (!fs.existsSync(dir))
@@ -215,9 +353,10 @@ export function findUserBinDir() {
  *   2. ~/.local/bin   — user-local fallback; may not be in PATH, shows warning if so
  *
  * @param opts._overrideSystemBinDir - Override system bin dir selection (for testing)
+ * @param opts._overrideStablePaths  - Override stable paths list (for testing)
  */
 export function ensureZigrixInPath(opts) {
-    if (checkZigrixInPath()) {
+    if (checkZigrixInPath({ _overrideStablePaths: opts?._overrideStablePaths })) {
         return { alreadyInPath: true, symlinkCreated: false, symlinkPath: null, warning: null };
     }
     const binEntry = resolveZigrixBin();
@@ -249,7 +388,15 @@ export function ensureZigrixInPath(opts) {
             fs.chmodSync(symlinkPath, 0o755);
             return { alreadyInPath: false, symlinkCreated: true, symlinkPath, warning: null };
         }
-        catch {
+        catch (e) {
+            if (e.code === 'EACCES') {
+                return {
+                    alreadyInPath: false,
+                    symlinkCreated: false,
+                    symlinkPath: null,
+                    warning: `Cannot write to ${systemBinDir} (permission denied). Run:\n  sudo ln -sfn $(which zigrix) ${symlinkPath}`,
+                };
+            }
             // Fall through to user bin dir
         }
     }
@@ -302,6 +449,121 @@ export function ensureZigrixInPath(opts) {
         : `Created zigrix at ${symlinkPath}, but ${userBinDir} is not in your PATH. Add it:\n  export PATH="${userBinDir}:$PATH"`;
     return { alreadyInPath: false, symlinkCreated: true, symlinkPath, warning };
 }
+// ─── OpenClaw PATH check and stabilization ────────────────────────────────────
+export function checkOpenClawInPath(opts) {
+    const dirs = opts?._overrideStablePaths ?? STABLE_SHELL_PATHS;
+    for (const dir of dirs) {
+        try {
+            if (!fs.existsSync(dir))
+                continue;
+            const entries = fs.readdirSync(dir);
+            if (entries.includes('openclaw')) {
+                return true;
+            }
+        }
+        catch {
+            // skip unreadable dirs
+        }
+    }
+    return false;
+}
+/**
+ * Ensure openclaw is reachable from PATH.
+ * Same strategy as ensureZigrixInPath():
+ *   1. /usr/local/bin — stable path, accessible from non-login shells
+ *   2. ~/.local/bin   — user-local fallback
+ *
+ * @param opts._overrideSystemBinDir - Override system bin dir selection (for testing)
+ * @param opts._overrideStablePaths  - Override stable paths list (for testing)
+ */
+export function ensureOpenClawInPath(opts) {
+    if (checkOpenClawInPath({ _overrideStablePaths: opts?._overrideStablePaths })) {
+        return { alreadyInPath: true, symlinkCreated: false, symlinkPath: null, warning: null };
+    }
+    const binPath = resolveOpenClawBin();
+    if (!binPath) {
+        return {
+            alreadyInPath: false,
+            symlinkCreated: false,
+            symlinkPath: null,
+            warning: 'Could not locate openclaw binary. Ensure openclaw is installed via npm.',
+        };
+    }
+    // ── Strategy 1: system bin dir (accessible from non-login shells) ──────────
+    const systemBinDir = opts !== undefined && '_overrideSystemBinDir' in opts
+        ? opts._overrideSystemBinDir
+        : findSystemBinDir();
+    if (systemBinDir) {
+        const symlinkPath = path.join(systemBinDir, 'openclaw');
+        try {
+            // Remove stale entry if present
+            try {
+                if (fs.existsSync(symlinkPath) || fs.lstatSync(symlinkPath).isSymbolicLink()) {
+                    fs.unlinkSync(symlinkPath);
+                }
+            }
+            catch {
+                // doesn't exist — fine
+            }
+            fs.symlinkSync(binPath, symlinkPath);
+            fs.chmodSync(symlinkPath, 0o755);
+            return { alreadyInPath: false, symlinkCreated: true, symlinkPath, warning: null };
+        }
+        catch (e) {
+            if (e.code === 'EACCES') {
+                return {
+                    alreadyInPath: false,
+                    symlinkCreated: false,
+                    symlinkPath: null,
+                    warning: `Cannot write to ${systemBinDir} (permission denied). Run:\n  sudo ln -sfn ${binPath} ${symlinkPath}`,
+                };
+            }
+            // Fall through to user bin dir
+        }
+    }
+    // ── Strategy 2: user-local bin dir ────────────────────────────────────────
+    const userBinDir = findUserBinDir();
+    try {
+        fs.mkdirSync(userBinDir, { recursive: true });
+    }
+    catch {
+        return {
+            alreadyInPath: false,
+            symlinkCreated: false,
+            symlinkPath: null,
+            warning: `Could not create ${userBinDir}. Create it manually and add to PATH.`,
+        };
+    }
+    const symlinkPath = path.join(userBinDir, 'openclaw');
+    try {
+        // Remove existing if present (stale symlink)
+        if (fs.existsSync(symlinkPath) || fs.lstatSync(symlinkPath).isSymbolicLink()) {
+            fs.unlinkSync(symlinkPath);
+        }
+    }
+    catch {
+        // doesn't exist, fine
+    }
+    try {
+        fs.symlinkSync(binPath, symlinkPath);
+        fs.chmodSync(symlinkPath, 0o755);
+    }
+    catch (e) {
+        return {
+            alreadyInPath: false,
+            symlinkCreated: false,
+            symlinkPath: null,
+            warning: `Failed to create symlink at ${symlinkPath}: ${e instanceof Error ? e.message : String(e)}`,
+        };
+    }
+    // Check if userBinDir is actually in PATH
+    const pathEnv = process.env.PATH ?? '';
+    const inPath = pathEnv.split(path.delimiter).some((d) => path.resolve(d) === path.resolve(userBinDir));
+    const warning = inPath
+        ? null
+        : `Created openclaw at ${symlinkPath}, but ${userBinDir} is not in your PATH. Add it:\n  export PATH="${userBinDir}:$PATH"`;
+    return { alreadyInPath: false, symlinkCreated: true, symlinkPath, warning };
+}
 // ─── OpenClaw skill registration ──────────────────────────────────────────────
 /**
  * Find the skills/ directory bundled with this zigrix package.
@@ -418,13 +680,137 @@ export async function promptAgentSelection(agents) {
         return agents;
     }
 }
+export async function promptAgentRoleAssignments(agents) {
+    const defaults = Object.fromEntries(agents.map((agent) => [agent.id, inferStandardAgentRole({ agentId: agent.id, theme: agent.identity?.theme ?? null })]));
+    if (agents.length === 0)
+        return defaults;
+    try {
+        const { checkbox } = await import('@inquirer/prompts');
+        const assignments = {};
+        for (const agent of agents) {
+            const suggested = defaults[agent.id];
+            let selected = [];
+            while (selected.length !== 1) {
+                selected = await checkbox({
+                    message: `Assign role for ${agent.id} (space toggle + enter confirm, choose exactly one):`,
+                    choices: STANDARD_AGENT_ROLES.map((role) => ({
+                        name: `${role}${role === suggested ? ' (suggested)' : ''}`,
+                        value: role,
+                        checked: role === suggested,
+                    })),
+                });
+                if (selected.length !== 1) {
+                    console.log(`⚠️  Select exactly one role for ${agent.id}.`);
+                }
+            }
+            assignments[agent.id] = selected[0];
+        }
+        return assignments;
+    }
+    catch {
+        console.log('ℹ️  Non-interactive mode — inferring roles from agent ids/themes.');
+        return defaults;
+    }
+}
+export async function promptWorkspaceBaseDir(defaultPath) {
+    try {
+        const { input } = await import('@inquirer/prompts');
+        const answer = await input({
+            message: 'Workspace directory',
+            default: defaultPath,
+            validate: (value) => {
+                if (!value || value.trim().length === 0)
+                    return 'Workspace directory is required';
+                return true;
+            },
+        });
+        return resolveAbsolutePath((answer || defaultPath).trim());
+    }
+    catch {
+        console.log('ℹ️  Non-interactive mode — using configured workspace directory.');
+        return resolveAbsolutePath(defaultPath);
+    }
+}
+export async function promptGatewayUrl(defaultValue) {
+    try {
+        const { input } = await import('@inquirer/prompts');
+        const answer = await input({
+            message: 'OpenClaw gateway URL (leave blank to skip)',
+            default: defaultValue,
+            validate: (value) => {
+                const trimmed = value.trim();
+                if (!trimmed)
+                    return true;
+                try {
+                    normalizeGatewayUrl(trimmed);
+                    return true;
+                }
+                catch (error) {
+                    return error.message;
+                }
+            },
+        });
+        return normalizeGatewayUrl((answer || defaultValue).trim());
+    }
+    catch {
+        console.log('ℹ️  Non-interactive mode — skipping gateway URL prompt.');
+        return normalizeGatewayUrl(defaultValue);
+    }
+}
+export function ensureOrchestratorId(config, preferredId) {
+    const next = structuredClone(config);
+    const participants = new Set(next.agents.orchestration.participants);
+    const excluded = new Set(next.agents.orchestration.excluded);
+    const participantMode = participants.size > 0;
+    const eligible = Object.entries(next.agents.registry)
+        .filter(([agentId, agent]) => {
+        if (!agent.enabled)
+            return false;
+        if (agent.role !== 'orchestrator')
+            return false;
+        if (excluded.has(agentId))
+            return false;
+        if (participantMode && !participants.has(agentId))
+            return false;
+        return true;
+    })
+        .map(([agentId]) => agentId)
+        .sort();
+    const requested = preferredId?.trim();
+    const current = next.agents.orchestration.orchestratorId;
+    if (requested) {
+        if (!eligible.includes(requested)) {
+            return {
+                config: next,
+                changed: false,
+                warning: `requested orchestrator '${requested}' is not eligible (eligible: ${eligible.join(', ') || 'none'})`,
+            };
+        }
+        const changed = current !== requested;
+        next.agents.orchestration.orchestratorId = requested;
+        return { config: next, changed };
+    }
+    if (eligible.includes(current)) {
+        return { config: next, changed: false };
+    }
+    const fallback = eligible[0];
+    if (!fallback) {
+        return {
+            config: next,
+            changed: false,
+            warning: 'no eligible orchestrator role agent found. set one with --orchestrator-id after assigning roles.',
+        };
+    }
+    next.agents.orchestration.orchestratorId = fallback;
+    return { config: next, changed: true };
+}
 // ─── Ensure config (idempotent) ───────────────────────────────────────────────
 function ensureConfig() {
     const existing = loadConfig({});
     if (existing.configPath && fs.existsSync(existing.configPath)) {
         return { configPath: existing.configPath, isNew: false };
     }
-    const configPath = writeDefaultConfig(undefined, false);
+    const configPath = writeDefaultConfig(false);
     return { configPath, isNew: true };
 }
 // ─── Main onboard function ────────────────────────────────────────────────────
@@ -435,10 +821,22 @@ export async function runOnboard(options) {
         if (!silent)
             console.log(msg);
     };
-    // 1. Ensure ~/.zigrix base state (idempotent)
+    // 1. Ensure config.paths.baseDir state (idempotent)
     const { configPath } = ensureConfig();
     const loaded = loadConfig({ configPath });
-    const paths = resolvePaths(loaded.config);
+    let nextConfig = structuredClone(loaded.config);
+    const configuredWorkspace = nextConfig.workspace.projectsBaseDir?.trim() || path.join(nextConfig.paths.baseDir, 'workspace');
+    const desiredWorkspace = options.projectsBaseDir
+        ? resolveAbsolutePath(options.projectsBaseDir)
+        : options.yes
+            ? resolveAbsolutePath(configuredWorkspace)
+            : await promptWorkspaceBaseDir(configuredWorkspace);
+    if (nextConfig.workspace.projectsBaseDir !== desiredWorkspace) {
+        nextConfig.workspace.projectsBaseDir = desiredWorkspace;
+        writeConfigFile(configPath, nextConfig);
+        log(`✅ Workspace base dir set to: ${desiredWorkspace}`);
+    }
+    const paths = resolvePaths(nextConfig);
     ensureBaseState(paths);
     rebuildIndex(paths);
     // 2. Detect OpenClaw
@@ -456,6 +854,23 @@ export async function runOnboard(options) {
             log(`⚠️  ${warnings[warnings.length - 1]}`);
         }
     }
+    const storedGatewayUrl = nextConfig.openclaw.gatewayUrl?.trim() ?? '';
+    const detectedGatewayUrl = resolveOpenClawGatewayUrl(openclawConfig);
+    const resolvedGatewayUrl = (() => {
+        if (typeof options.gatewayUrl === 'string' && options.gatewayUrl.trim().length > 0) {
+            return normalizeGatewayUrl(options.gatewayUrl);
+        }
+        if (storedGatewayUrl && !shouldReplaceStoredGatewayUrl(storedGatewayUrl, detectedGatewayUrl)) {
+            return normalizeGatewayUrl(storedGatewayUrl);
+        }
+        if (detectedGatewayUrl) {
+            return detectedGatewayUrl;
+        }
+        if (openclawExists && !options.yes) {
+            return '';
+        }
+        return storedGatewayUrl ? normalizeGatewayUrl(storedGatewayUrl) : '';
+    })();
     // 3. Agent selection and registration
     let agentsRegistered = [];
     let agentsSkipped = [];
@@ -472,32 +887,64 @@ export async function runOnboard(options) {
             selectedAgents = await promptAgentSelection(allAgents);
         }
         if (selectedAgents.length > 0) {
-            const result = registerAgents(loaded.config, selectedAgents);
+            const roleAssignments = options.yes
+                ? Object.fromEntries(selectedAgents.map((agent) => [agent.id, inferStandardAgentRole({ agentId: agent.id, theme: agent.identity?.theme ?? null })]))
+                : await promptAgentRoleAssignments(selectedAgents);
+            const result = registerAgents(nextConfig, selectedAgents, roleAssignments);
+            nextConfig = result.config;
             agentsRegistered = result.registered;
             agentsSkipped = result.skipped;
             if (agentsRegistered.length > 0) {
-                writeConfigFile(configPath, result.config);
                 log(`✅ Registered agents: ${agentsRegistered.join(', ')}`);
             }
             if (agentsSkipped.length > 0) {
                 log(`⏭️  Already registered (skipped): ${agentsSkipped.join(', ')}`);
             }
         }
+        const orchResult = ensureOrchestratorId(nextConfig, options.orchestratorId);
+        nextConfig = orchResult.config;
+        if (orchResult.warning) {
+            warnings.push(orchResult.warning);
+            log(`⚠️  ${orchResult.warning}`);
+        }
+        if (agentsRegistered.length > 0 || orchResult.changed) {
+            writeConfigFile(configPath, nextConfig);
+            if (orchResult.changed) {
+                log(`✅ Orchestrator set to: ${nextConfig.agents.orchestration.orchestratorId}`);
+            }
+        }
+    }
+    if (!openclawConfig && options.orchestratorId) {
+        const orchResult = ensureOrchestratorId(nextConfig, options.orchestratorId);
+        if (orchResult.warning) {
+            warnings.push(orchResult.warning);
+            log(`⚠️  ${orchResult.warning}`);
+        }
+        if (orchResult.changed) {
+            writeConfigFile(configPath, orchResult.config);
+            log(`✅ Orchestrator set to: ${orchResult.config.agents.orchestration.orchestratorId}`);
+        }
     }
     // 4. Seed rules
-    const projectDir = options.projectDir ?? process.cwd();
-    const rulesSourceDir = path.join(projectDir, 'orchestration', 'rules');
     const rulesTargetDir = paths.rulesDir;
-    if (!fs.existsSync(rulesSourceDir)) {
-        warnings.push(`orchestration/rules/ not found at ${rulesSourceDir}. Rules seeding skipped.`);
+    const ruleSeed = resolveRuleSeedSource(options.projectDir);
+    let rulesCopied = [];
+    let rulesSkipped = [];
+    if (!ruleSeed.sourceDir) {
+        warnings.push('No bundled rule templates available. Rules seeding skipped.');
         log(`⚠️  ${warnings[warnings.length - 1]}`);
     }
-    const { copied: rulesCopied, skipped: rulesSkipped } = seedRules(rulesSourceDir, rulesTargetDir);
-    if (rulesCopied.length > 0) {
-        log(`✅ Rules copied: ${rulesCopied.join(', ')}`);
-    }
-    if (rulesSkipped.length > 0) {
-        log(`⏭️  Rules already exist (skipped): ${rulesSkipped.join(', ')}`);
+    else {
+        if (options.projectDir && ruleSeed.source === 'bundled') {
+            log(`ℹ️  No external rule templates found under ${options.projectDir}; using bundled defaults.`);
+        }
+        ({ copied: rulesCopied, skipped: rulesSkipped } = seedRules(ruleSeed.sourceDir, rulesTargetDir));
+        if (rulesCopied.length > 0) {
+            log(`✅ Rules copied: ${rulesCopied.join(', ')}`);
+        }
+        if (rulesSkipped.length > 0) {
+            log(`⏭️  Rules already exist (skipped): ${rulesSkipped.join(', ')}`);
+        }
     }
     // 5. Stabilize PATH — ensure zigrix is reachable
     const pathResult = ensureZigrixInPath();
@@ -511,7 +958,59 @@ export async function runOnboard(options) {
         warnings.push(pathResult.warning);
         log(`⚠️  ${pathResult.warning}`);
     }
-    // 6. Register OpenClaw skills (symlink skill packs)
+    // 6. Detect and persist openclaw binary path
+    let openclawBinPath = null;
+    if (openclawExists) {
+        openclawBinPath = resolveOpenClawBin(openclawHome);
+        if (openclawBinPath) {
+            log(`✅ OpenClaw binary found: ${openclawBinPath}`);
+        }
+        else {
+            warnings.push('openclaw binary not found. Dashboard conversation features may be limited.');
+            log(`⚠️  ${warnings[warnings.length - 1]}`);
+        }
+        // Persist openclaw integration config (home, binPath, gatewayUrl)
+        const currentConfig = loadConfig({ configPath }).config;
+        // Gateway URL: explicit flag > autodiscovery > interactive prompt > stored value
+        let finalGatewayUrl = resolvedGatewayUrl;
+        if (!finalGatewayUrl && openclawExists && !options.yes) {
+            const suggested = detectedGatewayUrl || '';
+            finalGatewayUrl = await promptGatewayUrl(suggested);
+        }
+        if (finalGatewayUrl) {
+            log(`✅ OpenClaw gateway URL: ${finalGatewayUrl}`);
+        }
+        else if (openclawExists) {
+            warnings.push('OpenClaw gateway URL not configured. Dashboard gateway features may be limited. Set later with `zigrix configure --section openclaw` or `zigrix onboard --gateway-url <url>`.');
+            log(`⚠️  ${warnings[warnings.length - 1]}`);
+        }
+        const needsUpdate = currentConfig.openclaw.home !== openclawHome ||
+            currentConfig.openclaw.binPath !== openclawBinPath ||
+            currentConfig.openclaw.gatewayUrl !== (finalGatewayUrl || '');
+        if (needsUpdate) {
+            currentConfig.openclaw.home = openclawHome;
+            currentConfig.openclaw.binPath = openclawBinPath;
+            currentConfig.openclaw.gatewayUrl = finalGatewayUrl || '';
+            writeConfigFile(configPath, currentConfig);
+            log(`✅ OpenClaw config persisted (home: ${openclawHome}, bin: ${openclawBinPath ?? 'not found'}, gateway: ${finalGatewayUrl || 'not set'})`);
+        }
+    }
+    // 7. Stabilize PATH — ensure openclaw is reachable from non-login shells
+    let openclawPathResult = { alreadyInPath: false, symlinkCreated: false, symlinkPath: null, warning: null };
+    if (openclawBinPath) {
+        openclawPathResult = ensureOpenClawInPath();
+        if (openclawPathResult.symlinkCreated) {
+            log(`✅ openclaw symlinked to ${openclawPathResult.symlinkPath}`);
+        }
+        else if (openclawPathResult.alreadyInPath) {
+            log('✅ openclaw already in PATH');
+        }
+        if (openclawPathResult.warning) {
+            warnings.push(openclawPathResult.warning);
+            log(`⚠️  ${openclawPathResult.warning}`);
+        }
+    }
+    // 8. Register OpenClaw skills (symlink skill packs)
     let skillsRegistered = [];
     let skillsSkipped = [];
     let skillsFailed = [];
@@ -542,10 +1041,13 @@ export async function runOnboard(options) {
         ok: true,
         action: 'onboard',
         baseDir: paths.baseDir,
+        workspaceBaseDir: nextConfig.workspace.projectsBaseDir,
         configPath,
         paths,
         openclawDetected: openclawExists,
         openclawHome,
+        openclawBinPath,
+        openclawGatewayUrl: resolvedGatewayUrl || null,
         agentsRegistered,
         agentsSkipped,
         rulesCopied,
@@ -554,9 +1056,11 @@ export async function runOnboard(options) {
         skillsSkipped,
         skillsFailed,
         pathStabilized: pathResult,
+        openclawPathStabilized: openclawPathResult,
         warnings,
         checks: {
             zigrixInPath: pathResult.alreadyInPath || pathResult.symlinkCreated,
+            openclawInPath: openclawPathResult.alreadyInPath || openclawPathResult.symlinkCreated,
             openclawSkillsDir: openclawSkillsDirExists,
         },
     };