trellis 3.1.13 → 3.1.19

package/dist/cli/index.js

@@ -2401,8 +2401,8 @@ var exports_server = {};
 __export(exports_server, {
   startUIServer: () => startUIServer
 });
-import { readFileSync as readFileSync3, existsSync as existsSync5 } from "fs";
-import { join as join5, dirname as dirname4 } from "path";
+import { readFileSync as readFileSync4, existsSync as existsSync5 } from "fs";
+import { join as join5, dirname as dirname5 } from "path";
 function buildGraph(engine) {
   const nodes = [];
   const edges = [];
@@ -2506,7 +2506,7 @@ function buildGraph(engine) {
         if (existsSync5(absPath)) {
           mdFiles.push({
             path: f.path,
-            content: readFileSync3(absPath, "utf-8")
+            content: readFileSync4(absPath, "utf-8")
           });
         }
       }
@@ -2732,26 +2732,26 @@ async function startUIServer(opts) {
   const engine = new TrellisVcsEngine({ rootPath: opts.rootPath });
   engine.open();
   function findClientHtml() {
-    const here = dirname4(process.argv[1]);
+    const here2 = dirname5(process.argv[1]);
     const candidates = [
-      join5(here, "client.html"),
-      join5(here, "..", "ui", "client.html"),
-      join5(here, "ui", "client.html")
+      join5(here2, "client.html"),
+      join5(here2, "..", "ui", "client.html"),
+      join5(here2, "ui", "client.html")
     ];
-    let dir = here;
+    let dir = here2;
     for (let i = 0;i < 5; i++) {
       candidates.push(join5(dir, "dist", "ui", "client.html"));
       candidates.push(join5(dir, "ui", "client.html"));
-      dir = dirname4(dir);
+      dir = dirname5(dir);
     }
     for (const p of candidates) {
       if (existsSync5(p))
         return p;
     }
-    throw new Error(`Could not find client.html. Searched from: ${here}
+    throw new Error(`Could not find client.html. Searched from: ${here2}
 Try reinstalling the package or running \`bun run build\`.`);
   }
-  const clientHtml = readFileSync3(findClientHtml(), "utf-8");
+  const clientHtml = readFileSync4(findClientHtml(), "utf-8");
   let embeddingManager = null;
   function getEmbeddingManager() {
     if (!embeddingManager) {
@@ -3375,7 +3375,7 @@ var chalkStderr = createChalk({ level: stderrColor ? stderrColor.level : 0 });
 var source_default = chalk;
 
 // src/cli/index.ts
-import { resolve, join as join6 } from "path";
+import { resolve as resolve2, join as join6 } from "path";
 
 // node_modules/@inquirer/core/dist/lib/key.js
 var isUpKey = (key, keybindings = []) => key.name === "up" || keybindings.includes("vim") && key.name === "k" || keybindings.includes("emacs") && key.ctrl && key.name === "p";
@@ -5706,15 +5706,54 @@ function base58btcEncode(buf) {
   }
   return encoded || "1";
 }
-// src/cli/index.ts
-var program2 = new Command;
-program2.name("trellis").description("TrellisVCS \u2014 graph-native, code-first version control").version("0.1.0");
-function requireRepo(rootPath) {
-  if (!TrellisVcsEngine.isRepo(rootPath)) {
-    console.error(source_default.red("Not a TrellisVCS repository. Run `trellis init` first."));
-    process.exit(1);
+// src/cli/repo-path.ts
+import { readFileSync as readFileSync3 } from "fs";
+import { dirname as dirname4, resolve } from "path";
+import { fileURLToPath } from "url";
+init_engine();
+var here = dirname4(fileURLToPath(import.meta.url));
+function cliVersion() {
+  const path = resolve(here, "../../package.json");
+  try {
+    const pkg = JSON.parse(readFileSync3(path, "utf8"));
+    if (typeof pkg.version === "string")
+      return pkg.version;
+  } catch {}
+  return "0.0.0";
+}
+function findRepoRoot(pathOpt) {
+  const start = resolve(pathOpt ?? process.cwd());
+  let dir = start;
+  while (true) {
+    if (TrellisVcsEngine.isRepo(dir))
+      return dir;
+    const parent = dirname4(dir);
+    if (parent === dir)
+      return;
+    dir = parent;
   }
 }
+function resolveRepoRoot(pathOpt) {
+  const start = resolve(pathOpt ?? process.cwd());
+  const found = findRepoRoot(pathOpt);
+  if (found)
+    return found;
+  failNotRepo(start, pathOpt);
+}
+function failNotRepo(start, pathOpt) {
+  console.error(source_default.red("Not a TrellisVCS repository."));
+  console.error(source_default.dim(`  looked from: ${start}`));
+  if (pathOpt && resolve(pathOpt) !== process.cwd()) {
+    console.error(source_default.dim(`  -p:          ${resolve(pathOpt)}`));
+  }
+  console.error(source_default.dim(`  cwd:         ${process.cwd()}`));
+  console.error(source_default.dim("  Hint: run from the repo root, pass -p <path>, or run `trellis init`."));
+  process.exit(1);
+}
+
+// src/cli/index.ts
+var program2 = new Command;
+program2.name("trellis").description("TrellisVCS \u2014 graph-native, code-first version control").version(cliVersion());
 async function runInit(rootPath, opts = {}) {
   const isInteractive = opts.interactive !== false && process.stdout.isTTY && !process.argv.includes("--no-interactive");
   if (TrellisVcsEngine.isRepo(rootPath)) {
@@ -5750,115 +5789,147 @@ async function runInit(rootPath, opts = {}) {
   if (isInteractive) {
     console.log(source_default.cyan(`
   Configuring workspace...`));
-    const frameworkChoices = [
-      { name: "React", value: "react" },
-      { name: "Vue", value: "vue" },
-      { name: "Svelte", value: "svelte" },
-      { name: "Next.js", value: "next" },
-      { name: "Nuxt", value: "nuxt" },
-      { name: "Remotion", value: "remotion" },
-      { name: "Expo / React Native", value: "expo" },
-      { name: "Bun runtime", value: "bun" },
-      { name: "Node.js server", value: "node" },
-      { name: "CLI tool", value: "cli" },
-      { name: "Library / Package", value: "library" },
-      { name: "Animation studio", value: "animation" },
-      { name: "Games", value: "games" },
-      { name: "None / Vanilla", value: "none" }
-    ];
-    framework = await dist_default5({
-      message: detectedFramework ? `What type of project are you building? (detected: ${detectedFramework})` : "What type of project are you building?",
-      choices: frameworkChoices,
-      default: opts.framework || detectedFramework || "none"
-    });
-    const ideChoices = [
-      {
-        name: "Cursor",
-        value: "cursor",
-        checked: selectedIdes.includes("cursor") || selectedIdes.length === 0
-      },
-      {
-        name: "Windsurf",
-        value: "windsurf",
-        checked: selectedIdes.includes("windsurf")
-      },
-      {
-        name: "Claude Desktop",
-        value: "claude",
-        checked: selectedIdes.includes("claude")
-      },
-      {
-        name: "VS Code Copilot",
-        value: "copilot",
-        checked: selectedIdes.includes("copilot")
-      },
-      {
-        name: "Google Gemini (Code Assist)",
-        value: "gemini",
-        checked: selectedIdes.includes("gemini")
-      },
-      {
-        name: "OpenAI Codex",
-        value: "codex",
-        checked: selectedIdes.includes("codex")
-      }
-    ];
-    selectedIdes = await dist_default4({
-      message: "Which IDEs/agents do you want to scaffold for?",
-      choices: ideChoices
-    });
-    footprint = await dist_default5({
-      message: "How minimal do you want your workspace?",
-      choices: [
-        { name: "Minimal (just agent rules)", value: "minimal" },
-        { name: "Standard (includes skills + workflows)", value: "standard" },
-        { name: "Full (kitchen sink)", value: "full" }
-      ],
-      default: footprint
-    });
-    plugins = await dist_default4({
-      message: "Select features:",
+    const setupType = await dist_default5({
+      message: "Choose your setup mode:",
       choices: [
         {
-          name: "Sub-projects (monorepo, workspaces)",
-          value: "sub-projects",
-          checked: plugins.includes("sub-projects")
+          name: "\u26A1 Minimal Setup (One-shot setup with detected defaults)",
+          value: "minimal"
         },
-        { name: "P2P Sync", value: "p2p", checked: plugins.includes("p2p") },
         {
-          name: "MCP Server",
-          value: "mcp",
-          checked: plugins.includes("mcp")
+          name: "\uD83D\uDD27 Custom Guided Setup (Customize framework, IDEs, footprint, features)",
+          value: "custom"
+        }
+      ],
+      default: "minimal"
+    });
+    if (setupType === "minimal") {
+      footprint = "minimal";
+      framework = detectedFramework || "none";
+      const ides = [];
+      const envKeys = Object.keys(process.env).join(",").toLowerCase();
+      if (process.env.TERM_PROGRAM === "Windsurf" || envKeys.includes("windsurf")) {
+        ides.push("windsurf");
+      } else if (process.env.TERM_PROGRAM === "vscode" || envKeys.includes("cursor")) {
+        ides.push("cursor");
+      } else {
+        ides.push("cursor", "windsurf");
+      }
+      selectedIdes = ides;
+      plugins = [];
+      console.log(source_default.green(`  \u2713 Detected project type: ${source_default.bold(framework)}`));
+      console.log(source_default.green(`  \u2713 Scaffolding rules for: ${source_default.bold(selectedIdes.join(", "))}`));
+    } else {
+      const frameworkChoices = [
+        { name: "React", value: "react" },
+        { name: "Vue", value: "vue" },
+        { name: "Svelte", value: "svelte" },
+        { name: "Next.js", value: "next" },
+        { name: "Nuxt", value: "nuxt" },
+        { name: "Remotion", value: "remotion" },
+        { name: "Expo / React Native", value: "expo" },
+        { name: "Bun runtime", value: "bun" },
+        { name: "Node.js server", value: "node" },
+        { name: "CLI tool", value: "cli" },
+        { name: "Library / Package", value: "library" },
+        { name: "Animation studio", value: "animation" },
+        { name: "Games", value: "games" },
+        { name: "None / Vanilla", value: "none" }
+      ];
+      framework = await dist_default5({
+        message: detectedFramework ? `What type of project are you building? (detected: ${detectedFramework})` : "What type of project are you building?",
+        choices: frameworkChoices,
+        default: opts.framework || detectedFramework || "none"
+      });
+      const ideChoices = [
+        {
+          name: "Cursor",
+          value: "cursor",
+          checked: selectedIdes.includes("cursor") || selectedIdes.length === 0
         },
         {
-          name: "UI Components",
-          value: "ui-components",
-          checked: plugins.includes("ui-components")
+          name: "Windsurf",
+          value: "windsurf",
+          checked: selectedIdes.includes("windsurf")
         },
         {
-          name: "Media Pipelines",
-          value: "media-pipelines",
-          checked: plugins.includes("media-pipelines")
+          name: "Claude Desktop",
+          value: "claude",
+          checked: selectedIdes.includes("claude")
         },
         {
-          name: "Brand System",
-          value: "brand-system",
-          checked: plugins.includes("brand-system")
+          name: "VS Code Copilot",
+          value: "copilot",
+          checked: selectedIdes.includes("copilot")
         },
         {
-          name: "Agent Memory",
-          value: "agent-memory",
-          checked: plugins.includes("agent-memory")
+          name: "Google Gemini (Code Assist)",
+          value: "gemini",
+          checked: selectedIdes.includes("gemini")
         },
         {
-          name: "Workflows",
-          value: "workflows",
-          checked: plugins.includes("workflows") || footprint !== "minimal"
+          name: "OpenAI Codex",
+          value: "codex",
+          checked: selectedIdes.includes("codex")
         }
-      ]
-    });
-    if (plugins.includes("sub-projects") && !plugins.includes("workflows")) {
-      plugins.push("workflows");
+      ];
+      selectedIdes = await dist_default4({
+        message: "Which IDEs/agents do you want to scaffold for?",
+        choices: ideChoices
+      });
+      footprint = await dist_default5({
+        message: "How minimal do you want your workspace?",
+        choices: [
+          { name: "Minimal (just agent rules)", value: "minimal" },
+          { name: "Standard (includes skills + workflows)", value: "standard" },
+          { name: "Full (kitchen sink)", value: "full" }
+        ],
+        default: footprint
+      });
+      plugins = await dist_default4({
+        message: "Select features:",
+        choices: [
+          {
+            name: "Sub-projects (monorepo, workspaces)",
+            value: "sub-projects",
+            checked: plugins.includes("sub-projects")
+          },
+          { name: "P2P Sync", value: "p2p", checked: plugins.includes("p2p") },
+          {
+            name: "MCP Server",
+            value: "mcp",
+            checked: plugins.includes("mcp")
+          },
+          {
+            name: "UI Components",
+            value: "ui-components",
+            checked: plugins.includes("ui-components")
+          },
+          {
+            name: "Media Pipelines",
+            value: "media-pipelines",
+            checked: plugins.includes("media-pipelines")
+          },
+          {
+            name: "Brand System",
+            value: "brand-system",
+            checked: plugins.includes("brand-system")
+          },
+          {
+            name: "Agent Memory",
+            value: "agent-memory",
+            checked: plugins.includes("agent-memory")
+          },
+          {
+            name: "Workflows",
+            value: "workflows",
+            checked: plugins.includes("workflows") || footprint !== "minimal"
+          }
+        ]
+      });
+      if (plugins.includes("sub-projects") && !plugins.includes("workflows")) {
+        plugins.push("workflows");
+      }
     }
   }
   const engine = new TrellisVcsEngine({ rootPath });
@@ -5893,7 +5964,7 @@ async function runInit(rootPath, opts = {}) {
   }
 }
 program2.command("init").description("Initialize a new TrellisVCS repository in the current directory").option("-p, --path <path>", "Path to initialize", ".").option("--ides <ides...>", "IDEs to scaffold for (cursor, windsurf, claude, copilot, codex, gemini)").option("--framework <framework>", "Project framework (react, vue, svelte, next, nuxt, remotion, expo, bun, node, cli, library, animation, games, none)", "none").option("--footprint <footprint>", "Workspace footprint (minimal, standard, full)", "standard").option("--no-interactive", "Skip interactive prompts").action(async (opts) => {
-  const rootPath = resolve(opts.path);
+  const rootPath = resolve2(opts.path);
   if (TrellisVcsEngine.isRepo(rootPath)) {
     console.log(source_default.yellow("Already a Trellis workspace."));
     return;
@@ -5911,7 +5982,6 @@ program2.command("init").description("Initialize a new TrellisVCS repository in
   console.log(`  ${source_default.dim("Ops:")}            ${opsCount} initial operations scanned`);
   console.log(`  ${source_default.dim("Config:")}         .trellis/config.json`);
   console.log(`  ${source_default.dim("Op log:")}         .trellis/ops.json`);
-  console.log(`  ${source_default.dim("Graph DB:")}       .trellis/graph.db`);
   console.log(`  ${source_default.dim("Agent context:")}  .trellis/agents/AGENTS.md`);
   const preInfer = await inferProjectContext(rootPath);
   if (preInfer.domain) {
@@ -5936,8 +6006,7 @@ program2.command("init").description("Initialize a new TrellisVCS repository in
   console.log(source_default.dim("The causal stream is now active. Every file change will be tracked."));
 });
 program2.command("seed").description("Refresh agent context files with current project state").option("-p, --path <path>", "Repository path", ".").option("--ide <ide>", "IDE to update (cursor, windsurf, claude, copilot)", "none").option("-f, --force", "Force rewrite even if files do not exist", false).action(async (opts) => {
-  const rootPath = resolve(opts.path);
-  requireRepo(rootPath);
+  const rootPath = resolveRepoRoot(opts.path);
   const ide = opts.ide || "none";
   const force = opts.force || false;
   console.log(source_default.dim("Seeding agent context..."));
@@ -5954,8 +6023,7 @@ program2.command("seed").description("Refresh agent context files with current p
   }
 });
 program2.command("repair").description("Attempt to repair a corrupted .trellis/ops.json file").option("-p, --path <path>", "Repository path", ".").action((opts) => {
-  const rootPath = resolve(opts.path);
-  requireRepo(rootPath);
+  const rootPath = resolveRepoRoot(opts.path);
   console.log(source_default.yellow("Attempting to repair ops.json..."));
   const result = TrellisVcsEngine.repair(rootPath);
   if (result.lost === -1) {
@@ -5967,11 +6035,7 @@ program2.command("repair").description("Attempt to repair a corrupted .trellis/o
   }
 });
 program2.command("status").description("Show current repository status").option("-p, --path <path>", "Repository path", ".").action(async (opts) => {
-  const rootPath = resolve(opts.path);
-  if (!TrellisVcsEngine.isRepo(rootPath)) {
-    console.log(source_default.red("Not a TrellisVCS repository. Run `trellis init` first."));
-    process.exit(1);
-  }
+  const rootPath = resolveRepoRoot(opts.path);
   const engine = new TrellisVcsEngine({ rootPath });
   engine.open();
   const st = engine.status();
@@ -6001,11 +6065,7 @@ program2.command("status").description("Show current repository status").option(
   }
 });
 program2.command("log").description("Show operation history").option("-p, --path <path>", "Repository path", ".").option("-n, --limit <n>", "Number of ops to show", "20").option("-f, --file <file>", "Filter by file path").action(async (opts) => {
-  const rootPath = resolve(opts.path);
-  if (!TrellisVcsEngine.isRepo(rootPath)) {
-    console.log(source_default.red("Not a TrellisVCS repository. Run `trellis init` first."));
-    process.exit(1);
-  }
+  const rootPath = resolveRepoRoot(opts.path);
   const engine = new TrellisVcsEngine({ rootPath });
   engine.open();
   const ops = engine.log({
@@ -6028,11 +6088,7 @@ program2.command("log").description("Show operation history").option("-p, --path
   }
 });
 program2.command("files").description("List all tracked files").option("-p, --path <path>", "Repository path", ".").action(async (opts) => {
-  const rootPath = resolve(opts.path);
-  if (!TrellisVcsEngine.isRepo(rootPath)) {
-    console.log(source_default.red("Not a TrellisVCS repository. Run `trellis init` first."));
-    process.exit(1);
-  }
+  const rootPath = resolveRepoRoot(opts.path);
   const engine = new TrellisVcsEngine({ rootPath });
   engine.open();
   const files = engine.trackedFiles();
@@ -6048,11 +6104,7 @@ program2.command("files").description("List all tracked files").option("-p, --pa
   }
 });
 program2.command("watch").description("Start file watcher (foreground, Ctrl+C to stop)").option("-p, --path <path>", "Repository path", ".").action(async (opts) => {
-  const rootPath = resolve(opts.path);
-  if (!TrellisVcsEngine.isRepo(rootPath)) {
-    console.log(source_default.red("Not a TrellisVCS repository. Run `trellis init` first."));
-    process.exit(1);
-  }
+  const rootPath = resolveRepoRoot(opts.path);
   const engine = new TrellisVcsEngine({ rootPath });
   engine.open();
   console.log(source_default.green("\u2713 Watching for changes\u2026") + source_default.dim(" (Ctrl+C to stop)"));
@@ -6067,8 +6119,8 @@ program2.command("watch").description("Start file watcher (foreground, Ctrl+C to
   });
 });
 program2.command("import").description("Import from an existing Git repository").requiredOption("--from <path>", "Path to the Git repository to import from").option("-p, --path <path>", "Target TrellisVCS repository path", ".").action(async (opts) => {
-  const from = resolve(opts.from);
-  const to = resolve(opts.path);
+  const from = resolve2(opts.from);
+  const to = resolve2(opts.path);
   console.log(source_default.dim(`Importing from Git: ${from}`));
   console.log(source_default.dim(`Target: ${to}`));
   console.log();
@@ -6103,12 +6155,8 @@ Import failed: ${err.message}`));
   }
 });
 program2.command("export").description("Export milestones to a Git repository").requiredOption("--to <path>", "Path to the target Git repository").option("-p, --path <path>", "Source TrellisVCS repository path", ".").option("--author-name <name>", "Author name for Git commits").option("--author-email <email>", "Author email for Git commits").action(async (opts) => {
-  const from = resolve(opts.path);
-  const to = resolve(opts.to);
-  if (!TrellisVcsEngine.isRepo(from)) {
-    console.error(source_default.red("Not a TrellisVCS repository. Run `trellis init` first."));
-    process.exit(1);
-  }
+  const from = resolveRepoRoot(opts.path);
+  const to = resolve2(opts.to);
   console.log(source_default.dim(`Exporting from: ${from}`));
   console.log(source_default.dim(`Target Git repo: ${to}`));
   console.log();
@@ -6141,11 +6189,7 @@ Export failed: ${err.message}`));
   }
 });
 program2.command("branch").description("Manage branches").argument("[name]", "Branch name to create or switch to").option("-d, --delete <name>", "Delete a branch").option("-l, --list", "List all branches").option("-p, --path <path>", "Repository path", ".").action(async (name, opts) => {
-  const rootPath = resolve(opts.path);
-  if (!TrellisVcsEngine.isRepo(rootPath)) {
-    console.error(source_default.red("Not a TrellisVCS repository. Run `trellis init` first."));
-    process.exit(1);
-  }
+  const rootPath = resolveRepoRoot(opts.path);
   const engine = new TrellisVcsEngine({ rootPath });
   engine.open();
   if (opts.delete) {
@@ -6196,11 +6240,7 @@ program2.command("branch").description("Manage branches").argument("[name]", "Br
   }
 });
 program2.command("milestone").description("Create or list milestones").argument("[action]", '"create" or "list" (default: list)').option("-m, --message <message>", "Milestone message").option("--from <hash>", "Start op hash for the milestone range").option("--to <hash>", "End op hash for the milestone range").option("-p, --path <path>", "Repository path", ".").action(async (action, opts) => {
-  const rootPath = resolve(opts.path);
-  if (!TrellisVcsEngine.isRepo(rootPath)) {
-    console.error(source_default.red("Not a TrellisVCS repository. Run `trellis init` first."));
-    process.exit(1);
-  }
+  const rootPath = resolveRepoRoot(opts.path);
   const engine = new TrellisVcsEngine({ rootPath });
   engine.open();
   if (action === "create") {
@@ -6241,11 +6281,7 @@ program2.command("milestone").description("Create or list milestones").argument(
   }
 });
 program2.command("checkpoint").description("Create or list checkpoints").argument("[action]", '"create" or "list" (default: list)').option("-p, --path <path>", "Repository path", ".").action(async (action, opts) => {
-  const rootPath = resolve(opts.path);
-  if (!TrellisVcsEngine.isRepo(rootPath)) {
-    console.error(source_default.red("Not a TrellisVCS repository. Run `trellis init` first."));
-    process.exit(1);
-  }
+  const rootPath = resolveRepoRoot(opts.path);
   const engine = new TrellisVcsEngine({ rootPath });
   engine.open();
   if (action === "create") {
@@ -6273,11 +6309,7 @@ program2.command("checkpoint").description("Create or list checkpoints").argumen
   }
 });
 program2.command("diff").description("Show file-level diff between two points in history").argument("[from]", "Starting op hash or milestone ID").argument("[to]", "Ending op hash (default: current head)").option("-p, --path <path>", "Repository path", ".").option("--stat", "Show only summary stats").action((from, to, opts) => {
-  const rootPath = resolve(opts.path);
-  if (!TrellisVcsEngine.isRepo(rootPath)) {
-    console.error(source_default.red("Not a TrellisVCS repository. Run `trellis init` first."));
-    process.exit(1);
-  }
+  const rootPath = resolveRepoRoot(opts.path);
   const engine = new TrellisVcsEngine({ rootPath });
   engine.open();
   let result;
@@ -6335,11 +6367,7 @@ program2.command("diff").description("Show file-level diff between two points in
   }
 });
 program2.command("merge").description("Merge a branch into the current branch").argument("<branch>", "Source branch to merge").option("-p, --path <path>", "Repository path", ".").option("--dry-run", "Preview merge without applying changes").action((branch, opts) => {
-  const rootPath = resolve(opts.path);
-  if (!TrellisVcsEngine.isRepo(rootPath)) {
-    console.error(source_default.red("Not a TrellisVCS repository. Run `trellis init` first."));
-    process.exit(1);
-  }
+  const rootPath = resolveRepoRoot(opts.path);
   const engine = new TrellisVcsEngine({ rootPath });
   engine.open();
   const result = engine.mergeBranch(branch);
@@ -6365,13 +6393,12 @@ program2.command("merge").description("Merge a branch into the current branch").
   }
 });
 program2.command("parse").description("Parse a file into AST-level semantic entities").argument("<file>", "File to parse").option("-p, --path <path>", "Repository path", ".").action((file, opts) => {
-  const rootPath = resolve(opts.path);
+  const rootPath = resolveRepoRoot(opts.path);
   const engine = new TrellisVcsEngine({ rootPath });
-  if (TrellisVcsEngine.isRepo(rootPath))
-    engine.open();
-  const { readFileSync: readFileSync4 } = __require("fs");
-  const filePath = resolve(file);
-  const content = readFileSync4(filePath, "utf-8");
+  engine.open();
+  const { readFileSync: readFileSync5 } = __require("fs");
+  const filePath = resolve2(file);
+  const content = readFileSync5(filePath, "utf-8");
   const result = engine.parseFile(content, file);
   if (!result) {
     console.log(source_default.dim(`No parser available for: ${file}`));
@@ -6403,13 +6430,12 @@ program2.command("parse").description("Parse a file into AST-level semantic enti
   }
 });
 program2.command("sdiff").description("Show semantic diff between two versions of a file").argument("<fileA>", "Old version of the file").argument("<fileB>", "New version of the file").option("-p, --path <path>", "Repository path", ".").action((fileA, fileB, opts) => {
-  const rootPath = resolve(opts.path);
+  const rootPath = resolveRepoRoot(opts.path);
   const engine = new TrellisVcsEngine({ rootPath });
-  if (TrellisVcsEngine.isRepo(rootPath))
-    engine.open();
-  const { readFileSync: readFileSync4 } = __require("fs");
-  const oldContent = readFileSync4(resolve(fileA), "utf-8");
-  const newContent = readFileSync4(resolve(fileB), "utf-8");
+  engine.open();
+  const { readFileSync: readFileSync5 } = __require("fs");
+  const oldContent = readFileSync5(resolve2(fileA), "utf-8");
+  const newContent = readFileSync5(resolve2(fileB), "utf-8");
   const patches = engine.semanticDiff(oldContent, newContent, fileA);
   if (patches.length === 0) {
     console.log(source_default.dim("No semantic differences."));
@@ -6455,11 +6481,7 @@ program2.command("sdiff").description("Show semantic diff between two versions o
   }
 });
 program2.command("sync").description("Sync operations with another TrellisVCS repository").argument("[action]", '"push", "pull", "status", or "reconcile" (default: status)').option("-p, --path <path>", "Local repository path", ".").option("--remote <remote>", "Remote repository path").action((action, opts) => {
-  const rootPath = resolve(opts.path);
-  if (!TrellisVcsEngine.isRepo(rootPath)) {
-    console.error(source_default.red("Not a TrellisVCS repository. Run `trellis init` first."));
-    process.exit(1);
-  }
+  const rootPath = resolveRepoRoot(opts.path);
   const engine = new TrellisVcsEngine({ rootPath });
   engine.open();
   const ops = engine.getOps();
@@ -6472,7 +6494,7 @@ program2.command("sync").description("Sync operations with another TrellisVCS re
     return;
   }
   if (action === "reconcile" && opts.remote) {
-    const remotePath = resolve(opts.remote);
+    const remotePath = resolve2(opts.remote);
     if (!TrellisVcsEngine.isRepo(remotePath)) {
       console.error(source_default.red(`Not a TrellisVCS repository: ${remotePath}`));
       process.exit(1);
@@ -6502,11 +6524,7 @@ program2.command("sync").description("Sync operations with another TrellisVCS re
   console.log(source_default.dim("Full peer sync requires a transport layer (coming soon)."));
 });
 program2.command("garden").description("Explore the Idea Garden \u2014 abandoned work clusters").argument("[action]", '"list", "show <id>", "search", "revive <id>", or "stats" (default: list)').argument("[id]", "Cluster ID (for show/revive)").option("-p, --path <path>", "Repository path", ".").option("-f, --file <file>", "Filter by file path").option("-k, --keyword <keyword>", "Filter by keyword").option("-s, --status <status>", "Filter by status (abandoned|draft|revived)").option("-n, --limit <n>", "Max results", parseInt).action((action, id, opts) => {
-  const rootPath = resolve(opts.path);
-  if (!TrellisVcsEngine.isRepo(rootPath)) {
-    console.error(source_default.red("Not a TrellisVCS repository. Run `trellis init` first."));
-    process.exit(1);
-  }
+  const rootPath = resolveRepoRoot(opts.path);
   const engine = new TrellisVcsEngine({ rootPath });
   engine.open();
   const garden = engine.garden();
@@ -6663,9 +6681,8 @@ function formatCriterionStatus(status) {
   }
 }
 var issueCmd = program2.command("issue").description("Manage issues (task tracking)");
-issueCmd.command("create").description("Create a new issue").requiredOption("-t, --title <title>", "Issue title").option("-P, --priority <priority>", "Priority: critical, high, medium, low", "medium").option("-l, --labels <labels>", "Comma-separated labels").option("--assignee <agentId>", "Agent to assign").option("--parent <id>", "Parent issue ID (for sub-tasks)").option("-d, --desc <description>", "Short description").option("-S, --status <status>", "Initial status: backlog (default) or queue", "backlog").option("--ac <criteria...>", 'Acceptance criteria. Prefix with "test:" for test commands').option("-p, --path <path>", "Repository path", ".").action(async (opts) => {
-  const rootPath = resolve(opts.path);
-  requireRepo(rootPath);
+issueCmd.command("create").description("Create a new issue").requiredOption("-t, --title <title>", "Issue title").option("-P, --priority <priority>", "Priority: critical, high, medium, low", "medium").option("-l, --labels <labels>", "Comma-separated labels").option("--assignee <agentId>", "Agent to assign").option("--parent <id>", "Parent issue ID (for sub-tasks)").option("-d, --desc <description>", "Short description").option("--description <description>", "Alias for --desc").option("-S, --status <status>", "Initial status: backlog (default) or queue", "backlog").option("--ac <criteria...>", 'Acceptance criteria. Prefix with "test:" for test commands').option("-p, --path <path>", "Repository path", ".").action(async (opts) => {
+  const rootPath = resolveRepoRoot(opts.path);
   const engine = new TrellisVcsEngine({ rootPath });
   engine.open();
   const labels = opts.labels ? opts.labels.split(",").map((l) => l.trim()) : undefined;
@@ -6680,7 +6697,7 @@ issueCmd.command("create").description("Create a new issue").requiredOption("-t,
     labels,
     assignee: opts.assignee,
     parentId: opts.parent,
-    description: opts.desc,
+    description: opts.desc ?? opts.description,
     status: opts.status,
     criteria
   });
@@ -6699,8 +6716,7 @@ issueCmd.command("create").description("Create a new issue").requiredOption("-t,
   }
 });
 issueCmd.command("list").description("List issues").option("--status <status>", "Filter by status: backlog, queue, in_progress, paused, closed").option("--label <label>", "Filter by label").option("--assignee <agentId>", "Filter by assignee").option("--parent <id>", "Filter by parent issue").option("-p, --path <path>", "Repository path", ".").action((opts) => {
-  const rootPath = resolve(opts.path);
-  requireRepo(rootPath);
+  const rootPath = resolveRepoRoot(opts.path);
   const engine = new TrellisVcsEngine({ rootPath });
   engine.open();
   const issues = engine.listIssues({
@@ -6725,8 +6741,7 @@ issueCmd.command("list").description("List issues").option("--status <status>",
   }
 });
 issueCmd.command("show").description("Show issue details").argument("<id>", "Issue ID (e.g. TRL-1)").option("-p, --path <path>", "Repository path", ".").action((id, opts) => {
-  const rootPath = resolve(opts.path);
-  requireRepo(rootPath);
+  const rootPath = resolveRepoRoot(opts.path);
   const engine = new TrellisVcsEngine({ rootPath });
   engine.open();
   const issue = engine.getIssue(id);
@@ -6780,8 +6795,7 @@ issueCmd.command("show").description("Show issue details").argument("<id>", "Iss
   }
 });
 issueCmd.command("start").description("Start working on an issue (creates branch, auto-assigns)").argument("<id>", "Issue ID").option("-p, --path <path>", "Repository path", ".").action(async (id, opts) => {
-  const rootPath = resolve(opts.path);
-  requireRepo(rootPath);
+  const rootPath = resolveRepoRoot(opts.path);
   const engine = new TrellisVcsEngine({ rootPath });
   engine.open();
   const op = await engine.startIssue(id);
@@ -6795,8 +6809,7 @@ issueCmd.command("start").description("Start working on an issue (creates branch
   }
 });
 issueCmd.command("pause").description("Pause an in-progress issue (switches to default branch)").argument("<id>", "Issue ID").requiredOption("-n, --note <note>", "Why paused and what must happen before resuming").option("-p, --path <path>", "Repository path", ".").action(async (id, opts) => {
-  const rootPath = resolve(opts.path);
-  requireRepo(rootPath);
+  const rootPath = resolveRepoRoot(opts.path);
   const engine = new TrellisVcsEngine({ rootPath });
   engine.open();
   await engine.pauseIssue(id, opts.note);
@@ -6805,8 +6818,7 @@ issueCmd.command("pause").description("Pause an in-progress issue (switches to d
   console.log(`  ${source_default.dim("Switched to:")} ${engine.getCurrentBranch()}`);
 });
 issueCmd.command("resume").description("Resume a paused issue (switches to issue branch)").argument("<id>", "Issue ID").option("-p, --path <path>", "Repository path", ".").action(async (id, opts) => {
-  const rootPath = resolve(opts.path);
-  requireRepo(rootPath);
+  const rootPath = resolveRepoRoot(opts.path);
   const engine = new TrellisVcsEngine({ rootPath });
   engine.open();
   await engine.resumeIssue(id);
@@ -6817,23 +6829,22 @@ issueCmd.command("resume").description("Resume a paused issue (switches to issue
   }
 });
 issueCmd.command("triage").description("Move a backlog issue to queue (ready to start)").argument("<id>", "Issue ID").option("-p, --path <path>", "Repository path", ".").action(async (id, opts) => {
-  const rootPath = resolve(opts.path);
-  requireRepo(rootPath);
+  const rootPath = resolveRepoRoot(opts.path);
   const engine = new TrellisVcsEngine({ rootPath });
   engine.open();
   await engine.triageIssue(id);
   console.log(source_default.green(`\u2713 Triaged ${source_default.bold(id)} \u2192 queue`));
 });
-issueCmd.command("update").description("Update issue metadata").argument("<id>", "Issue ID").option("--title <title>", "New title").option("-d, --desc <description>", "Short description").option("--status <status>", "New status: backlog, queue, in_progress, paused, closed").option("-P, --priority <priority>", "Priority: critical, high, medium, low").option("-l, --labels <labels>", "Comma-separated labels").option("--assignee <agentId>", "Agent to assign").option("-p, --path <path>", "Repository path", ".").action(async (id, opts) => {
-  const rootPath = resolve(opts.path);
-  requireRepo(rootPath);
+issueCmd.command("update").description("Update issue metadata").argument("<id>", "Issue ID").option("--title <title>", "New title").option("-d, --desc <description>", "Short description").option("--description <description>", "Alias for --desc").option("--status <status>", "New status: backlog, queue, in_progress, paused, closed").option("-P, --priority <priority>", "Priority: critical, high, medium, low").option("-l, --labels <labels>", "Comma-separated labels").option("--assignee <agentId>", "Agent to assign").option("-p, --path <path>", "Repository path", ".").action(async (id, opts) => {
+  const rootPath = resolveRepoRoot(opts.path);
   const engine = new TrellisVcsEngine({ rootPath });
   engine.open();
   const updates = {};
   if (opts.title !== undefined)
     updates.title = opts.title;
-  if (opts.desc !== undefined)
-    updates.description = opts.desc;
+  const desc = opts.desc ?? opts.description;
+  if (desc !== undefined)
+    updates.description = desc;
   if (opts.status !== undefined)
     updates.status = opts.status;
   if (opts.priority !== undefined)
@@ -6847,24 +6858,21 @@ issueCmd.command("update").description("Update issue metadata").argument("<id>",
   console.log(source_default.green(`\u2713 Updated ${source_default.bold(id)}`));
 });
 issueCmd.command("describe").description("Set an issue description").argument("<id>", "Issue ID").argument("<description>", "Short description text").option("-p, --path <path>", "Repository path", ".").action(async (id, description, opts) => {
-  const rootPath = resolve(opts.path);
-  requireRepo(rootPath);
+  const rootPath = resolveRepoRoot(opts.path);
   const engine = new TrellisVcsEngine({ rootPath });
   engine.open();
   await engine.updateIssue(id, { description });
   console.log(source_default.green(`\u2713 Description set for ${source_default.bold(id)}`));
 });
 issueCmd.command("assign").description("Assign an issue to an agent").argument("<id>", "Issue ID").requiredOption("--to <agentId>", "Agent ID to assign").option("-p, --path <path>", "Repository path", ".").action(async (id, opts) => {
-  const rootPath = resolve(opts.path);
-  requireRepo(rootPath);
+  const rootPath = resolveRepoRoot(opts.path);
   const engine = new TrellisVcsEngine({ rootPath });
   engine.open();
   await engine.assignIssue(id, opts.to);
   console.log(source_default.green(`\u2713 Assigned ${source_default.bold(id)} \u2192 ${opts.to}`));
 });
 issueCmd.command("ac").description("Add acceptance criterion to an issue").argument("<id>", "Issue ID").argument("<description>", "Criterion description").option("--test <command>", "Shell command to validate (exit 0 = pass)").option("-p, --path <path>", "Repository path", ".").action(async (id, description, opts) => {
-  const rootPath = resolve(opts.path);
-  requireRepo(rootPath);
+  const rootPath = resolveRepoRoot(opts.path);
   const engine = new TrellisVcsEngine({ rootPath });
   engine.open();
   await engine.addCriterion(id, description, opts.test);
@@ -6872,24 +6880,21 @@ issueCmd.command("ac").description("Add acceptance criterion to an issue").argum
   console.log(source_default.green(`\u2713 Added criterion to ${source_default.bold(id)}: ${description}${cmdNote}`));
 });
 issueCmd.command("ac-pass").description("Manually mark an acceptance criterion as passed").argument("<id>", "Issue ID").argument("<index>", "Criterion number (1-based)").option("-p, --path <path>", "Repository path", ".").action(async (id, index, opts) => {
-  const rootPath = resolve(opts.path);
-  requireRepo(rootPath);
+  const rootPath = resolveRepoRoot(opts.path);
   const engine = new TrellisVcsEngine({ rootPath });
   engine.open();
   await engine.setCriterionStatus(id, parseInt(index, 10), "passed");
   console.log(source_default.green(`\u2713 Criterion #${index} on ${source_default.bold(id)} marked as passed`));
 });
 issueCmd.command("ac-fail").description("Manually mark an acceptance criterion as failed").argument("<id>", "Issue ID").argument("<index>", "Criterion number (1-based)").option("-p, --path <path>", "Repository path", ".").action(async (id, index, opts) => {
-  const rootPath = resolve(opts.path);
-  requireRepo(rootPath);
+  const rootPath = resolveRepoRoot(opts.path);
   const engine = new TrellisVcsEngine({ rootPath });
   engine.open();
   await engine.setCriterionStatus(id, parseInt(index, 10), "failed");
   console.log(source_default.red(`\u2717 Criterion #${index} on ${source_default.bold(id)} marked as failed`));
 });
 issueCmd.command("check").description("Run acceptance criteria for an issue").argument("<id>", "Issue ID").option("-p, --path <path>", "Repository path", ".").action(async (id, opts) => {
-  const rootPath = resolve(opts.path);
-  requireRepo(rootPath);
+  const rootPath = resolveRepoRoot(opts.path);
   const engine = new TrellisVcsEngine({ rootPath });
   engine.open();
   console.log(source_default.bold(`Running criteria for ${id}...
@@ -6924,8 +6929,7 @@ issueCmd.command("check").description("Run acceptance criteria for an issue").ar
   }
 });
 issueCmd.command("close").description("Close an issue (requires all criteria pass + --confirm)").argument("<id>", "Issue ID").option("--confirm", "Confirm closure after criteria pass").option("-p, --path <path>", "Repository path", ".").action(async (id, opts) => {
-  const rootPath = resolve(opts.path);
-  requireRepo(rootPath);
+  const rootPath = resolveRepoRoot(opts.path);
   const engine = new TrellisVcsEngine({ rootPath });
   engine.open();
   try {
@@ -6947,32 +6951,28 @@ issueCmd.command("close").description("Close an issue (requires all criteria pas
   }
 });
 issueCmd.command("reopen").description("Reopen a closed issue").argument("<id>", "Issue ID").option("-p, --path <path>", "Repository path", ".").action(async (id, opts) => {
-  const rootPath = resolve(opts.path);
-  requireRepo(rootPath);
+  const rootPath = resolveRepoRoot(opts.path);
   const engine = new TrellisVcsEngine({ rootPath });
   engine.open();
   await engine.reopenIssue(id);
   console.log(source_default.green(`\u2713 Issue ${source_default.bold(id)} reopened`));
 });
 issueCmd.command("block").description("Mark an issue as blocked by another issue").argument("<id>", "Issue ID to block").argument("<blockedBy>", "Issue ID that blocks it").option("-p, --path <path>", "Repository path", ".").action(async (id, blockedBy, opts) => {
-  const rootPath = resolve(opts.path);
-  requireRepo(rootPath);
+  const rootPath = resolveRepoRoot(opts.path);
   const engine = new TrellisVcsEngine({ rootPath });
   engine.open();
   await engine.blockIssue(id, blockedBy);
   console.log(source_default.yellow(`\uD83D\uDD12 ${source_default.bold(id)} is now blocked by ${source_default.bold(blockedBy)}`));
 });
 issueCmd.command("unblock").description("Remove a blocking relationship").argument("<id>", "Blocked issue ID").argument("<blockedBy>", "Blocking issue ID to remove").option("-p, --path <path>", "Repository path", ".").action(async (id, blockedBy, opts) => {
-  const rootPath = resolve(opts.path);
-  requireRepo(rootPath);
+  const rootPath = resolveRepoRoot(opts.path);
   const engine = new TrellisVcsEngine({ rootPath });
   engine.open();
   await engine.unblockIssue(id, blockedBy);
   console.log(source_default.green(`\uD83D\uDD13 ${source_default.bold(id)} is no longer blocked by ${source_default.bold(blockedBy)}`));
 });
 issueCmd.command("active").description("Show all active (in-progress) issues").option("-p, --path <path>", "Repository path", ".").action((opts) => {
-  const rootPath = resolve(opts.path);
-  requireRepo(rootPath);
+  const rootPath = resolveRepoRoot(opts.path);
   const engine = new TrellisVcsEngine({ rootPath });
   engine.open();
   const active = engine.getActiveIssues();
@@ -6989,8 +6989,7 @@ issueCmd.command("active").description("Show all active (in-progress) issues").o
   }
 });
 issueCmd.command("readiness").description("Check if all issues are complete (no queue, paused, or in-progress)").option("-p, --path <path>", "Repository path", ".").action((opts) => {
-  const rootPath = resolve(opts.path);
-  requireRepo(rootPath);
+  const rootPath = resolveRepoRoot(opts.path);
   const engine = new TrellisVcsEngine({ rootPath });
   engine.open();
   const result = engine.checkCompletionReadiness();
@@ -7001,8 +7000,7 @@ issueCmd.command("readiness").description("Check if all issues are complete (no
 });
 var decisionCmd = program2.command("decision").description("Manage decision traces");
 decisionCmd.command("list").description("List decision traces").option("-p, --path <path>", "Repository path", ".").option("-t, --tool <pattern>", 'Filter by tool name pattern (e.g. "trellis_issue_*")').option("-e, --entity <id>", "Filter by related entity ID").option("-n, --limit <n>", "Max results", "20").action((opts) => {
-  const rootPath = resolve(opts.path);
-  requireRepo(rootPath);
+  const rootPath = resolveRepoRoot(opts.path);
   const engine = new TrellisVcsEngine({ rootPath });
   engine.open();
   const decisions = engine.queryDecisions({
@@ -7023,8 +7021,7 @@ decisionCmd.command("list").description("List decision traces").option("-p, --pa
   }
 });
 decisionCmd.command("show").description("Show full details of a decision trace").argument("<id>", "Decision ID (e.g. DEC-1)").option("-p, --path <path>", "Repository path", ".").action((id, opts) => {
-  const rootPath = resolve(opts.path);
-  requireRepo(rootPath);
+  const rootPath = resolveRepoRoot(opts.path);
   const engine = new TrellisVcsEngine({ rootPath });
   engine.open();
   const d = engine.getDecision(id);
@@ -7051,8 +7048,7 @@ decisionCmd.command("show").description("Show full details of a decision trace")
   }
 });
 decisionCmd.command("chain").description("Trace all decisions that affected a given entity").argument("<entityId>", 'Entity ID (e.g. "issue:TRL-5", "file:src/engine.ts")').option("-p, --path <path>", "Repository path", ".").action((entityId, opts) => {
-  const rootPath = resolve(opts.path);
-  requireRepo(rootPath);
+  const rootPath = resolveRepoRoot(opts.path);
   const engine = new TrellisVcsEngine({ rootPath });
   engine.open();
   const chain = engine.getDecisionChain(entityId);
@@ -7070,7 +7066,7 @@ decisionCmd.command("chain").description("Trace all decisions that affected a gi
   }
 });
 program2.command("identity").description("Manage local identity (Ed25519 key pair)").argument("[action]", '"init" or "show" (default: show)').option("-p, --path <path>", "Repository path", ".").option("--name <name>", "Display name for new identity").option("--email <email>", "Email for new identity").action((action, opts) => {
-  const rootPath = resolve(opts.path);
+  const rootPath = resolve2(opts.path);
   const trellisDir = join6(rootPath, ".trellis");
   if (action === "init") {
     if (hasIdentity(trellisDir)) {
@@ -7108,14 +7104,10 @@ program2.command("identity").description("Manage local identity (Ed25519 key pai
   console.log(`  ${source_default.dim("Created:")}    ${pub.createdAt}`);
 });
 program2.command("refs").description("List wiki-link references in files or find backlinks").argument("[file]", "File to list outgoing refs for").option("-p, --path <path>", "Repository path", ".").option("--backlinks <entity>", "Show all files referencing an entity (e.g. TRL-5)").option("--broken", "List all broken and stale references").option("--stats", "Show reference index statistics").action((file, opts) => {
-  const rootPath = resolve(opts.path);
-  if (!TrellisVcsEngine.isRepo(rootPath)) {
-    console.error(source_default.red("Not a TrellisVCS repository. Run `trellis init` first."));
-    process.exit(1);
-  }
+  const rootPath = resolveRepoRoot(opts.path);
   const engine = new TrellisVcsEngine({ rootPath });
   engine.open();
-  const { readFileSync: readFileSync4 } = __require("fs");
+  const { readFileSync: readFileSync5 } = __require("fs");
   const {
     parseFileRefs,
     buildRefIndex: buildRefIndex2,
@@ -7135,7 +7127,7 @@ program2.command("refs").description("List wiki-link references in files or find
   for (const f of trackedFiles) {
     try {
       const absPath = join6(rootPath, f.path);
-      const content = readFileSync4(absPath, "utf-8");
+      const content = readFileSync5(absPath, "utf-8");
       fileContents.push({ path: f.path, content });
     } catch {}
   }
@@ -7247,11 +7239,7 @@ program2.command("refs").description("List wiki-link references in files or find
   }
 });
 program2.command("search").description("Semantic search across all embedded content").argument("<query>", "Natural language search query").option("-p, --path <path>", "Repository path", ".").option("-l, --limit <n>", "Max results", "10").option("-t, --type <types>", "Filter by chunk type(s), comma-separated (issue_title,issue_desc,milestone_msg,markdown,code_entity,doc_comment,summary_md)").action(async (query, opts) => {
-  const rootPath = resolve(opts.path);
-  if (!TrellisVcsEngine.isRepo(rootPath)) {
-    console.error(source_default.red("Not a TrellisVCS repository. Run `trellis init` first."));
-    process.exit(1);
-  }
+  const rootPath = resolveRepoRoot(opts.path);
   const engine = new TrellisVcsEngine({ rootPath });
   engine.open();
   const { EmbeddingManager } = (init_embeddings(), __toCommonJS(exports_embeddings));
@@ -7285,11 +7273,7 @@ program2.command("search").description("Semantic search across all embedded cont
   }
 });
 program2.command("reindex").description("Rebuild the semantic embedding index").option("-p, --path <path>", "Repository path", ".").action(async (opts) => {
-  const rootPath = resolve(opts.path);
-  if (!TrellisVcsEngine.isRepo(rootPath)) {
-    console.error(source_default.red("Not a TrellisVCS repository. Run `trellis init` first."));
-    process.exit(1);
-  }
+  const rootPath = resolveRepoRoot(opts.path);
   const engine = new TrellisVcsEngine({ rootPath });
   engine.open();
   const { EmbeddingManager } = (init_embeddings(), __toCommonJS(exports_embeddings));
@@ -7306,11 +7290,7 @@ program2.command("reindex").description("Rebuild the semantic embedding index").
   }
 });
 program2.command("ui").description("Launch the interactive graph explorer in your browser").option("-p, --path <path>", "Repository path", ".").option("--port <port>", "Server port", "3333").option("--no-open", "Do not auto-open browser").action(async (opts) => {
-  const rootPath = resolve(opts.path);
-  if (!TrellisVcsEngine.isRepo(rootPath)) {
-    console.error(source_default.red("Not a TrellisVCS repository. Run `trellis init` first."));
-    process.exit(1);
-  }
+  const rootPath = resolveRepoRoot(opts.path);
   const { startUIServer: startUIServer2 } = (init_server(), __toCommonJS(exports_server));
   const port = parseInt(opts.port, 10) || 3000;
   try {
@@ -7348,8 +7328,7 @@ async function bootKernel(rootPath) {
 }
 var entityCmd = program2.command("entity").description("Manage graph entities (generic CRUD)");
 entityCmd.command("create").description("Create a new entity in the graph").requiredOption("-i, --id <id>", 'Entity ID (e.g. "project:my-app")').requiredOption("-t, --type <type>", 'Entity type (e.g. "Project", "User")').option("-a, --attr <attrs...>", "Attributes as key=value pairs").option("-p, --path <path>", "Repository path", ".").action(async (opts) => {
-  const rootPath = resolve(opts.path);
-  requireRepo(rootPath);
+  const rootPath = resolveRepoRoot(opts.path);
   const kernel = await bootKernel(rootPath);
   try {
     const attrs = {};
@@ -7379,8 +7358,7 @@ entityCmd.command("create").description("Create a new entity in the graph").requ
   }
 });
 entityCmd.command("get").description("Get an entity by ID").argument("<id>", "Entity ID").option("-p, --path <path>", "Repository path", ".").option("--json", "Output as JSON").action(async (id, opts) => {
-  const rootPath = resolve(opts.path);
-  requireRepo(rootPath);
+  const rootPath = resolveRepoRoot(opts.path);
   const kernel = await bootKernel(rootPath);
   try {
     const entity = kernel.getEntity(id);
@@ -7421,8 +7399,7 @@ entityCmd.command("get").description("Get an entity by ID").argument("<id>", "En
   }
 });
 entityCmd.command("update").description("Update attributes on an existing entity").argument("<id>", "Entity ID").requiredOption("-a, --attr <attrs...>", "Attributes as key=value pairs").option("-p, --path <path>", "Repository path", ".").action(async (id, opts) => {
-  const rootPath = resolve(opts.path);
-  requireRepo(rootPath);
+  const rootPath = resolveRepoRoot(opts.path);
   const kernel = await bootKernel(rootPath);
   try {
     const updates = {};
@@ -7450,8 +7427,7 @@ entityCmd.command("update").description("Update attributes on an existing entity
   }
 });
 entityCmd.command("delete").description("Delete an entity and all its facts/links").argument("<id>", "Entity ID").option("-p, --path <path>", "Repository path", ".").action(async (id, opts) => {
-  const rootPath = resolve(opts.path);
-  requireRepo(rootPath);
+  const rootPath = resolveRepoRoot(opts.path);
   const kernel = await bootKernel(rootPath);
   try {
     const entity = kernel.getEntity(id);
@@ -7466,8 +7442,7 @@ entityCmd.command("delete").description("Delete an entity and all its facts/link
   }
 });
 entityCmd.command("list").description("List entities, optionally filtered by type").option("-t, --type <type>", "Filter by entity type").option("-f, --filter <filters...>", "Attribute filters as key=value").option("--json", "Output as JSON").option("-p, --path <path>", "Repository path", ".").action(async (opts) => {
-  const rootPath = resolve(opts.path);
-  requireRepo(rootPath);
+  const rootPath = resolveRepoRoot(opts.path);
   const kernel = await bootKernel(rootPath);
   try {
     let filters;
@@ -7519,8 +7494,7 @@ entityCmd.command("list").description("List entities, optionally filtered by typ
 });
 var factCmd = program2.command("fact").description("Add or remove individual facts on entities");
 factCmd.command("add").description("Add a fact to an entity").argument("<entity>", "Entity ID").argument("<attribute>", "Attribute name").argument("<value>", "Value").option("-p, --path <path>", "Repository path", ".").action(async (entity, attribute, value, opts) => {
-  const rootPath = resolve(opts.path);
-  requireRepo(rootPath);
+  const rootPath = resolveRepoRoot(opts.path);
   const kernel = await bootKernel(rootPath);
   try {
     let val = value;
@@ -7537,8 +7511,7 @@ factCmd.command("add").description("Add a fact to an entity").argument("<entity>
   }
 });
 factCmd.command("remove").description("Remove a fact from an entity").argument("<entity>", "Entity ID").argument("<attribute>", "Attribute name").argument("<value>", "Value to remove").option("-p, --path <path>", "Repository path", ".").action(async (entity, attribute, value, opts) => {
-  const rootPath = resolve(opts.path);
-  requireRepo(rootPath);
+  const rootPath = resolveRepoRoot(opts.path);
   const kernel = await bootKernel(rootPath);
   try {
     let val = value;
@@ -7555,8 +7528,7 @@ factCmd.command("remove").description("Remove a fact from an entity").argument("
   }
 });
 factCmd.command("query").description("Query facts by entity or attribute").option("-e, --entity <id>", "Filter by entity ID").option("-a, --attribute <attr>", "Filter by attribute").option("--json", "Output as JSON").option("-p, --path <path>", "Repository path", ".").action(async (opts) => {
-  const rootPath = resolve(opts.path);
-  requireRepo(rootPath);
+  const rootPath = resolveRepoRoot(opts.path);
   const kernel = await bootKernel(rootPath);
   try {
     const store = kernel.getStore();
@@ -7590,8 +7562,7 @@ factCmd.command("query").description("Query facts by entity or attribute").optio
 });
 var linkCmd = program2.command("link").description("Add or remove links between entities");
 linkCmd.command("add").description("Add a link between two entities").argument("<source>", "Source entity ID").argument("<attribute>", "Relationship attribute").argument("<target>", "Target entity ID").option("-p, --path <path>", "Repository path", ".").action(async (source, attribute, target, opts) => {
-  const rootPath = resolve(opts.path);
-  requireRepo(rootPath);
+  const rootPath = resolveRepoRoot(opts.path);
   const kernel = await bootKernel(rootPath);
   try {
     await kernel.addLink(source, attribute, target);
@@ -7601,8 +7572,7 @@ linkCmd.command("add").description("Add a link between two entities").argument("
   }
 });
 linkCmd.command("remove").description("Remove a link between two entities").argument("<source>", "Source entity ID").argument("<attribute>", "Relationship attribute").argument("<target>", "Target entity ID").option("-p, --path <path>", "Repository path", ".").action(async (source, attribute, target, opts) => {
-  const rootPath = resolve(opts.path);
-  requireRepo(rootPath);
+  const rootPath = resolveRepoRoot(opts.path);
   const kernel = await bootKernel(rootPath);
   try {
     await kernel.removeLink(source, attribute, target);
@@ -7612,8 +7582,7 @@ linkCmd.command("remove").description("Remove a link between two entities").argu
   }
 });
 linkCmd.command("query").description("Query links for an entity").option("-e, --entity <id>", "Entity ID").option("-a, --attribute <attr>", "Relationship attribute").option("--json", "Output as JSON").option("-p, --path <path>", "Repository path", ".").action(async (opts) => {
-  const rootPath = resolve(opts.path);
-  requireRepo(rootPath);
+  const rootPath = resolveRepoRoot(opts.path);
   const kernel = await bootKernel(rootPath);
   try {
     const store = kernel.getStore();
@@ -7648,8 +7617,7 @@ linkCmd.command("query").description("Query links for an entity").option("-e, --
   }
 });
 program2.command("query").description("Execute an EQL-S query against the graph").argument("<query>", 'EQL-S query string (or "find ?e where attr = value" shorthand)').option("-p, --path <path>", "Repository path", ".").option("--json", "Output as JSON").action(async (queryStr, opts) => {
-  const rootPath = resolve(opts.path);
-  requireRepo(rootPath);
+  const rootPath = resolveRepoRoot(opts.path);
   const kernel = await bootKernel(rootPath);
   try {
     const store = kernel.getStore();
@@ -7688,8 +7656,7 @@ ${result.count} result(s) in ${result.executionTime.toFixed(1)}ms`));
   }
 });
 program2.command("repl").description("Interactive EQL-S query shell").option("-p, --path <path>", "Repository path", ".").action(async (opts) => {
-  const rootPath = resolve(opts.path);
-  requireRepo(rootPath);
+  const rootPath = resolveRepoRoot(opts.path);
   const kernel = await bootKernel(rootPath);
   const store = kernel.getStore();
   const engine = new QueryEngine(store);
@@ -7867,8 +7834,7 @@ Relations:`));
   console.log(source_default.dim("Available types: " + registry.listEntityTypes().join(", ")));
 });
 ontologyCmd.command("validate").description("Validate all entities in the graph against registered ontologies").option("-p, --path <path>", "Repository path", ".").option("--strict", "Treat unknown types as errors").action(async (opts) => {
-  const rootPath = resolve(opts.path);
-  requireRepo(rootPath);
+  const rootPath = resolveRepoRoot(opts.path);
   const kernel = await bootKernel(rootPath);
   try {
     const registry = new OntologyRegistry;
@@ -7905,8 +7871,7 @@ ontologyCmd.command("validate").description("Validate all entities in the graph
   }
 });
 program2.command("ask").description("Natural language search over the graph (semantic search)").argument("<question>", "Natural language query").option("-p, --path <path>", "Repository path", ".").option("-n, --limit <n>", "Max results", "5").option("--json", "Output as JSON").option("--rag", "Output as RAG context (for LLM consumption)").action(async (question, opts) => {
-  const rootPath = resolve(opts.path);
-  requireRepo(rootPath);
+  const rootPath = resolveRepoRoot(opts.path);
   const dbPath = join6(rootPath, ".trellis", "embeddings.db");
   const vectorStore = new VectorStore(dbPath);
   try {
@@ -7995,12 +7960,12 @@ function formatRelativeTime(iso) {
 var db = program2.command("db").description("Trellis DB \u2014 use Trellis as an application database");
 db.command("init").description("Initialize a new Trellis DB in the current directory").option("-p, --path <path>", "Database directory", ".trellis-db").option("--port <port>", "Server port", "3000").option("--key <key>", "API key (auto-generated if omitted)").option("--jwt-secret <secret>", "JWT secret (auto-generated if omitted)").option("--multi-tenant", "Enable multi-tenancy (separate SQLite per tenant)").action(async (opts) => {
   const { writeConfig, defaultLocalConfig, hasConfig, configPath } = await import("../config-8hczw0rs.js");
-  const { resolve: resolve2 } = await import("path");
+  const { resolve: resolve3 } = await import("path");
   if (hasConfig(".")) {
     console.log(source_default.yellow(`Already initialized (${configPath(".")}). Use \`trellis db serve\` to start.`));
     return;
   }
-  const dbPath = resolve2(opts.path);
+  const dbPath = resolve3(opts.path);
   const apiKey = opts.key ?? `spk_${crypto.randomUUID().replace(/-/g, "")}`;
   const jwtSecret = opts.jwtSecret ?? `jws_${crypto.randomUUID().replace(/-/g, "")}`;
   writeConfig(defaultLocalConfig(dbPath, {
@@ -8048,8 +8013,8 @@ db.command("create <type> [json]").description("Create an entity (json can be a
   const db2 = TrellisDb.fromConfig(opts.configDir);
   let attributes = {};
   if (jsonArg) {
-    const { readFileSync: readFileSync4 } = await import("fs");
-    const raw = jsonArg.startsWith("@") ? readFileSync4(jsonArg.slice(1), "utf8") : jsonArg;
+    const { readFileSync: readFileSync5 } = await import("fs");
+    const raw = jsonArg.startsWith("@") ? readFileSync5(jsonArg.slice(1), "utf8") : jsonArg;
     attributes = JSON.parse(raw);
   }
   const id = await db2.create(type, attributes);
@@ -8070,8 +8035,8 @@ db.command("read <id>").description("Read an entity by ID").option("--config-dir
 db.command("update <id> <json>").description("Update entity attributes (JSON string or @file.json)").option("--config-dir <dir>", "Config directory", ".").action(async (id, jsonArg, opts) => {
   const { TrellisDb } = await import("../sdk-bepky0xs.js");
   const db2 = TrellisDb.fromConfig(opts.configDir);
-  const { readFileSync: readFileSync4 } = await import("fs");
-  const raw = jsonArg.startsWith("@") ? readFileSync4(jsonArg.slice(1), "utf8") : jsonArg;
+  const { readFileSync: readFileSync5 } = await import("fs");
+  const raw = jsonArg.startsWith("@") ? readFileSync5(jsonArg.slice(1), "utf8") : jsonArg;
   await db2.update(id, JSON.parse(raw));
   console.log(source_default.green(`\u2713 Updated: ${source_default.bold(id)}`));
   db2.close();
@@ -8102,7 +8067,7 @@ db.command("query <eql>").description("Run an EQL-S query").option("--config-dir
   db2.close();
 });
 db.command("upload <file>").description("Upload a file to the blob store").option("--config-dir <dir>", "Config directory", ".").option("--type <mime>", "MIME type (auto-detected if omitted)").action(async (filePath, opts) => {
-  const { readFileSync: readFileSync4 } = await import("fs");
+  const { readFileSync: readFileSync5 } = await import("fs");
   const { extname } = await import("path");
   const { TrellisDb } = await import("../sdk-bepky0xs.js");
   const mimeMap = {
@@ -8115,7 +8080,7 @@ db.command("upload <file>").description("Upload a file to the blob store").optio
     ".txt": "text/plain"
   };
   const contentType = opts.type ?? mimeMap[extname(filePath).toLowerCase()] ?? "application/octet-stream";
-  const buffer = readFileSync4(filePath);
+  const buffer = readFileSync5(filePath);
   const db2 = TrellisDb.fromConfig(opts.configDir);
   const result = await db2.upload(new Uint8Array(buffer), contentType);
   console.log(source_default.green(`\u2713 Uploaded`));
@@ -8266,10 +8231,10 @@ vmProgram.command("destroy <name>").description("Destroy a Sprite").action(async
       input: process.stdin,
       output: process.stdout
     });
-    const answer = await new Promise((resolve2) => {
+    const answer = await new Promise((resolve3) => {
       rl.question(`Destroy Sprite "${name}"? Cannot be undone. (y/N) `, (a) => {
         rl.close();
-        resolve2(a.trim().toLowerCase());
+        resolve3(a.trim().toLowerCase());
       });
     });
     if (answer !== "y" && answer !== "yes") {
@@ -8532,8 +8497,7 @@ vmProgram.command("code [name]").description("Create Sprite, deploy Trellis, ope
 });
 program2.addCommand(vmProgram);
 program2.command("season").description("Enrich project context for agents \u2014 interactive Q&A").option("-p, --path <path>", "Repository path", ".").option("--reset", "Re-run even if previously configured").action(async (opts) => {
-  const rootPath = resolve(opts.path);
-  requireRepo(rootPath);
+  const rootPath = resolveRepoRoot(opts.path);
   const { createInterface: createInterface2 } = await import("readline");
   const rl = createInterface2({
     input: process.stdin,
@@ -8561,8 +8525,8 @@ program2.command("season").description("Enrich project context for agents \u2014
   writeAgentScaffold(rootPath, { profile, context: updatedContext });
   const agentContextPath = join6(rootPath, ".trellis", "agents", "agent-context.json");
   try {
-    const { readFileSync: readFileSync4, writeFileSync: writeFileSync3 } = await import("fs");
-    const existing = JSON.parse(readFileSync4(agentContextPath, "utf-8"));
+    const { readFileSync: readFileSync5, writeFileSync: writeFileSync3 } = await import("fs");
+    const existing = JSON.parse(readFileSync5(agentContextPath, "utf-8"));
     existing.domain = updatedContext.domain;
     if (toolsRaw) {
       existing.tools = toolsRaw.split(",").map((s) => s.trim()).filter(Boolean);
@@ -8584,12 +8548,12 @@ program2.command("season").description("Enrich project context for agents \u2014
   console.log();
 });
 program2.command("code").alias("ide").description('Launch OpenCode in "Harness" mode, bridged to this Trellis repository').option("-p, --path <path>", "Repository path", ".").option("-m, --model <model>", "OpenCode model to use").option("-w, --web", "Launch MCP server in HTTP mode for web client access").option("--mcp-port <port>", "MCP HTTP server port (default: 3333)", "3333").option("--no-init", "Skip initialization even if not a Trellis workspace").action(async (opts) => {
-  const { resolve: resolve2, dirname: dirname6, join: join7 } = await import("path");
+  const { resolve: resolve3, dirname: dirname7, join: join7 } = await import("path");
   const { existsSync: existsSync6 } = await import("fs");
   const { spawn } = await import("child_process");
-  const { readFileSync: readFileSync4 } = await import("fs");
+  const { readFileSync: readFileSync5 } = await import("fs");
   const { createServer: createHttpServer } = await import("http");
-  const rootPath = resolve2(opts.path);
+  const rootPath = findRepoRoot(opts.path) ?? resolve3(opts.path);
   if (!opts.noInit) {
     if (!TrellisVcsEngine.isRepo(rootPath)) {
       console.log(source_default.dim("Not a Trellis workspace \u2014 initializing\u2026"));
@@ -8600,17 +8564,17 @@ program2.command("code").alias("ide").description('Launch OpenCode in "Harness"
     }
   }
   function findOpencode() {
-    const here = dirname6(process.argv[1]);
+    const here2 = dirname7(process.argv[1]);
     const candidates = [
-      join7(here, "..", "node_modules", ".bin", "opencode"),
-      join7(here, "..", "..", "node_modules", ".bin", "opencode")
+      join7(here2, "..", "node_modules", ".bin", "opencode"),
+      join7(here2, "..", "..", "node_modules", ".bin", "opencode")
     ];
-    let dir = here;
+    let dir = here2;
     for (let i = 0;i < 5; i++) {
       const p = join7(dir, "node_modules", ".bin", "opencode");
       if (existsSync6(p))
         return p;
-      dir = dirname6(dir);
+      dir = dirname7(dir);
     }
     for (const p of candidates) {
       if (existsSync6(p))
@@ -8619,14 +8583,14 @@ program2.command("code").alias("ide").description('Launch OpenCode in "Harness"
     return null;
   }
   function findMcpServer() {
-    const here = dirname6(process.argv[1]);
+    const here2 = dirname7(process.argv[1]);
     const candidates = [
-      join7(here, "..", "..", "src", "mcp", "index.ts"),
-      join7(here, "..", "src", "mcp", "index.ts"),
-      join7(here, "..", "..", "..", "src", "mcp", "index.ts"),
-      join7(here, "..", "mcp", "index.js"),
-      join7(here, "..", "mcp", "index.ts"),
-      join7(here, "mcp", "index.ts")
+      join7(here2, "..", "..", "src", "mcp", "index.ts"),
+      join7(here2, "..", "src", "mcp", "index.ts"),
+      join7(here2, "..", "..", "..", "src", "mcp", "index.ts"),
+      join7(here2, "..", "mcp", "index.js"),
+      join7(here2, "..", "mcp", "index.ts"),
+      join7(here2, "mcp", "index.ts")
     ];
     for (const p of candidates) {
       if (existsSync6(p))
@@ -8657,7 +8621,16 @@ program2.command("code").alias("ide").description('Launch OpenCode in "Harness"
   let mcpProcess = null;
   if (opts.web) {
     console.log(source_default.dim(`   Starting MCP server on port ${mcpPort}\u2026`));
-    mcpProcess = spawn("bun", ["run", mcp, "--quiet", "--path", rootPath, "--http", "--port", String(mcpPort)], {
+    mcpProcess = spawn("bun", [
+      "run",
+      mcp,
+      "--quiet",
+      "--path",
+      rootPath,
+      "--http",
+      "--port",
+      String(mcpPort)
+    ], {
       stdio: ["pipe", "pipe", "pipe"],
       detached: false
     });
@@ -8723,12 +8696,12 @@ program2.command("code").alias("ide").description('Launch OpenCode in "Harness"
   });
 });
 program2.command("studio").alias("web").description("Launch Trellis Studio in your browser, bridged to this repo").option("-p, --path <path>", "Repository path", ".").option("--port <port>", "Studio HTTP port (defaults to turtlecode default)").option("--new", "Open the new-project prompt instead of the current directory").option("--no-open", "Do not auto-open the browser").option("--no-init", "Skip initialization even if not a Trellis workspace").option("--quiet-backend", "Suppress backend stdout/stderr").allowUnknownOption(true).action(async (opts, command) => {
-  const { resolve: resolve2 } = await import("path");
-  const { existsSync: existsSync6, readFileSync: readFileSync4 } = await import("fs");
+  const { resolve: resolve3 } = await import("path");
+  const { existsSync: existsSync6, readFileSync: readFileSync5 } = await import("fs");
   const { spawn } = await import("child_process");
   const { createRequire } = await import("module");
   const path = await import("path");
-  const rootPath = resolve2(opts.path);
+  const rootPath = findRepoRoot(opts.path) ?? resolve3(opts.path);
   if (!opts.noInit) {
     if (!TrellisVcsEngine.isRepo(rootPath)) {
       console.log(source_default.dim("Not a Trellis workspace \u2014 initializing\u2026"));
@@ -8740,7 +8713,7 @@ program2.command("studio").alias("web").description("Launch Trellis Studio in yo
   let turtlecodeBin = null;
   try {
     const pkgPath = requireFn.resolve("turtlecode/package.json");
-    const pkg = JSON.parse(readFileSync4(pkgPath, "utf-8"));
+    const pkg = JSON.parse(readFileSync5(pkgPath, "utf-8"));
     const binRel = typeof pkg.bin === "string" ? pkg.bin : pkg.bin?.turtlecode;
     if (binRel) {
       const candidate = path.join(path.dirname(pkgPath), binRel);
@@ -8792,10 +8765,10 @@ async function waitForMcpReady(url, timeoutMs) {
   const { get } = await import("http");
   const start = Date.now();
   while (Date.now() - start < timeoutMs) {
-    await new Promise((resolve2) => setTimeout(resolve2, 500));
+    await new Promise((resolve3) => setTimeout(resolve3, 500));
     try {
-      const res = await new Promise((resolve2, reject) => {
-        const req = get(`${url}/health`, resolve2);
+      const res = await new Promise((resolve3, reject) => {
+        const req = get(`${url}/health`, resolve3);
         req.on("error", reject);
         req.setTimeout(2000);
       });
@@ -8806,4 +8779,100 @@ async function waitForMcpReady(url, timeoutMs) {
   }
   return false;
 }
+var cmsCmd = program2.command("cms").description("Manage CMS entities (collections, libraries, schemas)");
+cmsCmd.command("register-library <pkg>").description("Register a Svelte 5 component library as DesignComponent entities. The package must ship dist/components.json (see @turtle.tech/ui for the format).").option("-p, --path <path>", "Repository path", ".").option("--url <url>", "Trellis server URL", "http://localhost:4096").option("--dry-run", "Print the facts that would be asserted without contacting the server").action(async (pkg, opts) => {
+  const rootPath = resolveRepoRoot(opts.path);
+  const { readFileSync: readFileSync5, existsSync: existsSync6 } = await import("fs");
+  const manifestPath = join6(rootPath, "node_modules", pkg, "dist", "components.json");
+  if (!existsSync6(manifestPath)) {
+    console.error(source_default.red(`\u2717 No manifest at ${manifestPath}`));
+    console.error(source_default.dim(`  Install ${pkg} in this repo and ensure it ships dist/components.json.`));
+    process.exit(1);
+  }
+  let manifest;
+  try {
+    manifest = JSON.parse(readFileSync5(manifestPath, "utf8"));
+  } catch (err) {
+    console.error(source_default.red(`\u2717 Manifest is not valid JSON: ${manifestPath}`));
+    console.error(source_default.dim(`  ${err?.message ?? String(err)}`));
+    process.exit(1);
+  }
+  const { package: pkgName, version, components } = manifest;
+  if (!Array.isArray(components) || components.length === 0) {
+    console.error(source_default.yellow(`\u26A0 Manifest is empty: ${manifestPath}`));
+    process.exit(1);
+  }
+  const pkgSlug = pkgName.replace(/^@/, "").replace(/\//g, "__");
+  const now = new Date().toISOString();
+  const facts = [];
+  for (const comp of components) {
+    const id = `design:component:${pkgSlug}:${comp.slug}`;
+    facts.push({ e: id, a: "type", v: "DesignComponent" }, { e: id, a: "label", v: comp.component }, { e: id, a: "package", v: pkgName }, { e: id, a: "packageVersion", v: version }, { e: id, a: "slug", v: comp.slug }, { e: id, a: "source", v: comp.source ?? "" }, { e: id, a: "editable", v: JSON.stringify(comp.editable ?? []) }, { e: id, a: "createdAt", v: now });
+  }
+  if (opts.dryRun) {
+    console.log(source_default.dim("\u2500\u2500 Dry run: would assert these facts \u2500\u2500"));
+    console.log(JSON.stringify(facts, null, 2));
+    console.log(source_default.dim(`\u2500\u2500 ${facts.length} facts across ${components.length} components \u2500\u2500`));
+    return;
+  }
+  const url = new URL("/trellis/store/assert", opts.url);
+  url.searchParams.set("directory", rootPath);
+  const meta = {
+    actor: "cli:trellis",
+    actorKind: "user",
+    source: "trellis-cms-register-library",
+    relatedEntities: [...new Set(facts.map((f) => f.e))]
+  };
+  try {
+    const res = await fetch(url.toString(), {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ facts, meta })
+    });
+    if (!res.ok) {
+      const body2 = await res.text().catch(() => "");
+      console.error(source_default.red(`\u2717 Assert failed: HTTP ${res.status}`));
+      if (body2)
+        console.error(source_default.dim(`  ${body2.slice(0, 400)}`));
+      process.exit(1);
+    }
+    const body = await res.json().catch(() => ({ added: 0 }));
+    console.log(source_default.green(`\u2713 Registered ${source_default.bold(String(components.length))} components from ${source_default.bold(pkgName)}@${version}`));
+    console.log(`  ${source_default.dim("Facts added:")} ${body.added ?? "?"}`);
+    console.log(`  ${source_default.dim("Workspace:")}   ${rootPath}`);
+    for (const comp of components) {
+      console.log(`  ${source_default.dim("\u2022")} ${comp.component} ${source_default.dim(`(design:component:${pkgSlug}:${comp.slug})`)}`);
+    }
+  } catch (err) {
+    const msg = err?.message ?? String(err);
+    console.error(source_default.red(`\u2717 Could not reach Trellis server at ${opts.url}`));
+    console.error(source_default.dim(`  ${msg}`));
+    console.error(source_default.dim(`  Hint: start the Trellis backend (e.g. open the turtlecode IDE) and retry.`));
+    process.exit(1);
+  }
+});
+program2.command("skills").description("Install Trellis agent skills using the skills CLI (npx skills)").argument("[args...]", "Additional arguments to pass to the skills CLI").allowUnknownOption().action(async () => {
+  const skillsIndex = process.argv.indexOf("skills");
+  const extraArgs = skillsIndex !== -1 ? process.argv.slice(skillsIndex + 1) : [];
+  const { spawnSync } = await import("child_process");
+  const skillsArgs = ["skills", "add", "trentbrew/trellis", ...extraArgs];
+  console.log(source_default.cyan("  Installing Trellis agent skills..."));
+  console.log(source_default.dim(`  Running: npx ${skillsArgs.join(" ")}
+`));
+  if (process.env.TRELLIS_CLI_DRY_RUN === "1") {
+    return;
+  }
+  const result = spawnSync("npx", skillsArgs, {
+    stdio: "inherit",
+    shell: true
+  });
+  if (result.error) {
+    console.error(source_default.red(`
+\u2717 Failed to run skills CLI: ${result.error.message}`));
+    process.exit(1);
+  }
+  if (result.status !== 0) {
+    process.exit(result.status ?? 1);
+  }
+});
 program2.parse();