zigrix 0.1.0-alpha.9 → 0.1.0

package/dist/onboard.d.ts

@@ -14,6 +14,23 @@ export interface OpenClawConfig {
     agents?: {
         list?: OpenClawAgent[];
     };
+    gateway?: {
+        port?: number | string;
+        bind?: string;
+        mode?: string;
+        auth?: {
+            token?: string;
+        };
+    };
+    plugins?: {
+        entries?: {
+            'device-pair'?: {
+                config?: {
+                    publicUrl?: string;
+                };
+            };
+        };
+    };
 }
 export type AgentRoleAssignments = Record<string, StandardAgentRole>;
 export interface PathStabilizeResult {
@@ -31,10 +48,13 @@ export interface OnboardResult {
     ok: boolean;
     action: string;
     baseDir: string;
+    workspaceBaseDir: string;
     configPath: string;
     paths: ZigrixPaths;
     openclawDetected: boolean;
     openclawHome: string;
+    openclawBinPath: string | null;
+    openclawGatewayUrl: string | null;
     agentsRegistered: string[];
     agentsSkipped: string[];
     rulesCopied: string[];
@@ -43,20 +63,37 @@ export interface OnboardResult {
     skillsSkipped: string[];
     skillsFailed: string[];
     pathStabilized: PathStabilizeResult;
+    openclawPathStabilized: PathStabilizeResult;
     warnings: string[];
     checks: {
         zigrixInPath: boolean;
+        openclawInPath: boolean;
         openclawSkillsDir: boolean;
     };
 }
 export interface RunOnboardOptions {
     yes?: boolean;
     projectDir?: string;
+    projectsBaseDir?: string;
     orchestratorId?: string;
+    gatewayUrl?: string;
     silent?: boolean;
 }
 export declare function detectOpenClawHome(): string;
 export declare function loadOpenClawConfig(openclawHome: string): OpenClawConfig | null;
+export declare function resolveOpenClawGatewayUrl(openclawConfig: OpenClawConfig | null): string | null;
+export declare function resolveOpenClawGatewayToken(openclawConfig: OpenClawConfig | null): string | null;
+/**
+ * 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 declare function resolveOpenClawBin(openclawHome?: string): string | null;
 export declare function filterAgents(agents: OpenClawAgent[]): OpenClawAgent[];
 export declare function registerAgents(config: ZigrixConfig, agents: OpenClawAgent[], roleAssignments?: AgentRoleAssignments): {
     config: ZigrixConfig;
@@ -67,6 +104,11 @@ export declare function registerAgents(config: ZigrixConfig, agents: OpenClawAge
  * Find the bundled default rules directory shipped with the zigrix package.
  */
 export declare function resolveBundledRulesDir(): string | null;
+export declare function resolveRuleSeedSource(projectDir?: string): {
+    sourceDir: string | null;
+    source: 'external' | 'bundled' | 'none';
+    searched: string[];
+};
 export declare function seedRules(sourceDir: string, targetDir: string): {
     copied: string[];
     skipped: string[];
@@ -106,6 +148,22 @@ export declare function ensureZigrixInPath(opts?: {
     _overrideSystemBinDir?: string | null;
     _overrideStablePaths?: string[];
 }): PathStabilizeResult;
+export declare function checkOpenClawInPath(opts?: {
+    _overrideStablePaths?: string[];
+}): boolean;
+/**
+ * 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 declare function ensureOpenClawInPath(opts?: {
+    _overrideSystemBinDir?: string | null;
+    _overrideStablePaths?: string[];
+}): PathStabilizeResult;
 /**
  * Find the skills/ directory bundled with this zigrix package.
  */
@@ -122,6 +180,8 @@ export declare function registerSkills(openclawHome: string): SkillRegistrationR
  */
 export declare function promptAgentSelection(agents: OpenClawAgent[]): Promise<OpenClawAgent[]>;
 export declare function promptAgentRoleAssignments(agents: OpenClawAgent[]): Promise<AgentRoleAssignments>;
+export declare function promptWorkspaceBaseDir(defaultPath: string): Promise<string>;
+export declare function promptGatewayUrl(defaultValue: string): Promise<string>;
 export declare function ensureOrchestratorId(config: ZigrixConfig, preferredId?: string): {
     config: ZigrixConfig;
     changed: boolean;

package/dist/onboard.js

@@ -1,16 +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');
@@ -24,6 +28,114 @@ 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');
@@ -77,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 = [];
@@ -315,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.
@@ -463,6 +712,51 @@ export async function promptAgentRoleAssignments(agents) {
         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);
@@ -516,7 +810,7 @@ function ensureConfig() {
     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 ────────────────────────────────────────────────────
@@ -527,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
@@ -548,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 = [];
@@ -563,7 +886,6 @@ export async function runOnboard(options) {
         else {
             selectedAgents = await promptAgentSelection(allAgents);
         }
-        let nextConfig = loaded.config;
         if (selectedAgents.length > 0) {
             const roleAssignments = options.yes
                 ? Object.fromEntries(selectedAgents.map((agent) => [agent.id, inferStandardAgentRole({ agentId: agent.id, theme: agent.identity?.theme ?? null })]))
@@ -593,7 +915,7 @@ export async function runOnboard(options) {
         }
     }
     if (!openclawConfig && options.orchestratorId) {
-        const orchResult = ensureOrchestratorId(loaded.config, options.orchestratorId);
+        const orchResult = ensureOrchestratorId(nextConfig, options.orchestratorId);
         if (orchResult.warning) {
             warnings.push(orchResult.warning);
             log(`⚠️  ${orchResult.warning}`);
@@ -604,19 +926,25 @@ export async function runOnboard(options) {
         }
     }
     // 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();
@@ -630,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 = [];
@@ -661,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,
@@ -673,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,
         },
     };

package/dist/orchestration/dispatch.d.ts

@@ -1,5 +1,6 @@
 import type { ZigrixConfig } from '../config/schema.js';
 import { type ZigrixPaths } from '../state/paths.js';
+export declare function resolveConfiguredProjectDir(config: ZigrixConfig, explicitProjectDir?: string): string | undefined;
 export declare function dispatchTask(paths: ZigrixPaths, config: ZigrixConfig, params: {
     title: string;
     description: string;