@akinet/akidevrule 3.1.0 → 3.2.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## [3.2.0] - 2026-09-15
+
+### Added
+- **Installer auto-discovers and deploys to all Claude config directory profiles (`~/.claude*`, `$CLAUDE_CONFIG_DIR`, `--claude-dir`).**
+  - **Evidence:** Users running alternate Claude Code profiles (such as `CLAUDE_CONFIG_DIR=~/.claude-9rt` or `~/.claude-prx` for proxy routing or multi-account quotas) noticed that running `./install.sh` / `node install.mjs` only installed skills, agents, hooks, and CLAUDE.md into the default `~/.claude/`. Alternate profiles were missing new agents, updated skills, and update hooks unless manually symlinked or copied per folder.
+  - **Root cause:** `install.mjs` hardcoded `CLAUDE_DIR = join(HOME, ".claude")` with no auto-detection, no `$CLAUDE_CONFIG_DIR` awareness, and no CLI parameter for alternate profile roots.
+  - **Mechanism:** `getClaudeDirs()` auto-discovers all `~/.claude*` directories under `$HOME`, respects `$CLAUDE_CONFIG_DIR` and `--claude-dir <path>`, deduplicates canonical paths across symlinks, and synchronizes skills, agents, hooks, `CLAUDE.md`, and `settings.json` across all detected profiles in a single install pass. New variant profiles automatically seed `CLAUDE.local.md` importing `@~/.claude/CLAUDE.local.md` to inherit machine-local facts. Antigravity and Kiro permission allowlists now expand to cover skill scripts across all detected Claude roots.
+  - **Tradeoff / rejected alternative:** Requiring the user to run `CLAUDE_CONFIG_DIR=... ./install.sh` separately for each profile was rejected — it is tedious, easy to forget, and leaves profiles silently drifting out of sync. Auto-discovering all sibling `~/.claude*` profiles by default makes a single install update the entire machine's Claude environments simultaneously.
+
+### Fixed
+- **Installer preflight now prevents partial installs, legacy migration follows confirmation, and Antigravity permission-only updates persist.** Evidence: malformed Claude, Gemini skills, or Antigravity settings could be handled during mutation; legacy root migration could run before an interactive cancellation; and Antigravity's `allowNonWorkspaceAccess`, `agentMode`, and `trustedWorkspaces` did not save when they were the only differences. Root cause: not every later-mutated JSON file was validated up front, malformed Gemini files were silently replaced or skipped, migration preceded confirmation, and those Antigravity fields did not update change tracking. Mechanism: before the prompt or any mutation, the installer requires every existing Claude `settings.json`, Gemini `config/skills.json`, Antigravity CLI settings, and Gemini settings to parse as an object; cancellation precedes migration; later merges parse directly and Antigravity fields mark their settings file changed. Tradeoff / rejected alternative: continuing with valid profiles or silently replacing malformed JSON was rejected because partial machine configuration and lost user configuration are harder to repair than one explicit failed install.
+
+## [3.1.1] - 2026-09-15
+
+### Fixed
+- **`coding.B3` bans moving uncommitted work to attribute a failing check.** Evidence: during the 3.1.0 site sync a worker hit a typecheck failure and ran `git stash` on a site repo to re-check a clean HEAD, sweeping 17 of the owner's uncommitted files out of the tree; they were restored with `git stash pop`, nothing lost. Root cause: 3.1.0 made build/test self-authorized at ship time but said nothing about how a failure is attributed, and `agent.B5`'s git-mutation ban covers audits only. Mechanism: attribution reads the error against the changed files or rebuilds the committed tree in a separate `git worktree`; `stash`/`checkout -- <path>`/`restore`/`reset`/`clean` are never used for it. Rejected: widening `agent.B5` to all work, which would also forbid legitimate owner-ordered resets; the risk lives exactly where a check fails, so the ban sits in `coding.B3`.
+
 ## [3.1.0] - 2026-09-15
 
 ### Changed

package/README.md

@@ -267,8 +267,8 @@ flowchart TD
         R_META[".source-repo & .version"]
     end
 
-    %% TARGET 2: ~/.claude/
-    subgraph T2["🤖 2. Claude Code Agent (~/.claude/)"]
+    %% TARGET 2: ~/.claude/ and ~/.claude-*
+    subgraph T2["🤖 2. Claude Code Agent (~/.claude/ & ~/.claude-*)"]
         C_MD["CLAUDE.md (Managed prompt)"]
         C_LOCAL["CLAUDE.local.md (Machine local)"]
         C_SKILLS["skills/<skill_name>/SKILL.md"]
@@ -308,14 +308,16 @@ flowchart TD
 Targets 4-6 only get the shared skill corpus (no rule corpus / no `CLAUDE.md`/`GEMINI.md`-style overrides — those CLIs have no equivalent hard-load hook this baseline plugs into yet). Each sync is scoped per skill folder name via a Node `fs` copy plus a managed-names-only prune, same never-touch-the-rest guarantee as targets 2 and 3, and runs unconditionally — harmless if that CLI isn't installed on the machine, picked up the moment it is.
 
 1. Syncs `payload/*` into `~/.aki/akidevrule/` (Node `fs` copy, excludes `ref-ECC/`), removes stale files left by renames, syncs `agskills/` for Antigravity skill inheritance, and deploys the full TCC lookup to `~/.aki/akidevrule/docs/ref/macos-codesign-tcc.md`.
-2. Syncs every skill folder under `skills/*/` (whole directory, including any `references/` or `scripts/`) into `~/.claude/skills/`, one named folder at a time (copy + managed-names-only prune), removing only Aki's own old/renamed skill directories (`akidoc-*`, `akiadvise`) — any other skill you already have is never touched. `skills/` is a top-level, agent-neutral folder (siblings with `payload/`, not nested under `claude/`) because SKILL.md is a shared open standard both Claude Code and Antigravity/AGY consume identically — see [docs/ref/agent-skills-standard.md](docs/ref/agent-skills-standard.md).
-3. Copies `claude/agents/*.md` into `~/.claude/agents/` **file by file, never a directory mirror with `--delete`** — that folder is a shared namespace where your own agent definitions sit beside Aki's, exactly like `~/.claude/skills/`, so nothing you did not install is ever removed.
-4. Replaces `~/.claude/CLAUDE.md` with the packaged guidance (timestamped backup first), appending this machine's source-repo path and an `@~/.claude/CLAUDE.local.md` import.
-5. Creates `~/.claude/CLAUDE.local.md` **only if missing** — never overwritten afterward. Put per-machine rules there (build constraints, IDE paths, remote flags); they survive every reinstall.
-6. Updates `~/.claude/settings.json` (timestamped backup first): read permission for `~/.aki/akidevrule/**`, skill script execution permissions (`Bash(python3 ~/.claude/skills/**)`), `skillOverrides.akirule = "on"`, idempotent registration of the `SessionStart` update-check hook.
-7. Installs `~/.claude/hooks/aki-update-check.mjs` plus its shared parser `~/.claude/hooks/aki_version_check.mjs`, and records the source-repo path in `~/.aki/akidevrule/.source-repo`. Writes `~/.aki/akidevrule/.version` with `installed=`/`version=`/`commit=`/`branch=` — `version=` is the just-installed CHANGELOG's latest released semver, the same value `install.mjs --check` and the hook compare against remote.
-8. Installs `payload/GEMINI.md` to `~/.gemini/GEMINI.md` — Antigravity global behavior overrides, stamped with a version marker (`[AKIRULE-AG-OVERRIDES-…]`) on line 1. Generates 18 native rule files under `~/.gemini/config/rules/` with YAML `trigger` frontmatter. Deploys 10 skills directly to `~/.gemini/config/skills/` for native auto-discovery (synced per skill folder, same never-touch-the-rest guarantee as step 2), configures `~/.gemini/config/skills.json` with absolute paths as secondary, and merges skill execution permissions into `~/.gemini/antigravity-cli/settings.json` and `~/.gemini/settings.json` — a `command()` prefix rule for each of akiflow's five scripts (the only skill whose scripts agy invokes directly) per skill root, in both the expanded and the tilde-literal rendering (agy's matcher compares command strings literally — no glob expansion, and no tilde expansion in either direction — so a directory wildcard never matches and a rule only matches a command written the same way; see [docs/ref/cli-permission-allowlist-standard.md](docs/ref/cli-permission-allowlist-standard.md) §1.2) plus scoped `write_file`/`read_file` rules for the council workspace and rule corpus.
-9. Syncs the same skill folders to `~/.agents/skills/` (Codex CLI), `~/.kiro/skills/` (Kiro CLI, plus pre-allowed shell permissions in `~/.kiro/settings/permissions.yaml`), and `~/.grok/skills/` (Grok CLI) — each a plain global skills root these CLIs read natively, synced per skill folder name exactly like step 2. Skills-only: no rule corpus is generated for these targets.
+2. Deploys to **all detected Claude config directories** — `~/.claude` (default primary), all existing `~/.claude*` profile variants (e.g. `~/.claude-9rt`, `~/.claude-prx`), plus `$CLAUDE_CONFIG_DIR` or `--claude-dir <path>` if provided:
+   - Syncs every skill folder under `skills/*/` (whole directory, including any `references/` or `scripts/`) into `<target>/skills/`, one named folder at a time (copy + managed-names-only prune), removing only Aki's own old/renamed skill directories (`akidoc-*`, `akiadvise`) — any other skill you already have is never touched. `skills/` is a top-level, agent-neutral folder (siblings with `payload/`, not nested under `claude/`) because SKILL.md is a shared open standard both Claude Code and Antigravity/AGY consume identically — see [docs/ref/agent-skills-standard.md](docs/ref/agent-skills-standard.md).
+   - Copies `claude/agents/*.md` into `<target>/agents/` **file by file, never a directory mirror with `--delete`** — that folder is a shared namespace where your own agent definitions sit beside Aki's, exactly like `<target>/skills/`, so nothing you did not install is ever removed.
+   - Replaces `<target>/CLAUDE.md` with the packaged guidance (timestamped backup first), appending this machine's source-repo path and an `@<target>/CLAUDE.local.md` import.
+   - Creates `<target>/CLAUDE.local.md` **only if missing** — never overwritten afterward. On profile variants (`~/.claude-*`), the template imports `@~/.claude/CLAUDE.local.md` by default so machine-wide facts are inherited. Put per-machine/per-profile rules there; they survive every reinstall.
+   - Before the confirmation prompt or any mutation, preflights every existing JSON file it may update: each detected profile's `settings.json`, `~/.gemini/config/skills.json`, `~/.gemini/antigravity-cli/settings.json`, and `~/.gemini/settings.json`. A malformed file or non-object root aborts the install with originals untouched. After preflight, updates `<target>/settings.json` with a timestamped backup: read permission for `~/.aki/akidevrule/**`, skill script execution permissions (`Bash(python3 <target>/skills/*)` and `Bash(python3 ~/.claude/skills/*)`), `skillOverrides.akirule = "on"`, idempotent registration of the `SessionStart` update-check hook.
+   - Installs `<target>/hooks/aki-update-check.mjs` plus its shared parser `<target>/hooks/aki_version_check.mjs`.
+3. Writes `~/.aki/akidevrule/.version` with `installed=`/`version=`/`commit=`/`branch=` and records the source-repo path in `~/.aki/akidevrule/.source-repo` — `version=` is the just-installed CHANGELOG's latest released semver, the same value `install.mjs --check` and the hook compare against remote.
+4. Installs `payload/GEMINI.md` to `~/.gemini/GEMINI.md` — Antigravity global behavior overrides, stamped with a version marker (`[AKIRULE-AG-OVERRIDES-…]`) on line 1. Generates 18 native rule files under `~/.gemini/config/rules/` with YAML `trigger` frontmatter. Deploys 10 skills directly to `~/.gemini/config/skills/` for native auto-discovery (synced per skill folder, same never-touch-the-rest guarantee as step 2), configures `~/.gemini/config/skills.json` with absolute paths as secondary, and merges skill execution permissions into `~/.gemini/antigravity-cli/settings.json` and `~/.gemini/settings.json` — a `command()` prefix rule for each of akiflow's five scripts (the only skill whose scripts agy invokes directly) per skill root, in both the expanded and the tilde-literal rendering (agy's matcher compares command strings literally — no glob expansion, and no tilde expansion in either direction — so a directory wildcard never matches and a rule only matches a command written the same way; see [docs/ref/cli-permission-allowlist-standard.md](docs/ref/cli-permission-allowlist-standard.md) §1.2) plus scoped `write_file`/`read_file` rules for the council workspace and rule corpus.
+5. Syncs the same skill folders to `~/.agents/skills/` (Codex CLI), `~/.kiro/skills/` (Kiro CLI, plus pre-allowed shell permissions in `~/.kiro/settings/permissions.yaml`), and `~/.grok/skills/` (Grok CLI) — each a plain global skills root these CLIs read natively, synced per skill folder name exactly like step 2. Skills-only: no rule corpus is generated for these targets.
 
 Re-running the installer updates the same managed files cleanly.
 

package/install.mjs

@@ -10,6 +10,7 @@ import {
   copyFileSync,
   rmSync,
   renameSync,
+  realpathSync,
 } from "node:fs";
 import { homedir } from "node:os";
 import { join, dirname, basename, extname, relative, isAbsolute, sep } from "node:path";
@@ -37,7 +38,7 @@ const HOME = homedir();
 const INSTALL_ROOT = join(HOME, ".aki", "akidevrule");
 
 const LEGACY_INSTALL_ROOT = join(HOME, ".aki", "claudedoc");
-const CLAUDE_DIR = join(HOME, ".claude");
+const PRIMARY_CLAUDE_DIR = join(HOME, ".claude");
 const GEMINI_DIR = join(HOME, ".gemini");
 const GEMINI_RULES_DIR = join(GEMINI_DIR, "config", "rules");
 const GEMINI_SKILLS_DIR = join(GEMINI_DIR, "config", "skills");
@@ -50,6 +51,83 @@ const OLD_SKILLS = ["akidoc-rules", "akidoc-flow-audit", "akidoc-techbiz-optimiz
 
 const IS_WIN = process.platform === "win32";
 
+if (Number(process.versions.node.split(".")[0]) < 18) {
+  console.error("akidevrule requires Node.js 18 or later.");
+  process.exit(1);
+}
+
+function expandTilde(p) {
+  if (!p) return "";
+  if (p === "~") return HOME;
+  if (p.startsWith("~" + sep) || p.startsWith("~/")) {
+    return join(HOME, p.slice(2));
+  }
+  return p;
+}
+
+function toTildePath(p) {
+  if (!p) return "";
+  if (p === HOME) return "~";
+  if (p.startsWith(HOME + sep) || p.startsWith(HOME + "/")) {
+    return "~" + p.slice(HOME.length).replace(/\\/g, "/");
+  }
+  return p.replace(/\\/g, "/");
+}
+
+function getClaudeDirs(argv = []) {
+  const dirs = new Set();
+  dirs.add(PRIMARY_CLAUDE_DIR);
+
+  // 1. Explicit CLI arguments: --claude-dir <path> or --claude-dir=<path>
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--claude-dir" && argv[i + 1]) {
+      const p = expandTilde(argv[i + 1].trim());
+      dirs.add(isAbsolute(p) ? p : join(HOME, p));
+    } else if (arg.startsWith("--claude-dir=")) {
+      const p = expandTilde(arg.slice("--claude-dir=".length).trim());
+      dirs.add(isAbsolute(p) ? p : join(HOME, p));
+    }
+  }
+
+  // 2. Environment variable: CLAUDE_CONFIG_DIR
+  if (process.env.CLAUDE_CONFIG_DIR) {
+    const p = expandTilde(process.env.CLAUDE_CONFIG_DIR.trim());
+    if (p) dirs.add(isAbsolute(p) ? p : join(HOME, p));
+  }
+
+  // 3. Auto-discover all ~/.claude* directories in HOME
+  try {
+    for (const name of listDir(HOME)) {
+      if (!name.startsWith(".claude")) continue;
+      const full = join(HOME, name);
+      if (!isDir(full)) continue;
+      if (name.includes("backup") || name.endsWith(".bak")) continue;
+      dirs.add(full);
+    }
+  } catch {
+    /* ignore */
+  }
+
+  // 4. Deduplicate symlinks resolving to the same real directory
+  const canonicalMap = new Map();
+  for (const d of dirs) {
+    let canonical = d;
+    try {
+      canonical = realpathSync(d);
+    } catch {
+      /* directory might not exist yet */
+    }
+    if (!canonicalMap.has(canonical)) {
+      canonicalMap.set(canonical, d);
+    } else if (d === canonical) {
+      canonicalMap.set(canonical, d);
+    }
+  }
+
+  return Array.from(canonicalMap.values()).sort();
+}
+
 function pad2(n) {
   return String(n).padStart(2, "0");
 }
@@ -185,10 +263,10 @@ function syncAkiSkills(destRoot) {
   }
 }
 
-function syncAkiAgents() {
+function syncAkiAgents(destClaudeDir) {
   const agentsSrc = join(REPO_ROOT, "claude", "agents");
   if (!isDir(agentsSrc)) return;
-  const dest = join(CLAUDE_DIR, "agents");
+  const dest = join(destClaudeDir, "agents");
   mkdirSync(dest, { recursive: true });
   for (const name of listDir(agentsSrc).sort()) {
     if (name.endsWith(".md")) copyFileSync(join(agentsSrc, name), join(dest, name));
@@ -396,6 +474,22 @@ function installAgRules() {
 // settings.json merge (Claude Code)
 // ---------------------------------------------------------------------------
 
+function validateJsonObject(path, label) {
+  if (!isFile(path)) return;
+  const data = JSON.parse(readFileSync(path, "utf-8"));
+  if (typeof data !== "object" || data === null || Array.isArray(data)) {
+    throw new Error(`${label} must be a JSON object: ${path}`);
+  }
+}
+
+function preflightInstallSettings(claudeDirs) {
+  for (const claudeDir of claudeDirs) validateJsonObject(join(claudeDir, "settings.json"), "Claude settings");
+  if (!isDir(GEMINI_DIR)) return;
+  validateJsonObject(join(GEMINI_DIR, "config", "skills.json"), "Gemini skills config");
+  validateJsonObject(join(GEMINI_DIR, "antigravity-cli", "settings.json"), "Antigravity settings");
+  validateJsonObject(join(GEMINI_DIR, "settings.json"), "Antigravity settings");
+}
+
 function mergeSettings(settingsPath, installRoot, claudeDir) {
   const data = JSON.parse(readFileSync(settingsPath, "utf-8"));
 
@@ -419,6 +513,11 @@ function mergeSettings(settingsPath, installRoot, claudeDir) {
     "Bash(python3 ~/.claude/skills/*)",
     "Bash(python3 ~/.aki/akidevrule/agskills/*)",
   ];
+  const variantBashRule = `Bash(python3 ${toTildePath(join(claudeDir, "skills"))}/*)`;
+  if (!managedBashRules.includes(variantBashRule)) {
+    managedBashRules.push(variantBashRule);
+  }
+
   perms.allow = perms.allow.filter((x) => !legacyBashRules.includes(x));
   for (const rule of managedBashRules) if (!perms.allow.includes(rule)) perms.allow.push(rule);
 
@@ -462,7 +561,7 @@ function mergeSettings(settingsPath, installRoot, claudeDir) {
 // Antigravity permissions merge
 // ---------------------------------------------------------------------------
 
-function mergeAntigravityPermissions() {
+function mergeAntigravityPermissions(claudeDirs = []) {
   if (!isDir(GEMINI_DIR)) return;
 
   const scriptsDir = join(REPO_ROOT, "skills", "akiflow", "scripts");
@@ -470,7 +569,8 @@ function mergeAntigravityPermissions() {
     .filter((n) => n.endsWith(".py"))
     .map((n) => `akiflow/scripts/${n}`)
     .sort();
-  const skillRoots = [GEMINI_SKILLS_DIR, join(CLAUDE_DIR, "skills")];
+  const claudeRoots = claudeDirs.map((d) => join(d, "skills"));
+  const skillRoots = [GEMINI_SKILLS_DIR, ...claudeRoots];
   const launchers = IS_WIN ? ["py -3", "python", "python3"] : ["python3"];
 
   const managedCommands = [];
@@ -506,18 +606,7 @@ function mergeAntigravityPermissions() {
 
   for (const target of targetFiles) {
     let data = {};
-    if (isFile(target)) {
-      try {
-        data = JSON.parse(readFileSync(target, "utf-8"));
-      } catch (e) {
-        console.log(`  \u26a0\ufe0f  Antigravity: ${target} is not parseable JSON (${e}) \u2014 skipped, re-run the installer to retry.`);
-        continue;
-      }
-      if (typeof data !== "object" || data === null || Array.isArray(data)) {
-        console.log(`  \u26a0\ufe0f  Antigravity: ${target} top-level is not an object \u2014 skipped, fix it manually.`);
-        continue;
-      }
-    }
+    if (isFile(target)) data = JSON.parse(readFileSync(target, "utf-8"));
 
     if (typeof data.permissions !== "object" || data.permissions === null || Array.isArray(data.permissions))
       data.permissions = {};
@@ -539,6 +628,23 @@ function mergeAntigravityPermissions() {
       }
     }
 
+    if (perms.allowNonWorkspaceAccess !== true) {
+      perms.allowNonWorkspaceAccess = true;
+      changed = true;
+    }
+    if (perms.agentMode !== true) {
+      perms.agentMode = true;
+      changed = true;
+    }
+    if (!Array.isArray(perms.trustedWorkspaces)) {
+      perms.trustedWorkspaces = [];
+      changed = true;
+    }
+    if (!perms.trustedWorkspaces.includes(HOME)) {
+      perms.trustedWorkspaces.push(HOME);
+      changed = true;
+    }
+
     if (changed || !isFile(target)) {
       mkdirSync(dirname(target), { recursive: true });
       if (isFile(target)) {
@@ -554,7 +660,7 @@ function mergeAntigravityPermissions() {
 // Kiro permissions merge
 // ---------------------------------------------------------------------------
 
-function mergeKiroPermissions() {
+function mergeKiroPermissions(claudeDirs = []) {
   const kiroDir = join(HOME, ".kiro");
   if (!isDir(kiroDir)) return;
 
@@ -564,10 +670,13 @@ function mergeKiroPermissions() {
 
   const managedMatches = [
     "python3 ~/.kiro/skills/*",
-    "python3 ~/.claude/skills/*",
     "python3 ~/.gemini/config/skills/*",
     "python3 ~/.aki/akidevrule/agskills/*",
   ];
+  for (const cDir of claudeDirs) {
+    const m = `python3 ${toTildePath(join(cDir, "skills"))}/*`;
+    if (!managedMatches.includes(m)) managedMatches.push(m);
+  }
 
   if (!isFile(yamlPath)) {
     const lines = [
@@ -593,6 +702,76 @@ function mergeKiroPermissions() {
   }
 }
 
+// ---------------------------------------------------------------------------
+// Deploy single Claude target
+// ---------------------------------------------------------------------------
+
+function installClaudeDir(claudeDir) {
+  mkdirSync(claudeDir, { recursive: true });
+
+  // 1. Skills
+  syncAkiSkills(join(claudeDir, "skills"));
+
+  // 2. Agents
+  syncAkiAgents(claudeDir);
+
+  // 3. Hooks
+  const hooksDest = join(claudeDir, "hooks");
+  mkdirSync(hooksDest, { recursive: true });
+  copyFileSync(join(REPO_ROOT, "claude", "hooks", "aki-update-check.mjs"), join(hooksDest, "aki-update-check.mjs"));
+  copyFileSync(join(REPO_ROOT, "claude", "hooks", "aki_version_check.mjs"), join(hooksDest, "aki_version_check.mjs"));
+  for (const legacy of ["aki-update-check.py", "aki_version_check.py"]) {
+    const p = join(hooksDest, legacy);
+    if (existsSync(p)) rmrf(p);
+  }
+  const pyCache = join(hooksDest, "__pycache__");
+  if (isDir(pyCache)) {
+    for (const n of readdirSync(pyCache)) if (n.startsWith("aki_version_check.")) rmrf(join(pyCache, n));
+    if (readdirSync(pyCache).length === 0) rmrf(pyCache);
+  }
+
+  // 4. CLAUDE.md
+  const claudeMd = join(claudeDir, "CLAUDE.md");
+  backup(claudeMd);
+  pruneBackups(claudeMd);
+
+  const claudeMdSrc = readFileSync(join(REPO_ROOT, "claude", "CLAUDE.md"), "utf-8");
+  const propagateCmd = `node "${join(REPO_ROOT, "install.mjs")}"`;
+  const localMd = join(claudeDir, "CLAUDE.local.md");
+  const localMdTilde = toTildePath(localMd);
+  const ruleSourceBlock =
+    "\n## akidevrule — edit source, not deployed copy (ABSOLUTE)\n\n" +
+    `The deployed rule files at \`${INSTALL_ROOT}\` are **overwritten on every install**.\n` +
+    "To change any shared rule:\n" +
+    `1. Edit in the **source repo**: \`${join(REPO_ROOT, "payload")}/\`\n` +
+    `2. Run \`${propagateCmd}\` to propagate.\n\n` +
+    `**NEVER edit files under \`${INSTALL_ROOT}\` directly** — changes will be silently lost on the next install.\n\n` +
+    `@${localMdTilde}\n`;
+  writeTextLf(claudeMd, claudeMdSrc + ruleSourceBlock);
+
+  // 5. CLAUDE.local.md (create-only if missing)
+  if (!isFile(localMd)) {
+    const isPrimary = claudeDir === PRIMARY_CLAUDE_DIR;
+    const templateContent = isPrimary
+      ? "# Machine-local Claude instructions\n\n" +
+        "This file is machine-specific and never touched by akidevrule installs.\n" +
+        "Add any per-machine rules here (e.g. build constraints, IDE paths, remote flags).\n"
+      : "# Machine-local Claude instructions (profile variant)\n\n" +
+        "This file is machine-specific and never touched by akidevrule installs.\n" +
+        "@~/.claude/CLAUDE.local.md\n\n" +
+        "# Add any profile-specific instructions below:\n";
+    writeTextLf(localMd, templateContent);
+    console.log(`📝 Created ${localMd} (machine-local template)`);
+  }
+
+  // 6. settings.json
+  const settingsPath = join(claudeDir, "settings.json");
+  if (!isFile(settingsPath)) writeTextLf(settingsPath, "{}\n");
+  backup(settingsPath);
+  pruneBackups(settingsPath);
+  mergeSettings(settingsPath, INSTALL_ROOT, claudeDir);
+}
+
 // ---------------------------------------------------------------------------
 // skills.json for Antigravity
 // ---------------------------------------------------------------------------
@@ -600,14 +779,7 @@ function mergeKiroPermissions() {
 function updateSkillsJson() {
   const skillsJson = join(GEMINI_DIR, "config", "skills.json");
   mkdirSync(dirname(skillsJson), { recursive: true });
-  let data = {};
-  if (existsSync(skillsJson)) {
-    try {
-      data = JSON.parse(readFileSync(skillsJson, "utf-8"));
-    } catch {
-      data = {};
-    }
-  }
+  const data = isFile(skillsJson) ? JSON.parse(readFileSync(skillsJson, "utf-8")) : {};
   if (!Array.isArray(data.entries)) data.entries = [];
   const absPath = join(INSTALL_ROOT, "agskills");
   const tildePath = "~/.aki/akidevrule/agskills";
@@ -663,78 +835,71 @@ async function printVersionCheck() {
 // inspect_status (pre-install preview)
 // ---------------------------------------------------------------------------
 
-async function inspectStatus() {
+async function inspectStatus(claudeDirs) {
   console.log(cyanBold("=== SYSTEM STATUS CHECK BEFORE INSTALL ==="));
 
   const head = gitShortHash(REPO_ROOT);
   const sameCheckout = !!head && installedCommit() === head && gitTreeClean(REPO_ROOT);
   if (sameCheckout)
-    console.log(`\u2705 Already installed from this exact commit (${head}, clean tree) \u2014 reinstalling refreshes identical content.`);
+    console.log(`✅ Already installed from this exact commit (${head}, clean tree) — reinstalling refreshes identical content.`);
 
   const { state, localVersion, remoteVersion } = await getVersionStatus();
   if (state === STATE_CURRENT)
-    console.log(`\u2139\ufe0f  Installed release ${localVersion} matches remote; the overwrite below comes from this checkout, which may carry [Unreleased] work.`);
+    console.log(`ℹ️  Installed release ${localVersion} matches remote; the overwrite below comes from this checkout, which may carry [Unreleased] work.`);
   else if (state === STATE_UPDATE)
-    console.log(`\ud83d\udd14 A newer akidevrule is available: ${localVersion} \u2192 ${remoteVersion} (this install only refreshes local files at the current repo checkout's version).`);
+    console.log(`🔔 A newer akidevrule is available: ${localVersion} → ${remoteVersion} (this install only refreshes local files at the current repo checkout's version).`);
   else if (state === STATE_MISSING)
-    console.log("\ud83d\udce6 Fresh install \u2014 akidevrule is not currently installed on this machine.");
+    console.log("📦 Fresh install — akidevrule is not currently installed on this machine.");
   else if (state === STATE_UNKNOWN)
-    console.log("\u26a0\ufe0f  Could not reach the remote CHANGELOG to compare versions (network/parse error) \u2014 proceeding with local install only.");
+    console.log("⚠️  Could not reach the remote CHANGELOG to compare versions (network/parse error) — proceeding with local install only.");
   else if (state === STATE_AHEAD)
-    console.log(`\u2139\ufe0f  Local install (${localVersion || "Unreleased-only"}) is ahead of or diverged from remote (${remoteVersion}).`);
+    console.log(`ℹ️  Local install (${localVersion || "Unreleased-only"}) is ahead of or diverged from remote (${remoteVersion}).`);
 
-  if (isDir(INSTALL_ROOT)) console.log(`\ud83d\udce6 Payload rules: will ${yellowBold("OVERWRITE")} ${INSTALL_ROOT}`);
-  else console.log(`\ud83d\udce6 Payload rules: will ${greenBold("CREATE")} at ${INSTALL_ROOT}`);
+  if (isDir(INSTALL_ROOT)) console.log(`📦 Payload rules: will ${yellowBold("OVERWRITE")} ${INSTALL_ROOT}`);
+  else console.log(`📦 Payload rules: will ${greenBold("CREATE")} at ${INSTALL_ROOT}`);
 
-  const claudeMd = join(CLAUDE_DIR, "CLAUDE.md");
-  if (isFile(claudeMd)) console.log(`\ud83d\udcdd Global CLAUDE.md: will ${yellowBold("OVERWRITE")} ${claudeMd} (backed up)`);
-  else console.log(`\ud83d\udcdd Global CLAUDE.md: will ${greenBold("CREATE")} ${claudeMd}`);
+  console.log(`🤖 Claude config targets (${claudeDirs.length}): ${claudeDirs.map(toTildePath).join(", ")}`);
+  for (const claudeDir of claudeDirs) {
+    const claudeMd = join(claudeDir, "CLAUDE.md");
+    if (isFile(claudeMd)) console.log(`  📝 Global CLAUDE.md (${toTildePath(claudeDir)}): will ${yellowBold("OVERWRITE")} (backed up)`);
+    else console.log(`  📝 Global CLAUDE.md (${toTildePath(claudeDir)}): will ${greenBold("CREATE")}`);
+
+    const oldPresent = OLD_SKILLS.filter((s) => isDir(join(claudeDir, "skills", s)));
+    if (oldPresent.length) console.log(`  🗑️  Old skills in ${toTildePath(claudeDir)} will be REMOVED: ${redBold(oldPresent.join(" "))}`);
+  }
 
   const skillsSrc = join(REPO_ROOT, "skills");
   if (isDir(skillsSrc)) {
-    for (const name of listDir(skillsSrc).sort()) {
-      const skillDir = join(skillsSrc, name);
-      if (!isDir(skillDir)) continue;
-      const destSkill = join(CLAUDE_DIR, "skills", name, "SKILL.md");
-      if (isFile(destSkill)) console.log(`\ud83d\udd27 Skill ${name}: will ${yellowBold("OVERWRITE")} ${destSkill}`);
-      else console.log(`\ud83d\udd27 Skill ${name}: will ${greenBold("CREATE")} ${destSkill}`);
-    }
+    const skillList = listDir(skillsSrc).filter((n) => isDir(join(skillsSrc, n))).sort();
+    console.log(`🔧 Skills (${skillList.length}): will sync to all Claude targets (${skillList.join(", ")})`);
   }
 
   const agentsSrc = join(REPO_ROOT, "claude", "agents");
   if (isDir(agentsSrc)) {
-    for (const name of listDir(agentsSrc).sort()) {
-      if (!name.endsWith(".md")) continue;
-      const destAgent = join(CLAUDE_DIR, "agents", name);
-      if (isFile(destAgent)) console.log(`\ud83e\udde0 Agent ${name}: will ${yellowBold("OVERWRITE")} ${destAgent}`);
-      else console.log(`\ud83e\udde0 Agent ${name}: will ${greenBold("CREATE")} ${destAgent}`);
-    }
+    const agentList = listDir(agentsSrc).filter((n) => n.endsWith(".md")).sort();
+    console.log(`🧠 Agents (${agentList.length}): will sync to all Claude targets (${agentList.map((n) => basename(n, ".md")).join(", ")})`);
   }
 
-  const oldPresent = OLD_SKILLS.filter((s) => isDir(join(CLAUDE_DIR, "skills", s)));
-  if (oldPresent.length) console.log(`\ud83d\uddd1\ufe0f  Old skills will be REMOVED: ${redBold(oldPresent.join(" "))}`);
-
-  console.log("\u2699\ufe0f  settings: checking permissions and skill overrides across platforms...");
-  const settingsPath = join(CLAUDE_DIR, "settings.json");
-  if (isFile(settingsPath)) {
-    try {
-      const data = JSON.parse(readFileSync(settingsPath, "utf-8"));
-      const readRule = `Read(//${INSTALL_ROOT.replace(/^\/+/, "")}/**)`;
-      const allow = (data.permissions && data.permissions.allow) || [];
-      if (allow.includes(readRule)) console.log("  \u2705 Claude Code: Read permission for payload already granted.");
-      else console.log("  \u26a0\ufe0f  Claude Code: Read permission MISSING. Will be added automatically.");
-      if (allow.includes("Bash(python3 ~/.claude/skills/*)")) console.log("  \u2705 Claude Code: Skill scripts Bash execution permission already granted.");
-      else console.log("  \u26a0\ufe0f  Claude Code: Skill scripts Bash execution permission will be added.");
-      const overrides = data.skillOverrides || {};
-      if (overrides.akirule === "on") console.log("  \u2705 Claude Code: akirule skill is already enabled (on).");
-      else console.log("  \u26a0\ufe0f  Claude Code: Will auto-enable skill: akirule");
-      const stale = ["akidoc-rules", "akidoc-flow-audit", "akidoc-techbiz-optimizer"].filter((s) => s in overrides);
-      if (stale.length) console.log(`  \ud83d\uddd1\ufe0f  Claude Code: Stale skillOverrides will be REMOVED: ${stale.join(", ")}`);
-    } catch (e) {
-      console.log(`  \u274c Error reading Claude settings.json: ${e}`);
+  console.log("⚙️  settings: checking permissions and skill overrides across platforms...");
+  for (const claudeDir of claudeDirs) {
+    const settingsPath = join(claudeDir, "settings.json");
+    if (isFile(settingsPath)) {
+      try {
+        const data = JSON.parse(readFileSync(settingsPath, "utf-8"));
+        const readRule = `Read(//${INSTALL_ROOT.replace(/^\/+/, "")}/**)`;
+        const allow = (data.permissions && data.permissions.allow) || [];
+        const bashRule = `Bash(python3 ${toTildePath(join(claudeDir, "skills"))}/*)`;
+        const bashOk = allow.includes(bashRule) || allow.includes("Bash(python3 ~/.claude/skills/*)");
+        const readOk = allow.includes(readRule);
+        const overrides = data.skillOverrides || {};
+        const akiOk = overrides.akirule === "on";
+        console.log(`  Claude (${toTildePath(claudeDir)}): Read=${readOk ? "✅" : "⚠️ missing"}, Bash=${bashOk ? "✅" : "⚠️ missing"}, akirule=${akiOk ? "✅" : "⚠️ will enable"}`);
+      } catch (e) {
+        console.log(`  ❌ Error reading ${settingsPath}: ${e}`);
+      }
+    } else {
+      console.log(`  ⚠️  Claude (${toTildePath(claudeDir)}): No settings.json yet. Will be CREATED.`);
     }
-  } else {
-    console.log("  \u26a0\ufe0f  Claude Code: No settings.json yet. Will be CREATED.");
   }
 
   if (isDir(GEMINI_DIR)) {
@@ -744,13 +909,13 @@ async function inspectStatus() {
         const data = JSON.parse(readFileSync(agSettings, "utf-8"));
         const allow = (data.permissions && data.permissions.allow) || [];
         const probeRule = `command(python3 ${join(GEMINI_SKILLS_DIR, "akiflow", "scripts", "council_open.py")})`;
-        if (allow.includes(probeRule)) console.log("  \u2705 Antigravity CLI: per-script skill permissions already granted.");
-        else console.log("  \u26a0\ufe0f  Antigravity CLI: per-script skill permissions will be added.");
+        if (allow.includes(probeRule)) console.log("  ✅ Antigravity CLI: per-script skill permissions already granted.");
+        else console.log("  ⚠️  Antigravity CLI: per-script skill permissions will be added.");
       } catch (e) {
-        console.log(`  \u274c Error reading Antigravity settings: ${e}`);
+        console.log(`  ❌ Error reading Antigravity settings: ${e}`);
       }
     } else {
-      console.log("  \u26a0\ufe0f  Antigravity CLI: settings.json will be updated with skill permissions.");
+      console.log("  ⚠️  Antigravity CLI: settings.json will be updated with skill permissions.");
     }
   }
 
@@ -762,14 +927,17 @@ async function inspectStatus() {
 // print_summary (post-install)
 // ---------------------------------------------------------------------------
 
-function printSummary() {
+function printSummary(claudeDirs) {
   console.log(`\n${greenBold("=== INSTALL SUCCEEDED ===")}`);
 
   const gitHash = gitShortHash(REPO_ROOT);
   const hashSuffix = gitHash ? ` (${gitHash})` : "";
-  console.log(`\ud83d\udcc5 Time    : ${dateTimeNow()}${hashSuffix}`);
-  console.log(`\ud83d\udcc2 Payload : ${INSTALL_ROOT}`);
-  console.log(`\ud83d\udd27 Skills  : ${join(CLAUDE_DIR, "skills")}${sep}`);
+  console.log(`📅 Time    : ${dateTimeNow()}${hashSuffix}`);
+  console.log(`📁 Payload : ${INSTALL_ROOT}`);
+  console.log(`🤖 Claude targets (${claudeDirs.length}):`);
+  for (const dir of claudeDirs) {
+    console.log(`   - ${toTildePath(dir)} (skills, agents, hooks, CLAUDE.md, settings.json)`);
+  }
   console.log();
 
   console.log(cyanBold("Rules deployed:"));
@@ -791,39 +959,39 @@ function printSummary() {
 
   console.log();
   console.log(cyanBold("Skills deployed:"));
-  const claudeSkills = join(CLAUDE_DIR, "skills");
-  if (isDir(claudeSkills)) {
-    for (const name of listDir(claudeSkills).sort()) {
-      if (isDir(join(claudeSkills, name))) console.log(`  \ud83d\udd27 ${name}`);
+  const primarySkills = join(PRIMARY_CLAUDE_DIR, "skills");
+  if (isDir(primarySkills)) {
+    for (const name of listDir(primarySkills).sort()) {
+      if (isDir(join(primarySkills, name))) console.log(`  🔧 ${name}`);
     }
   }
 
   const agentsSrc = join(REPO_ROOT, "claude", "agents");
   if (isDir(agentsSrc)) {
     console.log();
-    console.log(cyanBold(`Agents deployed (${join(CLAUDE_DIR, "agents")} \u2014 your own agents there are untouched):`));
+    console.log(cyanBold(`Agents deployed (${claudeDirs.map(toTildePath).join(", ")} — your own agents there are untouched):`));
     for (const name of listDir(agentsSrc).sort()) {
-      if (name.endsWith(".md")) console.log(`  \ud83e\udde0 ${basename(name, ".md")}`);
+      if (name.endsWith(".md")) console.log(`  🧠 ${basename(name, ".md")}`);
     }
   }
 
   console.log();
   console.log(cyanBold("Other CLI skill roots synced (harmless if that CLI isn't installed):"));
-  console.log(`  \ud83e\udd16 Codex CLI : ${CODEX_SKILLS_DIR}`);
-  console.log(`  \ud83e\udd16 Kiro CLI  : ${KIRO_SKILLS_DIR}`);
-  console.log(`  \ud83e\udd16 Grok CLI  : ${GROK_SKILLS_DIR}`);
+  console.log(`  🤖 Codex CLI : ${CODEX_SKILLS_DIR}`);
+  console.log(`  🤖 Kiro CLI  : ${KIRO_SKILLS_DIR}`);
+  console.log(`  🤖 Grok CLI  : ${GROK_SKILLS_DIR}`);
 
   console.log();
   console.log(cyanBold("Permissions configured:"));
-  console.log("  \u2699\ufe0f  Claude Code     : Read(~/.aki/akidevrule/**), Bash(python3 ~/.claude/skills/*)");
+  console.log("  ⚙️  Claude Code     : Read(~/.aki/akidevrule/**), Bash(python3 <target>/skills/*)");
   if (isDir(GEMINI_DIR))
-    console.log("  \u2699\ufe0f  Antigravity     : per-script command() rules (akiflow scripts \u00d72 roots \u00d72 path renderings \u00d7the platform's python launchers), write_file(~/.aki/agent-council/), read_file(~/.aki/akidevrule/)");
+    console.log("  ⚙️  Antigravity     : per-script command() rules (akiflow scripts ×all roots ×2 path renderings ×the platform's python launchers), write_file(~/.aki/agent-council/), read_file(~/.aki/akidevrule/)");
   if (isDir(join(HOME, ".kiro")))
-    console.log("  \u2699\ufe0f  Kiro CLI        : capability:shell (python3 ~/.kiro/skills/*, ~/.claude/skills/*)");
+    console.log("  ⚙️  Kiro CLI        : capability:shell (python3 ~/.kiro/skills/*, ~/.claude*/skills/*)");
 
   console.log();
   console.log(cyanBold("Hooks deployed:"));
-  console.log("  \ud83d\udce2 aki-update-check (SessionStart, notify-only) \u2014 notifies when a new rule version is available");
+  console.log("  📢 aki-update-check (SessionStart, notify-only) — notifies when a new rule version is available");
 
   console.log(`\n${greenBold("==============================")}`);
 }
@@ -846,15 +1014,8 @@ function ask(question) {
 // Main install logic
 // ---------------------------------------------------------------------------
 
-async function runInstall() {
-  // Legacy migration: ~/.aki/claudedoc -> ~/.aki/akidevrule
-  if (isDir(LEGACY_INSTALL_ROOT) && !existsSync(INSTALL_ROOT)) {
-    mkdirSync(dirname(INSTALL_ROOT), { recursive: true });
-    renameSync(LEGACY_INSTALL_ROOT, INSTALL_ROOT);
-    console.log(`\ud83d\udce6 Migrated legacy install root: ${LEGACY_INSTALL_ROOT} \u2192 ${INSTALL_ROOT}`);
-  }
-
-  const sameCheckout = await inspectStatus();
+async function runInstall(claudeDirs) {
+  const sameCheckout = await inspectStatus(claudeDirs);
 
   // Skip the prompt only for a byte-identical overwrite (same commit, clean tree).
   if (process.stdin.isTTY && !sameCheckout) {
@@ -864,11 +1025,17 @@ async function runInstall() {
       process.exit(1);
     }
   }
+
+  // Legacy migration: ~/.aki/claudedoc -> ~/.aki/akidevrule
+  if (isDir(LEGACY_INSTALL_ROOT) && !existsSync(INSTALL_ROOT)) {
+    mkdirSync(dirname(INSTALL_ROOT), { recursive: true });
+    renameSync(LEGACY_INSTALL_ROOT, INSTALL_ROOT);
+    console.log(`📦 Migrated legacy install root: ${LEGACY_INSTALL_ROOT} → ${INSTALL_ROOT}`);
+  }
   console.log("Installing...");
 
   // --- 1. Payload -> INSTALL_ROOT ---
   mkdirSync(INSTALL_ROOT, { recursive: true });
-  mkdirSync(join(CLAUDE_DIR, "skills"), { recursive: true });
 
   const payloadSrc = join(REPO_ROOT, "payload");
   const EXCLUDED = new Set(["ref-ECC", ".DS_Store", "GEMINI.md"]);
@@ -909,65 +1076,19 @@ async function runInstall() {
     if (branch) versionLines.push(`branch=${branch}`);
   }
   writeTextLf(join(INSTALL_ROOT, ".version"), versionLines.join("\n") + "\n");
+  writeTextLf(join(INSTALL_ROOT, ".source-repo"), REPO_ROOT + "\n");
+
+  // --- 2. Claude targets (skills, agents, hooks, CLAUDE.md, settings.json) ---
+  for (const cDir of claudeDirs) {
+    installClaudeDir(cDir);
+  }
 
-  // --- 2. Skills ---
-  syncAkiSkills(join(CLAUDE_DIR, "skills"));
+  // --- 3. Other CLI skill roots ---
   syncAkiSkills(CODEX_SKILLS_DIR);
   syncAkiSkills(KIRO_SKILLS_DIR);
   syncAkiSkills(GROK_SKILLS_DIR);
 
-  // --- 3. Agents ---
-  syncAkiAgents();
-
-  // --- 4. Hooks + source-repo ---
-  const hooksDest = join(CLAUDE_DIR, "hooks");
-  mkdirSync(hooksDest, { recursive: true });
-  copyFileSync(join(REPO_ROOT, "claude", "hooks", "aki-update-check.mjs"), join(hooksDest, "aki-update-check.mjs"));
-  copyFileSync(join(REPO_ROOT, "claude", "hooks", "aki_version_check.mjs"), join(hooksDest, "aki_version_check.mjs"));
-  // Remove orphaned Python hooks left by a pre-3.0 install.
-  for (const legacy of ["aki-update-check.py", "aki_version_check.py"]) {
-    const p = join(hooksDest, legacy);
-    if (existsSync(p)) rmrf(p);
-  }
-  // hooks/ is shared with the user's own hooks, so only our bytecode is removed, never the whole cache.
-  const pyCache = join(hooksDest, "__pycache__");
-  if (isDir(pyCache)) {
-    for (const n of readdirSync(pyCache)) if (n.startsWith("aki_version_check.")) rmrf(join(pyCache, n));
-    if (readdirSync(pyCache).length === 0) rmrf(pyCache);
-  }
-  writeTextLf(join(INSTALL_ROOT, ".source-repo"), REPO_ROOT + "\n");
-
-  // --- 5. CLAUDE.md ---
-  mkdirSync(CLAUDE_DIR, { recursive: true });
-  backup(join(CLAUDE_DIR, "CLAUDE.md"));
-  console.log("\ud83e\uddf9 Pruning CLAUDE.md backups (keeping the 2 most recent):");
-  pruneBackups(join(CLAUDE_DIR, "CLAUDE.md"));
-
-  const claudeMdSrc = readFileSync(join(REPO_ROOT, "claude", "CLAUDE.md"), "utf-8");
-  const propagateCmd = `node "${join(REPO_ROOT, "install.mjs")}"`;
-  const ruleSourceBlock =
-    "\n## akidevrule \u2014 edit source, not deployed copy (ABSOLUTE)\n\n" +
-    `The deployed rule files at \`${INSTALL_ROOT}\` are **overwritten on every install**.\n` +
-    "To change any shared rule:\n" +
-    `1. Edit in the **source repo**: \`${join(REPO_ROOT, "payload")}/\`\n` +
-    `2. Run \`${propagateCmd}\` to propagate.\n\n` +
-    `**NEVER edit files under \`${INSTALL_ROOT}\` directly** \u2014 changes will be silently lost on the next install.\n\n` +
-    "@~/.claude/CLAUDE.local.md\n";
-  writeTextLf(join(CLAUDE_DIR, "CLAUDE.md"), claudeMdSrc + ruleSourceBlock);
-
-  // --- 6. CLAUDE.local.md (create-only) ---
-  const localMd = join(CLAUDE_DIR, "CLAUDE.local.md");
-  if (!isFile(localMd)) {
-    writeTextLf(
-      localMd,
-      "# Machine-local Claude instructions\n\n" +
-        "This file is machine-specific and never touched by akidevrule installs.\n" +
-        "Add any per-machine rules here (e.g. build constraints, IDE paths, remote flags).\n"
-    );
-    console.log(`\ud83d\udcdd Created ${localMd} (machine-local template)`);
-  }
-
-  // --- 7. GEMINI.md (only when ~/.gemini exists) ---
+  // --- 4. GEMINI.md (only when ~/.gemini exists) ---
   if (isDir(GEMINI_DIR)) {
     const geminiFile = join(GEMINI_DIR, "GEMINI.md");
     const geminiLocal = join(GEMINI_DIR, "GEMINI.local.md");
@@ -983,11 +1104,11 @@ async function runInstall() {
           "This file is machine-specific and never touched by akidevrule installs.\n" +
           "Add machine-specific paths, CLIs, and emulator commands here.\n"
       );
-      console.log(`\ud83d\udcdd Created ${geminiLocal} (machine-local template)`);
+      console.log(`📝 Created ${geminiLocal} (machine-local template)`);
     }
 
     backup(geminiFile);
-    console.log("\ud83e\uddf9 Pruning GEMINI.md backups (keeping the 2 most recent):");
+    console.log("🧹 Pruning GEMINI.md backups (keeping the 2 most recent):");
     pruneBackups(geminiFile);
 
     const d = new Date();
@@ -995,50 +1116,43 @@ async function runInstall() {
     const geminiTemplate = readFileSync(join(REPO_ROOT, "payload", "GEMINI.md"), "utf-8");
     const geminiContent = geminiTemplate.split("__VERSION__").join(geminiVersion);
 
+    const propagateCmd = `node "${join(REPO_ROOT, "install.mjs")}"`;
     const geminiSourceBlock =
-      "\n## 15. Shared rule source \u2014 edit source, not deployed copy (ABSOLUTE)\n\n" +
-      `The deployed rule corpus at \`${INSTALL_ROOT}\` is **overwritten on every install**.\n` +
+      "\n## 15. Shared rule source — edit source, not deployed copy (ABSOLUTE)\n\n" +
+      `The deployed rule corpus at \`${INSTALL_ROOT}\` are **overwritten on every install**.\n` +
       "To change any shared rule:\n" +
       `1. Edit in the **source repo**: \`${join(REPO_ROOT, "payload")}/\` (rules) or \`${join(REPO_ROOT, "claude")}/\` (runtime assets).\n` +
-      `2. Read \`${join(REPO_ROOT, "CLAUDE.md")}\` first \u2014 it lists which files must be updated together.\n` +
+      `2. Read \`${join(REPO_ROOT, "CLAUDE.md")}\` first — it lists which files must be updated together.\n` +
       `3. Run \`${propagateCmd}\` to propagate.\n\n` +
-      `**NEVER edit files under \`${INSTALL_ROOT}\` directly** \u2014 changes are silently lost on the next install.\n`;
+      `**NEVER edit files under \`${INSTALL_ROOT}\` directly** — changes will be silently lost on the next install.\n`;
 
     const localContent = readFileSync(geminiLocal, "utf-8");
     const fullGemini = geminiContent + geminiSourceBlock + "\n---\n\n" + localContent;
     writeTextLf(geminiFile, fullGemini);
 
-    console.log(`\ud83e\udd16 Installed ${geminiFile} (marker ${geminiMarker}${geminiVersion}])`);
+    console.log(`🤖 Installed ${geminiFile} (marker ${geminiMarker}${geminiVersion}])`);
     if (hadUnmanaged) {
-      console.log("  \u26a0\ufe0f  Your previous ~/.gemini/GEMINI.md was replaced (saved as *.akidevrule-backup-*).");
+      console.log("  ⚠️  Your previous ~/.gemini/GEMINI.md was replaced (saved as *.akidevrule-backup-*).");
       console.log(`      Move any machine-local lines from that backup into ${geminiLocal}.`);
     }
 
-    // --- 8. Antigravity rules ---
+    // --- Antigravity rules ---
     const agCount = installAgRules();
-    console.log(`\ud83e\udded Installed ${agCount} rule(s) to ${GEMINI_RULES_DIR} (read by AG, AG IDE and AGY)`);
+    console.log(`🧭 Installed ${agCount} rule(s) to ${GEMINI_RULES_DIR} (read by AG, AG IDE and AGY)`);
 
-    // --- 9. Antigravity skills ---
+    // --- Antigravity skills ---
     syncAkiSkills(GEMINI_SKILLS_DIR);
     syncAkiSkills(join(INSTALL_ROOT, "agskills"));
     updateSkillsJson();
-    console.log(`\ud83d\udca1 Deployed skills to ${GEMINI_SKILLS_DIR} & updated ~/.gemini/config/skills.json`);
-    console.log("  \u2139\ufe0f  Antigravity discovers rules and skills at startup \u2014 restart the app or start a new agy session.");
+    console.log(`💡 Deployed skills to ${GEMINI_SKILLS_DIR} & updated ~/.gemini/config/skills.json`);
+    console.log("  ℹ️  Antigravity discovers rules and skills at startup — restart the app or start a new agy session.");
   }
 
-  // --- 10. settings.json ---
-  const settingsPath = join(CLAUDE_DIR, "settings.json");
-  if (!isFile(settingsPath)) writeTextLf(settingsPath, "{}\n");
-  backup(settingsPath);
-  console.log("\ud83e\uddf9 Pruning settings.json backups (keeping the 2 most recent):");
-  pruneBackups(settingsPath);
-  mergeSettings(settingsPath, INSTALL_ROOT, CLAUDE_DIR);
-
-  // --- 11. Antigravity & Kiro permissions ---
-  mergeAntigravityPermissions();
-  mergeKiroPermissions();
+  // --- 5. Antigravity & Kiro permissions ---
+  mergeAntigravityPermissions(claudeDirs);
+  mergeKiroPermissions(claudeDirs);
 
-  printSummary();
+  printSummary(claudeDirs);
 }
 
 // ---------------------------------------------------------------------------
@@ -1048,17 +1162,20 @@ async function runInstall() {
 async function main() {
   const argv = process.argv.slice(2);
   if (argv.includes("-h") || argv.includes("--help")) {
-    console.log("akidevrule installer \u2014 deploys shared rule corpus and skills.");
+    console.log("akidevrule installer — deploys shared rule corpus and skills.");
     console.log("");
-    console.log("Usage: node install.mjs [--check]");
-    console.log("  --check   Print installed vs latest akidevrule version and exit. No install, no overwrite.");
+    console.log("Usage: node install.mjs [--check] [--claude-dir <path>]");
+    console.log("  --check              Print installed vs latest akidevrule version and exit. No install, no overwrite.");
+    console.log("  --claude-dir <path>  Explicit Claude config directory to include (also auto-detects ~/.claude* and $CLAUDE_CONFIG_DIR).");
     process.exit(0);
   }
   if (argv.includes("--check")) {
     await printVersionCheck();
     process.exit(0);
   }
-  await runInstall();
+  const claudeDirs = getClaudeDirs(argv);
+  preflightInstallSettings(claudeDirs);
+  await runInstall(claudeDirs);
 }
 
 main().catch((err) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akinet/akidevrule",
-  "version": "3.1.0",
+  "version": "3.2.0",
   "description": "Aki's shared rule corpus + Agent Skills for Claude Code, Gemini/Antigravity, Codex, Kiro and Grok — install and update with one command.",
   "keywords": [
     "claude-code",

package/payload/RULE-coding.md

@@ -39,6 +39,7 @@ A principle with the procedure that guarantees it — apply to any edit of code
 ### B3. Verification
 - Done means verified — never claim success from intention alone.
 - Verify by the **narrowest tool that actually settles the doubt**: static reading and type/lint/unit checks first. Never spin up a full build or dev server just to catch a typo a typecheck would catch.
+- **Never move uncommitted work to attribute a failing check.** No `git stash`/`checkout -- <path>`/`restore`/`reset`/`clean` to learn whether a typecheck or build error pre-exists: read the error against the changed files, or rebuild the committed tree in a separate `git worktree`. The working tree may hold the owner's unfinished work, and a known pre-existing failure yields no information worth risking it.
 - **Static reading IS verification** when the property is fully determined by visible code flow — state what was read as the evidence and close the checklist item on that evidence. Escalate a tier (typecheck → unit → runtime) only when you can name the specific doubt that tier settles.
 - **Never gate a done-transition on human manual testing for a check that static reading or an automated tier settles.** A plan's verify checklist stays fully detailed — the violation is not the checklist, it is parking finished work as "waiting for manual test" on items whose truth the code flow already proves. Hand the human only what genuinely needs human runtime judgment: UX feel, visual rendering, live external integration.
 - **Running the app is not a default verification step — but not running it does not let you claim "Done".** Starting a dev server or making live network calls stays **user-triggered**, not self-authorized (cost and side effects are the user's call). A full build and the test suite are **not** in that category — they are self-authorized, gated by the moment instead: **after edits** → typecheck/lint/related unit tests, never a full build per edit; **committing a large batch** (spans several modules, or touches build config/dependencies) → add the build; **ship/release/deploy** → full build plus full test suite is mandatory and self-authorized, commands derived per `release.B7` step 6. When a change's real risk lives **only at runtime** — hydration, layout/z-index, route/auth flow, a dynamically-built class a build step may purge — and you cannot settle it statically, you may **not** report "Done": halt and report the state as **"unverified — needs a runtime check"**, propose the exact command, and hand it to the user (see [[RULE-agent-behavior]] A3). "Done" for logic you only compiled is not done.