@biaoo/tiangong-wiki 0.2.0

package/dist/commands/daemon.js

@@ -0,0 +1,186 @@
+import { getMeta } from "../core/db.js";
+import { resolveRuntimePaths } from "../core/paths.js";
+import { openRuntimeDb } from "../core/runtime.js";
+import { inspectDaemonAvailability, requestDaemonJson } from "../daemon/client.js";
+import { runDaemonServer } from "../daemon/server.js";
+import { clearDaemonArtifacts, isDaemonProcessRunning, readDaemonPid, readDaemonState, writeDaemonPid } from "../daemon/state.js";
+import { AppError } from "../utils/errors.js";
+import { pathExistsSync } from "../utils/fs.js";
+import { ensureTextOrJson, writeJson, writeText } from "../utils/output.js";
+import { spawnDetachedCurrentProcess } from "../utils/process.js";
+const DAEMON_STARTUP_TIMEOUT_MS = 5_000;
+const DAEMON_STARTUP_POLL_MS = 100;
+async function sleep(ms) {
+    await new Promise((resolve) => setTimeout(resolve, ms));
+}
+function resolveDaemonRunLaunchMode(env = process.env) {
+    return env.WIKI_DAEMON_LAUNCH_MODE === "start" ? "start" : "run";
+}
+function readLastSyncAt(env = process.env) {
+    try {
+        const { db } = openRuntimeDb(env);
+        try {
+            return getMeta(db, "last_sync_at");
+        }
+        finally {
+            db.close();
+        }
+    }
+    catch {
+        return null;
+    }
+}
+function buildFallbackStatus(env = process.env) {
+    const paths = resolveRuntimePaths(env);
+    const pidFromPidFile = readDaemonPid(paths.daemonPidPath);
+    const state = readDaemonState(paths.daemonStatePath);
+    const pid = state?.pid ?? pidFromPidFile;
+    const running = isDaemonProcessRunning(pid);
+    return {
+        running,
+        pid,
+        host: state?.host ?? null,
+        port: state?.port ?? null,
+        lastSyncAt: readLastSyncAt(env),
+        nextSyncAt: state?.nextRunAt ?? null,
+        lastResult: state?.lastResult ?? null,
+        syncIntervalSeconds: state?.syncIntervalSeconds ?? null,
+        launchMode: state?.launchMode ?? null,
+        currentTask: state?.currentTask ?? null,
+        state,
+    };
+}
+async function stopViaSignal(pid, env = process.env) {
+    const paths = resolveRuntimePaths(env);
+    try {
+        process.kill(pid, "SIGTERM");
+    }
+    catch (error) {
+        if (error.code === "ESRCH") {
+            clearDaemonArtifacts(paths);
+            return { status: "stopped", pid: null };
+        }
+        throw error;
+    }
+    for (let index = 0; index < 10; index += 1) {
+        if (!isDaemonProcessRunning(pid)) {
+            clearDaemonArtifacts(paths);
+            return { status: "stopped", pid: null };
+        }
+        await sleep(100);
+    }
+    return { status: "stopping", pid };
+}
+async function waitForHealthyDaemon(expectedPid, env = process.env) {
+    const paths = resolveRuntimePaths(env);
+    const deadline = Date.now() + DAEMON_STARTUP_TIMEOUT_MS;
+    while (Date.now() < deadline) {
+        const availability = await inspectDaemonAvailability(env);
+        if (availability.status === "healthy" && availability.pid === expectedPid) {
+            return;
+        }
+        if (!isDaemonProcessRunning(expectedPid)) {
+            clearDaemonArtifacts(paths);
+            throw new AppError(`Failed to start daemon. Check ${paths.daemonLogPath} for details.`, "runtime");
+        }
+        await sleep(DAEMON_STARTUP_POLL_MS);
+    }
+    await stopViaSignal(expectedPid, env).catch(() => undefined);
+    clearDaemonArtifacts(paths);
+    throw new AppError(`Timed out waiting for daemon to become healthy. Check ${paths.daemonLogPath} for details.`, "runtime");
+}
+function renderStatusText(payload) {
+    return [
+        "tiangong-wiki daemon status",
+        `running: ${payload.running}`,
+        `pid: ${payload.pid ?? ""}`,
+        `host: ${payload.host ?? ""}`,
+        `port: ${payload.port ?? ""}`,
+        `lastSyncAt: ${payload.lastSyncAt ?? ""}`,
+        `nextSyncAt: ${payload.nextSyncAt ?? ""}`,
+        `lastResult: ${payload.lastResult ?? ""}`,
+        `syncIntervalSeconds: ${payload.syncIntervalSeconds ?? ""}`,
+        `launchMode: ${payload.launchMode ?? ""}`,
+        `currentTask: ${payload.currentTask ?? ""}`,
+    ].join("\n");
+}
+export function registerDaemonCommand(program) {
+    const daemon = program.command("daemon").description("Manage the background sync daemon");
+    daemon
+        .command("start")
+        .description("Start the wiki daemon as a detached local background service")
+        .action(async () => {
+        const paths = resolveRuntimePaths(process.env);
+        const availability = await inspectDaemonAvailability(process.env);
+        if (availability.status === "healthy" || availability.status === "degraded") {
+            throw new AppError(`Daemon is already running with PID ${availability.pid}`, "runtime", availability);
+        }
+        if (pathExistsSync(paths.daemonPidPath) || pathExistsSync(paths.daemonStatePath)) {
+            clearDaemonArtifacts(paths);
+        }
+        const pid = spawnDetachedCurrentProcess(["daemon", "run"], {
+            env: {
+                ...process.env,
+                WIKI_DAEMON_LAUNCH_MODE: "start",
+            },
+            logFile: paths.daemonLogPath,
+        });
+        if (!pid) {
+            throw new AppError("Failed to start daemon", "runtime");
+        }
+        writeDaemonPid(paths.daemonPidPath, pid);
+        await waitForHealthyDaemon(pid, process.env);
+        writeJson({ status: "started", pid });
+    });
+    daemon
+        .command("stop")
+        .description("Stop the wiki daemon")
+        .action(async () => {
+        const availability = await inspectDaemonAvailability(process.env);
+        if (availability.status === "healthy" && availability.endpoint) {
+            writeJson(await requestDaemonJson({
+                endpoint: availability.endpoint,
+                method: "POST",
+                path: "/shutdown",
+            }));
+            return;
+        }
+        const paths = resolveRuntimePaths(process.env);
+        const pid = availability.pid ?? readDaemonPid(paths.daemonPidPath);
+        if (!isDaemonProcessRunning(pid)) {
+            clearDaemonArtifacts(paths);
+            writeJson({ status: "stopped", pid: null });
+            return;
+        }
+        writeJson(await stopViaSignal(pid, process.env));
+    });
+    daemon
+        .command("status")
+        .description("Show daemon state and scheduling information")
+        .option("--format <format>", "text or json", "text")
+        .action(async (options) => {
+        const format = ensureTextOrJson(options.format);
+        const availability = await inspectDaemonAvailability(process.env);
+        const payload = availability.status === "healthy" && availability.endpoint
+            ? await requestDaemonJson({
+                endpoint: availability.endpoint,
+                method: "GET",
+                path: "/status",
+            })
+            : buildFallbackStatus(process.env);
+        if (format === "json") {
+            writeJson(payload);
+            return;
+        }
+        writeText(renderStatusText(payload));
+    });
+    daemon
+        .command("run")
+        .description("Run the wiki daemon in the foreground")
+        .action(async () => {
+        await runDaemonServer({
+            env: process.env,
+            launchMode: resolveDaemonRunLaunchMode(process.env),
+        });
+    });
+}

package/dist/commands/dashboard.js

@@ -0,0 +1,112 @@
+import path from "node:path";
+import { inspectDaemonAvailability } from "../daemon/client.js";
+import { clearDaemonArtifacts, isDaemonProcessRunning, writeDaemonPid } from "../daemon/state.js";
+import { resolveRuntimePaths } from "../core/paths.js";
+import { AppError } from "../utils/errors.js";
+import { pathExistsSync } from "../utils/fs.js";
+import { ensureTextOrJson, writeJson, writeText } from "../utils/output.js";
+import { openTarget, spawnDetachedCurrentProcess } from "../utils/process.js";
+const DAEMON_STARTUP_TIMEOUT_MS = 5_000;
+const DAEMON_STARTUP_POLL_MS = 100;
+async function sleep(ms) {
+    await new Promise((resolve) => setTimeout(resolve, ms));
+}
+function getDashboardDistEntry(env = process.env) {
+    const paths = resolveRuntimePaths(env);
+    return path.join(paths.packageRoot, "dist", "dashboard", "index.html");
+}
+async function waitForHealthyDaemon(expectedPid, env = process.env) {
+    const paths = resolveRuntimePaths(env);
+    const deadline = Date.now() + DAEMON_STARTUP_TIMEOUT_MS;
+    while (Date.now() < deadline) {
+        const availability = await inspectDaemonAvailability(env);
+        if (availability.status === "healthy" && availability.endpoint && availability.pid === expectedPid) {
+            return availability.endpoint;
+        }
+        if (!isDaemonProcessRunning(expectedPid)) {
+            clearDaemonArtifacts(paths);
+            throw new AppError(`Failed to start daemon. Check ${paths.daemonLogPath} for details.`, "runtime");
+        }
+        await sleep(DAEMON_STARTUP_POLL_MS);
+    }
+    clearDaemonArtifacts(paths);
+    throw new AppError(`Timed out waiting for daemon to become healthy. Check ${paths.daemonLogPath} for details.`, "runtime");
+}
+async function stopDegradedDaemon(env = process.env) {
+    const paths = resolveRuntimePaths(env);
+    const availability = await inspectDaemonAvailability(env);
+    if (availability.status !== "degraded" || !availability.pid) {
+        return;
+    }
+    try {
+        process.kill(availability.pid, "SIGTERM");
+    }
+    catch (error) {
+        if (error.code !== "ESRCH") {
+            throw error;
+        }
+    }
+    const deadline = Date.now() + 2_000;
+    while (Date.now() < deadline) {
+        if (!isDaemonProcessRunning(availability.pid)) {
+            clearDaemonArtifacts(paths);
+            return;
+        }
+        await sleep(100);
+    }
+    clearDaemonArtifacts(paths);
+}
+async function ensureDashboardDaemon(env = process.env) {
+    const availability = await inspectDaemonAvailability(env);
+    if (availability.status === "healthy" && availability.endpoint) {
+        return availability.endpoint;
+    }
+    if (availability.status === "degraded") {
+        await stopDegradedDaemon(env);
+    }
+    const paths = resolveRuntimePaths(env);
+    const pid = spawnDetachedCurrentProcess(["daemon", "run"], {
+        env: {
+            ...env,
+            WIKI_DAEMON_LAUNCH_MODE: "start",
+        },
+        logFile: paths.daemonLogPath,
+    });
+    if (!pid) {
+        throw new AppError("Failed to start daemon", "runtime");
+    }
+    writeDaemonPid(paths.daemonPidPath, pid);
+    return waitForHealthyDaemon(pid, env);
+}
+export function registerDashboardCommand(program) {
+    program
+        .command("dashboard")
+        .description("Open the local dashboard in a browser, starting the daemon if needed")
+        .option("--no-open", "Do not open the dashboard URL in a browser")
+        .option("--format <format>", "text or json", "text")
+        .action(async (options) => {
+        const format = ensureTextOrJson(options.format);
+        const dashboardEntry = getDashboardDistEntry(process.env);
+        if (!pathExistsSync(dashboardEntry)) {
+            throw new AppError(`Dashboard assets are missing at ${dashboardEntry}. Run \`npm run build\` before opening the dashboard.`, "not_found");
+        }
+        const endpoint = await ensureDashboardDaemon(process.env);
+        const url = `http://${endpoint.host}:${endpoint.port}/dashboard`;
+        const opened = options.open !== false;
+        if (opened) {
+            openTarget(url);
+        }
+        const payload = {
+            url,
+            opened,
+            pid: endpoint.pid,
+            host: endpoint.host,
+            port: endpoint.port,
+        };
+        if (format === "json") {
+            writeJson(payload);
+            return;
+        }
+        writeText(url);
+    });
+}

package/dist/commands/doctor.js

@@ -0,0 +1,22 @@
+import { buildDoctorReport, formatDoctorReport } from "../core/onboarding.js";
+import { ensureTextOrJson, writeJson, writeText } from "../utils/output.js";
+export function registerDoctorCommand(program) {
+    program
+        .command("doctor")
+        .description("Diagnose the current wiki configuration and runtime health")
+        .option("--probe", "Probe configured remote services such as embeddings and Synology NAS")
+        .option("--format <format>", "Output format: text or json", "text")
+        .action(async (options) => {
+        const format = ensureTextOrJson(options.format);
+        const report = await buildDoctorReport(process.env, { probe: options.probe === true });
+        if (format === "json") {
+            writeJson(report);
+        }
+        else {
+            writeText(formatDoctorReport(report));
+        }
+        if (!report.ok) {
+            process.exitCode = 2;
+        }
+    });
+}

package/dist/commands/export-graph.js

@@ -0,0 +1,28 @@
+import { executeServerBackedOperation, requestDaemonJson } from "../daemon/client.js";
+import { exportGraphContent } from "../operations/export.js";
+import { writeJson, writeText } from "../utils/output.js";
+import { writeTextFileSync } from "../utils/fs.js";
+export function registerExportGraphCommand(program) {
+    program
+        .command("export-graph")
+        .description("Export graph nodes and edges as JSON")
+        .option("--output <filePath>", "Write JSON to a file")
+        .action(async (options) => {
+        const payload = await executeServerBackedOperation({
+            kind: "read",
+            local: () => exportGraphContent(process.env),
+            remote: (endpoint) => requestDaemonJson({
+                endpoint,
+                method: "POST",
+                path: "/export/graph",
+            }),
+        });
+        const content = `${JSON.stringify(payload, null, 2)}\n`;
+        if (options.output) {
+            writeTextFileSync(options.output, content);
+            writeJson({ output: options.output, nodes: payload.nodes.length, edges: payload.edges.length });
+            return;
+        }
+        writeText(content);
+    });
+}

package/dist/commands/export-index.js

@@ -0,0 +1,31 @@
+import { executeServerBackedOperation, requestDaemonJson } from "../daemon/client.js";
+import { exportIndexContent } from "../operations/export.js";
+import { writeText } from "../utils/output.js";
+import { writeTextFileSync } from "../utils/fs.js";
+export function registerExportIndexCommand(program) {
+    program
+        .command("export-index")
+        .description("Export a human-readable Markdown index of pages")
+        .option("--output <filePath>", "Write Markdown output to a file")
+        .option("--group-by <mode>", "Group by pageType or tags", "pageType")
+        .action(async (options) => {
+        const payload = await executeServerBackedOperation({
+            kind: "read",
+            local: () => exportIndexContent(process.env, {
+                groupBy: options.groupBy ?? undefined,
+            }),
+            remote: (endpoint) => requestDaemonJson({
+                endpoint,
+                method: "POST",
+                path: "/export/index",
+                body: {
+                    groupBy: options.groupBy ?? undefined,
+                },
+            }),
+        });
+        if (options.output) {
+            writeTextFileSync(options.output, `${payload.content}\n`);
+        }
+        writeText(String(payload.content ?? ""));
+    });
+}

package/dist/commands/find.js

@@ -0,0 +1,36 @@
+import { executeServerBackedOperation, requestDaemonJson } from "../daemon/client.js";
+import { camelToSnake } from "../utils/case.js";
+import { findPages } from "../operations/query.js";
+import { writeJson } from "../utils/output.js";
+export function registerFindCommand(program, config) {
+    const command = program
+        .command("find")
+        .description("Find wiki pages by structured metadata filters")
+        .option("--type <pageType>", "Filter by pageType")
+        .option("--status <status>", "Filter by status")
+        .option("--visibility <visibility>", "Filter by visibility")
+        .option("--tag <tag>", "Filter by tag")
+        .option("--node-id <nodeId>", "Filter by nodeId")
+        .option("--updated-after <date>", "Filter by updatedAt >= date")
+        .option("--sort <column>", "Sort column")
+        .option("--limit <number>", "Max rows to return", "50");
+    const dynamicFields = config
+        ? [...new Set([...Object.keys(config.customColumns), ...Object.values(config.templates).flatMap((template) => Object.keys(template.columns))])]
+        : [];
+    for (const field of dynamicFields) {
+        command.option(`--${camelToSnake(field).replace(/_/g, "-")} <value>`, `Filter by ${field}`);
+    }
+    command.action(async (options) => {
+        const payload = await executeServerBackedOperation({
+            kind: "read",
+            local: () => findPages(process.env, options),
+            remote: (endpoint) => requestDaemonJson({
+                endpoint,
+                method: "GET",
+                path: "/find",
+                query: options,
+            }),
+        });
+        writeJson(payload);
+    });
+}

package/dist/commands/fts.js

@@ -0,0 +1,32 @@
+import { executeServerBackedOperation, requestDaemonJson } from "../daemon/client.js";
+import { ftsSearchPages } from "../operations/query.js";
+import { writeJson } from "../utils/output.js";
+export function registerFtsCommand(program) {
+    program
+        .command("fts")
+        .description("Run full-text search over title, tags, and summary text")
+        .argument("<query>", "FTS query")
+        .option("--type <pageType>", "Optional pageType filter")
+        .option("--limit <number>", "Max rows to return", "20")
+        .action(async (query, options) => {
+        const payload = await executeServerBackedOperation({
+            kind: "read",
+            local: () => ftsSearchPages(process.env, {
+                query,
+                type: options.type ?? undefined,
+                limit: options.limit ?? undefined,
+            }),
+            remote: (endpoint) => requestDaemonJson({
+                endpoint,
+                method: "GET",
+                path: "/fts",
+                query: {
+                    query,
+                    type: options.type ?? undefined,
+                    limit: options.limit ?? undefined,
+                },
+            }),
+        });
+        writeJson(payload);
+    });
+}

package/dist/commands/graph.js

@@ -0,0 +1,35 @@
+import { executeServerBackedOperation, requestDaemonJson } from "../daemon/client.js";
+import { traverseGraph } from "../operations/query.js";
+import { writeJson } from "../utils/output.js";
+export function registerGraphCommand(program) {
+    program
+        .command("graph")
+        .description("Traverse the tiangong-wiki graph with recursive CTEs")
+        .argument("<root>", "Root nodeId or page id")
+        .option("--depth <number>", "Traversal depth", "1")
+        .option("--edge-type <edgeType>", "Optional edge type filter")
+        .option("--direction <direction>", "outgoing, incoming, or both", "both")
+        .action(async (root, options) => {
+        const payload = await executeServerBackedOperation({
+            kind: "read",
+            local: () => traverseGraph(process.env, {
+                root,
+                depth: options.depth ?? undefined,
+                edgeType: options.edgeType ?? undefined,
+                direction: options.direction ?? undefined,
+            }),
+            remote: (endpoint) => requestDaemonJson({
+                endpoint,
+                method: "GET",
+                path: "/graph",
+                query: {
+                    root,
+                    depth: options.depth ?? undefined,
+                    edgeType: options.edgeType ?? undefined,
+                    direction: options.direction ?? undefined,
+                },
+            }),
+        });
+        writeJson(payload);
+    });
+}

package/dist/commands/init.js

@@ -0,0 +1,48 @@
+import { EmbeddingClient } from "../core/embedding.js";
+import { resolveRuntimePaths } from "../core/paths.js";
+import { syncWorkspace } from "../core/sync.js";
+import { getWikiAgentStatus } from "../core/vault-processing.js";
+import { scaffoldWorkspaceAssets } from "../core/workspace-bootstrap.js";
+import { AppError } from "../utils/errors.js";
+import { spawnDetachedCurrentProcess } from "../utils/process.js";
+import { writeJson } from "../utils/output.js";
+export function registerInitCommand(program) {
+    program
+        .command("init")
+        .description("Initialize wiki workspace assets and run the first structured sync")
+        .option("--force", "Force a full rebuild of the index")
+        .action(async (options) => {
+        const paths = resolveRuntimePaths(process.env);
+        const bootstrap = scaffoldWorkspaceAssets({
+            packageRoot: paths.packageRoot,
+            wikiRoot: paths.wikiRoot,
+            wikiPath: paths.wikiPath,
+            vaultPath: paths.vaultPath,
+            templatesPath: paths.templatesPath,
+            configPath: paths.configPath,
+        });
+        const structuredSync = await syncWorkspace({
+            force: options.force === true,
+            skipEmbedding: true,
+        });
+        let backgroundEmbeddingStarted = false;
+        let backgroundPid;
+        if (EmbeddingClient.fromEnv(process.env)) {
+            backgroundPid = spawnDetachedCurrentProcess(["embed-pending"], { env: process.env });
+            backgroundEmbeddingStarted = typeof backgroundPid === "number";
+        }
+        const wikiAgent = getWikiAgentStatus(process.env);
+        if (wikiAgent.enabled && wikiAgent.missing.length > 0) {
+            throw new AppError(`WIKI_AGENT_ENABLED=true but missing required settings: ${wikiAgent.missing.join(", ")}`, "config");
+        }
+        writeJson({
+            initialized: true,
+            copiedConfig: bootstrap.copiedConfig,
+            copiedTemplates: bootstrap.copiedTemplates,
+            sync: structuredSync,
+            backgroundEmbeddingStarted,
+            ...(backgroundEmbeddingStarted ? { backgroundPid } : {}),
+            backgroundQueueProcessingStarted: false,
+        });
+    });
+}

package/dist/commands/lint.js

@@ -0,0 +1,35 @@
+import { executeServerBackedOperation, requestDaemonJson } from "../daemon/client.js";
+import { renderLintResult, runLint } from "../operations/query.js";
+import { ensureTextOrJson, writeJson, writeText } from "../utils/output.js";
+export function registerLintCommand(program) {
+    program
+        .command("lint")
+        .description("Validate wiki pages, references, and graph integrity")
+        .option("--path <pagePath>", "Lint only one page")
+        .option("--level <level>", "error, warning, or info", "info")
+        .option("--format <format>", "text or json", "text")
+        .action(async (options) => {
+        const format = ensureTextOrJson(options.format);
+        const payload = await executeServerBackedOperation({
+            kind: "read",
+            local: () => runLint(process.env, {
+                path: options.path ?? undefined,
+                level: options.level ?? undefined,
+            }),
+            remote: (endpoint) => requestDaemonJson({
+                endpoint,
+                method: "GET",
+                path: "/lint",
+                query: {
+                    path: options.path ?? undefined,
+                    level: options.level ?? undefined,
+                },
+            }),
+        });
+        if (format === "json") {
+            writeJson(payload);
+            return;
+        }
+        writeText(renderLintResult(payload));
+    });
+}

package/dist/commands/list.js

@@ -0,0 +1,28 @@
+import { executeServerBackedOperation, requestDaemonJson } from "../daemon/client.js";
+import { listPages } from "../operations/query.js";
+import { writeJson } from "../utils/output.js";
+export function registerListCommand(program) {
+    program
+        .command("list")
+        .description("List wiki pages")
+        .option("--type <pageType>", "Optional pageType filter")
+        .option("--sort <column>", "Sort column", "updatedAt")
+        .option("--limit <number>", "Max rows to return", "50")
+        .action(async (options) => {
+        const payload = await executeServerBackedOperation({
+            kind: "read",
+            local: () => listPages(process.env, options),
+            remote: (endpoint) => requestDaemonJson({
+                endpoint,
+                method: "GET",
+                path: "/list",
+                query: {
+                    type: options.type ?? undefined,
+                    sort: options.sort ?? undefined,
+                    limit: options.limit ?? undefined,
+                },
+            }),
+        });
+        writeJson(payload);
+    });
+}

package/dist/commands/page-info.js

@@ -0,0 +1,24 @@
+import { executeServerBackedOperation, requestDaemonJson } from "../daemon/client.js";
+import { getPageInfo } from "../operations/query.js";
+import { writeJson } from "../utils/output.js";
+export function registerPageInfoCommand(program) {
+    program
+        .command("page-info")
+        .description("Show full metadata and edge details for one page")
+        .argument("<pageId>", "Page id relative to wiki/pages")
+        .action(async (inputPageId) => {
+        const payload = await executeServerBackedOperation({
+            kind: "read",
+            local: () => getPageInfo(process.env, inputPageId),
+            remote: (endpoint) => requestDaemonJson({
+                endpoint,
+                method: "GET",
+                path: "/page-info",
+                query: {
+                    pageId: inputPageId,
+                },
+            }),
+        });
+        writeJson(payload);
+    });
+}

package/dist/commands/search.js

@@ -0,0 +1,32 @@
+import { executeServerBackedOperation, requestDaemonJson } from "../daemon/client.js";
+import { searchPages } from "../operations/query.js";
+import { writeJson } from "../utils/output.js";
+export function registerSearchCommand(program) {
+    program
+        .command("search")
+        .description("Run semantic search over page summary embeddings")
+        .argument("<query>", "Natural language query")
+        .option("--type <pageType>", "Optional pageType filter")
+        .option("--limit <number>", "Max rows to return", "10")
+        .action(async (query, options) => {
+        const payload = await executeServerBackedOperation({
+            kind: "read",
+            local: () => searchPages(process.env, {
+                query,
+                type: options.type ?? undefined,
+                limit: options.limit ?? undefined,
+            }),
+            remote: (endpoint) => requestDaemonJson({
+                endpoint,
+                method: "GET",
+                path: "/search",
+                query: {
+                    query,
+                    type: options.type ?? undefined,
+                    limit: options.limit ?? undefined,
+                },
+            }),
+        });
+        writeJson(payload);
+    });
+}