@kvell007/embed-labs-cli 0.1.0-alpha.6 → 0.1.0-alpha.60

package/dist/local-toolchain.js

@@ -8,9 +8,9 @@ import { Readable } from "node:stream";
 import { pipeline } from "node:stream/promises";
 import { fileURLToPath } from "node:url";
 const DEFAULT_RELEASE_ROOT = "/Volumes/LLVM-TSPI/tspi-rk3566-llvm-release-minimal";
-const DEFAULT_QT_SMOKE_SOURCE = "/Users/kvell/kk-project/DBT-Agent-Project/llvm-build-tspi/qt-smoke";
-const DEFAULT_METADATA_ROOT = "/Users/kvell/kk-project/DBT-Agent-Project/llvm-build-tspi/embedlabs-release";
 const DEFAULT_BOARD_ID = "taishanpi-1m-rk3566";
+const PICO2W_RP2350_BOARD_ID = "pico2w-rp2350-monitor";
+const COLOREASYPICO2_RP2350_BOARD_ID = "coloreasypico2-rp2350-monitor";
 const DEFAULT_CHANNEL = "stable";
 const DEFAULT_DOWNLOAD_BASE_URL = "https://download.embedboard.com";
 const DOWNLOAD_REQUEST_TIMEOUT_MS = 12_000;
@@ -20,9 +20,15 @@ const BUILT_IN_CHANNEL = {
     packages: [
         { id: "embedlabs.tools.vendor.rockchip", version: "1.0.0", manifest: "" },
         { id: "embedlabs.tools.common.llvm", version: "22.1.3", manifest: "" },
+        { id: "embedlabs.tools.common.arm-none-eabi", version: "15.2.rel1", manifest: "" },
         { id: "embedlabs.tools.common.e2fsprogs", version: "1.0.0", manifest: "" },
+        { id: "embedlabs.tools.runtime.qtquick-live-preview", version: "1.0.33", manifest: "" },
+        { id: "embedlabs.tools.runtime.rp2350-monitor", version: "1.0.33", manifest: "" },
         { id: "embedlabs.family.rk356x", version: "1.0.0", manifest: "" },
-        { id: "embedlabs.board.taishanpi.1m-rk3566", version: "1.0.31", manifest: "" }
+        { id: "embedlabs.family.rp2350", version: "1.0.0", manifest: "" },
+        { id: "embedlabs.board.taishanpi.1m-rk3566", version: "1.0.33", manifest: "" },
+        { id: "embedlabs.board.pico2w.rp2350-monitor", version: "1.0.33", manifest: "" },
+        { id: "embedlabs.board.coloreasypico2.rp2350-monitor", version: "1.0.33", manifest: "" }
     ]
 };
 const BUILT_IN_MANIFESTS = {
@@ -42,6 +48,14 @@ const BUILT_IN_MANIFESTS = {
         hosts: ["darwin-arm64", "linux-x86_64"],
         provides: ["llvm.clang", "llvm.clangxx", "llvm.ld_lld", "llvm.ar", "llvm.objcopy", "llvm.readelf"]
     },
+    "embedlabs.tools.common.arm-none-eabi": {
+        schema: "embedlabs.package.v1",
+        id: "embedlabs.tools.common.arm-none-eabi",
+        version: "15.2.rel1",
+        kind: "tools",
+        hosts: ["darwin-arm64"],
+        provides: ["arm-none-eabi.gcc", "arm-none-eabi.g++", "arm-none-eabi.objcopy", "picotool"]
+    },
     "embedlabs.tools.common.e2fsprogs": {
         schema: "embedlabs.package.v1",
         id: "embedlabs.tools.common.e2fsprogs",
@@ -50,6 +64,22 @@ const BUILT_IN_MANIFESTS = {
         hosts: ["darwin-arm64", "linux-x86_64"],
         provides: ["ext4.mke2fs", "ext4.resize2fs", "fakeroot"]
     },
+    "embedlabs.tools.runtime.qtquick-live-preview": {
+        schema: "embedlabs.package.v1",
+        id: "embedlabs.tools.runtime.qtquick-live-preview",
+        version: "1.0.33",
+        kind: "tools",
+        hosts: ["darwin-arm64", "linux-x86_64"],
+        provides: ["qtquick.live_preview", "qtquick.live_preview.inspector", "qtquick.live_preview.feedback"]
+    },
+    "embedlabs.tools.runtime.rp2350-monitor": {
+        schema: "embedlabs.package.v1",
+        id: "embedlabs.tools.runtime.rp2350-monitor",
+        version: "1.0.33",
+        kind: "tools",
+        hosts: ["darwin-arm64", "linux-x86_64"],
+        provides: ["rp2350.monitor.cli", "rp2350.monitor.logic_analyzer", "rp2350.monitor.logic_decode"]
+    },
     "embedlabs.family.rk356x": {
         schema: "embedlabs.package.v1",
         id: "embedlabs.family.rk356x",
@@ -62,10 +92,21 @@ const BUILT_IN_MANIFESTS = {
             { id: "embedlabs.tools.common.e2fsprogs", version: "^1.0.0" }
         ]
     },
+    "embedlabs.family.rp2350": {
+        schema: "embedlabs.package.v1",
+        id: "embedlabs.family.rp2350",
+        version: "1.0.0",
+        kind: "family",
+        family: "rp2350",
+        requires: [
+            { id: "embedlabs.tools.common.arm-none-eabi", version: "15.x", roles: ["compile", "uf2"] },
+            { id: "embedlabs.tools.runtime.rp2350-monitor", version: "^1.0.33", roles: ["hardware-control", "logic-analyzer", "debug-probe"] }
+        ]
+    },
     "embedlabs.board.taishanpi.1m-rk3566": {
         schema: "embedlabs.package.v1",
         id: "embedlabs.board.taishanpi.1m-rk3566",
-        version: "1.0.31",
+        version: "1.0.33",
         kind: "board",
         family: "rk356x",
         board: "TaishanPi",
@@ -74,20 +115,67 @@ const BUILT_IN_MANIFESTS = {
             { id: "embedlabs.family.rk356x", version: "^1.0.0" },
             { id: "embedlabs.tools.vendor.rockchip", version: "^1.0.0", roles: ["flash", "resource-image"] },
             { id: "embedlabs.tools.common.llvm", version: "22.x", roles: ["compile"] },
-            { id: "embedlabs.tools.common.e2fsprogs", version: "^1.0.0", roles: ["userdata-image"] }
+            { id: "embedlabs.tools.common.e2fsprogs", version: "^1.0.0", roles: ["userdata-image"] },
+            { id: "embedlabs.tools.runtime.qtquick-live-preview", version: "^1.0.33", roles: ["qtquick-preview"] }
         ],
         build_modes: ["local-llvm"]
+    },
+    "embedlabs.board.pico2w.rp2350-monitor": {
+        schema: "embedlabs.package.v1",
+        id: "embedlabs.board.pico2w.rp2350-monitor",
+        version: "1.0.33",
+        kind: "board",
+        display_name: "Pico 2 W",
+        family: "rp2350",
+        board: "Pico 2 W",
+        board_id: PICO2W_RP2350_BOARD_ID,
+        requires: [
+            { id: "embedlabs.family.rp2350", version: "^1.0.0" },
+            { id: "embedlabs.tools.common.arm-none-eabi", version: "15.x", roles: ["compile", "uf2", "picotool"] },
+            { id: "embedlabs.tools.runtime.rp2350-monitor", version: "^1.0.33", roles: ["hardware-control", "logic-analyzer", "debug-probe"] }
+        ],
+        build_modes: ["local-pico-sdk", "optional-rp2350-monitor"]
+    },
+    "embedlabs.board.coloreasypico2.rp2350-monitor": {
+        schema: "embedlabs.package.v1",
+        id: "embedlabs.board.coloreasypico2.rp2350-monitor",
+        version: "1.0.33",
+        kind: "board",
+        display_name: "ColorEasyPICO2",
+        family: "rp2350",
+        board: "ColorEasyPICO2",
+        board_id: COLOREASYPICO2_RP2350_BOARD_ID,
+        requires: [
+            { id: "embedlabs.family.rp2350", version: "^1.0.0" },
+            { id: "embedlabs.tools.common.arm-none-eabi", version: "15.x", roles: ["compile", "uf2", "picotool"] },
+            { id: "embedlabs.tools.runtime.rp2350-monitor", version: "^1.0.33", roles: ["hardware-control", "logic-analyzer", "debug-probe"] }
+        ],
+        build_modes: ["local-pico-sdk", "optional-rp2350-monitor"]
     }
 };
 const INSTALL_COPY_PATHS = [
     "toolchain/llvm-cross",
-    "toolchain/host/aarch64-buildroot-linux-gnu/sysroot",
+    "toolchain/host",
+    "toolchain/host-tools",
+    "toolchain/qt6-rk3566-llvm-toolchain.cmake",
     "qt-target/qt6-rk3566-llvm-6.8.3",
+    "qt-host/qt6-host-macos-6.8.3",
     "tools/mac",
+    "toolkit-runtime/qtquick-live-preview",
+    "toolkit-runtime/rp2350-monitor",
+    "rp2350-sdk",
+    "rp2350-initial-firmware",
+    "rp2350-examples",
     "images/current",
     "userdata/rootfs",
-    "boot-workspace/kernel-tree"
+    "boot-workspace",
+    "README.md",
+    "meta",
+    "scripts",
+    "support",
+    "third_party"
 ];
+const LOCAL_TOOLCHAIN_INSTALL_MODES = ["minimal", "runtime", "compile", "qt", "firmware", "full", "images"];
 export function defaultLocalReleaseRoot() {
     return process.env.EMBEDLABS_LOCAL_RELEASE_ROOT?.trim()
         || process.env.EMBEDLABS_RELEASE_ROOT?.trim()
@@ -102,12 +190,13 @@ export async function latestLocalToolchain(options = {}) {
     if (!board) {
         throw new Error(`No local toolchain board package found for ${boardId}.`);
     }
+    const canonicalBoardId = boardIdForPackageManifest(board);
     const packages = resolvePackageRefs(boardPackageId, channel, manifests);
     let download;
     let downloadError;
     try {
         download = await resolveLocalToolchainDownloadPlan({
-            boardId,
+            boardId: canonicalBoardId,
             channel: channelName,
             host: hostId(),
             toolchain: "llvm"
@@ -116,11 +205,14 @@ export async function latestLocalToolchain(options = {}) {
     catch (error) {
         downloadError = error instanceof Error ? error.message : String(error);
     }
+    if (!download && isNativeWindowsTaishanPiHost(canonicalBoardId, hostId())) {
+        downloadError = taishanPiWindowsRequirementMessage(hostId());
+    }
     return {
-        board_id: boardId,
+        board_id: canonicalBoardId,
         channel: channel.channel,
         host: hostId(),
-        version: board.version,
+        version: download?.version ?? board.version,
         metadata_root: metadataRoot,
         packages,
         download,
@@ -132,11 +224,36 @@ export async function currentLocalToolchain(installRoot, boardId = DEFAULT_BOARD
     const registryPath = localToolchainRegistryPath(root);
     try {
         const registry = JSON.parse(await readFile(registryPath, "utf8"));
+        const environments = registry.environments;
+        const boardInstall = environments?.[normalizeBoardId(boardId)];
+        if (boardInstall?.release_root) {
+            return {
+                installed: true,
+                board_id: typeof boardInstall.board_id === "string" ? boardInstall.board_id : boardId,
+                version: typeof boardInstall.version === "string" ? boardInstall.version : undefined,
+                mode: typeof boardInstall.mode === "string" ? boardInstall.mode : undefined,
+                release_root: boardInstall.release_root,
+                registry_path: registryPath,
+                install_root: root,
+                channel: typeof boardInstall.channel === "string" ? boardInstall.channel : undefined,
+                packages: Array.isArray(boardInstall.packages) ? boardInstall.packages : undefined
+            };
+        }
         const releaseRoot = typeof registry.release_root === "string" ? registry.release_root : undefined;
+        const registryBoardId = typeof registry.board_id === "string" ? registry.board_id : boardId;
+        if (releaseRoot && normalizeBoardId(registryBoardId) !== normalizeBoardId(boardId)) {
+            return {
+                installed: false,
+                board_id: boardId,
+                registry_path: registryPath,
+                install_root: root
+            };
+        }
         return {
             installed: !!releaseRoot,
-            board_id: typeof registry.board_id === "string" ? registry.board_id : boardId,
+            board_id: registryBoardId,
             version: typeof registry.version === "string" ? registry.version : undefined,
+            mode: typeof registry.mode === "string" ? registry.mode : undefined,
             release_root: releaseRoot,
             registry_path: registryPath,
             install_root: root,
@@ -153,48 +270,248 @@ export async function currentLocalToolchain(installRoot, boardId = DEFAULT_BOARD
         };
     }
 }
+async function discoverInstalledLocalToolchains(installRoot, current) {
+    const installed = new Map();
+    if (current.installed && current.release_root) {
+        installed.set(normalizeBoardId(current.board_id), {
+            board_id: current.board_id,
+            version: current.version,
+            channel: current.channel,
+            mode: current.mode,
+            release_root: current.release_root
+        });
+    }
+    const toolchainsRoot = join(installRoot, "toolchains");
+    let boardEntries;
+    try {
+        boardEntries = await readdir(toolchainsRoot, { withFileTypes: true });
+    }
+    catch {
+        return installed;
+    }
+    for (const boardEntry of boardEntries) {
+        if (!boardEntry.isDirectory()) {
+            continue;
+        }
+        const boardId = normalizeBoardId(boardEntry.name);
+        if (installed.has(boardId)) {
+            continue;
+        }
+        const boardRoot = join(toolchainsRoot, boardEntry.name);
+        let versionEntries;
+        try {
+            versionEntries = await readdir(boardRoot, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        const versions = versionEntries
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => entry.name)
+            .sort(compareVersionLike)
+            .reverse();
+        const version = versions[0];
+        if (!version) {
+            continue;
+        }
+        installed.set(boardId, {
+            board_id: boardId,
+            version,
+            release_root: join(boardRoot, version)
+        });
+    }
+    return installed;
+}
+export async function listLocalToolchainEnvironments(options = {}) {
+    const channelName = options.channel ?? DEFAULT_CHANNEL;
+    const host = hostId();
+    const installRoot = resolveInstallRoot(options.installRoot);
+    const registryPath = localToolchainRegistryPath(installRoot);
+    const { channel, manifests, metadataRoot } = await loadLocalToolchainMetadata(options.metadataRoot, channelName);
+    const current = await currentLocalToolchain(installRoot);
+    const installedByBoard = await discoverInstalledLocalToolchains(installRoot, current);
+    const boardManifests = [...manifests.values()]
+        .filter((manifest) => manifest.kind === "board")
+        .filter((manifest) => {
+        if (!options.boardId) {
+            return true;
+        }
+        const normalizedFilter = normalizeBoardId(options.boardId);
+        return boardIdForPackageManifest(manifest) === normalizedFilter
+            || manifest.id === options.boardId
+            || manifest.id === packageIdForBoardFilter(options.boardId);
+    })
+        .sort((left, right) => boardIdForPackageManifest(left).localeCompare(boardIdForPackageManifest(right)));
+    const environments = [];
+    const wslStatus = host.startsWith("win32-")
+        ? await windowsWslStatus()
+        : undefined;
+    for (const board of boardManifests) {
+        const boardId = boardIdForPackageManifest(board);
+        const packages = resolvePackageRefs(board.id, channel, manifests);
+        const hostSupport = packageHostSupport(packages, manifests, host);
+        let download;
+        let downloadError;
+        try {
+            download = await resolveLocalToolchainDownloadPlan({
+                boardId,
+                channel: channelName,
+                host,
+                toolchain: "llvm"
+            });
+        }
+        catch (error) {
+            downloadError = error instanceof Error ? error.message : String(error);
+        }
+        if (!download && isNativeWindowsTaishanPiHost(boardId, host)) {
+            downloadError = taishanPiWindowsRequirementMessage(host);
+        }
+        const latestVersion = download?.version ?? board.version;
+        const currentForBoard = await currentLocalToolchain(installRoot, boardId);
+        const installedCandidate = currentForBoard.installed
+            ? currentForBoard
+            : installedByBoard.get(normalizeBoardId(boardId));
+        const installed = installedCandidate
+            ? {
+                version: installedCandidate.version,
+                channel: installedCandidate.channel,
+                mode: installedCandidate.mode,
+                release_root: installedCandidate.release_root
+            }
+            : undefined;
+        const updateAvailable = !!installed?.version && installed.version !== latestVersion;
+        const nativeWindowsTaishanPi = isNativeWindowsTaishanPiHost(boardId, host);
+        const execution = nativeWindowsTaishanPi
+            ? taishanPiWindowsExecutionRoute(host, wslStatus)
+            : {
+                kind: "native",
+                supported: !!download || !!installed || hostSupport.supported,
+                actual_host: host
+            };
+        const effectiveHostSupport = nativeWindowsTaishanPi
+            ? { supported: false, unsupportedPackages: ["taishanpi-1m-rk3566 native Windows toolchain"] }
+            : download || installed
+                ? { supported: true, unsupportedPackages: [] }
+                : hostSupport;
+        const status = !effectiveHostSupport.supported
+            ? "unsupported_host"
+            : updateAvailable
+                ? "update_available"
+                : installed
+                    ? "installed"
+                    : "available";
+        const mode = download?.default_mode ?? "qt";
+        const installModes = download
+            ? localToolchainInstallModesForDownload(download)
+            : installed?.mode
+                ? [installed.mode]
+                : localToolchainInstallModesForDownload(download);
+        environments.push({
+            board_id: boardId,
+            package_id: board.id,
+            display_name: board.display_name || [board.board, board.variant].filter(Boolean).join(" ") || boardId,
+            family: board.family,
+            variant: board.variant,
+            channel: channel.channel,
+            host,
+            status,
+            supported_host: effectiveHostSupport.supported,
+            unsupported_packages: effectiveHostSupport.unsupportedPackages,
+            install_modes: installModes,
+            installed,
+            latest: {
+                version: latestVersion,
+                default_mode: download?.default_mode,
+                source_url: download?.source_url,
+                manifest_url: download?.manifest_url,
+                component_count: download?.components?.length,
+                download_error: downloadError
+            },
+            packages,
+            components: download?.components?.map(localToolchainEnvironmentComponent),
+            execution,
+            install_command: nativeWindowsTaishanPi ? "embedlabs local wsl status" : `embedlabs local toolchain install --board ${boardId} --mode ${mode}`,
+            update_command: nativeWindowsTaishanPi ? "embedlabs local wsl status" : `embedlabs local toolchain install --board ${boardId} --mode ${mode} --force`,
+            notes: environmentNotes({ boardId, status, downloadError, unsupportedPackages: effectiveHostSupport.unsupportedPackages })
+        });
+    }
+    const filteredEnvironments = options.installedOnly
+        ? environments.filter((environment) => !!environment.installed)
+        : environments;
+    return {
+        host,
+        channel: channel.channel,
+        metadata_source: metadataRoot ? "local_override" : "built_in",
+        metadata_root: metadataRoot,
+        install_root: installRoot,
+        registry_path: registryPath,
+        environments: filteredEnvironments
+    };
+}
 export async function installLocalToolchain(options = {}) {
     const latest = await latestLocalToolchain(options);
+    if (isNativeWindowsTaishanPiHost(latest.board_id, latest.host)) {
+        throw new Error(taishanPiWindowsRequirementMessage(latest.host));
+    }
     const installRoot = resolveInstallRoot(options.installRoot);
     const releaseRoot = resolve(installRoot, "toolchains", latest.board_id, latest.version);
+    const installMode = normalizeLocalToolchainInstallMode(options.mode ?? latest.download?.default_mode);
     if (await pathExists(releaseRoot) && !options.force) {
-        const validation = await validateLocalToolchain(releaseRoot);
+        await rewriteLocalToolchainPortablePaths(releaseRoot, latest.board_id);
+        const validation = await validateLocalToolchain({ releaseRoot, mode: installMode, boardId: latest.board_id });
         if (!validation.ok) {
-            throw new Error(`Existing local toolchain is incomplete at ${releaseRoot}; rerun with --force.`);
+            if (latest.download?.components?.length) {
+                // Component installs can upgrade an existing lower-mode install by overlaying
+                // only the newly selected components instead of deleting the whole tree.
+            }
+            else {
+                throw new Error(`Existing local toolchain is incomplete at ${releaseRoot}; rerun with --force.`);
+            }
+        }
+        else {
+            await writeCurrentRegistry(installRoot, latest, releaseRoot, installMode);
+            return {
+                board_id: latest.board_id,
+                version: latest.version,
+                channel: latest.channel,
+                host: latest.host,
+                mode: installMode,
+                install_root: installRoot,
+                release_root: releaseRoot,
+                registry_path: localToolchainRegistryPath(installRoot),
+                source: { kind: "directory", value: releaseRoot },
+                installed_paths: [],
+                packages: latest.packages,
+                validation
+            };
         }
-        await writeCurrentRegistry(installRoot, latest, releaseRoot);
-        return {
-            board_id: latest.board_id,
-            version: latest.version,
-            channel: latest.channel,
-            host: latest.host,
-            install_root: installRoot,
-            release_root: releaseRoot,
-            registry_path: localToolchainRegistryPath(installRoot),
-            source: { kind: "directory", value: releaseRoot },
-            installed_paths: [],
-            packages: latest.packages,
-            validation
-        };
     }
     const tempDir = await mkdtemp(join(tmpdir(), "embedlabs-local-toolchain-install-"));
     try {
         const sourceRoot = await sourceReleaseRootForInstall(options, latest, installRoot, tempDir);
-        await rm(releaseRoot, { recursive: true, force: true });
+        if (options.force || !await pathExists(releaseRoot) || sourceRoot.source.kind !== "components") {
+            await rm(releaseRoot, { recursive: true, force: true });
+        }
         await mkdir(releaseRoot, { recursive: true });
         const installedPaths = [];
-        for (const relativePath of INSTALL_COPY_PATHS) {
-            const sourcePath = resolve(sourceRoot.path, relativePath);
+        for (const relativePath of installCopyPathsForBoard(latest.board_id)) {
+            const sourcePath = await resolveInstallSourcePathForBoard(sourceRoot.path, relativePath, latest.board_id);
             if (!await pathExists(sourcePath)) {
                 continue;
             }
             const targetPath = resolve(releaseRoot, relativePath);
             await mkdir(dirname(targetPath), { recursive: true });
-            await cp(sourcePath, targetPath, { recursive: true, force: true, preserveTimestamps: true });
+            await cp(sourcePath, targetPath, {
+                recursive: true,
+                force: true,
+                preserveTimestamps: true,
+                verbatimSymlinks: true
+            });
             installedPaths.push(relativePath);
         }
-        await writeCurrentRegistry(installRoot, latest, releaseRoot);
-        const validation = await validateLocalToolchain(releaseRoot);
+        await rewriteLocalToolchainPortablePaths(releaseRoot, latest.board_id);
+        await writeCurrentRegistry(installRoot, latest, releaseRoot, installMode, sourceRoot.source);
+        const validation = await validateLocalToolchain({ releaseRoot, mode: installMode, boardId: latest.board_id });
         if (!validation.ok) {
             throw new Error(`Installed local toolchain is incomplete: ${validation.missing_paths.join(", ")}`);
         }
@@ -203,6 +520,7 @@ export async function installLocalToolchain(options = {}) {
             version: latest.version,
             channel: latest.channel,
             host: latest.host,
+            mode: installMode,
             install_root: installRoot,
             release_root: releaseRoot,
             registry_path: localToolchainRegistryPath(installRoot),
@@ -216,19 +534,183 @@ export async function installLocalToolchain(options = {}) {
         await rm(tempDir, { recursive: true, force: true });
     }
 }
-export async function validateLocalToolchain(releaseRoot) {
-    const resolvedRoot = await resolveLocalReleaseRoot(releaseRoot);
-    const required = [
-        ["release root", "."],
-        ["C compiler", "toolchain/llvm-cross/bin/aarch64-linux-gnu-gcc"],
-        ["C++ compiler", "toolchain/llvm-cross/bin/aarch64-linux-gnu-g++"],
-        ["readelf", "toolchain/llvm-cross/bin/aarch64-linux-gnu-readelf"],
-        ["Qt CMake", "qt-target/qt6-rk3566-llvm-6.8.3/bin/qt-cmake"],
-        ["target sysroot", "toolchain/host/aarch64-buildroot-linux-gnu/sysroot"],
-        ["Qt target libraries", "qt-target/qt6-rk3566-llvm-6.8.3/lib"],
-        ["Rockchip mkimage", "tools/mac/mkimage"],
-        ["Rockchip resource_tool", "tools/mac/resource_tool"]
-    ];
+export async function windowsWslStatus() {
+    const result = {
+        host: hostId(),
+        platform: platform(),
+        arch: arch(),
+        checked_at: new Date().toISOString(),
+        applicable: platform() === "win32",
+        wsl_available: false,
+        usable: false,
+        distributions: [],
+        online_distributions: [],
+        taishanpi_execution: {
+            supported: false,
+            required_host: "linux-x86_64",
+            windows_host: hostId(),
+            route: "wsl2",
+            status: platform() === "win32" ? "wsl_missing" : "wsl_not_applicable",
+            install_command: "embedlabs local wsl status",
+            reason: platform() === "win32"
+                ? "WSL status has not been checked yet."
+                : "WSL2 is only applicable on Windows hosts."
+        },
+        commands: {
+            status: "wsl.exe --status",
+            list: "wsl.exe -l -v",
+            list_online: "wsl.exe --list --online",
+            install_ubuntu: "wsl.exe --install -d Ubuntu --web-download"
+        },
+        notes: []
+    };
+    if (!result.applicable) {
+        result.taishanpi_execution = taishanPiWindowsExecutionRoute(result.host, result);
+        result.notes.push("WSL2 is only required for TaishanPi local development on Windows hosts.");
+        return result;
+    }
+    const whereWsl = await runCommand(["cmd", "/c", "where wsl.exe"], homedir());
+    result.wsl_available = whereWsl.exit_code === 0;
+    if (!result.wsl_available) {
+        result.taishanpi_execution = taishanPiWindowsExecutionRoute(result.host, result);
+        result.notes.push("wsl.exe was not found. Enable Windows Subsystem for Linux before installing TaishanPi local tools.");
+        return result;
+    }
+    const list = await runCommand(["wsl.exe", "-l", "-v"], homedir());
+    const normalized = normalizeWindowsCommandText([...list.stdout_tail, ...list.stderr_tail].join("\n"));
+    result.distributions = list.exit_code === 0 ? parseWslDistributionList(normalized) : [];
+    const online = await runCommand(["wsl.exe", "--list", "--online"], homedir());
+    const normalizedOnline = normalizeWindowsCommandText([...online.stdout_tail, ...online.stderr_tail].join("\n"));
+    result.online_distributions = online.exit_code === 0 ? parseWslOnlineDistributionList(normalizedOnline) : [];
+    result.usable = list.exit_code === 0 && result.distributions.length > 0;
+    result.taishanpi_execution = taishanPiWindowsExecutionRoute(result.host, result);
+    if (!result.usable) {
+        result.notes.push("No usable WSL2 distribution is configured yet. Install Ubuntu, restart Windows if requested, then run Embed Labs TaishanPi tools inside WSL2.");
+    }
+    else {
+        result.notes.push("Run TaishanPi local compile, Qt, and image tooling inside the listed WSL2 distribution. Native Windows TaishanPi toolchain packages are intentionally not published.");
+    }
+    if (result.host === "win32-arm64") {
+        result.notes.push("This Windows ARM64 host maps WSL2 to linux-arm64. TaishanPi local compile/Qt/image parity still requires a published linux-arm64/native Windows package, or a separate Windows x64 + WSL2/linux-x86_64 package and validation.");
+    }
+    return result;
+}
+export async function windowsWslInstall(options = {}) {
+    const distro = options.distribution?.trim() || "Ubuntu";
+    const command = ["wsl.exe", "--install", "-d", distro];
+    if (options.noLaunch !== false) {
+        command.push("--no-launch");
+    }
+    if (options.webDownload !== false) {
+        command.push("--web-download");
+    }
+    const notes = [];
+    if (platform() !== "win32") {
+        notes.push("WSL installation can only run on Windows hosts.");
+        return {
+            host: hostId(),
+            platform: platform(),
+            arch: arch(),
+            command,
+            exit_code: 1,
+            stdout_tail: [],
+            stderr_tail: [],
+            status_after: await windowsWslStatus(),
+            notes
+        };
+    }
+    const result = await runCommandWithTimeout(command, homedir(), options.timeoutMs ?? 600_000);
+    const statusAfter = await windowsWslStatus();
+    if (result.exit_code === 0) {
+        notes.push("WSL install command completed. If Windows requests a restart, restart before running TaishanPi local tools.");
+    }
+    else {
+        notes.push("WSL install command did not complete successfully. Run the same command in an elevated Windows terminal if the error indicates permissions or reboot requirements.");
+    }
+    if (!statusAfter.usable) {
+        notes.push("WSL2 is still not usable after this command. Complete first-launch setup for the distribution, then rerun embedlabs local wsl status.");
+    }
+    return {
+        host: hostId(),
+        platform: platform(),
+        arch: arch(),
+        command,
+        exit_code: result.exit_code,
+        stdout_tail: result.stdout_tail,
+        stderr_tail: result.stderr_tail,
+        status_after: statusAfter,
+        notes
+    };
+}
+export async function uninstallLocalToolchain(options = {}) {
+    if (!options.boardId?.trim()) {
+        throw new Error("board_id is required for local toolchain uninstall.");
+    }
+    const boardId = normalizeBoardId(options.boardId);
+    const installRoot = resolveInstallRoot(options.installRoot);
+    const registryPath = localToolchainRegistryPath(installRoot);
+    const boardRoot = resolve(installRoot, "toolchains", boardId);
+    const removedPaths = [];
+    if (await pathExists(boardRoot)) {
+        await rm(boardRoot, { recursive: true, force: true });
+        removedPaths.push(boardRoot);
+    }
+    let removedRegistryEntry = false;
+    let existing = {};
+    try {
+        existing = JSON.parse(await readFile(registryPath, "utf8"));
+    }
+    catch {
+        existing = {};
+    }
+    const environments = isRecord(existing.environments)
+        ? { ...existing.environments }
+        : {};
+    if (Object.prototype.hasOwnProperty.call(environments, boardId)) {
+        delete environments[boardId];
+        removedRegistryEntry = true;
+    }
+    const topLevelBoard = normalizeBoardId(String(existing.board_id ?? DEFAULT_BOARD_ID));
+    const topLevelPointsToBoard = topLevelBoard === boardId && typeof existing.release_root === "string";
+    const cleaned = { ...existing, environments, updated_at: new Date().toISOString() };
+    if (topLevelPointsToBoard) {
+        for (const key of [
+            "installed",
+            "board_id",
+            "version",
+            "channel",
+            "host",
+            "mode",
+            "release_root",
+            "packages",
+            "source",
+            "installed_components"
+        ]) {
+            delete cleaned[key];
+        }
+        removedRegistryEntry = true;
+    }
+    if (removedRegistryEntry || Object.keys(environments).length > 0 || Object.keys(existing).length > 0) {
+        await mkdir(dirname(registryPath), { recursive: true });
+        await writeFile(registryPath, `${JSON.stringify(cleaned, null, 2)}\n`, "utf8");
+    }
+    return {
+        board_id: boardId,
+        install_root: installRoot,
+        registry_path: registryPath,
+        removed: removedPaths.length > 0 || removedRegistryEntry,
+        removed_paths: removedPaths,
+        removed_registry_entry: removedRegistryEntry,
+        remaining_installed_boards: Object.keys(environments).sort(),
+        observed_at: new Date().toISOString()
+    };
+}
+export async function validateLocalToolchain(input) {
+    const releaseRoot = typeof input === "string" ? input : input?.releaseRoot;
+    const mode = normalizeLocalToolchainInstallMode(typeof input === "string" ? undefined : input?.mode);
+    const boardId = normalizeBoardId(typeof input === "string" ? DEFAULT_BOARD_ID : input?.boardId ?? DEFAULT_BOARD_ID);
+    const resolvedRoot = await resolveLocalReleaseRoot(releaseRoot, boardId);
+    const required = requiredLocalToolchainChecks(mode, boardId);
     const checked_paths = [];
     for (const [label, relativePath] of required) {
         const absolutePath = resolve(resolvedRoot, relativePath);
@@ -239,22 +721,353 @@ export async function validateLocalToolchain(releaseRoot) {
         });
     }
     const missing_paths = checked_paths.filter((item) => !item.exists).map((item) => item.path);
+    const path_leaks = await localToolchainPathLeaks(resolvedRoot, boardId);
+    const missing_groups = localToolchainMissingGroups(checked_paths, path_leaks);
+    const repair_command = missing_paths.length > 0 || path_leaks.length > 0
+        ? `embedlabs local toolchain install --board ${boardId} --mode ${mode}`
+        : undefined;
     return {
-        ok: missing_paths.length === 0,
+        ok: missing_paths.length === 0 && path_leaks.length === 0,
+        mode,
         host: {
             platform: platform(),
             arch: arch()
         },
-        board_id: DEFAULT_BOARD_ID,
+        board_id: boardId,
         release_root: resolvedRoot,
         checked_paths,
         missing_paths,
+        path_leaks,
+        missing_groups,
+        repair_command,
+        summary_for_user: localToolchainValidationSummary({
+            boardId,
+            mode,
+            ok: missing_paths.length === 0,
+            missingGroups: missing_groups,
+            repairCommand: repair_command
+        }),
         notes: [
             "Local build commands require an Embed Labs auth token so local resource use remains account attributable.",
-            "This validator checks the Mac-first TaishanPi LLVM release layout; package install/update registry work is tracked separately."
+            `This validator checks the ${boardId} local support layout for install mode ${mode}.`
         ]
     };
 }
+function localToolchainMissingGroups(checkedPaths, pathLeaks = []) {
+    const groups = new Set();
+    if (pathLeaks.length > 0) {
+        groups.add("portable-paths/安装包可移植路径");
+    }
+    for (const check of checkedPaths) {
+        if (check.exists) {
+            continue;
+        }
+        const text = `${check.label} ${check.path}`.toLowerCase();
+        if (text.includes("qt host") || text.includes("qtquick") || text.includes("qt cmake") || text.includes("qt target")) {
+            groups.add("qt/Qt host、target 或实时预览组件");
+            continue;
+        }
+        if (text.includes("compiler") || text.includes("readelf") || text.includes("sysroot") || text.includes("include directory") || text.includes("clang wrapper") || text.includes("gcc libraries")) {
+            groups.add("compile/交叉编译器与 sysroot");
+            continue;
+        }
+        if (text.includes("boot") || text.includes("dtb") || text.includes("resource image") || text.includes("metadata") || text.includes("/meta")) {
+            groups.add("board-resources/启动资源、DTB 与元数据");
+            continue;
+        }
+        if (text.includes("image") || text.includes("rootfs") || text.includes("parameter")) {
+            groups.add("images/基础镜像资源");
+            continue;
+        }
+        if (text.includes("rp2350") || text.includes("pico")) {
+            groups.add("rp2350/RP2350 SDK、固件或监控运行时");
+            continue;
+        }
+        groups.add("runtime/运行时文件");
+    }
+    return [...groups];
+}
+async function rewriteLocalToolchainPortablePaths(releaseRoot, boardId) {
+    if (normalizeBoardId(boardId) !== DEFAULT_BOARD_ID) {
+        return;
+    }
+    const replacements = taishanPiPortablePathReplacements(releaseRoot);
+    const files = await taishanPiPortableTextFiles(releaseRoot);
+    for (const file of files) {
+        let content;
+        try {
+            content = await readFile(file, "utf8");
+        }
+        catch {
+            continue;
+        }
+        const rewritten = rewritePortablePathContent(content, replacements);
+        if (rewritten !== content) {
+            await writeFile(file, rewritten, "utf8");
+        }
+    }
+}
+async function localToolchainPathLeaks(releaseRoot, boardId) {
+    if (normalizeBoardId(boardId) !== DEFAULT_BOARD_ID || !await pathExists(releaseRoot)) {
+        return [];
+    }
+    const forbidden = taishanPiForbiddenPortablePathFragments();
+    const files = await taishanPiPortableTextFiles(releaseRoot);
+    const leaks = [];
+    for (const file of files) {
+        let content;
+        try {
+            content = await readFile(file, "utf8");
+        }
+        catch {
+            continue;
+        }
+        for (const fragment of forbidden) {
+            if (content.includes(fragment)) {
+                leaks.push({
+                    label: "portable path check",
+                    path: file,
+                    forbidden: fragment
+                });
+                break;
+            }
+        }
+    }
+    return leaks;
+}
+async function taishanPiPortableTextFiles(releaseRoot) {
+    const candidates = [
+        "toolchain/qt6-rk3566-llvm-toolchain.cmake",
+        "qt-target/qt6-rk3566-llvm-6.8.3/bin/target_qt.conf",
+        "qt-target/qt6-rk3566-llvm-6.8.3/lib/cmake/Qt6/Qt6Dependencies.cmake",
+        "qt-target/qt6-rk3566-llvm-6.8.3/lib/cmake/Qt6/qt.toolchain.cmake",
+        "qt-target/qt6-rk3566-llvm-6.8.3/lib/cmake/Qt6BuildInternals/QtBuildInternalsExtra.cmake",
+        "qt-target/qt6-rk3566-llvm-6.8.3/mkspecs/qdevice.pri",
+        "qt-target/qt6-rk3566-llvm-6.8.3/mkspecs/qmodule.pri",
+        "qt-target/qt6-rk3566-llvm-6.8.3/mkspecs/modules/qt_lib_core_private.pri",
+        "qt-target/qt6-rk3566-llvm-6.8.3/mkspecs/modules/qt_lib_gui_private.pri",
+        "qt-target/qt6-rk3566-llvm-6.8.3/mkspecs/modules/qt_lib_serialport.pri",
+        "qt-target/qt6-rk3566-llvm-6.8.3/mkspecs/modules/qt_lib_serialport_private.pri",
+        "qt-target/qt6-rk3566-llvm-6.8.3/mkspecs/modules/qt_lib_serialbus.pri",
+        "qt-target/qt6-rk3566-llvm-6.8.3/mkspecs/modules/qt_lib_serialbus_private.pri",
+        "qt-target/qt6-rk3566-llvm-6.8.3/lib/pkgconfig/Qt6SerialPort.pc",
+        "qt-target/qt6-rk3566-llvm-6.8.3/lib/pkgconfig/Qt6SerialBus.pc",
+        "qt-target/qt6-rk3566-llvm-6.8.3/mkspecs/modules/qt_ext_openxr_loader.pri",
+        "qt-host/qt6-host-macos-6.8.3/lib/cmake/Qt6BuildInternals/QtBuildInternalsExtra.cmake",
+        "qt-host/qt6-host-macos-6.8.3/mkspecs/modules/qt_lib_serialport.pri",
+        "qt-host/qt6-host-macos-6.8.3/mkspecs/modules/qt_lib_serialport_private.pri",
+        "qt-host/qt6-host-macos-6.8.3/mkspecs/modules/qt_lib_serialbus.pri",
+        "qt-host/qt6-host-macos-6.8.3/mkspecs/modules/qt_lib_serialbus_private.pri",
+        "qt-host/qt6-host-macos-6.8.3/mkspecs/modules/qt_ext_openxr_loader.pri"
+    ];
+    const files = [];
+    for (const candidate of candidates) {
+        const file = join(releaseRoot, candidate);
+        if (await pathExists(file)) {
+            files.push(file);
+        }
+    }
+    for (const relativeDir of [
+        "qt-target/qt6-rk3566-llvm-6.8.3/lib/cmake/Qt6SerialPort",
+        "qt-target/qt6-rk3566-llvm-6.8.3/lib/cmake/Qt6SerialBus",
+        "qt-host/qt6-host-macos-6.8.3/lib/cmake/Qt6SerialPort",
+        "qt-host/qt6-host-macos-6.8.3/lib/cmake/Qt6SerialBus"
+    ]) {
+        const dir = join(releaseRoot, relativeDir);
+        if (!await pathExists(dir)) {
+            continue;
+        }
+        for (const entry of await readdir(dir, { withFileTypes: true })) {
+            if (!entry.isFile()) {
+                continue;
+            }
+            const file = join(dir, entry.name);
+            if ([".cmake", ".pri", ".pc", ".json"].includes(extname(file))) {
+                files.push(file);
+            }
+        }
+    }
+    return files;
+}
+function taishanPiPortablePathReplacements(releaseRoot) {
+    const normalizedRoot = resolve(releaseRoot);
+    // Legacy development paths are recognized only so older staged packages can
+    // be rewritten into a portable installed layout during validation/repair.
+    return [
+        ["@EMBEDLABS_RELEASE_ROOT@", normalizedRoot],
+        ["/Users/kvell/kk-project/DBT-Agent-Project/llvm-build-tspi/scripts/qt6-rk3566-llvm-toolchain.cmake", join(normalizedRoot, "toolchain", "qt6-rk3566-llvm-toolchain.cmake")],
+        ["/Users/kvell/kk-project/DBT-Agent-Project/llvm-build-tspi/.llvm-cross", join(normalizedRoot, "toolchain", "llvm-cross")],
+        ["/Volumes/LLVM-TSPI/tspi-rk3566-llvm-release-minimal", normalizedRoot],
+        ["/Volumes/LLVM-TSPI/sdk-tools/buildroot/output/rockchip_rk3566/host", join(normalizedRoot, "toolchain", "host")],
+        ["/Volumes/LLVM-TSPI/qt6-host-macos-6.8.3", join(normalizedRoot, "qt-host", "qt6-host-macos-6.8.3")],
+        ["/Volumes/LLVM-TSPI/qt6-rk3566-llvm-6.8.3", join(normalizedRoot, "qt-target", "qt6-rk3566-llvm-6.8.3")],
+        ["/Volumes/LLVM-TSPI/qt-build-host-macos-6.8.3", join(normalizedRoot, "qt-host", "qt6-host-macos-6.8.3", ".build-info", "qt-build-host-macos-6.8.3")],
+        ["/Volumes/LLVM-TSPI/qt-build-rk3566-llvm-6.8.3", join(normalizedRoot, "qt-target", "qt6-rk3566-llvm-6.8.3", ".build-info", "qt-build-rk3566-llvm-6.8.3")],
+        ["/Volumes/LLVM-TSPI/qt-everywhere-src-6.8.3", join(normalizedRoot, "meta", "source", "qt-everywhere-src-6.8.3")],
+        ["/Users/kvell/kk-project/DBT-Agent-Project/llvm-build-tspi", join(normalizedRoot, "meta", "source", "llvm-build-tspi")]
+    ];
+}
+function taishanPiForbiddenPortablePathFragments() {
+    return [
+        "/Volumes/LLVM-TSPI",
+        "/Users/kvell/kk-project/DBT-Agent-Project"
+    ];
+}
+function rewritePortablePathContent(content, replacements) {
+    let rewritten = content;
+    for (const [from, to] of replacements) {
+        rewritten = rewritten.split(from).join(to);
+    }
+    return rewritten;
+}
+function localToolchainValidationSummary(input) {
+    const boardName = input.boardId === DEFAULT_BOARD_ID
+        ? "泰山派 1M-RK3566"
+        : input.boardId;
+    if (input.ok) {
+        if (input.boardId === DEFAULT_BOARD_ID && input.mode === "qt") {
+            return `${boardName} Qt 本地开发环境完整，可以继续 QtQuick 原型、一键交叉编译和真机部署。`;
+        }
+        return `${boardName} 本地开发环境完整，可以继续使用 ${input.mode} 模式。`;
+    }
+    const groups = input.missingGroups.length > 0 ? input.missingGroups.join("、") : "部分文件";
+    if (input.boardId === DEFAULT_BOARD_ID && input.mode === "qt") {
+        return `${boardName} Qt 本地开发环境不完整，缺少 ${groups}。这会影响一键交叉编译、实时预览或真机部署；请先执行 ${input.repairCommand} 补装缺失组件。`;
+    }
+    return `${boardName} 本地开发环境不完整，缺少 ${groups}；请先执行 ${input.repairCommand} 补装缺失组件。`;
+}
+function normalizeLocalToolchainInstallMode(mode) {
+    const normalized = mode?.trim();
+    if (!normalized) {
+        return "qt";
+    }
+    if (LOCAL_TOOLCHAIN_INSTALL_MODES.includes(normalized)) {
+        return normalized;
+    }
+    throw new Error(`Unsupported local toolchain install mode ${normalized}; expected ${LOCAL_TOOLCHAIN_INSTALL_MODES.join(", ")}.`);
+}
+function requiredLocalToolchainChecks(mode, boardId) {
+    if (isRp2350MonitorBoardId(boardId)) {
+        return requiredRp2350MonitorChecks(mode);
+    }
+    const base = [
+        ["release root", "."],
+        ["boot resource image", "boot-workspace/out/resource.img"],
+        ["boot image", "boot-workspace/out/boot.img"],
+        ["boot DTB", "boot-workspace/out/tspi-rk3566-user-v10-linux.dtb"],
+        ["package metadata", "meta"]
+    ];
+    const rockchipTools = [
+        ["Rockchip mkimage", "tools/mac/mkimage"],
+        ["Rockchip dumpimage", "tools/mac/dumpimage"],
+        ["Rockchip resource_tool", "tools/mac/resource_tool"],
+        ["Rockchip rkdeveloptool", "tools/mac/rkdeveloptool"]
+    ];
+    const compile = [
+        ["C compiler", "toolchain/llvm-cross/bin/aarch64-linux-gnu-gcc"],
+        ["C++ compiler", "toolchain/llvm-cross/bin/aarch64-linux-gnu-g++"],
+        ["readelf", "toolchain/llvm-cross/bin/aarch64-linux-gnu-readelf"],
+        ["host clang wrapper", "toolchain/host-tools/bin/clang-aarch64-linux-gnu"],
+        ["host GCC libraries", "toolchain/host/lib/gcc"],
+        ["target sysroot", "toolchain/host/aarch64-buildroot-linux-gnu/sysroot"],
+        ["target include directory", "toolchain/host/aarch64-buildroot-linux-gnu/include"]
+    ];
+    const qt = [
+        ["Qt CMake", "qt-target/qt6-rk3566-llvm-6.8.3/bin/qt-cmake"],
+        ["Qt target libraries", "qt-target/qt6-rk3566-llvm-6.8.3/lib"],
+        ["Qt host tools", "qt-host/qt6-host-macos-6.8.3"],
+        ["Qt host SerialPort CMake package", "qt-host/qt6-host-macos-6.8.3/lib/cmake/Qt6SerialPort/Qt6SerialPortConfig.cmake"],
+        ["Qt host SerialBus CMake package", "qt-host/qt6-host-macos-6.8.3/lib/cmake/Qt6SerialBus/Qt6SerialBusConfig.cmake"],
+        ["Qt target SerialPort library", "qt-target/qt6-rk3566-llvm-6.8.3/lib/libQt6SerialPort.so.6"],
+        ["Qt target SerialPort CMake package", "qt-target/qt6-rk3566-llvm-6.8.3/lib/cmake/Qt6SerialPort/Qt6SerialPortConfig.cmake"],
+        ["Qt target SerialBus library", "qt-target/qt6-rk3566-llvm-6.8.3/lib/libQt6SerialBus.so.6"],
+        ["Qt target SerialBus CMake package", "qt-target/qt6-rk3566-llvm-6.8.3/lib/cmake/Qt6SerialBus/Qt6SerialBusConfig.cmake"],
+        ["Qt board runtime SerialPort library", "userdata/rootfs/qt6-rk3566-llvm/lib/libQt6SerialPort.so.6"],
+        ["Qt board runtime SerialBus library", "userdata/rootfs/qt6-rk3566-llvm/lib/libQt6SerialBus.so.6"],
+        ["QtQuick live preview", "toolkit-runtime/qtquick-live-preview/bin/embed-qml-live-preview"]
+    ];
+    const images = [
+        ["base boot image", "images/current/boot.img"],
+        ["base rootfs image", "images/current/rootfs.img"],
+        ["base image parameter", "images/current/parameter.txt"]
+    ];
+    const full = [
+        ["rootfs overlay", "userdata/rootfs"]
+    ];
+    if (mode === "minimal") {
+        return [...base, ...rockchipTools];
+    }
+    if (mode === "compile") {
+        return [...base, ...compile];
+    }
+    if (mode === "qt") {
+        return [...base, ...compile, ...qt];
+    }
+    if (mode === "images") {
+        return [...base, ...rockchipTools, ...images];
+    }
+    return [...base, ...rockchipTools, ...compile, ...qt, ...images, ...full];
+}
+function requiredRp2350MonitorChecks(mode) {
+    const armToolchainDir = rp2350ArmToolchainDirName();
+    const executableSuffix = platform() === "win32" ? ".exe" : "";
+    const monitorLauncher = platform() === "win32"
+        ? "toolkit-runtime/rp2350-monitor/ui/bin/embed-labs-logic-analyzer.cmd"
+        : "toolkit-runtime/rp2350-monitor/ui/bin/embed-labs-logic-analyzer";
+    const base = [
+        ["release root", "."],
+    ];
+    const runtime = [
+        ["RP2350 Monitor UI", "toolkit-runtime/rp2350-monitor/ui/index.html"],
+        ["RP2350 Monitor bridge", "toolkit-runtime/rp2350-monitor/ui/bridge/rpmon_bridge.py"],
+        ["RP2350 Monitor CLI", "toolkit-runtime/rp2350-monitor/tools/rpmon_cli.py"],
+        ["RP2350 picotool", `toolkit-runtime/rp2350-monitor/tools/picotool${executableSuffix}`],
+        ["RP2350 Monitor logic analyzer", monitorLauncher],
+        ["RP2350 Monitor AI operation contract", "toolkit-runtime/rp2350-monitor/ui/docs/ai-operation-contract.md"],
+        ["package metadata", "meta"]
+    ];
+    if (platform() === "win32") {
+        runtime.splice(4, 0, ["RP2350 Monitor bundled Python", "toolkit-runtime/rp2350-monitor/tools/python/python.exe"]);
+        runtime.splice(5, 0, ["RP2350 Monitor pyserial", "toolkit-runtime/rp2350-monitor/tools/python/Lib/site-packages/serial/__init__.py"]);
+    }
+    const firmware = [
+        ["RP2350 Monitor UF2", "toolkit-runtime/rp2350-monitor/firmware/rp2350_monitor.uf2"],
+        ["RP2350 Monitor firmware source", "toolkit-runtime/rp2350-monitor/firmware/src/main.cpp"]
+    ];
+    const initialFirmware = [
+        ["Pico 2 W initialization UF2", "rp2350-initial-firmware/pico2w/initial.uf2"],
+        ["ColorEasyPICO2 initialization UF2", "rp2350-initial-firmware/coloreasypico2/initial.uf2"]
+    ];
+    const compile = [
+        ["Pico SDK", "rp2350-sdk/pico-sdk/pico_sdk_init.cmake"],
+        ["Pico SDK CMakeLists", "rp2350-sdk/pico-sdk/CMakeLists.txt"],
+        ["ARM bare-metal C compiler", `rp2350-sdk/toolchains/${armToolchainDir}/bin/arm-none-eabi-gcc${executableSuffix}`],
+        ["ARM bare-metal C++ compiler", `rp2350-sdk/toolchains/${armToolchainDir}/bin/arm-none-eabi-g++${executableSuffix}`],
+        ["picotool", `rp2350-sdk/picotool/install/picotool/picotool${executableSuffix}`]
+    ];
+    if (mode === "compile") {
+        return [...base, ...compile, ...initialFirmware];
+    }
+    if (mode === "firmware") {
+        return [...base, ...runtime, ...firmware, ...initialFirmware];
+    }
+    if (mode === "full") {
+        return [...base, ...runtime, ...firmware, ...initialFirmware, ...compile];
+    }
+    return [...base, ...runtime];
+}
+function rp2350ArmToolchainDirName() {
+    if (platform() === "win32") {
+        return "arm-gnu-toolchain-15.2.rel1-mingw-w64-x86_64-arm-none-eabi";
+    }
+    if (platform() === "linux" && arch() === "x64") {
+        return "arm-gnu-toolchain-15.2.rel1-x86_64-arm-none-eabi";
+    }
+    if (platform() === "linux" && arch() === "arm64") {
+        return "arm-gnu-toolchain-15.2.rel1-aarch64-arm-none-eabi";
+    }
+    return "arm-gnu-toolchain-15.2.rel1-darwin-arm64-arm-none-eabi";
+}
 export async function compileTaishanPiSingleFile(options) {
     assertAuthenticated(options.auth);
     const releaseRoot = await resolveLocalReleaseRoot(options.releaseRoot);
@@ -285,7 +1098,7 @@ export async function compileTaishanPiSingleFile(options) {
 export async function buildTaishanPiQtSmoke(options) {
     assertAuthenticated(options.auth);
     const releaseRoot = await resolveLocalReleaseRoot(options.releaseRoot);
-    const sourceDir = resolve(options.sourceDir ?? DEFAULT_QT_SMOKE_SOURCE);
+    const sourceDir = resolve(options.sourceDir ?? join(releaseRoot, "examples", "qt-smoke"));
     const buildDir = resolve(options.buildDir);
     const targetName = options.targetName ?? "qt_llvm_smoke";
     const qtCmake = join(releaseRoot, "qt-target", "qt6-rk3566-llvm-6.8.3", "bin", "qt-cmake");
@@ -324,15 +1137,14 @@ export async function buildTaishanPiQtSmoke(options) {
 }
 async function loadLocalToolchainMetadata(metadataRoot, channelName) {
     const explicitRoot = metadataRoot || process.env.EMBEDLABS_METADATA_ROOT?.trim();
-    const candidateRoot = explicitRoot || (await pathExists(DEFAULT_METADATA_ROOT) ? DEFAULT_METADATA_ROOT : undefined);
-    if (!candidateRoot) {
+    if (!explicitRoot) {
         return {
             channel: BUILT_IN_CHANNEL,
             manifests: new Map(Object.entries(BUILT_IN_MANIFESTS)),
             metadataRoot: undefined
         };
     }
-    const root = resolve(candidateRoot);
+    const root = resolve(explicitRoot);
     const channelPath = join(root, "channels", channelName, "index.json");
     const channel = JSON.parse(await readFile(channelPath, "utf8"));
     if (channel.schema !== "embedlabs.channel.v1") {
@@ -355,17 +1167,26 @@ async function loadLocalToolchainMetadata(metadataRoot, channelName) {
     return { channel, manifests, metadataRoot: root };
 }
 async function resolveLocalToolchainDownloadPlan(input) {
+    const requestedBoardId = normalizeBoardId(input.boardId);
+    const compatibleBoardIds = compatibleDownloadBoardIds(requestedBoardId);
     const channelUrl = downloadChannelUrl(input.channel);
     const channel = await fetchJson(channelUrl);
     if (channel.schema !== "embedlabs.download-channel.v1") {
         throw new Error(`Unexpected download channel schema ${channel.schema}.`);
     }
-    const entry = (channel.packages ?? []).find((item) => {
-        return item.board_id === input.boardId
-            && item.host === input.host
-            && item.toolchain === input.toolchain
-            && (item.kind === undefined || item.kind === "toolchain-archive");
-    });
+    const entries = channel.packages ?? [];
+    let entry;
+    for (const boardId of compatibleBoardIds) {
+        entry = entries.find((item) => {
+            return normalizeBoardId(item.board_id ?? "") === boardId
+                && item.host === input.host
+                && item.toolchain === input.toolchain
+                && (item.kind === undefined || item.kind === "toolchain-archive" || item.kind === "board-support-archive");
+        });
+        if (entry) {
+            break;
+        }
+    }
     if (!entry?.manifest) {
         return undefined;
     }
@@ -374,23 +1195,28 @@ async function resolveLocalToolchainDownloadPlan(input) {
     if (manifest.id !== entry.id || manifest.version !== entry.version) {
         throw new Error(`Download manifest mismatch for ${entry.id}@${entry.version}.`);
     }
-    if (manifest.board_id !== input.boardId || manifest.host !== input.host || manifest.toolchain !== input.toolchain) {
-        throw new Error(`Download manifest does not match requested ${input.boardId}/${input.host}/${input.toolchain}.`);
+    const manifestBoardId = normalizeBoardId(manifest.board_id ?? "");
+    if (!compatibleBoardIds.includes(manifestBoardId) || manifest.host !== input.host || manifest.toolchain !== input.toolchain) {
+        throw new Error(`Download manifest does not match requested ${requestedBoardId}/${input.host}/${input.toolchain}.`);
     }
-    if (!manifest.archive?.file || !manifest.archive.sha256 || !Number.isFinite(manifest.archive.size_bytes)) {
-        throw new Error(`Download manifest ${manifest.id}@${manifest.version} is missing archive file, size, or SHA256.`);
+    if ((!manifest.archive?.file || !manifest.archive.sha256 || !Number.isFinite(manifest.archive.size_bytes))
+        && (!Array.isArray(manifest.components) || manifest.components.length === 0)) {
+        throw new Error(`Download manifest ${manifest.id}@${manifest.version} is missing archive/components metadata.`);
     }
-    const mirrors = orderDownloadMirrors((manifest.mirrors ?? [])
-        .filter((mirror) => mirror.enabled !== false && typeof mirror.url === "string" && mirror.url.length > 0)
-        .map((mirror) => ({
-        kind: mirror.kind || "unknown",
-        enabled: mirror.enabled !== false,
-        url: mirror.url,
-        sha256: typeof mirror.sha256 === "string" ? mirror.sha256 : manifest.archive?.sha256,
-        size_bytes: Number.isFinite(mirror.size_bytes) ? mirror.size_bytes : manifest.archive?.size_bytes
-    })), manifest.download_policy?.preferred_order);
+    const mirrors = manifest.archive
+        ? orderDownloadMirrors((manifest.mirrors ?? [])
+            .filter((mirror) => mirror.enabled !== false && typeof mirror.url === "string" && mirror.url.length > 0)
+            .map((mirror) => ({
+            kind: mirror.kind || "unknown",
+            enabled: mirror.enabled !== false,
+            url: mirror.url,
+            sha256: typeof mirror.sha256 === "string" ? mirror.sha256 : manifest.archive?.sha256,
+            size_bytes: Number.isFinite(mirror.size_bytes) ? mirror.size_bytes : manifest.archive?.size_bytes
+        })), manifest.download_policy?.preferred_order)
+        : [];
+    const components = downloadComponentsForBoard(requestedBoardId, (manifest.components ?? []).map((component) => normalizeDownloadComponent(component, manifest, manifestUrl)));
     const first = mirrors[0];
-    if (!first) {
+    if (!first && components.length === 0) {
         return undefined;
     }
     return {
@@ -398,17 +1224,55 @@ async function resolveLocalToolchainDownloadPlan(input) {
         manifest_url: manifestUrl,
         package_id: manifest.id,
         version: manifest.version,
-        board_id: input.boardId,
+        board_id: requestedBoardId,
         host: input.host,
         toolchain: input.toolchain,
-        source_url: first.url,
-        mirror_kind: first.kind,
-        archive: {
+        source_url: first?.url,
+        mirror_kind: first?.kind,
+        archive: manifest.archive ? {
             file: manifest.archive.file,
             size_bytes: manifest.archive.size_bytes,
             sha256: manifest.archive.sha256,
             content_type: manifest.archive.content_type
+        } : undefined,
+        mirrors,
+        components: components.length > 0 ? components : undefined,
+        default_mode: manifest.download_policy?.default_mode
+    };
+}
+function normalizeDownloadComponent(component, manifest, manifestUrl) {
+    if (!component.id || !component.version) {
+        throw new Error(`Download manifest ${manifest.id}@${manifest.version} contains a component without id/version.`);
+    }
+    if (!component.archive?.file || !component.archive.sha256 || !Number.isFinite(component.archive.size_bytes)) {
+        throw new Error(`Download manifest ${manifest.id}@${manifest.version} component ${component.id} is missing archive metadata.`);
+    }
+    const mirrors = orderDownloadMirrors((component.mirrors ?? [])
+        .filter((mirror) => mirror.enabled !== false && typeof mirror.url === "string" && mirror.url.length > 0)
+        .map((mirror) => ({
+        kind: mirror.kind || "unknown",
+        enabled: mirror.enabled !== false,
+        url: new URL(mirror.url, manifestUrl).toString(),
+        sha256: typeof mirror.sha256 === "string" ? mirror.sha256 : component.archive?.sha256,
+        size_bytes: Number.isFinite(mirror.size_bytes) ? mirror.size_bytes : component.archive?.size_bytes
+    })), manifest.download_policy?.preferred_order);
+    const first = mirrors[0];
+    if (!first) {
+        throw new Error(`Download manifest ${manifest.id}@${manifest.version} component ${component.id} has no enabled mirrors.`);
+    }
+    return {
+        id: component.id,
+        version: component.version,
+        role: component.role,
+        install_modes: Array.isArray(component.install_modes) ? component.install_modes : undefined,
+        archive: {
+            file: component.archive.file,
+            size_bytes: component.archive.size_bytes,
+            sha256: component.archive.sha256,
+            content_type: component.archive.content_type
         },
+        source_url: first.url,
+        mirror_kind: first.kind,
         mirrors
     };
 }
@@ -423,7 +1287,12 @@ function mirrorRank(kind, preferredOrder) {
     return index >= 0 ? index : preferredOrder.length + 1;
 }
 async function fetchJson(url) {
-    const response = await fetch(url, { signal: AbortSignal.timeout(DOWNLOAD_REQUEST_TIMEOUT_MS) });
+    const response = await fetch(url, {
+        headers: {
+            "accept-encoding": "identity"
+        },
+        signal: AbortSignal.timeout(DOWNLOAD_REQUEST_TIMEOUT_MS)
+    });
     if (!response.ok) {
         throw new Error(`HTTP ${response.status} while loading ${url}`);
     }
@@ -467,14 +1336,157 @@ function resolvePackageRefs(packageId, channel, manifests, seen = new Set()) {
     return refs;
 }
 function boardPackageIdFor(boardId) {
-    if (boardId === DEFAULT_BOARD_ID || boardId === "taishanpi" || boardId === "taishanpi-1m-rk3566") {
+    const normalized = normalizeBoardId(boardId);
+    if (normalized === DEFAULT_BOARD_ID || normalized === "taishanpi" || normalized === "taishanpi-1m-rk3566") {
         return "embedlabs.board.taishanpi.1m-rk3566";
     }
-    if (boardId.startsWith("embedlabs.board.")) {
+    if (normalized === COLOREASYPICO2_RP2350_BOARD_ID
+        || normalized === "coloreasypico2"
+        || normalized === "color-easy-pico2"
+        || normalized === "color-easy-pico-2"
+        || normalized === "color-easy-pico-2-rp2350-monitor"
+        || normalized === "ce-pico2") {
+        return "embedlabs.board.coloreasypico2.rp2350-monitor";
+    }
+    if (normalized === PICO2W_RP2350_BOARD_ID
+        || normalized === "pico2w"
+        || normalized === "pico-2-w"
+        || normalized === "pico2"
+        || normalized === "rp2350"
+        || normalized === "rp2350-monitor") {
+        return "embedlabs.board.pico2w.rp2350-monitor";
+    }
+    if (normalized.startsWith("embedlabs.board.")) {
         return boardId;
     }
     throw new Error(`Unsupported local toolchain board ${boardId}.`);
 }
+function packageIdForBoardFilter(boardId) {
+    try {
+        return boardPackageIdFor(boardId);
+    }
+    catch {
+        return undefined;
+    }
+}
+function boardIdForPackageManifest(manifest) {
+    const explicit = manifest.board_id;
+    if (explicit?.trim()) {
+        return normalizeBoardId(explicit);
+    }
+    if (manifest.id === "embedlabs.board.taishanpi.1m-rk3566") {
+        return DEFAULT_BOARD_ID;
+    }
+    if (manifest.id.startsWith("embedlabs.board.")) {
+        return normalizeBoardId(manifest.id.slice("embedlabs.board.".length).replaceAll(".", "-"));
+    }
+    return normalizeBoardId([manifest.board, manifest.variant].filter(Boolean).join("-") || manifest.id);
+}
+function normalizeBoardId(boardId) {
+    return boardId.trim().toLowerCase().replaceAll("_", "-");
+}
+function isRp2350MonitorBoardId(boardId) {
+    const normalized = normalizeBoardId(boardId);
+    return normalized === PICO2W_RP2350_BOARD_ID
+        || normalized === COLOREASYPICO2_RP2350_BOARD_ID
+        || normalized === "pico2w"
+        || normalized === "pico-2-w"
+        || normalized === "pico2"
+        || normalized === "rp2350"
+        || normalized === "rp2350-monitor"
+        || normalized === "coloreasypico2"
+        || normalized === "color-easy-pico2"
+        || normalized === "color-easy-pico-2"
+        || normalized === "ce-pico2";
+}
+function compatibleDownloadBoardIds(boardId) {
+    const normalized = normalizeBoardId(boardId);
+    if (normalized === COLOREASYPICO2_RP2350_BOARD_ID) {
+        return [COLOREASYPICO2_RP2350_BOARD_ID, PICO2W_RP2350_BOARD_ID];
+    }
+    return [normalized];
+}
+function downloadComponentsForBoard(boardId, components) {
+    const normalized = normalizeBoardId(boardId);
+    if (normalized === DEFAULT_BOARD_ID) {
+        return components.filter((component) => !isRp2350MonitorComponent(component));
+    }
+    return components;
+}
+function isRp2350MonitorComponent(component) {
+    const text = `${component.id} ${component.role ?? ""} ${component.archive.file}`.toLowerCase();
+    return text.includes("rp2350-monitor") || text.includes("pico2w-rp2350-monitor");
+}
+function compareVersionLike(left, right) {
+    return left.localeCompare(right, undefined, { numeric: true, sensitivity: "base" });
+}
+function isRecord(value) {
+    return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function packageHostSupport(packages, manifests, host) {
+    const unsupportedPackages = [];
+    for (const item of packages) {
+        const manifest = manifests.get(item.id);
+        if (manifest?.hosts?.length && !manifest.hosts.includes(host)) {
+            unsupportedPackages.push(`${item.id}@${manifest.version}`);
+        }
+    }
+    return {
+        supported: unsupportedPackages.length === 0,
+        unsupportedPackages
+    };
+}
+function environmentNotes(input) {
+    const notes = [];
+    if (normalizeBoardId(input.boardId) === COLOREASYPICO2_RP2350_BOARD_ID) {
+        notes.push("ColorEasyPICO2 uses the same RP2350/Pico SDK, ARM bare-metal toolchain, picotool, and optional RP2350 Monitor image package as Pico 2 W; Wi-Fi operations are not declared for this no-Wi-Fi board.");
+    }
+    if (isRp2350MonitorBoardId(input.boardId)) {
+        notes.push("RP2350 Monitor is an optional hardware-control firmware image; the board environment itself is the Pico 2 W or ColorEasyPICO2 C/C++ SDK environment.");
+    }
+    if (isNativeWindowsTaishanPiHost(input.boardId, hostId())) {
+        notes.push(taishanPiWindowsRequirementMessage(hostId()));
+        notes.push("Check this computer with: embedlabs local wsl status");
+    }
+    if (input.status === "available") {
+        notes.push("Environment is available but not installed on this computer.");
+    }
+    if (input.status === "update_available") {
+        notes.push("A newer package is available; run the update command to refresh only the selected environment.");
+    }
+    if (input.status === "unsupported_host") {
+        notes.push(`This host is missing platform support for: ${input.unsupportedPackages.join(", ")}`);
+    }
+    if (input.downloadError) {
+        notes.push(`Download manifest could not be resolved yet: ${input.downloadError}`);
+    }
+    return notes;
+}
+function localToolchainInstallModesForDownload(download) {
+    if (!download?.components?.length) {
+        return [...LOCAL_TOOLCHAIN_INSTALL_MODES];
+    }
+    const modes = new Set();
+    for (const component of download.components) {
+        for (const mode of component.install_modes ?? []) {
+            modes.add(mode);
+        }
+    }
+    return modes.size > 0
+        ? [...modes].filter((mode) => LOCAL_TOOLCHAIN_INSTALL_MODES.includes(mode))
+        : [...LOCAL_TOOLCHAIN_INSTALL_MODES];
+}
+function localToolchainEnvironmentComponent(component) {
+    return {
+        id: component.id,
+        version: component.version,
+        role: component.role,
+        install_modes: component.install_modes,
+        file: component.archive.file,
+        size_bytes: component.archive.size_bytes,
+        source_url: component.source_url
+    };
+}
 function hostId() {
     if (platform() === "darwin" && arch() === "arm64") {
         return "darwin-arm64";
@@ -484,6 +1496,154 @@ function hostId() {
     }
     return `${platform()}-${arch()}`;
 }
+function isNativeWindowsTaishanPiHost(boardId, host) {
+    return normalizeBoardId(boardId) === DEFAULT_BOARD_ID && host.startsWith("win32-");
+}
+function taishanPiWindowsExecutionRoute(host, status) {
+    const actualHost = wslHostForWindowsHost(host);
+    if (!host.startsWith("win32-")) {
+        return {
+            kind: "native",
+            supported: false,
+            required_host: "linux-x86_64",
+            actual_host: host,
+            windows_host: host,
+            route: "wsl2",
+            status: "wsl_not_applicable",
+            status_command: "embedlabs local wsl status",
+            install_command: "embedlabs local wsl status",
+            reason: "WSL2 routing is only used from Windows hosts."
+        };
+    }
+    if (!status?.wsl_available) {
+        return {
+            kind: "wsl2",
+            supported: false,
+            required_host: "linux-x86_64",
+            actual_host: actualHost,
+            windows_host: host,
+            route: "wsl2",
+            status: "wsl_missing",
+            status_command: "embedlabs local wsl status",
+            install_command: "embedlabs local wsl install --distribution Ubuntu",
+            reason: "wsl.exe is not available on this Windows host."
+        };
+    }
+    if (actualHost !== "linux-x86_64") {
+        return {
+            kind: "wsl2",
+            supported: false,
+            required_host: "linux-x86_64",
+            actual_host: actualHost,
+            windows_host: host,
+            route: "wsl2",
+            status: "architecture_mismatch",
+            status_command: "embedlabs local wsl status",
+            install_command: "embedlabs local wsl status",
+            reason: `This Windows host maps WSL2 to ${actualHost}, but the current TaishanPi package requires linux-x86_64.`
+        };
+    }
+    if (!status.usable) {
+        return {
+            kind: "wsl2",
+            supported: false,
+            required_host: "linux-x86_64",
+            actual_host: actualHost,
+            windows_host: host,
+            route: "wsl2",
+            status: "wsl_not_configured",
+            status_command: "embedlabs local wsl status",
+            install_command: "embedlabs local wsl install --distribution Ubuntu",
+            reason: "No usable WSL2 distribution is configured."
+        };
+    }
+    return {
+        kind: "wsl2",
+        supported: false,
+        required_host: "linux-x86_64",
+        actual_host: actualHost,
+        windows_host: host,
+        route: "wsl2",
+        status: "package_missing",
+        status_command: "embedlabs local wsl status",
+        install_command: "embedlabs local wsl status",
+        reason: "The Windows x64 WSL2 route is structurally compatible, but no TaishanPi linux-x86_64 package is published in the current stable channel."
+    };
+}
+function wslHostForWindowsHost(host) {
+    if (host === "win32-x64") {
+        return "linux-x86_64";
+    }
+    if (host === "win32-arm64") {
+        return "linux-arm64";
+    }
+    return undefined;
+}
+function taishanPiWindowsRequirementMessage(host) {
+    if (host === "win32-arm64") {
+        return "TaishanPi local compile, Qt, image, and Rockchip tooling is not available on native Windows ARM64 yet. Full parity requires a published linux-arm64/native Windows TaishanPi package, or a separately validated Windows x64 + WSL2/linux-x86_64 package.";
+    }
+    return "TaishanPi local compile, Qt, image, and Rockchip tooling is not available on native Windows yet. Windows x64 support requires WSL2/Linux x86_64 plus a published and validated TaishanPi linux-x86_64 package.";
+}
+function normalizeWindowsCommandText(value) {
+    return value.replace(/\0/g, "").replace(/\r/g, "\n");
+}
+function parseWslDistributionList(value) {
+    const distributions = [];
+    const lines = value.split(/\n+/)
+        .map((line) => line.trim())
+        .filter(Boolean);
+    for (const rawLine of lines) {
+        if (/^(NAME|Windows Subsystem|Usage|Copyright|\-|用法|选项|命令)/i.test(rawLine)) {
+            continue;
+        }
+        const isDefault = rawLine.startsWith("*");
+        const line = rawLine.replace(/^\*\s*/, "").trim();
+        const parts = line.split(/\s+/).filter(Boolean);
+        if (parts.length === 0 || parts[0].includes(":")) {
+            continue;
+        }
+        const maybeVersion = parts.at(-1);
+        const version = maybeVersion && /^[12]$/.test(maybeVersion) ? maybeVersion : undefined;
+        const state = version && parts.length >= 3 ? parts.at(-2) : parts.length >= 2 ? parts.at(-1) : undefined;
+        distributions.push({
+            name: parts[0],
+            state,
+            version,
+            default: isDefault
+        });
+    }
+    return distributions;
+}
+function parseWslOnlineDistributionList(value) {
+    const distributions = [];
+    const lines = value.split(/\n+/)
+        .map((line) => line.trim())
+        .filter(Boolean);
+    let inTable = false;
+    for (const rawLine of lines) {
+        if (/^NAME\s+FRIENDLY NAME/i.test(rawLine)) {
+            inTable = true;
+            continue;
+        }
+        if (!inTable) {
+            continue;
+        }
+        const isDefault = rawLine.startsWith("*");
+        const line = rawLine.replace(/^\*\s*/, "").trim();
+        const parts = line.split(/\s{2,}/).filter(Boolean);
+        const name = parts[0]?.trim();
+        if (!name || name.includes(":")) {
+            continue;
+        }
+        distributions.push({
+            name,
+            friendly_name: parts.slice(1).join(" ").trim() || undefined,
+            default: isDefault
+        });
+    }
+    return distributions;
+}
 function resolveInstallRoot(installRoot) {
     return resolve(installRoot
         || process.env.EMBEDLABS_HOME?.trim()
@@ -492,21 +1652,44 @@ function resolveInstallRoot(installRoot) {
 function localToolchainRegistryPath(installRoot) {
     return join(installRoot, "registry", "local-toolchains.json");
 }
-async function writeCurrentRegistry(installRoot, latest, releaseRoot) {
+async function writeCurrentRegistry(installRoot, latest, releaseRoot, mode, source) {
     const registryPath = localToolchainRegistryPath(installRoot);
     await mkdir(dirname(registryPath), { recursive: true });
-    await writeFile(registryPath, `${JSON.stringify({
+    let existing = {};
+    try {
+        existing = JSON.parse(await readFile(registryPath, "utf8"));
+    }
+    catch {
+        existing = {};
+    }
+    const entry = {
         installed: true,
         board_id: latest.board_id,
         version: latest.version,
         channel: latest.channel,
         host: latest.host,
+        mode,
         release_root: releaseRoot,
         packages: latest.packages,
+        source,
+        installed_components: source?.components,
+        updated_at: new Date().toISOString()
+    };
+    const environments = isRecord(existing.environments)
+        ? { ...existing.environments }
+        : {};
+    environments[normalizeBoardId(latest.board_id)] = entry;
+    const preserveTopLevel = latest.board_id !== DEFAULT_BOARD_ID
+        && typeof existing.release_root === "string"
+        && normalizeBoardId(String(existing.board_id ?? DEFAULT_BOARD_ID)) === DEFAULT_BOARD_ID;
+    const topLevel = preserveTopLevel ? existing : entry;
+    await writeFile(registryPath, `${JSON.stringify({
+        ...topLevel,
+        environments,
         updated_at: new Date().toISOString()
     }, null, 2)}\n`, "utf8");
 }
-async function resolveLocalReleaseRoot(releaseRoot) {
+async function resolveLocalReleaseRoot(releaseRoot, boardId = DEFAULT_BOARD_ID) {
     if (releaseRoot?.trim()) {
         return resolve(releaseRoot);
     }
@@ -514,7 +1697,7 @@ async function resolveLocalReleaseRoot(releaseRoot) {
     if (envRoot) {
         return resolve(envRoot);
     }
-    const current = await currentLocalToolchain(undefined, DEFAULT_BOARD_ID);
+    const current = await currentLocalToolchain(undefined, boardId);
     if (current.release_root) {
         return resolve(current.release_root);
     }
@@ -540,12 +1723,18 @@ async function sourceReleaseRootForInstall(options, latest, installRoot, tempDir
             source: { kind: "url", value: options.sourceUrl, downloaded_path: downloadedPath }
         };
     }
+    if (latest.download?.components?.length) {
+        return await componentSourceRootForInstall(options, latest.download, installRoot, tempDir);
+    }
     if (latest.download) {
         const failures = [];
         for (const mirror of latest.download.mirrors) {
             if (!mirror.enabled) {
                 continue;
             }
+            if (!latest.download.archive) {
+                continue;
+            }
             const extractRoot = join(tempDir, `extract-${safeFileToken(mirror.kind)}`);
             try {
                 const downloadedPath = await downloadToolchainArchive(mirror.url, installRoot, {
@@ -586,6 +1775,127 @@ async function sourceReleaseRootForInstall(options, latest, installRoot, tempDir
     }
     throw new Error("Local toolchain install could not resolve a source. Pass --source-url <tar.gz>, --source-release-root <path>, or configure EMBED_DOWNLOAD_BASE_URL.");
 }
+async function componentSourceRootForInstall(options, download, installRoot, tempDir) {
+    const mode = normalizeLocalToolchainInstallMode(options.mode ?? download.default_mode);
+    const components = selectedDownloadComponents(download.components ?? [], mode);
+    if (components.length === 0) {
+        throw new Error(`No local toolchain components selected for mode ${mode}.`);
+    }
+    const extractRoot = join(tempDir, "extract-components");
+    await mkdir(extractRoot, { recursive: true });
+    const installedComponents = [];
+    const failures = [];
+    for (const component of components) {
+        let installed = false;
+        for (const mirror of component.mirrors) {
+            if (!mirror.enabled) {
+                continue;
+            }
+            try {
+                const downloadedPath = await downloadToolchainArchive(mirror.url, installRoot, {
+                    sha256: mirror.sha256 ?? component.archive.sha256,
+                    size_bytes: mirror.size_bytes ?? component.archive.size_bytes
+                });
+                const extracted = await runCommand(["tar", "-xzf", downloadedPath, "-C", extractRoot], tempDir);
+                if (extracted.exit_code !== 0) {
+                    throw new Error(`Could not extract component ${component.id}: ${extracted.stderr_tail.join("\n")}`);
+                }
+                installedComponents.push({
+                    id: component.id,
+                    version: component.version,
+                    role: component.role,
+                    archive_file: component.archive.file,
+                    mirror_kind: mirror.kind,
+                    downloaded_path: downloadedPath,
+                    size_bytes: mirror.size_bytes ?? component.archive.size_bytes,
+                    sha256: mirror.sha256 ?? component.archive.sha256
+                });
+                installed = true;
+                break;
+            }
+            catch (error) {
+                failures.push(`${component.id}@${component.version}/${mirror.kind}: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+        if (!installed) {
+            throw new Error(`Could not install component ${component.id}@${component.version}: ${failures.join("; ")}`);
+        }
+    }
+    return {
+        path: extractRoot,
+        source: {
+            kind: "components",
+            value: download.manifest_url,
+            mirror_kind: "components",
+            size_bytes: installedComponents.reduce((total, component) => total + component.size_bytes, 0),
+            components: installedComponents
+        }
+    };
+}
+function selectedDownloadComponents(components, mode) {
+    return components.filter((component) => {
+        if (!component.install_modes?.length) {
+            return true;
+        }
+        return component.install_modes.includes(mode);
+    });
+}
+function installCopyPathsForBoard(boardId) {
+    if (normalizeBoardId(boardId) === DEFAULT_BOARD_ID) {
+        return INSTALL_COPY_PATHS.filter((relativePath) => {
+            const normalized = relativePath.toLowerCase();
+            return normalized !== "toolkit-runtime/rp2350-monitor"
+                && normalized !== "toolkit-runtime/rp2350-monitor/";
+        });
+    }
+    return INSTALL_COPY_PATHS;
+}
+async function resolveInstallSourcePathForBoard(sourceRoot, relativePath, boardId) {
+    const direct = resolve(sourceRoot, relativePath);
+    if (await pathExists(direct)) {
+        return direct;
+    }
+    if (!isRp2350MonitorBoardId(boardId)) {
+        return direct;
+    }
+    const legacyRp2350Root = await findLegacyRp2350Root(sourceRoot);
+    if (!legacyRp2350Root) {
+        return direct;
+    }
+    if (relativePath === "rp2350-sdk") {
+        return legacyRp2350Root;
+    }
+    if (relativePath === "rp2350-initial-firmware") {
+        return resolve(legacyRp2350Root, "initial_firmware");
+    }
+    if (relativePath === "rp2350-examples") {
+        return resolve(legacyRp2350Root, "validation");
+    }
+    return direct;
+}
+async function findLegacyRp2350Root(sourceRoot) {
+    const direct = resolve(sourceRoot, "RP2350");
+    if (await pathExists(resolve(direct, "pico-sdk", "pico_sdk_init.cmake"))) {
+        return direct;
+    }
+    let entries;
+    try {
+        entries = await readdir(sourceRoot, { withFileTypes: true });
+    }
+    catch {
+        return undefined;
+    }
+    for (const entry of entries) {
+        if (!entry.isDirectory()) {
+            continue;
+        }
+        const candidate = resolve(sourceRoot, entry.name, "RP2350");
+        if (await pathExists(resolve(candidate, "pico-sdk", "pico_sdk_init.cmake"))) {
+            return candidate;
+        }
+    }
+    return undefined;
+}
 async function downloadToolchainArchive(sourceUrl, installRoot, expected) {
     const downloadsDir = join(installRoot, "cache", "downloads");
     await mkdir(downloadsDir, { recursive: true });
@@ -775,6 +2085,68 @@ async function runCommand(command, cwd) {
         });
     });
 }
+async function runCommandWithTimeout(command, cwd, timeoutMs) {
+    return await new Promise((resolve) => {
+        const child = spawn(command[0], command.slice(1), {
+            cwd,
+            env: process.env,
+            stdio: ["ignore", "pipe", "pipe"]
+        });
+        let stdout = "";
+        let stderr = "";
+        let settled = false;
+        const timer = setTimeout(() => {
+            if (settled) {
+                return;
+            }
+            stderr += `Command timed out after ${timeoutMs} ms.\n`;
+            child.kill("SIGTERM");
+            setTimeout(() => {
+                if (!settled) {
+                    child.kill("SIGKILL");
+                }
+            }, 2_000).unref();
+        }, timeoutMs);
+        child.stdout.setEncoding("utf8");
+        child.stderr.setEncoding("utf8");
+        child.stdout.on("data", (chunk) => {
+            stdout += chunk;
+        });
+        child.stderr.on("data", (chunk) => {
+            stderr += chunk;
+        });
+        child.on("error", (error) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            clearTimeout(timer);
+            stderr += `${error.message}\n`;
+            resolve({
+                command,
+                cwd,
+                exit_code: 127,
+                stdout_tail: tailLines(stdout),
+                stderr_tail: tailLines(stderr)
+            });
+        });
+        child.on("close", (code) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            clearTimeout(timer);
+            const timedOut = stderr.includes(`Command timed out after ${timeoutMs} ms.`);
+            resolve({
+                command,
+                cwd,
+                exit_code: timedOut ? 124 : code ?? 1,
+                stdout_tail: tailLines(stdout),
+                stderr_tail: tailLines(stderr)
+            });
+        });
+    });
+}
 async function fileInfoFor(filePath) {
     const result = await runCommand(["file", filePath], dirname(filePath));
     return result.exit_code === 0 ? result.stdout_tail.join("\n") : undefined;