@driftless-sh/cli 0.1.34 → 0.1.36

package/dist/index.js

@@ -214567,7 +214567,7 @@ async function installSkillCommand() {
 // src/commands/init.ts
 function getVersion() {
   try {
-    return "0.1.34";
+    return "0.1.36";
   } catch {
     return "0.0.0";
   }
@@ -214866,6 +214866,15 @@ function step(label, value) {
 }
 async function initCommand(args) {
   const version = getVersion();
+  let srcOverride;
+  let suggest = false;
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--src" && i + 1 < args.length && !args[i + 1].startsWith("--")) {
+      srcOverride = args[++i];
+    } else if (args[i] === "--suggest") {
+      suggest = true;
+    }
+  }
   console.log("D R I F T L E S S");
   console.log(`v${version}`);
   console.log("");
@@ -214901,10 +214910,12 @@ async function initCommand(args) {
   const workspaceSlug = workspace.slug;
   console.log(`Repository: ${remote.org}/${remote.repo}`);
   console.log(`Workspace:  ${workspaceSlug} \u2713`);
+  if (srcOverride) console.log(`Scan root:  ${srcOverride}`);
   console.log("");
   const cwd = process.cwd();
+  const scanRoot = srcOverride ? (0, import_node_path4.resolve)(cwd, srcOverride) : cwd;
   const scanStart = Date.now();
-  const scanResult = await (0, import_scanner.scanRepo)(cwd);
+  const scanResult = await (0, import_scanner.scanRepo)(scanRoot);
   const scanMs = Date.now() - scanStart;
   const earlyPatterns = analyzeCodePatterns(scanResult.components);
   const summary = {
@@ -214924,6 +214935,12 @@ async function initCommand(args) {
     }
   };
   const components = scanResult.components;
+  if (components.length === 0) {
+    console.warn(`\u26A0 0 components found in ${srcOverride ? `--src ${srcOverride}` : "repo root"}.`);
+    console.warn("  For NestJS monorepos, point --src at the app source root, not the package root.");
+    console.warn("  Example: driftless init --src apps/api/src  (not apps/api)");
+    console.warn("  Continuing with baseline upload \u2014 no components or relations will be registered.");
+  }
   const relationCount = components.reduce(
     (sum, component) => sum + (component.relations?.length || 0),
     0
@@ -214976,46 +214993,53 @@ async function initCommand(args) {
       step("uploading components", "failed (continuing)");
     }
   }
-  const patterns = earlyPatterns;
-  const smartRules = generateSmartRules(repo.id, patterns);
   let rulesCreated = 0;
-  let rulesSkipped = 0;
-  for (const rule of smartRules) {
-    try {
-      const result = await api.post(`/workspaces/${workspaceSlug}/rules`, { ...rule, auto_suggested: true });
-      if (result?.skipped) {
+  if (suggest) {
+    const smartRules = generateSmartRules(repo.id, earlyPatterns);
+    let rulesSkipped = 0;
+    for (const rule of smartRules) {
+      try {
+        const result = await api.post(`/workspaces/${workspaceSlug}/rules`, { ...rule, auto_suggested: true });
+        if (result?.skipped) rulesSkipped++;
+        else rulesCreated++;
+      } catch {
         rulesSkipped++;
-      } else {
-        rulesCreated++;
       }
-    } catch {
-      rulesSkipped++;
     }
+    step("creating rules", `${rulesCreated} created \xB7 ${rulesSkipped} skipped \u2713`);
+  } else {
+    step("creating rules", "skipped (use --suggest to auto-generate)");
   }
-  step("creating rules", `${rulesCreated} created \xB7 ${rulesSkipped} skipped \u2713`);
-  const smartWatchers = generateSmartWatchers(components);
   let watchersCreated = 0;
-  let watchersSkipped = 0;
-  for (const watcher of smartWatchers) {
-    try {
-      await api.post(`/workspaces/${workspaceSlug}/watchers`, {
-        name: watcher.name,
-        what: watcher.what,
-        how: watcher.how,
-        pattern: watcher.pattern,
-        decisions: watcher.decisions,
-        gotchas: watcher.gotchas,
-        ownership: watcher.ownership,
-        where_repos: [repo.id],
-        created_by: "driftless-init",
-        suggested: true
-      });
-      watchersCreated++;
-    } catch {
-      watchersSkipped++;
+  if (suggest) {
+    const smartWatchers = generateSmartWatchers(components);
+    let watchersSkipped = 0;
+    for (const watcher of smartWatchers) {
+      try {
+        await api.post(`/workspaces/${workspaceSlug}/watchers`, {
+          name: watcher.name,
+          what: watcher.what,
+          how: watcher.how,
+          pattern: watcher.pattern,
+          decisions: watcher.decisions,
+          gotchas: watcher.gotchas,
+          ownership: watcher.ownership,
+          where_repos: [repo.id],
+          created_by: "driftless-init",
+          suggested: true,
+          origin: "auto",
+          status: "draft",
+          kind: "domain-map"
+        });
+        watchersCreated++;
+      } catch {
+        watchersSkipped++;
+      }
     }
+    step("creating context", `${watchersCreated} topics \u2713`);
+  } else {
+    step("creating context", "skipped (use --suggest to auto-generate)");
   }
-  step("creating context", `${watchersCreated} watchers \u2713`);
   const existingDocs = detectExistingDocs(cwd);
   step("detecting docs", `${existingDocs.length} found (not auto-synced)`);
   let skillLine = "skipped";
@@ -215029,8 +215053,8 @@ async function initCommand(args) {
   step("installing skill", skillLine);
   console.log("");
   console.log("\u2713 repo context bootstrapped");
-  console.log(`  \u251C\u2500 watchers      ${watchersCreated}`);
-  console.log(`  \u251C\u2500 rules          ${rulesCreated}`);
+  console.log(`  \u251C\u2500 topics        ${suggest ? watchersCreated : "(use --suggest to generate)"}`);
+  console.log(`  \u251C\u2500 rules          ${suggest ? rulesCreated : "(use --suggest to generate)"}`);
   console.log(`  \u251C\u2500 docs found    ${existingDocs.length} (ask your agent to sync them)`);
   console.log(`  \u251C\u2500 components   ${components.length}`);
   console.log(`  \u2514\u2500 relations    ${relationCount}`);
@@ -215212,10 +215236,12 @@ function renderSummaryHuman(items) {
   }
   const topicWidth = Math.max(...items.map((i) => i.topic.length), 12) + 2;
   const badgeWidth = Math.max(...items.map((i) => formatBadges(i.badges).length), 8) + 2;
+  const statusWidth = Math.max(...items.map((i) => (i.classification?.status || "").length), 8) + 2;
   for (const item of items) {
     const topic = pad(item.topic, topicWidth);
     const badges = pad(formatBadges(item.badges), badgeWidth);
-    console.log(`${topic}${badges}${item.summary}`);
+    const status = pad(item.classification?.status || "", statusWidth);
+    console.log(`${topic}${status}${badges}${item.summary}`);
   }
   console.log(`
 ${items.length} topic${items.length === 1 ? "" : "s"}.`);
@@ -215224,11 +215250,19 @@ function renderContextHuman(ctx) {
   console.log(`\u258C ${ctx.topic}`);
   console.log(`  ${ctx.summary}`);
   if (ctx.version !== void 0) console.log(`  version:    ${ctx.version}`);
+  if (ctx.classification) {
+    const { origin, status, kind } = ctx.classification;
+    console.log(`  origin: ${origin}  status: ${status}  kind: ${kind}`);
+  }
   if (ctx.stale.is_stale) {
     console.log(`
   \u26A0 STALE: ${ctx.stale.reason || "Context may be outdated"}`);
     console.log(`  \u2192 driftless context update ${ctx.topic} --what "..." --how "..."`);
   }
+  if (ctx.metadata.created_by === "driftless-init") {
+    console.log(`
+  \u24D8 auto-suggested by init \u2014 confirm with \`driftless context update ${ctx.topic} --what "..."\``);
+  }
   console.log("");
   if (ctx.description.what) console.log(`  what:       ${ctx.description.what}`);
   if (ctx.description.how) console.log(`  how:        ${ctx.description.how}`);
@@ -215357,9 +215391,23 @@ async function contextCommand(args) {
     if (flags["docs"]) query.push("docs=true");
     if (flags["auto"]) query.push("auto=true");
     if (flags["manual"]) query.push("manual=true");
-    if (flags["repo"]) query.push(`repo=${encodeURIComponent(flags["repo"])}`);
     if (flags["suggested"]) query.push("suggested=true");
     else query.push("suggested=false");
+    if (flags["status"]) query.push(`status=${encodeURIComponent(flags["status"])}`);
+    if (flags["kind"]) query.push(`kind=${encodeURIComponent(flags["kind"])}`);
+    if (flags["repo"]) {
+      query.push(`repo=${encodeURIComponent(flags["repo"])}`);
+    } else if (flags["auto"]) {
+      const currentRemote = getGitRemote();
+      if (currentRemote) {
+        try {
+          const repos = await api.get(`/workspaces/${workspaceSlug}/repos`);
+          const match = repos.find((r) => r.github_org === currentRemote.org && r.github_repo === currentRemote.repo);
+          if (match) query.push(`repo=${encodeURIComponent(match.id)}`);
+        } catch {
+        }
+      }
+    }
     const qs = query.length > 0 ? `?${query.join("&")}` : "";
     try {
       const summaries = await api.get(`/workspaces/${workspaceSlug}/watchers${qs}`);
@@ -215494,10 +215542,17 @@ async function contextCommand(args) {
       }
     }
     const pattern = flags["pattern"];
-    if (pattern && !isJSON) {
+    if (pattern) {
+      if (pattern.includes(",")) {
+        console.error(`Error: pattern "${pattern}" contains a comma. Only one glob is accepted per topic.`);
+        console.error("  Create separate topics for each path, or use a broader glob.");
+        process.exit(1);
+      }
       const localCount = countLocalFilesMatching(pattern);
       if (localCount === 0) {
-        console.error(`Warning: pattern "${pattern}" matches 0 files locally. Topic created anyway.`);
+        console.error(`Error: pattern "${pattern}" matches 0 files locally. Topic not created.`);
+        console.error("  Verify the glob against your repo root, or use --where for explicit file paths.");
+        process.exit(1);
       }
     }
     try {
@@ -215510,7 +215565,9 @@ async function contextCommand(args) {
         decisions: flags["decisions"],
         gotchas: flags["gotchas"],
         ownership: flags["ownership"],
-        file_content: fileContent
+        file_content: fileContent,
+        status: flags["status"],
+        kind: flags["kind"]
       });
       analyticsEvent("context_created", workspaceSlug, { topic: name, has_pattern: !!pattern, has_what: !!flags["what"] });
       if (isJSON) {
@@ -215541,12 +215598,21 @@ async function contextCommand(args) {
     if (flags["decisions"]) updates.decisions = flags["decisions"];
     if (flags["gotchas"]) updates.gotchas = flags["gotchas"];
     if (flags["ownership"]) updates.ownership = flags["ownership"];
-    const gotchaFlag = flags["gotcha"] || flags["gotchas_append"];
-    if (gotchaFlag) updates._append_gotchas = gotchaFlag;
-    const invariantFlag = flags["invariant"];
-    if (invariantFlag) updates._append_invariants = invariantFlag;
-    const checkFlag = flags["check"];
-    if (checkFlag) updates._append_required_checks = checkFlag;
+    if (flags["status"]) updates.status = flags["status"];
+    const gotchaValues = [];
+    const invariantValues = [];
+    const checkValues = [];
+    for (let i = 0; i < args.length - 1; i++) {
+      const a = args[i];
+      const b = args[i + 1];
+      if (!b || b.startsWith("--")) continue;
+      if (a === "--gotcha" || a === "--gotchas_append") gotchaValues.push(b);
+      if (a === "--invariant") invariantValues.push(b);
+      if (a === "--check") checkValues.push(b);
+    }
+    if (gotchaValues.length > 0) updates._append_gotchas = gotchaValues.join("\n");
+    if (invariantValues.length > 0) updates._append_invariants = invariantValues.join("\n");
+    if (checkValues.length > 0) updates._append_required_checks = checkValues.join("\n");
     const enforceFlag = flags["enforce"];
     if (enforceFlag && typeof enforceFlag === "string") {
       updates._enforce_rule = enforceFlag;
@@ -215554,16 +215620,18 @@ async function contextCommand(args) {
       updates._enforce_rule = true;
     }
     const eventParts = [];
-    if (gotchaFlag) eventParts.push(`gotcha appended`);
-    if (invariantFlag) eventParts.push(`invariant appended`);
-    if (checkFlag) eventParts.push(`check appended`);
+    if (gotchaValues.length > 0) eventParts.push(`gotcha appended`);
+    if (invariantValues.length > 0) eventParts.push(`invariant appended`);
+    if (checkValues.length > 0) eventParts.push(`check appended`);
     if (enforceFlag) eventParts.push(`enforce requested`);
     if (eventParts.length > 0) {
       updates._event_detail = `CONTEXT_UPDATED: ${eventParts.join(", ")}`;
     }
     if (Object.keys(updates).length === 0) {
-      console.error("No fields to update. Use --what, --how, --pattern, --decisions, --gotchas, --ownership");
-      console.error('PR 3: --gotcha, --invariant, --check, --enforce "<rule-description>"');
+      console.error("No fields to update.");
+      console.error("Scalar: --what, --how, --pattern, --decisions, --gotchas, --ownership");
+      console.error("Append: --gotcha (repeatable), --invariant (repeatable), --check (repeatable)");
+      console.error('Enforce: --enforce "<rule-description>"');
       process.exit(1);
     }
     const currentRemote = getGitRemote();
@@ -215672,7 +215740,12 @@ async function contextCommand(args) {
     }
     const updates = { last_updated: /* @__PURE__ */ new Date() };
     if (fileContent) updates.file_content = fileContent;
-    if (docFlag) updates.anchored_doc_path = docFlag;
+    if (docFlag) {
+      updates.anchored_doc_path = docFlag;
+      updates.origin = "doc";
+      updates.status = "draft";
+      updates.kind = "docs-pending";
+    }
     if (noteFlag) updates.decisions = noteFlag;
     if (filesFlag) updates.where_files = filesFlag.split(",").map((f) => f.trim()).filter(Boolean);
     if (patternFlag) updates.pattern = patternFlag;
@@ -215952,6 +216025,39 @@ Run 'driftless help context' for full reference.`);
 
 // src/commands/sync.ts
 init_api_client();
+
+// src/repo-resolver.ts
+init_api_client();
+function notLinkedMessage(remote, workspaceSlug) {
+  return `Repo '${remote.org}/${remote.repo}' is not registered in workspace '${workspaceSlug}'. Run \`driftless init\` to register it.`;
+}
+async function resolveRepo() {
+  const remote = getGitRemote();
+  if (!remote) return { ok: false, reason: "no_remote" };
+  let workspaceSlug;
+  try {
+    const me = await api.get("/me");
+    workspaceSlug = me?.slug;
+  } catch {
+  }
+  if (!workspaceSlug) return { ok: false, reason: "no_workspace", remote };
+  let repo;
+  try {
+    const repos = await api.get(`/workspaces/${workspaceSlug}/repos`);
+    repo = repos.find((r) => r.github_org === remote.org && r.github_repo === remote.repo);
+  } catch {
+  }
+  if (!repo) return { ok: false, reason: "not_linked", workspaceSlug, remote };
+  return {
+    ok: true,
+    workspaceSlug,
+    repoId: repo.id,
+    remote,
+    hasScanBaseline: !!repo.scan_summary
+  };
+}
+
+// src/commands/sync.ts
 function parseArgs2(args) {
   const flags = {};
   for (let i = 0; i < args.length; i++) {
@@ -215969,19 +216075,6 @@ function parseArgs2(args) {
 function emitJSON3(data) {
   console.log(JSON.stringify(data, null, 2));
 }
-async function resolveWorkspaceSlug2() {
-  try {
-    const me = await api.get("/me");
-    if (me?.slug) return me.slug;
-  } catch {
-  }
-  const remote = getGitRemote();
-  if (!remote) {
-    console.error("Error: no git remote found.");
-    process.exit(1);
-  }
-  return remote.org;
-}
 async function syncCommand(args) {
   if (!isGitRepo()) {
     console.error("Error: not a git repository.");
@@ -215989,33 +216082,23 @@ async function syncCommand(args) {
   }
   const { flags } = parseArgs2(args);
   const isJSON = !!flags["json"];
-  const remote = getGitRemote();
-  if (!remote) {
-    console.error("Error: no git remote configured.");
-    process.exit(1);
-  }
-  const workspaceSlug = await resolveWorkspaceSlug2();
-  let repoId = null;
-  try {
-    const repos = await api.get(`/workspaces/${workspaceSlug}/repos`);
-    const match = repos.find((r) => r.github_org === remote.org && r.github_repo === remote.repo);
-    if (match) repoId = match.id;
-  } catch {
-  }
-  if (!repoId) {
+  const resolution = await resolveRepo();
+  if (!resolution.ok) {
+    const msg = resolution.reason === "no_remote" ? "Error: no git remote configured." : resolution.reason === "no_workspace" ? "Error: could not resolve workspace. Run `driftless doctor` to diagnose." : notLinkedMessage(resolution.remote, resolution.workspaceSlug);
     if (!isJSON) {
-      console.log(`Repo '${remote.org}/${remote.repo}' not found in workspace.`);
-      console.log("Run driftless init to register this repo first.");
+      console.log(`\u26A0 ${msg}`);
+      if (resolution.reason !== "no_remote") console.log("  Run `driftless doctor` to diagnose.");
     } else {
-      emitJSON3({ error: "repo_not_found", repo: `${remote.org}/${remote.repo}` });
+      emitJSON3({ error: resolution.reason, message: msg });
     }
-    process.exit(0);
+    process.exit(1);
   }
+  const { workspaceSlug, repoId, remote } = resolution;
   const [eventsRes, staleTopics, violations, suggestedTopics] = await Promise.allSettled([
     api.get(`/workspaces/${workspaceSlug}/watchers/events?repo_id=${repoId}&limit=20`),
     api.get(`/workspaces/${workspaceSlug}/watchers?stale=true&repo=${repoId}`),
     api.get(`/workspaces/${workspaceSlug}/violations?repo_id=${repoId}&status=open&limit=20`),
-    api.get(`/workspaces/${workspaceSlug}/watchers?suggested=true`)
+    api.get(`/workspaces/${workspaceSlug}/watchers?suggested=true&repo=${repoId}`)
   ]);
   const events = eventsRes.status === "fulfilled" ? eventsRes.value.events ?? [] : [];
   const stale = staleTopics.status === "fulfilled" ? staleTopics.value : [];
@@ -216210,38 +216293,22 @@ async function doctorCommand() {
   } else {
     checks.push({ name: "Workspace", status: "warn", detail: "Skipped (local API or no key)" });
   }
-  if (remote) {
-    const me = await getMe();
-    if (me?.slug) {
-      const repos = await getRepos(me.slug);
-      const linked = repos?.find((r) => r.github_org === remote.org && r.github_repo === remote.repo);
-      if (linked) {
-        checks.push({ name: "Repo linked", status: "ok", detail: `${remote.org}/${remote.repo}` });
-      } else {
-        checks.push({ name: "Repo linked", status: "warn", detail: `Not connected. Run \`driftless init\`` });
-      }
-    } else {
-      checks.push({ name: "Repo linked", status: "warn", detail: "Could not verify (workspace unknown)" });
-    }
+  const resolution = await resolveRepo();
+  if (resolution.ok) {
+    checks.push({ name: "Repo linked", status: "ok", detail: `${resolution.remote.org}/${resolution.remote.repo}` });
+    checks.push({
+      name: "Baseline",
+      status: resolution.hasScanBaseline ? "ok" : "warn",
+      detail: resolution.hasScanBaseline ? "Scan data present" : "No scan baseline. Run `driftless init`"
+    });
+  } else if (resolution.reason === "not_linked") {
+    checks.push({ name: "Repo linked", status: "warn", detail: notLinkedMessage(resolution.remote, resolution.workspaceSlug) });
+    checks.push({ name: "Baseline", status: "warn", detail: "Could not verify (repo not registered)" });
+  } else if (resolution.reason === "no_workspace") {
+    checks.push({ name: "Repo linked", status: "warn", detail: "Could not verify (workspace unknown)" });
+    checks.push({ name: "Baseline", status: "warn", detail: "Could not verify (workspace unknown)" });
   } else {
     checks.push({ name: "Repo linked", status: "warn", detail: "Skipped (no git remote)" });
-  }
-  if (remote) {
-    const me = await getMe();
-    if (me?.slug) {
-      const repos = await getRepos(me.slug);
-      const linked = repos?.find((r) => r.github_org === remote.org && r.github_repo === remote.repo);
-      if (linked?.scan_summary) {
-        checks.push({ name: "Baseline", status: "ok", detail: "Scan data present" });
-      } else if (linked) {
-        checks.push({ name: "Baseline", status: "warn", detail: "Repo connected but no scan baseline. Run `driftless init`" });
-      } else {
-        checks.push({ name: "Baseline", status: "warn", detail: "Could not verify" });
-      }
-    } else {
-      checks.push({ name: "Baseline", status: "warn", detail: "Could not verify" });
-    }
-  } else {
     checks.push({ name: "Baseline", status: "warn", detail: "Skipped (no git remote)" });
   }
   const agentsPath = (0, import_node_path7.resolve)(process.cwd(), "AGENTS.md");
@@ -216264,13 +216331,18 @@ async function doctorCommand() {
         if (ghApp) {
           checks.push({ name: "GitHub App", status: "ok", detail: "Installed and active" });
         } else {
-          checks.push({ name: "GitHub App", status: "warn", detail: "Not installed. Install via dashboard Settings \u2192 GitHub" });
+          checks.push({ name: "GitHub App", status: "warn", detail: "Not installed \u2014 driftless.icu/ecosystem \u2192 Settings \u2192 Integrations (if just installed, wait ~60s)" });
+        }
+      } catch (err) {
+        const isNotFound = err?.status === 404 || String(err?.message ?? "").includes("404");
+        if (isNotFound) {
+          checks.push({ name: "GitHub App", status: "warn", detail: "Not installed \u2014 driftless.icu/ecosystem \u2192 Settings \u2192 Integrations" });
+        } else {
+          checks.push({ name: "GitHub App", status: "warn", detail: "Could not verify \u2014 check your connection or API key" });
         }
-      } catch {
-        checks.push({ name: "GitHub App", status: "warn", detail: "Could not verify" });
       }
     } else {
-      checks.push({ name: "GitHub App", status: "warn", detail: "Could not verify" });
+      checks.push({ name: "GitHub App", status: "warn", detail: "Could not verify (workspace unknown)" });
     }
   } else {
     checks.push({ name: "GitHub App", status: "warn", detail: "Skipped (not a git repo)" });
@@ -216302,7 +216374,7 @@ function pad2(s, n) {
 }
 
 // src/index.ts
-var VERSION = "0.1.34";
+var VERSION = "0.1.36";
 var HELP_TEXT = `Driftless CLI v${VERSION} \u2014 Living repo context for humans and coding agents
 
 Install:  npm install -g @driftless-sh/cli
@@ -216319,7 +216391,7 @@ Agent loop:
 
 Setup:
   driftless login --key <api-key>       Authenticate
-  driftless init                        Scan repo, bootstrap context, suggest rules
+  driftless init [--src <path>]         Scan repo, bootstrap context (add --suggest for auto topics+rules)
   driftless doctor                      Check environment health
 
 Commands:
@@ -216370,8 +216442,8 @@ Examples:
   driftless sync --json                # machine-readable output
 
   driftless context add "b2b-guard" \\
-    --what "Guard que protege endpoints B2B" \\
-    --how "Verifica org_id en el token" \\
+    --what "Guard protecting B2B endpoints" \\
+    --how "Verifies org_id from the auth token" \\
     --pattern "src/shared/guards/**"
 
   driftless context get sdk
@@ -216393,22 +216465,30 @@ Options:
 Example:
   driftless login --key drift_xxx
 `,
-    init: `driftless init
+    init: `driftless init [--src <path>] [--suggest]
 
 Smart initialization \u2014 zero friction:
   1. Detects framework, system type, auth patterns (Pass 1)
   2. AST scan: extracts endpoints, guards, services, modules, relations (Pass 2)
   3. Analyzes code patterns: guard enforcement, multi-tenant, large files, legacy
   4. Uploads baseline + components + relations to Cloud
-  5. Creates specific rules from detected patterns (not generic ones)
-  6. Creates context topics for each detected module with smart gotchas
-  7. Detects existing docs (not auto-synced \u2014 ask your agent to sync them)
+  5. Detects existing docs (not auto-synced \u2014 ask your agent to sync them)
+  6. Installs AGENTS.md skill
+
+With --suggest (optional):
+  Also auto-generates rules and context topics from detected patterns.
+
+Options:
+  --src <path>   Scan root relative to cwd (monorepo support).
+                 Git root stays at cwd; scanner starts from <path>.
+  --suggest      Auto-generate rules and context topics. Off by default.
 
 Must be run from a git repository root.
 
-Example:
-  cd my-nestjs-repo
+Examples:
   driftless init
+  driftless init --src apps/api/src
+  driftless init --src apps/api/src --suggest
 `,
     scan: `driftless scan [--diff]
 
@@ -216505,25 +216585,53 @@ async function main() {
   const command = args[0];
   switch (command) {
     case "init":
-      await initCommand(args.slice(1));
+      if (args[1] === "--help") {
+        showCommandHelp("init");
+      } else {
+        await initCommand(args.slice(1));
+      }
       break;
     case "scan":
-      await scanCommand(args.slice(1));
+      if (args[1] === "--help") {
+        showCommandHelp("scan");
+      } else {
+        await scanCommand(args.slice(1));
+      }
       break;
     case "context":
-      await contextCommand(args.slice(1));
+      if (args[1] === "--help") {
+        showCommandHelp("context");
+      } else {
+        await contextCommand(args.slice(1));
+      }
       break;
     case "sync":
-      await syncCommand(args.slice(1));
+      if (args[1] === "--help") {
+        showCommandHelp("sync");
+      } else {
+        await syncCommand(args.slice(1));
+      }
       break;
     case "install-skill":
-      await installSkillCommand();
+      if (args[1] === "--help") {
+        showCommandHelp("install-skill");
+      } else {
+        await installSkillCommand();
+      }
       break;
     case "login":
-      loginCommand(args.slice(1));
+      if (args[1] === "--help") {
+        showCommandHelp("login");
+      } else {
+        loginCommand(args.slice(1));
+      }
       break;
     case "doctor":
-      await doctorCommand();
+      if (args[1] === "--help") {
+        showCommandHelp("doctor");
+      } else {
+        await doctorCommand();
+      }
       break;
     case "help":
       if (args[1]) {