@archme/cli 0.4.0 → 0.4.1

package/LICENSE

@@ -0,0 +1,64 @@
+ArchitectMe CLI License
+
+Copyright (c) 2026 ArchitectMe. All rights reserved.
+
+This software (the "Software") is proprietary and is licensed, not sold.
+
+1. GRANT OF LICENSE
+
+   Subject to the terms below, you are granted a non-exclusive,
+   non-transferable, revocable license to install and use the Software solely
+   to interact with the ArchitectMe service operated at archme.io (the
+   "Service"), in connection with an active ArchitectMe account.
+
+   Use of the Software for any other purpose — including use with any service,
+   endpoint, or system other than the Service — is not licensed.
+
+2. RESTRICTIONS
+
+   You may not:
+
+   (a) redistribute, sublicense, sell, rent, lease, or otherwise transfer the
+       Software or copies of it;
+   (b) modify, adapt, translate, or create derivative works of the Software;
+   (c) reverse engineer, decompile, or disassemble the Software, or otherwise
+       attempt to derive its source code, except to the extent that such
+       activity is expressly permitted by applicable law notwithstanding this
+       restriction;
+   (d) remove, obscure, or alter any proprietary notices contained in the
+       Software; or
+   (e) use the Software to build, train, or improve a competing product or
+       service.
+
+3. RESERVATION OF RIGHTS
+
+   All right, title, and interest in and to the Software, including all
+   intellectual property rights, remain with ArchitectMe. No rights are granted
+   except as expressly set out in this license.
+
+4. TERMINATION
+
+   This license terminates automatically if you breach any of its terms, and
+   may be terminated by ArchitectMe at any time. On termination you must cease
+   all use of the Software and destroy all copies in your possession.
+
+5. NO WARRANTY
+
+   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+   IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+   FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT.
+
+6. LIMITATION OF LIABILITY
+
+   IN NO EVENT SHALL ARCHITECTME BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER
+   LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING
+   FROM, OUT OF, OR IN CONNECTION WITH THE SOFTWARE OR THE USE OF OR OTHER
+   DEALINGS IN THE SOFTWARE.
+
+7. THIRD-PARTY COMPONENTS
+
+   The Software incorporates third-party open-source components, which remain
+   subject to their own licenses. Nothing in this license limits your rights
+   under those licenses with respect to those components.
+
+For licensing enquiries, contact archme.io.

package/README.md

@@ -31,29 +31,37 @@ everything else keeps working.
 
 ### Developing on the CLI
 
-From a clone, `npm link` puts the local copy on your `PATH`:
+**For iterating on sources, use tsx directly** — it always runs current code:
 
 ```bash
 cd archme-cli
 npm install
+npx tsx src/bin.ts <subcommand> [args]
+```
+
+`npm link` also works, but note the published `bin` is the *built bundle*
+(`dist/cli.js`), so linking without building leaves a dangling symlink, and a
+stale `dist/` silently shadows your edits. Build first, and rebuild after
+changes:
+
+```bash
+npm install
+npm run build     # required — bin points at dist/cli.js
 npm link
 
-which archme   # → <your-npm-prefix>/bin/archme
+which archme      # → <your-npm-prefix>/bin/archme
 ```
 
 To uninstall: `cd archme-cli && npm unlink` (or `npm rm -g @archme/cli`).
 
-**One-off / no global install:**
-
-```bash
-npx tsx archme-cli/src/bin.ts <subcommand> [args]
-```
+`npm run build` uses esbuild to inline the repo's top-level `shared/` modules,
+which do not exist inside the package. `npm run build:check` builds and then
+executes the artifact — that is what CI and `prepublishOnly` run.
 
-The published package runs `dist/cli.js`, built by `npm run build` (esbuild
-inlines the repo's top-level `shared/` modules, which do not exist inside the
-package). `npm run build:check` builds and then executes the artifact — that is
-what CI and `prepublishOnly` run. When iterating on sources, prefer
-`npx tsx src/bin.ts`, which never consults `dist/`.
+`bin/archme` (the dev shim, used by an unbuilt clone and by service units when
+`dist/` is absent) runs `src/bin.ts` via tsx. It must point at `bin.ts`, not
+`cli.ts` — `cli.ts` exports `main` without invoking it, so pointing at it makes
+every command a silent exit 0. `src/binShim.test.ts` pins this by executing it.
 
 ### Do you need env config?
 

package/dist/cli.js

@@ -1020,15 +1020,15 @@ var require_windows = __commonJS({
       }
       return false;
     }
-    function checkStat(stat9, path7, options) {
-      if (!stat9.isSymbolicLink() && !stat9.isFile()) {
+    function checkStat(stat10, path7, options) {
+      if (!stat10.isSymbolicLink() && !stat10.isFile()) {
         return false;
       }
       return checkPathExt(path7, options);
     }
     function isexe(path7, options, cb) {
-      fs.stat(path7, function(er, stat9) {
-        cb(er, er ? false : checkStat(stat9, path7, options));
+      fs.stat(path7, function(er, stat10) {
+        cb(er, er ? false : checkStat(stat10, path7, options));
       });
     }
     function sync(path7, options) {
@@ -1044,20 +1044,20 @@ var require_mode = __commonJS({
     isexe.sync = sync;
     var fs = __require("fs");
     function isexe(path7, options, cb) {
-      fs.stat(path7, function(er, stat9) {
-        cb(er, er ? false : checkStat(stat9, options));
+      fs.stat(path7, function(er, stat10) {
+        cb(er, er ? false : checkStat(stat10, options));
       });
     }
     function sync(path7, options) {
       return checkStat(fs.statSync(path7), options);
     }
-    function checkStat(stat9, options) {
-      return stat9.isFile() && checkMode(stat9, options);
+    function checkStat(stat10, options) {
+      return stat10.isFile() && checkMode(stat10, options);
     }
-    function checkMode(stat9, options) {
-      var mod = stat9.mode;
-      var uid = stat9.uid;
-      var gid = stat9.gid;
+    function checkMode(stat10, options) {
+      var mod = stat10.mode;
+      var uid = stat10.uid;
+      var gid = stat10.gid;
       var myUid = options.uid !== void 0 ? options.uid : process.getuid && process.getuid();
       var myGid = options.gid !== void 0 ? options.gid : process.getgid && process.getgid();
       var u2 = parseInt("100", 8);
@@ -1091,12 +1091,12 @@ var require_isexe = __commonJS({
         if (typeof Promise !== "function") {
           throw new TypeError("callback not provided");
         }
-        return new Promise(function(resolve3, reject) {
+        return new Promise(function(resolve4, reject) {
           isexe(path7, options || {}, function(er, is) {
             if (er) {
               reject(er);
             } else {
-              resolve3(is);
+              resolve4(is);
             }
           });
         });
@@ -1162,27 +1162,27 @@ var require_which = __commonJS({
         opt = {};
       const { pathEnv, pathExt, pathExtExe } = getPathInfo(cmd, opt);
       const found = [];
-      const step = (i2) => new Promise((resolve3, reject) => {
+      const step = (i2) => new Promise((resolve4, reject) => {
         if (i2 === pathEnv.length)
-          return opt.all && found.length ? resolve3(found) : reject(getNotFoundError(cmd));
+          return opt.all && found.length ? resolve4(found) : reject(getNotFoundError(cmd));
         const ppRaw = pathEnv[i2];
         const pathPart = /^".*"$/.test(ppRaw) ? ppRaw.slice(1, -1) : ppRaw;
         const pCmd = path7.join(pathPart, cmd);
         const p = !pathPart && /^\.[\\\/]/.test(cmd) ? cmd.slice(0, 2) + pCmd : pCmd;
-        resolve3(subStep(p, i2, 0));
+        resolve4(subStep(p, i2, 0));
       });
-      const subStep = (p, i2, ii) => new Promise((resolve3, reject) => {
+      const subStep = (p, i2, ii) => new Promise((resolve4, reject) => {
         if (ii === pathExt.length)
-          return resolve3(step(i2 + 1));
+          return resolve4(step(i2 + 1));
         const ext2 = pathExt[ii];
         isexe(p + ext2, { pathExt: pathExtExe }, (er, is) => {
           if (!er && is) {
             if (opt.all)
               found.push(p + ext2);
             else
-              return resolve3(p + ext2);
+              return resolve4(p + ext2);
           }
-          return resolve3(subStep(p, i2, ii + 1));
+          return resolve4(subStep(p, i2, ii + 1));
         });
       });
       return cb ? step(0).then((res) => cb(null, res), cb) : step(0);
@@ -2262,8 +2262,8 @@ var init_deferred = __esm({
   "node_modules/execa/lib/utils/deferred.js"() {
     createDeferred = () => {
       const methods = {};
-      const promise = new Promise((resolve3, reject) => {
-        Object.assign(methods, { resolve: resolve3, reject });
+      const promise = new Promise((resolve4, reject) => {
+        Object.assign(methods, { resolve: resolve4, reject });
       });
       return Object.assign(promise, methods);
     };
@@ -7560,11 +7560,11 @@ var init_concurrent = __esm({
       const promises = weakMap.get(stream);
       const promise = createDeferred();
       promises.push(promise);
-      const resolve3 = promise.resolve.bind(promise);
-      return { resolve: resolve3, promises };
+      const resolve4 = promise.resolve.bind(promise);
+      return { resolve: resolve4, promises };
     };
-    waitForConcurrentStreams = async ({ resolve: resolve3, promises }, subprocess) => {
-      resolve3();
+    waitForConcurrentStreams = async ({ resolve: resolve4, promises }, subprocess) => {
+      resolve4();
       const [isSubprocessExit] = await Promise.race([
         Promise.allSettled([true, subprocess]),
         Promise.all([false, ...promises])
@@ -8636,7 +8636,7 @@ async function runLogin() {
   const expiresAt = Date.now() + data.expires_in * 1e3;
   let intervalMs = Math.max(data.interval, 1) * 1e3;
   while (Date.now() < expiresAt) {
-    await new Promise((resolve3) => setTimeout(resolve3, intervalMs));
+    await new Promise((resolve4) => setTimeout(resolve4, intervalMs));
     const poll = await postJson("/poll", {
       device_code: data.device_code
     });
@@ -8852,7 +8852,7 @@ var init_launchctl = __esm({
         if (r.exitCode === 0 || r.exitCode === 17) return;
         if (r.exitCode === 5) {
           await this.opts.spawner.run("launchctl", ["bootout", SERVICE_TARGET(this.opts.uid)]);
-          await new Promise((resolve3) => setTimeout(resolve3, 500));
+          await new Promise((resolve4) => setTimeout(resolve4, 500));
           r = await bootstrap();
           if (r.exitCode === 0 || r.exitCode === 17) return;
         }
@@ -9231,7 +9231,7 @@ async function tailLog(opts = {}) {
     }
   }
   if (!opts.follow) return;
-  await new Promise((resolve3, reject) => {
+  await new Promise((resolve4, reject) => {
     let fileWatcher = null;
     let dirWatcher = null;
     const dir = dirname6(path7);
@@ -9295,7 +9295,7 @@ async function tailLog(opts = {}) {
     const handleSigint = () => {
       fileWatcher?.close();
       dirWatcher?.close();
-      resolve3();
+      resolve4();
     };
     process.once("SIGINT", handleSigint);
   });
@@ -9425,6 +9425,7 @@ async function writeMcpConfig(opts) {
     project: opts.projectSlug,
     branch: opts.branch
   });
+  if (opts.sourceKind) params.set("source_kind", opts.sourceKind);
   if (opts.source) {
     params.set("source_repo", opts.source.repo);
     params.set("source_after_sha", opts.source.after_sha);
@@ -9506,8 +9507,7 @@ var init_daemonModel = __esm({
 function buildClaudeArgs(opts) {
   const tools = (opts.allowedTools ?? DEFAULT_ALLOWED_TOOLS).join(",");
   const args = [
-    "-p",
-    opts.prompt,
+    ...opts.interactive ? [opts.prompt] : ["-p", opts.prompt],
     "--mcp-config",
     opts.mcpConfigPath,
     // Load ONLY the server(s) from our --mcp-config file; ignore the repo's
@@ -9524,7 +9524,7 @@ function buildClaudeArgs(opts) {
     "--allowedTools",
     tools
   ];
-  if (opts.jsonOutput) {
+  if (opts.jsonOutput && !opts.interactive) {
     args.push("--output-format", "json");
   }
   if (opts.model) {
@@ -9535,9 +9535,20 @@ function buildClaudeArgs(opts) {
 function spawnClaude(opts) {
   const env = scrubPrivilegedEnv(process.env);
   const args = buildClaudeArgs({ ...opts, model: opts.model || DEFAULT_CLAUDE_MODEL });
-  if (opts.streamJson) {
+  if (opts.streamJson && !opts.interactive) {
     args.push("--output-format", "stream-json", "--verbose");
   }
+  if (opts.interactive) {
+    return execa("claude", args, {
+      reject: false,
+      // No timeout: the session is only as long as the human wants, and killing
+      // it out from under them mid-answer would be worse than any runaway.
+      cwd: opts.cwd,
+      env,
+      // Hand over the terminal — this is the whole point.
+      stdio: "inherit"
+    });
+  }
   return execa(
     "claude",
     args,
@@ -14086,7 +14097,7 @@ var init_semaphore = __esm({
       acquire() {
         const slot = this.tryAcquire();
         if (slot) return Promise.resolve(slot);
-        return new Promise((resolve3) => this.waiters.push(resolve3));
+        return new Promise((resolve4) => this.waiters.push(resolve4));
       }
       makeRelease() {
         let released = false;
@@ -16659,8 +16670,8 @@ async function defaultLoadUptime(pid) {
   if (process.platform === "linux") {
     try {
       const { readFile: readFile12 } = await import("node:fs/promises");
-      const stat9 = await readFile12(`/proc/${pid}/stat`, "utf8");
-      const parts = stat9.split(") ").pop()?.split(" ") ?? [];
+      const stat10 = await readFile12(`/proc/${pid}/stat`, "utf8");
+      const parts = stat10.split(") ").pop()?.split(" ") ?? [];
       const ticks = Number(parts[19]);
       if (!Number.isFinite(ticks)) return null;
       const { readFile: rf } = await import("node:fs/promises");
@@ -16715,6 +16726,45 @@ var init_dispatch2 = __esm({
   }
 });
 
+// src/scan/authedClient.ts
+import { createClient as createClient2 } from "@supabase/supabase-js";
+async function createAuthedClient(opts) {
+  initBearer({
+    supabaseUrl: opts.supabaseUrl,
+    anonKey: opts.supabaseAnonKey,
+    clientId: opts.clientId,
+    preSpawnMinLifetimeMs: opts.preSpawnMinLifetimeMs
+  });
+  let loaded;
+  try {
+    loaded = await loadStoredAndRefresh();
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    throw new Error(`${msg}
+\u2192 run \`archme login\` first`);
+  }
+  const userId = getCurrentUserId();
+  if (!userId) throw new Error("could not resolve user id from OAuth tokens");
+  const supabase = createClient2(opts.supabaseUrl, opts.supabaseAnonKey, {
+    accessToken: async () => getCurrentAccessToken()
+  });
+  return {
+    supabase,
+    userId,
+    orgId: getCurrentOrgId(),
+    identity: `${loaded.user.email ?? "OAuth user"} (${loaded.user.sub ?? "unknown"})`
+  };
+}
+var SCAN_CLAUDE_TIMEOUT_MS, SCAN_PRE_SPAWN_TOKEN_MIN_LIFETIME_MS;
+var init_authedClient = __esm({
+  "src/scan/authedClient.ts"() {
+    "use strict";
+    init_bearer();
+    SCAN_CLAUDE_TIMEOUT_MS = 45 * 60 * 1e3;
+    SCAN_PRE_SPAWN_TOKEN_MIN_LIFETIME_MS = SCAN_CLAUDE_TIMEOUT_MS + 5 * 60 * 1e3;
+  }
+});
+
 // src/scan/web-url.ts
 function deriveWebOrigin(apiUrl, onMalformed = "throw") {
   let parsed;
@@ -16995,20 +17045,24 @@ var init_github_remote = __esm({
 });
 
 // src/scan/run-scan.ts
-import { createClient as createClient2 } from "@supabase/supabase-js";
 import { createWriteStream as createWriteStream2 } from "node:fs";
 import { mkdir as mkdir10, readFile as readFile11 } from "node:fs/promises";
 import { basename as basename2, join as join16 } from "node:path";
-function buildBootstrapPrompt(promptVariant) {
-  if (!promptVariant) return BOOTSTRAP_PROMPT_BASE;
+function buildBootstrapPrompt(opts = {}) {
+  const { promptVariant, interactive, briefing } = opts;
+  let base = interactive ? briefing ? `${BOOTSTRAP_INTERACTIVE}
+
+${briefing}` : BOOTSTRAP_INTERACTIVE_NO_BRIEFING : BOOTSTRAP_HEADLESS;
+  if (!promptVariant) return base;
   if (!PROMPT_VARIANT_RE.test(promptVariant)) {
     throw new Error(
       `invalid prompt variant id \`${promptVariant}\` (expected YY-MM-DD-HHMM, optionally followed by -<suffix>)`
     );
   }
-  return `${BOOTSTRAP_PROMPT_BASE}
+  base += `
 
 Use scan-prompt variant \`${promptVariant}\` \u2014 pass \`variant: "${promptVariant}"\` to \`start_scan\`.`;
+  return base;
 }
 function todayDate() {
   const d = /* @__PURE__ */ new Date();
@@ -17204,26 +17258,14 @@ async function runScan(opts, deps = {}) {
   log(`  supabase: ${supabaseUrl}`);
   log(`  mcp base: ${mcpUrl}`);
   log(`  repo:     ${opts.repoPath}`);
-  initBearer({
+  const authed = await createAuthedClient({
     supabaseUrl,
-    anonKey: supabaseAnon,
+    supabaseAnonKey: supabaseAnon,
     clientId,
     preSpawnMinLifetimeMs: SCAN_PRE_SPAWN_TOKEN_MIN_LIFETIME_MS
   });
-  let loaded;
-  try {
-    loaded = await loadStoredAndRefresh();
-  } catch (err) {
-    const msg = err instanceof Error ? err.message : String(err);
-    throw new Error(`${msg}
-\u2192 run \`archme login\` first`);
-  }
-  log(`  signed in as ${loaded.user.email ?? "OAuth user"} (${loaded.user.sub ?? "unknown"})`);
-  const userId = getCurrentUserId();
-  if (!userId) throw new Error("could not resolve user id from OAuth tokens");
-  const supabase = createClient2(supabaseUrl, supabaseAnon, {
-    accessToken: async () => getCurrentAccessToken()
-  });
+  log(`  signed in as ${authed.identity}`);
+  const { supabase, userId } = authed;
   let headSha;
   try {
     headSha = await repoHeadSha(opts.repoPath);
@@ -17259,24 +17301,38 @@ async function runScan(opts, deps = {}) {
     baseUrl: mcpUrl,
     projectSlug: `${resolved.orgSlug}/${resolved.projectSlug}`,
     branch: branchName,
-    bearer
-    // No source headers — developer-driven run, commits stay untagged.
+    bearer,
+    // No source-SHA block (no job id for a local run), but DO tag these as scan
+    // writes: otherwise they are indistinguishable from a manual chat edit, and
+    // the scan-in-progress banner cannot tell a running scan from a human typing.
+    sourceKind: "scan"
   });
   try {
     const model = await resolveModelPin(supabase);
-    log(`spawning claude (mcp config at ${configPath}, model ${model}, timeout ${Math.round(SCAN_CLAUDE_TIMEOUT_MS / 6e4)} min)`);
+    const interactive = opts.interactive !== false;
+    log(
+      interactive ? `starting claude (mcp config at ${configPath}, model ${model}) \u2014 this session is interactive; answer its questions as they come` : `spawning claude (mcp config at ${configPath}, model ${model}, timeout ${Math.round(SCAN_CLAUDE_TIMEOUT_MS / 6e4)} min)`
+    );
     const spawn2 = deps.spawn ?? spawnClaude;
     const proc = spawn2({
-      prompt: buildBootstrapPrompt(opts.promptVariant),
+      prompt: buildBootstrapPrompt({
+        promptVariant: opts.promptVariant,
+        interactive,
+        briefing: opts.briefing
+      }),
       mcpConfigPath: configPath,
       cwd: opts.repoPath,
-      timeoutMs: SCAN_CLAUDE_TIMEOUT_MS,
+      // No timeout interactively — a human is present and can Ctrl-C. Killing a
+      // session mid-answer would be worse than any runaway.
+      timeoutMs: interactive ? void 0 : SCAN_CLAUDE_TIMEOUT_MS,
       allowedTools: SCAN_ALLOWED_TOOLS,
       model,
+      interactive,
       // stream-json: required for the transcript regexes in
       // transcript-signals.ts to see real tool events. Without it, claude
       // -p emits only the model's final text and every signal reports 0.
-      streamJson: true
+      // Incompatible with an interactive TTY session.
+      streamJson: !interactive
     });
     const transcriptDir = join16(opts.repoPath, ".archme", "scan");
     const transcriptPath = join16(transcriptDir, "transcript.log");
@@ -17319,8 +17375,8 @@ async function runScan(opts, deps = {}) {
     log(`  stories:    ${counts.stories}`);
     let signals2 = null;
     try {
-      await new Promise((resolve3, reject) => {
-        transcriptStream.end((err) => err ? reject(err) : resolve3());
+      await new Promise((resolve4, reject) => {
+        transcriptStream.end((err) => err ? reject(err) : resolve4());
       });
       const reportPath = join16(transcriptDir, "report.json");
       const orphansTxtPath = join16(transcriptDir, "orphans.txt");
@@ -17393,12 +17449,13 @@ async function runScan(opts, deps = {}) {
     });
   }
 }
-var SCAN_CLAUDE_TIMEOUT_MS, SCAN_PRE_SPAWN_TOKEN_MIN_LIFETIME_MS, BOOTSTRAP_PROMPT_BASE, PROMPT_VARIANT_RE;
+var BOOTSTRAP_HEADLESS, BOOTSTRAP_INTERACTIVE, BOOTSTRAP_INTERACTIVE_NO_BRIEFING, PROMPT_VARIANT_RE;
 var init_run_scan = __esm({
   "src/scan/run-scan.ts"() {
     "use strict";
     init_execa();
     init_bearer();
+    init_authedClient();
     init_mcp_config();
     init_spawn_claude();
     init_model_pin();
@@ -17409,9 +17466,11 @@ var init_run_scan = __esm({
     init_transcript_signals();
     init_report();
     init_github_remote();
-    SCAN_CLAUDE_TIMEOUT_MS = 45 * 60 * 1e3;
-    SCAN_PRE_SPAWN_TOKEN_MIN_LIFETIME_MS = SCAN_CLAUDE_TIMEOUT_MS + 5 * 60 * 1e3;
-    BOOTSTRAP_PROMPT_BASE = `Run the \`scan\` MCP prompt now and follow it to completion. This is a non-interactive automated run \u2014 skip any steps that pause for user confirmation (e.g. "does this hierarchy look right?"). Proceed with your best-judgement decisions rather than waiting for human input.`;
+    BOOTSTRAP_HEADLESS = `Run the \`scan\` MCP prompt now and follow it to completion. This is a non-interactive automated run \u2014 skip any steps that pause for user confirmation (e.g. "does this hierarchy look right?"). Proceed with your best-judgement decisions rather than waiting for human input.`;
+    BOOTSTRAP_INTERACTIVE = `Run the \`scan\` MCP prompt now and follow it to completion. The user is at an interactive terminal \u2014 ask them when the prompt says to, and wait for their answer.
+
+Before you call \`start_scan\`, show the user this briefing verbatim and ask them to confirm they want to go ahead. Do not start scanning until they say yes.`;
+    BOOTSTRAP_INTERACTIVE_NO_BRIEFING = `Run the \`scan\` MCP prompt now and follow it to completion. The user is at an interactive terminal \u2014 ask them when the prompt says to, and wait for their answer.`;
     PROMPT_VARIANT_RE = /^\d{2}-\d{2}-\d{2}-\d{4}(-[A-Za-z0-9_-]+)?$/;
   }
 });
@@ -17465,6 +17524,8 @@ async function dispatchScan(args) {
     } else if (arg === "--mcp-url" && next) {
       opts.mcpUrl = next;
       i2++;
+    } else if (arg === "--no-interactive") {
+      opts.interactive = false;
     } else if (arg && arg.startsWith("--")) {
       console.error(`archme scan: unknown flag '${arg}'`);
       printScanHelp();
@@ -17514,6 +17575,7 @@ Usage:
 Flags:
   --project <org/slug>     Target project. Defaults to e2e/<basename>.
   --branch <name>          Target scan branch. Defaults to <date>-<sha7>-scan.
+  --no-interactive         Run headless (no questions). For CI/automation.
   --prompt-variant <id>    Scan prompt variant. Defaults to latest.
   --mcp-url <url>          MCP base URL. Defaults to $ARCHME_MCP_BASE_URL.
 
@@ -17534,6 +17596,584 @@ var init_dispatch3 = __esm({
   }
 });
 
+// src/init/repoSize.ts
+import { stat as stat9 } from "node:fs/promises";
+import { extname, join as join17 } from "node:path";
+async function measureRepo(repoPath) {
+  const files = await gitListFiles(repoPath);
+  if (!files) return { sourceFiles: 0, sourceBytes: 0, totalFiles: 0 };
+  let sourceFiles = 0;
+  let sourceBytes = 0;
+  for (const rel of files) {
+    if (!SOURCE_EXTENSIONS.has(extname(rel).toLowerCase())) continue;
+    try {
+      const s = await stat9(join17(repoPath, rel));
+      if (!s.isFile()) continue;
+      sourceFiles++;
+      sourceBytes += s.size;
+    } catch {
+    }
+  }
+  return { sourceFiles, sourceBytes, totalFiles: files.length };
+}
+function fullReadTokens(sourceBytes) {
+  return Math.round(sourceBytes / BYTES_PER_TOKEN);
+}
+function formatCount(n2) {
+  if (n2 >= 1e6) return `${(n2 / 1e6).toFixed(1)}M`;
+  if (n2 >= 1e3) return `${(n2 / 1e3).toFixed(n2 >= 1e4 ? 0 : 1)}k`;
+  return String(n2);
+}
+function formatBytes(bytes) {
+  if (bytes >= 1024 * 1024) return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+  if (bytes >= 1024) return `${Math.round(bytes / 1024)} KB`;
+  return `${bytes} B`;
+}
+function expectedDuration(sourceFiles) {
+  if (sourceFiles < 100) return "a few minutes";
+  if (sourceFiles < 1e3) return "5\u201315 minutes";
+  return "15\u201345 minutes";
+}
+function formatRepoBriefing(m, repoPath, target) {
+  const lines = [
+    "",
+    "About to scan:",
+    `  ${repoPath}`,
+    ...target ? [`  \u2192 project ${target.project}, branch ${target.branch}`] : [],
+    `  ${formatCount(m.sourceFiles)} source files \xB7 ${formatBytes(m.sourceBytes)} (${formatCount(m.totalFiles)} files tracked)`,
+    "",
+    "What this costs:",
+    "  The scan runs Claude Code on YOUR machine, against YOUR Claude",
+    "  subscription or API key. ArchMe is not billed for it, and you are.",
+    `  Reading every source file once would be ~${formatCount(fullReadTokens(m.sourceBytes))} tokens;`,
+    "  a scan reads a fraction of that, and reports its actual usage when done.",
+    `  Expect it to take ${expectedDuration(m.sourceFiles)}.`,
+    ""
+  ];
+  if (m.sourceFiles === 0) {
+    lines.push(
+      "  No recognised source files found \u2014 is this the right directory?",
+      ""
+    );
+  }
+  return lines.join("\n");
+}
+var BYTES_PER_TOKEN, SOURCE_EXTENSIONS;
+var init_repoSize = __esm({
+  "src/init/repoSize.ts"() {
+    "use strict";
+    init_repo_walk();
+    BYTES_PER_TOKEN = 4;
+    SOURCE_EXTENSIONS = /* @__PURE__ */ new Set([
+      ".ts",
+      ".tsx",
+      ".js",
+      ".jsx",
+      ".mjs",
+      ".cjs",
+      ".py",
+      ".go",
+      ".java",
+      ".rb",
+      ".rs",
+      ".swift",
+      ".kt",
+      ".kts",
+      ".c",
+      ".h",
+      ".cc",
+      ".cpp",
+      ".hpp",
+      ".cs",
+      ".php",
+      ".scala",
+      ".ex",
+      ".exs",
+      ".sql",
+      ".sh",
+      ".bash"
+    ]);
+  }
+});
+
+// src/init/watchRepo.ts
+async function watchRepoForProject(input) {
+  const { supabase, orgId, projectId, repoSlug, branch } = input;
+  if (!repoSlug) {
+    return {
+      watched: false,
+      reason: "no GitHub remote found, so pushes cannot be linked to this project. Add a remote and re-run `archme init` for continuous updates."
+    };
+  }
+  if (!orgId) {
+    return { watched: false, reason: "could not resolve your organization." };
+  }
+  const [owner, name] = repoSlug.split("/");
+  if (!owner || !name) {
+    return { watched: false, reason: `could not parse repo slug \`${repoSlug}\`.` };
+  }
+  const { data: installs, error: installErr } = await supabase.from("org_github_installations").select("installation_id").eq("org_id", orgId).limit(1);
+  if (installErr) {
+    return {
+      watched: false,
+      reason: `could not check GitHub App installations (${installErr.message}).`
+    };
+  }
+  const installationId = installs?.[0]?.installation_id;
+  if (!installationId) {
+    return {
+      watched: false,
+      reason: "the ArchMe GitHub App is not installed on this org yet \u2014 connect it in the app to get automatic updates on every push."
+    };
+  }
+  const { error } = await supabase.rpc("watch_repo", {
+    p_org_id: orgId,
+    p_project_id: projectId,
+    p_repo_owner: owner,
+    p_repo_name: name,
+    p_branch: branch,
+    p_installation_id: installationId
+  });
+  if (error) {
+    return { watched: false, reason: `could not watch the repo (${error.message}).` };
+  }
+  return { watched: true };
+}
+var init_watchRepo = __esm({
+  "src/init/watchRepo.ts"() {
+    "use strict";
+  }
+});
+
+// src/init/gitContext.ts
+async function git(cwd, args) {
+  const { stdout } = await execa("git", args, { cwd });
+  return stdout.trim();
+}
+async function resolveGitContext(repoPath) {
+  let root;
+  try {
+    root = await git(repoPath, ["rev-parse", "--show-toplevel"]);
+  } catch {
+    throw new Error(
+      `\`${repoPath}\` is not inside a git repository \u2014 run \`archme init\` from a repo, or pass its path`
+    );
+  }
+  try {
+    await git(root, ["rev-parse", "HEAD"]);
+  } catch {
+    throw new Error(
+      `\`${root}\` is a git repository with no commits yet \u2014 make a commit first, then run \`archme init\``
+    );
+  }
+  let branch = "";
+  try {
+    branch = await git(root, ["rev-parse", "--abbrev-ref", "HEAD"]);
+  } catch {
+    branch = "";
+  }
+  if (!branch || branch === "HEAD") {
+    try {
+      const ref = await git(root, ["symbolic-ref", "refs/remotes/origin/HEAD"]);
+      branch = ref.replace(/^refs\/remotes\/origin\//, "");
+    } catch {
+      branch = "main";
+    }
+  }
+  let repoSlug = null;
+  try {
+    const url = await git(root, ["remote", "get-url", "origin"]);
+    repoSlug = url ? parseGitHubRepo(url) : null;
+  } catch {
+    repoSlug = null;
+  }
+  return { root, branch, repoSlug };
+}
+var init_gitContext = __esm({
+  "src/init/gitContext.ts"() {
+    "use strict";
+    init_execa();
+    init_github_remote();
+  }
+});
+
+// src/init/plan.ts
+function shouldRunScan(d) {
+  if (d.skipScan) return false;
+  if (d.force) return true;
+  return !d.architectureExists;
+}
+function buildProjectMcpUrl(mcpBaseUrl, project, branch) {
+  const url = new URL(mcpBaseUrl);
+  url.searchParams.set("project", project);
+  url.searchParams.set("branch", branch);
+  return url.toString();
+}
+function resolveAppOrigin(mcpBaseUrl, override) {
+  if (override) return override.replace(/\/$/, "");
+  return deriveWebOrigin(mcpBaseUrl, "fallback");
+}
+function buildInstallAgentUrl(appOrigin, mcpUrl) {
+  const url = new URL("/api/install-agent", appOrigin);
+  url.searchParams.set("mcp_url", mcpUrl);
+  return url.toString();
+}
+var init_plan = __esm({
+  "src/init/plan.ts"() {
+    "use strict";
+    init_web_url();
+  }
+});
+
+// src/init/run-init.ts
+import { mkdtemp as mkdtemp4, rm as rm8, writeFile as writeFile11 } from "node:fs/promises";
+import { tmpdir as tmpdir4 } from "node:os";
+import { join as join18 } from "node:path";
+function initScanBranch(defaultBranch) {
+  return normalizeScanBranchName(defaultBranch);
+}
+async function defaultFetchInstallScript(url) {
+  const resp = await fetch(url);
+  if (!resp.ok) {
+    throw new Error(`could not fetch agent installer (${resp.status} ${resp.statusText}) from ${url}`);
+  }
+  return await resp.text();
+}
+async function defaultRunInstallScript(script, cwd) {
+  const dir = await mkdtemp4(join18(tmpdir4(), "archme-init-"));
+  const scriptPath = join18(dir, "install-agent.sh");
+  try {
+    await writeFile11(scriptPath, script, { mode: 448 });
+    await execa("sh", [scriptPath], { cwd, stdio: "inherit" });
+  } finally {
+    await rm8(dir, { recursive: true, force: true });
+  }
+}
+async function runInit(opts, deps = {}) {
+  const log = opts.log ?? ((msg) => console.log(msg));
+  const login = deps.login ?? runLogin;
+  const fetchInstallScript = deps.fetchInstallScript ?? defaultFetchInstallScript;
+  const runInstallScript = deps.runInstallScript ?? defaultRunInstallScript;
+  const scan = deps.scan ?? runScan;
+  const authenticate = deps.authenticate ?? createAuthedClient;
+  const resolveProject = deps.resolveProject ?? resolveOrCreateProject;
+  const resolveOrgSlug = deps.resolveOrgSlug ?? resolveCurrentOrgSlug;
+  const fetchArchitecture = deps.fetchArchitecture ?? fetchArchitectureDetail;
+  const loadCreds = deps.loadCredentials ?? loadAllCredentials;
+  const gitContext = deps.gitContext ?? resolveGitContext;
+  const measure = deps.measure ?? measureRepo;
+  const watchRepo = deps.watchRepo ?? watchRepoForProject;
+  const cfg = resolveConfig();
+  const git2 = await gitContext(opts.repoPath);
+  const repoPath = git2.root;
+  const { credentials } = await loadCreds(cfg.supabaseUrl);
+  const signedIn = credentials.length > 0;
+  if (!signedIn) {
+    log("\u2192 signing you in\u2026");
+    await login();
+  } else {
+    log("\u2713 already signed in");
+  }
+  const authed = await authenticate({
+    supabaseUrl: cfg.supabaseUrl,
+    supabaseAnonKey: cfg.supabaseAnonKey,
+    clientId: cfg.archmeDaemonClientId,
+    preSpawnMinLifetimeMs: SCAN_PRE_SPAWN_TOKEN_MIN_LIFETIME_MS
+  });
+  log(`  signed in as ${authed.identity}`);
+  let fullSlug = opts.project;
+  if (!fullSlug) {
+    const orgId = authed.orgId;
+    if (!orgId) {
+      throw new Error(
+        "could not resolve your organization \u2014 run `archme login` again, or pass --project <org>/<slug>"
+      );
+    }
+    const orgSlug = await resolveOrgSlug(authed.supabase, orgId);
+    if (!orgSlug) {
+      throw new Error(
+        `paired org ${orgId} no longer exists \u2014 run \`archme login\` again, or pass --project <org>/<slug>`
+      );
+    }
+    fullSlug = defaultProjectSlug(orgSlug, repoPath);
+  }
+  const project = await resolveProject(
+    authed.supabase,
+    authed.userId,
+    fullSlug
+  );
+  log(
+    project.created ? `\u2713 created project ${fullSlug}` : `\u2713 using existing project ${fullSlug}`
+  );
+  const scanBranch = initScanBranch(project.defaultBranch);
+  const detail = await fetchArchitecture(
+    authed.supabase,
+    project.projectId,
+    scanBranch
+  );
+  const architectureExists = detail.components.length > 0;
+  const ran = signedIn ? [] : ["login"];
+  ran.push("project");
+  const mcpUrl = buildProjectMcpUrl(cfg.archmeMcpBaseUrl, fullSlug, scanBranch);
+  const appOrigin = resolveAppOrigin(cfg.archmeMcpBaseUrl, opts.appOrigin);
+  log("\u2192 installing agent config (.mcp.json, CLAUDE.md, architecture skill)\u2026");
+  const script = await fetchInstallScript(buildInstallAgentUrl(appOrigin, mcpUrl));
+  await runInstallScript(script, repoPath);
+  ran.push("agent-config");
+  const watched = await watchRepo({
+    supabase: authed.supabase,
+    orgId: authed.orgId,
+    projectId: project.projectId,
+    repoSlug: git2.repoSlug,
+    branch: git2.branch,
+    log
+  });
+  if (!watched.watched && watched.reason) {
+    log(`  note: ${watched.reason}`);
+  }
+  const webUrl = buildWebUrl({
+    apiUrl: cfg.archmeMcpBaseUrl,
+    orgSlug: project.orgSlug,
+    projectSlug: project.projectSlug,
+    branchName: scanBranch,
+    defaultBranch: project.defaultBranch,
+    onMalformed: "throw"
+  });
+  const wantsScan = shouldRunScan({
+    architectureExists,
+    force: opts.force,
+    skipScan: opts.skipScan
+  });
+  if (!wantsScan) {
+    if (architectureExists && !opts.force) {
+      log(`\u2713 ${fullSlug} already has an architecture \u2014 skipping the scan (use --force to re-scan)`);
+    }
+    log(`
+Your board: ${webUrl}`);
+    return { exitCode: 0, project: fullSlug, branch: scanBranch, webUrl, ran };
+  }
+  const measurement = await measure(repoPath);
+  const briefing = formatRepoBriefing(measurement, repoPath, {
+    project: fullSlug,
+    branch: scanBranch
+  });
+  log("\u2192 handing over to Claude Code \u2014 it will confirm before scanning");
+  const result = await scan({
+    repoPath,
+    project: fullSlug,
+    // --yes means unattended: run headless and skip the agent's confirmations.
+    interactive: !opts.yes,
+    briefing,
+    // Explicit: without it runScan derives a dated `<date>-<sha7>-scan` branch
+    // that nothing else in this flow knows about.
+    branch: scanBranch,
+    log
+  });
+  ran.push("scan");
+  const finalUrl = result.webUrl || webUrl;
+  if (result.exitCode === 0) {
+    log(`
+\u2713 Done. Your architecture: ${finalUrl}`);
+    log("  Restart Claude Code in this repo to pick up the archme MCP server.");
+    if (watched.watched) {
+      log("");
+      log("Keeping it up to date \u2014 one more step:");
+      log("  Pushes to this repo now queue an architecture update, but");
+      log("  something has to process that queue, and nothing does yet.");
+      log("");
+      log("  Run the agent yourself, on a machine that stays on:");
+      log("");
+      log("    archme daemon start");
+      log("");
+      log("  Each update counts tokens against your Claude account, the same");
+      log("  way this scan did. Your code is not sent to our servers \u2014 only");
+      log("  the resulting architecture.");
+      log("");
+      log("  Or get in touch at archme.io and we'll run it for you.");
+    } else {
+      log("");
+      log("Not yet set up for automatic updates:");
+      log(`  ${watched.reason ?? "the repo could not be linked to this project."}`);
+      log("  Until that is resolved, this architecture will not track new");
+      log("  commits \u2014 re-run `archme init` once it is.");
+    }
+  }
+  return {
+    exitCode: result.exitCode,
+    project: fullSlug,
+    branch: result.branchName || scanBranch,
+    webUrl: finalUrl,
+    ran
+  };
+}
+var init_run_init = __esm({
+  "src/init/run-init.ts"() {
+    "use strict";
+    init_execa();
+    init_defaults();
+    init_enroll();
+    init_credentials();
+    init_authedClient();
+    init_run_scan();
+    init_architecture_detail();
+    init_repoSize();
+    init_watchRepo();
+    init_gitContext();
+    init_web_url();
+    init_plan();
+  }
+});
+
+// src/init/args.ts
+function parseInitArgs(argv) {
+  const args = {
+    force: false,
+    skipScan: false,
+    yes: false,
+    noInteractive: false,
+    help: false
+  };
+  const positionals = [];
+  for (let i2 = 0; i2 < argv.length; i2++) {
+    const arg = argv[i2];
+    if (HELP_FLAGS.has(arg)) {
+      args.help = true;
+      return { ok: true, args };
+    }
+    if (BOOLEAN_FLAGS.has(arg)) {
+      if (arg === "--force") args.force = true;
+      else if (arg === "--yes") args.yes = true;
+      else if (arg === "--no-interactive") args.noInteractive = true;
+      else args.skipScan = true;
+      continue;
+    }
+    const eq = arg.indexOf("=");
+    const name = arg.startsWith("--") && eq > 0 ? arg.slice(0, eq) : arg;
+    if (VALUE_FLAGS.has(name)) {
+      let value;
+      if (eq > 0 && arg.startsWith("--")) {
+        value = arg.slice(eq + 1);
+      } else {
+        value = argv[i2 + 1];
+        if (value !== void 0 && value.startsWith("-")) value = void 0;
+        else i2++;
+      }
+      if (!value) return { ok: false, error: `${name} requires a value` };
+      if (name === "--project") {
+        if (!PROJECT_SLUG_RE2.test(value)) {
+          return {
+            ok: false,
+            error: `--project must be <org>/<slug> (got \`${value}\`)`
+          };
+        }
+        args.project = value;
+      } else {
+        args.appOrigin = value;
+      }
+      continue;
+    }
+    if (arg.startsWith("-")) {
+      return { ok: false, error: `unknown option \`${arg}\`` };
+    }
+    positionals.push(arg);
+  }
+  if (positionals.length > 1) {
+    return {
+      ok: false,
+      error: `expected at most one repo path, got ${positionals.length} (${positionals.join(", ")})`
+    };
+  }
+  args.repoPath = positionals[0];
+  return { ok: true, args };
+}
+var BOOLEAN_FLAGS, VALUE_FLAGS, HELP_FLAGS, PROJECT_SLUG_RE2;
+var init_args = __esm({
+  "src/init/args.ts"() {
+    "use strict";
+    BOOLEAN_FLAGS = /* @__PURE__ */ new Set([
+      "--force",
+      "--skip-scan",
+      "--yes",
+      "--no-interactive"
+    ]);
+    VALUE_FLAGS = /* @__PURE__ */ new Set(["--project", "--app-origin"]);
+    HELP_FLAGS = /* @__PURE__ */ new Set(["--help", "-h", "help"]);
+    PROJECT_SLUG_RE2 = /^[^/\s]+\/[^/\s]+$/;
+  }
+});
+
+// src/init/dispatch.ts
+var dispatch_exports4 = {};
+__export(dispatch_exports4, {
+  EX_INFRA: () => EX_INFRA2,
+  EX_OK: () => EX_OK2,
+  EX_USAGE: () => EX_USAGE2,
+  dispatchInit: () => dispatchInit,
+  printInitHelp: () => printInitHelp
+});
+import { resolve as resolve3 } from "node:path";
+function printInitHelp() {
+  console.log(`archme init \u2014 guided first-time setup for this repo
+
+Signs you in, creates a project named after the repo, installs agent config
+(.mcp.json, CLAUDE.md block, architecture skill), then hands over to an
+interactive Claude Code session that confirms the cost and runs the scan.
+
+Usage:
+  archme init [repo-path] [options]
+
+  repo-path              Defaults to the current directory.
+
+Options:
+  --project <org/slug>   Use a specific project instead of <your-org>/<repo-name>
+  --skip-scan            Set up agent config but do not scan
+  --force                Re-scan even if the project already has an architecture
+  --yes                  Run unattended (headless scan, no questions)
+  --no-interactive       Same as --yes; for automation
+  --app-origin <url>     Origin serving /api/install-agent (local development)
+  -h, --help             Show this help
+
+Requires Claude Code to be installed and authenticated \u2014 the scan runs on your
+own Claude subscription.`);
+}
+async function dispatchInit(argv) {
+  const parsed = parseInitArgs(argv);
+  if (!parsed.ok) {
+    console.error(`archme init: ${parsed.error}`);
+    printInitHelp();
+    return EX_USAGE2;
+  }
+  if (parsed.args.help) {
+    printInitHelp();
+    return EX_OK2;
+  }
+  try {
+    const result = await runInit({
+      repoPath: resolve3(parsed.args.repoPath ?? process.cwd()),
+      project: parsed.args.project,
+      appOrigin: parsed.args.appOrigin,
+      force: parsed.args.force,
+      skipScan: parsed.args.skipScan,
+      yes: parsed.args.yes || parsed.args.noInteractive
+    });
+    return result.exitCode;
+  } catch (err) {
+    console.error(`archme init: ${err instanceof Error ? err.message : String(err)}`);
+    return EX_INFRA2;
+  }
+}
+var EX_OK2, EX_INFRA2, EX_USAGE2;
+var init_dispatch4 = __esm({
+  "src/init/dispatch.ts"() {
+    "use strict";
+    init_run_init();
+    init_args();
+    EX_OK2 = 0;
+    EX_INFRA2 = 3;
+    EX_USAGE2 = 78;
+  }
+});
+
 // src/auth/logout.ts
 var logout_exports = {};
 __export(logout_exports, {
@@ -17580,7 +18220,7 @@ var init_logout = __esm({
 
 // src/cli.ts
 init_enroll();
-var KNOWN_COMMANDS = /* @__PURE__ */ new Set(["daemon", "analyze", "login", "logout", "keys", "scan"]);
+var KNOWN_COMMANDS = /* @__PURE__ */ new Set(["daemon", "analyze", "login", "logout", "keys", "scan", "init"]);
 function route(argv) {
   if (argv.length === 0) return { name: "help", args: [] };
   const [first, ...rest] = argv;
@@ -17658,6 +18298,10 @@ async function main(argv) {
       const { dispatchScan: dispatchScan2 } = await Promise.resolve().then(() => (init_dispatch3(), dispatch_exports3));
       return await dispatchScan2(r.args);
     }
+    case "init": {
+      const { dispatchInit: dispatchInit2 } = await Promise.resolve().then(() => (init_dispatch4(), dispatch_exports4));
+      return await dispatchInit2(r.args);
+    }
     case "logout": {
       const { runLogout: runLogout2 } = await Promise.resolve().then(() => (init_logout(), logout_exports));
       return await runLogout2(r.args);
@@ -17671,6 +18315,8 @@ function printHelp() {
   console.log(`archme \u2014 architecture-aware code analysis and daemon
 
 Usage:
+  archme init [repo-path]              Guided first-time setup (login, project,
+                                       agent config, scan)
   archme daemon <subcommand>           Manage the local daemon as a service
                                        (start|stop|status|logs|restart|enable|
                                         disable|install|uninstall|run)
@@ -17679,7 +18325,8 @@ Usage:
   archme login | logout                Authenticate with archme
   archme keys list|create|revoke       Manage MCP API keys
 
-Run 'archme daemon --help', 'archme analyze --help', or 'archme scan --help' for subcommand help.`);
+Run 'archme init --help', 'archme daemon --help', 'archme analyze --help', or
+'archme scan --help' for subcommand help.`);
 }
 
 // src/bin.ts

package/package.json

@@ -1,15 +1,17 @@
 {
   "name": "@archme/cli",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "archme command-line interface: daemon, analyze, auth, key management",
   "type": "module",
+  "license": "SEE LICENSE IN LICENSE",
   "bin": {
     "archme": "dist/cli.js"
   },
   "files": [
     "dist",
     "SKILL.md",
-    "README.md"
+    "README.md",
+    "LICENSE"
   ],
   "engines": {
     "node": ">=20.0.0"