claude-nomad 0.28.0 → 0.30.0

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## [0.30.0](https://github.com/funkadelic/claude-nomad/compare/v0.29.1...v0.30.0) (2026-05-29)
+
+
+### Added
+
+* **doctor:** report gh and curl presence in Version Checks ([#175](https://github.com/funkadelic/claude-nomad/issues/175)) ([5163833](https://github.com/funkadelic/claude-nomad/commit/516383301dbd9c64cfc8f1c7a654655b61c29280))
+
+
+### Changed
+
+* widen npm-publish smoke-test propagation window ([#176](https://github.com/funkadelic/claude-nomad/issues/176)) ([f8b1eef](https://github.com/funkadelic/claude-nomad/commit/f8b1eef18dcee91fb894d2036c42356f82c76f79))
+
+## [0.29.1](https://github.com/funkadelic/claude-nomad/compare/v0.29.0...v0.29.1) (2026-05-29)
+
+
+### Fixed
+
+* **doctor:** degrade gitleaks-absent probe to WARN, not FAIL ([#173](https://github.com/funkadelic/claude-nomad/issues/173)) ([320bb8a](https://github.com/funkadelic/claude-nomad/commit/320bb8a5d6f6c1f02207be8e186fe678f8e6f8bd))
+
+## [0.29.0](https://github.com/funkadelic/claude-nomad/compare/v0.28.0...v0.29.0) (2026-05-29)
+
+
+### Added
+
+* sync hook scripts and tool support dirs across hosts ([#171](https://github.com/funkadelic/claude-nomad/issues/171)) ([e340fd2](https://github.com/funkadelic/claude-nomad/commit/e340fd221882f9107f4e10c3a64ccd7be4061a14))
+
 ## [0.28.0](https://github.com/funkadelic/claude-nomad/compare/v0.27.0...v0.28.0) (2026-05-28)
 
 

package/README.md

@@ -45,6 +45,7 @@ box, a personal rig and a work machine. [Get started in three steps.](#quickstar
   - [Repo layout](#repo-layout-what-claude-nomad-looks-like-on-a-configured-host)
   - [What gets synced vs. not](#what-gets-synced-vs-not)
   - [Path remapping](#path-remapping)
+  - [Shared support dirs (sharedDirs)](#shared-support-dirs-shareddirs)
   - [Per-host overrides](#per-host-overrides)
   - [What does NOT sync (deliberate trade-offs)](#what-does-not-sync-deliberate-trade-offs)
 - **Getting started**
@@ -113,6 +114,7 @@ public funkadelic/claude-nomad          your private <your-username>/claude-noma
                                           │   ├── skills/
                                           │   ├── commands/
                                           │   ├── rules/
+                                          │   ├── hooks/
                                           │   ├── settings.base.json
                                           │   └── projects/
                                           ├── hosts/<hostname>.json
@@ -143,6 +145,7 @@ so a clobbered dotfile variable does not break the CLI.
 │   ├── skills/
 │   ├── commands/
 │   ├── rules/
+│   ├── hooks/                # hook scripts, symlinked into ~/.claude/hooks/
 │   ├── my-statusline.cjs     # any script you want symlinked into ~/.claude/
 │   ├── .gitignore            # defense-in-depth: blocks .claude.json, settings.local.json, *.token, *.key, *.pem, id_rsa, id_ed25519, .env, .env.*
 │   ├── projects/             # session transcripts under logical names
@@ -157,22 +160,29 @@ so a clobbered dotfile variable does not break the CLI.
 
 ## What gets synced vs. not
 
-| Category               | Items                                                                         | Behavior                                                                                       |
-| ---------------------- | ----------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
-| **Synced**             | `CLAUDE.md`, `agents/`, `skills/`, `commands/`, `rules/`, `my-statusline.cjs` | Symlinked into `~/.claude/` from `shared/`.                                                    |
-| **Generated**          | `settings.json`                                                               | Deep-merge of `settings.base.json` with `hosts/<hostname>.json`; rewritten every pull.         |
-| **Remapped**           | `projects/` session transcripts                                               | Copied with path translation per `path-map.json`.                                              |
-| **Per-project extras** | Whitelisted dirs like `.planning/`, or a root file like `CLAUDE.md`           | Opt-in via the `extras` field in `path-map.json`; mirrored to/from `shared/extras/<logical>/`. |
-| **Never synced**       | OAuth and MCP state, shell history, per-host overrides, caches, scratch dirs  | Per-host ephemeral state; left untouched in both directions.                                   |
-| **Auto-rehydrated**    | `~/.claude/plugins/cache/<plugin>/...`                                        | Re-downloaded by Claude Code from the `enabledPlugins` list; no per-host install.              |
+| Category                | Items                                                                                   | Behavior                                                                                                                                                      |
+| ----------------------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Synced**              | `CLAUDE.md`, `agents/`, `skills/`, `commands/`, `rules/`, `hooks/`, `my-statusline.cjs` | Symlinked into `~/.claude/` from `shared/`.                                                                                                                   |
+| **Generated**           | `settings.json`                                                                         | Deep-merge of `settings.base.json` with `hosts/<hostname>.json`; rewritten every pull.                                                                        |
+| **Remapped**            | `projects/` session transcripts                                                         | Copied with path translation per `path-map.json`.                                                                                                             |
+| **Per-project extras**  | Whitelisted dirs like `.planning/`, or a root file like `CLAUDE.md`                     | Opt-in via the `extras` field in `path-map.json`; mirrored to/from `shared/extras/<logical>/`.                                                                |
+| **Shared support dirs** | Opt-in global `~/.claude/` dirs like a tool's `get-shit-done/`                          | Opt-in via the `sharedDirs` field in `path-map.json`; symlinked into `~/.claude/` from `shared/`. See [Shared support dirs](#shared-support-dirs-shareddirs). |
+| **Never synced**        | OAuth and MCP state, shell history, per-host overrides, caches, scratch dirs            | Per-host ephemeral state; left untouched in both directions.                                                                                                  |
+| **Auto-rehydrated**     | `~/.claude/plugins/cache/<plugin>/...`                                                  | Re-downloaded by Claude Code from the `enabledPlugins` list; no per-host install.                                                                             |
 
 Pointers and specifics:
 
-- **Synced** link names live in `SHARED_LINKS`, **whitelisted extras** names in `SUPPORTED_EXTRAS`,
-  and the full **never-synced** set in `NEVER_SYNC` (all in `src/config.ts`).
-- **Never synced**, in full: `~/.claude.json` (OAuth, MCP state), `history.jsonl`,
-  `settings.local.json` (per-host overrides), `stats-cache.json`, `todos/`, `shell-snapshots/`,
-  `debug/`, `file-history/`, `plans/`, `session-env/`, `statsig/`, `telemetry/`, `ide/`.
+- **Synced** link names live in `SHARED_LINKS` (and the optional `sharedDirs` field in
+  `path-map.json` -- see [Shared support dirs](#shared-support-dirs-shareddirs)), **whitelisted
+  extras** names in `SUPPORTED_EXTRAS`, and the full **never-synced** set in `NEVER_SYNC` (all in
+  `src/config.ts`).
+- **Never synced**, in full: `~/.claude.json` (OAuth, MCP state), `.credentials.json` (OAuth
+  credential store), `history.jsonl`, `settings.local.json` (per-host overrides),
+  `stats-cache.json`, `todos/`, `shell-snapshots/`, `debug/`, `file-history/`, `plans/`,
+  `session-env/`, `statsig/`, `telemetry/`, `ide/`, plus host-local caches and runtime state
+  (`cache/`, `backups/`, `paste-cache/`, `daemon/`, `jobs/`, `tasks/`, `security/`, `sessions/`).
+  This set is also the deny-list the `sharedDirs` opt-in is checked against, so one of these names
+  cannot be symlinked into the shared repo by mistake.
 - **Per-project extras** run a pre-pull divergence WARN that flags local edits before they get
   overwritten.
 
@@ -239,6 +249,55 @@ copy and prints a per-file WARN naming anything that differs.
 Your existing local content is backed up under `~/.cache/claude-nomad/backup/<ts>/extras/` before
 the pull copy lands, so an unexpected overwrite is always recoverable.
 
+## Shared support dirs (sharedDirs)
+
+Some tools install a `hooks` block into `settings.json` whose commands point at scripts under
+`~/.claude/hooks/` (and sometimes a support directory such as `~/.claude/get-shit-done/`). Because
+`settings.json` is regenerated on every pull, that hook configuration travels to every host, but the
+scripts it points at did not, so hooks broke on a freshly configured host. `~/.claude/hooks/` is now
+a built-in synced link (it rides the same symlink model as `skills/` and `agents/`), so hook scripts
+travel automatically.
+
+For any other global `~/.claude/` support directory a tool needs, the optional top-level
+`sharedDirs` field in `path-map.json` opts it into the same symlink sync:
+
+```json
+{
+  "projects": {
+    "my-example-repo": {
+      "<your-mac>": "/Users/you/code/my-example-repo"
+    }
+  },
+  "sharedDirs": ["get-shit-done"]
+}
+```
+
+What this means for you: each listed name is symlinked from `shared/<name>` into `~/.claude/<name>`
+(the same model as the built-in synced links, not a copy), so editing it on any host updates the one
+shared copy. The field is additive and back-compatible: a `path-map.json` without it behaves exactly
+as before.
+
+Entries are validated before anything is linked. A name is accepted only if it is a single path
+segment (no `/`, no `..`), is not one of the never-synced names, and does not collide with a
+reserved `shared/` name (`settings.base.json`, the built-in synced links, `hooks`, `hosts`,
+`path-map.json`). An invalid entry is dropped with a warning rather than aborting the run. The
+contents still go through the same gitleaks scan as everything else on push, so do not point
+`sharedDirs` at a directory that holds credentials.
+
+First-time setup on an already-configured repo: a symlink can only form once the directory exists
+under `shared/`. On a fresh repo `nomad init --snapshot` handles this for you. To add `hooks/` (or a
+new `sharedDirs` entry) to a repo that is already set up, move it into `shared/` once on the host
+that has it, then let the normal flow take over:
+
+```bash
+$ mv ~/.claude/hooks ~/claude-nomad/shared/hooks   # one-time, on the source host
+$ nomad pull                                        # re-creates ~/.claude/hooks as a symlink
+$ nomad push                                        # shares it with your other hosts
+```
+
+`nomad pull` never writes back to the remote, so it will not seed `shared/` for you; the one-time
+move is deliberate.
+
 ## Per-host overrides
 
 `settings.base.json` holds portable defaults (model, permissions, plugins).
@@ -321,10 +380,11 @@ Read these before adopting so you opt in with eyes open.
 
 - `gh` ([GitHub CLI](https://cli.github.com/)), used only by `nomad init` to auto-disable Actions on
   the private repo; if it is missing or unauthenticated, init prints a manual fallback tip and
-  continues
+  continues. `nomad doctor` reports its presence in the Version Checks section.
 - [curl](https://curl.se/), used by the version/update check (the `nomad doctor` latest-release line
   and the post-`nomad update` check) and by `nomad doctor --check-schema`; it degrades silently when
-  curl is absent or offline, so the rest of the CLI works without it
+  curl is absent or offline, so the rest of the CLI works without it. `nomad doctor` reports its
+  presence in the Version Checks section.
 
 ## Setup
 
@@ -540,28 +600,35 @@ point under your npm prefix's `bin/`), then delete the alias line from your shel
 
 ## Commands
 
-| Command                          | Description                                                                                                                                                                                                                                                                                                                                              |
-| -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `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, and pull opted-in per-project extras. Errors out 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.                                                                                                                                                                                                                                             |
-| `nomad push`                     | Export local sessions and opted-in per-project extras to logical names, commit (`chore: sync from <NOMAD_HOST>`), push.                                                                                                                                                                                                                                  |
-| `nomad push --dry-run`           | Run pre-push safety checks (gitleaks probe, rebase, remap preview, gitlink scan, allow-list) and a read-only gitleaks leak preview over a throwaway temp copy of the sessions and extras this host would stage; skip stage, commit, and push. Exits 1 if a leak is found in the preview. Nothing is written to the sync repo.                            |
-| `nomad drop-session <id>`        | Surgically unstage every `shared/projects/*/<id>.jsonl` and the sibling `shared/projects/*/<id>/` subagent directory from the staged tree of `~/claude-nomad/`. Idempotent; the local `~/.claude/projects/<encoded>/<id>.jsonl` and `<id>/` tree are preserved. See [Recovery flows](#recovery-flows).                                                   |
-| `nomad update`                   | Topology-aware upgrade to the latest upstream. Flags: `--dry-run`, `--force`, `--push-origin`. See [Upgrading the tool](#upgrading-the-tool).                                                                                                                                                                                                            |
-| `nomad doctor`                   | Read-only health check. Each line carries a status glyph (`✓` pass, `✗` fail, `⚠︎` warn); any `✗` sets `process.exitCode = 1` (`⚠︎` does not). Includes an offline-tolerant release-version staleness check plus two `⚠︎`-only drift checks: gitleaks version drift and, on a private GitHub mirror, re-enabled Actions.                                    |
-| `nomad doctor --resume-cmd <id>` | Print a host-local `cd ... && claude --resume <id>` line for a session (see [Cross-OS resume](#cross-os-resume)).                                                                                                                                                                                                                                        |
-| `nomad doctor --check-shared`    | Read-only gitleaks preflight: stages the session transcripts a `push` would publish into a temp tree and scans them, failing (`✗`, exit 1) per affected session with rotate-and-scrub guidance. Skips with a `⚠︎` when gitleaks is not on PATH. See [Recovery flow: gitleaks FATAL on a session JSONL](#recovery-flow-gitleaks-fatal-on-a-session-jsonl). |
-| `nomad doctor --check-schema`    | Read-only: fetches the live Claude Code settings schema and lists any `~/.claude/settings.json` key absent from it (candidates for the hand-maintained `APP_ONLY_KEYS` list). Non-fatal and offline-tolerant: skips with a `⚠︎` when curl is missing or the schema is unreachable.                                                                        |
-| `nomad --version`                | Print the installed CLI version as bare semver to stdout; exits 0. Used by the npm-publish smoke test and useful for ad-hoc upgrade checks.                                                                                                                                                                                                              |
+| Command                          | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `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, and pull opted-in per-project extras. Errors out 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.                                                                                                                                                                                                                                                                                                                                                                 |
+| `nomad push`                     | Export local sessions and opted-in per-project extras to logical names, commit (`chore: sync from <NOMAD_HOST>`), push.                                                                                                                                                                                                                                                                                                                                                      |
+| `nomad push --dry-run`           | Run pre-push safety checks (gitleaks probe, rebase, remap preview, gitlink scan, allow-list) and a read-only gitleaks leak preview over a throwaway temp copy of the sessions and extras this host would stage; skip stage, commit, and push. Exits 1 if a leak is found in the preview. Nothing is written to the sync repo.                                                                                                                                                |
+| `nomad drop-session <id>`        | Surgically unstage every `shared/projects/*/<id>.jsonl` and the sibling `shared/projects/*/<id>/` subagent directory from the staged tree of `~/claude-nomad/`. Idempotent; the local `~/.claude/projects/<encoded>/<id>.jsonl` and `<id>/` tree are preserved. See [Recovery flows](#recovery-flows).                                                                                                                                                                       |
+| `nomad update`                   | Topology-aware upgrade to the latest upstream. Flags: `--dry-run`, `--force`, `--push-origin`. See [Upgrading the tool](#upgrading-the-tool).                                                                                                                                                                                                                                                                                                                                |
+| `nomad doctor`                   | Read-only health check. Each line carries a status glyph (`✓` pass, `✗` fail, `⚠︎` warn); any `✗` sets `process.exitCode = 1` (`⚠︎` does not). Includes an offline-tolerant release-version staleness check, a Hook targets check that fails (`✗`, exit 1) when `settings.json` references a hook command whose script under `~/.claude/` is missing on this host, plus two `⚠︎`-only drift checks: gitleaks version drift and, on a private GitHub mirror, re-enabled Actions. |
+| `nomad doctor --resume-cmd <id>` | Print a host-local `cd ... && claude --resume <id>` line for a session (see [Cross-OS resume](#cross-os-resume)).                                                                                                                                                                                                                                                                                                                                                            |
+| `nomad doctor --check-shared`    | Read-only gitleaks preflight: stages the session transcripts a `push` would publish into a temp tree and scans them, failing (`✗`, exit 1) per affected session with rotate-and-scrub guidance. Skips with a `⚠︎` when gitleaks is not on PATH. See [Recovery flow: gitleaks FATAL on a session JSONL](#recovery-flow-gitleaks-fatal-on-a-session-jsonl).                                                                                                                     |
+| `nomad doctor --check-schema`    | Read-only: fetches the live Claude Code settings schema and lists any `~/.claude/settings.json` key absent from it (candidates for the hand-maintained `APP_ONLY_KEYS` list). Non-fatal and offline-tolerant: skips with a `⚠︎` when curl is missing or the schema is unreachable.                                                                                                                                                                                            |
+| `nomad --version`                | Print the installed CLI version as bare semver to stdout; exits 0. Used by the npm-publish smoke test and useful for ad-hoc upgrade checks.                                                                                                                                                                                                                                                                                                                                  |
 
 The version-check emits ``⚠︎ claude-nomad: <local> -> <latest> (run `nomad update`)`` when the local
 install is behind the latest upstream release, and `✓ claude-nomad: <local> (latest)` when current.
 It silently skips on network failures.
 
+The Hook targets check reads the live `~/.claude/settings.json` `hooks` block and fails (`✗`, exit
+
+1. when a hook command points at a script under `~/.claude/` that is missing on this host (the
+   freshly-configured-host symptom that motivated syncing `hooks/`). It deliberately skips any
+   command it cannot resolve to a `~/.claude/` path (bare binaries like `jq`, unresolved env vars),
+   so it never false-fails on a command that does not reference a local script.
+
 Two further `⚠︎`-only drift checks run in `nomad doctor`. The gitleaks version-drift line
 `⚠︎ gitleaks: <local> -> <pinned> (...)` fires when the local gitleaks major.minor differs from the
 CI-pinned `GITLEAKS_PINNED_VERSION` (gitleaks rule and allowlist behavior tracks the minor line, so

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-nomad",
-  "version": "0.28.0",
+  "version": "0.30.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.check-shared.scan.ts

@@ -83,10 +83,10 @@ function reportRemediation(
     const logical = logicalBySession.get(sid);
     /* c8 ignore next -- false branch is defensive; every bySession sid is keyed in logicalBySession */
     if (logical !== undefined) {
-      addItem(
-        section,
-        `  ${dim(`- rotate the credential, then scrub ${scrubPath(logical, sid, logicalToEncoded)}`)}`,
+      const rotateLine = dim(
+        `- rotate the credential, then scrub ${scrubPath(logical, sid, logicalToEncoded)}`,
       );
+      addItem(section, `  ${rotateLine}`);
     }
   }
   addItem(section, `  ${dim('- false positive? add a pattern to .gitleaks.toml')}`);
@@ -147,7 +147,8 @@ function emitDescriptionLegend(section: DoctorSection, findings: Finding[]): voi
   addItem(section, '');
   addItem(section, bold('Finding types'));
   for (const [rule, desc] of descByRule) {
-    addItem(section, `  ${red(`- [${rule}]`)}: ${dim(desc)}`);
+    const ruleLabel = red(`- [${rule}]`);
+    addItem(section, `  ${ruleLabel}: ${dim(desc)}`);
   }
 }
 

package/src/commands.doctor.checks.deps.ts

@@ -0,0 +1,97 @@
+import { execFileSync } from 'node:child_process';
+
+import { green, okGlyph, warnGlyph, yellow } from './color.ts';
+import { addItem, type DoctorSection } from './commands.doctor.format.ts';
+import type { SpawnSyncFn } from './gh-actions.ts';
+
+/**
+ * Optional-dependency presence reporter for `nomad doctor`. Probes for `gh`
+ * and `curl` (both optional CLIs used by nomad features) and emits one row
+ * per binary in the Version Checks section:
+ *   - present with parsed version: `okGlyph gh: X.Y.Z`
+ *   - present but version unparseable: `okGlyph gh: present`
+ *   - not installed (ENOENT): `warnGlyph gh: not installed (optional; ...)`
+ *
+ * This reporter MUST NOT set `process.exitCode`: absent optional deps are
+ * informational only (D-02). Both probes always run unconditionally.
+ */
+
+/**
+ * Regex to extract the first X.Y.Z version token from a string. Each segment
+ * is bounded (`{1,9}`) rather than `+` so the pattern is provably linear: a
+ * `--version` line never has a segment longer than a few digits, and bounding
+ * the repetition removes the super-linear backtracking an unbounded
+ * `\d+\.\d+\.\d+` carries on a degenerate all-digit input.
+ */
+const VERSION_TOKEN = /(\d{1,9}\.\d{1,9}\.\d{1,9})/;
+
+/**
+ * Extract the first X.Y.Z-shaped version token from a string.
+ *
+ * @param line - A single line of --version output (already trimmed).
+ * @returns The first version token, or `null` if none found.
+ */
+function parseFirstVersion(line: string): string | null {
+  const m = VERSION_TOKEN.exec(line);
+  return m ? m[1] : null;
+}
+
+/** Discriminated union for binary probe results. */
+type DepProbeResult = { status: 'present'; version: string | null } | { status: 'not-installed' };
+
+/**
+ * Probe a binary by running `bin --version` and parsing the first output line.
+ * Returns a DepProbeResult: present (with optional version token) or
+ * not-installed (ENOENT). Non-ENOENT errors are treated as present with no
+ * version (D-03: "never FAIL on unexpected --version output").
+ *
+ * @param bin - The binary name to probe (e.g. `gh` or `curl`).
+ * @param run - Injectable subprocess runner; defaults to `execFileSync`.
+ */
+function probeOptionalDep(bin: string, run: SpawnSyncFn): DepProbeResult {
+  try {
+    const firstLine = run(bin, ['--version'], { stdio: ['ignore', 'pipe', 'pipe'] })
+      .toString()
+      .split('\n')[0]
+      .trim();
+    const version = parseFirstVersion(firstLine);
+    return { status: 'present', version };
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === 'ENOENT') {
+      return { status: 'not-installed' };
+    }
+    // Non-ENOENT: binary may exist but --version misbehaved; report as present.
+    return { status: 'present', version: null };
+  }
+}
+
+/**
+ * Emit presence rows for the optional `gh` and `curl` CLIs into the given
+ * doctor section. Each row shows the binary's install status and version (if
+ * parseable). Absent binaries emit a WARN naming the features they enable.
+ * Never sets `process.exitCode` (D-02): both deps are optional.
+ *
+ * @param section - The Version Checks section to append rows to.
+ * @param run - Injectable subprocess runner; defaults to `execFileSync`.
+ */
+export function reportOptionalDeps(section: DoctorSection, run: SpawnSyncFn = execFileSync): void {
+  const gh = probeOptionalDep('gh', run);
+  if (gh.status === 'present') {
+    addItem(section, `${green(okGlyph)} gh: ${gh.version ?? 'present'}`);
+  } else {
+    addItem(
+      section,
+      `${yellow(warnGlyph)} gh: not installed (optional; needed for nomad init Actions auto-disable + mirror-Actions drift check)`,
+    );
+  }
+
+  const curl = probeOptionalDep('curl', run);
+  if (curl.status === 'present') {
+    addItem(section, `${green(okGlyph)} curl: ${curl.version ?? 'present'}`);
+  } else {
+    addItem(
+      section,
+      `${yellow(warnGlyph)} curl: not installed (optional; needed for release-version staleness check + nomad doctor --check-schema)`,
+    );
+  }
+}

package/src/commands.doctor.checks.hooks.ts

@@ -0,0 +1,176 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { dim, failGlyph, green, infoGlyph, okGlyph, red } from './color.ts';
+import { addItem, readJsonSafe, type DoctorSection } from './commands.doctor.format.ts';
+import { CLAUDE_HOME, HOME } from './config.ts';
+
+/**
+ * Always-on `nomad doctor` reporter. Reads `~/.claude/settings.json`, walks
+ * every `{ type: "command", command }` entry in the `hooks` block, and FAILs
+ * with `process.exitCode = 1` for each command token that confidently resolves
+ * to a path under `~/.claude` but is missing on disk. Commands with no
+ * resolvable `~/.claude` path (bare binaries, unresolved env vars) are silently
+ * skipped per D-09: the check only surfaces the issue-#170 case of synced hook
+ * config pointing at unsynced local scripts.
+ */
+
+/**
+ * Expand a leading `~`, `$HOME`, or `${HOME}` to the resolved HOME directory so
+ * the resulting path can be passed to `existsSync` and compared against the
+ * absolute `~/.claude` location. A token with no home-relative prefix (a bare
+ * binary, an already-absolute path) is returned unchanged.
+ *
+ * @param token - A raw path token extracted from a hook command string.
+ * @returns The path with any leading home-relative syntax resolved to HOME.
+ */
+function expandHome(token: string): string {
+  return token
+    .replace(/^\$\{HOME\}/, HOME)
+    .replace(/^\$HOME/, HOME)
+    .replace(/^~/, HOME);
+}
+
+/**
+ * Strip shell quoting and trailing control punctuation from a raw command
+ * token so a real path is not mistaken for a missing one. Without this, a
+ * quoted compound command like `bash -c 'a.sh; ~/.claude/hooks/run.sh'` yields
+ * the token `~/.claude/hooks/run.sh'` (trailing quote), and `existsSync` would
+ * FAIL on a script that is actually present (a D-09 false-FAIL). Removes
+ * leading quotes and any trailing run of `'"`;)|&>` characters. A genuine path
+ * never carries these on its boundary, so stripping them is safe.
+ *
+ * @param token - A raw whitespace-delimited token from a command segment.
+ * @returns The token with boundary shell punctuation removed.
+ */
+function stripShellPunctuation(token: string): string {
+  return token.replace(/^['"]+/, '').replace(/['"`;)|&>]+$/, '');
+}
+
+/**
+ * Yield every command token that resolves to a path under `~/.claude`. Each
+ * `&&`-, `||`-, `;`-, or `|`-separated sub-command is scanned token by token
+ * (not just its leading word), so wrappers like `bash ~/.claude/hooks/run.sh`
+ * are caught and not just `~/.claude/hooks/run.sh` on its own. Every token is
+ * stripped of shell quoting and home-expanded before comparison, so the
+ * literal `~`, `$HOME`, and `${HOME}` forms collapse to one check. Tokens that
+ * do not resolve under `~/.claude` (bare binaries, flags, unresolved env vars)
+ * are skipped per D-09, so the check only ever FAILs on a real `~/.claude`
+ * target.
+ *
+ * @param command - The raw `command` string from a hook entry.
+ * @returns Iterable of absolute resolved paths under `~/.claude`.
+ */
+function* claudePathsIn(command: string): Iterable<string> {
+  const claudePrefix = `${CLAUDE_HOME}/`;
+  for (const segment of command.split(/&&|\|\||;|\|/)) {
+    for (const raw of segment.trim().split(/\s+/).filter(Boolean)) {
+      const expanded = expandHome(stripShellPunctuation(raw));
+      if (expanded.startsWith(claudePrefix)) yield expanded;
+    }
+  }
+}
+
+/**
+ * A hook entry in flat format: `{ type: "command"; command: string }`.
+ * Used internally by `commandsFromFlat` to narrow the parsed JSON shape.
+ */
+type FlatEntry = { type: unknown; command?: unknown };
+
+/**
+ * Yield command strings from a flat-format entry list (each element is
+ * directly `{ type: "command", command: string }`). Skips non-object and
+ * non-command entries silently (T-25-07 defence).
+ *
+ * @param entries - Array of flat hook entries to walk.
+ */
+function* commandsFromFlat(entries: unknown[]): Iterable<string> {
+  for (const entry of entries) {
+    if (typeof entry !== 'object' || entry === null) continue;
+    const e = entry as FlatEntry;
+    if (e.type === 'command' && typeof e.command === 'string') yield e.command;
+  }
+}
+
+/**
+ * Yield every `{ type: "command"; command: string }` entry from a single
+ * hook group, which may be a flat array entry or a grouped object with a
+ * nested `hooks` array. Non-object / non-command entries are silently skipped
+ * (D-09 / T-25-07 defence: malformed input degrades to skips, never throws).
+ *
+ * @param group - One element of a hooks event array.
+ * @returns Iterable of command strings from command-type entries.
+ */
+function* commandsFromGroup(group: unknown): Iterable<string> {
+  if (typeof group !== 'object' || group === null) return;
+  const g = group as Record<string, unknown>;
+  // Grouped shape: { matcher?, hooks: HookEntry[] }
+  if (Array.isArray(g.hooks)) {
+    yield* commandsFromFlat(g.hooks);
+    return;
+  }
+  // Flat shape: the group itself is { type: "command", command: string }
+  if (g.type === 'command' && typeof g.command === 'string') yield g.command;
+}
+
+/**
+ * Walk all hook groups for a single event and emit FAIL items for every
+ * resolved-but-missing `~/.claude` target. Returns true when at least one
+ * FAIL was emitted (used by the caller to suppress the OK summary line).
+ *
+ * @param section - Doctor section to append items to.
+ * @param event - Hook event name (e.g. `PostToolUse`).
+ * @param groups - Array of hook groups for this event.
+ * @returns True when any missing target was found.
+ */
+function checkEventGroups(section: DoctorSection, event: string, groups: unknown[]): boolean {
+  let anyFail = false;
+  for (const group of groups) {
+    for (const cmd of commandsFromGroup(group)) {
+      for (const resolved of claudePathsIn(cmd)) {
+        if (existsSync(resolved)) continue;
+        addItem(section, `${red(failGlyph)} hooks/${event}: command target missing: ${resolved}`);
+        process.exitCode = 1;
+        anyFail = true;
+      }
+    }
+  }
+  return anyFail;
+}
+
+/**
+ * Append the Hook-targets check result to the supplied section. Reads
+ * `~/.claude/settings.json`, walks every command entry in the `hooks` block,
+ * and emits a `✗` FAIL for each `~/.claude` target that is absent on disk.
+ * Commands with no resolvable local path are silently skipped (D-09).
+ * Emits a `✓` OK line when all resolvable targets exist (or none were found).
+ * Emits a `ℹ︎` info skip when `settings.json` is absent.
+ *
+ * @param section - The doctor section to append items to.
+ */
+export function reportHooksTargetCheck(section: DoctorSection): void {
+  const settingsPath = join(CLAUDE_HOME, 'settings.json');
+  if (!existsSync(settingsPath)) {
+    addItem(section, `${dim(infoGlyph)} no ~/.claude/settings.json; skipping hook target check`);
+    return;
+  }
+
+  const settings = readJsonSafe<Record<string, unknown>>(settingsPath, settingsPath, section);
+  if (settings === null) return;
+
+  const hooks = settings.hooks;
+  if (typeof hooks !== 'object' || hooks === null || Array.isArray(hooks)) {
+    addItem(section, `${green(okGlyph)} hooks: all command targets present`);
+    return;
+  }
+
+  let anyFail = false;
+  for (const [event, groups] of Object.entries(hooks as Record<string, unknown>)) {
+    if (!Array.isArray(groups)) continue;
+    if (checkEventGroups(section, event, groups)) anyFail = true;
+  }
+
+  if (!anyFail) {
+    addItem(section, `${green(okGlyph)} hooks: all command targets present`);
+  }
+}

package/src/commands.doctor.checks.repo.ts

@@ -13,7 +13,7 @@ import {
   warnGlyph,
   yellow,
 } from './color.ts';
-import { CLAUDE_HOME, HOST, REPO_HOME, SHARED_LINKS } from './config.ts';
+import { allSharedLinks, CLAUDE_HOME, HOST, REPO_HOME, type PathMap } from './config.ts';
 import { addItem, type DoctorSection } from './commands.doctor.format.ts';
 import { classifyRepoState, reasonForPartial } from './init.classify.ts';
 
@@ -157,8 +157,9 @@ function classifySymlinkTarget(name: string, p: string): { line: string; fail: b
 }
 
 /**
- * Emits a per-entry status line for each name in SHARED_LINKS
- * (okGlyph/warnGlyph/infoGlyph/failGlyph). A non-symlink blocks sync and FAILs
+ * Emits a per-entry status line for each name in `allSharedLinks(map)` (the
+ * static shared-link set plus any validated `sharedDirs` entries) using
+ * okGlyph/warnGlyph/infoGlyph/failGlyph. A non-symlink blocks sync and FAILs
  * via process.exitCode. TOCTOU-safe: lstatSync is wrapped in try/catch so a path
  * that vanishes or becomes unreadable between the probe and the stat yields a
  * row instead of an unhandled throw that aborts the whole doctor run. Severity
@@ -168,8 +169,8 @@ function classifySymlinkTarget(name: string, p: string): { line: string; fail: b
  * sync). A symlink whose target cannot be resolved is never a healthy OK, so a
  * dangling or unreadable link is not masked.
  */
-export function reportSharedLinks(section: DoctorSection): void {
-  for (const name of SHARED_LINKS) {
+export function reportSharedLinks(section: DoctorSection, map: PathMap): void {
+  for (const name of allSharedLinks(map)) {
     const p = join(CLAUDE_HOME, name);
     const { line, fail } = classifySharedLink(name, p);
     addItem(section, line);

package/src/commands.doctor.checks.repository.ts

@@ -28,10 +28,16 @@ import { gitStatusPorcelainZ } from './utils.ts';
  */
 
 /**
- * Probes for gitleaks on PATH; emits okGlyph with version, or failGlyph with
- * ENOENT vs other-error distinction (sets exitCode=1). Returns `true` when a
- * usable binary was found so the caller can skip a redundant second `version`
- * probe (e.g. the `--check-shared` Shared scan section).
+ * Probes for gitleaks on PATH. Emits okGlyph with version when found. When
+ * gitleaks is absent (ENOENT), emits warnGlyph and does NOT set exitCode:
+ * gitleaks is required for `nomad push` but is an optional dependency for the
+ * read-only doctor check, so its absence degrades to WARN per the project
+ * convention that optional-dependency absence must never affect exit code. A
+ * non-ENOENT error (broken binary, permission denied) still emits failGlyph
+ * and sets exitCode=1 because a present-but-unrunnable gitleaks is a real
+ * defect that would break `nomad push`. Returns `true` when a usable binary
+ * was found so the caller can skip a redundant second `version` probe (e.g.
+ * the `--check-shared` Shared scan section).
  */
 export function reportGitleaksProbe(section: DoctorSection): boolean {
   try {
@@ -42,11 +48,11 @@ export function reportGitleaksProbe(section: DoctorSection): boolean {
     return true;
   } catch (err) {
     if ((err as NodeJS.ErrnoException).code === 'ENOENT') {
-      addItem(section, `${red(failGlyph)} gitleaks: not on PATH (required for nomad push)`);
+      addItem(section, `${yellow(warnGlyph)} gitleaks: not on PATH (required for nomad push)`);
     } else {
       addItem(section, `${red(failGlyph)} gitleaks: probe failed: ${(err as Error).message}`);
+      process.exitCode = 1;
     }
-    process.exitCode = 1;
     return false;
   }
 }

package/src/commands.doctor.ts

@@ -1,3 +1,6 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+
 import {
   reportHostAndPaths,
   reportRepoState,
@@ -17,9 +20,12 @@ import {
 } from './commands.doctor.checks.repository.ts';
 import { reportCheckSchema } from './commands.doctor.check-schema.ts';
 import { reportCheckShared } from './commands.doctor.check-shared.ts';
+import { reportHooksTargetCheck } from './commands.doctor.checks.hooks.ts';
+import { REPO_HOME, type PathMap } from './config.ts';
 import { reportNodeEngineCheck } from './commands.doctor.engine.ts';
-import { renderDoctor, section } from './commands.doctor.format.ts';
+import { readJsonSafe, renderDoctor, section } from './commands.doctor.format.ts';
 import { reportGitleaksVersionCheck } from './commands.doctor.gitleaks-version.ts';
+import { reportOptionalDeps } from './commands.doctor.checks.deps.ts';
 import { reportMirrorActions } from './commands.doctor.mirror-actions.ts';
 import { reportVersionCheck } from './commands.doctor.version.ts';
 
@@ -47,7 +53,16 @@ export function cmdDoctor(opts: { checkShared?: boolean; checkSchema?: boolean }
   reportRepoState(host);
 
   const links = section('Shared links');
-  reportSharedLinks(links);
+  // Tolerantly read path-map.json for sharedDirs: doctor is read-only and
+  // must not throw on a missing or malformed map. Fall back to { projects: {} }
+  // so hooks + static SHARED_LINKS rows still emit on a fresh host.
+  const mapPath = join(REPO_HOME, 'path-map.json');
+  const rawMap = existsSync(mapPath) ? readJsonSafe<PathMap>(mapPath, mapPath, links) : null;
+  const map: PathMap = rawMap ?? { projects: {} };
+  reportSharedLinks(links, map);
+
+  const hooksScan = section('Hook targets');
+  reportHooksTargetCheck(hooksScan);
 
   const settings = section('Settings');
   const base = loadBaseSettings(settings);
@@ -71,6 +86,7 @@ export function cmdDoctor(opts: { checkShared?: boolean; checkSchema?: boolean }
   reportVersionCheck(version);
   reportNodeEngineCheck(version);
   reportGitleaksVersionCheck(version);
+  reportOptionalDeps(version);
 
   const sharedScan = section('Shared scan');
   // Reuse the Repository-section readiness probe so reportCheckShared does not
@@ -86,6 +102,7 @@ export function cmdDoctor(opts: { checkShared?: boolean; checkSchema?: boolean }
     version,
     host,
     links,
+    hooksScan,
     settings,
     pathMap,
     neverSync,

package/src/commands.pull.ts

@@ -6,7 +6,7 @@ import {
   buildSessionsSection,
   buildSettingsSection,
 } from './commands.push.sections.ts';
-import { HOME, HOST, REPO_HOME } from './config.ts';
+import { HOME, HOST, REPO_HOME, type PathMap } from './config.ts';
 import { divergenceCheckExtras, remapExtrasPull } from './extras-sync.ts';
 import { applySharedLinks, regenerateSettings } from './links.ts';
 import { renderTree, section, addItem } from './output-tree.ts';
@@ -16,6 +16,7 @@ import { emitSummary, summaryRow } from './summary.ts';
 import { die, fail, gitOrFatal, log, NomadFatal } from './utils.ts';
 import { freshBackupTs } from './utils.fs.ts';
 import { acquireLock, releaseLock } from './utils.lockfile.ts';
+import { readPathMap } from './utils.json.ts';
 
 /**
  * Run the WET (non-dry-run) pull side effects in order and render the
@@ -30,8 +31,8 @@ import { acquireLock, releaseLock } from './utils.lockfile.ts';
  *
  * @param ts - backup timestamp namespace shared by every WET side effect.
  */
-function applyWetPull(ts: string): void {
-  applySharedLinks(ts);
+function applyWetPull(ts: string, map: PathMap): void {
+  applySharedLinks(ts, map);
   const { label } = regenerateSettings(ts);
   const remapResult = remapPull(ts);
   const extrasResult = remapExtrasPull(ts);
@@ -133,20 +134,25 @@ export function cmdPull(opts: { dryRun?: boolean } = {}): void {
         : `pull on host=${HOST} (backup=${ts})`,
     );
     gitOrFatal(['pull', '--rebase', '--autostash'], 'git pull --rebase', REPO_HOME);
+    // Read path-map.json for sharedDirs/symlink threading. Falls back to a
+    // no-sharedDirs map when the file is absent (fresh-clone before init).
+    // A parse failure routes through NomadFatal -> catch -> lock release.
+    const mapPath = join(REPO_HOME, 'path-map.json');
+    const map: PathMap = existsSync(mapPath) ? readPathMap(mapPath) : { projects: {} };
     // Read-only pre-pull check: fires in BOTH wet and dry modes (D-08).
     // Runs AFTER the rebase (so origin content is fetched) and BEFORE any
     // mutation (so local state is intact for byte-level comparison). The
     // function itself silently skips when no `extras` key is declared.
     divergenceCheckExtras(ts);
     if (dryRun) {
-      const previewResult = computePreview(ts);
+      const previewResult = computePreview(ts, map);
       // dryRun deliberately omits remapExtrasPull to preserve the
       // zero-mutation contract; users still see the divergence WARN above.
       // BYTE-IDENTICAL dry-run output: standalone emitSummary, no tree.
       log('dry-run complete; no mutation');
       emitSummary('pull', previewResult.unmapped);
     } else {
-      applyWetPull(ts);
+      applyWetPull(ts, map);
     }
   } catch (err) {
     // Catch fatal errors here so the finally block runs and releases the

package/src/commands.push.allowlist.ts

@@ -1,4 +1,5 @@
 import { NEVER_SYNC, PUSH_ALLOWED_STATIC, SUPPORTED_EXTRAS, type PathMap } from './config.ts';
+import { isValidSharedDir } from './config.sharedDirs.guard.ts';
 import { fail, NomadFatal } from './utils.ts';
 
 /**
@@ -98,6 +99,7 @@ export function enforceAllowList(statusPorcelain: string, map: PathMap): void {
         .filter((n) => extrasWhitelist.includes(n))
         .flatMap((n) => [`shared/extras/${l}/${n}`, `shared/extras/${l}/${n}/`]),
     ),
+    ...(map.sharedDirs ?? []).filter((d) => isValidSharedDir(d)).map((d) => `shared/${d}/`),
   ];
   const neverSyncHits: string[] = [];
   const violations: string[] = [];

package/src/config.sharedDirs.guard.ts

@@ -0,0 +1,55 @@
+import { NEVER_SYNC } from './config.ts';
+
+/**
+ * Single-segment path characters allowed in a `sharedDirs` entry. Mirrors
+ * `SAFE_LOGICAL` in `extras-sync.guards.ts` but applied to global support
+ * directory names rather than per-project logical names. Must match
+ * `^[A-Za-z0-9._-]+$` so no path separator, no shell-special character, no
+ * leading dot that would collide with a hidden state directory.
+ */
+const SAFE_SEGMENT = /^[A-Za-z0-9._-]+$/;
+
+/**
+ * Names that already exist under `shared/` (as repo-structural files or as
+ * members of `SHARED_LINKS`) that a `sharedDirs` entry must not collide with.
+ * Adding a `sharedDirs` entry matching one of these would either shadow a
+ * structural file or create a duplicate symlink pointing at the same target.
+ */
+const RESERVED_SHARED = new Set([
+  'settings.base.json',
+  'CLAUDE.md',
+  'agents',
+  'skills',
+  'commands',
+  'rules',
+  'my-statusline.cjs',
+  'hooks',
+  'hosts',
+  'path-map.json',
+  'extras',
+  'projects',
+]);
+
+/**
+ * Returns `true` when `entry` is a valid `sharedDirs` path segment: a single
+ * path segment (no `/` or `..`), not present in `NEVER_SYNC`, and not a
+ * reserved `shared/` name. Invalid entries are dropped with a WARN by the
+ * caller (`allSharedLinks` in `config.ts`) rather than throwing a fatal error,
+ * mirroring the resilience of the existing extras path.
+ *
+ * Accepts `unknown` because `path-map.json` is runtime input: a malformed
+ * `sharedDirs` array can hold non-string values (numbers, objects, null) that
+ * `SAFE_SEGMENT.test` would otherwise string-coerce (e.g. `42` -> `"42"`).
+ * Rejecting non-strings first drops those shapes deterministically, and the
+ * `entry is string` predicate narrows the value for callers that filter on it.
+ *
+ * @param entry - Candidate `sharedDirs` value from `path-map.json`.
+ * @returns `true` if the entry is safe to use as a symlink target under `~/.claude/`.
+ */
+export function isValidSharedDir(entry: unknown): entry is string {
+  if (typeof entry !== 'string') return false;
+  if (!SAFE_SEGMENT.test(entry) || entry === '.' || entry === '..') return false;
+  if (NEVER_SYNC.has(entry)) return false;
+  if (RESERVED_SHARED.has(entry)) return false;
+  return true;
+}

package/src/config.ts

@@ -1,6 +1,9 @@
 import { homedir, hostname } from 'node:os';
 import { resolve } from 'node:path';
 
+import { isValidSharedDir } from './config.sharedDirs.guard.ts';
+import { warn } from './utils.ts';
+
 /**
  * Resolved home directory. Uses Node's `os.homedir()` which reads `$HOME` on
  * POSIX and falls back to `getpwuid_r()` when the env var is unset. Returns
@@ -74,8 +77,34 @@ export const SHARED_LINKS = [
   'commands',
   'rules',
   'my-statusline.cjs',
+  'hooks',
 ] as const;
 
+/**
+ * Returns the union of `SHARED_LINKS` and any validated entries from
+ * `map.sharedDirs`. Entries that fail the `isValidSharedDir` guard (path
+ * separators, NEVER_SYNC names, reserved shared/ names) are dropped with a
+ * single WARN per entry; the remaining valid entries are appended after the
+ * static `SHARED_LINKS` names. Callers iterate the result with `for...of` to
+ * apply the same symlink machinery to both built-in and user-configured dirs.
+ *
+ * @param map - Parsed `path-map.json` content.
+ * @returns Array of link names to symlink under `~/.claude/`.
+ */
+export function allSharedLinks(map: PathMap): string[] {
+  const extras: string[] = [];
+  for (const entry of map.sharedDirs ?? []) {
+    if (isValidSharedDir(entry)) {
+      extras.push(entry);
+    } else {
+      warn(
+        `sharedDirs entry ${JSON.stringify(entry)} is invalid (path separator, reserved name, or NEVER_SYNC); skipping`,
+      );
+    }
+  }
+  return [...SHARED_LINKS, ...extras];
+}
+
 /**
  * Whitelist of names allowed in `path-map.json`'s top-level `extras` field.
  * Each entry is either a directory name (e.g. `.planning`) OR a single
@@ -94,9 +123,13 @@ export const SUPPORTED_EXTRAS = ['.planning', 'CLAUDE.md'] as const;
  * Path segments that must never cross the sync boundary in either direction.
  * Defense-in-depth pair with `PUSH_ALLOWED_STATIC`: even if the allow-list
  * misses a path, anything containing one of these segments is hard-blocked.
+ * Also the deny-list the `sharedDirs` opt-in is validated against, so a user
+ * cannot symlink a host-local secret or cache into the shared repo by naming
+ * it in `path-map.json`.
  */
 export const NEVER_SYNC = new Set([
   '.claude.json',
+  '.credentials.json',
   'history.jsonl',
   'settings.local.json',
   'stats-cache.json',
@@ -109,6 +142,16 @@ export const NEVER_SYNC = new Set([
   'statsig',
   'telemetry',
   'ide',
+  // Host-local caches and runtime state: never useful to share, and named here
+  // so the sharedDirs guard rejects an accidental opt-in.
+  'cache',
+  'backups',
+  'paste-cache',
+  'daemon',
+  'jobs',
+  'tasks',
+  'security',
+  'sessions',
 ]);
 
 // Schema-drift baseline for `~/.claude/settings.json`; top-level keys not in
@@ -134,6 +177,7 @@ export const PUSH_ALLOWED_STATIC = [
   'shared/commands/',
   'shared/rules/',
   'shared/.gitignore',
+  'shared/hooks/',
   'hosts/',
   'path-map.json',
 ] as const;
@@ -150,8 +194,16 @@ export const PUSH_ALLOWED_STATIC = [
  * consumers against `SUPPORTED_EXTRAS`. Absence of the field is equivalent
  * to no extras for any project; legacy `path-map.json` files without an
  * `extras` block continue to work unchanged (no migration required).
+ *
+ * Optional `sharedDirs` field (additive, top-level): opt-in global support
+ * directories under `~/.claude/` to include in the `SHARED_LINKS` symlink set.
+ * Each entry is a single path segment (e.g. `"get-shit-done"`); entries that
+ * fail the `isValidSharedDir` guard are dropped with a WARN and never reach the
+ * filesystem. Absence of the field is equivalent to no extra shared dirs; legacy
+ * `path-map.json` files without a `sharedDirs` block continue to work unchanged.
  */
 export type PathMap = {
   projects: Record<string, Record<string, string>>;
   extras?: Record<string, string[]>;
+  sharedDirs?: string[];
 };

package/src/diff-lines.ts

@@ -27,14 +27,13 @@ export function diffLinesToUnified(oldStr: string, newStr: string): string[] {
   for (const part of parts) {
     const partLines = part.value.split('\n');
     // A part value ending in '\n' yields a trailing '' after split; drop it.
-    if (partLines[partLines.length - 1] === '') {
+    if (partLines.at(-1) === '') {
       partLines.pop();
     }
-    const prefix = part.removed
-      ? (line: string) => red(`-${line}`)
-      : part.added
-        ? (line: string) => green(`+${line}`)
-        : (line: string) => ` ${line}`;
+    let prefix: (line: string) => string;
+    if (part.removed) prefix = (line) => red(`-${line}`);
+    else if (part.added) prefix = (line) => green(`+${line}`);
+    else prefix = (line) => ` ${line}`;
     for (const line of partLines) {
       lines.push(prefix(line));
     }

package/src/diff.ts

@@ -1,11 +1,12 @@
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 
-import { HOME, REPO_HOME } from './config.ts';
+import { HOME, REPO_HOME, type PathMap } from './config.ts';
 import { computePreview } from './preview.ts';
 import { emitSummary } from './summary.ts';
 import { die, fail, NomadFatal } from './utils.ts';
 import { freshBackupTs } from './utils.fs.ts';
+import { readPathMap } from './utils.json.ts';
 
 /**
  * `nomad diff` command. Offline-safe, read-only preview surface that runs
@@ -37,7 +38,11 @@ export function cmdDiff(): void {
     const ts = freshBackupTs(backupBase);
     // Preview log lines reference `ts` so output stays consistent with
     // pull --dry-run; the backup root itself is intentionally NOT created.
-    const result = computePreview(ts);
+    // Read the map tolerantly (offline-safe: fall back to no-sharedDirs when
+    // path-map.json is absent from a partially-scaffolded repo).
+    const mapPath = join(REPO_HOME, 'path-map.json');
+    const map: PathMap = existsSync(mapPath) ? readPathMap(mapPath) : { projects: {} };
+    const result = computePreview(ts, map);
     emitSummary('diff', result.unmapped);
   } catch (err) {
     if (err instanceof NomadFatal) {

package/src/extras-sync.ts

@@ -3,21 +3,17 @@ import { join } from 'node:path';
 
 import { HOME, REPO_HOME, SUPPORTED_EXTRAS, type PathMap } from './config.ts';
 import { listDivergingFiles } from './extras-sync.diff.ts';
-import {
-  copyExtras,
-  eachExtrasTarget,
-  loadValidatedExtras,
-  type ExtrasCounts,
-  type ValidatedExtras,
-} from './extras-sync.core.ts';
+import { eachExtrasTarget, loadValidatedExtras, type ExtrasCounts } from './extras-sync.core.ts';
 import { assertSafeLogical } from './extras-sync.guards.ts';
 import { warn } from './utils.ts';
 import { encodePath } from './utils.json.ts';
 
 // Re-export the shared primitives so existing import sites that pull them from
 // `./extras-sync.ts` (tests call `copyExtras` directly) keep working unchanged.
-export { copyExtras, eachExtrasTarget, loadValidatedExtras };
-export type { ExtrasCounts, ValidatedExtras };
+export { copyExtras } from './extras-sync.core.ts';
+export type { ValidatedExtras } from './extras-sync.core.ts';
+export { eachExtrasTarget, loadValidatedExtras };
+export type { ExtrasCounts };
 
 // The two public remap ops live in the sibling module to hold the soft
 // line-cap; re-exported here so `./extras-sync.ts` stays the public surface.

package/src/init.snapshot.ts

@@ -1,26 +1,27 @@
 import { copyFileSync, cpSync, existsSync, rmSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 
-import { CLAUDE_HOME, HOST, REPO_HOME, SHARED_LINKS } from './config.ts';
+import { allSharedLinks, CLAUDE_HOME, HOST, REPO_HOME, type PathMap } from './config.ts';
 import { die, log } from './utils.ts';
 import { writeJsonAtomic } from './utils.fs.ts';
 import { readJson } from './utils.json.ts';
 
 /**
- * Overlay `~/.claude/` SHARED_LINKS onto the freshly-written scaffold under
- * `REPO_HOME/shared/`. Regular files (`CLAUDE.md`, `my-statusline.cjs`) go
- * through `copyFileSync` so the placeholder is overwritten; directories
- * (`agents`, `skills`, `commands`, `rules`) drop their just-written
- * `.gitkeep` marker first and then go through `cpSync` with `force: false`,
- * so any unexpected pre-existing destination content (an out-of-band write
- * between the preflight check and this step) surfaces as an error. Also
- * translates `~/.claude/settings.json` (when present) into `hosts/<HOST>.json`
- * via `writeJsonAtomic`. Does NOT modify `~/.claude/`; the caller emits the
- * user-visible next-step + originals-not-removed log lines so the canonical
- * phrasing stays co-located with `cmdInit` itself.
+ * Overlay `~/.claude/` entries for every name in `allSharedLinks(map)` (the
+ * static shared-link set plus any validated `sharedDirs` entries) onto the
+ * freshly-written scaffold under `REPO_HOME/shared/`. Regular files
+ * (`CLAUDE.md`, `my-statusline.cjs`) go through `copyFileSync` so the
+ * placeholder is overwritten; directories (`agents`, `skills`, `commands`,
+ * `rules`) drop their just-written `.gitkeep` marker first and then go through
+ * `cpSync` with `force: false`, so any unexpected pre-existing destination
+ * content surfaces as an error. Also translates `~/.claude/settings.json`
+ * (when present) into `hosts/<HOST>.json` via `writeJsonAtomic`. Does NOT
+ * modify `~/.claude/`; the caller emits the user-visible next-step +
+ * originals-not-removed log lines so the canonical phrasing stays co-located
+ * with `cmdInit` itself.
  */
-export function snapshotIntoShared(): void {
-  for (const name of SHARED_LINKS) {
+export function snapshotIntoShared(map: PathMap): void {
+  for (const name of allSharedLinks(map)) {
     const src = join(CLAUDE_HOME, name);
     if (!existsSync(src)) continue;
     const dst = join(REPO_HOME, 'shared', name);

package/src/init.ts

@@ -29,7 +29,7 @@ const SHARED_CLAUDE_MD =
  * with the SHARED_LINKS contract in `src/config.ts` (those same names are
  * symlinked into `~/.claude/` on every pull).
  */
-const SHARED_KEEP_DIRS = ['agents', 'skills', 'commands', 'rules'] as const;
+const SHARED_KEEP_DIRS = ['agents', 'skills', 'commands', 'rules', 'hooks'] as const;
 
 /**
  * Pre-flight refuse-to-clobber list. If ANY of these absolute paths
@@ -112,7 +112,10 @@ export function cmdInit(
   log('created path-map.json');
 
   if (snapshot) {
-    snapshotIntoShared();
+    // In the init path, path-map.json was just written as `{ projects: {} }`
+    // (preflight refuses a pre-existing one), so sharedDirs is empty by
+    // construction. Pass the minimal map literal to satisfy the type.
+    snapshotIntoShared({ projects: {} });
     log(`snapshot staged in shared/; review, then 'nomad push' to share with other hosts.`);
     log('~/.claude/ originals were NOT removed.');
   }

package/src/links.ts

@@ -1,19 +1,21 @@
 import { existsSync, lstatSync, rmSync } from 'node:fs';
 import { join } from 'node:path';
 
-import { CLAUDE_HOME, HOST, REPO_HOME, SHARED_LINKS } from './config.ts';
+import { allSharedLinks, CLAUDE_HOME, HOST, REPO_HOME, type PathMap } from './config.ts';
 import { die, log, warn } from './utils.ts';
 import { backupBeforeWrite, ensureSymlink, writeJsonAtomic } from './utils.fs.ts';
 import { deepMerge, readJson } from './utils.json.ts';
 
 /**
- * Symlink the `SHARED_LINKS` names from the repo's `shared/` dir into
- * `~/.claude/`. Two-pass: first back up and remove any pre-existing
- * non-symlink at each link path (auto-move using `ts` as the backup
- * timestamp), then create the symlinks. Skips a link entirely when the repo
- * has no counterpart, so a host where `shared/commands/` does not exist
- * keeps its local `~/.claude/commands/` instead of having it silently
- * deleted.
+ * Symlink every name in `allSharedLinks(map)` (the static shared-link set
+ * plus any validated `sharedDirs` entries from `path-map.json`) from the
+ * repo's `shared/` dir into `~/.claude/`. Two-pass: first back up and remove
+ * any pre-existing non-symlink at each link path (auto-move using `ts` as the
+ * backup timestamp), then create the symlinks. Skips a link entirely when the
+ * repo has no `shared/<name>` counterpart, so a host where `shared/commands/`
+ * does not exist keeps its local `~/.claude/commands/` instead of having it
+ * silently deleted. `sharedDirs` entries route through the identical two-pass
+ * logic (refuse-non-symlink / backup / dryRun-log behavior is unchanged).
  *
  * `opts.dryRun` (default `false`): when `true`, no disk mutation occurs. The
  * function logs `would auto-move non-symlink:` and `would create symlink:`
@@ -21,9 +23,12 @@ import { deepMerge, readJson } from './utils.json.ts';
  * call with no opts arg or with `dryRun: false` keeps the prior mutating
  * behavior.
  */
-export function applySharedLinks(ts: string, opts: { dryRun?: boolean } = {}): void {
+export function applySharedLinks(ts: string, map: PathMap, opts: { dryRun?: boolean } = {}): void {
   const dryRun = opts.dryRun === true;
-  for (const name of SHARED_LINKS) {
+  // Derive once: allSharedLinks emits a WARN per invalid sharedDirs entry, so
+  // calling it per loop would double every such warning in a single run.
+  const linkNames = allSharedLinks(map);
+  for (const name of linkNames) {
     const linkPath = join(CLAUDE_HOME, name);
     const target = join(REPO_HOME, 'shared', name);
     if (!existsSync(linkPath)) continue;
@@ -36,7 +41,7 @@ export function applySharedLinks(ts: string, opts: { dryRun?: boolean } = {}): v
     backupBeforeWrite(linkPath, ts);
     rmSync(linkPath, { recursive: true, force: true });
   }
-  for (const name of SHARED_LINKS) {
+  for (const name of linkNames) {
     const target = join(REPO_HOME, 'shared', name);
     if (!existsSync(target)) continue;
     if (dryRun) {

package/src/preview.ts

@@ -1,7 +1,7 @@
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 
-import { CLAUDE_HOME, HOST, REPO_HOME } from './config.ts';
+import { CLAUDE_HOME, HOST, REPO_HOME, type PathMap } from './config.ts';
 import { diffLinesToUnified } from './diff-lines.ts';
 import { applySharedLinks } from './links.ts';
 import { remapPull } from './remap.ts';
@@ -102,13 +102,16 @@ function previewSettings(basePath: string, hostPath: string, settingsPath: strin
  *
  * Settings diff output goes through `log()` so each line gets the info-prefixed
  * prefix, keeping output channels consistent across the three sections.
+ *
+ * @param map - parsed path-map.json; callers fall back to `{ projects: {} }`
+ *   when the file is absent so the offline/fresh-clone contract holds.
  */
-export function computePreview(ts: string): { unmapped: number; collisions: number } {
+export function computePreview(ts: string, map: PathMap): { unmapped: number; collisions: number } {
   log(`would pull on host=${HOST} (dry-run; no mutation)`);
 
   // Symlinks: applySharedLinks emits its own would-create / would-auto-move
   // lines. dryRun:true is mandatory; a real call here would mutate disk.
-  applySharedLinks(ts, { dryRun: true });
+  applySharedLinks(ts, map, { dryRun: true });
 
   previewSettings(
     join(REPO_HOME, 'shared', 'settings.base.json'),

package/src/summary.ts

@@ -1,6 +1,9 @@
 import { green, okGlyph, warnGlyph, yellow } from './color.ts';
 import { ok, warn } from './utils.ts';
 
+/** The three originating commands that share the end-of-run summary line. */
+type SummaryVerb = 'pull' | 'push' | 'diff';
+
 /**
  * Pure phrasing core for the end-of-run summary line shared by cmdPull,
  * cmdPush, and cmdDiff. Returns the message `text` (without any status glyph)
@@ -27,7 +30,7 @@ import { ok, warn } from './utils.ts';
  * @returns `{ text, clean }` where `clean` is true on the no-warning outcome.
  */
 export function summaryText(
-  verb: 'pull' | 'push' | 'diff',
+  verb: SummaryVerb,
   unmapped: number,
   collisions = 0,
   extrasSkipped = 0,
@@ -63,7 +66,7 @@ export function summaryText(
  * @returns the rendered row string for the Summary section.
  */
 export function summaryRow(
-  verb: 'pull' | 'push' | 'diff',
+  verb: SummaryVerb,
   unmapped: number,
   collisions = 0,
   extrasSkipped = 0,
@@ -85,7 +88,7 @@ export function summaryRow(
  * contract). `cmdDiff` still calls this for its standalone summary line.
  */
 export function emitSummary(
-  verb: 'pull' | 'push' | 'diff',
+  verb: SummaryVerb,
   unmapped: number,
   collisions = 0,
   extrasSkipped = 0,