@sayansr26/agent-os 0.5.3 → 0.6.0

package/plugins/agent-os/skills/init/scripts/settings.mjs

@@ -0,0 +1,186 @@
+#!/usr/bin/env node
+/**
+ * agent-os settings — write the permission and task-tool setup, not describe it.
+ *
+ * Three things, at project scope, user scope, or both:
+ *
+ *   settings.json  permissions.deny  += the git write-protection rules
+ *                  env.CLAUDE_CODE_ENABLE_TODO_TOOLS = "1"
+ *   CLAUDE.md      the task-tracking rule
+ *
+ * Merges, never replaces: existing keys, allow rules, deny rules and a value
+ * the user set for the env flag all survive. Idempotent. Before changing a
+ * file under ~/.claude it copies it to `<file>.agent-os.bak`; project files
+ * are left to git, so a backup does not show up as an untracked file.
+ *
+ * Previews by default. `--apply` writes. The preview is what /agent-os:init
+ * shows the user before asking once; the CLI's `init` asks the same question.
+ *
+ * Usage: node settings.mjs [--root <dir>] [--scope project|user|both] [--apply]
+ */
+import { copyFileSync, existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const TODO_ENV = "CLAUDE_CODE_ENABLE_TODO_TOOLS";
+
+export const TASK_RULE = `- **Always track work with the task tool (TaskCreate / TaskUpdate).** Any request
+  with more than one step gets a task list before work starts: one task per
+  deliverable, marked \`in_progress\` when started and \`completed\` only when
+  verified. Keep it current as scope changes, including work delegated to
+  subagents, so I can see what is done, running and left at any moment.`;
+
+/**
+ * Every git command that changes the repository. Read-only inspection
+ * (status, log, diff, show, blame, …) stays available. The first five close
+ * the flag forms that would otherwise walk past a per-subcommand rule —
+ * references/git-permissions.md explains each judgment call.
+ */
+export const GIT_DENY = [
+  "Bash(git -C*)", "Bash(git -c*)", "Bash(git --git-dir*)", "Bash(git --work-tree*)", "Bash(git --exec-path*)",
+  "Bash(git add *)", "Bash(git am *)", "Bash(git apply *)", "Bash(git bisect *)", "Bash(git branch *)",
+  "Bash(git checkout *)", "Bash(git cherry-pick *)", "Bash(git clean *)", "Bash(git clone *)", "Bash(git commit *)",
+  "Bash(git config *)", "Bash(git fast-import *)", "Bash(git filter-branch *)", "Bash(git gc *)", "Bash(git init *)",
+  "Bash(git merge *)", "Bash(git mv *)", "Bash(git notes *)", "Bash(git prune *)", "Bash(git pull *)",
+  "Bash(git push *)", "Bash(git rebase *)", "Bash(git reflog *)", "Bash(git remote *)", "Bash(git repack *)",
+  "Bash(git replace *)", "Bash(git reset *)", "Bash(git restore *)", "Bash(git revert *)", "Bash(git rm *)",
+  "Bash(git stash *)", "Bash(git submodule *)", "Bash(git switch *)", "Bash(git symbolic-ref *)", "Bash(git tag *)",
+  "Bash(git update-ref *)", "Bash(git worktree *)",
+];
+
+export const userDir = () => process.env.CLAUDE_CONFIG_DIR || join(homedir(), ".claude");
+
+export function paths(scope, root) {
+  return scope === "user"
+    ? { settings: join(userDir(), "settings.json"), claudeMd: join(userDir(), "CLAUDE.md"), label: "USER (~/.claude)" }
+    : { settings: join(root, ".claude/settings.json"), claudeMd: join(root, "CLAUDE.md"), label: "PROJECT" };
+}
+
+const put = (p, text, keep) => {
+  if (keep && existsSync(p)) copyFileSync(p, `${p}.agent-os.bak`);
+  mkdirSync(dirname(p), { recursive: true }); writeFileSync(p, text); };
+
+// "Bash(git commit *)" and "Bash(git commit:*)" are the same rule to Claude Code.
+const norm = (r) => r.replace(/:\*\)$/, " *)").replace(/\s+/g, " ");
+
+/**
+ * Merge the deny rules and the env flag into one settings.json.
+ * Returns { status: "changed"|"unchanged"|"invalid", file, denyAdded, env, current }
+ * where env is "added" | "present" | "conflict".
+ */
+export function mergeSettings(file, { dry = false, deny = GIT_DENY, todo = true, keep = false } = {}) {
+  let settings = {};
+  if (existsSync(file)) {
+    try { settings = JSON.parse(readFileSync(file, "utf8")); }
+    catch { return { status: "invalid", file, denyAdded: [], env: null }; }
+  }
+  const perms = settings.permissions || {};
+  const have = new Set((perms.deny || []).map(norm));
+  const denyAdded = deny.filter((r) => !have.has(norm(r)));
+
+  let env = null, current;
+  if (todo) {
+    current = (settings.env || {})[TODO_ENV];
+    // "true" and "1" are both truthy to Claude Code; an existing value is the
+    // user's choice and is left alone rather than normalised.
+    if (current === undefined) env = "added";
+    else env = current === "1" || current === "true" || current === true ? "present" : "conflict";
+  }
+
+  if (!denyAdded.length && env !== "added") return { status: "unchanged", file, denyAdded, env, current };
+
+  if (denyAdded.length) settings.permissions = { ...perms, deny: [...(perms.deny || []), ...denyAdded] };
+  if (env === "added") settings.env = { ...(settings.env || {}), [TODO_ENV]: "1" };
+  if (!dry) put(file, JSON.stringify(settings, null, 2) + "\n", keep);
+  return { status: "changed", file, denyAdded, env, current };
+}
+
+/**
+ * Put the task-tracking rule in a CLAUDE.md. Returns "added" | "present" | "no-file".
+ * A project CLAUDE.md is never created — that is the project's own
+ * always-loaded context, and a CLI inventing one leaves a stub nobody owns.
+ * The user's ~/.claude/CLAUDE.md is created when `create` is set.
+ */
+export function addTaskRule(file, { dry = false, create = false, keep = false } = {}) {
+  if (!existsSync(file)) {
+    if (!create) return { status: "no-file", file };
+    if (!dry) put(file, `# Personal working agreement\n\n${TASK_RULE}\n`);
+    return { status: "added", file, section: "new file" };
+  }
+  const text = readFileSync(file, "utf8");
+  if (/TaskCreate/.test(text)) return { status: "present", file };
+
+  // Prefer an operator-preferences section so the rule lands with the other
+  // instructions about how to work rather than orphaned at the bottom.
+  const heading = text.match(/^##\s+Operator preferences\s*$/m);
+  let next;
+  if (heading) {
+    const start = heading.index + heading[0].length;
+    const rest = text.slice(start);
+    const nextHeading = rest.search(/^##\s+/m);
+    const end = nextHeading === -1 ? text.length : start + nextHeading;
+    next = `${text.slice(0, end).replace(/\s*$/, "")}\n\n${TASK_RULE}\n\n${text.slice(end)}`;
+  } else {
+    next = `${text.replace(/\s*$/, "")}\n\n## Working agreement\n\n${TASK_RULE}\n`;
+  }
+  if (!dry) put(file, next.replace(/\n{4,}/g, "\n\n\n"), keep);
+  return { status: "added", file, section: heading ? "Operator preferences" : "Working agreement" };
+}
+
+/** Everything for one scope. */
+export function applyScope(scope, root, { dry = false } = {}) {
+  const p = paths(scope, root);
+  return {
+    scope,
+    label: p.label,
+    settings: mergeSettings(p.settings, { dry, keep: scope === "user" }),
+    rule: addTaskRule(p.claudeMd, { dry, create: scope === "user", keep: scope === "user" }),
+  };
+}
+
+export function describe(r, { dry }) {
+  const s = r.settings, lines = [];
+  const verb = dry ? "would add" : "added";
+  lines.push(`${r.label}  ${s.file}`);
+  if (s.status === "invalid") lines.push("  not valid JSON — left alone; fix it and re-run");
+  else {
+    lines.push(s.denyAdded.length
+      ? `  permissions.deny   ${verb} ${s.denyAdded.length} git write rule(s)${s.denyAdded.length < GIT_DENY.length ? ` (${GIT_DENY.length - s.denyAdded.length} already there)` : ""}`
+      : `  permissions.deny   git write protection already complete`);
+    lines.push({
+      added: `  env.${TODO_ENV}  ${verb} "1"`,
+      present: `  env.${TODO_ENV}  already on`,
+      conflict: `  env.${TODO_ENV}  is "${s.current}" — left as set`,
+    }[s.env]);
+    if (s.status === "changed" && !dry && r.scope === "user" && existsSync(`${s.file}.agent-os.bak`)) lines.push(`  backup             ${s.file}.agent-os.bak`);
+  }
+  lines.push({
+    added: `  ${r.rule.file}  ${dry ? "would add" : "added"} the task-tracking rule (${r.rule.section})`,
+    present: `  ${r.rule.file}  task-tracking rule already there`,
+    "no-file": `  ${r.rule.file}  absent — /agent-os:init builds it`,
+  }[r.rule.status]);
+  return lines;
+}
+
+function main(argv) {
+  const arg = (k, d) => { const i = argv.indexOf(k); return i === -1 ? d : argv[i + 1]; };
+  const root = arg("--root", process.cwd());
+  const scope = arg("--scope", "both");
+  const dry = !argv.includes("--apply");
+  const scopes = scope === "both" ? ["project", "user"] : [scope];
+  if (!scopes.every((s) => s === "project" || s === "user")) {
+    console.error(`--scope must be project, user or both (got "${scope}")`);
+    process.exit(2);
+  }
+  const out = [`AGENT-OS SETTINGS  ${dry ? "preview — nothing written; re-run with --apply" : "applied"}`, ""];
+  for (const s of scopes) out.push(...describe(applyScope(s, root, { dry }), { dry }), "");
+  if (scopes.includes("user")) out.push("~/.claude applies to every project on this machine.");
+  process.stdout.write(out.join("\n") + "\n");
+}
+
+const isMain = () => {
+  try { return realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url)); }
+  catch { return false; }
+};
+if (process.argv[1] && isMain()) main(process.argv.slice(2));

package/plugins/agent-os/skills/init/scripts/state.mjs

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+/**
+ * agent-os setup state — is this a fresh setup, a repair, or already healthy?
+ *
+ * Both `npx agent-os init` and `/agent-os:init` start here, so neither
+ * re-scaffolds a project that is set up, and both name exactly what a repair
+ * has to touch. Read-only: every check is a file read, and the settings checks
+ * are dry runs of what settings.mjs would write.
+ *
+ * The plugin check reads Claude Code's own records (installed_plugins.json,
+ * enabledPlugins, the marketplace cache) instead of calling the `claude` CLI,
+ * so it also works from inside a session.
+ *
+ * Usage: node state.mjs [projectDir]
+ */
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { addTaskRule, GIT_DENY, mergeSettings, paths, userDir } from "./settings.mjs";
+
+export const PLUGIN_ID = "agent-os@sayan-plugins";
+export const MARKETPLACE_NAME = "sayan-plugins";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const readJson = (p) => { try { return JSON.parse(readFileSync(p, "utf8")); } catch { return null; } };
+const real = (p) => { try { return realpathSync(p); } catch { return p; } };
+
+/** -1, 0, 1 for dotted numeric versions; unknown sorts lowest. */
+export function cmpVersion(a, b) {
+  const pa = String(a || "0").split(/[.-]/).map((n) => parseInt(n, 10) || 0);
+  const pb = String(b || "0").split(/[.-]/).map((n) => parseInt(n, 10) || 0);
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const d = (pa[i] || 0) - (pb[i] || 0);
+    if (d) return d > 0 ? 1 : -1;
+  }
+  return 0;
+}
+
+/** The version of the plugin this script ships in. */
+export const bundledVersion = () => readJson(join(HERE, "../../../.claude-plugin/plugin.json"))?.version || null;
+
+/**
+ * What Claude Code has installed for this project.
+ * { installed, scope, version, enabled, latest } — latest is the version in the
+ * local marketplace cache, which is only as new as the last marketplace update.
+ */
+export function pluginState(root) {
+  const home = userDir();
+  const rootReal = real(root);
+  const records = readJson(join(home, "plugins/installed_plugins.json"))?.plugins?.[PLUGIN_ID] || [];
+  // Project and local installs belong to one directory; user installs to all.
+  const mine = records.filter((r) => r.scope === "user" || (r.projectPath && real(r.projectPath) === rootReal));
+  const pick = mine.find((r) => r.scope === "project" || r.scope === "local") || mine[0] || null;
+
+  const enabledIn = [
+    join(root, ".claude/settings.local.json"),
+    join(root, ".claude/settings.json"),
+    join(home, "settings.json"),
+  ].map((p) => readJson(p)?.enabledPlugins?.[PLUGIN_ID]).find((v) => v !== undefined);
+
+  const latest = readJson(join(home, "plugins/marketplaces", MARKETPLACE_NAME, "plugins/agent-os/.claude-plugin/plugin.json"))?.version || null;
+  return {
+    installed: !!pick,
+    scope: pick?.scope || null,
+    version: pick?.version || null,
+    enabled: pick ? enabledIn !== false : false,
+    latest,
+  };
+}
+
+/**
+ * Every check, then the verdict:
+ *   fresh    nothing of agent-os is here yet — run the whole setup
+ *   repair   some of it is — fix only the items marked missing
+ *   healthy  all of it is
+ * `expect` is the plugin version the caller wants at minimum (the CLI passes
+ * the version it bundles).
+ */
+export function setupState(root, { expect = bundledVersion() } = {}) {
+  const items = [];
+  const add = (key, label, ok, fix) => items.push({ key, label, ok, fix });
+
+  const hasSource = existsSync(join(root, ".agent-os/config.json"));
+  const claudeMd = (() => { try { return readFileSync(join(root, "CLAUDE.md"), "utf8"); } catch { return null; } })();
+  const hasMemory = existsSync(join(root, ".claude/agent-memory"));
+
+  add("source", ".agent-os/ source", hasSource, "npx @sayansr26/agent-os init");
+  add("claude-md", "CLAUDE.md", claudeMd !== null, "/init in Claude Code, then /agent-os:init");
+
+  for (const scope of ["project", "user"]) {
+    const p = paths(scope, root);
+    const s = mergeSettings(p.settings, { dry: true });
+    const where = scope === "user" ? "~/.claude/settings.json" : ".claude/settings.json";
+    if (s.status === "invalid") { add(`${scope}-settings`, `${where} is valid JSON`, false, `fix ${where} by hand`); continue; }
+    const have = GIT_DENY.length - s.denyAdded.length;
+    add(`${scope}-git`, `${where} git write protection (${have}/${GIT_DENY.length})`, !s.denyAdded.length, `agent-os settings --scope ${scope} --apply`);
+    add(`${scope}-todo`, `${where} task tools`, s.env !== "added", `agent-os settings --scope ${scope} --apply`);
+  }
+  if (claudeMd !== null) {
+    add("task-rule", "CLAUDE.md task-tracking rule", addTaskRule(join(root, "CLAUDE.md"), { dry: true }).status === "present", "agent-os settings --scope project --apply");
+    add("agents-section", "CLAUDE.md says when to use each agent", /agent-os:(feature-cartographer|builder|reviewer)/.test(claudeMd), "/agent-os:init (establishing.md, Step 4b)");
+  }
+
+  const pl = pluginState(root);
+  const want = [expect, pl.latest].filter(Boolean).sort((a, b) => cmpVersion(b, a))[0] || null;
+  add("plugin", "Claude Code plugin installed", pl.installed, "npx @sayansr26/agent-os init");
+  if (pl.installed) {
+    add("plugin-enabled", "plugin enabled", pl.enabled, `claude plugin enable ${PLUGIN_ID}`);
+    add("plugin-version", `plugin version ${pl.version}${want && cmpVersion(pl.version, want) < 0 ? ` (latest ${want})` : ""}`,
+      !want || cmpVersion(pl.version, want) >= 0, "npx @sayansr26/agent-os init  (or /plugin update, then /reload-plugins)");
+  }
+
+  // Settings alone do not count: deny rules may be the user's own.
+  const anything = hasSource || hasMemory || pl.installed || /agent-os/.test(claudeMd || "");
+  const missing = items.filter((i) => !i.ok);
+  const status = !anything ? "fresh" : missing.length ? "repair" : "healthy";
+  return { status, items, missing, plugin: pl };
+}
+
+export function describeState(st) {
+  const lines = [`SETUP  ${st.status.toUpperCase()}${st.status === "repair" ? `  — ${st.missing.length} item(s) to fix` : ""}`];
+  for (const i of st.items) lines.push(`  ${i.ok ? "ok     " : "MISSING"} ${i.label}${i.ok ? "" : `  → ${i.fix}`}`);
+  return lines;
+}
+
+const isMain = () => {
+  try { return realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url)); }
+  catch { return false; }
+};
+if (process.argv[1] && isMain()) {
+  const root = process.argv[2] || process.cwd();
+  process.stdout.write(describeState(setupState(root)).join("\n") + "\n");
+}

package/src/claude-setup.mjs

@@ -1,81 +1,12 @@
 /**
- * The two Claude Code settings that are not rules and not a plugin.
+ * The Claude Code settings that are not rules and not the plugin: git write
+ * protection, the todo tools flag, and the task-tracking rule.
  *
- * Both are written at PROJECT scope only — `.claude/settings.json` and the
- * project's `CLAUDE.md`. Nothing here touches `~/.claude/`: a project setup
- * tool that edits the machine's global config is overreach, and the point is
- * that the setup travels with the repository.
+ * The logic lives in the plugin (`skills/init/scripts/settings.mjs`) so that
+ * `/agent-os:init` inside Claude Code and `agent-os init` in a terminal write
+ * exactly the same thing. This module is the CLI's door to it.
  */
-import { existsSync, readFileSync } from "node:fs";
-import { join } from "node:path";
-import { write } from "./source.mjs";
-
-export const TODO_ENV = "CLAUDE_CODE_ENABLE_TODO_TOOLS";
-
-export const TASK_RULE = `- **Always track work with the task tool (TaskCreate / TaskUpdate).** Any request
-  with more than one step gets a task list before work starts: one task per
-  deliverable, marked \`in_progress\` when started and \`completed\` only when
-  verified. Keep it current as scope changes, including work delegated to
-  subagents, so I can see what is done, running and left at any moment.`;
-
-/**
- * Turn on the todo tools in project settings, preserving every other key.
- * Returns "added" | "present" | "conflict" | "invalid".
- */
-export function ensureTodoEnv(root, { dry = false } = {}) {
-  const rel = ".claude/settings.json";
-  const p = join(root, rel);
-  let settings = {};
-  if (existsSync(p)) {
-    try { settings = JSON.parse(readFileSync(p, "utf8")); }
-    catch { return { status: "invalid", rel }; }
-  }
-  const env = settings.env || {};
-  const current = env[TODO_ENV];
-
-  // "true" and "1" are both truthy to Claude Code; an existing truthy value is
-  // the user's choice and is left alone rather than normalised.
-  if (current !== undefined) {
-    const on = current === "1" || current === "true" || current === true;
-    return { status: on ? "present" : "conflict", rel, current };
-  }
-
-  settings.env = { ...env, [TODO_ENV]: "1" };
-  if (!dry) write(root, rel, JSON.stringify(settings, null, 2) + "\n");
-  return { status: "added", rel };
-}
-
-/**
- * Put the task-tracking rule in CLAUDE.md if it is not already there.
- * Never creates CLAUDE.md — that file is the project's own always-loaded
- * context, and inventing one from a CLI is how a project ends up with a stub
- * nobody owns. Returns "added" | "present" | "no-file".
- */
-export function ensureTaskRule(root, { dry = false } = {}) {
-  const rel = "CLAUDE.md";
-  const p = join(root, rel);
-  if (!existsSync(p)) return { status: "no-file", rel };
-
-  const text = readFileSync(p, "utf8");
-  if (/TaskCreate/.test(text)) return { status: "present", rel };
-
-  // Prefer the operator-preferences section if the project keeps one, so the
-  // rule lands with the other instructions about how to work rather than
-  // orphaned at the bottom of the file.
-  const heading = text.match(/^##\s+Operator preferences\s*$/m);
-  let next;
-  if (heading) {
-    const start = heading.index + heading[0].length;
-    const rest = text.slice(start);
-    const nextHeading = rest.search(/^##\s+/m);
-    const end = nextHeading === -1 ? text.length : start + nextHeading;
-    const before = text.slice(0, end).replace(/\s*$/, "");
-    next = `${before}\n\n${TASK_RULE}\n\n${text.slice(end)}`;
-  } else {
-    next = `${text.replace(/\s*$/, "")}\n\n## Working agreement\n\n${TASK_RULE}\n`;
-  }
-  next = next.replace(/\n{4,}/g, "\n\n\n");
-
-  if (!dry) write(root, rel, next);
-  return { status: "added", rel, section: heading ? "Operator preferences" : "Working agreement" };
-}
+export {
+  TODO_ENV, TASK_RULE, GIT_DENY, userDir, paths,
+  mergeSettings, addTaskRule, applyScope, describe,
+} from "../plugins/agent-os/skills/init/scripts/settings.mjs";

package/src/cli.mjs

@@ -5,8 +5,10 @@ import { join } from "node:path";
 import { detect, summarise, TOOLS } from "./detect.mjs";
 import { load, write, readIfExists, matches, BANNER, DIR } from "./source.mjs";
 import { adopt } from "./adopt.mjs";
-import { installPlugin, MARKETPLACE, MARKETPLACE_NAME, PLUGIN } from "./plugin.mjs";
-import { ensureTodoEnv, ensureTaskRule, TODO_ENV } from "./claude-setup.mjs";
+import { ensurePlugin, MARKETPLACE_NAME, PLUGIN } from "./plugin.mjs";
+import { setupState, describeState } from "../plugins/agent-os/skills/init/scripts/state.mjs";
+import { applyScope, describe } from "./claude-setup.mjs";
+import { createInterface } from "node:readline/promises";
 import { compile, TARGETS } from "./targets.mjs";
 
 const bold = (s) => `\x1b[1m${s}\x1b[0m`;
@@ -15,12 +17,14 @@ const dim = (s) => `\x1b[2m${s}\x1b[0m`;
 const USAGE = `
 ${bold("agent-os")} — one source of truth for AI coding agent config
 
-  agent-os init      detect your tools, create .agent-os/, compile
+  agent-os init      set up a fresh project, or repair and update an existing one
   agent-os sync      recompile after editing .agent-os/
   agent-os check     verify nothing drifted (exit 1 if it has) — for CI
   agent-os detect    list which tools this project is set up for
   agent-os audit     inspect the project's context layer and report findings
   agent-os memory    inspect and health-check every memory store
+  agent-os settings  preview git write protection + task tools for Claude Code
+                     (--scope project|user|both, --apply to write)
 
   Without a global install, prefix any of these with
   ${dim("npx @sayansr26/agent-os")}
@@ -29,7 +33,9 @@ Options
   --root <dir>   project directory (default: cwd)
   --dry-run      print what would change, write nothing
   --force        overwrite files agent-os did not generate (it refuses by default)
-  --no-plugin    skip installing the Claude Code plugin during init
+  --no-plugin    skip installing or updating the Claude Code plugin during init
+  --global       init: also write ~/.claude settings without asking
+  --no-global    init: leave ~/.claude alone
 `;
 
 function scaffold(root, found) {
@@ -116,6 +122,13 @@ export async function main(argv) {
     return;
   }
 
+  if (cmd === "settings") {
+    const i = argv.indexOf("--scope");
+    runScript("plugins/agent-os/skills/init/scripts/settings.mjs",
+      ["--root", root, "--scope", i === -1 ? "both" : argv[i + 1], ...(argv.includes("--apply") ? ["--apply"] : [])]);
+    return;
+  }
+
   if (cmd === "memory") {
     runScript("plugins/agent-os/skills/memory/scripts/memory.mjs", argv.includes("--stale") ? [root, "--stale"] : [root]);
     return;
@@ -123,14 +136,28 @@ export async function main(argv) {
 
   let adopted = new Set();
 
+  let before = null;
   if (cmd === "init") {
     console.log(`\n${bold("agent-os init")}  ${root}\n`);
+    // Decide fresh vs repair before touching anything, and say which, so a
+    // second run on a set-up project reads as a repair rather than a re-init.
+    before = setupState(root);
+    for (const l of describeState(before)) console.log(`  ${l}`);
+    console.log({
+      fresh: `\n  ${dim("Fresh setup: creating everything.")}`,
+      repair: `\n  ${dim("Existing setup: fixing the items marked MISSING, leaving the rest as it is.")}`,
+      healthy: `\n  ${dim("Setup is complete: re-syncing and checking the plugin for updates.")}`,
+    }[before.status]);
+    console.log("");
     console.log(summarise(found));
+    const hadSource = existsSync(join(root, DIR));
     const { present, taken } = scaffold(root, found);
     adopted = taken.paths;
     if (taken.from.length) {
       console.log(`\n  adopted into ${DIR}/ ${dim("— your existing files are now the source")}`);
       for (const f of taken.from) console.log(`    ${f}`);
+    } else if (hadSource) {
+      console.log(`\n  kept ${DIR}/ ${dim("— already the source; nothing re-scaffolded")}`);
     } else {
       console.log(`\n  created ${DIR}/ ${dim("(config.json, AGENTS.md, rules/example.md)")}`);
     }
@@ -214,37 +241,53 @@ Pick one:
     if (cmd === "init" && targets.includes("claude-code")) {
       console.log(`\n${bold("Claude Code setup")}\n`);
 
-      const e = ensureTodoEnv(root, { dry });
-      const eMsg = {
-        added: `  ${e.rel}  ${dim(`env.${TODO_ENV} = "1"`)}`,
-        present: `  ${e.rel}  ${dim(`env.${TODO_ENV} already set`)}`,
-        conflict: `  ${e.rel}  ${dim(`env.${TODO_ENV} is "${e.current}" — left as you set it`)}`,
-        invalid: `  ${e.rel}  ${dim("is not valid JSON — left alone, fix it and re-run")}`,
-      }[e.status];
-      console.log(eMsg);
-
-      const t = ensureTaskRule(root, { dry });
-      const tMsg = {
-        added: `  ${t.rel}  ${dim(`task-tracking rule added under ${t.section}`)}`,
-        present: `  ${t.rel}  ${dim("task-tracking rule already there")}`,
-        "no-file": `  ${t.rel}  ${dim("absent — run /agent-os:init inside Claude Code to build it")}`,
-      }[t.status];
-      console.log(tMsg);
+      // Project scope always: it travels with the repo. User scope protects
+      // every other project on the machine too, so it is asked once rather
+      // than assumed — unless --global / --no-global already answered.
+      for (const l of describe(applyScope("project", root, { dry }), { dry })) console.log(`  ${l}`);
+
+      let global = argv.includes("--global") ? true : argv.includes("--no-global") ? false : null;
+      if (global === null && !dry && process.stdin.isTTY && process.stdout.isTTY) {
+        console.log("");
+        for (const l of describe(applyScope("user", root, { dry: true }), { dry: true })) console.log(`  ${l}`);
+        const rl = createInterface({ input: process.stdin, output: process.stdout });
+        const a = (await rl.question(`\n  Apply the same to ~/.claude (every project on this machine)? [Y/n] `)).trim().toLowerCase();
+        rl.close();
+        global = a === "" || a === "y" || a === "yes";
+      }
+      if (global) {
+        console.log("");
+        for (const l of describe(applyScope("user", root, { dry }), { dry })) console.log(`  ${l}`);
+      } else if (global === null) {
+        console.log(`\n  ${dim("~/.claude left alone (not a terminal). To protect every project:")}`);
+        console.log(`  ${dim("npx @sayansr26/agent-os settings --scope user --apply")}`);
+      }
     }
 
     if (cmd === "init" && targets.includes("claude-code") && !argv.includes("--no-plugin")) {
       console.log(`\n${bold("Claude Code plugin")} ${dim(`${PLUGIN}@${MARKETPLACE_NAME}`)}\n`);
-      const r = installPlugin({ dry });
+      const r = ensurePlugin({ root, dry });
       for (const line of r.done) console.log(`  ${dim(line)}`);
-      if (r.ok && r.reason === "installed") {
-        console.log(`\n  installed at project scope ${dim("— .claude/settings.json, so it travels with the repo")}`);
-        console.log(`  ${dim("restart Claude Code, or /reload-plugins, then run /agent-os:init")}`);
-      } else if (!r.ok) {
-        console.log("");
-        for (const line of r.hint) console.log(`  ${line}`);
-      }
+      if (r.ok) console.log({
+        installed: `\n  installed ${r.to || ""} at project scope ${dim("— .claude/settings.json, so it travels with the repo")}`,
+        updated: `\n  updated ${r.from} → ${r.to}`,
+        current: `\n  already the latest (${r.to})`,
+        "dry-run": `\n  ${dim(r.from ? `installed: ${r.from} — would refresh and update` : "not installed — would install")}`,
+      }[r.reason]);
+      for (const line of r.hint) console.log(`  ${r.ok ? dim(line) : line}`);
+      if (r.reason === "installed" || r.reason === "updated")
+        console.log(`  ${dim("restart Claude Code, or /reload-plugins, to load it")}`);
       console.log(`\n  ${dim("--no-plugin skips this")}`);
     }
+
+    if (cmd === "init" && !dry) {
+      const after = setupState(root);
+      console.log(`\n${bold("Result")}  ${before.status} → ${after.status}`);
+      if (after.missing.length) {
+        console.log(dim("  still to do:"));
+        for (const i of after.missing) console.log(`    ${i.label}  → ${i.fix}`);
+      }
+    }
     console.log("");
     return;
   }