### First-time Setup Checklist

Source: https://github.com/nexu-io/nexu/blob/main/e2e/desktop/README.md

A comprehensive checklist for setting up the E2E testing environment, including Node.js installation, dependency installation, macOS permissions, artifact download, and verification.

```bash
# 1. Install Node.js
nvm install 22

# 2. Install E2E dependencies
cd e2e/desktop
npm install

# 3. Grant macOS permissions (manual, one-time)
#    - System Settings → Privacy & Security → Accessibility → add Terminal + /usr/bin/osascript
#    - System Settings → Privacy & Security → Screen Recording → add Terminal
#    (See tables above for details)

# 4. Download nightly artifacts
npm run download

# 5. Verify everything works
npm run test:smoke
```

--------------------------------

### Install Playwright and Download Artifacts

Source: https://github.com/nexu-io/nexu/blob/main/e2e/desktop/README.md

Quick start commands to install dependencies and download the latest nightly DMG and ZIP artifacts for testing.

```bash
cd e2e/desktop
npm install           # Install Playwright (one-time)
npm run download      # Download latest nightly DMG + ZIP (~500MB)
npm run test:smoke    # Run smoke to verify the basics
```

--------------------------------

### Run Local Docs

Source: https://github.com/nexu-io/nexu/blob/main/docs/en/guide/contributing.md

Commands to install dependencies and start the local documentation development server.

```bash
cd docs
pnpm install
pnpm dev
```

--------------------------------

### Dependency Verification Example

Source: https://github.com/nexu-io/nexu/blob/main/specs/designs/skill-system-architecture-comparison.md

Illustrates how skill dependencies, specifically required plugins, are displayed and verified during the installation process.

```text
Show skill dependencies (`requires.plugins`) in UI
```

--------------------------------

### Mac mini Self-hosted Runner Setup

Source: https://github.com/nexu-io/nexu/blob/main/e2e/desktop/README.md

Steps to set up a self-hosted GitHub Actions runner on a Mac mini for E2E testing. Includes cloning the repo, installing dependencies, and downloading/configuring the runner.

```bash
# 1. Clone the repo
git clone git@github.com:nexu-io/nexu.git ~/nexu
cd ~/nexu/e2e/desktop
npm install

# 2. Install GitHub Actions runner
mkdir -p ~/actions-runner && cd ~/actions-runner
# Download from: https://github.com/actions/runner/releases (macOS ARM64)
curl -fL -o actions-runner.tar.gz https://github.com/actions/runner/releases/download/v2.324.0/actions-runner-osx-arm64-2.324.0.tar.gz
tar xzf actions-runner.tar.gz && rm actions-runner.tar.gz

```

--------------------------------

### Setup Command for First-time Use

Source: https://github.com/nexu-io/nexu/blob/main/apps/desktop/static/bundled-skills/libtv-video/SKILL.md

Use the setup command to initialize the skill with your API key. This is a non-blocking operation.

```bash
setup --api-key <mgk_xxx|sk-libtv_xxx>
```

--------------------------------

### Bootstrap Nexu with Launchd Services

Source: https://github.com/nexu-io/nexu/blob/main/specs/designs/launchd-process-architecture/en.md

Ensures necessary services (controller, openclaw) are installed and running. Starts services if they are not running and waits for the controller to be ready before starting the embedded web server.

```typescript
export interface DesktopEnv {
  plistDir: string;
  isDev: boolean;
  controllerPort: number;
  webPort: number;
  webRoot: string;
}

export async function bootstrapWithLaunchd(env: DesktopEnv): Promise<void> {
  const launchd = new LaunchdManager({ plistDir: env.plistDir });
  const labels = {
    controller: env.isDev ? "io.nexu.controller.dev" : "io.nexu.controller",
    openclaw: env.isDev ? "io.nexu.openclaw.dev" : "io.nexu.openclaw",
  };

  // 1. Ensure plist installed
  for (const [service, label] of Object.entries(labels)) {
    if (!(await launchd.isServiceInstalled(label))) {
      const plist = generatePlist(service as "controller" | "openclaw", env);
      await launchd.installService(label, plist);
    }
  }

  // 2. Start services not running
  const controllerStatus = await launchd.getServiceStatus(labels.controller);
  if (controllerStatus.status !== "running") {
    await launchd.startService(labels.controller);
    await waitForControllerReadiness(env.controllerPort);
  }

  const openclawStatus = await launchd.getServiceStatus(labels.openclaw);
  if (openclawStatus.status !== "running") {
    await launchd.startService(labels.openclaw);
  }

  // 3. Start embedded Web Server
  await startEmbeddedWebServer({
    port: env.webPort,
    webRoot: env.webRoot,
    controllerPort: env.controllerPort,
  });
}
```

--------------------------------

### Start Services in local-dev Environment

Source: https://github.com/nexu-io/nexu/blob/main/specs/current/environment.md

Use these commands to start individual services for controller-first development. Services can be started and stopped independently.

```bash
pnpm dev start openclaw
```

```bash
pnpm dev start controller
```

```bash
pnpm dev start web
```

```bash
pnpm dev start desktop
```

--------------------------------

### Local Tool Configurations Example

Source: https://github.com/nexu-io/nexu/blob/main/apps/controller/static/platform-templates/TOOLS.md

Example of how to define local configurations for cameras, SSH, and text-to-speech preferences.

```markdown
### Cameras

- living-room → Main area, 180° wide angle
- front-door → Entrance, motion-triggered

### SSH

- home-server → 192.168.1.100, user: admin

### TTS

- Preferred voice: "Nova" (warm, slightly British)
- Default speaker: Kitchen HomePod
```

--------------------------------

### Install Skills via Controller API

Source: https://github.com/nexu-io/nexu/blob/main/docs/plans/2026-03-21-verify-curated-skills.md

Installs a list of skills by sending POST requests to the controller's install endpoint. It then uses a Node.js script to parse and display the installation status.

```bash
CONTROLLER_URL="http://localhost:3001"

for slug in baoyu-xhs-images deep-research research-to-diagram qiaomu-mondo-poster-design; do
  echo "--- Installing: $slug ---"
  curl -s -X POST "$CONTROLLER_URL/api/v1/skillhub/install" \
    -H "Content-Type: application/json" \
    -d "{\"slug\": \"$slug\"}" | node -e "
      let d=''; process.stdin.on('data',c=>d+=c); process.stdin.on('end',()=>{
        const r=JSON.parse(d);
        console.log(r.ok ? 'OK' : 'FAIL: '+r.error);
      })"
done
```

--------------------------------

### Install Skill API Call

Source: https://github.com/nexu-io/nexu/blob/main/docs/plans/2026-03-23-skillhub-install-queue.md

Demonstrates how to install a skill using the SkillHub API via a curl command. Shows the expected JSON response for a successful queued installation.

```bash
curl -X POST http://localhost:3010/api/v1/skillhub/install -H 'Content-Type: application/json' -d '{"slug":"ontology"}'
```

--------------------------------

### Install Dependencies

Source: https://github.com/nexu-io/nexu/blob/main/AGENTS.md

Installs all project dependencies using pnpm.

```bash
pnpm install
```

--------------------------------

### Clone and Install Dependencies

Source: https://github.com/nexu-io/nexu/blob/main/CONTRIBUTING.md

Clone the nexu repository and install project dependencies using pnpm. This includes setting up the OpenClaw runtime.

```bash
git clone https://github.com/nexu-io/nexu.git
cd nexu
pnpm install
```

--------------------------------

### Install SkillHub via IPC

Source: https://github.com/nexu-io/nexu/blob/main/specs/plans/2026-03-17-skillhub-desktop-integration.md

Initiates the installation of SkillHub through an Inter-Process Communication (IPC) call to the 'clawhub install' command. This is typically triggered by a user clicking an install button.

```shell
clawhub install
```

--------------------------------

### List Installed Skills

Source: https://github.com/nexu-io/nexu/blob/main/apps/desktop/static/bundled-skills/clawhub/SKILL.md

Display a list of all skills currently installed on your system.

```bash
clawhub list
```

--------------------------------

### Start Local Development Stack

Source: https://github.com/nexu-io/nexu/blob/main/AGENTS.md

Starts the complete lightweight local development stack, including OpenClaw, controller, web, and desktop services.

```bash
pnpm dev start
```

--------------------------------

### Troubleshooting Desktop Cold Start

Source: https://github.com/nexu-io/nexu/blob/main/specs/guides/desktop-runtime-guide.md

Commands and log file locations for diagnosing desktop cold start issues.

```bash
pnpm dev logs desktop
```

```bash
cold-start.log
```

```bash
desktop-main.log
```

```bash
logs/runtime-units/*.log
```

```json
desktop-diagnostics.json
```

```bash
pnpm exec electron
```

```bash
pnpm dev start desktop
```

```bash
@nexu/desktop
```

```bash
desktop.log
```

--------------------------------

### Start Specific Local Service

Source: https://github.com/nexu-io/nexu/blob/main/AGENTS.md

Starts a single local development service. Available services are desktop, openclaw, controller, and web.

```bash
pnpm dev start <service>
```

--------------------------------

### Start Desktop App

Source: https://github.com/nexu-io/nexu/blob/main/specs/current/diagnostics/trigger-export-diagnostics.md

Starts the Nexu desktop application if it is not already running. This command should be used before attempting to export diagnostics if the status check fails.

```bash
pnpm desktop:start
```

--------------------------------

### Run Install Queue Test

Source: https://github.com/nexu-io/nexu/blob/main/docs/plans/2026-03-23-skillhub-install-queue.md

Execute the install queue test to verify failure when the module is not found. This command should result in a FAIL status.

```bash
pnpm test -- apps/controller/tests/install-queue.test.ts
```

--------------------------------

### Pi Coding Agent: Install and Run

Source: https://github.com/nexu-io/nexu/blob/main/apps/desktop/static/bundled-skills/coding-agent/SKILL.md

Installs the Pi Coding Agent globally and runs a task. PTY is recommended.

```bash
# Install: npm install -g @mariozechner/pi-coding-agent
bash pty:true workdir:~/project command:"pi 'Your task'"
```

--------------------------------

### Monitor Skill Installation

Source: https://github.com/nexu-io/nexu/blob/main/docs/plans/2026-03-27-skill-config-sync-manual-test.md

Watch for configuration updates while installing a skill via the SkillHub UI. Requires the inspector script to be running in watch mode.

```bash
node scripts/test-skill-sync.mjs watch
```

--------------------------------

### Test Disposal of Install Queue

Source: https://github.com/nexu-io/nexu/blob/main/docs/plans/2026-03-23-skillhub-install-queue.md

Confirms that the install queue stops processing new items after the dispose method is called. Only previously started items should complete.

```typescript
const executor = vi.fn(() => new Promise<void>(() => {}));
    queue = new InstallQueue({ executor, log: noopLog });

    queue.enqueue("weather", "managed");
    queue.dispose();

    // Should not start new items after dispose
    queue.enqueue("another", "managed");
    await Promise.resolve();
    expect(executor).toHaveBeenCalledTimes(1); // Only the first one
  });
```

--------------------------------

### Set Up Local Development Environment

Source: https://github.com/nexu-io/nexu/blob/main/AGENTS.md

Copies the example environment file to a new file for local development. This is an optional step for Windows users.

```bash
copy tools/dev/.env.example tools/dev/.env
```

--------------------------------

### Get Curated Slugs to Enqueue

Source: https://github.com/nexu-io/nexu/blob/main/docs/plans/2026-03-23-skillhub-install-queue.md

Returns a list of curated skill slugs that have not been previously installed or removed by the user. This method is used to determine which skills should be added to the installation queue.

```typescript
/**
 * Returns curated slugs that need installation.
 * Only returns slugs with NO record in the ledger (never seen before).
 */
getCuratedSlugsToEnqueue(): string[] {
  return CURATED_SKILL_SLUGS.filter(
    (slug) =>
      !this.db.isInstalled(slug, "curated") &&
      !this.db.isRemovedByUser(slug),
  );
}
```

--------------------------------

### Install and Run Docs Locally

Source: https://github.com/nexu-io/nexu/blob/main/CONTRIBUTING.md

Steps to set up and run the documentation site locally using pnpm. This is useful for previewing changes to the documentation.

```bash
cd docs
pnpm install   # first time only
pnpm dev
```

--------------------------------

### Start Desktop Application

Source: https://github.com/nexu-io/nexu/blob/main/docs/plans/2026-03-20-skillhub-single-dir-refactor.md

Launch the desktop application to observe its startup flow and verify its state.

```bash
pnpm start
```

--------------------------------

### Explicit Service Startup (Dev)

Source: https://github.com/nexu-io/nexu/blob/main/specs/guides/desktop-startup-flow.md

Demonstrates the command-line sequence for starting individual services during development. This includes ensuring build artifacts, launching Electron, and attaching to external runtimes.

```bash
pnpm dev start openclaw
pnpm dev start controller
pnpm dev start web
pnpm dev start desktop
  └─ tools/dev desktop service
       ├─ ensure desktop build artifacts
       ├─ launch Electron directly
       └─ attach desktop to external runtime targets

```

--------------------------------

### LaunchdManager Class for macOS Services

Source: https://github.com/nexu-io/nexu/blob/main/specs/designs/launchd-process-architecture/en.md

Manages macOS launchd services, including installation, uninstallation, starting, stopping, and status checks. Requires macOS platform.

```typescript
import { execFile } from "child_process";
import { promisify } from "util";
import * as fs from "fs/promises";
import * as path from "path";
import * as os from "os";

const execFileAsync = promisify(execFile);

export interface LaunchdService {
  label: string;
  plistPath: string;
  status: "running" | "stopped" | "unknown";
  pid?: number;
}

export class LaunchdManager {
  private readonly plistDir: string;
  private readonly uid: number;
  private readonly domain: string;

  constructor(opts?: { plistDir?: string }) {
    if (process.platform !== "darwin") {
      throw new Error("LaunchdManager only works on macOS");
    }
    this.plistDir = opts?.plistDir ?? path.join(os.homedir(), "Library/LaunchAgents");
    // Use os.userInfo() to get UID, avoid hardcoding
    this.uid = os.userInfo().uid;
    this.domain = `gui/${this.uid}`;
  }

  async installService(label: string, plistContent: string): Promise<void> {
    const plistPath = path.join(this.plistDir, `${label}.plist`);
    await fs.mkdir(this.plistDir, { recursive: true });
    await fs.writeFile(plistPath, plistContent, "utf8");

    // Check if service is already registered to avoid duplicate bootstrap
    const isRegistered = await this.isServiceRegistered(label);
    if (!isRegistered) {
      try {
        const { stdout, stderr } = await execFileAsync("launchctl", ["bootstrap", this.domain, plistPath]);
        if (stdout) console.log(`Bootstrap ${label}:`, stdout);
        if (stderr) console.warn(`Bootstrap ${label} warnings:`, stderr);
      } catch (err) {
        console.error(`Failed to bootstrap ${label}:`, err instanceof Error ? err.message : err);
        throw err;
      }
    }
  }

  async uninstallService(label: string): Promise<void> {
    try {
      await execFileAsync("launchctl", ["bootout", `${this.domain}/${label}`]);
    } catch (err) {
      // Service may not be running, log but don't throw
      console.warn(`Failed to bootout ${label}:`, err instanceof Error ? err.message : err);
    }
    try {
      await fs.unlink(path.join(this.plistDir, `${label}.plist`));
    } catch (err) {
      // plist may not exist
      console.warn(`Failed to remove plist for ${label}:`, err instanceof Error ? err.message : err);
    }
  }

  async startService(label: string): Promise<void> {
    await execFileAsync("launchctl", ["kickstart", `${this.domain}/${label}`]);
  }

  async stopService(label: string): Promise<void> {
    await execFileAsync("launchctl", ["kill", "SIGTERM", `${this.domain}/${label}`]);
  }

  /** Gracefully stop service: send SIGTERM then wait, force kill on timeout */
  async stopServiceGracefully(label: string, timeoutMs = 5000): Promise<void> {
    await this.stopService(label);

    const startTime = Date.now();
    while (Date.now() - startTime < timeoutMs) {
      const status = await this.getServiceStatus(label);
      if (status.status !== "running") {
        return;
      }
      await new Promise((r) => setTimeout(r, 200));
    }

    // Timeout, force stop
    console.warn(`Service ${label} did not stop in ${timeoutMs}ms, force killing`);
    await execFileAsync("launchctl", ["kill", "SIGKILL", `${this.domain}/${label}`]);
  }

  async restartService(label: string): Promise<void> {
    await execFileAsync("launchctl", ["kickstart", "-k", `${this.domain}/${label}`]);
  }

  async getServiceStatus(label: string): Promise<LaunchdService> {
    const plistPath = path.join(this.plistDir, `${label}.plist`);
    try {
      const { stdout } = await execFileAsync("launchctl", ["print", `${this.domain}/${label}`]);
      const pidMatch = stdout.match(/pid\s*=\s*(\d+)/);
      const pid = pidMatch ? parseInt(pidMatch[1], 10) : undefined;
      const isRunning = stdout.includes("state = running");
      return { label, plistPath, status: isRunning ? "running" : "stopped", pid };
    } catch {
      return { label, plistPath, status: "unknown" };
    }
  }

  /** Check if service is registered with launchd */
  async isServiceRegistered(label: string): Promise<boolean> {
    try {
      await execFileAsync("launchctl", ["print", `${this.domain}/${label}`]);
      return true;
    } catch {
      return false;
    }
  }

  /** Check if plist file exists */
  async hasPlistFile(label: string): Promise<boolean> {
    try {
      await fs.access(path.join(this.plistDir, `${label}.plist`));
      return true;
    } catch {
      return false;
    }
  }

  /** Check if service is installed (plist exists and registered) */
  async isServiceInstalled(label: string): Promise<boolean> {
    const hasPlist = await this.hasPlistFile(label);
    const isRegistered = await this.isServiceRegistered(label);
    return hasPlist && isRegistered;
  }
}

```

--------------------------------

### IPC Channels for SkillHub

Source: https://github.com/nexu-io/nexu/blob/main/specs/plans/2026-03-17-skillhub-desktop-integration.md

Defines the IPC channel types used for communication between the main process and renderer for SkillHub operations. These include getting the catalog, installing, uninstalling, and refreshing skills.

```typescript
// shared/host.ts — add to HostInvokePayloadMap
"skillhub:get-catalog":    undefined
"skillhub:install":        { slug: string }
"skillhub:uninstall":      { slug: string }
"skillhub:refresh-catalog": undefined

// Results
"skillhub:get-catalog":    { skills: MinimalSkill[], meta: CatalogMeta }
"skillhub:install":        { ok: boolean, error?: string }
"skillhub:uninstall":      { ok: boolean, error?: string }
"skillhub:refresh-catalog": { ok: boolean, skillCount: number }
```

--------------------------------

### Migration Log Output Example

Source: https://github.com/nexu-io/nexu/blob/main/docs/plans/2026-03-27-workspace-skill-visibility-and-upgrade-compat.md

Provides an example of the log output during startup reconciliation, showing the number of shared skills installed/uninstalled and a breakdown of agent-installed workspace skills detected.

```plaintext
[skillhub] Startup reconciliation:
[skillhub]   Shared skills: 12 installed, 2 uninstalled
[skillhub]   Workspace scan:
[skillhub]     agent bot-abc: 3 skills (my-tool, web-scraper, calendar)
[skillhub]     agent bot-xyz: 1 skill (ticket-helper)
[skillhub]   New workspace records: 4 (first-time detection)
[skillhub]   Reconciliation complete
```

--------------------------------

### Common launchd Commands for Nexu Services

Source: https://github.com/nexu-io/nexu/blob/main/specs/designs/launchd-process-architecture/en.md

A collection of bash commands to manage Nexu services using launchctl, including listing, viewing details, starting, restarting, stopping, installing, and uninstalling plists.

```bash
# List all Nexu services
launchctl list | grep nexu
```

```bash
# View service details
launchctl print gui/$(id -u)/io.nexu.controller
```

```bash
# Start service
launchctl kickstart gui/$(id -u)/io.nexu.controller
```

```bash
# Restart service (-k = kill first)
launchctl kickstart -k gui/$(id -u)/io.nexu.controller
```

```bash
# Stop service
launchctl kill SIGTERM gui/$(id -u)/io.nexu.controller
```

```bash
# Install plist
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/io.nexu.controller.plist
```

```bash
# Uninstall service
launchctl bootout gui/$(id -u)/io.nexu.controller
```

--------------------------------

### Local Development Baseline Verification

Source: https://github.com/nexu-io/nexu/blob/main/TASK.mac.md

This sequence of commands verifies the core local development setup on macOS. It ensures that all services (shared, controller, web, openclaw) can be built, started, monitored, and stopped correctly.

```bash
pnpm --filter @nexu/shared build
pnpm dev start
pnpm dev logs desktop
pnpm dev status desktop
pnpm dev status controller
pnpm dev status web
pnpm dev status openclaw
pnpm dev stop
```

--------------------------------

### Unified Bootstrap Logic

Source: https://github.com/nexu-io/nexu/blob/main/specs/guides/desktop-startup-flow.md

Details the steps involved in the unified bootstrap process for services, including reading previous session data, checking service status, and deciding whether to attach, restart, or install and start.

```plaintext
1. Read runtime-ports.json (from previous session)
2. Check each service status via launchctl print
3. Per-service decision:
   ├─ Running + healthy + ports match → KEEP (attach)
   ├─ Running + unhealthy → TEARDOWN + restart
   └─ Not running → INSTALL plist + START
4. Start embedded web server
5. Write runtime-ports.json
```

--------------------------------

### Update catalog route handler to resolve agent names

Source: https://github.com/nexu-io/nexu/blob/main/docs/plans/2026-03-27-workspace-skill-scanner.md

Modify the GET /api/v1/skillhub/catalog route handler to enrich installed skills with agent names. It fetches bot configurations to map agent IDs to their corresponding names, enhancing the API response.

```typescript
async (c) => {
  const catalog = container.skillhubService.catalog.getCatalog();
  const queue = [...container.skillhubService.queue.getQueue()];
  const bots = await container.configStore.listBots();
  const botNameMap = new Map(bots.map((b) => [b.id, b.name]));

  const installedSkills = catalog.installedSkills.map((skill) => ({
    ...skill,
    agentName: skill.agentId ? (botNameMap.get(skill.agentId) ?? null) : null,
  }));

  return c.json({ ...catalog, installedSkills, queue }, 200);
}
```

--------------------------------

### Setup LibTV Video Skill API Key

Source: https://github.com/nexu-io/nexu/blob/main/apps/desktop/static/bundled-skills/libtv-video/SKILL.md

Configure your API key and default video ratio for the LibTV skill. This is a one-time setup or when updating your key.

```bash
python3 scripts/libtv_video.py setup --api-key <your_key> --video-ratio 16:9
```

--------------------------------

### MCP Server Integration Examples

Source: https://github.com/nexu-io/nexu/blob/main/specs/designs/skill-system-architecture-comparison.md

Demonstrates how different agents and configurations can utilize a service exposed as an MCP server, enabling cross-platform compatibility.

```text
By exposing the cloud service as an MCP server, it becomes usable by:
- Nexu — native integration via controller
- Claude Code — `claude mcp add nexu-cloud -- ...`
- Codex — `[mcp_servers.nexu-cloud]` in config.toml
- Cursor, Windsurf, etc. — any MCP-compatible agent
```

--------------------------------

### Parallel npm Dependency Installation

Source: https://github.com/nexu-io/nexu/blob/main/docs/plans/2026-03-18-parallel-curated-skill-install.md

Installs npm dependencies in parallel for all successfully installed skills after the main download process is complete. Logs any rejections during the dependency installation.

```typescript
// Install npm deps in parallel for skills that have package.json
if (installed.length > 0) {
  const depResults = await Promise.allSettled(
    installed.map((slug) =>
      this.installSkillDeps(resolve(this.curatedSkillsDir, slug), slug),
    ),
  );
  for (const r of depResults) {
    if (r.status === "rejected") {
      this.log("warn", `npm dep install rejected: ${r.reason}`);
    }
  }
}
```

--------------------------------

### Install a Skill

Source: https://github.com/nexu-io/nexu/blob/main/apps/desktop/static/bundled-skills/clawhub/SKILL.md

Install a skill from ClawHub by its name. You can also specify a specific version to install.

```bash
clawhub install my-skill
```

```bash
clawhub install my-skill --version 1.2.3
```

--------------------------------

### Run Web Development Server

Source: https://github.com/nexu-io/nexu/blob/main/AGENTS.md

Starts the development server specifically for the web application package.

```bash
pnpm --filter @nexu/web dev
```

--------------------------------

### OpenClaw Gateway Startup

Source: https://github.com/nexu-io/nexu/blob/main/specs/guides/desktop-startup-flow.md

Outlines the steps for starting the OpenClaw gateway, including reading configuration, loading plugins, and establishing communication channels.

```plaintext
OpenClaw gateway startup (~5-7s from cold)
  ├─ Read openclaw.json (gateway.port from env.openclawGatewayPort)
  ├─ Load plugins: feishu, openclaw-weixin, nexu-runtime-model, nexu-platform-bootstrap
  ├─ Start channels: feishu (WebSocket), weixin (long-polling)
  └─ Gateway WS reachable → health loop detects → wsClient.retryNow()
```

--------------------------------

### Run Beta Build Tests with Custom URLs

Source: https://github.com/nexu-io/nexu/blob/main/e2e/desktop/README.md

Overrides for downloading beta artifacts using environment variables for DMG and ZIP URLs. Example for an Intel Mac.

```bash
# Beta (Intel Mac example)
NEXU_DESKTOP_E2E_DMG_URL=https://desktop-releases.nexu.io/beta/x64/nexu-latest-beta-mac-x64.dmg \
NEXU_DESKTOP_E2E_ZIP_URL=https://desktop-releases.nexu.io/beta/x64/nexu-latest-beta-mac-x64.zip \
npm run download && npm test
```

--------------------------------

### Install Runner as User-Level LaunchAgent

Source: https://github.com/nexu-io/nexu/blob/main/e2e/desktop/README.md

Install the runner to run within the GUI session without requiring sudo. This involves creating a .plist file in ~/Library/LaunchAgents and using launchctl to bootstrap it. Ensure the PATH includes the Node.js bin directory.

```bash
# Create ~/Library/LaunchAgents/com.github.actions-runner.plist with:
#   ProgramArguments: ~/actions-runner/run.sh
#   RunAtLoad: true
#   KeepAlive: true
#   PATH must include Node.js bin dir
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.github.actions-runner.plist
```

--------------------------------

### Start Full Stack Development Server

Source: https://github.com/nexu-io/nexu/blob/main/docs/plans/2026-03-23-skillhub-install-queue.md

This command starts the full stack development environment, including the controller and the web frontend. It is used for manual verification of frontend interactions.

```bash
pnpm dev
```

--------------------------------

### Verify Installed Skills via Catalog API

Source: https://github.com/nexu-io/nexu/blob/main/docs/plans/2026-03-21-verify-curated-skills.md

Fetches the skill catalog from the controller and verifies if the previously installed skills are listed as installed. It checks both the presence in installedSlugs and details in installedSkills.

```bash
curl -s "$CONTROLLER_URL/api/v1/skillhub/catalog" | node -e "
  let d=''; process.stdin.on('data',c=>d+=c); process.stdin.on('end',()=>{
    const catalog = JSON.parse(d);
    const target = ['baoyu-xhs-images','deep-research','research-to-diagram','qiaomu-mondo-poster-design'];
    for (const slug of target) {
      const installed = catalog.installedSlugs.includes(slug);
      const detail = catalog.installedSkills.find(s => s.slug === slug);
      console.log(slug + ': ' + (installed ? 'INSTALLED' : 'MISSING') +
        (detail ? ' name=\'" + detail.name + "\'' : ' (no detail)'));
    }
  })"
```

--------------------------------

### Electron Main Process Startup Flow

Source: https://github.com/nexu-io/nexu/blob/main/specs/guides/desktop-startup-flow.md

Illustrates the sequence of operations in the Electron main process during application startup, including port allocation, window creation, and launchd cold start.

```plaintext
Electron main process
  ├─ allocateDesktopRuntimePorts()          # Probe ports, auto-offset if occupied
  │    ├─ controller: 50800 (→50801 if occupied)
  │    ├─ web: 50810 (→50811 if occupied)
  │    └─ openclaw: 18789 (→18790 if occupied)
  ├─ createMainWindow()                     # loadFile(dist/index.html)
  └─ runLaunchdColdStart()
       ├─ resolveLaunchdPaths()
       │    └─ (packaged) ensurePackagedOpenclawSidecar()  # Extract tar with retry
       └─ bootstrapWithLaunchd()            # Unified attach/cold-start flow
```

--------------------------------

### Pure Auto-Increment Example

Source: https://github.com/nexu-io/nexu/blob/main/nexu-skills/skills/feishu-bitable/references/field-properties.md

Example of configuring a field for pure auto-incrementing numbers.

```json
{
  "type": 1005,
  "field_name": "编号",
  "property": {
    "auto_serial": {
      "type": "auto_increment_number"
    }
  }
}
```

--------------------------------

### Detect Installed Skills

Source: https://github.com/nexu-io/nexu/blob/main/specs/plans/2026-03-17-skillhub-desktop-integration.md

Scans the specified skills directory to identify installed skills by checking for the presence of a 'SKILL.md' file. This is used to determine which skills are currently installed in the Nexu Desktop runtime.

```typescript
const installedSlugs = new Set(
  readdirSync(skillsDir)
    .filter(name => existsSync(join(skillsDir, name, "SKILL.md")))
);
// In renderer: skill.installed = installedSlugs.has(skill.slug)
```

--------------------------------

### Test for Installed Skill Slugs

Source: https://github.com/nexu-io/nexu/blob/main/docs/plans/2026-03-27-skill-install-config-sync.md

This test verifies that the sync service correctly includes installed skill slugs in the compiled agent configuration. It installs a skill, triggers a sync, and then checks the written configuration file.

```typescript
it("includes installed skill slugs in compiled agent config", async () => {
  // Install a skill in the skill DB
  skillDb.recordInstall("my-skill", "managed");

  const { configPushed } = await syncService.syncAllImmediate();

  // Read the written config file
  const written = JSON.parse(
    readFileSync(env.openclawConfigPath, "utf-8"),
  );
  expect(written.agents.list[0].skills).toEqual(["my-skill"]);
  expect(configPushed).toBe(true);
});
```

--------------------------------

### Image+Text Generation (Image-to-Video)

Source: https://github.com/nexu-io/nexu/blob/main/apps/desktop/static/bundled-skills/libtv-video/SKILL.md

First, upload the image using the 'upload' command to get a URL. Then, use this URL within the description when creating the session for image-to-video generation.

```bash
# 1. Upload the image first
python3 scripts/libtv_video.py upload --file /path/to/image.png
# Output: url=https://libtv-res.liblib.art/...
```

```bash
# 2. Create session with the image URL in the message
python3 scripts/libtv_video.py create-session "user's description reference: {oss_url}"
```

--------------------------------

### Custom Style Fusion Example

Source: https://github.com/nexu-io/nexu/blob/main/apps/desktop/static/bundled-skills/qiaomu-mondo-poster-design/references/artist-styles.md

An example demonstrating how to apply the custom style fusion template to create a specific poster aesthetic. This example blends geometric abstraction, neon futurism, and flat color blocks.

```plaintext
Blade Runner in Mondo poster style, combining Saul Bass's geometric abstraction
with Kilian Eng's neon futurism and Toulouse-Lautrec's flat color blocks, unified
through angular architecture, creating a retro-futuristic neo-noir aesthetic with
2-color duotone: electric blue and blade-orange
```

--------------------------------

### Horror Comedy Example

Source: https://github.com/nexu-io/nexu/blob/main/apps/desktop/static/bundled-skills/qiaomu-mondo-poster-design/references/genre-templates.md

Example of a horror-comedy poster, blending absurd humor with gruesome imagery.

```markdown
Zombie hand holding ice cream cone in Mondo horror-comedy poster style, playful
horror juxtaposition, 3-color print: mint green, blood red, cream, vintage
1985 horror-comedy aesthetic, screen print with halftone shadows, absurd
gruesome humor, comedic monster imagery
```

--------------------------------

### Copy Environment File (POSIX)

Source: https://github.com/nexu-io/nexu/blob/main/AGENTS.md

Copies the example environment file to a new file for local development on POSIX systems.

```bash
cp tools/dev/.env.example tools/dev/.env
```

--------------------------------

### Install and Build Shared Package

Source: https://github.com/nexu-io/nexu/blob/main/AGENTS.md

Installs project dependencies and builds the shared package for local development.

```bash
pnpm install
pnpm --filter @nexu/shared build
```

--------------------------------

### Thread Handling Example

Source: https://github.com/nexu-io/nexu/blob/main/specs/designs/openclaw-architecture-internals.md

Illustrates how threads create independent sub-sessions while potentially inheriting context from a parent session.

```text
#general
├── Bob: "@Alice Assistant 查报表"         → session: ...channel:c_general
│   └── Alice Assistant: "好的..."
│       └── Bob: "再详细点"                → session: ...channel:c_general:thread:1234567890.123
│           └── Alice Assistant: "详细如下..."
```

--------------------------------

### Example Fact Card

Source: https://github.com/nexu-io/nexu/blob/main/apps/desktop/static/bundled-skills/deep-research/templates/fact-card.md

An example of a filled-out fact card documenting the Claude Skills trigger mechanism.

```markdown
## 事实卡片 #001

**主题**：Claude Skills 触发机制

**事实陈述**：
Skills 是 model-invoked（模型调用的），Claude 会根据用户请求与 SKILL.md 中 description 字段的匹配度决定是否启用该 Skill，不需要用户显式调用。

**出处**：
- 来源：Claude Code 官方文档
- 链接：https://code.claude.com/docs/en/skills
- 章节：How skills work
- 获取日期：2025-01-11

**置信度**：✅ 高

**置信度理由**：
官方文档明确说明："Claude will automatically use relevant skills when they match your request"

**相关事实**：#002（渐进式加载）, #003（SKILL.md 结构）

**备注**：与传统函数的显式调用形成对比
```

--------------------------------

### Launch Packaged App

Source: https://github.com/nexu-io/nexu/blob/main/docs/plans/2026-04-07-skills-watcher-nudge-manual-test.md

Open the newly built macOS desktop application. This command assumes the app is in the 'mac-arm64' release directory, adjust if necessary.

```bash
open apps/desktop/release/mac-arm64/Nexu.app
```

--------------------------------

### Check LibTV Video Skill Configuration

Source: https://github.com/nexu-io/nexu/blob/main/apps/desktop/static/bundled-skills/libtv-video/SKILL.md

Verify your API key configuration and connection status before generating content. This command helps diagnose setup issues.

```bash
python3 scripts/libtv_video.py check
```

--------------------------------

### Skill Lifecycle Flow

Source: https://github.com/nexu-io/nexu/blob/main/specs/plans/2026-03-17-skillhub-desktop-integration.md

Illustrates the user journey from discovering skills in the community to installing and using them within the Nexu Desktop environment.

```text
Discovery ──────► Install ──────► Use

Browse Community   clawhub install   Skill appears in
tab with search,   <slug> via IPC    Nexu Desktop runtime
sort, tag filter   → atomic extract  skills dir
                   to runtime/       → OpenClaw watcher
                   openclaw/state/   detects SKILL.md
                   skills/<slug>/    → session rebuilds
```

--------------------------------

### Commit Install Queue Types

Source: https://github.com/nexu-io/nexu/blob/main/docs/plans/2026-03-23-skillhub-install-queue.md

Stage and commit the newly added type definitions for the install queue to version control.

```bash
git add apps/controller/src/services/skillhub/types.ts apps/controller/src/services/skillhub/index.ts
git commit -m "feat(skillhub): add install queue types"
```

--------------------------------

### Query Gateway Startup/Recovery Events

Source: https://github.com/nexu-io/nexu/blob/main/skills/localdev/datadog/SKILL.md

Use this query to track gateway startup and recovery events for the 'nexu-gateway' service. It looks for logs containing 'starting gateway', 'gateway is ready', or 'spawned openclaw' within the last hour.

```bash
curl -s "https://api.datadoghq.com/api/v2/logs/events/search" \
  -H "DD-API-KEY: $DD_API_KEY" \
  -H "DD-APPLICATION-KEY: $DD_APP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "query": "service:nexu-gateway (\"starting gateway\" OR \"gateway is ready\" OR \"spawned openclaw\")",
      "from": "now-1h",
      "to": "now"
    },
    "sort": "timestamp",
    "page": {"limit": 30}
  }'
```