nomarmy 0.1.0-alpha.17 → 0.1.0-alpha.18

package/README.md

@@ -4,6 +4,7 @@
   <a href="https://github.com/rayson-tech/nomarmy/actions/workflows/ci.yml"><img src="https://github.com/rayson-tech/nomarmy/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
   <a href="https://www.npmjs.com/package/nomarmy"><img src="https://img.shields.io/npm/v/nomarmy/alpha?label=npm%40alpha" alt="npm"></a>
   <a href="https://github.com/rayson-tech/nomarmy/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-Apache%202.0-blue.svg" alt="License: Apache 2.0"></a>
+  <a href="https://github.com/rayson-tech/nomarmy/blob/main/docs/feature-runs.md"><img src="https://raw.githubusercontent.com/rayson-tech/nomarmy/main/.github/nomarmy-badge.svg" alt="nomArmy: AI worker claims checked on this repository"></a>
 </p>
 
 <p align="center"><em>Every byte verified.</em> 🍪</p>
@@ -50,6 +51,8 @@ Stuck? `nomarmy doctor` checks the machine and `nomarmy health` checks everythin
 
 Failing verification stays failed, unconditionally. A malformed report isn't automatically a failure: if the repository changed, nomArmy verifies independently and may recover the work. And the checks aren't the General's to waive: a repo's `.nomarmy.yml` policy (on by default for new repos) makes verification and the revert check mandatory for every job.
 
+**Showing what was checked.** When a `/feature` run finishes, the General gets a "Verified by nomArmy" block for the pull request: how many "done, tests pass" claims held up, how many nomArmy caught and why, and the new tests shown to fail without their change. `nomarmy stats --share` prints the same for any period, and `nomarmy stats --badge` writes a README badge like `nomArmy | 78 claims checked · 11 caught`. Every number comes from the verified records.
+
 **Checking without building** costs nothing: `mode: verify` runs a verification profile against any branch, with no worker and no model tokens.
 
 **Want deeper checks?** Three optional [validators](https://github.com/rayson-tech/nomarmy/blob/main/docs/validators.md) go further, each only adding review flags: mutation testing (do the tests pin down the changed lines?), Jev (do a scout's citations support its findings, does a report match its diff?) and a model judge (acceptance criteria, weakened tests).

package/bin/nomarmy.mjs

@@ -32,12 +32,16 @@ import { setupSteps, formatSetupSteps, runSetupPlaybook } from "../lib/setup-ste
 import { readUsageSnapshots } from "../lib/usage-limits.mjs";
 import { pickMachine, planResize } from "../lib/sandbox-vm.mjs";
 import { listProcesses, staleSessions, formatStaleSessions } from "../lib/stale-sessions.mjs";
+import { readSetting, writeSetting, writeEnvLine, userCommonPath, userProfilePath, profilePathFor, tildePath } from "../lib/user-config.mjs";
 import { MIN_PODMAN_VM_MB } from "../lib/doctor.mjs";
 import { liveLeases } from "../lib/slots.mjs";
 import { ensureProviderConfig } from "../lib/openclaw-config.mjs";
 import { recordProbeSuccess } from "../lib/health.mjs";
 import { pruneJobRuntime } from "../lib/prune.mjs";
 import { SUBSCRIPTION_VENDORS, parseOpenclawVersion, versionAtLeast, parseCatalogModels, parseCliLoginStatus, probeOutcome, parseMuseAuthDescriptor, extractMintedKey } from "../lib/subscription-setup.mjs";
+import { ensureOpenClawOnPath } from "../lib/openclaw-path.mjs";
+// OpenClaw in ~/.npm-global/bin (no writable npm prefix) is found without the operator editing PATH.
+ensureOpenClawOnPath();
 
 // Add a new coordinator: add its name here, teach commandExists/connectTarget
 // about it below (a JSON-file target like Cursor has no PATH binary to check
@@ -239,7 +243,7 @@ Usage: nomarmy <command> [options]
                   project for this repository, committed for the team
                   (.mcp.json or .cursor/mcp.json, running \`nomarmy mcp\`).
                   Codex has only the user scope.
-  stats [--since 7d|<date>] [--until <date>] [--role <role>] [--model <model>] [--details] [--all-suggestions]
+  stats [--since 7d|<date>] [--until <date>] [--role <role>] [--model <model>] [--run <id>] [--details] [--all-suggestions] [--share] [--badge [path]]
         [--repo <path|name>] [--all-repos] [--json]
                   What nomArmy's job records show for this repository (or
                   all): volume by role and model, code committed, time,
@@ -468,15 +472,9 @@ function readEnvValue(filePath, key) {
   return m ? m[1].trim() : null;
 }
 
-/** Read-modify-write one KEY=VALUE line, replacing it if present, appending if not -- the exact pattern scripts/select-model.mjs already uses for config/common.env. */
-function writeEnvLine(filePath, key, value) {
-  const existingText = fs.existsSync(filePath) ? fs.readFileSync(filePath, "utf8") : "";
-  const line = `${key}=${value}`;
-  const updated = new RegExp(`^${key}=.*$`, "m").test(existingText)
-    ? existingText.replace(new RegExp(`^${key}=.*$`, "m"), line)
-    : `${existingText.trimEnd()}\n${line}\n`.replace(/^\n/, "");
-  fs.writeFileSync(filePath, updated);
-}
+// Your settings live in ~/.config/nomarmy/, over the package's config/
+// defaults, so an update can't reset them (lib/user-config.mjs).
+const setting = (key) => readSetting(key, { nomarmyRoot });
 
 // Each entry's repo/quant/alias is verified against this project's own real
 // usage (downloaded, loaded, dispatched against), not guessed from a model
@@ -495,6 +493,14 @@ function writeEnvLine(filePath, key, value) {
  * not left to fail only at the very end via schema validation with no
  * indication of which of several answers was the problem.
  */
+/** A numbered choice, asked again until it's one of 1..count (an empty or mistyped answer used to end the whole flow). */
+async function askChoice(rl, count) {
+  const answer = await askUntilValid(rl, "Choice: ", { pattern: new RegExp(`^([1-9]|[1-9][0-9])$`), invalidMessage: `Choose a number from 1 to ${count}.` });
+  if (Number(answer) >= 1 && Number(answer) <= count) return Number(answer) - 1;
+  console.log(c.red(`  ✗ Choose a number from 1 to ${count}.`));
+  return askChoice(rl, count);
+}
+
 async function askUntilValid(rl, prompt, { pattern, invalidMessage, allowEmpty = false, fallback = "" }) {
   for (;;) {
     const answer = (await rl.question(c.bold(prompt))).trim();
@@ -527,15 +533,15 @@ async function askSecret(rl, prompt) {
 
 const KNOWN_MODELS = {
   default: {
-    label: "Qwen3-Coder-Next (shipped default; no thinking mode -- 0 failures across every case tested tonight)",
+    label: "Qwen3-Coder-Next · 48 GB download · the most reliable in our tests (recommended)",
     repo: "Qwen/Qwen3-Coder-Next-GGUF", quant: "Q4_K_M", alias: "qwen3-coder-next", thinking: false, recommended: true,
   },
   "gpt-oss-20b": {
-    label: "gpt-oss-20b (thinking, use reasoning: medium -- fastest of every model tested on the hardest case: 62s/0 failures; reasoning: high on the SAME ticket was the worst result measured: 318s/4 failures)",
+    label: "gpt-oss-20b · 12 GB download · the fastest; keep reasoning at medium",
     repo: "ggml-org/gpt-oss-20b-GGUF", quant: "MXFP4", alias: "gpt-oss-20b", thinking: true,
   },
   "qwen3.6-27b": {
-    label: "Qwen3.6-27B (thinking, use reasoning: medium -- best measured reliability, noticeably slower per-token; reasoning: high caused a full timeout on an open-ended task)",
+    label: "Qwen3.6-27B · 17 GB download · very reliable, slower; keep reasoning at medium",
     repo: "unsloth/Qwen3.6-27B-GGUF", quant: "Q4_K_M", alias: "qwen3.6-27b", thinking: true,
   },
 };
@@ -588,14 +594,14 @@ function defaultLocalProfile() {
 // `install`: the one setup recorded, else the install marker's, else the
 // execution mode's, else (a working local install) install.sh's default.
 function setupProfileState() {
-  const common = path.join(nomarmyRoot, "config", "common.env");
-  const chosen = readEnvValue(common, "NOMARMY_SETUP_PROFILE");
+  const common = userCommonPath();
+  const chosen = setting("NOMARMY_SETUP_PROFILE");
   const probeCommand = (binary, args) => {
     const result = spawnSync(binary, args, { encoding: "utf8", timeout: 10000 });
     return result.status === 0 ? result.stdout.trim() : "";
   };
-  const profileFile = chosen ? path.join(nomarmyRoot, "config", "profiles", `${chosen}.env`) : null;
-  const root = (process.env.NOMARMY_INSTALL_ROOT || (profileFile && readEnvValue(profileFile, "NOMARMY_INSTALL_ROOT")) || readEnvValue(common, "NOMARMY_INSTALL_ROOT") || "$HOME/.local/share/nomarmy-local-agents").replace(/\$HOME|\$\{HOME\}/g, os.homedir());
+  const profileFile = profilePathFor(chosen, { nomarmyRoot });
+  const root = (process.env.NOMARMY_INSTALL_ROOT || (profileFile && readEnvValue(profileFile, "NOMARMY_INSTALL_ROOT")) || setting("NOMARMY_INSTALL_ROOT") || "$HOME/.local/share/nomarmy-local-agents").replace(/\$HOME|\$\{HOME\}/g, os.homedir());
   let marker = null;
   try { marker = JSON.parse(fs.readFileSync(path.join(root, "install.json"), "utf8")); } catch (error) { if (error.code !== "ENOENT") marker = {}; }
   const version = probeCommand("openclaw", ["--version"]);
@@ -603,7 +609,7 @@ function setupProfileState() {
   const registered = !marker && Boolean(version) && ["claude", "codex"].some((name) => spawnSync(name, ["mcp", "get", "nomarmy-local-worker"], { stdio: "ignore", timeout: 10000 }).status === 0);
   // An install from before setup recorded its profile: the marker's, else the
   // execution mode's, else (a working local install) install.sh's default.
-  const execution = readEnvValue(common, "NOMARMY_EXECUTION");
+  const execution = setting("NOMARMY_EXECUTION");
   const profile = chosen ?? marker?.profile
     ?? (["hosted", "remote", "bedrock"].includes(execution) ? execution : null)
     ?? (registered ? defaultLocalProfile() : null);
@@ -614,7 +620,7 @@ function setupChecklist() {
   const { common, profile, marker, version, registered } = setupProfileState();
   const project = setupProjectDir();
   return setupSteps({
-    mode: () => ({ profile, host: readEnvValue(common, "NOMARMY_LLAMA_HOST"), port: readEnvValue(common, "NOMARMY_LLAMA_PORT") }),
+    mode: () => ({ profile, host: setting("NOMARMY_LLAMA_HOST"), port: setting("NOMARMY_LLAMA_PORT") }),
     install: () => ({ marker, version, registered }),
     agents: () => Object.keys(loadAgents(globalConfigDir()).agents),
     army: () => {
@@ -652,6 +658,15 @@ async function cmdSetup() {
       const steps = setupChecklist();
       return json ? out(steps) : console.log(formatSetupSteps(steps));
     }
+    // What's ahead, before the first question: a practice run found setup
+    // felt heavy mostly because nothing said how much of it there was.
+    if (setupChecklist().find((step) => step.status === "todo")?.id === "mode") {
+      console.log(`${c.bold("🍪 nomArmy setup")}\n\nAbout 10 to 20 minutes, one step at a time; stop any time and ${c.cyan("nomarmy setup")} picks up where you left off.`);
+      console.log(c.dim("  1. Where models run: your API and subscription agents, or a model on this machine"));
+      console.log(c.dim("  2. Install: OpenClaw (runs the models) and Podman (the sandbox every job runs in; on macOS a small VM, about a 1 GB download)"));
+      console.log(c.dim("  3. Agents: log in to your subscription or add an API key"));
+      console.log(c.dim("  4. Roles, this repo's checks, and a final health check\n"));
+    }
     process.exitCode = await runSetupPlaybook({
       evaluate: setupChecklist, print: console.log, run: runSetupChild,
       ask: async (prompt) => {
@@ -670,10 +685,8 @@ async function cmdSetup() {
       if (choice === "1") argv.push("--hosted");
       if (choice === "3") argv.push("--llama-url", (await rl.question("Server URL: ")).trim());
       if (choice === "4") {
-        const common = path.join(nomarmyRoot, "config", "common.env");
-        fs.mkdirSync(path.dirname(common), { recursive: true });
-        writeEnvLine(common, "NOMARMY_EXECUTION", "bedrock");
-        writeEnvLine(common, "NOMARMY_SETUP_PROFILE", "bedrock");
+        writeSetting("NOMARMY_EXECUTION", "bedrock");
+        writeSetting("NOMARMY_SETUP_PROFILE", "bedrock");
         console.log("Next: nomarmy install");
         return;
       }
@@ -684,7 +697,7 @@ async function cmdSetup() {
   if (hosted && hasLlamaUrl) throw new Error("--hosted and --llama-url cannot be used together.");
 
   if (hosted || hasLlamaUrl) {
-    const commonPath = path.join(nomarmyRoot, "config", "common.env");
+    const commonPath = userCommonPath();
 
     if (hosted) {
       const next = [
@@ -692,11 +705,10 @@ async function cmdSetup() {
         "nomarmy agents add",
         "nomarmy army init --agent <name>",
       ];
-      fs.mkdirSync(path.dirname(commonPath), { recursive: true });
       writeEnvLine(commonPath, "NOMARMY_EXECUTION", "hosted");
       writeEnvLine(commonPath, "NOMARMY_SETUP_PROFILE", "hosted");
       if (json) return out({ written: commonPath, execution: "hosted", next });
-      console.log(c.green(`✓ Wrote NOMARMY_EXECUTION=hosted to ${path.relative(nomarmyRoot, commonPath)}.`));
+      console.log(c.green(`✓ Jobs will run on your API and subscription agents (saved in ${tildePath(commonPath)}).`));
       console.log(c.dim("\nNext:"));
       for (const step of next) console.log(`  ${c.bold(step)}`);
       return;
@@ -724,7 +736,7 @@ async function cmdSetup() {
     console.log(reachable
       ? c.green(`✓ llama-server is reachable at ${healthUrl}.`)
       : c.yellow(`⚠ llama-server is not reachable at ${healthUrl} right now; configuration was still written.`));
-    console.log(c.green(`✓ Wrote the remote llama-server settings to ${path.relative(nomarmyRoot, commonPath)}.`));
+    console.log(c.green(`✓ Wrote the remote llama-server settings to ${tildePath(commonPath)}.`));
     console.log(c.dim("\nNext:"));
     console.log(`  ${c.bold(next)}`);
     return;
@@ -753,10 +765,10 @@ async function cmdSetup() {
       console.log(isCloud
         ? `Execution is '${execution}' -- hosted inference, local hardware does not bound this.\n`
         : `Hardware: ${c.cyan(`${hardware.platform}/${hardware.arch}`)}, ${hardware.cpu?.logicalCores ?? "?"} logical cores, ${(hardware.memory?.totalBytes / 1024 ** 3).toFixed(1)} GiB RAM\n`);
-      console.log(`More noms ${c.dim(`(confidence: ${res.confidence})`)}: ${c.green(res.summary ?? JSON.stringify(res.env))}`);
-      if (res.nominal && !res.nominal.sameAsRecommended) {
-        console.log(`Nominal: ${res.nominal.fits ? c.dim(res.nominal.summary) : c.red(`${res.nominal.summary} DOES NOT FIT either -- nothing on this machine does.`)}`);
-      }
+      // Plain words; the exact settings are shown before anything is written.
+      const plain = (env) => { const n = Number(env?.NOMARMY_MAX_WORKERS ?? env?.NOMARMY_LLAMA_PARALLEL ?? 1), ctx = Math.round(Number(env?.NOMARMY_LLAMA_CONTEXT ?? 0) / Math.max(1, Number(env?.NOMARMY_LLAMA_PARALLEL ?? 1)) / 1024); return `${n} local job${n === 1 ? "" : "s"} at a time${ctx ? `, ${ctx}K tokens of context each` : ""}`; };
+      console.log(`This machine fits ${c.green(plain(res.env))}${res.confidence === "low" ? c.dim(" (an estimate)") : ""}.`);
+      if (res.nominal && !res.nominal.fits) console.log(c.red("Even one local job doesn't fit in this machine's memory: choose hosted instead (nomarmy setup --choose)."));
     }
 
     // "More noms" fits as many noms as memory allows; "nominal" is 1 worker
@@ -774,8 +786,8 @@ async function cmdSetup() {
         if (sizingTier !== "more" && sizingTier !== "nominal") throw new Error('--tier must be "more" or "nominal".');
       } else {
         console.log(`\n${c.bold("Which sizing?")}`);
-        console.log(`  ${c.cyan("1.")} More noms -- as many as fit in memory`);
-        console.log(`  ${c.cyan("2.")} Nominal -- 1 nom, matching this project's own shipped profiles`);
+        console.log(`  ${c.cyan("1.")} As many at once as fit in memory`);
+        console.log(`  ${c.cyan("2.")} One at a time (lighter on the machine)`);
         const choice = (await rl.question(c.bold("Choice [1]: "))).trim() || "1";
         sizingTier = choice === "2" ? "nominal" : "more";
       }
@@ -794,8 +806,8 @@ async function cmdSetup() {
     }
 
     const profileName = nonInteractive ? value("profile-name") : (await rl.question(`\nProfile name [${hardware?.appleSilicon ? "macbook-pro" : "custom"}]: `)).trim() || (hardware?.appleSilicon ? "macbook-pro" : "custom");
-    const profilePath = path.join(nomarmyRoot, "config", "profiles", `${profileName}.env`);
-    const commonPath = path.join(nomarmyRoot, "config", "common.env");
+    const profilePath = userProfilePath(profileName);
+    const commonPath = userCommonPath();
 
     const profileWrites = { ...sizingEnv };
     if (!isCloud) {
@@ -808,10 +820,10 @@ async function cmdSetup() {
     }
 
     if (!json) {
-      console.log(c.bold(`\nAbout to write ${path.relative(nomarmyRoot, profilePath)}:`));
+      console.log(c.bold(`\nAbout to write ${tildePath(profilePath)}:`));
       for (const [k, v] of Object.entries(profileWrites)) console.log(c.dim(`  ${k}=${v}`));
       if (model?.kind === "known") {
-        console.log(c.bold(`\nAnd ${path.relative(nomarmyRoot, commonPath)}:`));
+        console.log(c.bold(`\nAnd ${tildePath(commonPath)}:`));
         console.log(c.dim(`  NOMARMY_MODEL_REPO=${model.repo}`));
         console.log(c.dim(`  NOMARMY_MODEL_QUANT=${model.quant}`));
         console.log(c.dim(`  NOMARMY_MODEL_ALIAS=${model.alias}`));
@@ -819,8 +831,9 @@ async function cmdSetup() {
         console.log(c.dim(`  NOMARMY_MODEL_THINKING=${model.thinking}`));
       }
       if (!nonInteractive) {
-        const answer = (await rl.question(c.bold("\nWrite this configuration? [y/N] "))).trim().toLowerCase();
-        if (answer !== "y") { console.log(c.dim("Canceled; nothing written.")); return; }
+        // Yes by default: someone who accepted every suggestion shouldn't lose it all at the last Enter.
+        const answer = (await rl.question(c.bold("\nWrite this configuration? [Y/n] "))).trim().toLowerCase();
+        if (answer === "n" || answer === "no") { console.log(c.dim("Canceled; nothing written.")); return; }
       }
     }
 
@@ -842,7 +855,7 @@ async function cmdSetup() {
       writeEnvLine(commonPath, "NOMARMY_WORKER_MODEL", model.alias);
       writeEnvLine(commonPath, "NOMARMY_MODEL_THINKING", String(model.thinking));
     } else if (model?.kind === "search") {
-      const searchedAlias = readEnvValue(commonPath, "NOMARMY_MODEL_ALIAS");
+      const searchedAlias = setting("NOMARMY_MODEL_ALIAS");
       if (searchedAlias) {
         writeEnvLine(commonPath, "NOMARMY_WORKER_MODEL", searchedAlias);
         writeEnvLine(commonPath, "NOMARMY_MODEL_THINKING", String(model.thinking));
@@ -851,7 +864,7 @@ async function cmdSetup() {
 
     const installCmd = "nomarmy install";
     if (json) return out({ written: { profile: profilePath, common: model?.kind === "known" ? commonPath : null }, env: profileWrites, sizingTier, installCommand: installCmd });
-    console.log(c.green(`\n✓ Wrote ${path.relative(nomarmyRoot, profilePath)}${model?.kind === "known" ? ` and ${path.relative(nomarmyRoot, commonPath)}` : ""}.`));
+    console.log(c.green(`\n✓ Wrote ${tildePath(profilePath)}${model?.kind === "known" ? ` and ${tildePath(commonPath)}` : ""}.`));
     console.log(c.dim("\nThis proposes; it does not install. Run:\n"));
     console.log(`  ${c.bold(installCmd)}\n`);
   } finally {
@@ -880,7 +893,7 @@ function restartInference() {
   runScript("start-inference.sh", []);
 }
 async function cmdModel() {
-  const commonPath = path.join(nomarmyRoot, "config", "common.env");
+  const commonPath = userCommonPath();
   if (json) {
     const which = value("model");
     if (!KNOWN_MODELS[which]) throw new Error(`--json requires --model one of ${Object.keys(KNOWN_MODELS).join(", ")} (Hugging Face search is interactive-only).`);
@@ -904,17 +917,17 @@ async function cmdModel() {
     const model = await chooseModel(rl);
     let alias;
     if (model.kind === "search") {
-      console.log(c.green("\n✓ Done") + " -- config/common.env was already updated by the search above.");
-      alias = readEnvValue(commonPath, "NOMARMY_MODEL_ALIAS");
+      console.log(c.green("\n✓ Done") + ` -- ${tildePath(commonPath)} was already updated by the search above.`);
+      alias = setting("NOMARMY_MODEL_ALIAS");
     } else {
-      console.log(c.bold(`\nAbout to write ${path.relative(nomarmyRoot, commonPath)}:`));
+      console.log(c.bold(`\nAbout to write ${tildePath(commonPath)}:`));
       console.log(c.dim(`  NOMARMY_MODEL_REPO=${model.repo}\n  NOMARMY_MODEL_QUANT=${model.quant}\n  NOMARMY_MODEL_ALIAS=${model.alias}`));
       const answer = (await rl.question(c.bold("\nApply this model configuration? [y/N] "))).trim().toLowerCase();
       if (answer !== "y") { console.log(c.dim("Canceled; nothing changed.")); return; }
       writeEnvLine(commonPath, "NOMARMY_MODEL_REPO", model.repo);
       writeEnvLine(commonPath, "NOMARMY_MODEL_QUANT", model.quant);
       writeEnvLine(commonPath, "NOMARMY_MODEL_ALIAS", model.alias);
-      console.log(c.green(`✓ Wrote ${path.relative(nomarmyRoot, commonPath)}.`));
+      console.log(c.green(`✓ Wrote ${tildePath(commonPath)}.`));
       alias = model.alias;
     }
     if (alias) {
@@ -1371,8 +1384,7 @@ async function cmdAgentsAdd() {
       console.log(`  ${c.cyan("1.")} local         ${c.dim("the local model on this machine (no per-token bill, private; slower)")}`);
       console.log(`  ${c.cyan("2.")} api           ${c.dim("a metered API key (xAI, OpenAI, Anthropic, DeepSeek, ...)")}`);
       console.log(`  ${c.cyan("3.")} subscription  ${c.dim("your own Claude, ChatGPT or Muse Code plan (never shared)")}`);
-      kind = AGENT_KINDS[Number((await rl.question(c.bold("Choice: "))).trim()) - 1];
-      if (!kind) throw new Error("Not a valid choice.");
+      kind = AGENT_KINDS[await askChoice(rl, AGENT_KINDS.length)];
     }
     if (kind === "local") return await addLocalAgent(rl, agents);
     if (kind === "api") return await addApiAgent(rl, agents);
@@ -1409,8 +1421,7 @@ async function addLocalAgent(rl, agents) {
 async function addApiAgent(rl, agents) {
   console.log("\n" + c.bold("Which provider?"));
   API_PROVIDER_TYPES.forEach((t, i) => console.log(`  ${c.cyan(`${i + 1}.`)} ${KNOWN_PROVIDERS[t]?.label ?? t}`));
-  const provider = API_PROVIDER_TYPES[Number((await rl.question(c.bold("Choice: "))).trim()) - 1];
-  if (!provider) throw new Error("Not a valid choice.");
+  const provider = API_PROVIDER_TYPES[await askChoice(rl, API_PROVIDER_TYPES.length)];
   const info = KNOWN_PROVIDERS[provider] ?? {};
   const agent = { kind: "api", provider };
 
@@ -1485,8 +1496,7 @@ async function addSubscriptionAgent(rl, agents) {
   if (!SUBSCRIPTION_VENDORS[vendorKey]) {
     console.log("\n" + c.bold("Which subscription?"));
     vendorKeys.forEach((k, i) => console.log(`  ${c.cyan(`${i + 1}.`)} ${SUBSCRIPTION_VENDORS[k].label}`));
-    vendorKey = vendorKeys[Number((await rl.question(c.bold("Choice: "))).trim()) - 1];
-    if (!vendorKey) throw new Error(`Not a valid choice. Supported: ${vendorKeys.join(", ")}. DeepSeek and others without a plan are api agents.`);
+    vendorKey = vendorKeys[await askChoice(rl, vendorKeys.length)];
   }
   const vendor = SUBSCRIPTION_VENDORS[vendorKey];
 
@@ -2045,7 +2055,7 @@ async function maybeRemoveAgentsDir({ force }) {
  * needs manual cleanup -- an honest, bounded scope beats guessing at which
  * cache entries are "ours". */
 function resolveConfiguredModelRepos() {
-  const repo = readEnvValue(path.join(nomarmyRoot, "config", "common.env"), "NOMARMY_MODEL_REPO");
+  const repo = setting("NOMARMY_MODEL_REPO");
   return repo ? [repo] : [];
 }
 
@@ -2757,6 +2767,25 @@ async function cmdStatusline() {
   process.stdout.write(`${statusLineText({ session })}\n`);
 }
 
+// `stats --share`: markdown for a PR description or README; `--badge [path]`:
+// an SVG badge to commit, with the README line for it (lib/share.mjs).
+async function shareStats(stats) {
+  const { shareMarkdown, badgeSvg, badgeMarkdown } = await import("../lib/share.mjs");
+  const scope = value("run") ? "this feature run" : value("since") ? `since ${value("since")}` : null;
+  if (flag("share")) console.log(shareMarkdown(stats, { scope }));
+  if (flag("badge")) {
+    const given = value("badge");
+    const top = spawnSync("git", ["rev-parse", "--show-toplevel"], { encoding: "utf8" });
+    const root = top.status === 0 ? top.stdout.trim() : process.cwd();
+    const file = path.resolve(root, given ?? path.join(".github", "nomarmy-badge.svg"));
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, badgeSvg(stats));
+    const rel = path.relative(root, file).split(path.sep).join("/");
+    console.log(`${flag("share") ? "\n" : ""}${c.green("✓")} Wrote ${rel}. Commit it and add this to your README:\n\n  ${badgeMarkdown(rel)}\n`);
+    console.log(c.dim("Re-run nomarmy stats --badge after more jobs to refresh the numbers."));
+  }
+}
+
 function cmdStats() {
   const stateRoot = process.env.NOMARMY_AGENT_STATE || path.join(os.homedir(), ".local", "share", "nomarmy-local-agents");
   const records = loadJobRecords(path.join(stateRoot, "jobs"));
@@ -2768,8 +2797,9 @@ function cmdStats() {
   }
   let agentFor = () => null;
   try { agentFor = agentLookup(loadAgents(globalConfigDir()).agents, agentProviderId); } catch { /* no agents.yml: commands name <agent> */ }
-  const stats = computeStats(records, { repo, sinceMs: parseSince(value("since")), untilMs: parseSince(value("until")), role: value("role"), model: value("model"), agentFor, allSuggestions: flag("all-suggestions") });
+  const stats = computeStats(records, { repo, sinceMs: parseSince(value("since")), untilMs: parseSince(value("until")), role: value("role"), model: value("model"), runId: value("run"), agentFor, allSuggestions: flag("all-suggestions") });
   if (json) return out(stats);
+  if (flag("share") || flag("badge")) return shareStats(stats);
   console.log(flag("details") ? formatStats(stats) : formatStatsSummary(stats, { c }));
 }
 
@@ -2905,7 +2935,12 @@ async function cmdDoctor() {
   await runDoctor({ json, exit: true, env: installEnv() });
 }
 commands.doctor = cmdDoctor;
-if (!command || flag("help") || !commands[command]) usage(command && !commands[command] ? 2 : 0);
+if (!command && !flag("help")) {
+  // New users typed `nomarmy` and got the whole command reference.
+  console.log(`${c.bold("nomArmy")}: bounded coding workers with independently verified results.\n\n  New here?   ${c.cyan("nomarmy setup")}   walks you through it, one step at a time\n  All commands: ${c.cyan("nomarmy help")}\n  Docs: https://github.com/rayson-tech/nomarmy`);
+  process.exit(0);
+}
+if (flag("help") || !commands[command]) usage(command && !commands[command] ? 2 : 0);
 
 try {
   await commands[command]();

package/install.sh

@@ -87,7 +87,9 @@ echo '==> Installing nomArmy dependencies'
 
 # Put `nomarmy` on PATH. Non-fatal by design: linking needs a writable npm
 # global prefix, and the CLI is equally usable as `node bin/nomarmy.mjs`.
-if (cd "$ROOT" && npm link >/dev/null 2>&1); then
+if [[ "$ROOT" == */node_modules/* ]]; then
+  : # Installed from npm: `nomarmy` is already on PATH.
+elif (cd "$ROOT" && npm link >/dev/null 2>&1); then
   echo '==> Linked the nomarmy CLI onto PATH'
 else
   echo 'NOTE: could not link the nomarmy CLI (npm global prefix not writable).'
@@ -115,6 +117,9 @@ if ! command -v openclaw >/dev/null 2>&1; then
   else
     # No writable global prefix: install for this user, as OpenClaw's own installer does.
     npm install -g --prefix "$HOME/.npm-global" "openclaw@$OPENCLAW_VERSION" --no-audit --no-fund
+    # nomArmy finds it there on its own (lib/openclaw-path.mjs); your shell won't until PATH has it.
+    echo "NOTE: OpenClaw is in ~/.npm-global/bin. nomArmy finds it there; to run openclaw yourself, add it to PATH:"
+    echo '      echo '"'"'export PATH="$HOME/.npm-global/bin:$PATH"'"'"' >> ~/.profile'
   fi
   export PATH="$HOME/.local/bin:$HOME/.npm-global/bin:$PATH"
 fi

package/lib/connect.mjs

@@ -29,6 +29,7 @@ import { loadAgents } from "./agents.mjs";
 import { globalConfigDir } from "./army.mjs";
 import { buildNotifierApp } from "./notifier-app.mjs";
 import { recordCopySource } from "./install-freshness.mjs";
+import { readSettings, migrateUserConfig } from "./user-config.mjs";
 
 export function defaultInstallDir() {
   return process.env.NOMARMY_AGENT_INSTALL_DIR || path.join(process.env.HOME ?? process.env.USERPROFILE ?? ".", ".local", "share", "nomarmy-local-worker");
@@ -140,6 +141,9 @@ export function installClaudeStatusLine({ installDir, settingsPath = defaultClau
 }
 
 export function installMcpCopy({ nomarmyRoot, installDir, run = defaultRun }) {
+  // Settings from before they moved to ~/.config/nomarmy/ survive in the old
+  // copy's config/ until this call replaces it: rescue them first.
+  try { migrateUserConfig({ oldConfigDir: path.join(installDir, "config"), nomarmyRoot }); } catch { /* never block a connect */ }
   fs.mkdirSync(path.join(installDir, "mcp"), { recursive: true });
   fs.copyFileSync(path.join(nomarmyRoot, "package.json"), path.join(installDir, "package.json"));
   fs.copyFileSync(path.join(nomarmyRoot, "mcp", "server.mjs"), path.join(installDir, "mcp", "server.mjs"));
@@ -246,15 +250,13 @@ function readEnvValue(filePath, key) {
  * such keys yet just contributes nothing here, unchanged from before.
  */
 export function deriveWorkerModelEnv(nomarmyRoot) {
-  const commonPath = path.join(nomarmyRoot, "config", "common.env");
-  const model = readEnvValue(commonPath, "NOMARMY_WORKER_MODEL");
-  const thinking = readEnvValue(commonPath, "NOMARMY_MODEL_THINKING");
+  // Your settings over the package defaults (lib/user-config.mjs).
+  const settings = readSettings({ nomarmyRoot });
   const env = {};
-  if (model) env.NOMARMY_WORKER_MODEL = model;
-  if (thinking !== null) env.NOMARMY_WORKER_MODEL_THINKING = thinking;
+  if (settings.NOMARMY_WORKER_MODEL) env.NOMARMY_WORKER_MODEL = settings.NOMARMY_WORKER_MODEL;
+  if (settings.NOMARMY_MODEL_THINKING !== undefined) env.NOMARMY_WORKER_MODEL_THINKING = settings.NOMARMY_MODEL_THINKING;
   for (const key of ["NOMARMY_EXECUTION", "NOMARMY_LLAMA_HOST", "NOMARMY_LLAMA_PORT"]) {
-    const value = readEnvValue(commonPath, key);
-    if (value !== null) env[key] = value;
+    if (settings[key] !== undefined) env[key] = settings[key];
   }
   return env;
 }

package/lib/doctor.mjs

@@ -252,7 +252,7 @@ export function checkEndpoint(facts) {
   return {
     ok: false,
     message: `NOMARMY_EXECUTION '${execution}' is not recognized.`,
-    fix: "Set NOMARMY_EXECUTION to 'local', 'remote', 'hosted', or 'bedrock' (see config/common.env).",
+    fix: "Set NOMARMY_EXECUTION to 'local', 'remote', 'hosted', or 'bedrock' (nomarmy setup --choose, or ~/.config/nomarmy/common.env).",
   };
 }
 
@@ -282,7 +282,7 @@ function checkBedrockEndpoint(endpoint) {
     return {
       ok: false,
       message: "NOMARMY_BEDROCK_REGION is not set.",
-      fix: "Set NOMARMY_BEDROCK_REGION, e.g. export NOMARMY_BEDROCK_REGION=eu-west-2 (see config/profiles/bedrock.env).",
+      fix: "Set NOMARMY_BEDROCK_REGION, e.g. export NOMARMY_BEDROCK_REGION=eu-west-2 (or set it in ~/.config/nomarmy/common.env).",
     };
   }
   if (!regionValid) {

package/lib/openclaw-path.mjs

@@ -0,0 +1,28 @@
+// Find OpenClaw where install.sh may have put it. With no writable npm global
+// folder (common on Linux), it installs into ~/.npm-global/bin, which isn't on
+// most PATHs: a fresh-install practice run ended "OpenClaw not found", and
+// every job would then fail. The CLI and the MCP server call this first, so
+// they and everything they spawn find it.
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+const isExecutable = (file) => { try { fs.accessSync(file, fs.constants.X_OK); return fs.statSync(file).isFile(); } catch { return false; } };
+
+export function openclawFallbackDirs(home = os.homedir()) {
+  return [path.join(home, ".npm-global", "bin"), path.join(home, ".local", "bin")];
+}
+
+/** Adds the folder holding openclaw to env.PATH when it isn't already reachable. Returns the folder added, or null. */
+export function ensureOpenClawOnPath(env = process.env, { home = os.homedir(), platform = process.platform } = {}) {
+  if (env.NOMARMY_OPENCLAW_CMD) return null;
+  const sep = platform === "win32" ? ";" : ":";
+  const names = platform === "win32" ? ["openclaw.cmd", "openclaw.exe", "openclaw"] : ["openclaw"];
+  const dirs = String(env.PATH ?? "").split(sep).filter(Boolean);
+  if (dirs.some((d) => names.some((n) => isExecutable(path.join(d, n))))) return null;
+  const found = openclawFallbackDirs(home).find((d) => names.some((n) => isExecutable(path.join(d, n))));
+  if (!found) return null;
+  env.PATH = [found, ...dirs].join(sep);
+  return found;
+}

package/lib/share.mjs

@@ -0,0 +1,82 @@
+// Sharing what nomArmy verified, where people already look: a block for a
+// pull request's description, and a README badge. Every number comes from
+// the job records (lib/stats.mjs), never from a worker's report, so what
+// gets shared is evidence, not a claim.
+
+const REPO_URL = "https://github.com/rayson-tech/nomarmy";
+
+/** Claims that held up and those caught, from computeStats' claimVsEvidence. */
+function claims(stats) {
+  const cv = stats.claimVsEvidence;
+  const caught = cv.verificationFailed + cv.revertStillPassed;
+  return { total: cv.claimedDone, caught, held: cv.claimedDone - caught, cv };
+}
+
+/**
+ * Markdown for a pull request (or anywhere): what the workers claimed, what
+ * nomArmy caught, the tests shown to catch their change, and high-stakes
+ * reviews. `scope` names what it covers ("this feature run", "the last 7 days").
+ */
+export function shareMarkdown(stats, { scope = null } = {}) {
+  const { total, caught, held, cv } = claims(stats);
+  const rows = [];
+  if (total) {
+    const why = [cv.verificationFailed && `${cv.verificationFailed} failed when nomArmy ran the tests itself`, cv.revertStillPassed && `${cv.revertStillPassed} had tests that pass with the change reverted`].filter(Boolean).join(", ");
+    rows.push(["Worker claims checked", `${held} of ${total} "done, tests pass" claims held up${caught ? `; ${caught} caught (${why})` : ""}`]);
+  } else rows.push(["Worker claims checked", "none reported \"done, tests pass\""]);
+  if (cv.provenTestFiles) rows.push(["Tests proven", `${cv.provenTestFiles} new test file(s) shown to fail without their change`]);
+  if (stats.code?.committedJobs) rows.push(["Work committed", `${stats.code.committedJobs} verified job(s), +${stats.code.linesAdded} / -${stats.code.linesRemoved} lines`]);
+  if (stats.highStakes?.jobs) rows.push(["High-stakes changes", `${stats.highStakes.jobs}, ${stats.highStakes.reviewed === stats.highStakes.jobs ? "all" : stats.highStakes.reviewed} independently reviewed`]);
+  return [
+    `### ✓ Verified by nomArmy${scope ? ` (${scope})` : ""}`,
+    "",
+    "| | |",
+    "|---|---|",
+    ...rows.map(([k, v]) => `| ${k} | ${v} |`),
+    "",
+    `<sub>From nomArmy's verified job records, not the workers' own reports. [What is nomArmy?](${REPO_URL})</sub>`,
+  ].join("\n");
+}
+
+const esc = (s) =>
+  String(s)
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&#39;");
+// Verdana 11px, the badge convention: rough widths by letter shape, plus padding.
+function textWidth(s) {
+  let w = 0;
+  for (const ch of String(s)) w += /[mwMW]/.test(ch) ? 10.5 : /[ijlI|.,:;!' ]/.test(ch) ? 3.8 : /[frt]/.test(ch) ? 4.8 : /[A-Z]/.test(ch) ? 7.6 : /[0-9]/.test(ch) ? 7 : ch === "·" ? 4.5 : 6.6;
+  return Math.round(w + 14);
+}
+
+/**
+ * A shields-style SVG: "nomArmy | 78 claims checked · 11 caught". Caught
+ * claims are the point of running nomArmy, not something to hide, so the
+ * color is a neutral blue, and green when every claim held up.
+ */
+export function badgeSvg(stats) {
+  const { total, caught } = claims(stats);
+  const label = "nomArmy";
+  const message = !total ? "verified" : caught ? `${total} claims checked · ${caught} caught` : `${total} claims checked, all held up`;
+  const color = total && !caught ? "#2da44e" : "#0969da";
+  const lw = textWidth(label), mw = textWidth(message), w = lw + mw;
+  return `<svg xmlns="http://www.w3.org/2000/svg" width="${w}" height="20" role="img" aria-label="${esc(`${label}: ${message}`)}">
+  <title>${esc(`${label}: ${message}`)}</title>
+  <linearGradient id="s" x2="0" y2="100%"><stop offset="0" stop-color="#bbb" stop-opacity=".1"/><stop offset="1" stop-opacity=".1"/></linearGradient>
+  <clipPath id="r"><rect width="${w}" height="20" rx="3" fill="#fff"/></clipPath>
+  <g clip-path="url(#r)"><rect width="${lw}" height="20" fill="#555"/><rect x="${lw}" width="${mw}" height="20" fill="${color}"/><rect width="${w}" height="20" fill="url(#s)"/></g>
+  <g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" font-size="11">
+    <text x="${lw / 2}" y="14">${esc(label)}</text>
+    <text x="${lw + mw / 2}" y="14">${esc(message)}</text>
+  </g>
+</svg>
+`;
+}
+
+/** The README line for a committed badge, linking to nomArmy. */
+export function badgeMarkdown(relPath) {
+  return `[![nomArmy](${relPath})](${REPO_URL})`;
+}

package/lib/stats.mjs

@@ -99,7 +99,7 @@ export function resolveRepo(records, value) {
  * @param {object[]} records
  * @param {{ repo?: string|null, sinceMs?: number|null, untilMs?: number|null, role?: string|null, model?: string|null }} filter
  */
-export function computeStats(records, { repo = null, sinceMs = null, untilMs = null, role = null, model = null, agentFor = () => null, now = Date.now(), allSuggestions = false } = {}) {
+export function computeStats(records, { repo = null, sinceMs = null, untilMs = null, role = null, model = null, runId = null, agentFor = () => null, now = Date.now(), allSuggestions = false } = {}) {
   const inRange = records.filter((r) => {
     const at = Date.parse(r.startedAt ?? r.finishedAt ?? "");
     if (sinceMs != null && !(at >= sinceMs)) return false;
@@ -107,6 +107,7 @@ export function computeStats(records, { repo = null, sinceMs = null, untilMs = n
     if (repo && r.projectDir && path.resolve(r.projectDir) !== path.resolve(repo)) return false;
     if (role && jobRole(r) !== role) return false;
     if (model && (r.metrics?.worker_model ?? r.worker?.model) !== model) return false;
+    if (runId && r.labels?.runId !== runId) return false;
     return true;
   });
   // Verify runs from before records carried the repo can't be placed in one.

package/lib/user-config.mjs

@@ -0,0 +1,106 @@
+// Your setup choices (where models run, the local model, hardware profiles)
+// live in ~/.config/nomarmy/, layered over the package's config/ defaults.
+// They used to be written into config/ itself, which for an npm install is
+// inside the package: every `nomarmy update` put them back to the defaults
+// (found in a fresh-install practice run: hosted silently became local).
+//
+//   ~/.config/nomarmy/common.env           your overrides of config/common.env
+//   ~/.config/nomarmy/profiles/<name>.env  your profiles, used before config/profiles/
+//
+// scripts/lib.sh layers the same files the same way.
+
+import fs from "node:fs";
+import path from "node:path";
+import { globalConfigDir } from "./army.mjs";
+
+export function userCommonPath(env = process.env) { return path.join(globalConfigDir(env), "common.env"); }
+export function userProfilePath(name, env = process.env) { return path.join(globalConfigDir(env), "profiles", `${name}.env`); }
+
+export function parseEnvFile(filePath) {
+  const out = {};
+  let text;
+  try { text = fs.readFileSync(filePath, "utf8"); } catch { return out; }
+  for (const line of text.split("\n")) {
+    const m = /^([A-Z][A-Z0-9_]*)=(.*)$/.exec(line.trim());
+    if (m) out[m[1]] = m[2].trim();
+  }
+  return out;
+}
+
+/** Your value, else the package default. */
+export function readSetting(key, { nomarmyRoot, env = process.env }) {
+  const mine = parseEnvFile(userCommonPath(env));
+  if (key in mine) return mine[key];
+  return parseEnvFile(path.join(nomarmyRoot, "config", "common.env"))[key] ?? null;
+}
+
+/** Every common setting, package defaults with yours on top. */
+export function readSettings({ nomarmyRoot, env = process.env }) {
+  return { ...parseEnvFile(path.join(nomarmyRoot, "config", "common.env")), ...parseEnvFile(userCommonPath(env)) };
+}
+
+/** A profile's file: yours if you have one by that name, else the shipped one (null if neither). */
+export function profilePathFor(name, { nomarmyRoot, env = process.env }) {
+  if (!name) return null;
+  const mine = userProfilePath(name, env);
+  if (fs.existsSync(mine)) return mine;
+  const shipped = path.join(nomarmyRoot, "config", "profiles", `${name}.env`);
+  return fs.existsSync(shipped) ? shipped : null;
+}
+
+const HEADER = "# Your nomArmy settings, layered over the package's config/common.env.\n# Written by nomarmy setup and nomarmy model; kept across updates.\n";
+
+/** Set one KEY=VALUE in a settings file, replacing it if present. */
+export function writeEnvLine(filePath, key, value, { header = HEADER } = {}) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  const existing = fs.existsSync(filePath) ? fs.readFileSync(filePath, "utf8") : header;
+  const line = `${key}=${value}`;
+  const re = new RegExp(`^${key}=.*$`, "m");
+  const updated = re.test(existing) ? existing.replace(re, line) : `${existing.trimEnd()}\n${line}\n`.replace(/^\n/, "");
+  fs.writeFileSync(filePath, updated);
+}
+
+export function writeSetting(key, value, { env = process.env } = {}) {
+  writeEnvLine(userCommonPath(env), key, value);
+  return userCommonPath(env);
+}
+
+/**
+ * One-time rescue, run before an update's copy replaces the installed one:
+ * settings that only ever lived in the package (or its installed copy) move
+ * to ~/.config/nomarmy/. A key is moved when the old copy's value differs from
+ * the new package's default; a profile when the new package doesn't ship it
+ * or ships it differently. Never overwrites what you already have there.
+ * @returns {{ keys: string[], profiles: string[] }}
+ */
+export function migrateUserConfig({ oldConfigDir, nomarmyRoot, env = process.env }) {
+  const moved = { keys: [], profiles: [] };
+  if (!oldConfigDir || !fs.existsSync(oldConfigDir)) return moved;
+  if (path.resolve(oldConfigDir) === path.resolve(path.join(nomarmyRoot, "config"))) return moved;
+  const old = parseEnvFile(path.join(oldConfigDir, "common.env"));
+  const shipped = parseEnvFile(path.join(nomarmyRoot, "config", "common.env"));
+  const mine = parseEnvFile(userCommonPath(env));
+  for (const [key, value] of Object.entries(old)) {
+    if (key in mine || shipped[key] === value) continue;
+    writeSetting(key, value, { env });
+    moved.keys.push(key);
+  }
+  let names = [];
+  try { names = fs.readdirSync(path.join(oldConfigDir, "profiles")).filter((f) => f.endsWith(".env")); } catch { /* none */ }
+  for (const file of names) {
+    const target = userProfilePath(path.basename(file, ".env"), env);
+    if (fs.existsSync(target)) continue;
+    const text = fs.readFileSync(path.join(oldConfigDir, "profiles", file), "utf8");
+    const shippedFile = path.join(nomarmyRoot, "config", "profiles", file);
+    if (fs.existsSync(shippedFile) && fs.readFileSync(shippedFile, "utf8") === text) continue;
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.writeFileSync(target, text);
+    moved.profiles.push(path.basename(file, ".env"));
+  }
+  return moved;
+}
+
+/** A path for messages: ~ for the home directory. */
+export function tildePath(p, home = process.env.HOME) {
+  return home && p.startsWith(home + path.sep) ? `~${p.slice(home.length)}` : p;
+}

package/mcp/server.mjs

@@ -38,12 +38,16 @@ import { podmanProblem, podmanVmStartedAt } from "../lib/podman-health.mjs";
 import { restartNotice } from "../lib/install-freshness.mjs";
 import { requestJobStop } from "../lib/openclaw-run.mjs";
 import { loadJobRecords, computeStats, formatStats, formatStatsSummary, parseSince, resolveRepo, agentLookup } from "../lib/stats.mjs";
+import { shareMarkdown } from "../lib/share.mjs";
 import { recentSuggestions } from "../lib/suggestions.mjs";
 import { probeModel } from "../lib/model-probe.mjs";
 import { jevSettings, judgeSettings } from "../lib/validators.mjs";
 import { agentRunsToolsOnHost } from "../lib/dispatch-schema.mjs";
 import { createBuildMetrics, resolveOutcome, finalText, workerMetadata, usageMetrics, policyAdmissionProblems, applyRefactorContract, applyVerificationPolicy, resolveVerifyRegression } from "../lib/outcome.mjs";
 import { jobLabel, compactJobRecord, formatResult, reportView, formatUnion, testChangeBanner, regressionCheckBanner, decomposeOverlapBanner } from "../lib/job-format.mjs";
+import { ensureOpenClawOnPath } from "../lib/openclaw-path.mjs";
+// OpenClaw in ~/.npm-global/bin (no writable npm prefix) is found without the operator editing PATH.
+ensureOpenClawOnPath();
 
 export { run, mapLimit };
 export { readsMeasurable, measureReads };
@@ -548,7 +552,10 @@ server.tool("run_finish", "Close a /feature run as complete or stopped, with a o
   try {
     const run = finishRun(runsRoot, run_id, { status, summary });
     if (activeRunId === run_id) activeRunId = null;
-    return toolText(JSON.stringify({ id: run.id, status: run.status, ...runTotals(run) }, null, 2));
+    // What nomArmy verified in this run, ready for the pull request's description (lib/share.mjs).
+    let prBlock = null;
+    try { prBlock = shareMarkdown(computeStats(loadJobRecords(jobsRoot), { runId: run_id }), { scope: "this feature run" }); } catch { /* the totals stand without it */ }
+    return toolText(JSON.stringify({ id: run.id, status: run.status, ...runTotals(run), ...(prBlock ? { prBlock, prBlockNote: "Put prBlock in the pull request's description as it is: every number is from nomArmy's verified records." } : {}) }, null, 2));
   } catch (error) { return toolText(error.message, true); }
 });
 server.tool("army", "Who you, the General, are and who you call for what in this repository: your fixed charter and the agent you're defined as, the army's workflow, then each role's description, phase (build, review, acceptance), suggested mode, and the agent it runs on, with which config layer set each value (global, project .nomarmy.yml, local .nomarmy.local.yml). Flags roles with no usable agent, and roles that share your model or subscription (not an independent review). Dispatch a role with `army_role`, or an agent directly with `agent`. Read-only, re-read on every call.", {}, async () => {

package/package.json

@@ -3,7 +3,7 @@
   "description": "Every byte verified: a harness for AI coding workers whose claims are never trusted. Your coding assistant stays in charge while workers implement and test in sandboxes, and nomArmy checks every change before it is committed.",
   "author": "Rayson Technologies",
   "license": "Apache-2.0",
-  "version": "0.1.0-alpha.17",
+  "version": "0.1.0-alpha.18",
   "private": false,
   "type": "module",
   "engines": {

package/playbooks/feature.md

@@ -41,4 +41,4 @@ The `logPath` from `run_start`. Markdown, updated after every phase: the plan; e
 
 ## When it's done
 
-Call `run_finish` (`complete` or `stopped`), then report in one message: what was built and on which branch; what each role found and how it was resolved; the decisions made on the operator's behalf; test and verification results; and the run's cost from `run_status` (jobs and api spend per agent). If a push-notification tool is available, notify the operator that the run finished or stopped.
+Call `run_finish` (`complete` or `stopped`). Its result has a `prBlock`: when you or the operator open a pull request for the run's branch, put it in the description as it is (every number is from nomArmy's verified records). Then report in one message: what was built and on which branch; what each role found and how it was resolved; the decisions made on the operator's behalf; test and verification results; and the run's cost from `run_status` (jobs and api spend per agent). If a push-notification tool is available, notify the operator that the run finished or stopped.

package/scripts/configure-openclaw.sh

@@ -57,7 +57,9 @@ else
     if [[ -n "$REMOTE_MODEL" && "$REMOTE_MODEL" != "${NOMARMY_WORKER_MODEL:-}" ]]; then
       # Jobs ask for NOMARMY_WORKER_MODEL, so record the name this server
       # actually serves (`nomarmy connect`, run next by install.sh, reads it).
-      COMMON="$ROOT/config/common.env"
+      # Your settings file, so an update can't reset it (lib/user-config.mjs).
+      COMMON="$(nomarmy_user_config_dir)/common.env"
+      mkdir -p "$(dirname "$COMMON")"; touch "$COMMON"
       for key in NOMARMY_MODEL_ALIAS NOMARMY_WORKER_MODEL; do
         if grep -q "^$key=" "$COMMON"; then
           KEY="$key" VALUE="$REMOTE_MODEL" node -e 'const fs=require("fs"),f=process.argv[1];fs.writeFileSync(f,fs.readFileSync(f,"utf8").replace(new RegExp(`^${process.env.KEY}=.*$`,"m"),`${process.env.KEY}=${process.env.VALUE}`))' "$COMMON"
@@ -66,7 +68,7 @@ else
         fi
       done
       export NOMARMY_MODEL_ALIAS="$REMOTE_MODEL" NOMARMY_WORKER_MODEL="$REMOTE_MODEL"
-      echo "==> The server serves '$REMOTE_MODEL'; recorded it in config/common.env"
+      echo "==> The server serves '$REMOTE_MODEL'; recorded it in $COMMON"
     fi
     # llama-server reports the context of one slot, which is one nom's share.
     REMOTE_CTX="$(curl -fsS --max-time 5 "$SERVER/props" | node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>{try{const n=JSON.parse(s).default_generation_settings?.n_ctx;if(Number.isInteger(n)&&n>0)process.stdout.write(String(n))}catch{}})' || true)"

package/scripts/lib.sh

@@ -19,9 +19,13 @@ nomarmy_compat_prefix(){
   done
 }
 
+# Your settings live here, over the package's config/ defaults, so an update
+# can't reset them (lib/user-config.mjs does the same for the CLI).
+nomarmy_user_config_dir(){ echo "${NOMARMY_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/nomarmy}"; }
+
 nomarmy_available_profiles(){
   local root; root="$(nomarmy_root)"
-  find "$root/config/profiles" -name '*.env' -exec basename {} .env \; | sort | tr '\n' ' '
+  { find "$root/config/profiles" -name '*.env' -exec basename {} .env \; ; find "$(nomarmy_user_config_dir)/profiles" -name '*.env' -exec basename {} .env \; 2>/dev/null; } | sort -u | tr '\n' ' '
 }
 
 # Where this install's models run (lib/execution.mjs is the same logic for the
@@ -129,7 +133,8 @@ load_profile(){
     elif command -v nvidia-smi >/dev/null 2>&1; then profile=nvidia-linux
     else profile=cpu-linux; fi
   fi
-  profile_file="$root/config/profiles/$profile.env"
+  profile_file="$(nomarmy_user_config_dir)/profiles/$profile.env"
+  [[ -f "$profile_file" ]] || profile_file="$root/config/profiles/$profile.env"
   if [[ ! -f "$profile_file" ]]; then
     echo "ERROR: unknown profile '$profile'. Available: $(nomarmy_available_profiles)" >&2
     exit 2
@@ -137,6 +142,8 @@ load_profile(){
   set -a
   # shellcheck disable=SC1091
   source "$root/config/common.env"
+  # shellcheck disable=SC1091
+  [[ -f "$(nomarmy_user_config_dir)/common.env" ]] && source "$(nomarmy_user_config_dir)/common.env"
   # shellcheck disable=SC1090
   source "$profile_file"
   set +a

package/scripts/select-model.mjs

@@ -3,12 +3,14 @@ import { createInterface } from "node:readline/promises";
 import { stdin as input, stdout as output } from "node:process";
 import { readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
+import { userCommonPath } from "../lib/user-config.mjs";
 
 const root = path.resolve(path.dirname(new URL(import.meta.url).pathname), "..");
 const args = process.argv.slice(2);
 let query = "";
 let repo = "";
-let configPath = path.join(root, "config", "common.env");
+// Your settings file, not the package's config/ (an update would reset it): lib/user-config.mjs.
+let configPath = userCommonPath();
 
 for (let index = 0; index < args.length; index += 1) {
   const value = args[index];
@@ -70,16 +72,18 @@ try {
   const alias = (await rl.question(`Local model alias [${defaultAlias}]: `)).trim() || defaultAlias;
   if (!/^[A-Za-z0-9._-]+$/.test(alias)) throw new Error("Alias may contain only letters, numbers, dots, underscores, and hyphens.");
 
-  console.log(`\nReady to update ${path.relative(root, configPath)}:`);
+  console.log(`\nReady to update ${configPath}:`);
   console.log(`  NOMARMY_MODEL_REPO=${repo}`);
   console.log(`  NOMARMY_MODEL_QUANT=${requestedQuant}`);
   console.log(`  NOMARMY_MODEL_ALIAS=${alias}`);
-  if ((await rl.question("Apply this model configuration? [y/N] ")).trim().toLowerCase() !== "y") {
+  if (["n", "no"].includes((await rl.question("Apply this model configuration? [Y/n] ")).trim().toLowerCase())) {
     console.log("Canceled; no model configuration changed.");
     process.exit(0);
   }
 
-  const existing = await readFile(configPath, "utf8");
+  // Your settings file may not exist yet: start it rather than fail.
+  const existing = await readFile(configPath, "utf8").catch(() => "");
+  await import("node:fs").then((fs) => fs.mkdirSync(path.dirname(configPath), { recursive: true }));
   const replace = (key, value, text) => {
     const line = `${key}=${value}`;
     return new RegExp(`^${key}=.*$`, "m").test(text) ? text.replace(new RegExp(`^${key}=.*$`, "m"), line) : `${text.trimEnd()}\n${line}\n`;