@macroscope/cli 0.1.0 → 0.2.0

package/dist/cli.js

@@ -9,6 +9,271 @@ var __export = (target, all) => {
     __defProp(target, name, { get: all[name], enumerable: true });
 };
 
+// ../contracts/dist/index.js
+import { z } from "zod";
+import { z as z2 } from "zod";
+import { z as z3 } from "zod";
+import { z as z4 } from "zod";
+import { z as z5 } from "zod";
+import { z as z6 } from "zod";
+var SCHEMA_VERSION, FILESYSTEM_LAYOUT, BlockManifestSchema, SymbolSignatureSchema, UploadPayloadSchema, MeilisearchDocSchema, BlockHitSchema, CodeMatchSchema, IndexBatchRequestSchema, IndexBatchResponseSchema, SearchRequestSchema, SearchResponseSchema, DeleteIndexResponseSchema, ScopeTouchRequestSchema, ScopeTouchResponseSchema, HealthResponseSchema, API_ENDPOINTS, ErrorEnvelopeSchema, ProviderSchema, OAuthCredentialsSchema, UserContextSchema;
+var init_dist = __esm({
+  "../contracts/dist/index.js"() {
+    "use strict";
+    SCHEMA_VERSION = 1;
+    FILESYSTEM_LAYOUT = {
+      user: {
+        /** `~/.macroscope/` */
+        rootDir: ".macroscope",
+        /** `~/.macroscope/credentials` — OAuth token store, mode 0600. */
+        credentialsFile: ".macroscope/credentials",
+        /** `~/.macroscope/machine-id` — stable per-install identifier. */
+        machineIdFile: ".macroscope/machine-id"
+      },
+      project: {
+        /** `<project>/.macroscope/` */
+        rootDir: ".macroscope",
+        /** `<project>/.macroscope/blueprints/` — one folder per kind. */
+        blueprintsDir: ".macroscope/blueprints",
+        /** `<project>/.macroscope/cache/` */
+        cacheDir: ".macroscope/cache",
+        /** `<project>/.macroscope/cache/hashes.json` — content-hash cache used by catch-up scan. */
+        hashesFile: ".macroscope/cache/hashes.json",
+        /** `<project>/.macroscope/cache/queue.json` — watcher push queue, survives restart. */
+        queueFile: ".macroscope/cache/queue.json"
+      }
+    };
+    BlockManifestSchema = z.object({
+      /** Must reference a registered blueprint's `kind`. */
+      kind: z.string().min(1),
+      /** Optional override for the auto-derived block id (POSIX relative path). */
+      id: z.string().optional(),
+      name: z.string().optional(),
+      description: z.string().optional(),
+      tags: z.array(z.string()).optional(),
+      source: z.string().optional(),
+      preview: z.string().optional(),
+      docs: z.string().optional(),
+      tests: z.union([z.string(), z.array(z.string())]).optional()
+    }).passthrough();
+    SymbolSignatureSchema = z2.object({
+      name: z2.string().min(1),
+      kind: z2.string().min(1),
+      signature: z2.string()
+    });
+    UploadPayloadSchema = z2.object({
+      /** Stable block id (POSIX relative path or manifest `id` override). */
+      blockId: z2.string().min(1),
+      kind: z2.string().min(1),
+      name: z2.string().optional(),
+      description: z2.string().optional(),
+      tags: z2.array(z2.string()).optional(),
+      /** Exported symbols extracted from the block's source files. */
+      symbols: z2.array(SymbolSignatureSchema),
+      /** First ~500 chars of the README, if any. */
+      readmeExcerpt: z2.string().optional()
+    });
+    MeilisearchDocSchema = UploadPayloadSchema.extend({
+      /** SHA-256 over the canonical JSON of the UploadPayload (see T6). */
+      contentHash: z2.string().min(1),
+      /** Git remote URL (normalised) or local repo name when no remote exists. */
+      repo: z2.string().min(1),
+      /** hash(machineUuid + absolutePath) — see ARCHITECTURE.md. */
+      worktreeId: z2.string().min(1),
+      /** POSIX path from the worktree root to the block folder. */
+      path: z2.string().min(1),
+      /** Unix epoch milliseconds. Refreshed on every push and by `/scope/touch`. */
+      lastActiveAt: z2.number().int().nonnegative()
+    });
+    BlockHitSchema = z3.object({
+      blockId: z3.string().min(1),
+      kind: z3.string().min(1),
+      name: z3.string().optional(),
+      description: z3.string().optional(),
+      repo: z3.string().min(1),
+      worktreeId: z3.string().min(1),
+      path: z3.string().min(1),
+      /** Relevance score from Meilisearch hybrid ranking. Larger = more relevant. */
+      score: z3.number()
+    });
+    CodeMatchSchema = z3.object({
+      /** POSIX path from the worktree root. */
+      file: z3.string().min(1),
+      /** 1-based line number. */
+      line: z3.number().int().positive(),
+      /** 1-based column number, when available. */
+      column: z3.number().int().positive().optional(),
+      /** A single line of source text containing the match. */
+      preview: z3.string()
+    });
+    IndexBatchRequestSchema = z4.object({
+      /** Per-block docs to upsert. The cloud routes these to the user's Meilisearch index. */
+      upserts: z4.array(MeilisearchDocSchema),
+      /** Block ids to delete. Empty array is valid (upsert-only batch). */
+      deletes: z4.array(z4.string().min(1))
+    });
+    IndexBatchResponseSchema = z4.object({
+      /** Unix epoch ms of server-side acknowledgement. */
+      acceptedAt: z4.number().int().nonnegative(),
+      /** Number of upserts accepted (deletes excluded). */
+      accepted: z4.number().int().nonnegative()
+    });
+    SearchRequestSchema = z4.object({
+      q: z4.string().min(1),
+      /** Restrict to one worktree. Omit to search across all of the user's worktrees. */
+      worktreeId: z4.string().optional(),
+      /** Restrict to one repo. */
+      repo: z4.string().optional(),
+      /** Restrict to one block kind. */
+      kind: z4.string().optional(),
+      /** Cap on returned hits. Server enforces an upper bound. */
+      limit: z4.number().int().positive().optional()
+    });
+    SearchResponseSchema = z4.object({
+      hits: z4.array(BlockHitSchema),
+      /** Approximate total match count from Meilisearch (estimated, not exact). */
+      totalEstimated: z4.number().int().nonnegative()
+    });
+    DeleteIndexResponseSchema = z4.object({
+      deletedAt: z4.number().int().nonnegative()
+    });
+    ScopeTouchRequestSchema = z4.object({
+      worktreeId: z4.string().min(1),
+      repo: z4.string().min(1)
+    });
+    ScopeTouchResponseSchema = z4.object({
+      touchedAt: z4.number().int().nonnegative()
+    });
+    HealthResponseSchema = z4.object({
+      status: z4.literal("ok"),
+      schemaVersion: z4.number().int().positive()
+    });
+    API_ENDPOINTS = {
+      indexBatch: {
+        method: "POST",
+        path: "/index/batch",
+        request: IndexBatchRequestSchema,
+        response: IndexBatchResponseSchema
+      },
+      search: {
+        method: "GET",
+        path: "/search",
+        request: SearchRequestSchema,
+        response: SearchResponseSchema
+      },
+      deleteIndex: {
+        method: "DELETE",
+        path: "/index",
+        request: null,
+        response: DeleteIndexResponseSchema
+      },
+      scopeTouch: {
+        method: "POST",
+        path: "/scope/touch",
+        request: ScopeTouchRequestSchema,
+        response: ScopeTouchResponseSchema
+      },
+      health: {
+        method: "GET",
+        path: "/health",
+        request: null,
+        response: HealthResponseSchema
+      }
+    };
+    ErrorEnvelopeSchema = z5.object({
+      error: z5.object({
+        /** Stable machine-readable code (e.g. `unauthorized`, `validation_failed`). */
+        code: z5.string().min(1),
+        /** Human-readable message. */
+        message: z5.string().min(1),
+        /** Source file path when the error originates from parsing a manifest or other on-disk artifact. Set by the CLI side (see `ScanError`) and by the cloud when validating uploaded manifests. */
+        file: z5.string().optional(),
+        /** Path of the offending field when the error is validation-related. */
+        field: z5.string().optional(),
+        /** Server-assigned request id for log correlation. */
+        requestId: z5.string().optional()
+      })
+    });
+    ProviderSchema = z6.enum(["github", "gitlab"]);
+    OAuthCredentialsSchema = z6.object({
+      provider: ProviderSchema,
+      accessToken: z6.string().min(1),
+      refreshToken: z6.string().min(1).optional(),
+      /** Unix epoch milliseconds at which `accessToken` expires. */
+      expiresAt: z6.number().int().nonnegative().optional(),
+      /** Provider-side user id (e.g. GitHub `id`, GitLab `id`). Optional — useful
+       *  for UI display ("logged in as alexspdlr on github") and for the CLI to
+       *  short-circuit redundant `/user` lookups. */
+      providerUserId: z6.string().min(1).optional()
+    });
+    UserContextSchema = z6.object({
+      userId: z6.string().min(1),
+      indexName: z6.string().min(1),
+      provider: ProviderSchema
+    });
+  }
+});
+
+// src/core/project.ts
+import { existsSync } from "fs";
+import { readFile as readFile2 } from "fs/promises";
+import { dirname as dirname2, join as join2, resolve } from "path";
+import { parse as parseYaml } from "yaml";
+import { z as z7 } from "zod";
+async function findProject(cwd = process.cwd()) {
+  const startedFrom = resolve(cwd);
+  let current = startedFrom;
+  while (true) {
+    if (existsSync(join2(current, ".macroscope"))) {
+      return { root: current, config: await loadConfig(current) };
+    }
+    const parent = dirname2(current);
+    if (parent === current) {
+      throw new ProjectNotFoundError(startedFrom);
+    }
+    current = parent;
+  }
+}
+async function loadConfig(root) {
+  const configPath = join2(root, ".macroscope", "config.yaml");
+  if (!existsSync(configPath)) {
+    return projectConfigSchema.parse({});
+  }
+  const raw = await readFile2(configPath, "utf8");
+  let parsed;
+  try {
+    parsed = parseYaml(raw) ?? {};
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    throw new Error(`Failed to parse ${configPath}: ${msg}`);
+  }
+  const result = projectConfigSchema.safeParse(parsed);
+  if (!result.success) {
+    const issues = result.error.issues.map((i) => `  - ${i.path.join(".") || "(root)"}: ${i.message}`).join("\n");
+    throw new Error(`Invalid project config at ${configPath}:
+${issues}`);
+  }
+  return result.data;
+}
+var projectConfigSchema, ProjectNotFoundError;
+var init_project = __esm({
+  "src/core/project.ts"() {
+    "use strict";
+    projectConfigSchema = z7.object({
+      scanRoots: z7.array(z7.string()).default(["."]),
+      ignore: z7.array(z7.string()).default(["node_modules", ".git", "dist", ".macroscope"])
+    });
+    ProjectNotFoundError = class extends Error {
+      constructor(startedFrom) {
+        super(
+          `No macroscope project found. Walked up from ${startedFrom} looking for a .macroscope/ directory but reached the filesystem root. Run \`npm create macroscope\` to scaffold one, or cd into an existing project.`
+        );
+        this.name = "ProjectNotFoundError";
+      }
+    };
+  }
+});
+
 // src/core/handler.ts
 function isHandler(value) {
   if (typeof value !== "object" || value === null) return false;
@@ -70,13 +335,13 @@ var init_handler = __esm({
 });
 
 // src/core/blueprints.ts
-import { existsSync } from "fs";
+import { existsSync as existsSync2 } from "fs";
 import { readdir } from "fs/promises";
-import { join } from "path";
+import { join as join3 } from "path";
 import { createJiti } from "jiti";
 async function loadBlueprints(project) {
-  const blueprintsDir = join(project.root, ".macroscope", "blueprints");
-  if (!existsSync(blueprintsDir)) {
+  const blueprintsDir = join3(project.root, ".macroscope", "blueprints");
+  if (!existsSync2(blueprintsDir)) {
     return { blueprints: [], errors: [] };
   }
   let entries;
@@ -90,7 +355,7 @@ async function loadBlueprints(project) {
   const jiti = createJiti(import.meta.url);
   for (const entry of entries) {
     if (!entry.isDirectory()) continue;
-    const folder = join(blueprintsDir, entry.name);
+    const folder = join3(blueprintsDir, entry.name);
     const kind = entry.name.normalize("NFC");
     const result = await loadOne(folder, kind, jiti);
     if (result.ok) {
@@ -106,8 +371,8 @@ async function loadBlueprints(project) {
 async function loadOne(folder, kind, jiti) {
   let file = null;
   for (const filename of HANDLER_FILENAMES) {
-    const candidate = join(folder, filename);
-    if (existsSync(candidate)) {
+    const candidate = join3(folder, filename);
+    if (existsSync2(candidate)) {
       file = candidate;
       break;
     }
@@ -194,266 +459,76 @@ var init_blueprints = __esm({
   }
 });
 
-// src/core/project.ts
-import { existsSync as existsSync2 } from "fs";
-import { readFile } from "fs/promises";
-import { dirname, join as join2, resolve } from "path";
-import { parse as parseYaml } from "yaml";
-import { z } from "zod";
-async function findProject(cwd = process.cwd()) {
-  const startedFrom = resolve(cwd);
-  let current = startedFrom;
-  while (true) {
-    if (existsSync2(join2(current, ".macroscope"))) {
-      return { root: current, config: await loadConfig(current) };
-    }
-    const parent = dirname(current);
-    if (parent === current) {
-      throw new ProjectNotFoundError(startedFrom);
+// src/core/manifest.ts
+var manifestSchema;
+var init_manifest = __esm({
+  "src/core/manifest.ts"() {
+    "use strict";
+    init_dist();
+    manifestSchema = BlockManifestSchema;
+  }
+});
+
+// src/core/scanner.ts
+import { createHash as createHash3 } from "crypto";
+import { existsSync as existsSync3 } from "fs";
+import { readFile as readFile6, readdir as readdir2 } from "fs/promises";
+import { dirname as dirname4, join as join5, relative, resolve as resolve2, sep } from "path";
+import { parse as parseYaml2 } from "yaml";
+async function scan(project) {
+  const blocks = [];
+  const errors = [];
+  const ignore = new Set(project.config.ignore);
+  const seenIds = /* @__PURE__ */ new Set();
+  for (const root of project.config.scanRoots) {
+    const start = join5(project.root, root);
+    if (!existsSync3(start)) continue;
+    for await (const manifestPath of findManifests(start, ignore)) {
+      const result = await parseBlock(manifestPath, project.root);
+      if (result.kind === "ok") {
+        errors.push(...result.errors);
+        if (seenIds.has(result.block.id)) {
+          errors.push({
+            file: manifestPath,
+            kind: "validation",
+            message: `Duplicate block id "${result.block.id}" at ${manifestPath}. Set an explicit \`id:\` field to disambiguate.`,
+            field: "id"
+          });
+        } else {
+          seenIds.add(result.block.id);
+          blocks.push(result.block);
+        }
+      } else {
+        errors.push(result.error);
+      }
     }
-    current = parent;
   }
+  blocks.sort((a, b) => a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
+  return { blocks, errors };
 }
-async function loadConfig(root) {
-  const configPath = join2(root, ".macroscope", "config.yaml");
-  if (!existsSync2(configPath)) {
-    return projectConfigSchema.parse({});
-  }
-  const raw = await readFile(configPath, "utf8");
-  let parsed;
+async function* findManifests(dir, ignore) {
+  let entries;
   try {
-    parsed = parseYaml(raw) ?? {};
-  } catch (err) {
-    const msg = err instanceof Error ? err.message : String(err);
-    throw new Error(`Failed to parse ${configPath}: ${msg}`);
+    entries = await readdir2(dir, { withFileTypes: true });
+  } catch {
+    return;
   }
-  const result = projectConfigSchema.safeParse(parsed);
-  if (!result.success) {
-    const issues = result.error.issues.map((i) => `  - ${i.path.join(".") || "(root)"}: ${i.message}`).join("\n");
-    throw new Error(`Invalid project config at ${configPath}:
-${issues}`);
-  }
-  return result.data;
-}
-var projectConfigSchema, ProjectNotFoundError;
-var init_project = __esm({
-  "src/core/project.ts"() {
-    "use strict";
-    projectConfigSchema = z.object({
-      scanRoots: z.array(z.string()).default(["."]),
-      ignore: z.array(z.string()).default(["node_modules", ".git", "dist", ".macroscope"])
-    });
-    ProjectNotFoundError = class extends Error {
-      constructor(startedFrom) {
-        super(
-          `No macroscope project found. Walked up from ${startedFrom} looking for a .macroscope/ directory but reached the filesystem root. Run \`npm create macroscope\` to scaffold one, or cd into an existing project.`
-        );
-        this.name = "ProjectNotFoundError";
-      }
-    };
-  }
-});
-
-// ../contracts/dist/index.js
-import { z as z2 } from "zod";
-import { z as z22 } from "zod";
-import { z as z3 } from "zod";
-import { z as z4 } from "zod";
-import { z as z5 } from "zod";
-var BlockManifestSchema, SymbolSignatureSchema, UploadPayloadSchema, MeilisearchDocSchema, BlockHitSchema, CodeMatchSchema, IndexBatchRequestSchema, IndexBatchResponseSchema, SearchRequestSchema, SearchResponseSchema, DeleteIndexResponseSchema, ScopeTouchRequestSchema, ScopeTouchResponseSchema, HealthResponseSchema, ErrorEnvelopeSchema;
-var init_dist = __esm({
-  "../contracts/dist/index.js"() {
-    "use strict";
-    BlockManifestSchema = z2.object({
-      /** Must reference a registered blueprint's `kind`. */
-      kind: z2.string().min(1),
-      /** Optional override for the auto-derived block id (POSIX relative path). */
-      id: z2.string().optional(),
-      name: z2.string().optional(),
-      description: z2.string().optional(),
-      tags: z2.array(z2.string()).optional(),
-      source: z2.string().optional(),
-      preview: z2.string().optional(),
-      docs: z2.string().optional(),
-      tests: z2.union([z2.string(), z2.array(z2.string())]).optional()
-    }).passthrough();
-    SymbolSignatureSchema = z22.object({
-      name: z22.string().min(1),
-      kind: z22.string().min(1),
-      signature: z22.string()
-    });
-    UploadPayloadSchema = z22.object({
-      /** Stable block id (POSIX relative path or manifest `id` override). */
-      blockId: z22.string().min(1),
-      kind: z22.string().min(1),
-      name: z22.string().optional(),
-      description: z22.string().optional(),
-      tags: z22.array(z22.string()).optional(),
-      /** Exported symbols extracted from the block's source files. */
-      symbols: z22.array(SymbolSignatureSchema),
-      /** First ~500 chars of the README, if any. */
-      readmeExcerpt: z22.string().optional()
-    });
-    MeilisearchDocSchema = UploadPayloadSchema.extend({
-      /** SHA-256 over the canonical JSON of the UploadPayload (see T6). */
-      contentHash: z22.string().min(1),
-      /** Git remote URL (normalised) or local repo name when no remote exists. */
-      repo: z22.string().min(1),
-      /** hash(machineUuid + absolutePath) — see ARCHITECTURE.md. */
-      worktreeId: z22.string().min(1),
-      /** POSIX path from the worktree root to the block folder. */
-      path: z22.string().min(1),
-      /** Unix epoch milliseconds. Refreshed on every push and by `/scope/touch`. */
-      lastActiveAt: z22.number().int().nonnegative()
-    });
-    BlockHitSchema = z3.object({
-      blockId: z3.string().min(1),
-      kind: z3.string().min(1),
-      name: z3.string().optional(),
-      description: z3.string().optional(),
-      repo: z3.string().min(1),
-      worktreeId: z3.string().min(1),
-      path: z3.string().min(1),
-      /** Relevance score from Meilisearch hybrid ranking. Larger = more relevant. */
-      score: z3.number()
-    });
-    CodeMatchSchema = z3.object({
-      /** POSIX path from the worktree root. */
-      file: z3.string().min(1),
-      /** 1-based line number. */
-      line: z3.number().int().positive(),
-      /** 1-based column number, when available. */
-      column: z3.number().int().positive().optional(),
-      /** A single line of source text containing the match. */
-      preview: z3.string()
-    });
-    IndexBatchRequestSchema = z4.object({
-      /** Per-block docs to upsert. The cloud routes these to the user's Meilisearch index. */
-      upserts: z4.array(MeilisearchDocSchema),
-      /** Block ids to delete. Empty array is valid (upsert-only batch). */
-      deletes: z4.array(z4.string().min(1))
-    });
-    IndexBatchResponseSchema = z4.object({
-      /** Unix epoch ms of server-side acknowledgement. */
-      acceptedAt: z4.number().int().nonnegative(),
-      /** Number of upserts accepted (deletes excluded). */
-      accepted: z4.number().int().nonnegative()
-    });
-    SearchRequestSchema = z4.object({
-      q: z4.string().min(1),
-      /** Restrict to one worktree. Omit to search across all of the user's worktrees. */
-      worktreeId: z4.string().optional(),
-      /** Restrict to one repo. */
-      repo: z4.string().optional(),
-      /** Restrict to one block kind. */
-      kind: z4.string().optional(),
-      /** Cap on returned hits. Server enforces an upper bound. */
-      limit: z4.number().int().positive().optional()
-    });
-    SearchResponseSchema = z4.object({
-      hits: z4.array(BlockHitSchema),
-      /** Approximate total match count from Meilisearch (estimated, not exact). */
-      totalEstimated: z4.number().int().nonnegative()
-    });
-    DeleteIndexResponseSchema = z4.object({
-      deletedAt: z4.number().int().nonnegative()
-    });
-    ScopeTouchRequestSchema = z4.object({
-      worktreeId: z4.string().min(1),
-      repo: z4.string().min(1)
-    });
-    ScopeTouchResponseSchema = z4.object({
-      touchedAt: z4.number().int().nonnegative()
-    });
-    HealthResponseSchema = z4.object({
-      status: z4.literal("ok"),
-      schemaVersion: z4.number().int().positive()
-    });
-    ErrorEnvelopeSchema = z5.object({
-      error: z5.object({
-        /** Stable machine-readable code (e.g. `unauthorized`, `validation_failed`). */
-        code: z5.string().min(1),
-        /** Human-readable message. */
-        message: z5.string().min(1),
-        /** Source file path when the error originates from parsing a manifest or other on-disk artifact. Set by the CLI side (see `ScanError`) and by the cloud when validating uploaded manifests. */
-        file: z5.string().optional(),
-        /** Path of the offending field when the error is validation-related. */
-        field: z5.string().optional(),
-        /** Server-assigned request id for log correlation. */
-        requestId: z5.string().optional()
-      })
-    });
-  }
-});
-
-// src/core/manifest.ts
-var manifestSchema;
-var init_manifest = __esm({
-  "src/core/manifest.ts"() {
-    "use strict";
-    init_dist();
-    manifestSchema = BlockManifestSchema;
-  }
-});
-
-// src/core/scanner.ts
-import { createHash } from "crypto";
-import { existsSync as existsSync3 } from "fs";
-import { readFile as readFile2, readdir as readdir2 } from "fs/promises";
-import { dirname as dirname2, join as join3, relative, sep } from "path";
-import { parse as parseYaml2 } from "yaml";
-async function scan(project) {
-  const blocks = [];
-  const errors = [];
-  const ignore = new Set(project.config.ignore);
-  const seenIds = /* @__PURE__ */ new Set();
-  for (const root of project.config.scanRoots) {
-    const start = join3(project.root, root);
-    if (!existsSync3(start)) continue;
-    for await (const manifestPath of findManifests(start, ignore)) {
-      const result = await parseBlock(manifestPath, project.root);
-      if (result.kind === "ok") {
-        if (seenIds.has(result.block.id)) {
-          errors.push({
-            file: manifestPath,
-            kind: "validation",
-            message: `Duplicate block id "${result.block.id}" at ${manifestPath}. Set an explicit \`id:\` field to disambiguate.`,
-            field: "id"
-          });
-        } else {
-          seenIds.add(result.block.id);
-          blocks.push(result.block);
-        }
-      } else {
-        errors.push(result.error);
-      }
-    }
-  }
-  blocks.sort((a, b) => a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
-  return { blocks, errors };
-}
-async function* findManifests(dir, ignore) {
-  let entries;
-  try {
-    entries = await readdir2(dir, { withFileTypes: true });
-  } catch {
-    return;
-  }
-  for (const entry of entries) {
-    if (entry.isFile() && entry.name === "macroscope.yaml") {
-      yield join3(dir, entry.name);
-    }
-  }
-  for (const entry of entries) {
-    if (!entry.isDirectory()) continue;
-    if (ignore.has(entry.name)) continue;
-    yield* findManifests(join3(dir, entry.name), ignore);
+  for (const entry of entries) {
+    if (entry.isFile() && entry.name === "macroscope.yaml") {
+      yield join5(dir, entry.name);
+    }
+  }
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    if (entry.isSymbolicLink()) continue;
+    if (ignore.has(entry.name)) continue;
+    yield* findManifests(join5(dir, entry.name), ignore);
   }
 }
 async function parseBlock(manifestPath, projectRoot) {
   let raw;
   try {
-    raw = await readFile2(manifestPath, "utf8");
+    raw = await readFile6(manifestPath, "utf8");
   } catch (err) {
     return {
       kind: "err",
@@ -491,15 +566,88 @@ async function parseBlock(manifestPath, projectRoot) {
     };
   }
   const manifest = parsed.data;
-  const blockDir = dirname2(manifestPath);
+  const blockDir = dirname4(manifestPath);
   const defaultId = toPosix(relative(projectRoot, blockDir));
   const id = manifest.id ?? defaultId;
-  const contentHash = createHash("sha256").update(raw).digest("hex");
+  const contentHash = createHash3("sha256").update(raw).digest("hex");
+  const fileErrors = [];
+  const resolvedPaths = resolveManifestPaths(
+    manifest,
+    blockDir,
+    projectRoot,
+    manifestPath,
+    fileErrors
+  );
   return {
     kind: "ok",
-    block: { id, path: blockDir, manifest, contentHash }
+    block: { id, path: blockDir, manifest, contentHash, resolvedPaths },
+    errors: fileErrors
   };
 }
+function resolveManifestPaths(manifest, blockDir, projectRoot, manifestPath, errors) {
+  const testsRaw = manifest.tests;
+  const testsArray = testsRaw == null ? void 0 : typeof testsRaw === "string" ? [testsRaw] : testsRaw;
+  const hasAnyField = FILE_FIELDS.some((f) => manifest[f] != null) || testsArray != null;
+  if (!hasAnyField) return void 0;
+  const resolved = {};
+  for (const field of FILE_FIELDS) {
+    const value = manifest[field];
+    if (value == null) continue;
+    const abs = resolve2(blockDir, value);
+    if (!isInsideProject(abs, projectRoot)) {
+      errors.push({
+        file: manifestPath,
+        kind: "validation",
+        field,
+        message: `Field \`${field}\` in ${manifestPath} resolves to ${abs}, which is outside the project root ${projectRoot}.`
+      });
+      continue;
+    }
+    if (!existsSync3(abs)) {
+      errors.push({
+        file: manifestPath,
+        kind: "io",
+        field,
+        message: `Field \`${field}\` in ${manifestPath} references ${abs}, which does not exist.`
+      });
+      continue;
+    }
+    resolved[field] = abs;
+  }
+  if (testsArray) {
+    const resolvedTests = [];
+    for (const t of testsArray) {
+      const abs = resolve2(blockDir, t);
+      if (!isInsideProject(abs, projectRoot)) {
+        errors.push({
+          file: manifestPath,
+          kind: "validation",
+          field: "tests",
+          message: `Field \`tests\` in ${manifestPath} resolves to ${abs}, which is outside the project root ${projectRoot}.`
+        });
+        continue;
+      }
+      if (!existsSync3(abs)) {
+        errors.push({
+          file: manifestPath,
+          kind: "io",
+          field: "tests",
+          message: `Field \`tests\` in ${manifestPath} references ${abs}, which does not exist.`
+        });
+        continue;
+      }
+      resolvedTests.push(abs);
+    }
+    if (resolvedTests.length > 0) {
+      resolved.tests = resolvedTests;
+    }
+  }
+  return Object.keys(resolved).length > 0 ? resolved : void 0;
+}
+function isInsideProject(absPath, projectRoot) {
+  const normalized = resolve2(absPath);
+  return normalized === projectRoot || normalized.startsWith(projectRoot + sep);
+}
 function firstZodIssue(err) {
   const issue = err.issues[0];
   if (!issue) return { fieldPath: "(root)", message: "unknown validation error" };
@@ -509,10 +657,46 @@ function firstZodIssue(err) {
 function toPosix(p) {
   return p.split(sep).join("/");
 }
+var FILE_FIELDS;
 var init_scanner = __esm({
   "src/core/scanner.ts"() {
     "use strict";
     init_manifest();
+    FILE_FIELDS = ["source", "docs", "preview"];
+  }
+});
+
+// src/util/process-group.ts
+import { spawn as nodeSpawn } from "child_process";
+function spawnDetached(cmd, args, opts = {}, deps = {}) {
+  const spawnImpl = deps.spawn ?? nodeSpawn;
+  return spawnImpl(cmd, args, { ...opts, detached: true });
+}
+async function killTree(child, deps = {}) {
+  const kill = deps.kill ?? ((pid2, sig) => process.kill(pid2, sig));
+  const grace = deps.gracePeriodMs ?? DEFAULT_GRACE_MS;
+  const pid = child.pid;
+  if (!pid) return;
+  const safeKill = (sig) => {
+    try {
+      kill(-pid, sig);
+      return true;
+    } catch (err) {
+      const code = err.code;
+      if (code === "ESRCH") return false;
+      throw err;
+    }
+  };
+  if (!safeKill("SIGTERM")) return;
+  await new Promise((r) => setTimeout(r, grace));
+  if (child.killed) return;
+  safeKill("SIGKILL");
+}
+var DEFAULT_GRACE_MS;
+var init_process_group = __esm({
+  "src/util/process-group.ts"() {
+    "use strict";
+    DEFAULT_GRACE_MS = 5e3;
   }
 });
 
@@ -587,7 +771,6 @@ __export(terminal_ws_exports, {
   attachTerminalWs: () => attachTerminalWs,
   setSpawnOverride: () => setSpawnOverride
 });
-import { spawn } from "child_process";
 import { WebSocketServer } from "ws";
 function setSpawnOverride(override) {
   spawnOverride = override;
@@ -600,103 +783,2051 @@ function attachTerminalWs(httpServer, defaultCwd) {
       socket.destroy();
       return;
     }
-    wss.handleUpgrade(req, socket, head, (ws) => {
-      handleConnection(ws, req, defaultCwd);
+    wss.handleUpgrade(req, socket, head, (ws) => {
+      handleConnection(ws, req, defaultCwd);
+    });
+  });
+}
+async function handleConnection(ws, req, defaultCwd) {
+  const url = new URL(req.url ?? "/", "http://localhost");
+  const blockId = url.searchParams.get("blockId") ?? "";
+  const viewKey = url.searchParams.get("viewKey") ?? "";
+  let command;
+  let cwd;
+  if (spawnOverride) {
+    command = spawnOverride.command;
+    cwd = spawnOverride.cwd ?? defaultCwd;
+  } else {
+    const resolved = await resolveTerminalCommand(defaultCwd, blockId, viewKey);
+    if (!resolved.ok) {
+      send(ws, { type: "error", message: resolved.error });
+      ws.close();
+      return;
+    }
+    command = resolved.command;
+    cwd = resolved.cwd;
+  }
+  if (command.length === 0) {
+    send(ws, { type: "error", message: "empty command" });
+    ws.close();
+    return;
+  }
+  send(ws, { type: "open", command });
+  const [bin, ...args] = command;
+  let child;
+  try {
+    child = spawnDetached(bin, args, { cwd, stdio: ["pipe", "pipe", "pipe"] });
+  } catch (err) {
+    send(ws, { type: "error", message: `failed to spawn: ${err.message}` });
+    ws.close();
+    return;
+  }
+  child.stdout?.on("data", (chunk) => send(ws, { type: "out", data: chunk.toString() }));
+  child.stderr?.on("data", (chunk) => send(ws, { type: "err", data: chunk.toString() }));
+  child.on("exit", (code, signal) => {
+    send(ws, { type: "close", code, signal });
+    ws.close();
+  });
+  child.on("error", (err) => {
+    send(ws, { type: "error", message: err.message });
+    ws.close();
+  });
+  ws.on("message", (raw) => {
+    let frame;
+    try {
+      frame = JSON.parse(raw.toString());
+    } catch {
+      return;
+    }
+    if (frame.type === "in" && typeof frame.data === "string") {
+      child.stdin?.write(frame.data);
+    } else if (frame.type === "eof") {
+      child.stdin?.end();
+    }
+  });
+  ws.on("close", () => {
+    if (!child.killed) void killTree(child);
+  });
+}
+function send(ws, frame) {
+  try {
+    ws.send(JSON.stringify(frame));
+  } catch {
+  }
+}
+var spawnOverride;
+var init_terminal_ws = __esm({
+  "src/ui/api/terminal-ws.ts"() {
+    "use strict";
+    init_process_group();
+    init_terminal_resolver();
+    spawnOverride = null;
+  }
+});
+
+// src/cli.ts
+import { dirname as dirname8, resolve as resolve4 } from "path";
+import { fileURLToPath } from "url";
+import { Command, Option } from "commander";
+import importLocal from "import-local";
+
+// src/auth/errors.ts
+var LoginError = class extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "LoginError";
+  }
+  toEnvelope() {
+    return { error: { code: this.code, message: this.message } };
+  }
+};
+
+// src/auth/callback-server.ts
+import { createServer } from "http";
+var CALLBACK_PORT = 51337;
+var CALLBACK_PATH = "/callback";
+var REDIRECT_URI = `http://127.0.0.1:${CALLBACK_PORT}${CALLBACK_PATH}`;
+function awaitCallback(opts) {
+  let settled = false;
+  let resolveResult;
+  let rejectResult;
+  let resolveBound;
+  let rejectBound;
+  const result = new Promise((res, rej) => {
+    resolveResult = res;
+    rejectResult = rej;
+  });
+  const bound = new Promise((res, rej) => {
+    resolveBound = res;
+    rejectBound = rej;
+  });
+  const server = createServer((req, res) => {
+    const url = new URL(req.url ?? "/", `http://127.0.0.1:${CALLBACK_PORT}`);
+    if (url.pathname !== CALLBACK_PATH) {
+      res.statusCode = 404;
+      res.end("not found");
+      return;
+    }
+    const state = url.searchParams.get("state") ?? "";
+    const code = url.searchParams.get("code") ?? "";
+    if (state !== opts.expectedState) {
+      res.statusCode = 400;
+      res.end("state mismatch \u2014 close this tab and rerun `macroscope login`");
+      settle(
+        () => rejectResult(new LoginError("state_mismatch", "OAuth state parameter did not match"))
+      );
+      return;
+    }
+    if (!code) {
+      res.statusCode = 400;
+      res.end("missing code");
+      settle(
+        () => rejectResult(new LoginError("token_exchange_failed", "callback missing `code` parameter"))
+      );
+      return;
+    }
+    res.statusCode = 200;
+    res.setHeader("content-type", "text/html; charset=utf-8");
+    res.end(
+      "<!doctype html><meta charset=utf-8><title>macroscope</title><p>Login complete. You can close this tab.</p>"
+    );
+    settle(() => resolveResult({ code }));
+  });
+  const closeServer = () => new Promise((r) => {
+    const s = server;
+    if (typeof s.closeAllConnections === "function") s.closeAllConnections();
+    server.close(() => r());
+  });
+  function settle(fn) {
+    if (settled) return;
+    settled = true;
+    void closeServer().finally(fn);
+  }
+  server.on("error", (err) => {
+    if (err.code === "EADDRINUSE") {
+      const e = new LoginError(
+        "port_in_use",
+        `Port ${CALLBACK_PORT} is in use; close the process holding it, or rerun later`
+      );
+      rejectBound(e);
+      settle(() => rejectResult(e));
+    } else {
+      rejectBound(err);
+      settle(() => rejectResult(err));
+    }
+  });
+  let timer;
+  server.on("listening", () => {
+    resolveBound();
+    timer = setTimeout(() => {
+      settle(
+        () => rejectResult(
+          new LoginError(
+            "callback_timeout",
+            `no OAuth callback received within ${opts.timeoutMs}ms`
+          )
+        )
+      );
+    }, opts.timeoutMs);
+    if (typeof timer.unref === "function") timer.unref();
+  });
+  server.listen(CALLBACK_PORT, "127.0.0.1");
+  if (opts.signal) {
+    const onAbort = () => {
+      if (timer) clearTimeout(timer);
+      settle(() => rejectResult(new LoginError("login_cancelled", "login aborted")));
+    };
+    if (opts.signal.aborted) onAbort();
+    else opts.signal.addEventListener("abort", onAbort, { once: true });
+  }
+  bound.catch(() => {
+  });
+  result.catch(() => {
+  });
+  return { bound, result };
+}
+
+// src/auth/credentials.ts
+init_dist();
+import { chmod, stat as fsStat, mkdir, writeFile } from "fs/promises";
+import { homedir } from "os";
+import { dirname, join } from "path";
+function credentialsPath(homeDir = homedir()) {
+  return join(homeDir, FILESYSTEM_LAYOUT.user.credentialsFile);
+}
+async function writeCredentials(creds, opts = {}) {
+  const path2 = credentialsPath(opts.homeDir);
+  await mkdir(dirname(path2), { recursive: true });
+  const statFn = opts._statForTest ?? fsStat;
+  try {
+    const s = await statFn(path2);
+    if (process.platform !== "win32" && typeof process.getuid === "function") {
+      const uid = process.getuid();
+      if (s.uid !== uid) {
+        throw new LoginError(
+          "credentials_write_failed",
+          `${path2} is owned by another user (uid ${s.uid}); refusing to overwrite`
+        );
+      }
+    }
+  } catch (err) {
+    if (err instanceof LoginError) throw err;
+    if (err.code !== "ENOENT") throw err;
+  }
+  const json = `${JSON.stringify(creds, null, 2)}
+`;
+  await writeFile(path2, json, { mode: 384 });
+  await chmod(path2, 384);
+}
+
+// src/auth/pkce.ts
+import { createHash, randomBytes } from "crypto";
+function generateVerifier() {
+  return base64url(randomBytes(32));
+}
+function challengeFromVerifier(verifier) {
+  return base64url(createHash("sha256").update(verifier, "ascii").digest());
+}
+function base64url(buf) {
+  return buf.toString("base64").replaceAll("+", "-").replaceAll("/", "_").replaceAll("=", "");
+}
+
+// src/auth/state.ts
+import { randomBytes as randomBytes2 } from "crypto";
+function generateState() {
+  return randomBytes2(24).toString("base64").replaceAll("+", "-").replaceAll("/", "_").replaceAll("=", "");
+}
+
+// src/auth/token-exchange.ts
+async function exchangeCodeForToken(provider, opts) {
+  const body = new URLSearchParams({
+    grant_type: "authorization_code",
+    code: opts.code,
+    code_verifier: opts.codeVerifier,
+    redirect_uri: opts.redirectUri,
+    client_id: opts.clientId
+  });
+  const secret = opts.clientSecret ?? provider.clientSecret;
+  if (secret) body.set("client_secret", secret);
+  const fetchFn = opts.fetchFn ?? fetch;
+  let res;
+  try {
+    res = await fetchFn(provider.tokenUrl, {
+      method: "POST",
+      headers: {
+        accept: "application/json",
+        "content-type": "application/x-www-form-urlencoded",
+        "user-agent": "macroscope"
+      },
+      body: body.toString()
+    });
+  } catch (err) {
+    throw new LoginError(
+      "token_exchange_failed",
+      `network error talking to ${provider.tokenUrl}: ${err.message}`
+    );
+  }
+  if (!res.ok) {
+    const detail = await res.text().catch(() => "");
+    throw new LoginError(
+      "token_exchange_failed",
+      `${provider.humanName} token endpoint returned ${res.status}: ${detail.slice(0, 200)}`
+    );
+  }
+  const json = await res.json();
+  if (!json.access_token) {
+    throw new LoginError(
+      "token_exchange_failed",
+      `${provider.humanName} token endpoint returned 200 but no access_token`
+    );
+  }
+  return {
+    accessToken: json.access_token,
+    refreshToken: json.refresh_token,
+    expiresAt: typeof json.expires_in === "number" ? Date.now() + json.expires_in * 1e3 : void 0
+  };
+}
+
+// src/auth/user-info.ts
+async function fetchUserInfo(provider, accessToken, fetchFn = fetch) {
+  let res;
+  try {
+    res = await fetchFn(provider.userInfoUrl, {
+      headers: {
+        authorization: `Bearer ${accessToken}`,
+        accept: "application/json",
+        "user-agent": "macroscope"
+      }
+    });
+  } catch (err) {
+    throw new LoginError(
+      "user_info_failed",
+      `network error talking to ${provider.userInfoUrl}: ${err.message}`
+    );
+  }
+  if (!res.ok) {
+    throw new LoginError(
+      "user_info_failed",
+      `${provider.humanName} user-info endpoint returned ${res.status}`
+    );
+  }
+  return provider.parseProviderUserId(await res.json());
+}
+
+// src/auth/login.ts
+async function login(opts) {
+  const { provider, clientId } = opts;
+  const verifier = generateVerifier();
+  const challenge = challengeFromVerifier(verifier);
+  const state = generateState();
+  const authorizeUrl = new URL(provider.authorizeUrl);
+  authorizeUrl.searchParams.set("client_id", clientId);
+  authorizeUrl.searchParams.set("redirect_uri", REDIRECT_URI);
+  authorizeUrl.searchParams.set("response_type", "code");
+  authorizeUrl.searchParams.set("state", state);
+  authorizeUrl.searchParams.set("code_challenge", challenge);
+  authorizeUrl.searchParams.set("code_challenge_method", "S256");
+  if (provider.defaultScopes.length > 0) {
+    authorizeUrl.searchParams.set("scope", provider.defaultScopes.join(" "));
+  }
+  const { bound, result } = awaitCallback({
+    expectedState: state,
+    timeoutMs: opts.timeoutMs ?? 5 * 6e4,
+    signal: opts.signal
+  });
+  try {
+    await bound;
+  } catch {
+    return await result;
+  }
+  if (opts.openBrowser) {
+    await opts.openBrowser(authorizeUrl.toString());
+  } else {
+    const open = (await import("open")).default;
+    await open(authorizeUrl.toString());
+  }
+  const { code } = await result;
+  const token = await exchangeCodeForToken(provider, {
+    code,
+    codeVerifier: verifier,
+    redirectUri: REDIRECT_URI,
+    clientId,
+    clientSecret: opts.clientSecret
+  });
+  const providerUserId = await fetchUserInfo(provider, token.accessToken);
+  const creds = {
+    provider: provider.id,
+    accessToken: token.accessToken,
+    refreshToken: token.refreshToken,
+    expiresAt: token.expiresAt,
+    providerUserId
+  };
+  await writeCredentials(creds, { homeDir: opts.homeDir });
+  return creds;
+}
+
+// src/auth/providers/github.ts
+var github = {
+  id: "github",
+  humanName: "GitHub",
+  authorizeUrl: "https://github.com/login/oauth/authorize",
+  tokenUrl: "https://github.com/login/oauth/access_token",
+  userInfoUrl: "https://api.github.com/user",
+  defaultScopes: [],
+  // Hardcoded fallback is intentionally a placeholder — the release build
+  // substitutes the public OAuth-App secret. Env var wins at runtime.
+  clientSecret: process.env.MACROSCOPE_GITHUB_CLIENT_SECRET ?? "REPLACE_AT_BUILD",
+  parseProviderUserId(userInfo) {
+    if (typeof userInfo === "object" && userInfo !== null && "id" in userInfo && (typeof userInfo.id === "number" || typeof userInfo.id === "string")) {
+      return String(userInfo.id);
+    }
+    throw new Error("GitHub /user response missing numeric `id` field");
+  }
+};
+
+// src/auth/providers/gitlab.ts
+var gitlab = {
+  id: "gitlab",
+  humanName: "GitLab",
+  authorizeUrl: "https://gitlab.com/oauth/authorize",
+  tokenUrl: "https://gitlab.com/oauth/token",
+  userInfoUrl: "https://gitlab.com/api/v4/user",
+  defaultScopes: ["read_user"],
+  parseProviderUserId(userInfo) {
+    if (typeof userInfo === "object" && userInfo !== null && "id" in userInfo && (typeof userInfo.id === "number" || typeof userInfo.id === "string")) {
+      return String(userInfo.id);
+    }
+    throw new Error("GitLab /api/v4/user response missing `id` field");
+  }
+};
+
+// src/auth/providers/index.ts
+var REGISTRY = {
+  github,
+  gitlab
+};
+function getProvider(id) {
+  const p = REGISTRY[id];
+  if (!p) throw new Error(`unknown provider: ${id}`);
+  return p;
+}
+
+// src/auth/cli.ts
+var CLIENT_ID_ENV = {
+  github: "MACROSCOPE_GITHUB_CLIENT_ID",
+  gitlab: "MACROSCOPE_GITLAB_CLIENT_ID"
+};
+var CLIENT_ID_FALLBACK = {
+  github: "REPLACE_AT_BUILD",
+  gitlab: "REPLACE_AT_BUILD"
+};
+async function runLoginCommand(opts) {
+  const provider = getProvider(opts.providerId);
+  const t = opts._testOverrides ?? {};
+  const write = t.write ?? ((s) => void process.stdout.write(s));
+  const clientId = t.clientId ?? process.env[CLIENT_ID_ENV[opts.providerId]] ?? CLIENT_ID_FALLBACK[opts.providerId];
+  const clientSecret = opts.providerId === "github" ? t.clientSecret ?? process.env.MACROSCOPE_GITHUB_CLIENT_SECRET ?? provider.clientSecret : void 0;
+  try {
+    const creds = await login({
+      provider,
+      clientId,
+      clientSecret,
+      homeDir: t.homeDir,
+      openBrowser: t.openBrowser,
+      signal: opts.signal
+    });
+    if (opts.json) {
+      write(
+        `${JSON.stringify({
+          ok: true,
+          provider: creds.provider,
+          providerUserId: creds.providerUserId
+        })}
+`
+      );
+    } else {
+      write(`Logged in to ${provider.humanName} as ${creds.providerUserId}
+`);
+    }
+    return 0;
+  } catch (err) {
+    const loginErr = err instanceof LoginError ? err : new LoginError("credentials_write_failed", err.message);
+    if (opts.json) {
+      write(`${JSON.stringify(loginErr.toEnvelope())}
+`);
+    } else {
+      write(`Error: ${loginErr.message} (${loginErr.code})
+`);
+    }
+    return 1;
+  }
+}
+
+// src/util/lifecycle.ts
+var SIGNALS = ["SIGINT", "SIGTERM", "SIGHUP"];
+function installLifecycle(opts) {
+  const proc = opts.proc ?? process;
+  const stdin = opts.stdin ?? proc.stdin;
+  const hardTimeoutMs = opts.hardTimeoutMs ?? 5e3;
+  let fired = false;
+  const fire = (reason) => {
+    if (fired) return;
+    fired = true;
+    const hardKill = setTimeout(() => {
+      proc.exit(1);
+    }, hardTimeoutMs);
+    if (typeof hardKill.unref === "function") hardKill.unref();
+    Promise.resolve(opts.onShutdown(reason)).finally(() => {
+      clearTimeout(hardKill);
+    });
+  };
+  const signalHandlers = /* @__PURE__ */ new Map();
+  for (const sig of SIGNALS) {
+    const h = () => fire(sig);
+    signalHandlers.set(sig, h);
+    proc.on(sig, h);
+  }
+  const onUncaught = (_err) => fire("uncaughtException");
+  const onUnhandled = (_err) => fire("unhandledRejection");
+  proc.on("uncaughtException", onUncaught);
+  proc.on("unhandledRejection", onUnhandled);
+  const stdinEnd = () => fire("stdin-eof");
+  if (opts.watchStdin) {
+    stdin.resume();
+    stdin.on("end", stdinEnd);
+    stdin.on("close", stdinEnd);
+  }
+  return {
+    uninstall: () => {
+      for (const [sig, h] of signalHandlers) proc.off(sig, h);
+      proc.off("uncaughtException", onUncaught);
+      proc.off("unhandledRejection", onUnhandled);
+      if (opts.watchStdin) {
+        stdin.off("end", stdinEnd);
+        stdin.off("close", stdinEnd);
+      }
+    }
+  };
+}
+
+// src/commands/login.ts
+async function runLogin(opts) {
+  const runLoginImpl = opts.runLoginImpl ?? runLoginCommand;
+  const installLifecycleImpl = opts.installLifecycleImpl ?? installLifecycle;
+  const ac = new AbortController();
+  const lifecycle = installLifecycleImpl({
+    watchStdin: true,
+    onShutdown: () => {
+      ac.abort();
+    }
+  });
+  try {
+    return await runLoginImpl({
+      providerId: opts.providerId,
+      json: opts.json,
+      signal: ac.signal
+    });
+  } finally {
+    lifecycle.uninstall();
+  }
+}
+
+// src/commands/logout.ts
+import { stat as fsStat2, unlink } from "fs/promises";
+async function runLogout(opts) {
+  const write = opts.write ?? ((s) => void process.stdout.write(s));
+  const statFn = opts._statForTest ?? fsStat2;
+  const path2 = credentialsPath(opts.homeDir);
+  try {
+    if (process.platform !== "win32" && typeof process.getuid === "function") {
+      const s = await statFn(path2);
+      const uid = process.getuid();
+      if (s.uid !== uid) {
+        return fail(
+          write,
+          opts.json,
+          "credentials_foreign_owner",
+          `${path2} is owned by another user (uid ${s.uid}); refusing to delete`
+        );
+      }
+    }
+    await unlink(path2);
+    if (opts.json) {
+      write(`${JSON.stringify({ ok: true, deleted: path2 })}
+`);
+    } else {
+      write("Logged out\n");
+    }
+    return 0;
+  } catch (err) {
+    const e = err;
+    if (e.code === "ENOENT") {
+      if (opts.json) {
+        write(`${JSON.stringify({ ok: true, alreadyLoggedOut: true })}
+`);
+      } else {
+        write("Already logged out\n");
+      }
+      return 0;
+    }
+    return fail(write, opts.json, "logout_failed", e.message);
+  }
+}
+function fail(write, json, code, message) {
+  if (json) {
+    const envelope = { error: { code, message } };
+    write(`${JSON.stringify(envelope)}
+`);
+  } else {
+    write(`Error: ${message}
+`);
+  }
+  return 1;
+}
+
+// src/cloud/client.ts
+init_dist();
+import { readFile, stat } from "fs/promises";
+import { homedir as homedir2 } from "os";
+import path from "path";
+var DEFAULT_BASE_URL = "http://localhost:3001";
+var REQUEST_TIMEOUT_MS = 3e4;
+var MAX_RETRIES = 3;
+var BASE_BACKOFF_MS = 500;
+var JITTER_FRACTION = 0.25;
+var isRetryableStatus = (status) => status === 429 || status >= 500 && status <= 599;
+var computeBackoffMs = (attempt) => {
+  const exp = BASE_BACKOFF_MS * 2 ** attempt;
+  const jitter = exp * JITTER_FRACTION * (Math.random() * 2 - 1);
+  return Math.max(0, Math.round(exp + jitter));
+};
+var sleep = (ms) => new Promise((resolve5) => setTimeout(resolve5, ms));
+function parseRetryAfterMs(header) {
+  if (!header) return null;
+  const trimmed = header.trim();
+  if (/^\d+$/.test(trimmed)) {
+    return Number(trimmed) * 1e3;
+  }
+  const ts2 = Date.parse(trimmed);
+  if (Number.isNaN(ts2)) return null;
+  return Math.max(0, ts2 - Date.now());
+}
+var notLoggedIn = (message) => ({
+  kind: "error",
+  status: 0,
+  envelope: { error: { code: "not_logged_in", message } }
+});
+var unexpectedResponse = (status, statusText) => ({
+  kind: "error",
+  status,
+  envelope: {
+    error: {
+      code: "unexpected_response",
+      message: statusText || `HTTP ${status}`
+    }
+  }
+});
+var invalidResponse = (status) => ({
+  kind: "error",
+  status,
+  envelope: {
+    error: {
+      code: "invalid_response",
+      message: "Server returned a body that did not match the expected schema"
+    }
+  }
+});
+var resolveCredentialsPath = (override) => override ?? path.join(homedir2(), FILESYSTEM_LAYOUT.user.credentialsFile);
+var resolveBaseUrl = (override) => override ?? process.env.MACROSCOPE_CLOUD_URL ?? DEFAULT_BASE_URL;
+async function readAccessToken(credPath) {
+  let raw;
+  try {
+    raw = await readFile(credPath, "utf8");
+  } catch {
+    return null;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  const result = OAuthCredentialsSchema.safeParse(parsed);
+  if (!result.success) return null;
+  return result.data.accessToken;
+}
+async function parseErrorBody(res) {
+  let body;
+  try {
+    body = await res.json();
+  } catch {
+    return unexpectedResponse(res.status, res.statusText);
+  }
+  const envelope = ErrorEnvelopeSchema.safeParse(body);
+  if (!envelope.success) {
+    return unexpectedResponse(res.status, res.statusText);
+  }
+  return { kind: "error", status: res.status, envelope: envelope.data };
+}
+function clientValidationError(issue, fallbackMessage) {
+  return {
+    kind: "error",
+    status: 0,
+    envelope: {
+      error: {
+        code: "validation_failed",
+        message: issue?.message ?? fallbackMessage,
+        field: issue?.path.join(".") || void 0
+      }
+    }
+  };
+}
+function serializeRequest(method, data) {
+  if (data === null) return {};
+  if (method === "GET") {
+    const params = new URLSearchParams();
+    for (const [k, v] of Object.entries(data)) {
+      if (v === void 0) continue;
+      params.append(k, String(v));
+    }
+    const qs = params.toString();
+    return qs ? { query: `?${qs}` } : {};
+  }
+  return { body: JSON.stringify(data) };
+}
+async function parseOkBody(res, schema) {
+  let body;
+  try {
+    body = await res.json();
+  } catch {
+    return invalidResponse(res.status);
+  }
+  const parsed = schema.safeParse(body);
+  if (!parsed.success) {
+    return invalidResponse(res.status);
+  }
+  return { kind: "ok", data: parsed.data };
+}
+function createCloudClient(opts = {}) {
+  const credPath = resolveCredentialsPath(opts.credentialsPath);
+  const baseUrl = resolveBaseUrl(opts.baseUrl);
+  const fetchImpl = opts.fetchImpl ?? globalThis.fetch;
+  let cached = null;
+  async function getAccessToken() {
+    let mtimeMs;
+    try {
+      mtimeMs = (await stat(credPath)).mtimeMs;
+    } catch {
+      cached = null;
+      return null;
+    }
+    if (cached && cached.mtimeMs === mtimeMs) {
+      return cached.token;
+    }
+    const token = await readAccessToken(credPath);
+    cached = token ? { mtimeMs, token } : null;
+    return token;
+  }
+  async function executeRequest(endpoint, schema, init) {
+    const token = await getAccessToken();
+    if (!token) {
+      return notLoggedIn(`No valid credentials at ${credPath}. Run \`macroscope login\`.`);
+    }
+    const url = `${baseUrl}${endpoint.path}${init.query ?? ""}`;
+    const headers = {
+      Authorization: `Bearer ${token}`
+    };
+    if (init.body !== void 0) {
+      headers["Content-Type"] = "application/json";
+    }
+    let lastResponse = null;
+    let lastNetworkError = null;
+    for (let attempt = 0; attempt <= MAX_RETRIES; attempt += 1) {
+      let res;
+      try {
+        res = await fetchImpl(url, {
+          method: endpoint.method,
+          headers,
+          body: init.body,
+          signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS)
+        });
+      } catch (err) {
+        lastNetworkError = err;
+        if (attempt === MAX_RETRIES) break;
+        await sleep(computeBackoffMs(attempt));
+        continue;
+      }
+      if (!isRetryableStatus(res.status)) {
+        if (res.status >= 200 && res.status < 300) {
+          return parseOkBody(res, schema);
+        }
+        return parseErrorBody(res);
+      }
+      lastResponse = res;
+      lastNetworkError = null;
+      if (attempt === MAX_RETRIES) break;
+      const retryAfterMs = res.status === 429 ? parseRetryAfterMs(res.headers.get("retry-after")) : null;
+      const waitMs = retryAfterMs ?? computeBackoffMs(attempt);
+      await sleep(waitMs);
+    }
+    if (lastResponse) {
+      return parseErrorBody(lastResponse);
+    }
+    return {
+      kind: "error",
+      status: 0,
+      envelope: {
+        error: {
+          code: "upstream_unreachable",
+          message: lastNetworkError instanceof Error ? lastNetworkError.message : "Network request failed"
+        }
+      }
+    };
+  }
+  return {
+    health: () => executeRequest(API_ENDPOINTS.health, HealthResponseSchema, serializeRequest("GET", null)),
+    search: (req) => {
+      const parsed = SearchRequestSchema.safeParse(req);
+      if (!parsed.success) {
+        return Promise.resolve(
+          clientValidationError(
+            parsed.error.issues[0],
+            "Invalid search request"
+          )
+        );
+      }
+      return executeRequest(
+        API_ENDPOINTS.search,
+        SearchResponseSchema,
+        serializeRequest("GET", parsed.data)
+      );
+    },
+    indexBatch: (req) => {
+      const parsed = IndexBatchRequestSchema.safeParse(req);
+      if (!parsed.success) {
+        return Promise.resolve(
+          clientValidationError(
+            parsed.error.issues[0],
+            "Invalid index batch request"
+          )
+        );
+      }
+      return executeRequest(
+        API_ENDPOINTS.indexBatch,
+        IndexBatchResponseSchema,
+        serializeRequest("POST", parsed.data)
+      );
+    },
+    scopeTouch: (req) => {
+      const parsed = ScopeTouchRequestSchema.safeParse(req);
+      if (!parsed.success) {
+        return Promise.resolve(
+          clientValidationError(
+            parsed.error.issues[0],
+            "Invalid scope touch request"
+          )
+        );
+      }
+      return executeRequest(
+        API_ENDPOINTS.scopeTouch,
+        ScopeTouchResponseSchema,
+        serializeRequest("POST", parsed.data)
+      );
+    },
+    deleteIndex: () => executeRequest(
+      API_ENDPOINTS.deleteIndex,
+      DeleteIndexResponseSchema,
+      serializeRequest("DELETE", null)
+    )
+  };
+}
+
+// src/commands/search.ts
+init_project();
+
+// src/local/code-search.ts
+init_dist();
+import { execFile as execFileCb } from "child_process";
+import { promisify } from "util";
+var execFile = promisify(execFileCb);
+var DEFAULT_LIMIT = 100;
+var MAX_STDOUT_BYTES = 32 * 1024 * 1024;
+async function codeSearch(input) {
+  const limit = input.limit ?? DEFAULT_LIMIT;
+  const args = [
+    "grep",
+    "--no-color",
+    "--line-number",
+    "--column",
+    "--null",
+    "--ignore-case",
+    "--",
+    input.query
+  ];
+  let stdout;
+  try {
+    const result = await execFile("git", args, {
+      cwd: input.cwd,
+      maxBuffer: MAX_STDOUT_BYTES,
+      encoding: "utf8"
+    });
+    stdout = result.stdout;
+  } catch (err) {
+    const e = err;
+    if (e.code === "ENOENT") {
+      return errorEnvelope("git_unavailable", "git executable not found on PATH");
+    }
+    const stderr = e.stderr ?? "";
+    const exitCode = typeof e.code === "number" ? e.code : Number.NaN;
+    if (/not a git repository/i.test(stderr)) {
+      return errorEnvelope("not_a_git_repo", `${input.cwd} is not a git repository`);
+    }
+    if (exitCode === 1) {
+      return { kind: "ok", matches: [] };
+    }
+    const firstLine = stderr.split("\n", 1)[0]?.trim() || "git grep failed";
+    return errorEnvelope("git_grep_failed", firstLine);
+  }
+  return { kind: "ok", matches: parseGrepOutput(stdout, limit) };
+}
+function parseGrepOutput(stdout, limit) {
+  const matches = [];
+  if (!stdout) return matches;
+  const records = stdout.split("\n");
+  for (const record of records) {
+    if (matches.length >= limit) break;
+    if (!record) continue;
+    const fields = record.split("\0");
+    if (fields.length < 4) continue;
+    const [file, lineStr, colStr, ...rest] = fields;
+    const preview = rest.join("\0");
+    const line = Number.parseInt(lineStr, 10);
+    const column = Number.parseInt(colStr, 10);
+    if (!Number.isFinite(line) || line <= 0) continue;
+    const candidate = {
+      file,
+      line,
+      column: Number.isFinite(column) && column > 0 ? column : void 0,
+      preview
+    };
+    const parsed = CodeMatchSchema.safeParse(candidate);
+    if (!parsed.success) continue;
+    matches.push(parsed.data);
+  }
+  return matches;
+}
+function errorEnvelope(code, message) {
+  return { kind: "error", envelope: { error: { code, message } } };
+}
+
+// src/commands/search.ts
+var DEFAULT_LIMIT_PER_SIDE = 10;
+async function runSearch(opts) {
+  const write = opts.write ?? ((s) => void process.stdout.write(s));
+  const codeSearchFn = opts.codeSearchImpl ?? codeSearch;
+  const limit = opts.scope.limit ?? DEFAULT_LIMIT_PER_SIDE;
+  const credPath = credentialsPath(opts.homeDir);
+  const client = opts.client ?? createCloudClient({ credentialsPath: credPath });
+  const notes = [];
+  let projectRoot = null;
+  try {
+    const p = await findProject(opts.cwd ?? process.cwd());
+    projectRoot = p.root;
+  } catch (err) {
+    if (err instanceof ProjectNotFoundError) {
+      notes.push("local search unavailable: not in a macroscope project");
+    } else {
+      notes.push(`local search unavailable: ${err.message}`);
+    }
+  }
+  const searchReq = { q: opts.query, limit };
+  if (opts.scope.worktree) searchReq.worktreeId = opts.scope.worktree;
+  if (opts.scope.repo) searchReq.repo = opts.scope.repo;
+  if (opts.scope.kind) searchReq.kind = opts.scope.kind;
+  const [cloudRes, codeRes] = await Promise.allSettled([
+    client.search(searchReq),
+    projectRoot === null ? Promise.resolve({
+      kind: "error",
+      envelope: { error: { code: "not_a_git_repo", message: "no project" } }
+    }) : codeSearchFn({ query: opts.query, cwd: projectRoot, limit })
+  ]);
+  let blocks = [];
+  if (cloudRes.status === "fulfilled") {
+    const r = cloudRes.value;
+    if (r.kind === "ok") {
+      blocks = r.data.hits;
+    } else if (r.envelope.error.code === "not_logged_in") {
+      notes.push("cloud search unavailable: run `macroscope login` to enable catalogue search");
+    } else {
+      notes.push(`cloud unreachable: ${r.envelope.error.message}`);
+    }
+  } else {
+    notes.push(`cloud unreachable: ${cloudRes.reason.message}`);
+  }
+  let codeMatches = [];
+  if (codeRes.status === "fulfilled" && codeRes.value.kind === "ok") {
+    codeMatches = codeRes.value.matches;
+  } else if (codeRes.status === "fulfilled" && codeRes.value.kind === "error") {
+    if (projectRoot !== null) {
+      notes.push(`local search failed: ${codeRes.value.envelope.error.message}`);
+    }
+  } else if (codeRes.status === "rejected") {
+    notes.push(`local search failed: ${codeRes.reason.message}`);
+  }
+  const cloudFailed = cloudRes.status !== "fulfilled" || cloudRes.value.kind !== "ok";
+  if (projectRoot === null && cloudFailed) {
+    return fail2(write, opts.json, "search_unavailable", notes.join("; ") || "no project, no creds");
+  }
+  const result = { blocks, code: codeMatches, notes };
+  if (opts.json) {
+    write(`${JSON.stringify(result)}
+`);
+  } else {
+    writeHuman(write, result);
+  }
+  return 0;
+}
+function fail2(write, json, code, message) {
+  if (json) {
+    const env = { error: { code, message } };
+    write(`${JSON.stringify(env)}
+`);
+  } else {
+    write(`Error: ${message}
+`);
+  }
+  return 2;
+}
+function writeHuman(write, r) {
+  write(`Cloud catalogue (${r.blocks.length} hits):
+`);
+  if (r.blocks.length === 0) {
+    write("  (no results)\n");
+  } else {
+    for (const b of r.blocks) {
+      const name = b.name ?? b.blockId;
+      write(`  ${name.padEnd(28)} ${b.kind.padEnd(20)} ${b.path}
+`);
+    }
+  }
+  write(`
+Code matches (${r.code.length}):
+`);
+  if (r.code.length === 0) {
+    write("  (no results)\n");
+  } else {
+    for (const m of r.code) {
+      const loc = m.column ? `${m.file}:${m.line}:${m.column}` : `${m.file}:${m.line}`;
+      write(`  ${loc}  ${m.preview.trim()}
+`);
+    }
+  }
+  for (const note of r.notes) {
+    write(`
+(${note})
+`);
+  }
+}
+
+// src/commands/status.ts
+init_dist();
+import { readFile as readFile3 } from "fs/promises";
+init_project();
+var DEFAULT_HEALTH_TIMEOUT_MS = 3e3;
+async function runStatus(opts) {
+  const write = opts.write ?? ((s) => void process.stdout.write(s));
+  const healthTimeoutMs = opts.healthTimeoutMs ?? DEFAULT_HEALTH_TIMEOUT_MS;
+  const worktree = await resolveWorktree(opts.cwd);
+  const credPath = credentialsPath(opts.homeDir);
+  const client = opts.client ?? createCloudClient({ credentialsPath: credPath });
+  const cloud = await probeCloud(client, healthTimeoutMs);
+  const login2 = await readLogin(credPath);
+  const report = {
+    worktree,
+    cloud,
+    login: login2,
+    lastIndexTime: null,
+    watcher: "not_running"
+  };
+  if (opts.json) {
+    write(`${JSON.stringify(report)}
+`);
+  } else {
+    writeHuman2(write, report);
+  }
+  return 0;
+}
+async function resolveWorktree(cwd) {
+  try {
+    const project = await findProject(cwd ?? process.cwd());
+    return project.root;
+  } catch (err) {
+    if (err instanceof ProjectNotFoundError) return null;
+    return null;
+  }
+}
+async function probeCloud(client, timeoutMs) {
+  const result = await Promise.race([
+    client.health().catch(() => null),
+    new Promise((resolve5) => setTimeout(() => resolve5(null), timeoutMs))
+  ]);
+  if (result === null) return "unreachable";
+  if (result.kind === "ok") return "reachable";
+  if (result.envelope.error.code === "not_logged_in") return "not_logged_in";
+  return "unreachable";
+}
+async function readLogin(credPath) {
+  let raw;
+  try {
+    raw = await readFile3(credPath, "utf8");
+  } catch {
+    return null;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  const result = OAuthCredentialsSchema.safeParse(parsed);
+  if (!result.success) return null;
+  return { provider: result.data.provider, providerUserId: result.data.providerUserId };
+}
+function writeHuman2(write, r) {
+  const worktree = r.worktree ?? "(not in a macroscope project)";
+  const login2 = r.login ? `${r.login.provider}${r.login.providerUserId ? ` (${r.login.providerUserId})` : ""}` : "not logged in";
+  const lastIndexed = r.lastIndexTime === null ? "never" : new Date(r.lastIndexTime).toISOString();
+  write(`worktree:     ${worktree}
+`);
+  write(`cloud:        ${r.cloud}
+`);
+  write(`login:        ${login2}
+`);
+  write(`last indexed: ${lastIndexed}
+`);
+  write(`watcher:      ${r.watcher}
+`);
+}
+
+// src/cli.ts
+init_blueprints();
+init_project();
+
+// src/core/version.ts
+var VERSION = "0.0.0";
+
+// src/ui/ui-server.ts
+init_dist();
+import { existsSync as existsSync4 } from "fs";
+import { readFile as readFile13 } from "fs/promises";
+import { createServer as createServer2 } from "http";
+import { homedir as homedir4 } from "os";
+import { extname as extname2, join as join9, normalize, resolve as resolve3 } from "path";
+
+// src/local/catchup.ts
+init_dist();
+import { mkdir as mkdir5, readFile as readFile9, rename as rename3, writeFile as writeFile5 } from "fs/promises";
+import { dirname as dirname7, join as join8, relative as relative3, sep as sep3 } from "path";
+
+// src/core/extractor.ts
+import { readFile as readFile4 } from "fs/promises";
+import ts from "typescript";
+var DEFAULT_README_EXCERPT_MAX = 500;
+var TS_EXTENSIONS = /* @__PURE__ */ new Set([".ts", ".tsx", ".mts", ".cts"]);
+var DEFAULT_COMPILER_OPTIONS = {
+  target: ts.ScriptTarget.ES2022,
+  module: ts.ModuleKind.ESNext,
+  moduleResolution: ts.ModuleResolutionKind.Bundler,
+  jsx: ts.JsxEmit.ReactJSX,
+  allowJs: false,
+  noEmit: true,
+  skipLibCheck: true,
+  esModuleInterop: true,
+  allowSyntheticDefaultImports: true,
+  strict: false,
+  isolatedModules: true
+};
+function defaultProgramFactory(rootFiles) {
+  return ts.createProgram(rootFiles, DEFAULT_COMPILER_OPTIONS);
+}
+async function extractAll(blocks, opts = {}) {
+  const readmeMax = opts.readmeExcerptMax ?? DEFAULT_README_EXCERPT_MAX;
+  const payloads = [];
+  const errors = [];
+  const sourcesToBlocks = /* @__PURE__ */ new Map();
+  for (const block of blocks) {
+    if (!block.manifest?.kind) continue;
+    const src = block.resolvedPaths?.source;
+    if (src && isTsSource(src)) {
+      sourcesToBlocks.set(src, block);
+    }
+  }
+  let program;
+  let checker;
+  if (sourcesToBlocks.size > 0) {
+    const rootFiles = Array.from(sourcesToBlocks.keys());
+    const factory = opts.programFactory ?? defaultProgramFactory;
+    program = factory(rootFiles);
+    checker = program.getTypeChecker();
+  }
+  for (const block of blocks) {
+    if (!block.manifest?.kind) continue;
+    const payload = {
+      blockId: block.id,
+      kind: block.manifest.kind,
+      symbols: []
+    };
+    const { name, description, tags } = block.manifest;
+    if (typeof name === "string") payload.name = name;
+    if (typeof description === "string") payload.description = description;
+    if (Array.isArray(tags)) payload.tags = tags;
+    const sourcePath = block.resolvedPaths?.source;
+    if (sourcePath && isTsSource(sourcePath) && program && checker) {
+      const sourceFile = program.getSourceFile(sourcePath);
+      if (!sourceFile) {
+        errors.push({
+          blockId: block.id,
+          kind: "parse",
+          message: `TS Program did not load ${sourcePath} (parse error or missing file)`
+        });
+      } else if (hasFatalSyntaxErrors(program, sourceFile)) {
+        errors.push({
+          blockId: block.id,
+          kind: "parse",
+          message: `Source file ${sourcePath} has syntax errors; skipping symbol extraction`
+        });
+      } else {
+        payload.symbols = extractSymbols(sourceFile, checker);
+      }
+    }
+    const docsPath = block.resolvedPaths?.docs;
+    if (docsPath) {
+      try {
+        const raw = await readFile4(docsPath, "utf8");
+        payload.readmeExcerpt = formatReadmeExcerpt(raw, readmeMax);
+      } catch (err) {
+        errors.push({
+          blockId: block.id,
+          kind: "io",
+          message: `Failed to read docs at ${docsPath}: ${err.message}`
+        });
+      }
+    }
+    payloads.push(payload);
+  }
+  return { payloads, errors };
+}
+function isTsSource(path2) {
+  const dot = path2.lastIndexOf(".");
+  if (dot < 0) return false;
+  return TS_EXTENSIONS.has(path2.slice(dot).toLowerCase());
+}
+function hasFatalSyntaxErrors(program, sourceFile) {
+  const diagnostics = program.getSyntacticDiagnostics(sourceFile);
+  return diagnostics.length > 0;
+}
+function extractSymbols(sourceFile, checker) {
+  const symbols = [];
+  for (const statement of sourceFile.statements) {
+    visitTopLevel(statement, sourceFile, checker, symbols);
+  }
+  const seen = /* @__PURE__ */ new Set();
+  return symbols.filter((s) => {
+    const key = `${s.kind}\0${s.name}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+function visitTopLevel(node, sourceFile, checker, out) {
+  if (ts.isExportAssignment(node)) {
+    out.push(extractDefaultExport(node, sourceFile, checker));
+    return;
+  }
+  if (ts.isExportDeclaration(node)) {
+    extractExportDeclaration(node, sourceFile, checker, out);
+    return;
+  }
+  if (!hasExportModifier(node)) return;
+  const isDefault = hasDefaultModifier(node);
+  if (ts.isFunctionDeclaration(node)) {
+    const name = node.name?.text ?? (isDefault ? "default" : void 0);
+    if (!name) return;
+    out.push({
+      name,
+      kind: "function",
+      signature: renderFunctionSignature(node, name, sourceFile, checker)
+    });
+    return;
+  }
+  if (ts.isClassDeclaration(node)) {
+    const name = node.name?.text ?? (isDefault ? "default" : void 0);
+    if (!name) return;
+    out.push({ name, kind: "class", signature: `class ${name}` });
+    return;
+  }
+  if (ts.isInterfaceDeclaration(node)) {
+    out.push({
+      name: node.name.text,
+      kind: "interface",
+      signature: oneLineDeclaration(node, sourceFile, `interface ${node.name.text}`)
+    });
+    return;
+  }
+  if (ts.isTypeAliasDeclaration(node)) {
+    out.push({
+      name: node.name.text,
+      kind: "type",
+      signature: oneLineDeclaration(node, sourceFile, `type ${node.name.text}`)
+    });
+    return;
+  }
+  if (ts.isEnumDeclaration(node)) {
+    out.push({ name: node.name.text, kind: "enum", signature: `enum ${node.name.text}` });
+    return;
+  }
+  if (ts.isVariableStatement(node)) {
+    for (const decl of node.declarationList.declarations) {
+      if (!ts.isIdentifier(decl.name)) continue;
+      const name = decl.name.text;
+      out.push({
+        name,
+        kind: "const",
+        signature: renderVariableSignature(decl, name, checker)
+      });
+    }
+    return;
+  }
+}
+function extractDefaultExport(node, sourceFile, checker) {
+  const expr = node.expression;
+  if (ts.isIdentifier(expr)) {
+    const sym = checker.getSymbolAtLocation(expr);
+    const type = sym ? checker.getTypeOfSymbolAtLocation(sym, expr) : void 0;
+    const signature = type ? checker.typeToString(type) : "default";
+    return { name: "default", kind: "const", signature };
+  }
+  return { name: "default", kind: "const", signature: expr.getText(sourceFile) };
+}
+function extractExportDeclaration(node, sourceFile, checker, out) {
+  if (!node.exportClause && node.moduleSpecifier) {
+    const moduleSymbol = checker.getSymbolAtLocation(node.moduleSpecifier);
+    if (moduleSymbol) {
+      for (const exp of checker.getExportsOfModule(moduleSymbol)) {
+        out.push(renderExportedSymbol(exp.name, exp, checker, sourceFile));
+      }
+    }
+    return;
+  }
+  if (node.exportClause && ts.isNamedExports(node.exportClause)) {
+    for (const spec of node.exportClause.elements) {
+      const name = spec.name.text;
+      const sym = checker.getSymbolAtLocation(spec.name);
+      out.push(renderExportedSymbol(name, sym, checker, sourceFile));
+    }
+  }
+}
+function renderExportedSymbol(name, symbol, checker, sourceFile) {
+  if (!symbol) return { name, kind: "const", signature: name };
+  const aliased = (symbol.flags & ts.SymbolFlags.Alias) !== 0 ? checker.getAliasedSymbol(symbol) : symbol;
+  const decl = aliased.declarations?.[0];
+  if (decl) {
+    if (ts.isFunctionDeclaration(decl) || ts.isMethodDeclaration(decl)) {
+      return {
+        name,
+        kind: "function",
+        signature: renderFunctionSignature(decl, name, sourceFile, checker)
+      };
+    }
+    if (ts.isClassDeclaration(decl)) return { name, kind: "class", signature: `class ${name}` };
+    if (ts.isInterfaceDeclaration(decl)) {
+      return {
+        name,
+        kind: "interface",
+        signature: oneLineDeclaration(decl, decl.getSourceFile(), `interface ${name}`)
+      };
+    }
+    if (ts.isTypeAliasDeclaration(decl)) {
+      return {
+        name,
+        kind: "type",
+        signature: oneLineDeclaration(decl, decl.getSourceFile(), `type ${name}`)
+      };
+    }
+    if (ts.isEnumDeclaration(decl)) return { name, kind: "enum", signature: `enum ${name}` };
+  }
+  const type = checker.getTypeOfSymbolAtLocation(aliased, sourceFile);
+  return { name, kind: "const", signature: checker.typeToString(type) };
+}
+function renderFunctionSignature(node, name, _sourceFile, checker) {
+  const signature = checker.getSignatureFromDeclaration(node);
+  if (!signature) return `function ${name}()`;
+  return `function ${name}${checker.signatureToString(signature)}`;
+}
+function renderVariableSignature(decl, name, checker) {
+  const type = checker.getTypeAtLocation(decl);
+  return `const ${name}: ${checker.typeToString(type)}`;
+}
+function oneLineDeclaration(node, sourceFile, fallback) {
+  try {
+    const text = node.getText(sourceFile);
+    const collapsed = text.replace(/\s+/g, " ").trim();
+    return collapsed.length > 0 ? collapsed : fallback;
+  } catch {
+    return fallback;
+  }
+}
+function hasExportModifier(node) {
+  return (ts.getCombinedModifierFlags(node) & ts.ModifierFlags.Export) !== 0;
+}
+function hasDefaultModifier(node) {
+  return (ts.getCombinedModifierFlags(node) & ts.ModifierFlags.Default) !== 0;
+}
+function formatReadmeExcerpt(raw, max) {
+  const stripped = raw.replace(/[#*`_~>]/g, "");
+  const collapsed = stripped.replace(/\s+/g, " ").trim();
+  if (collapsed.length <= max) return collapsed;
+  const slice = collapsed.slice(0, max);
+  const nextChar = collapsed.charAt(max);
+  if (nextChar === "" || /\s/.test(nextChar)) return slice;
+  const lastSpace = slice.lastIndexOf(" ");
+  if (lastSpace > 0) return slice.slice(0, lastSpace);
+  return slice;
+}
+
+// src/core/hasher.ts
+init_dist();
+import { createHash as createHash2 } from "crypto";
+import { mkdir as mkdir2, readFile as readFile5, rename, stat as stat2, writeFile as writeFile2 } from "fs/promises";
+import { dirname as dirname3, join as join4 } from "path";
+function canonicalJSON(value) {
+  return stringify(value);
+}
+function stringify(value) {
+  if (value === null) return "null";
+  if (typeof value === "string") return JSON.stringify(value.normalize("NFC"));
+  if (typeof value === "number" || typeof value === "boolean") return JSON.stringify(value);
+  if (Array.isArray(value)) {
+    const parts = value.map((v) => v === void 0 ? "null" : stringify(v));
+    return `[${parts.join(",")}]`;
+  }
+  if (typeof value === "object") {
+    const obj = value;
+    const keys = Object.keys(obj).filter((k) => obj[k] !== void 0).sort();
+    const parts = keys.map((k) => `${JSON.stringify(k)}:${stringify(obj[k])}`);
+    return `{${parts.join(",")}}`;
+  }
+  throw new TypeError(`canonicalJSON: unsupported value type ${typeof value}`);
+}
+function hashPayload(payload) {
+  const canonical = canonicalJSON(payload);
+  return createHash2("sha256").update(canonical, "utf8").digest("hex");
+}
+function resolveHashesPath(opts) {
+  const root = opts?.workspaceRoot ?? process.cwd();
+  return join4(root, FILESYSTEM_LAYOUT.project.hashesFile);
+}
+async function readCacheFile(opts) {
+  const path2 = resolveHashesPath(opts);
+  let raw;
+  try {
+    raw = await readFile5(path2, "utf8");
+  } catch (err) {
+    const code = err.code;
+    if (code !== "ENOENT") {
+      console.warn(`[macroscope] failed to read hash cache at ${path2}: ${err.message}`);
+    }
+    return null;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    console.warn(`[macroscope] hash cache at ${path2} is not valid JSON: ${err.message}`);
+    return null;
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    console.warn(`[macroscope] hash cache at ${path2} has unexpected shape; ignoring`);
+    return null;
+  }
+  const obj = parsed;
+  if (typeof obj.schemaVersion === "number" && obj.entries && typeof obj.entries === "object" && !Array.isArray(obj.entries)) {
+    return { schemaVersion: obj.schemaVersion, entries: obj.entries };
+  }
+  return { schemaVersion: void 0, entries: obj };
+}
+async function loadHashCache(opts) {
+  const file = await readCacheFile(opts);
+  return file?.entries ?? {};
+}
+async function readSchemaVersion(opts) {
+  const file = await readCacheFile(opts);
+  return file?.schemaVersion;
+}
+async function saveHashCache(cache, opts) {
+  const path2 = resolveHashesPath(opts);
+  const dir = dirname3(path2);
+  await mkdir2(dir, { recursive: true });
+  const tmp = `${path2}.tmp`;
+  const envelope = {
+    schemaVersion: opts?.schemaVersion ?? SCHEMA_VERSION,
+    entries: cache
+  };
+  const body = `${JSON.stringify(envelope, null, 2)}
+`;
+  await writeFile2(tmp, body, "utf8");
+  await rename(tmp, path2);
+}
+async function filterChangedBlocks(blocks, cache) {
+  const changed = [];
+  for (const block of blocks) {
+    const cached = cache[block.id];
+    if (!cached) {
+      changed.push(block);
+      continue;
+    }
+    const maxMtime = await maxFileMtime(block);
+    if (maxMtime === void 0 || maxMtime > cached.mtime) {
+      changed.push(block);
+    }
+  }
+  return changed;
+}
+async function maxFileMtime(block) {
+  const paths = [join4(block.path, "macroscope.yaml")];
+  if (block.resolvedPaths?.source) paths.push(block.resolvedPaths.source);
+  if (block.resolvedPaths?.docs) paths.push(block.resolvedPaths.docs);
+  let max;
+  for (const p of paths) {
+    try {
+      const s = await stat2(p);
+      const m = s.mtimeMs;
+      if (max === void 0 || m > max) max = m;
+    } catch {
+      return void 0;
+    }
+  }
+  return max;
+}
+
+// src/local/catchup.ts
+init_project();
+init_scanner();
+
+// src/local/repo-id.ts
+import { execFile as execFileCb2 } from "child_process";
+import { basename } from "path";
+import { promisify as promisify2 } from "util";
+var execFile2 = promisify2(execFileCb2);
+var NotAGitRepoError = class extends Error {
+  constructor(path2) {
+    super(
+      `Not a git repository: ${path2}. The watcher needs a git working tree to derive a repo identity.`
+    );
+    this.name = "NotAGitRepoError";
+  }
+};
+function normalizeRemoteUrl(url) {
+  let s = url.trim();
+  s = s.toLowerCase();
+  s = s.replace(/^ssh:\/\//, "");
+  s = s.replace(/^https?:\/\//, "");
+  s = s.replace(/^git:\/\//, "");
+  s = s.replace(/^[a-z0-9._-]+@/, "");
+  s = s.replace(":", "/");
+  s = s.replace(/\.git$/, "");
+  s = s.replace(/\/+$/, "");
+  return s;
+}
+async function deriveRepoId(absolutePath) {
+  try {
+    await execFile2("git", ["-C", absolutePath, "rev-parse", "--git-dir"]);
+  } catch {
+    throw new NotAGitRepoError(absolutePath);
+  }
+  try {
+    const { stdout } = await execFile2("git", [
+      "-C",
+      absolutePath,
+      "config",
+      "--get",
+      "remote.origin.url"
+    ]);
+    const url = stdout.trim();
+    if (url) return normalizeRemoteUrl(url);
+  } catch {
+  }
+  return basename(absolutePath);
+}
+
+// src/local/watcher.ts
+init_dist();
+import { createHash as createHash5 } from "crypto";
+import { EventEmitter } from "events";
+import { mkdir as mkdir4, readFile as readFile8, rename as rename2, writeFile as writeFile4 } from "fs/promises";
+import { dirname as dirname6, join as join7, relative as relative2, sep as sep2 } from "path";
+import chokidar from "chokidar";
+init_project();
+init_scanner();
+
+// src/local/worktree-id.ts
+init_dist();
+import { createHash as createHash4, randomUUID } from "crypto";
+import { mkdir as mkdir3, readFile as readFile7, writeFile as writeFile3 } from "fs/promises";
+import { homedir as homedir3 } from "os";
+import { dirname as dirname5, join as join6 } from "path";
+function deriveWorktreeId(machineUuid, absolutePath) {
+  return createHash4("sha256").update(`${machineUuid}:${absolutePath}`).digest("hex").slice(0, 32);
+}
+async function getOrCreateMachineUuid(opts) {
+  const home = opts?.homeDir ?? homedir3();
+  const path2 = join6(home, FILESYSTEM_LAYOUT.user.machineIdFile);
+  try {
+    const raw = await readFile7(path2, "utf8");
+    const trimmed = raw.trim();
+    if (trimmed) return trimmed;
+  } catch (err) {
+    const code = err.code;
+    if (code !== "ENOENT") throw err;
+  }
+  const uuid = randomUUID();
+  await mkdir3(dirname5(path2), { recursive: true });
+  await writeFile3(path2, `${uuid}
+`, { encoding: "utf8", mode: 384 });
+  return uuid;
+}
+
+// src/local/watcher.ts
+var composeDocId = (repo, worktreeId, blockId) => createHash5("sha256").update(`${repo}:${worktreeId}:${blockId}`).digest("hex");
+var QUEUE_MAX_BYTES = 1048576;
+var STOP_DRAIN_TIMEOUT_MS = 3e4;
+var READY_TIMEOUT_MS = 1e4;
+var isRetryable = (r) => {
+  if (r.kind !== "error") return false;
+  if (r.status >= 500 && r.status <= 599) return true;
+  if (r.status === 0 && r.envelope.error.code === "not_logged_in") return false;
+  if (r.envelope.error.code === "upstream_unreachable") return true;
+  return false;
+};
+var toPosix2 = (p) => p.split(sep2).join("/");
+async function startWatcher(opts) {
+  const debounceMs = opts.debounceMs ?? 500;
+  const queueRetryMs = opts.queueRetryMs ?? 5e3;
+  const project = await findProject(opts.projectRoot);
+  const machineUuid = await getOrCreateMachineUuid({ homeDir: opts.homeDir });
+  const worktreeId = deriveWorktreeId(machineUuid, project.root);
+  const repo = await deriveRepoId(project.root);
+  const queuePath = join7(project.root, FILESYSTEM_LAYOUT.project.queueFile);
+  const emitter = new EventEmitter();
+  let stopping = false;
+  let stopped = false;
+  let flushTimer = null;
+  let inFlight = null;
+  let retryTimer = null;
+  async function readQueue2() {
+    try {
+      const raw = await readFile8(queuePath, "utf8");
+      const parsed = JSON.parse(raw);
+      if (Array.isArray(parsed)) return parsed;
+      return [];
+    } catch (err) {
+      if (err.code === "ENOENT") return [];
+      return [];
+    }
+  }
+  async function writeQueue(q) {
+    await mkdir4(dirname6(queuePath), { recursive: true });
+    const tmp = `${queuePath}.tmp`;
+    let body = JSON.stringify(q);
+    while (Buffer.byteLength(body, "utf8") > QUEUE_MAX_BYTES && q.length > 0) {
+      q.shift();
+      body = JSON.stringify(q);
+      console.warn(
+        `[macroscope] watcher queue exceeded ${QUEUE_MAX_BYTES} bytes; dropping oldest entry`
+      );
+    }
+    await writeFile4(tmp, body, "utf8");
+    await rename2(tmp, queuePath);
+  }
+  async function enqueueBatch(batch) {
+    const q = await readQueue2();
+    q.push({ ...batch, queuedAt: Date.now() });
+    await writeQueue(q);
+  }
+  async function drainQueue() {
+    const q = await readQueue2();
+    if (q.length === 0) return { drained: 0 };
+    let drained = 0;
+    while (q.length > 0) {
+      const next = q[0];
+      const res = await opts.cloudClient.indexBatch({
+        upserts: next.upserts,
+        deletes: next.deletes
+      });
+      if (res.kind === "ok") {
+        q.shift();
+        drained += 1;
+        continue;
+      }
+      if (isRetryable(res)) break;
+      q.shift();
+      drained += 1;
+      emitter.emit("error", {
+        err: new Error(res.envelope.error.message),
+        retryable: false
+      });
+    }
+    await writeQueue(q);
+    if (drained > 0) emitter.emit("queueDrained", { drained });
+    return { drained };
+  }
+  async function flush() {
+    flushTimer = null;
+    if (stopping) return;
+    const start = Date.now();
+    const scanResult = await scan(project);
+    const cache = await loadHashCache({ workspaceRoot: project.root });
+    const changedBlocks = await filterChangedBlocks(scanResult.blocks, cache);
+    const { payloads } = await extractAll(changedBlocks);
+    const payloadById = new Map(payloads.map((p) => [p.blockId, p]));
+    const blockById = new Map(scanResult.blocks.map((b) => [b.id, b]));
+    const upserts = [];
+    const newCache = { ...cache };
+    const now = Date.now();
+    for (const block of changedBlocks) {
+      const payload = payloadById.get(block.id);
+      if (!payload) continue;
+      const contentHash = hashPayload(payload);
+      const doc = {
+        ...payload,
+        contentHash,
+        repo,
+        worktreeId,
+        path: toPosix2(relative2(project.root, block.path)),
+        lastActiveAt: now
+      };
+      upserts.push(doc);
+      newCache[block.id] = { hash: contentHash, mtime: now };
+    }
+    const currentIds = new Set(scanResult.blocks.map((b) => b.id));
+    const deletes = [];
+    for (const id of Object.keys(cache)) {
+      if (currentIds.has(id)) continue;
+      deletes.push(composeDocId(repo, worktreeId, id));
+      delete newCache[id];
+    }
+    if (upserts.length === 0 && deletes.length === 0) {
+      await drainQueue();
+      return;
+    }
+    emitter.emit("batchStart", {
+      pendingUpserts: upserts.length,
+      pendingDeletes: deletes.length
     });
-  });
-}
-async function handleConnection(ws, req, defaultCwd) {
-  const url = new URL(req.url ?? "/", "http://localhost");
-  const blockId = url.searchParams.get("blockId") ?? "";
-  const viewKey = url.searchParams.get("viewKey") ?? "";
-  let command;
-  let cwd;
-  if (spawnOverride) {
-    command = spawnOverride.command;
-    cwd = spawnOverride.cwd ?? defaultCwd;
-  } else {
-    const resolved = await resolveTerminalCommand(defaultCwd, blockId, viewKey);
-    if (!resolved.ok) {
-      send(ws, { type: "error", message: resolved.error });
-      ws.close();
+    const drainBefore = await readQueue2();
+    if (drainBefore.length > 0) {
+      await drainQueue();
+    }
+    const res = await opts.cloudClient.indexBatch({ upserts, deletes });
+    if (res.kind === "ok") {
+      await saveHashCache(newCache, { workspaceRoot: project.root });
+      emitter.emit("batchSent", {
+        accepted: res.data.accepted,
+        deleted: deletes.length,
+        durationMs: Date.now() - start
+      });
+      await drainQueue();
       return;
     }
-    command = resolved.command;
-    cwd = resolved.cwd;
+    if (isRetryable(res)) {
+      await enqueueBatch({ upserts, deletes });
+      ensureQueueRetry();
+      emitter.emit("error", {
+        err: new Error(res.envelope.error.message),
+        retryable: true
+      });
+      return;
+    }
+    emitter.emit("error", {
+      err: new Error(res.envelope.error.message),
+      retryable: false
+    });
   }
-  if (command.length === 0) {
-    send(ws, { type: "error", message: "empty command" });
-    ws.close();
-    return;
+  function scheduleFlush() {
+    if (stopping) return;
+    if (flushTimer) clearTimeout(flushTimer);
+    flushTimer = setTimeout(() => {
+      inFlight = flush().catch((err) => {
+        emitter.emit("error", {
+          err: err instanceof Error ? err : new Error(String(err)),
+          retryable: false
+        });
+      }).finally(() => {
+        inFlight = null;
+      });
+    }, debounceMs);
   }
-  send(ws, { type: "open", command });
-  const [bin, ...args] = command;
-  let child;
-  try {
-    child = spawn(bin, args, { cwd, stdio: ["pipe", "pipe", "pipe"] });
-  } catch (err) {
-    send(ws, { type: "error", message: `failed to spawn: ${err.message}` });
-    ws.close();
-    return;
+  function clearQueueRetry() {
+    if (retryTimer) {
+      clearInterval(retryTimer);
+      retryTimer = null;
+    }
   }
-  child.stdout?.on("data", (chunk) => send(ws, { type: "out", data: chunk.toString() }));
-  child.stderr?.on("data", (chunk) => send(ws, { type: "err", data: chunk.toString() }));
-  child.on("exit", (code, signal) => {
-    send(ws, { type: "close", code, signal });
-    ws.close();
+  function ensureQueueRetry() {
+    if (retryTimer || stopping) return;
+    retryTimer = setInterval(() => {
+      void (async () => {
+        if (stopping) {
+          clearQueueRetry();
+          return;
+        }
+        if ((await readQueue2()).length === 0) {
+          clearQueueRetry();
+          return;
+        }
+        scheduleFlush();
+      })();
+    }, queueRetryMs);
+    if (typeof retryTimer.unref === "function") retryTimer.unref();
+  }
+  const factory = opts.watcherFactory ?? ((paths) => chokidar.watch(paths, {
+    ignoreInitial: true,
+    awaitWriteFinish: { stabilityThreshold: 100, pollInterval: 50 },
+    ignored: (p) => /(^|[/\\])(node_modules|\.git|dist)([/\\]|$)/.test(p) || /([/\\])\.macroscope[/\\]cache([/\\]|$)/.test(p)
+  }));
+  const fsWatcher = factory([project.root]);
+  for (const event of ["add", "change", "unlink", "addDir", "unlinkDir"]) {
+    fsWatcher.on(event, () => scheduleFlush());
+  }
+  fsWatcher.on("error", (err) => {
+    emitter.emit("error", {
+      err: err instanceof Error ? err : new Error(String(err)),
+      retryable: false
+    });
   });
-  child.on("error", (err) => {
-    send(ws, { type: "error", message: err.message });
-    ws.close();
+  await new Promise((resolve5) => {
+    let settled = false;
+    const settle = () => {
+      if (settled) return;
+      settled = true;
+      resolve5();
+    };
+    fsWatcher.on("ready", settle);
+    const t = setTimeout(settle, READY_TIMEOUT_MS);
+    if (typeof t.unref === "function") t.unref();
   });
-  ws.on("message", (raw) => {
-    let frame;
+  await drainQueue().catch((err) => {
+    emitter.emit("error", {
+      err: err instanceof Error ? err : new Error(String(err)),
+      retryable: false
+    });
+  });
+  if ((await readQueue2()).length > 0) ensureQueueRetry();
+  async function stop() {
+    if (stopped) return;
+    stopping = true;
+    if (flushTimer) {
+      clearTimeout(flushTimer);
+      flushTimer = null;
+    }
+    clearQueueRetry();
     try {
-      frame = JSON.parse(raw.toString());
+      await fsWatcher.close();
     } catch {
-      return;
     }
-    if (frame.type === "in" && typeof frame.data === "string") {
-      child.stdin?.write(frame.data);
-    } else if (frame.type === "eof") {
-      child.stdin?.end();
+    if (inFlight) {
+      const timeout = new Promise((resolve5) => {
+        const t = setTimeout(() => {
+          console.warn(
+            `[macroscope] watcher stop: in-flight batch did not settle within ${STOP_DRAIN_TIMEOUT_MS}ms \u2014 giving up`
+          );
+          resolve5();
+        }, STOP_DRAIN_TIMEOUT_MS);
+        if (typeof t.unref === "function") t.unref();
+      });
+      await Promise.race([inFlight, timeout]);
     }
+    stopped = true;
+  }
+  const handle = {
+    stop,
+    on(event, cb) {
+      const wrapped = (payload) => cb(payload);
+      emitter.on(event, wrapped);
+      return () => emitter.off(event, wrapped);
+    }
+  };
+  if (opts.lifecycle !== false) {
+    installLifecycle({
+      ...opts.lifecycle ?? {},
+      onShutdown: () => handle.stop()
+    });
+  }
+  return handle;
+}
+
+// src/local/catchup.ts
+var CHUNK = 500;
+var EXTRACT_PROGRESS_INTERVAL_MS = 100;
+var toPosix3 = (p) => p.split(sep3).join("/");
+async function runCatchup(opts) {
+  const startTime = Date.now();
+  const onProgress = opts.onProgress ?? (() => {
   });
-  ws.on("close", () => {
-    if (!child.killed) child.kill();
-  });
+  const project = await findProject(opts.projectRoot);
+  const machineUuid = await getOrCreateMachineUuid({ homeDir: opts.homeDir });
+  const worktreeId = deriveWorktreeId(machineUuid, project.root);
+  const repo = await deriveRepoId(project.root);
+  const scanResult = await scan(project);
+  const blocks = scanResult.blocks;
+  onProgress({ kind: "start", total: blocks.length });
+  const cachedSchemaVersion = await readSchemaVersion({ workspaceRoot: project.root });
+  const schemaMismatch = cachedSchemaVersion !== SCHEMA_VERSION;
+  const cache = schemaMismatch ? {} : await loadHashCache({ workspaceRoot: project.root });
+  const changedBlocks = schemaMismatch ? blocks : await filterChangedBlocks(blocks, cache);
+  const { payloads } = await extractAll(changedBlocks);
+  const payloadById = new Map(payloads.map((p) => [p.blockId, p]));
+  const mtimeRefreshes = {};
+  const upserts = [];
+  const upsertCacheEntries = /* @__PURE__ */ new Map();
+  const now = Date.now();
+  let lastExtractEmit = 0;
+  let done = 0;
+  for (const block of changedBlocks) {
+    done += 1;
+    const payload = payloadById.get(block.id);
+    if (payload) {
+      const contentHash = hashPayload(payload);
+      const cached = cache[block.id];
+      if (cached && cached.hash === contentHash) {
+        mtimeRefreshes[block.id] = { hash: contentHash, mtime: now };
+      } else {
+        const doc = {
+          ...payload,
+          contentHash,
+          repo,
+          worktreeId,
+          path: toPosix3(relative3(project.root, block.path)),
+          lastActiveAt: now
+        };
+        upserts.push(doc);
+        upsertCacheEntries.set(block.id, { hash: contentHash, mtime: now });
+      }
+    }
+    const t = Date.now();
+    if (t - lastExtractEmit >= EXTRACT_PROGRESS_INTERVAL_MS || done === changedBlocks.length) {
+      onProgress({ kind: "extract", done, total: changedBlocks.length });
+      lastExtractEmit = t;
+    }
+  }
+  const currentIds = new Set(blocks.map((b) => b.id));
+  const deletes = [];
+  for (const id of Object.keys(cache)) {
+    if (currentIds.has(id)) continue;
+    deletes.push(composeDocId(repo, worktreeId, id));
+  }
+  const batches = [];
+  for (let i = 0; i < upserts.length; i += CHUNK) {
+    batches.push({ upserts: upserts.slice(i, i + CHUNK), deletes: [] });
+  }
+  if (deletes.length > 0) {
+    if (batches.length > 0) batches[batches.length - 1].deletes = deletes;
+    else batches.push({ upserts: [], deletes });
+  }
+  const persistedCache = { ...cache, ...mtimeRefreshes };
+  let pushedUpserts = 0;
+  let pushedDeletes = 0;
+  const skipped = blocks.length - upserts.length;
+  if (batches.length === 0) {
+    if (Object.keys(mtimeRefreshes).length > 0 || schemaMismatch) {
+      await saveHashCache(persistedCache, { workspaceRoot: project.root });
+    }
+    const durationMs2 = Date.now() - startTime;
+    onProgress({ kind: "complete", durationMs: durationMs2, upserts: 0, deletes: 0 });
+    return { upserts: 0, deletes: 0, skipped, durationMs: durationMs2 };
+  }
+  for (let i = 0; i < batches.length; i += 1) {
+    const batch = batches[i];
+    const res = await opts.cloudClient.indexBatch(batch);
+    if (res.kind === "ok") {
+      for (const doc of batch.upserts) {
+        const entry = upsertCacheEntries.get(doc.blockId);
+        if (entry) persistedCache[doc.blockId] = entry;
+      }
+      if (batch.deletes.length > 0) {
+        for (const id of Object.keys(cache)) {
+          if (!currentIds.has(id)) delete persistedCache[id];
+        }
+      }
+      await saveHashCache(persistedCache, { workspaceRoot: project.root });
+      pushedUpserts += batch.upserts.length;
+      pushedDeletes += batch.deletes.length;
+      onProgress({ kind: "pushed", batch: i + 1, remaining: batches.length - i - 1 });
+      if (batch.deletes.length > 0) {
+        onProgress({ kind: "deleted", count: batch.deletes.length });
+      }
+      continue;
+    }
+    const retryable = isRetryable2(res);
+    if (!retryable) {
+      onProgress({
+        kind: "error",
+        err: new Error(res.envelope.error.message),
+        retryable: false
+      });
+      const durationMs3 = Date.now() - startTime;
+      return { upserts: pushedUpserts, deletes: pushedDeletes, skipped, durationMs: durationMs3 };
+    }
+    const remainingBatches = batches.slice(i);
+    await enqueueBatches(project.root, remainingBatches);
+    onProgress({
+      kind: "error",
+      err: new Error(res.envelope.error.message),
+      retryable: true
+    });
+    const durationMs2 = Date.now() - startTime;
+    return { upserts: pushedUpserts, deletes: pushedDeletes, skipped, durationMs: durationMs2 };
+  }
+  const durationMs = Date.now() - startTime;
+  onProgress({ kind: "complete", durationMs, upserts: pushedUpserts, deletes: pushedDeletes });
+  return { upserts: pushedUpserts, deletes: pushedDeletes, skipped, durationMs };
 }
-function send(ws, frame) {
+function isRetryable2(r) {
+  if (r.kind !== "error") return false;
+  const code = r.envelope.error.code;
+  if (code === "not_logged_in" || code === "unauthorized") return false;
+  if (code === "upstream_unreachable") return true;
+  if (r.status >= 500 && r.status <= 599) return true;
+  return false;
+}
+async function readQueue(queuePath) {
   try {
-    ws.send(JSON.stringify(frame));
-  } catch {
+    const raw = await readFile9(queuePath, "utf8");
+    const parsed = JSON.parse(raw);
+    if (Array.isArray(parsed)) return parsed;
+    return [];
+  } catch (err) {
+    if (err.code === "ENOENT") return [];
+    return [];
   }
 }
-var spawnOverride;
-var init_terminal_ws = __esm({
-  "src/ui/api/terminal-ws.ts"() {
-    "use strict";
-    init_terminal_resolver();
-    spawnOverride = null;
-  }
-});
-
-// src/cli.ts
-init_blueprints();
-init_project();
-import { dirname as dirname3, resolve as resolve3 } from "path";
-import { fileURLToPath } from "url";
-import { Command } from "commander";
-import importLocal from "import-local";
-
-// src/core/version.ts
-var VERSION = "0.0.0";
-
-// src/ui/ui-server.ts
-import { existsSync as existsSync4 } from "fs";
-import { readFile as readFile5 } from "fs/promises";
-import { createServer } from "http";
-import { extname as extname2, join as join4, normalize, resolve as resolve2 } from "path";
+async function writeQueueAtomic(queuePath, q) {
+  await mkdir5(dirname7(queuePath), { recursive: true });
+  const tmp = `${queuePath}.tmp`;
+  await writeFile5(tmp, JSON.stringify(q), "utf8");
+  await rename3(tmp, queuePath);
+}
+async function enqueueBatches(projectRoot, batches) {
+  const queuePath = join8(projectRoot, FILESYSTEM_LAYOUT.project.queueFile);
+  const existing = await readQueue(queuePath);
+  const queuedAt = Date.now();
+  for (const b of batches) {
+    existing.push({ upserts: b.upserts, deletes: b.deletes, queuedAt });
+  }
+  await writeQueueAtomic(queuePath, existing);
+}
 
 // src/ui/api/blocks-handler.ts
 init_blueprints();
@@ -838,7 +2969,7 @@ async function handleBlueprintsRequest(cwd) {
 }
 
 // src/ui/api/code-handler.ts
-import { readFile as readFile3 } from "fs/promises";
+import { readFile as readFile10 } from "fs/promises";
 import { extname } from "path";
 import { codeToHtml } from "shiki";
 var EXT_TO_LANG = {
@@ -862,7 +2993,7 @@ var EXT_TO_LANG = {
 async function handleCodeRequest(absolutePath, language) {
   let raw;
   try {
-    raw = await readFile3(absolutePath, "utf8");
+    raw = await readFile10(absolutePath, "utf8");
   } catch {
     return errorResponse(404, `File not found: ${absolutePath}`);
   }
@@ -908,13 +3039,54 @@ function escapeHtml(s) {
   return s.replace(/[&<>]/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;" })[c] ?? c);
 }
 
+// src/ui/api/code-search-handler.ts
+var MAX_QUERY_LENGTH = 1024;
+async function handleCodeSearchRequest(cwd, query) {
+  if (!query || query.length === 0) {
+    return {
+      status: 400,
+      body: { error: { code: "invalid_request", message: "Missing or empty ?q" } }
+    };
+  }
+  if (query.length > MAX_QUERY_LENGTH) {
+    return {
+      status: 400,
+      body: { error: { code: "invalid_request", message: "Query too long" } }
+    };
+  }
+  const result = await codeSearch({ query, cwd });
+  return { status: 200, body: result };
+}
+
+// src/ui/api/context-handler.ts
+init_project();
+async function handleContextRequest(cwd, opts = {}) {
+  try {
+    const project = await findProject(cwd);
+    const machineUuid = await getOrCreateMachineUuid({ homeDir: opts.homeDir });
+    const worktreeId = deriveWorktreeId(machineUuid, project.root);
+    const repo = await deriveRepoId(project.root);
+    return { status: 200, body: { worktreeId, repo } };
+  } catch (err) {
+    return {
+      status: 500,
+      body: {
+        error: {
+          code: "context_unavailable",
+          message: err instanceof Error ? err.message : String(err)
+        }
+      }
+    };
+  }
+}
+
 // src/ui/api/markdown-handler.ts
-import { readFile as readFile4 } from "fs/promises";
+import { readFile as readFile11 } from "fs/promises";
 import { marked } from "marked";
 async function handleMarkdownRequest(absolutePath) {
   let raw;
   try {
-    raw = await readFile4(absolutePath, "utf8");
+    raw = await readFile11(absolutePath, "utf8");
   } catch {
     return errorResponse2(404, `File not found: ${absolutePath}`);
   }
@@ -958,8 +3130,182 @@ function escapeHtml2(s) {
   return s.replace(/[&<>]/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;" })[c] ?? c);
 }
 
+// src/ui/api/progress-stream.ts
+var DEFAULT_HEARTBEAT_MS = 3e4;
+function createProgressBus(opts = {}) {
+  const heartbeatIntervalMs = opts.heartbeatIntervalMs ?? DEFAULT_HEARTBEAT_MS;
+  const clients = /* @__PURE__ */ new Set();
+  let closed = false;
+  return {
+    emit(event) {
+      if (closed) return;
+      const frame = `data: ${JSON.stringify(event)}
+
+`;
+      for (const c of clients) {
+        try {
+          c.res.write(frame);
+        } catch {
+        }
+      }
+    },
+    handleStream(req, res) {
+      if (closed) return;
+      res.statusCode = 200;
+      res.setHeader("content-type", "text/event-stream");
+      res.setHeader("cache-control", "no-cache");
+      res.setHeader("connection", "keep-alive");
+      if (typeof res.flushHeaders === "function") {
+        res.flushHeaders();
+      }
+      const timer = setInterval(() => {
+        try {
+          res.write(": heartbeat\n\n");
+        } catch {
+        }
+      }, heartbeatIntervalMs);
+      if (typeof timer.unref === "function") timer.unref();
+      const entry = { res, timer };
+      clients.add(entry);
+      const cleanup = () => {
+        clearInterval(timer);
+        clients.delete(entry);
+      };
+      req.on("close", cleanup);
+      res.on("close", cleanup);
+    },
+    close() {
+      if (closed) return;
+      closed = true;
+      for (const c of clients) {
+        clearInterval(c.timer);
+        try {
+          c.res.end();
+        } catch {
+        }
+      }
+      clients.clear();
+    }
+  };
+}
+
+// src/ui/api/proxy.ts
+init_dist();
+import { readFile as readFile12, stat as stat3 } from "fs/promises";
+import { request as httpRequest } from "http";
+import { request as httpsRequest } from "https";
+var CLOUD_PREFIX = "/api/cloud";
+var DEFAULT_CLOUD_URL = "http://localhost:3001";
+var MAX_BODY_BYTES = 16 * 1024 * 1024;
+var cachedToken = null;
+var cachedMtime = 0;
+function isCloudProxyRoute(pathname) {
+  return pathname.startsWith(`${CLOUD_PREFIX}/`) || pathname === CLOUD_PREFIX;
+}
+function selectRequestFn(url) {
+  return url.protocol === "https:" ? httpsRequest : httpRequest;
+}
+async function handleCloudProxy(req, res, opts) {
+  const url = new URL(req.url ?? "/", "http://localhost");
+  const cloudPath = url.pathname.slice(CLOUD_PREFIX.length);
+  const downstream = url.search ? `${cloudPath}${url.search}` : cloudPath;
+  const cloudBase = opts.cloudUrl ?? process.env.MACROSCOPE_CLOUD_URL ?? DEFAULT_CLOUD_URL;
+  const credPath = opts.credentialsPath;
+  if (!credPath) {
+    sendError(res, 401, "not_logged_in", "Run `macroscope login` first");
+    return;
+  }
+  let token;
+  try {
+    token = await readToken(credPath);
+  } catch {
+    sendError(res, 401, "not_logged_in", "Run `macroscope login` first");
+    return;
+  }
+  const { body, tooLarge } = await readBody(req);
+  if (tooLarge) {
+    sendError(res, 413, "payload_too_large", `request body exceeds ${MAX_BODY_BYTES} bytes`);
+    return;
+  }
+  const targetUrl = new URL(downstream, cloudBase);
+  const requestFn = selectRequestFn(targetUrl);
+  const headers = {
+    authorization: `Bearer ${token}`
+  };
+  if (req.headers["content-type"]) {
+    headers["content-type"] = req.headers["content-type"];
+  }
+  try {
+    await new Promise((resolve5, reject) => {
+      const proxyReq = requestFn(
+        targetUrl,
+        { method: req.method ?? "GET", headers },
+        (upstream) => {
+          res.statusCode = upstream.statusCode ?? 502;
+          const ct = upstream.headers["content-type"];
+          if (ct) res.setHeader("content-type", ct);
+          upstream.pipe(res);
+          upstream.on("end", resolve5);
+          upstream.on("error", reject);
+        }
+      );
+      proxyReq.on("error", reject);
+      if (body.length > 0) proxyReq.write(body);
+      proxyReq.end();
+    });
+  } catch (err) {
+    if (!res.headersSent) {
+      sendError(res, 502, "cloud_unreachable", err instanceof Error ? err.message : String(err));
+    }
+  }
+}
+async function readToken(credPath) {
+  const s = await stat3(credPath);
+  if (process.platform !== "win32") {
+    const groupWorldBits = s.mode & 63;
+    if (groupWorldBits !== 0) {
+      throw new Error(
+        `credentials file ${credPath} has mode ${(s.mode & 511).toString(8)}; require 0600`
+      );
+    }
+  }
+  const mtime = s.mtimeMs;
+  if (cachedToken && mtime === cachedMtime) {
+    return cachedToken;
+  }
+  const raw = await readFile12(credPath, "utf-8");
+  const parsed = OAuthCredentialsSchema.parse(JSON.parse(raw));
+  cachedToken = parsed.accessToken;
+  cachedMtime = mtime;
+  return cachedToken;
+}
+function readBody(req) {
+  return new Promise((resolve5, reject) => {
+    const chunks = [];
+    let total = 0;
+    let tooLarge = false;
+    req.on("data", (c) => {
+      total += c.length;
+      if (total > MAX_BODY_BYTES) {
+        tooLarge = true;
+        return;
+      }
+      chunks.push(c);
+    });
+    req.on("end", () => resolve5({ body: Buffer.concat(chunks), tooLarge }));
+    req.on("error", reject);
+  });
+}
+function sendError(res, status, code, message) {
+  const envelope = { error: { code, message } };
+  res.statusCode = status;
+  res.setHeader("content-type", "application/json; charset=utf-8");
+  res.end(JSON.stringify(envelope));
+}
+
 // src/ui/api/service-manager.ts
-import { spawn as nodeSpawn } from "child_process";
+init_process_group();
+import { spawn as nodeSpawn2 } from "child_process";
 
 // src/ui/api/service-readiness.ts
 async function pollReadiness(url, opts = {}) {
@@ -992,7 +3338,7 @@ async function pollReadiness(url, opts = {}) {
       if (opts.signal?.aborted || err instanceof AbortError) return { ready: false, aborted: true };
       lastError = err instanceof Error ? err.message : String(err);
     }
-    const result = await sleep(intervalMs, opts.signal);
+    const result = await sleep2(intervalMs, opts.signal);
     if (result.aborted) return { ready: false, aborted: true };
   }
   return { ready: false, lastError };
@@ -1002,22 +3348,22 @@ var AbortError = class extends Error {
     super("aborted");
   }
 };
-function sleep(ms, signal) {
-  return new Promise((resolve4) => {
+function sleep2(ms, signal) {
+  return new Promise((resolve5) => {
     let onAbort = null;
     const t = setTimeout(() => {
       if (onAbort && signal) signal.removeEventListener("abort", onAbort);
-      resolve4({ aborted: false });
+      resolve5({ aborted: false });
     }, ms);
     if (signal?.aborted) {
       clearTimeout(t);
-      resolve4({ aborted: true });
+      resolve5({ aborted: true });
       return;
     }
     onAbort = () => {
       clearTimeout(t);
       if (signal && onAbort) signal.removeEventListener("abort", onAbort);
-      resolve4({ aborted: true });
+      resolve5({ aborted: true });
     };
     signal?.addEventListener("abort", onAbort, { once: true });
   });
@@ -1028,10 +3374,14 @@ var LOG_BUFFER_BYTES = 4096;
 var ServiceManager = class {
   spawn;
   poll;
+  kill;
+  killGracePeriodMs;
   services = /* @__PURE__ */ new Map();
   constructor(deps = {}) {
-    this.spawn = deps.spawn ?? nodeSpawn;
+    this.spawn = deps.spawn ?? nodeSpawn2;
     this.poll = deps.pollReadiness ?? pollReadiness;
+    this.kill = deps.kill;
+    this.killGracePeriodMs = deps.killGracePeriodMs ?? 5e3;
   }
   keyFor(input) {
     return JSON.stringify({ command: input.command, cwd: input.cwd });
@@ -1057,7 +3407,12 @@ var ServiceManager = class {
     const state = { status: "starting", logs: "" };
     let child;
     try {
-      child = this.spawn(bin, args, { cwd: input.cwd, stdio: ["ignore", "pipe", "pipe"] });
+      child = spawnDetached(
+        bin,
+        args,
+        { cwd: input.cwd, stdio: ["ignore", "pipe", "pipe"] },
+        { spawn: this.spawn }
+      );
     } catch (err) {
       return { status: "failed", logs: "", message: `spawn failed: ${err.message}` };
     }
@@ -1084,24 +3439,34 @@ var ServiceManager = class {
     void this.poll(input.readyUrl, {
       timeoutMs: input.startupTimeoutMs ?? 3e4,
       signal: abort.signal
-    }).then((result) => {
+    }).then(async (result) => {
       if (state.status !== "starting") return;
       if (result.ready) {
         state.status = "ready";
       } else if (!result.aborted) {
         state.status = "failed";
         state.message = `readiness check failed: ${result.lastError ?? "timeout"}`;
-        if (!child.killed) child.kill();
+        if (!child.killed) {
+          await killTree(child, { kill: this.kill, gracePeriodMs: this.killGracePeriodMs });
+        }
       }
     });
     return state;
   }
-  shutdown() {
-    for (const entry of this.services.values()) {
-      entry.abort.abort();
-      if (entry.child && !entry.child.killed) entry.child.kill();
-    }
+  async shutdown() {
+    const entries = [...this.services.values()];
     this.services.clear();
+    await Promise.all(
+      entries.map(async (entry) => {
+        entry.abort.abort();
+        if (entry.child && !entry.child.killed) {
+          await killTree(entry.child, {
+            kill: this.kill,
+            gracePeriodMs: this.killGracePeriodMs
+          });
+        }
+      })
+    );
   }
 };
 
@@ -1170,19 +3535,26 @@ var MIME_TYPES = {
   ".map": "application/json; charset=utf-8"
 };
 async function startUiServer(opts) {
-  const staticDir = resolve2(opts.staticDir);
+  const staticDir = resolve3(opts.staticDir);
   if (!existsSync4(staticDir)) {
     throw new Error(
       `Macroscope UI build is missing. Expected files at ${staticDir}. Run \`pnpm build\` first.`
     );
   }
-  const indexFile = join4(staticDir, "index.html");
+  const indexFile = join9(staticDir, "index.html");
   if (!existsSync4(indexFile)) {
     throw new Error(`Macroscope UI build is incomplete: ${indexFile} not found.`);
   }
   const serviceManager = new ServiceManager();
-  const server = createServer((req, res) => {
-    void handleRequest(req, res, staticDir, opts.cwd, serviceManager).catch((err) => {
+  const progressBus = createProgressBus();
+  const credentialsPath2 = opts.credentialsPath ?? join9(homedir4(), FILESYSTEM_LAYOUT.user.credentialsFile);
+  const proxyOpts = { cloudUrl: opts.cloudUrl, credentialsPath: credentialsPath2 };
+  const server = createServer2((req, res) => {
+    if (req.url && new URL(req.url, "http://localhost").pathname === "/api/local/progress") {
+      progressBus.handleStream(req, res);
+      return;
+    }
+    void handleRequest(req, res, staticDir, opts.cwd, serviceManager, proxyOpts).catch((err) => {
       respondError(res, 500, err instanceof Error ? err.message : String(err));
     });
   });
@@ -1208,22 +3580,106 @@ async function startUiServer(opts) {
     } catch {
     }
   }
-  const onSignal = () => serviceManager.shutdown();
-  process.once("SIGINT", onSignal);
-  process.once("SIGTERM", onSignal);
+  const watcher = await maybeStartCloudSync(opts, credentialsPath2, progressBus);
+  let closed = false;
   return {
     url,
     port,
-    close: () => new Promise((resolveClose, reject) => {
-      serviceManager.shutdown();
-      process.off("SIGINT", onSignal);
-      process.off("SIGTERM", onSignal);
-      server.close((err) => err ? reject(err) : resolveClose());
-    })
+    serviceManager,
+    watcher,
+    close: async () => {
+      if (closed) return;
+      closed = true;
+      if (watcher) {
+        await watcher.stop().catch((err) => {
+          console.warn(
+            `[macroscope] watcher.stop() failed: ${err instanceof Error ? err.message : String(err)}`
+          );
+        });
+      }
+      progressBus.close();
+      await serviceManager.shutdown();
+      await new Promise(
+        (resolveClose, reject) => server.close((err) => err ? reject(err) : resolveClose())
+      );
+    }
   };
 }
-async function handleRequest(req, res, staticDir, cwd, serviceManager) {
+async function maybeStartCloudSync(opts, credentialsPath2, progressBus) {
+  if (opts.cloudSync === false) return null;
+  const sync = opts.cloudSync ?? {};
+  const cloudClient = sync.cloudClient ?? createCloudClient({ baseUrl: opts.cloudUrl, credentialsPath: credentialsPath2 });
+  let cloudFatalError = null;
+  try {
+    const result = await runCatchup({
+      projectRoot: opts.cwd,
+      cloudClient,
+      onProgress: (e) => {
+        sync.onCatchupProgress?.(e);
+        progressBus.emit({ source: "catchup", payload: e });
+        if (e.kind === "error" && !e.retryable) {
+          cloudFatalError = e.err.message;
+        }
+      }
+    });
+    if (result.upserts > 0 || result.deletes > 0) {
+      console.log(
+        `[macroscope] catch-up scan complete: ${result.upserts} upserts, ${result.deletes} deletes (${result.durationMs}ms)`
+      );
+    }
+  } catch (err) {
+    cloudFatalError = err instanceof Error ? err.message : String(err);
+  }
+  if (cloudFatalError) {
+    console.warn(
+      `[macroscope] cloud catalogue disabled: ${cloudFatalError} \u2014 local code search still works. Run \`macroscope login\` to enable cloud search.`
+    );
+    return null;
+  }
+  try {
+    const watcher = await startWatcher({
+      projectRoot: opts.cwd,
+      cloudClient,
+      lifecycle: false
+    });
+    const userFwd = sync.onWatcherEvent;
+    for (const name of ["batchStart", "batchSent", "error", "queueDrained"]) {
+      watcher.on(name, (payload) => {
+        userFwd?.(name, payload);
+        progressBus.emit({
+          source: "watcher",
+          payload: { event: name, data: payload }
+        });
+      });
+    }
+    return watcher;
+  } catch (err) {
+    console.warn(
+      `[macroscope] watcher failed to start: ${err instanceof Error ? err.message : String(err)}`
+    );
+    return null;
+  }
+}
+async function handleRequest(req, res, staticDir, cwd, serviceManager, proxyOpts) {
   const url = new URL(req.url ?? "/", "http://localhost");
+  if (isCloudProxyRoute(url.pathname)) {
+    await handleCloudProxy(req, res, proxyOpts);
+    return;
+  }
+  if (url.pathname === "/api/local/code-search") {
+    const result = await handleCodeSearchRequest(cwd, url.searchParams.get("q"));
+    res.statusCode = result.status;
+    res.setHeader("content-type", "application/json; charset=utf-8");
+    res.end(JSON.stringify(result.body));
+    return;
+  }
+  if (url.pathname === "/api/local/context") {
+    const result = await handleContextRequest(cwd);
+    res.statusCode = result.status;
+    res.setHeader("content-type", "application/json; charset=utf-8");
+    res.end(JSON.stringify(result.body));
+    return;
+  }
   if (url.pathname === "/api/blueprints") {
     const result = await handleBlueprintsRequest(cwd);
     res.statusCode = result.status;
@@ -1246,8 +3702,8 @@ async function handleRequest(req, res, staticDir, cwd, serviceManager) {
       res.end("Missing ?path");
       return;
     }
-    const absolute = resolve2(cwd, requestedPath);
-    if (!absolute.startsWith(resolve2(cwd))) {
+    const absolute = resolve3(cwd, requestedPath);
+    if (!absolute.startsWith(resolve3(cwd))) {
       res.statusCode = 403;
       res.setHeader("content-type", "text/plain");
       res.end("Forbidden");
@@ -1268,8 +3724,8 @@ async function handleRequest(req, res, staticDir, cwd, serviceManager) {
       res.end("Missing ?path");
       return;
     }
-    const absolute = resolve2(cwd, requestedPath);
-    if (!absolute.startsWith(resolve2(cwd))) {
+    const absolute = resolve3(cwd, requestedPath);
+    if (!absolute.startsWith(resolve3(cwd))) {
       res.statusCode = 403;
       res.setHeader("content-type", "text/plain");
       res.end("Forbidden");
@@ -1282,7 +3738,7 @@ async function handleRequest(req, res, staticDir, cwd, serviceManager) {
     return;
   }
   if (url.pathname === "/api/services/ensure" && req.method === "POST") {
-    const raw = await readBody(req);
+    const raw = await readBody2(req);
     let parsed;
     try {
       parsed = JSON.parse(raw || "{}");
@@ -1302,19 +3758,19 @@ async function handleRequest(req, res, staticDir, cwd, serviceManager) {
     return;
   }
   const requested = url.pathname === "/" ? "/index.html" : url.pathname;
-  const absolutePath = normalize(join4(staticDir, requested));
+  const absolutePath = normalize(join9(staticDir, requested));
   if (!absolutePath.startsWith(staticDir)) {
     respondError(res, 403, "Forbidden");
     return;
   }
   try {
-    const content = await readFile5(absolutePath);
+    const content = await readFile13(absolutePath);
     res.setHeader("content-type", MIME_TYPES[extname2(absolutePath)] ?? "application/octet-stream");
     res.end(content);
     return;
   } catch {
     try {
-      const indexContent = await readFile5(join4(staticDir, "index.html"));
+      const indexContent = await readFile13(join9(staticDir, "index.html"));
       res.setHeader("content-type", "text/html; charset=utf-8");
       res.end(indexContent);
     } catch {
@@ -1327,7 +3783,7 @@ function respondError(res, status, message) {
   res.setHeader("content-type", "text/plain; charset=utf-8");
   res.end(message);
 }
-function readBody(req) {
+function readBody2(req) {
   return new Promise((resolveBody, reject) => {
     const chunks = [];
     req.on("data", (c) => chunks.push(c));
@@ -1361,12 +3817,62 @@ function main() {
     "--port <n>",
     "port to listen on (default: auto-pick a free port)",
     (v) => Number.parseInt(v, 10)
-  ).option("--no-open", "don't automatically open a browser").action(async (cmdOpts) => {
+  ).option("--no-open", "don't automatically open a browser").option(
+    "--cloud-url <url>",
+    "override the cloud API URL (also: MACROSCOPE_CLOUD_URL env var; defaults to http://localhost:3001)"
+  ).option(
+    "--credentials <path>",
+    "override the credentials file path (defaults to ~/.macroscope/credentials)"
+  ).action(async (cmdOpts) => {
     await runUi({
       cwd: cmdOpts.cwd,
       port: cmdOpts.port,
-      open: cmdOpts.open !== false
+      open: cmdOpts.open !== false,
+      cloudUrl: cmdOpts.cloudUrl,
+      credentialsPath: cmdOpts.credentials
+    });
+  });
+  program.command("login").description(
+    "Authenticate with a Git host (GitHub or GitLab) and store credentials at ~/.macroscope/credentials"
+  ).addOption(
+    new Option("--provider <id>", "identity provider").choices(["github", "gitlab"]).default("github")
+  ).action(async (cmdOpts, cmd) => {
+    const globalOpts = cmd.parent?.opts() ?? {};
+    const code = await runLogin({
+      providerId: cmdOpts.provider,
+      json: !!globalOpts.json
+    });
+    process.exitCode = code;
+  });
+  program.command("logout").description("Delete the stored credentials file at ~/.macroscope/credentials").action(async (_cmdOpts, cmd) => {
+    const globalOpts = cmd.parent?.opts() ?? {};
+    const code = await runLogout({ json: !!globalOpts.json });
+    process.exitCode = code;
+  });
+  program.command("search <query>").description("Search the cloud catalogue and local code in one shot").option("--cwd <path>", "project search starts here (defaults to current dir)").option("--worktree <id>", "restrict to one worktree").option("--all-worktrees", "search across all worktrees (default until T14)").option("--all-repos", "no repo filter (default)").option("--repo <name>", "restrict to one repo").option("--kind <k>", "restrict to one block kind").option("--limit <n>", "cap results per side", (v) => Number.parseInt(v, 10)).action(async (query, cmdOpts, cmd) => {
+    const globalOpts = cmd.parent?.opts() ?? {};
+    const code = await runSearch({
+      query,
+      json: !!globalOpts.json,
+      cwd: cmdOpts.cwd,
+      scope: {
+        worktree: cmdOpts.worktree,
+        allWorktrees: !!cmdOpts.allWorktrees,
+        allRepos: !!cmdOpts.allRepos,
+        repo: cmdOpts.repo,
+        kind: cmdOpts.kind,
+        limit: cmdOpts.limit
+      }
+    });
+    process.exitCode = code;
+  });
+  program.command("status").description("Show worktree + cloud + login state").option("--cwd <path>", "project search starts here (defaults to current dir)").action(async (cmdOpts, cmd) => {
+    const globalOpts = cmd.parent?.opts() ?? {};
+    const code = await runStatus({
+      json: !!globalOpts.json,
+      cwd: cmdOpts.cwd
     });
+    process.exitCode = code;
   });
   program.parse(process.argv);
 }
@@ -1386,13 +3892,13 @@ async function runBlueprints(opts) {
   if (opts.json) {
     writeJson(result);
   } else {
-    writeHuman(result);
+    writeHuman3(result);
   }
   if (result.errors.length > 0) {
     process.exitCode = 1;
   }
 }
-function writeHuman(result) {
+function writeHuman3(result) {
   if (result.blueprints.length === 0 && result.errors.length === 0) {
     process.stdout.write(
       "No blueprints found. Create one at .macroscope/blueprints/<kind>/handler.ts.\n"
@@ -1441,25 +3947,40 @@ async function runUi(opts) {
     }
     throw err;
   }
-  const here = dirname3(fileURLToPath(import.meta.url));
-  const staticDir = resolve3(here, "ui");
+  const here = dirname8(fileURLToPath(import.meta.url));
+  const staticDir = resolve4(here, "ui");
   let server;
   try {
-    server = await startUiServer({ cwd, staticDir, port: opts.port, open: opts.open });
+    server = await startUiServer({
+      cwd,
+      staticDir,
+      port: opts.port,
+      open: opts.open,
+      cloudUrl: opts.cloudUrl,
+      credentialsPath: opts.credentialsPath
+    });
   } catch (err) {
     process.stderr.write(`macroscope ui: ${err.message}
 `);
     process.exit(1);
   }
+  installLifecycle({
+    watchStdin: true,
+    onShutdown: async (reason) => {
+      process.stderr.write(`macroscope shutting down (${reason})
+`);
+      try {
+        await server.close();
+      } catch (err) {
+        process.stderr.write(`shutdown error: ${err.message}
+`);
+      }
+      process.exit(0);
+    }
+  });
   process.stdout.write(`macroscope ui running at ${server.url}
 `);
   process.stdout.write("Press Ctrl+C to stop.\n");
-  const shutdown = async () => {
-    await server.close();
-    process.exit(0);
-  };
-  process.on("SIGINT", () => void shutdown());
-  process.on("SIGTERM", () => void shutdown());
 }
 function writeError(message, json) {
   if (json) {