claude-nomad 0.17.1 → 0.18.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [0.18.0](https://github.com/funkadelic/claude-nomad/compare/v0.17.2...v0.18.0) (2026-05-22)
+
+
+### Added
+
+* **init:** auto-disable GitHub Actions on private mirror ([#94](https://github.com/funkadelic/claude-nomad/issues/94)) ([aee4736](https://github.com/funkadelic/claude-nomad/commit/aee47365f504c4700a619a2828c6fca8c18b1868))
+
+## [0.17.2](https://github.com/funkadelic/claude-nomad/compare/v0.17.1...v0.17.2) (2026-05-22)
+
+
+### Fixed
+
+* **ci:** retry smoke-test install for registry propagation ([#92](https://github.com/funkadelic/claude-nomad/issues/92)) ([1ae7576](https://github.com/funkadelic/claude-nomad/commit/1ae75760f674e93be1fadc2b927ee4dd03f9d346))
+
 ## [0.17.1](https://github.com/funkadelic/claude-nomad/compare/v0.17.0...v0.17.1) (2026-05-21)
 
 

package/README.md

@@ -30,6 +30,9 @@ Two things it does that ad-hoc dotfiles syncing can't:
 - **Getting started**
   - [Requirements](#requirements)
   - [Setup](#setup)
+    - [Privacy by default](#privacy-by-default)
+    - [Bootstrap](#bootstrap)
+    - [Initialize the repo layout](#initialize-the-repo-layout)
   - [Migrating an existing ~/.claude/](#migrating-an-existing-claude)
   - [Upgrading the tool](#upgrading-the-tool)
 - **Reference**
@@ -51,7 +54,7 @@ npm i -g claude-nomad
 
 ```bash
 # Clone your private mirror so nomad has a repo to sync into.
-git clone git@github.com:you/claude-nomad.git ~/claude-nomad
+git clone git@github.com:<your-username>/claude-nomad.git ~/claude-nomad
 
 # Add to ~/.zshrc or ~/.bashrc:
 export NOMAD_HOST=<your-host-label>
@@ -76,7 +79,7 @@ First-host bootstrap and the safe-migration sequence for a populated `~/.claude/
 claude-nomad is a **tool**, not a config store. You maintain a separate **private** repo that holds your actual config (`CLAUDE.md`, agents, skills, settings overrides, session transcripts). The tool's source and your config end up coexisting in one working tree on each host.
 
 ```
-public funkadelic/claude-nomad          your private you/claude-nomad
+public funkadelic/claude-nomad          your private <your-username>/claude-nomad
   ├── src/         (the CLI)              ├── src/         (copy of the CLI)
   ├── package.json                        ├── package.json
   └── ...                                 ├── ...
@@ -101,7 +104,7 @@ By default the CLI operates on `~/claude-nomad/` (see `REPO_HOME` in `src/config
 ```
 ~/claude-nomad/
 ├── src/                      # the CLI (came from the public tool repo)
-├── scripts/                  # tool helpers (update.sh; plus any one-shot scripts you add)
+├── scripts/                  # helper scripts you add
 ├── shared/                   # synced to every machine
 │   ├── CLAUDE.md
 │   ├── settings.base.json    # baseline settings
@@ -209,25 +212,36 @@ Read these before adopting so you opt in with eyes open.
 
 **Why not just fork?** GitHub doesn't let you flip a public fork to private, and your config (especially session transcripts) must stay private. So the bootstrap is a one-time mirror-push into a fresh private repo, not a fork.
 
+### Privacy by default
+
+Your private mirror has two layers of defense against leaking transcripts via CI, both applied automatically:
+
+1. Every workflow under `.github/workflows/` is gated on `${{ !github.event.repository.private }}`, so they skip on private repos and only run on public ones.
+2. `nomad init` calls `gh api -X PUT repos/<owner>/<repo>/actions/permissions -F enabled=false` on first run, turning Actions off at the repo level. Requires `gh` CLI authed; if missing or unauthed, init logs a manual fallback tip and continues.
+
+Pass `--keep-actions` to either form of init to skip step 2 (for example, when your org already enforces an Actions policy upstream).
+
 > [!WARNING]
-> Keep the mirror private. CI workflows under `.github/workflows/` are gated on `${{ !github.event.repository.private }}`, so they skip on any private repo and run only on public ones. Flipping your mirror to public will start firing CI on every `nomad push` against `main`, and your session transcripts (which include conversation content) become world-readable.
+> If you ever flip the mirror to public, both protections evaporate: CI starts firing on every `nomad push` against `main`, and your session transcripts (which include conversation content) become world-readable. Keep it private.
 
-Bootstrap (steps 1-2 are once-ever across all hosts; step 3 repeats per host):
+### Bootstrap
+
+Steps 1-2 are once-ever across all hosts; step 3 repeats per host:
 
 ```bash
 # 1. Create the private repo (or use the GitHub UI). Once, ever.
-gh repo create you/claude-nomad --private
+gh repo create <your-username>/claude-nomad --private
 
 # 2. Mirror the public tool into it. This severs the fork relationship,
 #    so your repo is independent of upstream. Once, ever.
 git clone --bare git@github.com:funkadelic/claude-nomad.git /tmp/cn.git
 cd /tmp/cn.git
-git push --mirror git@github.com:you/claude-nomad.git
+git push --mirror git@github.com:<your-username>/claude-nomad.git
 cd .. && rm -rf /tmp/cn.git
 
 # 3. Install the CLI globally and clone your private copy. Repeat on every host.
 npm i -g claude-nomad
-git clone git@github.com:you/claude-nomad.git ~/claude-nomad
+git clone git@github.com:<your-username>/claude-nomad.git ~/claude-nomad
 ```
 
 `npm i -g claude-nomad` puts a `nomad` binary on your PATH. The bin shim is the existing `src/nomad.ts` entrypoint resolved through tsx (a runtime dependency); no compile step. The npm `engines` field declares the 22.22.1 floor and surfaces a warning on older runtimes; npm only blocks the install when `engine-strict=true` is configured.
@@ -242,7 +256,9 @@ export NOMAD_HOST=<your-host-label>      # any short, stable label; nomad reads
 
 `NOMAD_HOST` overrides `os.hostname()`, which returns noisy values like `WINDOWS-I5NT6OH` on WSL or `<name>.local` on macOS. Pick a clean label per machine (e.g., `wsl-laptop`, `macbook`, `homelab-nuc`). `nomad doctor` reports the resolved host so you can confirm.
 
-Initialize the repo layout (first host only; subsequent hosts just clone and `nomad pull`). Pick one:
+### Initialize the repo layout
+
+First host only; subsequent hosts just clone and `nomad pull`. Both forms below auto-disable Actions on a detected private GitHub mirror as described in [Privacy by default](#privacy-by-default). Pick one:
 
 ```bash
 # Fresh start: scaffold an empty shared/, hosts/, path-map.json skeleton.
@@ -252,6 +268,9 @@ nomad init
 # starting point. Stages shared/ and writes hosts/<NOMAD_HOST>.json from
 # your current ~/.claude/settings.json. Does NOT touch the originals.
 nomad init --snapshot
+
+# Either form accepts --keep-actions to skip the auto-disable.
+nomad init --keep-actions
 ```
 
 `nomad init` refuses to clobber existing scaffold artifacts, so re-running on a populated repo is a safe no-op (it errors out naming the offender). `nomad pull` against an unscaffolded repo fails fast with `FATAL: repo not initialized; run 'nomad init' to scaffold` instead of silently leaving a half-state.
@@ -324,8 +343,6 @@ One-time setup if you're running a fork layout and don't have the `upstream` rem
 git remote add upstream git@github.com:funkadelic/claude-nomad.git
 ```
 
-`npm run update` still exists as a legacy shim that shells out to `scripts/update.sh`; prefer `nomad update` for new invocations.
-
 To pin to a specific release (`vX.Y.Z`, tagged by release-please) instead of tracking `main`, fetch tags from the public repo and check out the tag (detached HEAD). On vanilla topology that's `origin`; on fork topology that's `upstream` (the private mirror at `origin` does not accumulate upstream release tags). Example: `git fetch upstream --tags && git switch --detach vX.Y.Z` (substitute `origin` for vanilla; use `git checkout vX.Y.Z` on older Git).
 
 If you installed an earlier version via `./install.sh` and a shell alias (the pre-npm path), your existing alias keeps working unchanged. Run `npm i -g claude-nomad` whenever you're ready to switch to the global binary, confirm `nomad --version` resolves to the npm install (`which nomad` should point under your npm prefix's `bin/`), then delete the alias line from your shell rc.
@@ -334,8 +351,9 @@ If you installed an earlier version via `./install.sh` and a shell alias (the pr
 
 | Command                          | Description                                                                                                                                                                                                             |
 | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `nomad init`                     | Scaffold empty `shared/`, `hosts/`, `path-map.json` on a fresh clone. Refuses to clobber existing scaffold.                                                                                                             |
-| `nomad init --snapshot`          | Overlay current host's `~/.claude/` into `shared/` and write `~/.claude/settings.json` verbatim into `hosts/<NOMAD_HOST>.json`. Originals not modified.                                                                 |
+| `nomad init`                     | Scaffold empty `shared/`, `hosts/`, `path-map.json` on a fresh clone. Refuses to clobber existing scaffold. Auto-disables Actions on a detected private GitHub mirror (see [Privacy by default](#privacy-by-default)).  |
+| `nomad init --snapshot`          | Overlay current host's `~/.claude/` into `shared/` and write `~/.claude/settings.json` verbatim into `hosts/<NOMAD_HOST>.json`. Originals not modified. Same auto-disable behavior as `nomad init`.                     |
+| `nomad init --keep-actions`      | Skip the auto-disable. Combinable with `--snapshot`. Use when an upstream org policy already governs Actions, or you intentionally want CI on the private mirror.                                                       |
 | `nomad pull`                     | `git pull --rebase --autostash`, apply symlinks, regenerate `settings.json`, remap session paths. FATAL if scaffold missing.                                                                                            |
 | `nomad pull --dry-run`           | Network-aware preview: acquire lock + `git pull --rebase`, print planned changes (symlink moves, `settings.json` diff, transcript overwrites), exit without writing.                                                    |
 | `nomad diff`                     | Offline, lockless twin of `pull --dry-run`. No network, no lock. Works against the current local repo state.                                                                                                            |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-nomad",
-  "version": "0.17.1",
+  "version": "0.18.0",
   "type": "module",
   "description": "Sync Claude Code config (~/.claude/) across machines via a private Git repo, with path remapping and per-host settings overrides.",
   "keywords": [

package/src/commands.doctor.checks.ts

@@ -17,7 +17,7 @@ import {
 // prettier-ignore
 import { CLAUDE_HOME, HOST, KNOWN_SETTINGS_KEYS, NEVER_SYNC, REPO_HOME, SHARED_LINKS, type PathMap } from './config.ts';
 import { addItem, type DoctorSection } from './commands.doctor.format.ts';
-import { classifyRepoState, reasonForPartial } from './init.ts';
+import { classifyRepoState, reasonForPartial } from './init.classify.ts';
 import { findGitlinks } from './push-checks.ts';
 import { encodePath, gitStatusPorcelainZ, readJson } from './utils.ts';
 

package/src/gh-actions.ts

@@ -0,0 +1,125 @@
+import { execFileSync, type ExecFileSyncOptions } from 'node:child_process';
+
+/**
+ * GitHub repo owner/name pair parsed from a remote URL. Used by
+ * `cmdInit`'s auto-disable hook and `nomad doctor`'s mirror-Actions check.
+ */
+export type GhRepoRef = { owner: string; repo: string };
+
+/**
+ * Reason `ghAuthStatus` returned without success. Distinguishes the two
+ * actionable failure modes so callers can print useful tips.
+ */
+export type GhUnavailableReason = 'gh-not-installed' | 'gh-not-authed';
+
+/**
+ * Injectable subprocess runner so tests can mock without `vi.doMock` and
+ * without touching `execFileSync` on the real shell. Default binds to
+ * `child_process.execFileSync` with the same signature.
+ */
+export type SpawnSyncFn = (
+  bin: string,
+  args: readonly string[],
+  opts?: ExecFileSyncOptions,
+) => Buffer | string;
+
+/**
+ * Maximum time in milliseconds to wait for a `gh` CLI subprocess. Prevents
+ * `nomad init` from hanging indefinitely on a slow or captive-portal network;
+ * `execFileSync` throws `ETIMEDOUT` on expiry, which the callers' try/catch
+ * blocks already handle as a silent-skip.
+ */
+const GH_TIMEOUT_MS = 5_000;
+
+/**
+ * Parse a git remote URL into `{ owner, repo }` when it points at GitHub.
+ * Returns `null` for any non-GitHub URL (other forge, local path, malformed)
+ * so the caller silently skips rather than failing init. Strips a trailing
+ * `.git` if present.
+ */
+export function parseGitHubRemote(remoteUrl: string): GhRepoRef | null {
+  const normalized = remoteUrl.trim().replace(/\/$/, '');
+  const m = /github\.com[:/]([^/]+)\/([^/]+?)(?:\.git)?$/.exec(normalized);
+  if (m === null) return null;
+  return { owner: m[1], repo: m[2] };
+}
+
+/**
+ * Check `gh` CLI availability and auth status in one call. Returns null on
+ * success or a structured reason string. `gh auth status` exits 0 when the
+ * user is authed against github.com and non-zero otherwise; ENOENT signals
+ * the binary itself is missing.
+ */
+export function ghAuthStatus(run: SpawnSyncFn = execFileSync): GhUnavailableReason | null {
+  try {
+    run('gh', ['auth', 'status'], {
+      stdio: ['ignore', 'ignore', 'ignore'],
+      timeout: GH_TIMEOUT_MS,
+    });
+    return null;
+  } catch (err) {
+    const e = err as { code?: string };
+    if (e.code === 'ENOENT') return 'gh-not-installed';
+    return 'gh-not-authed';
+  }
+}
+
+/**
+ * Fetch the `isPrivate` flag for a repo. Throws on subprocess or JSON
+ * failure; callers wrap with try/catch and treat as silent-skip.
+ */
+export function isRepoPrivate(ref: GhRepoRef, run: SpawnSyncFn = execFileSync): boolean {
+  const out = run('gh', ['repo', 'view', `${ref.owner}/${ref.repo}`, '--json', 'isPrivate'], {
+    stdio: ['ignore', 'pipe', 'ignore'],
+    timeout: GH_TIMEOUT_MS,
+  }).toString();
+  const parsed = JSON.parse(out) as { isPrivate?: unknown };
+  return parsed.isPrivate === true;
+}
+
+/**
+ * Fetch the `enabled` field of the repo's Actions permissions. Throws on
+ * subprocess failure; callers wrap with try/catch.
+ */
+export function isActionsEnabled(ref: GhRepoRef, run: SpawnSyncFn = execFileSync): boolean {
+  const out = run(
+    'gh',
+    ['api', `repos/${ref.owner}/${ref.repo}/actions/permissions`, '--jq', '.enabled'],
+    { stdio: ['ignore', 'pipe', 'ignore'], timeout: GH_TIMEOUT_MS },
+  )
+    .toString()
+    .trim();
+  return out === 'true';
+}
+
+/**
+ * Disable GitHub Actions on a repo. Idempotent on GitHub's side: re-disabling
+ * an already-disabled repo returns success. Throws on subprocess failure.
+ */
+export function disableActions(ref: GhRepoRef, run: SpawnSyncFn = execFileSync): void {
+  run(
+    'gh',
+    [
+      'api',
+      '-X',
+      'PUT',
+      `repos/${ref.owner}/${ref.repo}/actions/permissions`,
+      '-F',
+      'enabled=false',
+    ],
+    { stdio: ['ignore', 'ignore', 'pipe'], timeout: GH_TIMEOUT_MS },
+  );
+}
+
+/**
+ * Read the `origin` remote URL for a git working tree at `cwd`. Throws on
+ * any failure (no remote, not a git repo); callers treat as silent-skip.
+ */
+export function readOriginRemote(cwd: string, run: SpawnSyncFn = execFileSync): string {
+  return run('git', ['remote', 'get-url', 'origin'], {
+    cwd,
+    stdio: ['ignore', 'pipe', 'ignore'],
+  })
+    .toString()
+    .trim();
+}

package/src/init.classify.ts

@@ -0,0 +1,87 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { type PathMap } from './config.ts';
+import { readJson } from './utils.ts';
+
+/**
+ * Read-only health classifier for `cmdDoctor`'s `repo state:` header.
+ * Inspects three signals at the given `repoHome`: `shared/settings.base.json`
+ * presence, `path-map.json.projects` having at least one entry, and
+ * `hosts/<host>.json` presence.
+ *
+ * Returns `'empty'` when the base is missing AND the path-map has no entries
+ * (either missing or `projects` is empty); `'populated'` when all three
+ * signals are positive; `'partial'` for anything in between. Malformed
+ * `path-map.json` is treated as zero entries rather than thrown, so a doctor
+ * run against a corrupted scaffold still produces a classification line.
+ *
+ * The `host` parameter is passed explicitly (rather than read from the
+ * imported `HOST` constant) so the test fixture can drive multiple host
+ * scenarios without mutating module-level state via `vi.resetModules()`.
+ */
+export function classifyRepoState(
+  repoHome: string,
+  host: string,
+): 'empty' | 'partial' | 'populated' {
+  const basePath = join(repoHome, 'shared', 'settings.base.json');
+  const mapPath = join(repoHome, 'path-map.json');
+  const hostPath = join(repoHome, 'hosts', `${host}.json`);
+
+  const hasBase = existsSync(basePath);
+  const hasMap = existsSync(mapPath);
+  const hasHost = existsSync(hostPath);
+
+  let mapEntryCount = 0;
+  if (hasMap) {
+    try {
+      const map = readJson<PathMap>(mapPath);
+      mapEntryCount = Object.keys(map.projects).length;
+    } catch {
+      // Malformed JSON: treat as zero entries, do NOT throw. The doctor's
+      // own JSON-parse FAIL line will surface the malformed file separately.
+      mapEntryCount = 0;
+    }
+  }
+
+  if (!hasBase && mapEntryCount === 0) return 'empty';
+  if (hasBase && mapEntryCount > 0 && hasHost) return 'populated';
+  return 'partial';
+}
+
+/**
+ * Suffix that follows `repo state: WARN partial` per the fixed priority
+ * order. First matching condition wins, exactly one suffix per line.
+ * Inspects the same on-disk signals `classifyRepoState` reads (base file,
+ * `path-map.json` + its `.projects` entry count, `hosts/<host>.json`), but
+ * explicitly distinguishes "path-map missing" from "path-map present but
+ * empty" because users debug differently for each.
+ *
+ * Lives alongside `classifyRepoState` so the suffix rules and the classifier
+ * stay co-located: changes to one almost always require updating the other.
+ * Returns the string with a leading `- ` separator so the caller can
+ * concatenate directly without re-deciding the separator.
+ */
+export function reasonForPartial(repoHome: string, host: string): string {
+  const basePath = join(repoHome, 'shared', 'settings.base.json');
+  const mapPath = join(repoHome, 'path-map.json');
+  const hostPath = join(repoHome, 'hosts', `${host}.json`);
+  if (!existsSync(basePath)) return '- shared/settings.base.json missing';
+  if (!existsSync(mapPath)) return '- path-map.json missing';
+  let mapEntryCount: number;
+  try {
+    const map = readJson<PathMap>(mapPath);
+    mapEntryCount = Object.keys(map.projects).length;
+  } catch {
+    // Malformed JSON: treat as zero entries. Doctor's own JSON-parse FAIL
+    // line surfaces the malformed file separately.
+    mapEntryCount = 0;
+  }
+  if (mapEntryCount === 0) return '- path-map.json.projects has no entries';
+  if (!existsSync(hostPath)) return `- hosts/${host}.json missing`;
+  // Defensive fallback: classifyRepoState returned 'partial' for a reason
+  // not captured by the four signals above. Should be unreachable in
+  // practice because the priority order is exhaustive against the
+  // classifier's definition of populated.
+  return '- partial state (unknown gap)';
+}

package/src/init.ts

@@ -2,8 +2,17 @@ import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 
 import { CLAUDE_HOME, type PathMap, REPO_HOME } from './config.ts';
+import {
+  disableActions,
+  ghAuthStatus,
+  isActionsEnabled,
+  isRepoPrivate,
+  parseGitHubRemote,
+  readOriginRemote,
+  type SpawnSyncFn,
+} from './gh-actions.ts';
 import { snapshotIntoShared } from './init.snapshot.ts';
-import { die, log, readJson, writeJsonAtomic } from './utils.ts';
+import { die, log, writeJsonAtomic } from './utils.ts';
 
 /**
  * The HTML comment line that anchors `shared/CLAUDE.md` on a fresh scaffold.
@@ -59,8 +68,11 @@ function preflightConflict(repoHome: string): string | null {
  * identical to plain init; a bare `shared/` dir is enough to refuse since
  * partial state is unsafe to merge with.
  */
-export function cmdInit(opts: { snapshot?: boolean } = {}): void {
+export function cmdInit(
+  opts: { snapshot?: boolean; keepActions?: boolean; run?: SpawnSyncFn } = {},
+): void {
   const snapshot = opts.snapshot === true;
+  const keepActions = opts.keepActions === true;
 
   const conflict = preflightConflict(REPO_HOME);
   if (conflict !== null) {
@@ -104,87 +116,78 @@ export function cmdInit(opts: { snapshot?: boolean } = {}): void {
     log('~/.claude/ originals were NOT removed.');
   }
 
+  if (!keepActions) {
+    maybeDisableMirrorActions(REPO_HOME, opts.run);
+  }
+
   log('init complete');
 }
 
 /**
- * Read-only health classifier for `cmdDoctor`'s `repo state:` header.
- * Inspects three signals at the given `repoHome`: `shared/settings.base.json`
- * presence, `path-map.json.projects` having at least one entry, and
- * `hosts/<host>.json` presence.
- *
- * Returns `'empty'` when the base is missing AND the path-map has no entries
- * (either missing or `projects` is empty); `'populated'` when all three
- * signals are positive; `'partial'` for anything in between. Malformed
- * `path-map.json` is treated as zero entries rather than thrown, so a doctor
- * run against a corrupted scaffold still produces a classification line.
+ * Best-effort hook that disables GitHub Actions on the user's private mirror
+ * after a fresh `nomad init`. The private mirror is a settings store, not a
+ * CI target; leaving Actions enabled there causes the mirror-pushed workflows
+ * (release-please, npm-publish, etc.) to fire on every `nomad push`, which is
+ * pure noise.
  *
- * The `host` parameter is passed explicitly (rather than read from the
- * imported `HOST` constant) so the test fixture can drive multiple host
- * scenarios without mutating module-level state via `vi.resetModules()`.
+ * Silently no-ops when: the repo is not a git repo, the origin remote is not
+ * GitHub, the origin is public (not a private mirror), `gh` CLI is missing,
+ * or `gh` is not authed. Prints a tip on the last two so the user can finish
+ * the step manually. Suppress entirely with `nomad init --keep-actions`.
  */
-export function classifyRepoState(
-  repoHome: string,
-  host: string,
-): 'empty' | 'partial' | 'populated' {
-  const basePath = join(repoHome, 'shared', 'settings.base.json');
-  const mapPath = join(repoHome, 'path-map.json');
-  const hostPath = join(repoHome, 'hosts', `${host}.json`);
-
-  const hasBase = existsSync(basePath);
-  const hasMap = existsSync(mapPath);
-  const hasHost = existsSync(hostPath);
-
-  let mapEntryCount = 0;
-  if (hasMap) {
-    try {
-      const map = readJson<PathMap>(mapPath);
-      mapEntryCount = Object.keys(map.projects).length;
-    } catch {
-      // Malformed JSON: treat as zero entries, do NOT throw. The doctor's
-      // own JSON-parse FAIL line will surface the malformed file separately.
-      mapEntryCount = 0;
-    }
+function maybeDisableMirrorActions(repoHome: string, run?: SpawnSyncFn): void {
+  let remote: string;
+  try {
+    remote = readOriginRemote(repoHome, run);
+  } catch {
+    return;
   }
+  const ref = parseGitHubRemote(remote);
+  if (ref === null) return;
 
-  if (!hasBase && mapEntryCount === 0) return 'empty';
-  if (hasBase && mapEntryCount > 0 && hasHost) return 'populated';
-  return 'partial';
-}
+  const ghStatus = ghAuthStatus(run);
+  if (ghStatus === 'gh-not-installed') {
+    log(
+      `tip: install gh CLI and run 'gh api -X PUT repos/${ref.owner}/${ref.repo}/actions/permissions -F enabled=false' to disable Actions on your private mirror.`,
+    );
+    return;
+  }
+  if (ghStatus === 'gh-not-authed') {
+    log(
+      `tip: run 'gh auth login' then 'gh api -X PUT repos/${ref.owner}/${ref.repo}/actions/permissions -F enabled=false' to disable Actions on your private mirror.`,
+    );
+    return;
+  }
+
+  let isPrivate: boolean;
+  try {
+    isPrivate = isRepoPrivate(ref, run);
+  } catch {
+    log(
+      `could not determine privacy for ${ref.owner}/${ref.repo}; run 'gh api -X PUT repos/${ref.owner}/${ref.repo}/actions/permissions -F enabled=false' manually if it is private.`,
+    );
+    return;
+  }
+  if (!isPrivate) return;
+
+  let alreadyDisabled = false;
+  try {
+    alreadyDisabled = !isActionsEnabled(ref, run);
+  } catch {
+    // Treat as enabled and attempt the disable; the API call itself is
+    // idempotent so this is safe.
+  }
+  if (alreadyDisabled) {
+    log(`actions already disabled on ${ref.owner}/${ref.repo}`);
+    return;
+  }
 
-/**
- * Suffix that follows `repo state: WARN partial` per the fixed priority
- * order. First matching condition wins, exactly one suffix per line.
- * Inspects the same on-disk signals `classifyRepoState` reads (base file,
- * `path-map.json` + its `.projects` entry count, `hosts/<host>.json`), but
- * explicitly distinguishes "path-map missing" from "path-map present but
- * empty" because users debug differently for each.
- *
- * Lives alongside `classifyRepoState` so the suffix rules and the classifier
- * stay co-located: changes to one almost always require updating the other.
- * Returns the string with a leading `- ` separator so the caller can
- * concatenate directly without re-deciding the separator.
- */
-export function reasonForPartial(repoHome: string, host: string): string {
-  const basePath = join(repoHome, 'shared', 'settings.base.json');
-  const mapPath = join(repoHome, 'path-map.json');
-  const hostPath = join(repoHome, 'hosts', `${host}.json`);
-  if (!existsSync(basePath)) return '- shared/settings.base.json missing';
-  if (!existsSync(mapPath)) return '- path-map.json missing';
-  let mapEntryCount: number;
   try {
-    const map = readJson<PathMap>(mapPath);
-    mapEntryCount = Object.keys(map.projects).length;
+    disableActions(ref, run);
+    log(`disabled GitHub Actions on private mirror ${ref.owner}/${ref.repo}`);
   } catch {
-    // Malformed JSON: treat as zero entries. Doctor's own JSON-parse FAIL
-    // line surfaces the malformed file separately.
-    mapEntryCount = 0;
+    log(
+      `could not auto-disable Actions on ${ref.owner}/${ref.repo}; run 'gh api -X PUT repos/${ref.owner}/${ref.repo}/actions/permissions -F enabled=false' manually.`,
+    );
   }
-  if (mapEntryCount === 0) return '- path-map.json.projects has no entries';
-  if (!existsSync(hostPath)) return `- hosts/${host}.json missing`;
-  // Defensive fallback: classifyRepoState returned 'partial' for a reason
-  // not captured by the four signals above. Should be unreachable in
-  // practice because the priority order is exhaustive against the
-  // classifier's definition of populated.
-  return '- partial state (unknown gap)';
 }

package/src/nomad.ts

@@ -57,7 +57,8 @@ const DEFAULT_HELP = [
   '                   No git pull, no lock acquired.',
   '',
   '  init             Scaffold an empty ~/claude-nomad/ repo (shared/, hosts/, path-map).',
-  '       --snapshot  Overlay the current ~/.claude/ into shared/ as the initial seed.',
+  '       --snapshot      Overlay the current ~/.claude/ into shared/ as the initial seed.',
+  '       --keep-actions  Skip auto-disabling GitHub Actions on the private mirror.',
   '',
   '  doctor                  Read-only health check (symlinks, host file, path-map,',
   '                          gitleaks, gitlinks).',
@@ -128,20 +129,28 @@ try {
       }
       break;
     }
-    case 'init':
-      // Two valid forms: `nomad init` (empty scaffold) and
-      // `nomad init --snapshot` (overlay user's current ~/.claude/ into
-      // shared/). Anything else (unknown flag, extra positional arg, two
-      // flags) hits the same usage-error pattern as `doctor --resume-cmd`.
-      if (process.argv[3] === undefined) {
-        cmdInit();
-      } else if (process.argv[3] === '--snapshot' && process.argv[4] === undefined) {
-        cmdInit({ snapshot: true });
-      } else {
-        console.error('usage: nomad init [--snapshot]');
+    case 'init': {
+      // Set-based parse so flag order does not matter and duplicates are
+      // rejected. Unknown flags hit the same usage-error pattern as other
+      // subcommands.
+      const known = new Set(['--snapshot', '--keep-actions']);
+      const seen = new Set<string>();
+      let argvOk = true;
+      for (let i = 3; i < process.argv.length; i++) {
+        const flag = process.argv[i];
+        if (!known.has(flag) || seen.has(flag)) {
+          argvOk = false;
+          break;
+        }
+        seen.add(flag);
+      }
+      if (!argvOk) {
+        console.error('usage: nomad init [--snapshot] [--keep-actions]');
         process.exit(1);
       }
+      cmdInit({ snapshot: seen.has('--snapshot'), keepActions: seen.has('--keep-actions') });
       break;
+    }
     case 'diff':
       // Offline, lockless preview against local repo state. No git pull, no
       // lock acquisition. Reject any argv after `diff` since this slice