@andre.li/memoark 0.3.1 → 0.3.2

package/dist/cli.js

@@ -1,28 +1,62 @@
 #!/usr/bin/env node
 import { existsSync, mkdirSync } from "node:fs";
 import { homedir } from "node:os";
-import { resolve } from "node:path";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { Command } from "commander";
+import { planStartup, shouldOpenBrowserOnServe } from "./cli-helpers.js";
+import { normalizeDocsConfig } from "./collectors/feishu/docs/config.js";
+import { FullCardBuilder } from "./collectors/feishu/docs/full-builder.js";
+import { runDocSource } from "./collectors/feishu/docs/run.js";
+import { failedCards, summarizeCards } from "./collectors/feishu/docs/status.js";
+import { loadExistingCard, writeCard } from "./collectors/feishu/docs/store-writer.js";
+import { LarkCliHttpClient } from "./collectors/feishu/lark-cli-client.js";
+import { resolveSelfOpenId } from "./collectors/feishu/self-open-id.js";
 import { createClaudeCodeCollector, createCodexCollector, createFeishuCollector, createHermesCollector, getAllCollectors, getCollector, registerCollector, resetRegistry, } from "./collectors/index.js";
 import { Consolidator } from "./consolidator/consolidator.js";
-import { loadConfig } from "./core/config.js";
+import { loadConfig, resolveConfigPath, } from "./core/config.js";
+import { CursorStore } from "./core/cursors.js";
+import { getMissingEnvVarsForCommand, validateEnvForCommand } from "./core/env-validation.js";
+import { PersonIdentityStore } from "./core/person-identity.js";
 import { runPipeline } from "./core/pipeline.js";
+import { buildPipelineConfig } from "./core/pipeline-factory.js";
 import { ensureStateDir, statePath } from "./core/state.js";
-import { Scheduler } from "./daemon/scheduler.js";
+import { ReloadManager } from "./daemon/reload-manager.js";
+import { buildServeRuntime, ServeRuntimeHolder } from "./daemon/serve-runtime.js";
 import { VERSION } from "./embedded-assets.generated.js";
 import { createLLMProvider, createMockProvider } from "./extractors/providers/index.js";
+import { hooksInstall, hooksUninstall } from "./hooks/install.js";
+import { runHookEvent } from "./hooks/run-event.js";
+import { runInstall, runUninstall } from "./install/index.js";
+import { scaffoldSkill } from "./install/skill.js";
 import { createApiApp } from "./server/api.js";
+import { getSessionContext } from "./server/context.js";
 import { createMcpServer } from "./server/mcp.js";
+import { createMcpHttpApp } from "./server/mcp-http.js";
+import { openBrowser } from "./server/open-browser.js";
+import { startServer } from "./server/runtime.js";
 import { ChunkStore } from "./store/chunks.js";
 import { Database } from "./store/database.js";
 import { EmbeddingService } from "./store/embedding.js";
 import { GraphStore } from "./store/graph.js";
 import { PageStore } from "./store/pages.js";
+import { PersonBehaviorStore } from "./store/person-behavior.js";
 import { SearchEngine } from "./store/search.js";
 import { TagStore } from "./store/tags.js";
 import { TimelineStore } from "./store/timeline.js";
-function bootstrapCollectors(sources) {
+function resolveProjectPath(path, projectRoot) {
+    if (!path)
+        return undefined;
+    if (path.startsWith("~/"))
+        return resolve(homedir(), path.slice(2));
+    if (path === "~")
+        return homedir();
+    if (isAbsolute(path))
+        return path;
+    return resolve(projectRoot, path);
+}
+function bootstrapCollectors(sources, projectRoot) {
     resetRegistry();
     const agentConfigs = {
         "claude-code": { factory: createClaudeCodeCollector, config: sources["claude-code"] },
@@ -31,22 +65,33 @@ function bootstrapCollectors(sources) {
     };
     for (const [_id, { factory, config }] of Object.entries(agentConfigs)) {
         if (config?.enabled !== false) {
-            registerCollector(factory(config?.base_dir));
+            registerCollector(factory(resolveProjectPath(config?.base_dir, projectRoot)));
         }
     }
     if (sources.feishu?.enabled !== false && sources.feishu?.app_id) {
         registerCollector(createFeishuCollector(sources.feishu));
     }
 }
-function expandDataDir(dir) {
-    if (dir.startsWith("~/"))
-        return resolve(homedir(), dir.slice(2));
-    if (dir === "~")
-        return homedir();
-    return dir;
+function expandDataDir(dir, projectRoot) {
+    return resolveProjectPath(dir, projectRoot) ?? dir;
+}
+// Try to extract feishu.lark_bin from an existing config so the setup UI's
+// "Feishu — Test Connection" button doesn't fall through to the hardcoded
+// ~/.local/bin/lark path. Silent on missing file or parse errors (the wizard
+// may be running because the YAML doesn't exist yet).
+function readLarkBinFromConfig(configPath) {
+    const path = configPath ?? resolve(process.cwd(), "memoark.yaml");
+    if (!existsSync(path))
+        return undefined;
+    try {
+        return loadConfig(path).sources?.feishu?.lark_bin;
+    }
+    catch {
+        return undefined;
+    }
 }
 async function createStores(config) {
-    const dataDir = expandDataDir(config.store.data_dir);
+    const dataDir = expandDataDir(config.store.data_dir, config.__context.projectRoot);
     mkdirSync(dataDir, { recursive: true });
     const db = await Database.create(dataDir, {
         embeddingDimensions: config.embedding.dimensions,
@@ -60,7 +105,13 @@ async function createStores(config) {
         apiKey: config.embedding.api_key ?? process.env.OPENAI_API_KEY,
         baseUrl: config.embedding.base_url,
     });
-    const search = new SearchEngine(db.pg, { embedText: (q) => embedding.embedText(q) });
+    const search = new SearchEngine(db.pg, {
+        embedText: (q) => embedding.embedText(q),
+        search: {
+            pool_by_page: config.search.pool_by_page,
+            llm_rewrite: config.search.llm_rewrite,
+        },
+    });
     return {
         db,
         pages,
@@ -72,6 +123,20 @@ async function createStores(config) {
         embedding,
     };
 }
+/**
+ * Lightweight store for identity operations: opens only the Database + a
+ * PersonIdentityStore. Deliberately avoids EmbeddingService so that person
+ * alias/merge/rename never requires an LLM or embedding API key.
+ */
+async function openIdentityStore(config) {
+    const dataDir = expandDataDir(config.store.data_dir, config.__context.projectRoot);
+    mkdirSync(dataDir, { recursive: true });
+    const db = await Database.create(dataDir, {
+        embeddingDimensions: config.embedding.dimensions,
+    });
+    const identity = new PersonIdentityStore(db.pg, { pages: new PageStore(db.pg) }, { behavior: new PersonBehaviorStore(db.pg) });
+    return { db, identity };
+}
 const program = new Command();
 program
     .name("memoark")
@@ -88,7 +153,10 @@ program
     .action(async (options) => {
     if (options.web) {
         const { startSetupServer } = await import("./server/setup-server.js");
-        await startSetupServer({ configPath: options.config });
+        await startSetupServer({
+            configPath: options.config,
+            larkBin: readLarkBinFromConfig(options.config),
+        });
         return;
     }
     try {
@@ -123,10 +191,11 @@ program
     try {
         // Load configuration
         const config = loadConfig(options.config);
+        const { projectRoot } = config.__context;
         // Ensure state directory exists
-        ensureStateDir();
+        ensureStateDir(projectRoot);
         // Bootstrap collectors from config
-        bootstrapCollectors(config.sources);
+        bootstrapCollectors(config.sources, projectRoot);
         // Determine which sources to process
         let sourceIds;
         if (options.source === "all") {
@@ -138,6 +207,7 @@ program
         // Create LLM provider based on config (shared across all sources)
         let provider;
         if (!options.dryRun) {
+            validateEnvForCommand(config, "extract");
             const llmConfig = config.llm;
             const envKey = llmConfig.provider === "anthropic"
                 ? process.env.ANTHROPIC_API_KEY
@@ -156,16 +226,7 @@ program
             provider = createMockProvider(new Map());
         }
         // Build pipeline configuration
-        const pipelineConfig = {
-            dedup_checkpoint: statePath("dedup.jsonl"),
-            cursor_checkpoint: statePath("cursors.yaml"),
-            block_gap_minutes: config.block_builder.block_gap_minutes,
-            max_block_tokens: config.block_builder.max_block_tokens,
-            max_block_messages: config.block_builder.max_block_messages,
-            privacy: config.privacy,
-            output_dir: options.output || process.cwd(),
-            block_concurrency: config.pipeline?.block_concurrency,
-        };
+        const pipelineConfig = buildPipelineConfig(config, options.output || process.cwd(), projectRoot);
         // Parse options
         const format = ["json", "markdown"].includes(options.format) ? options.format : "json";
         const adapter = ["store", "file", "gbrain", "stdout"].includes(options.adapter)
@@ -276,7 +337,7 @@ program
     const warnings = [];
     const ok = [];
     // Check config file
-    const configPath = options.config || resolve(process.cwd(), "memoark.yaml");
+    const configPath = resolveConfigPath(options.config);
     let config = null;
     if (existsSync(configPath)) {
         ok.push(`Configuration file found: ${configPath}`);
@@ -293,7 +354,8 @@ program
         warnings.push("Create one with: memoark init");
     }
     // Check state directory
-    const stateDir = resolve(process.cwd(), ".memoark");
+    const projectRoot = config?.__context.projectRoot ?? dirname(configPath);
+    const stateDir = resolve(projectRoot, ".memoark");
     if (existsSync(stateDir)) {
         ok.push(`State directory exists: ${stateDir}`);
     }
@@ -301,12 +363,23 @@ program
         warnings.push(`State directory does not exist: ${stateDir}`);
         warnings.push("It will be created automatically on first extract");
     }
+    const cwdStateDir = resolve(process.cwd(), ".memoark");
+    if (cwdStateDir !== stateDir && existsSync(cwdStateDir)) {
+        warnings.push(`Legacy state directory found at current cwd: ${cwdStateDir}`);
+        warnings.push(`Current config-root state directory is: ${stateDir}`);
+        warnings.push("Move cursor/dedup files manually if you intended to reuse the old state.");
+    }
     // Check LLM configuration
     if (config) {
+        const missingEnvVars = getMissingEnvVarsForCommand(config, "doctor");
+        if (missingEnvVars.length > 0) {
+            warnings.push(`Missing environment variables: ${missingEnvVars.join(", ")}`);
+            warnings.push(`Referenced by: ${config.__context.configPath}`);
+        }
         if (config.llm?.provider && config.llm?.model) {
             ok.push(`LLM provider configured: ${config.llm.provider} / ${config.llm.model}`);
             const envKey = config.llm.provider === "anthropic" ? "ANTHROPIC_API_KEY" : "OPENAI_API_KEY";
-            if (process.env[envKey] || config.llm.api_key) {
+            if (!missingEnvVars.includes(envKey)) {
                 ok.push(`${config.llm.provider} API key configured`);
             }
             else {
@@ -318,7 +391,7 @@ program
             issues.push("LLM provider or model not configured");
         }
         // Check sources
-        bootstrapCollectors(config.sources);
+        bootstrapCollectors(config.sources, config.__context.projectRoot);
         for (const collector of getAllCollectors()) {
             const health = await collector.healthCheck();
             if (health.ok) {
@@ -385,9 +458,13 @@ configCmd
     .command("edit")
     .description("Edit configuration in browser UI")
     .option("--web", "Launch browser-based settings UI (default behavior)")
-    .action(async () => {
+    .option("-c, --config <path>", "Path to config file (default: memoark.yaml)")
+    .action(async (options) => {
     const { startSetupServer } = await import("./server/setup-server.js");
-    await startSetupServer();
+    await startSetupServer({
+        configPath: options.config,
+        larkBin: readLarkBinFromConfig(options.config),
+    });
 });
 /**
  * Sources subcommand group
@@ -399,7 +476,7 @@ sourcesCmd
     .option("-c, --config <path>", "Path to config file")
     .action((options) => {
     const config = loadConfig(options.config);
-    bootstrapCollectors(config.sources);
+    bootstrapCollectors(config.sources, config.__context.projectRoot);
     const collectors = getAllCollectors();
     console.log("Available sources:\n");
     for (const c of collectors) {
@@ -415,7 +492,7 @@ sourcesCmd
     .action(async (name, options) => {
     try {
         const config = loadConfig(options.config);
-        bootstrapCollectors(config.sources);
+        bootstrapCollectors(config.sources, config.__context.projectRoot);
         const collector = getCollector(name);
         if (!collector) {
             console.error(`Error: Unknown source '${name}'`);
@@ -436,104 +513,321 @@ sourcesCmd
         process.exit(1);
     }
 });
+async function runServe(options) {
+    {
+        const serveConfigPath = options.config ?? resolve(process.cwd(), "memoark.yaml");
+        if (!existsSync(serveConfigPath)) {
+            console.error("No configuration file found.\n" +
+                "Run `memoark start` for one-step setup + launch, or `memoark init --web` to configure first.");
+            process.exit(1);
+        }
+        const config = loadConfig(options.config);
+        // Anchor the .memoark state dir to the config's project root, not process.cwd().
+        // A Finder-launched sidecar has cwd=/, so the default would try to mkdir /.memoark
+        // (EROFS on macOS). projectRoot = dirname(configPath), so it lives beside the config.
+        const stateDir = ensureStateDir(config.__context.projectRoot);
+        const missingEnvVars = getMissingEnvVarsForCommand(config, "serve");
+        if (missingEnvVars.length > 0) {
+            console.warn(`[warn] Missing env vars: ${missingEnvVars.join(", ")} (referenced by ${config.__context.configPath})`);
+        }
+        const stores = await createStores(config);
+        const initialRuntime = await buildServeRuntime(config, stores, stateDir);
+        const holder = new ServeRuntimeHolder(initialRuntime);
+        if (config.scheduler?.enabled)
+            await holder.current.scheduler?.start();
+        const reloadManager = new ReloadManager({
+            holder,
+            // only read once at construction for the initial signature; ReloadManager tracks lastConfig internally afterward
+            currentConfig: () => config,
+            buildRuntime: (next) => buildServeRuntime(next, stores, stateDir),
+        });
+        const storesWithDaemon = {
+            ...stores,
+            getDaemonStatus: () => holder.current.getDaemonStatus(),
+            // getter: always reads the current runtime, so a Tier-2 swap is seen by routes
+            get chatNameRefreshJob() {
+                return holder.current.chatNameRefreshJob;
+            },
+        };
+        let shuttingDown = false;
+        const shutdown = async () => {
+            if (shuttingDown)
+                return; // 防重入:连按 Ctrl-C 不会二次 db.close()
+            shuttingDown = true;
+            await holder.current.dispose();
+            try {
+                await stores.db.close(); // 触发锁 release
+            }
+            finally {
+                process.exit(0); // db.close() 抛错也必须退出
+            }
+        };
+        process.on("SIGTERM", shutdown);
+        process.on("SIGINT", shutdown);
+        if (options.mcp) {
+            const llmConfig = { ...config.llm };
+            const envKey = llmConfig.provider === "anthropic"
+                ? process.env.ANTHROPIC_API_KEY
+                : process.env.OPENAI_API_KEY;
+            if (!llmConfig.api_key && envKey)
+                llmConfig.api_key = envKey;
+            const synthProvider = llmConfig.api_key
+                ? createLLMProvider(llmConfig)
+                : createMockProvider(new Map());
+            let ingestDeps;
+            const feishu = config.sources.feishu;
+            if (feishu?.enabled && feishu.sources?.docs?.enabled) {
+                const client = new LarkCliHttpClient(feishu.lark_bin);
+                ingestDeps = {
+                    client,
+                    stores: storesWithDaemon,
+                    provider: synthProvider,
+                    model: feishu.sources.docs.llm?.model ?? llmConfig.model,
+                    nowIso: () => new Date().toISOString(),
+                };
+            }
+            const server = createMcpServer(storesWithDaemon, { provider: synthProvider, synthModel: llmConfig.model }, ingestDeps);
+            await server.connect(new StdioServerTransport());
+            return;
+        }
+        if (options.mcpHttp ||
+            config.mcp.http.enabled ||
+            config.server.mcp_transport === "streamable_http") {
+            const tokenEnv = config.mcp.http.auth_token_env;
+            const app = createMcpHttpApp(storesWithDaemon, {
+                allowedOrigins: config.mcp.http.allowed_origins,
+                allowedHosts: config.mcp.http.allowed_hosts,
+                authToken: tokenEnv ? process.env[tokenEnv] : undefined,
+                exposeLegacyTools: config.mcp.expose_legacy_tools,
+                readOnly: config.mcp.http.read_only,
+            });
+            const server = await startServer(app, {
+                hostname: config.mcp.http.bind_host,
+                port: config.mcp.http.port,
+            });
+            console.log(`Memoark MCP Streamable HTTP listening on http://${server.hostname}:${server.port}/mcp`);
+            return;
+        }
+        const app = createApiApp(storesWithDaemon, {
+            onConfigSaved: () => {
+                try {
+                    void reloadManager.run(loadConfig(options.config)).catch((err) => {
+                        console.error("[reload] Runtime reload failed:", err);
+                    });
+                }
+                catch (err) {
+                    console.error("[reload] Failed to load config after save:", err);
+                }
+            },
+        });
+        // In a `bun --compile` sidecar, import.meta.url lives under $bunfs and web/dist is
+        // NOT embedded, so the default path can't be served. The Tauri shell ships web/dist
+        // as a resource and injects its real path via MEMOARK_WEB_DIST (mirrors pglite-assets).
+        const webDist = process.env.MEMOARK_WEB_DIST ?? join(fileURLToPath(import.meta.url), "../../web/dist");
+        // `--port 0` (used by the Tauri shell) binds an OS-assigned free port so the desktop
+        // app never collides with a CLI `memoark serve`, a stale instance, or anything else
+        // on the default port. The actual port is reported below for the webview to read.
+        const requestedPort = options.port !== undefined ? Number(options.port) : config.server.http_port;
+        const server = Bun.serve({
+            port: requestedPort,
+            fetch: async (req) => {
+                const url = new URL(req.url);
+                if (url.pathname.startsWith("/api"))
+                    return app.fetch(req);
+                const filePath = url.pathname === "/" ? "index.html" : url.pathname.replace(/^\//, "");
+                const candidate = Bun.file(join(webDist, filePath));
+                if (await candidate.exists())
+                    return new Response(candidate);
+                return new Response(Bun.file(join(webDist, "index.html")));
+            },
+        });
+        console.log(`Memoark HTTP API listening on http://localhost:${server.port}`);
+        // Stdout contract for the Tauri shell: the URL after the marker is where the webview
+        // navigates (the port may be OS-assigned, so report the real one — never hardcode).
+        console.log(`MEMOARK_READY http://localhost:${server.port}`);
+        if (shouldOpenBrowserOnServe({
+            open: options.open !== false,
+            mcp: !!options.mcp,
+            mcpHttp: !!options.mcpHttp,
+        })) {
+            openBrowser(`http://localhost:${server.port}`);
+        }
+        const activeScheduler = holder.current.scheduler;
+        if (activeScheduler && config.scheduler?.enabled) {
+            console.log(`Scheduler running — tick every ${config.scheduler.tick_interval_secs}s, sources: ${activeScheduler.getSourceIds().join(", ")}`);
+        }
+    }
+}
 program
     .command("serve")
     .description("Start Memoark HTTP API or MCP stdio server")
     .option("-c, --config <path>", "Path to config file")
     .option("--mcp", "Run MCP stdio transport instead of HTTP")
-    .action(async (options) => {
-    const serveConfigPath = options.config ?? resolve(process.cwd(), "memoark.yaml");
-    if (!existsSync(serveConfigPath)) {
-        console.error("No configuration file found.\nRun `memoark init` (TUI) or `memoark init --web` (browser) to set up Memoark.");
-        process.exit(1);
-    }
-    const config = loadConfig(options.config);
-    const stateDir = ensureStateDir();
-    const stores = await createStores(config);
-    let scheduler;
-    if (config.scheduler?.enabled) {
-        bootstrapCollectors(config.sources);
-        const llmConfig = config.llm;
-        const envKey = llmConfig.provider === "anthropic"
-            ? process.env.ANTHROPIC_API_KEY
-            : process.env.OPENAI_API_KEY;
-        if (!llmConfig.api_key && envKey)
-            llmConfig.api_key = envKey;
-        const provider = llmConfig.api_key
-            ? createLLMProvider(llmConfig)
-            : createMockProvider(new Map());
-        const pipelineConfig = {
-            dedup_checkpoint: statePath("dedup.jsonl"),
-            cursor_checkpoint: statePath("cursors.yaml"),
-            block_gap_minutes: config.block_builder.block_gap_minutes,
-            max_block_tokens: config.block_builder.max_block_tokens,
-            max_block_messages: config.block_builder.max_block_messages,
-            privacy: config.privacy,
-            output_dir: process.cwd(),
-            block_concurrency: config.pipeline?.block_concurrency,
-        };
-        scheduler = new Scheduler(config.scheduler, stateDir);
-        scheduler.setRunSource(async (sourceId) => {
-            const collector = getCollector(sourceId);
-            if (!collector)
-                throw new Error(`Unknown source: ${sourceId}`);
-            return runPipeline(pipelineConfig, {
-                source: collector,
-                provider,
-                format: "json",
-                adapter: "store",
-                stores,
-                dryRun: false,
-            });
-        });
-        scheduler.setOnTick((sourceId, result, duration_ms) => {
-            const status = result.fatal ? "failed" : "ok";
-            console.log(`[scheduler] ${sourceId}: ${status} (${duration_ms}ms)`);
+    .option("--mcp-http", "Run MCP Streamable HTTP transport instead of the HTTP API")
+    .option("--no-open", "Do not auto-open the browser after starting")
+    .option("--pglite-assets <dir>", "Directory holding bundled PGLite assets (compiled-sidecar mode; injected by the Tauri shell)")
+    .option("--web-dist <dir>", "Directory holding the built web UI (compiled-sidecar mode; injected by the Tauri shell)")
+    .option("--port <n>", "Override the HTTP port; 0 binds an OS-assigned free port (used by the Tauri shell)")
+    .action((options) => {
+    if (options.pgliteAssets)
+        process.env.MEMOARK_PGLITE_ASSETS = options.pgliteAssets;
+    if (options.webDist)
+        process.env.MEMOARK_WEB_DIST = options.webDist;
+    return runServe(options);
+});
+async function runStart(options) {
+    const configPath = options.config ?? resolve(process.cwd(), "memoark.yaml");
+    const plan = planStartup(existsSync(configPath));
+    if (plan.runSetup) {
+        console.log("No configuration found — launching setup wizard...");
+        const { startSetupServer } = await import("./server/setup-server.js");
+        await startSetupServer({
+            configPath: options.config,
+            larkBin: readLarkBinFromConfig(options.config),
         });
-        await scheduler.start();
-    }
-    const getDaemonStatus = scheduler
-        ? () => {
-            const hb = scheduler?.getHeartbeat();
-            const now = Date.now();
-            let lastRunAt = null;
-            let nextAt = null;
-            for (const id of scheduler?.getSourceIds() ?? []) {
-                const s = scheduler?.getSourceState(id);
-                if (!s)
-                    continue;
-                if (s.last_run_at !== null && (lastRunAt === null || s.last_run_at > lastRunAt)) {
-                    lastRunAt = s.last_run_at;
-                }
-                const next = s.last_run_at !== null ? s.last_run_at + s.interval_secs * 1000 : now;
-                if (nextAt === null || next < nextAt)
-                    nextAt = next;
-            }
-            return {
-                running: true,
-                uptime_seconds: Math.floor((now - (hb?.daemon_started_at ?? now)) / 1000),
-                last_run: lastRunAt ? new Date(lastRunAt).toISOString() : null,
-                next_scheduled: nextAt !== null ? new Date(nextAt).toISOString() : null,
-            };
-        }
-        : undefined;
-    const storesWithDaemon = { ...stores, getDaemonStatus };
-    const shutdown = () => {
-        scheduler?.stop();
-    };
-    process.on("SIGTERM", shutdown);
-    process.on("SIGINT", shutdown);
-    if (options.mcp) {
-        const server = createMcpServer(storesWithDaemon);
-        await server.connect(new StdioServerTransport());
+    }
+    await runServe({ config: options.config });
+}
+program
+    .command("start")
+    .description("One-step launch: setup if needed, then serve + open browser")
+    .option("-c, --config <path>", "Path to config file")
+    .action((options) => runStart(options));
+program.action(() => runStart({}));
+function reportPlan(planned, verb, dryRun) {
+    if (planned.length === 0) {
+        console.log("No AI agents detected. Specify one with --agent <id> (claude-code, claude-desktop, cursor, codex, windsurf).");
         return;
     }
-    const app = createApiApp(storesWithDaemon);
-    const server = Bun.serve({ port: config.server.http_port, fetch: app.fetch });
-    console.log(`Memoark HTTP API listening on http://localhost:${server.port}`);
-    if (scheduler) {
-        console.log(`Scheduler running — tick every ${config.scheduler?.tick_interval_secs}s, sources: ${scheduler.getSourceIds().join(", ")}`);
+    for (const client of planned) {
+        console.log(`\n${verb} → ${client.displayName}:`);
+        for (const op of client.ops) {
+            const where = "path" in op ? op.path : `cli: ${op.args.join(" ")}`;
+            console.log(`  - ${op.kind} ${op.action} ${where}`);
+        }
+    }
+    if (!dryRun)
+        console.log("\nRestart / reopen your agent for changes to take effect.");
+}
+program
+    .command("install")
+    .description("Register Memoark (MCP config + memory directive) into your AI agents")
+    .option("--agent <ids...>", "Target client(s): claude-code, claude-desktop, cursor, codex, windsurf (default: all detected)")
+    .option("--project", "Install into the current project instead of globally")
+    .option("--http", "Register the Streamable HTTP transport instead of stdio")
+    .option("--dry-run", "Preview changes without writing")
+    .action((options) => {
+    const scope = options.project ? "project" : "global";
+    const planned = runInstall({
+        agent: options.agent,
+        scope,
+        http: !!options.http,
+        dryRun: !!options.dryRun,
+    });
+    reportPlan(planned, options.dryRun ? "Would install" : "Installed", !!options.dryRun);
+});
+program
+    .command("uninstall")
+    .description("Remove Memoark MCP config + memory directive from your AI agents")
+    .option("--agent <ids...>", "Target client(s) (default: all detected)")
+    .option("--project", "Operate on the current project instead of globally")
+    .option("--dry-run", "Preview changes without writing")
+    .action((options) => {
+    const scope = options.project ? "project" : "global";
+    const planned = runUninstall({ agent: options.agent, scope, dryRun: !!options.dryRun });
+    reportPlan(planned, options.dryRun ? "Would remove" : "Removed", !!options.dryRun);
+});
+const hooksCmd = program
+    .command("hooks")
+    .description("Manage Claude Code hooks for automatic recall / write-back");
+hooksCmd
+    .command("install")
+    .description("Install SessionStart + UserPromptSubmit (read) hooks; write-back is opt-in")
+    .option("--write-back", "Also install the SessionEnd auto write-back hook (opt-in)")
+    .option("--project", "Write to ./.claude/settings.json instead of the global one")
+    .option("--dry-run", "Preview without writing")
+    .action((options) => {
+    const res = hooksInstall({
+        writeBack: !!options.writeBack,
+        project: !!options.project,
+        dryRun: !!options.dryRun,
+    });
+    console.log(`${options.dryRun ? "Would install" : "Installed"} hooks [${res.events.join(", ")}] → ${res.path}`);
+    if (!options.writeBack) {
+        console.log("Tip: add --write-back to also auto-capture memory at session end (opt-in).");
+    }
+    if (!options.dryRun)
+        console.log("Reopen Claude Code for the hooks to take effect.");
+});
+hooksCmd
+    .command("uninstall")
+    .description("Remove all Memoark hooks from settings.json")
+    .option("--project", "Operate on ./.claude/settings.json instead of the global one")
+    .option("--dry-run", "Preview without writing")
+    .action((options) => {
+    const res = hooksUninstall({ project: !!options.project, dryRun: !!options.dryRun });
+    console.log(`${options.dryRun ? "Would remove" : "Removed"} Memoark hooks → ${res.path}`);
+});
+const skillCmd = program.command("skill").description("Manage the Memoark agent skill");
+skillCmd
+    .command("scaffold")
+    .description("Write the memoark skill (SKILL.md) into a skills directory")
+    .option("--dir <path>", "Target skills directory (default: ./.claude/skills)")
+    .action((options) => {
+    const dir = options.dir ?? join(process.cwd(), ".claude", "skills");
+    const path = scaffoldSkill(dir);
+    console.log(`Wrote ${path}`);
+});
+async function readStdinJson() {
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(chunk);
+    const raw = Buffer.concat(chunks).toString("utf8").trim();
+    if (!raw)
+        return {};
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return {};
+    }
+}
+program
+    .command("hook <event>")
+    .description("Internal: Claude Code hook entrypoint (session-start|user-prompt|session-end)")
+    .action(async (event) => {
+    try {
+        const input = await readStdinJson();
+        const config = loadConfig(undefined);
+        const port = config.server.http_port;
+        const out = await runHookEvent(event, input, {
+            port,
+            sessionContext: async () => {
+                const stores = await createStores(config);
+                try {
+                    return await getSessionContext(stores);
+                }
+                finally {
+                    await stores.db.close();
+                }
+            },
+            ftsSearch: async (q, opts) => {
+                const stores = await createStores(config);
+                try {
+                    return await stores.search.search(q, opts);
+                }
+                finally {
+                    await stores.db.close();
+                }
+            },
+        });
+        if (out && Object.keys(out).length > 0)
+            process.stdout.write(JSON.stringify(out));
+    }
+    catch {
+        // Never break the host session: emit nothing on any failure.
     }
+    process.exit(0);
 });
 program
     .command("search <query>")
@@ -542,7 +836,9 @@ program
     .option("--mode <mode>", "Search mode (hybrid|fts)", "hybrid")
     .option("--limit <n>", "Limit results", "20")
     .action(async (query, options) => {
-    const stores = await createStores(loadConfig(options.config));
+    const config = loadConfig(options.config);
+    validateEnvForCommand(config, "search", { searchMode: options.mode });
+    const stores = await createStores(config);
     const limit = Number(options.limit);
     const results = options.mode === "fts"
         ? await stores.search.search(query, { limit })
@@ -558,7 +854,9 @@ program
     .option("-c, --config <path>", "Path to config file")
     .option("--limit <n>", "Limit chunks")
     .action(async (options) => {
-    const stores = await createStores(loadConfig(options.config));
+    const config = loadConfig(options.config);
+    validateEnvForCommand(config, "embed");
+    const stores = await createStores(config);
     const result = await stores.embedding.embedStale({
         limit: options.limit ? Number(options.limit) : undefined,
     });
@@ -666,7 +964,15 @@ program
             graph: stores.graph,
             tags: stores.tags,
             timeline: stores.timeline,
-        }, llmProvider);
+        }, llmProvider, {
+            profile: config.profile,
+            profileStores: {
+                pages: stores.pages,
+                graph: stores.graph,
+                timeline: stores.timeline,
+                behavior: new PersonBehaviorStore(stores.db.pg),
+            },
+        });
         const mode = options.hot
             ? "hot"
             : options.warm
@@ -683,6 +989,7 @@ program
         console.log(`  warm→cold pages archived: ${result.warmToCold}`);
         console.log(`  dead links checked:       ${result.deadLinksChecked}`);
         console.log(`  preferences inferred:     ${result.preferencesInferred}`);
+        console.log(`  profiles synthesized:     ${result.profilesSynthesized}`);
         await stores.db.close();
     }
     catch (error) {
@@ -690,5 +997,254 @@ program
         process.exit(1);
     }
 });
+// ── Person identity (Layer 1: aliases / merge / rename) ────────────────────
+const HANDLE_KINDS = ["feishu_open_id", "email", "name", "nickname", "slug"];
+const identityCmd = program
+    .command("identity")
+    .description("Manage person identity: aliases, merge, and rename");
+identityCmd
+    .command("alias <canonical_slug> <kind> <value>")
+    .description(`Attach an alias/handle to a person. kind: ${HANDLE_KINDS.join(" | ")}`)
+    .option("-c, --config <path>", "Path to config file")
+    .option("--strong", "Force strong strength (auto-resolvable)")
+    .option("--weak", "Force weak strength (explicit-only)")
+    .action(async (canonicalSlug, kind, value, options) => {
+    if (!HANDLE_KINDS.includes(kind)) {
+        console.error(`Error: invalid kind '${kind}'. Expected one of: ${HANDLE_KINDS.join(", ")}`);
+        process.exit(1);
+    }
+    const { db, identity } = await openIdentityStore(loadConfig(options.config));
+    try {
+        const strength = options.strong ? "strong" : options.weak ? "weak" : undefined;
+        await identity.addAlias(canonicalSlug, kind, value, strength);
+        console.log(`Linked ${kind}:${value} → ${canonicalSlug}`);
+        for (const h of await identity.listHandles(canonicalSlug)) {
+            console.log(`  ${h.kind}\t${h.value}\t(${h.strength})`);
+        }
+    }
+    catch (error) {
+        console.error("alias failed:", error instanceof Error ? error.message : String(error));
+        process.exit(1);
+    }
+    finally {
+        await db.close();
+    }
+});
+identityCmd
+    .command("handles <canonical_slug>")
+    .description("List all handles/aliases attached to a person")
+    .option("-c, --config <path>", "Path to config file")
+    .action(async (canonicalSlug, options) => {
+    const { db, identity } = await openIdentityStore(loadConfig(options.config));
+    try {
+        const handles = await identity.listHandles(canonicalSlug);
+        if (handles.length === 0) {
+            console.log(`No handles for ${canonicalSlug}`);
+        }
+        else {
+            for (const h of handles)
+                console.log(`${h.kind}\t${h.value}\t(${h.strength})`);
+        }
+    }
+    finally {
+        await db.close();
+    }
+});
+identityCmd
+    .command("merge <from> <into>")
+    .description("Merge person page <from> into <into> (re-points links/timeline/tags + aliases)")
+    .option("-c, --config <path>", "Path to config file")
+    .action(async (from, into, options) => {
+    const { db, identity } = await openIdentityStore(loadConfig(options.config));
+    try {
+        await identity.merge(from, into);
+        console.log(`Merged ${from} → ${into}`);
+        console.log("Note: run `memoark embed` to re-embed the folded content.");
+    }
+    catch (error) {
+        console.error("merge failed:", error instanceof Error ? error.message : String(error));
+        process.exit(1);
+    }
+    finally {
+        await db.close();
+    }
+});
+identityCmd
+    .command("rename <from> <to>")
+    .description("Rename a person's canonical slug (correct a wrong canonicalization)")
+    .option("-c, --config <path>", "Path to config file")
+    .action(async (from, to, options) => {
+    const { db, identity } = await openIdentityStore(loadConfig(options.config));
+    try {
+        await identity.recanonicalize(from, to);
+        console.log(`Renamed ${from} → ${to}`);
+    }
+    catch (error) {
+        console.error("rename failed:", error instanceof Error ? error.message : String(error));
+        process.exit(1);
+    }
+    finally {
+        await db.close();
+    }
+});
+const docsCmd = program.command("docs").description("Feishu doc summary cards (DocSource v2)");
+docsCmd
+    .command("sync")
+    .description("Scan Feishu docs, build pointer cards, upgrade triggered docs to full cards")
+    .option("-c, --config <path>", "Path to config file (default: memoark.yaml)")
+    .action(async (options) => {
+    try {
+        const config = loadConfig(options.config);
+        ensureStateDir();
+        const feishu = config.sources.feishu;
+        if (!feishu?.enabled || !feishu.sources?.docs?.enabled) {
+            console.error("Feishu docs source is not enabled in config (sources.feishu.sources.docs.enabled).");
+            process.exit(1);
+        }
+        const stores = await createStores(config);
+        const client = new LarkCliHttpClient(feishu.lark_bin);
+        const docsConfig = normalizeDocsConfig(feishu.sources.docs);
+        // self_open_id: config override else resolve via lark-cli whoami helper used elsewhere
+        const selfOpenId = docsConfig.self_open_id ??
+            (await resolveSelfOpenId(client, feishu.sources?.dm?.self_open_id)) ??
+            "";
+        const llmConfig = { ...config.llm };
+        if (docsConfig.llm.model)
+            llmConfig.model = docsConfig.llm.model;
+        const envKey = llmConfig.provider === "anthropic"
+            ? process.env.ANTHROPIC_API_KEY
+            : process.env.OPENAI_API_KEY;
+        if (!llmConfig.api_key && envKey)
+            llmConfig.api_key = envKey;
+        const provider = llmConfig.api_key
+            ? createLLMProvider(llmConfig)
+            : createMockProvider(new Map());
+        const cursor = new CursorStore(statePath("cursors.yaml"));
+        cursor.load();
+        // Identity layer for canonicalizing action_item owners → person slugs and
+        // detecting self-ownership, so doc/meeting action_items become task signals
+        // the daily report can surface (Spec 9 §3.3).
+        const identity = new PersonIdentityStore(stores.db.pg, { pages: stores.pages }, { behavior: new PersonBehaviorStore(stores.db.pg) });
+        const stats = await runDocSource({
+            client,
+            stores,
+            provider,
+            config: docsConfig,
+            cursor,
+            selfOpenId,
+            nowMs: Date.now(),
+            nowIso: () => new Date().toISOString(),
+            actionItemDeps: {
+                graph: stores.graph,
+                resolveOwner: async (ownerRaw) => {
+                    if (!ownerRaw)
+                        return null;
+                    // best-effort: map a name/@mention to a canonical person slug
+                    return ((await identity.resolveHandle("name", ownerRaw)) ??
+                        (await identity.resolveHandle("nickname", ownerRaw)) ??
+                        null);
+                },
+                isMe: (slug) => identity.isMe(slug),
+            },
+        });
+        console.log(`[docs] scanned=${stats.candidates_scanned} pointer=${stats.pointer_saved} full=${stats.full_card_generated} skipped=${stats.skipped} queue=${stats.upgrade_queue_size} llm_failed=${stats.llm_failed}`);
+        await stores.db.close();
+    }
+    catch (error) {
+        console.error("docs sync failed:", error instanceof Error ? error.message : String(error));
+        process.exit(1);
+    }
+});
+docsCmd
+    .command("status")
+    .description("Show Feishu doc card counts")
+    .option("-c, --config <path>", "Path to config file")
+    .option("--failed", "List cards whose last extraction failed")
+    .action(async (options) => {
+    try {
+        const config = loadConfig(options.config);
+        const stores = await createStores(config);
+        const pages = await stores.pages.listPages({ type: "feishu_doc_card", limit: 100000 });
+        if (options.failed) {
+            for (const f of failedCards(pages))
+                console.log(`${f.doc_token}\t${f.error}`);
+        }
+        else {
+            const s = summarizeCards(pages);
+            console.log(`total=${s.total} full=${s.full} pointer=${s.pointer} failed=${s.failed}`);
+        }
+        await stores.db.close();
+    }
+    catch (error) {
+        console.error("docs status failed:", error instanceof Error ? error.message : String(error));
+        process.exit(1);
+    }
+});
+docsCmd
+    .command("retry [doc_token]")
+    .description("Retry full-card extraction for a failed doc (or --all-failed)")
+    .option("-c, --config <path>", "Path to config file")
+    .option("--all-failed", "Retry every card with an extract_error")
+    .action(async (docToken, options) => {
+    try {
+        const config = loadConfig(options.config);
+        const feishu = config.sources.feishu;
+        if (!feishu?.sources?.docs?.enabled) {
+            console.error("Feishu docs source not enabled.");
+            process.exit(1);
+        }
+        const stores = await createStores(config);
+        const client = new LarkCliHttpClient(feishu.lark_bin);
+        const docsConfig = normalizeDocsConfig(feishu.sources.docs);
+        const llmConfig = { ...config.llm };
+        if (docsConfig.llm.model)
+            llmConfig.model = docsConfig.llm.model;
+        const envKey = llmConfig.provider === "anthropic"
+            ? process.env.ANTHROPIC_API_KEY
+            : process.env.OPENAI_API_KEY;
+        if (!llmConfig.api_key && envKey)
+            llmConfig.api_key = envKey;
+        const provider = llmConfig.api_key
+            ? createLLMProvider(llmConfig)
+            : createMockProvider(new Map());
+        const builder = new FullCardBuilder(client, provider, docsConfig.llm.model ?? "unknown", () => new Date().toISOString());
+        const tokens = [];
+        if (options.allFailed) {
+            const pages = await stores.pages.listPages({ type: "feishu_doc_card", limit: 100000 });
+            for (const f of failedCards(pages))
+                tokens.push(f.doc_token);
+        }
+        else if (docToken) {
+            tokens.push(docToken);
+        }
+        else {
+            console.error("Provide a doc_token or --all-failed.");
+            process.exit(1);
+        }
+        for (const token of tokens) {
+            const existing = await loadExistingCard(stores, token);
+            if (!existing) {
+                console.warn(`skip ${token}: no existing card`);
+                continue;
+            }
+            // retry intentionally re-evaluates the gate (no force); short/empty docs
+            // stay pointers by design — unlike MCP ingest which forces.
+            const card = await builder.build(existing);
+            await writeCard(stores, card);
+            if (card.extract_level === "pointer") {
+                const reason = card.extract_error ?? card.extract_skipped ?? "unknown";
+                console.log(`${token}: pointer (not upgraded — ${reason})`);
+            }
+            else {
+                console.log(`${token}: full`);
+            }
+        }
+        await stores.db.close();
+    }
+    catch (error) {
+        console.error("docs retry failed:", error instanceof Error ? error.message : String(error));
+        process.exit(1);
+    }
+});
 program.parse(process.argv);
 //# sourceMappingURL=cli.js.map