claude-nomad 0.27.0 → 0.28.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## [0.28.0](https://github.com/funkadelic/claude-nomad/compare/v0.27.0...v0.28.0) (2026-05-28)
+
+
+### Added
+
+* **doctor:** settings schema drift tooling (auto-sync PR + --check-schema) ([#168](https://github.com/funkadelic/claude-nomad/issues/168)) ([ac4ac21](https://github.com/funkadelic/claude-nomad/commit/ac4ac21f90148d7261b0b907bfdad43b3758f9fd))
+
+
+### Fixed
+
+* **doctor:** resync KNOWN_SETTINGS_KEYS with official settings schema ([#166](https://github.com/funkadelic/claude-nomad/issues/166)) ([2b453e1](https://github.com/funkadelic/claude-nomad/commit/2b453e18c18520dd0a4df035ace3825709097bc1))
+* drop-session scrub hint and README rendering/layout fixes ([#165](https://github.com/funkadelic/claude-nomad/issues/165)) ([0840ab4](https://github.com/funkadelic/claude-nomad/commit/0840ab408b72174b23532a0ea32c27df522cfe39))
+
 ## [0.27.0](https://github.com/funkadelic/claude-nomad/compare/v0.26.2...v0.27.0) (2026-05-28)
 
 

package/README.md

@@ -67,7 +67,7 @@ box, a personal rig and a work machine. [Get started in three steps.](#quickstar
 ## Quickstart
 
 If you already have a private **claude-nomad** mirror (see [Setup](#setup) for the one-time
-bootstrap), adding a new host is three steps:
+bootstrap), adding a new host is two one-time steps, then the everyday loop:
 
 ```bash
 $ npm i -g claude-nomad
@@ -157,16 +157,28 @@ 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/` (see `SHARED_LINKS` in `src/config.ts`).                                                                                                                             |
-| **Generated**          | `settings.json`                                                                                                                                                                                                                           | Deep-merge of `settings.base.json` with `hosts/<hostname>.json`. Rewritten on every pull.                                                                                                                       |
-| **Remapped**           | `projects/` session transcripts                                                                                                                                                                                                           | Copied with path translation per `path-map.json`.                                                                                                                                                               |
-| **Per-project extras** | `<localRoot>/.planning/` and other directories, or a single root file like `CLAUDE.md`, whitelisted by `SUPPORTED_EXTRAS` in `src/config.ts`                                                                                              | Opt-in via the `extras` field in `path-map.json`. Mirrored to/from `shared/extras/<logical>/<name>` (directory subtree or single file). Pre-pull divergence WARN flags local edits before they get overwritten. |
-| **Never synced**       | `~/.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/` | Per-host ephemeral state.                                                                                                                                                                                       |
-| **Auto-rehydrated**    | `~/.claude/plugins/cache/<plugin>/...`                                                                                                                                                                                                    | Plugin payloads not synced. Claude Code re-downloads them on first use from the `enabledPlugins` list in the regenerated `settings.json`; no manual `claude plugins install ...` per host.                      |
-
-> [!NOTE] Plugins that depend on host-specific state (external binaries, API keys in env, MCP server
+| 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.              |
+
+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/`.
+- **Per-project extras** run a pre-pull divergence WARN that flags local edits before they get
+  overwritten.
+
+<!-- prettier-ignore -->
+> [!NOTE]
+> Plugins that depend on host-specific state (external binaries, API keys in env, MCP server
 > URLs) still need that side set up on each host. Put them in `hosts/<host>.json` or the plugin's
 > own per-host config.
 
@@ -197,7 +209,9 @@ block opts a project into syncing whitelisted directories (or a single root file
 }
 ```
 
-> [!IMPORTANT] The host-label keys must match whatever you set `NOMAD_HOST=` to on each host (see
+<!-- prettier-ignore -->
+> [!IMPORTANT]
+> The host-label keys must match whatever you set `NOMAD_HOST=` to on each host (see
 > [Setup](#setup)). Mismatched labels silently skip remap, so sessions land in the wrong host's
 > encoded dir.
 
@@ -249,17 +263,25 @@ host-only model overrides).
 
 ```json
 {
-  "model": "claude-opus-4-7",
+  "model": "claude-opus-4-8",
   "env": { "OLLAMA_HOST": "http://localhost:11434" }
 }
 ```
 
-Results on `your-other-host`: opus 4.7, the local Ollama env var, plus the shared permissions array.
+Results on `your-other-host`: opus 4.8, the local Ollama env var, plus the shared permissions array.
 
-> [!CAUTION] Never hand-edit `~/.claude/settings.json` on a synced host. It's regenerated on every
+<!-- prettier-ignore -->
+> [!CAUTION]
+> Never hand-edit `~/.claude/settings.json` on a synced host. It's regenerated on every
 > `nomad pull` from base + host, so your edits will be clobbered. Edit the base or host file in the
 > repo instead.
 
+`nomad doctor` warns when `settings.json` carries a top-level key it does not recognize (a cue that
+Claude Code added a setting). The recognized set is kept current against Claude Code's published
+settings schema by a weekly automated PR in the public repo, so a periodic `nomad update` is what
+keeps that warning quiet on your hosts. To check your own `settings.json` against the live schema on
+demand, run `nomad doctor --check-schema`.
+
 ## What does NOT sync (deliberate trade-offs)
 
 Read these before adopting so you opt in with eyes open.
@@ -300,9 +322,9 @@ 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
-- [curl](https://curl.se/), used only by the version/update check (the `nomad doctor` latest-release
-  line and the post-`nomad update` check); it degrades silently when curl is absent or offline, so
-  the rest of the CLI works without it
+- [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
 
 ## Setup
 
@@ -330,7 +352,9 @@ automatically:
 Pass `--keep-actions` to either form of init to skip step 2 (for example, when your org already
 enforces an Actions policy upstream).
 
-> [!WARNING] If you ever flip the mirror to public, both protections evaporate: CI starts firing on
+<!-- prettier-ignore -->
+> [!WARNING]
+> 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.**
 
@@ -531,6 +555,7 @@ point under your npm prefix's `bin/`), then delete the alias line from your shel
 | `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.                                                                                                                                                                                                              |
 
 The version-check emits ``⚠︎ claude-nomad: <local> -> <latest> (run `nomad update`)`` when the local
@@ -614,8 +639,9 @@ synced, or a `⚠︎` warning naming the counts when something was skipped:
 gitleaks missing when push checks for it, or a rebase conflict before anything is staged) suppresses
 the tree entirely, so you do not see "summary: clean" stacked under an error. A later leak-scan
 finding is different: by then the tree has already been built, so it still renders in full with a
-`✗` Leak scan row and the recovery block below it (see "Recovery flow: gitleaks FATAL on a session
-JSONL"). Projects with no entry in `path-map.json` for this host count as unmapped and fold into the
+`✗` Leak scan row and the recovery block below it (see
+[Recovery flow: gitleaks FATAL on a session JSONL](#recovery-flow-gitleaks-fatal-on-a-session-jsonl)).
+Projects with no entry in `path-map.json` for this host count as unmapped and fold into the
 collapsed `ℹ︎ ... not in path-map` count; the hint points at `nomad doctor`, which lists them by
 logical name.
 
@@ -662,6 +688,13 @@ REQUIRED for durability, not optional housekeeping: `remapPush` (in `src/remap.t
 local content into the staged tree on the next push, so a drop without a local scrub re-stages the
 same secret.
 
+A successful drop prints this reminder inline, pointing at the live transcript that still needs
+scrubbing (the exact path when `path-map.json` maps the project to the current host, a generic
+`~/.claude/projects/<encoded>/<id>.jsonl` template otherwise). This is why a
+`nomad doctor --check-shared` run still reports the session after a drop: that scan reads the live
+`~/.claude/projects/` source, not the staged tree, so it keeps flagging the secret until the local
+transcript is scrubbed.
+
 ### Recovery flow: gitleaks FATAL on a session JSONL
 
 `nomad push` runs `gitleaks protect --staged` before commit. To catch the same findings before you

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-nomad",
-  "version": "0.27.0",
+  "version": "0.28.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-schema.ts

@@ -0,0 +1,72 @@
+import { execFileSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { dim, green, infoGlyph, okGlyph, warnGlyph, yellow } from './color.ts';
+import { addItem, readJsonSafe, type DoctorSection } from './commands.doctor.format.ts';
+import { CLAUDE_HOME, SETTINGS_SCHEMA_URL } from './config.ts';
+
+/**
+ * Opt-in `nomad doctor --check-schema` reporter. Fetches the live Claude Code
+ * settings JSON schema and lists any top-level key in this host's
+ * `~/.claude/settings.json` that the published schema does not define, i.e.
+ * candidates for the hand-maintained `APP_ONLY_KEYS` list. Offline-tolerant by
+ * design (mirrors the release version check): curl missing, a network failure,
+ * or a malformed schema all degrade to a single `⚠︎` skip line. Never sets
+ * `process.exitCode`; this is informational discovery, not a gate.
+ */
+
+/**
+ * Fetch the live settings schema via curl and return its top-level property
+ * names. curl is optional (matches the version check): a missing binary,
+ * non-2xx response, or malformed payload all surface as `null` so the caller
+ * skips cleanly. 3s timeout, fail-fast (`-f`), silent (`-s`), follow redirects.
+ */
+function fetchSchemaKeys(): string[] | null {
+  try {
+    const raw = execFileSync('curl', ['-fsSL', '-m', '3', SETTINGS_SCHEMA_URL], {
+      stdio: ['ignore', 'pipe', 'pipe'],
+    }).toString();
+    const parsed = JSON.parse(raw) as { properties?: Record<string, unknown> };
+    if (typeof parsed.properties !== 'object' || parsed.properties === null) return null;
+    return Object.keys(parsed.properties);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Append the `--check-schema` result to the supplied section: an info line when
+ * there is no local settings.json, a `⚠︎` skip when the schema cannot be
+ * fetched, an OK line when every key is in the schema, or a `⚠︎` line naming the
+ * keys absent from it (APP_ONLY_KEYS candidates).
+ */
+export function reportCheckSchema(section: DoctorSection): void {
+  const settingsPath = join(CLAUDE_HOME, 'settings.json');
+  if (!existsSync(settingsPath)) {
+    addItem(section, `${dim(infoGlyph)} no ~/.claude/settings.json to check`);
+    return;
+  }
+  const settings = readJsonSafe<Record<string, unknown>>(settingsPath, settingsPath, section);
+  if (settings === null) return;
+
+  const liveKeys = fetchSchemaKeys();
+  if (liveKeys === null) {
+    addItem(
+      section,
+      `${yellow(warnGlyph)} schema check skipped (offline, curl missing, or schema unreachable)`,
+    );
+    return;
+  }
+
+  const liveSet = new Set(liveKeys);
+  const candidates = Object.keys(settings).filter((k) => !liveSet.has(k));
+  if (candidates.length === 0) {
+    addItem(section, `${green(okGlyph)} settings.json keys all present in the published schema`);
+  } else {
+    addItem(
+      section,
+      `${yellow(warnGlyph)} settings.json keys absent from published schema (APP_ONLY_KEYS candidates): ${candidates.join(', ')}`,
+    );
+  }
+}

package/src/commands.doctor.ts

@@ -15,6 +15,7 @@ import {
   reportRebaseClean,
   reportRemote,
 } from './commands.doctor.checks.repository.ts';
+import { reportCheckSchema } from './commands.doctor.check-schema.ts';
 import { reportCheckShared } from './commands.doctor.check-shared.ts';
 import { reportNodeEngineCheck } from './commands.doctor.engine.ts';
 import { renderDoctor, section } from './commands.doctor.format.ts';
@@ -35,8 +36,12 @@ import { reportVersionCheck } from './commands.doctor.version.ts';
  * section that runs the gitleaks preflight over the session transcripts a
  * `nomad push` would stage. It is OFF by default so plain `nomad doctor`
  * stays the fast read-only smoke test (no scan, no temp tree).
+ *
+ * `opts.checkSchema` (the `--check-schema` sub-flag) appends a "Schema scan"
+ * section that fetches the live settings schema and flags local settings.json
+ * keys absent from it. Also OFF by default (it needs the network).
  */
-export function cmdDoctor(opts: { checkShared?: boolean } = {}): void {
+export function cmdDoctor(opts: { checkShared?: boolean; checkSchema?: boolean } = {}): void {
   const host = section('Host');
   reportHostAndPaths(host);
   reportRepoState(host);
@@ -74,5 +79,18 @@ export function cmdDoctor(opts: { checkShared?: boolean } = {}): void {
   // drift check above spawns `gitleaks version` separately, by design.)
   if (opts.checkShared === true) reportCheckShared(sharedScan, gitleaksReady);
 
-  renderDoctor([version, host, links, settings, pathMap, neverSync, repository, sharedScan]);
+  const schemaScan = section('Schema scan');
+  if (opts.checkSchema === true) reportCheckSchema(schemaScan);
+
+  renderDoctor([
+    version,
+    host,
+    links,
+    settings,
+    pathMap,
+    neverSync,
+    repository,
+    sharedScan,
+    schemaScan,
+  ]);
 }

package/src/commands.drop-session.scrub-hint.ts

@@ -0,0 +1,72 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { CLAUDE_HOME, HOST, REPO_HOME, type PathMap } from './config.ts';
+import { log } from './utils.ts';
+import { encodePath, readJson } from './utils.json.ts';
+
+/**
+ * Repo-relative session-match shape `shared/projects/<logical>/...`; the single
+ * capture group is the `<logical>` segment fed to the path-map reverse lookup.
+ */
+const SHARED_PROJECT_LOGICAL = /^shared\/projects\/([^/]+)\//;
+
+/**
+ * After a successful drop, remind the operator that the unstage is per-push
+ * only: the leaked secret still lives in the local transcript, so the next
+ * `nomad push` re-copies it (via `remapPush`) and `nomad doctor --check-shared`
+ * keeps reporting it (it scans the live `~/.claude/projects/` source, not the
+ * repo index). Points at the exact live transcript when it resolves for this
+ * host, or a generic `~/.claude/projects/<encoded>/<id>.jsonl` template
+ * otherwise. Advisory output only; never mutates state.
+ *
+ * @param id Already-validated session id.
+ * @param matches Repo-relative paths collected by `collectMatches`.
+ */
+export function reportScrubHint(id: string, matches: string[]): void {
+  const live = resolveLiveTranscript(id, matches);
+  const target = live ?? `~/.claude/projects/<encoded>/${id}.jsonl`;
+  log(
+    'note: this only un-stages the session from the next push. The leaked secret\n' +
+      '  is still in your local transcript, so nomad push re-stages it and nomad\n' +
+      '  doctor --check-shared keeps reporting it. To remediate, rotate the\n' +
+      `  credential, then scrub ${target}`,
+  );
+}
+
+/**
+ * Reverse-map a dropped session to its live transcript
+ * `~/.claude/projects/<encoded>/<id>.jsonl` on THIS host via `path-map.json`
+ * (`<logical>` -> `hosts[HOST]` -> `encodePath`). Best-effort: returns the path
+ * only when it resolves AND exists on disk; null when `path-map.json` is
+ * absent or malformed, no match maps to this host, or the live file is already
+ * gone. A `'TBD'` host placeholder also yields null (its bogus path never
+ * exists). The whole body is wrapped so a malformed map (parse error, `null`
+ * projects) degrades to the generic hint instead of crashing the drop.
+ *
+ * @param id Already-validated session id.
+ * @param matches Repo-relative paths collected by `collectMatches`.
+ * @returns Absolute live transcript path, or null when unresolvable.
+ */
+function resolveLiveTranscript(id: string, matches: string[]): string | null {
+  try {
+    const mapPath = join(REPO_HOME, 'path-map.json');
+    if (!existsSync(mapPath)) return null;
+    const projects = readJson<PathMap>(mapPath).projects;
+    for (const rel of matches) {
+      const logical = SHARED_PROJECT_LOGICAL.exec(rel)?.[1];
+      /* c8 ignore next -- defensive: every collectMatches path is rooted at shared/projects/<logical>/ */
+      if (logical === undefined) continue;
+      const abs = projects[logical]?.[HOST];
+      // A 'TBD' host placeholder needs no special case: encodePath('TBD') yields
+      // a directory that cannot exist among the absolute-path-encoded dirs, so
+      // the existsSync guard below rejects it and falls through to the generic.
+      if (abs === undefined) continue;
+      const live = join(CLAUDE_HOME, 'projects', encodePath(abs), `${id}.jsonl`);
+      if (existsSync(live)) return live;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}

package/src/commands.drop-session.ts

@@ -4,6 +4,7 @@ import { join, relative } from 'node:path';
 
 import { REPO_HOME } from './config.ts';
 import { expandStagedDir, isInIndex, isTrackedInHead } from './commands.drop-session.git.ts';
+import { reportScrubHint } from './commands.drop-session.scrub-hint.ts';
 import { die, fail, log, NomadFatal } from './utils.ts';
 import { acquireLock, releaseLock } from './utils.lockfile.ts';
 
@@ -13,7 +14,9 @@ import { acquireLock, releaseLock } from './utils.lockfile.ts';
  * lock, collects every staged path matching the flat `<id>.jsonl` and the
  * sibling subagent directory `<id>/` (via `collectMatches`), then unstages
  * each (via `unstageOne`). This closes the leak where a "dropped" session
- * still shipped its subagent transcripts.
+ * still shipped its subagent transcripts. A successful drop ends with
+ * `reportScrubHint`, which reminds the operator that the unstage is per-push
+ * only and points at the live transcript that still needs scrubbing.
  *
  * Idempotent: entries not in the index are skipped silently. Exits 0 on
  * any drop (including an idempotent re-run); exits 1 with `✗ no staged
@@ -53,6 +56,7 @@ export function cmdDropSession(id: string): void {
       throw new NomadFatal(`no staged session matches ${id}`);
     }
     for (const rel of matches) unstageOne(rel);
+    reportScrubHint(id, matches);
   } catch (err) {
     // Defensive escape hatch: only fires if a non-NomadFatal error escapes
     // the try block. All execFileSync mutation failures are wrapped in

package/src/config.ts

@@ -36,6 +36,14 @@ export const REPO_HOME = process.env.NOMAD_REPO || resolve(HOME, 'claude-nomad')
  */
 export const UPSTREAM_REPO_SLUG = 'funkadelic/claude-nomad';
 
+/**
+ * The official Claude Code settings JSON schema. Source of truth for
+ * `SCHEMA_KEYS` (kept current by `scripts/sync-settings-keys.ts`) and the
+ * on-demand `nomad doctor --check-schema` reporter, which fetches it live to
+ * flag local `settings.json` keys absent from the published schema.
+ */
+export const SETTINGS_SCHEMA_URL = 'https://json.schemastore.org/claude-code-settings.json';
+
 /**
  * Pinned gitleaks version. Single source of truth for the gitleaks pin used by
  * `nomad doctor`'s version-drift check (`reportGitleaksVersionCheck`), which
@@ -103,48 +111,11 @@ export const NEVER_SYNC = new Set([
   'ide',
 ]);
 
-/**
- * Schema-drift baseline for `~/.claude/settings.json`. Top-level keys not in
- * this set trigger a `nomad doctor` WARN line so we notice when Anthropic
- * adds new settings before they silently round-trip through pull. Update on
- * Anthropic settings.json schema changes.
- */
-export const KNOWN_SETTINGS_KEYS = new Set<string>([
-  '$schema',
-  'agent',
-  'agents',
-  'agentPushNotifEnabled',
-  'allowedHttpHookUrls',
-  'apiKeyHelper',
-  'apiKeyHelperTimeoutMs',
-  'awsAuthRefresh',
-  'awsCredentialExport',
-  'awsLoginRefresh',
-  'awsRegion',
-  'awsRetryMode',
-  'cleanupPeriodDays',
-  'disableNonEssentialModelCalls',
-  'enabledExperimentalFeatures',
-  'enabledPlugins',
-  'env',
-  'forceLoginMethod',
-  'forceLoginOrgUUID',
-  'hooks',
-  'includeCoAuthoredBy',
-  'installMethod',
-  'model',
-  'outputStyle',
-  'permissions',
-  'pluginGroups',
-  'pluginRepositoryEnabled',
-  'pluginsLocalConfig',
-  'proxy',
-  'skipAutoPermissionPrompt',
-  'statsig',
-  'statusLine',
-  'subagents',
-  'theme',
-]);
+// Schema-drift baseline for `~/.claude/settings.json`; top-level keys not in
+// this set trigger a `nomad doctor` WARN. Defined in ./settings-keys.ts so the
+// schema-derived half can be re-synced mechanically; re-exported here so
+// existing `from './config.ts'` imports keep resolving.
+export { KNOWN_SETTINGS_KEYS } from './settings-keys.ts';
 
 /**
  * Static half of the push allow-list. Entries with trailing `/` are prefix

package/src/nomad.help.ts

@@ -49,6 +49,8 @@ export const DEFAULT_HELP = [
   cont('gitleaks, gitlinks).'),
   row('       --check-shared', 'Preflight gitleaks scan of the session transcripts a'),
   cont('`nomad push` would stage (a temp copy, never the live dir).'),
+  row('       --check-schema', 'Flag settings.json keys absent from the live published'),
+  cont('Claude Code settings schema (needs network; degrades offline).'),
   row('       --resume-cmd <id>', 'Print `cd <abspath> && claude --resume <id>` for a session id'),
   cont('from ~/.claude/projects/.'),
   '',

package/src/nomad.ts

@@ -131,13 +131,16 @@ try {
       // Sub-flags: `doctor --resume-cmd <session-id>` dispatches to the
       // read-only sidecar that prints `cd <abspath> && claude --resume <id>`;
       // `doctor --check-shared` (no positional) appends the gitleaks preflight
-      // scan of the transcripts a push would stage. Bare `doctor` runs the
-      // plain read-only health check. Any other shape (unknown flag, extra
-      // positional, `--check-shared` with trailing args) is a usage error.
+      // scan of the transcripts a push would stage; `doctor --check-schema`
+      // (no positional) appends the live settings-schema check. Bare `doctor`
+      // runs the plain read-only health check. Any other shape (unknown flag,
+      // extra positional, a scan flag with trailing args) is a usage error.
       if (process.argv[3] === undefined) {
         cmdDoctor();
       } else if (process.argv[3] === '--check-shared' && process.argv.length === 4) {
         cmdDoctor({ checkShared: true });
+      } else if (process.argv[3] === '--check-schema' && process.argv.length === 4) {
+        cmdDoctor({ checkSchema: true });
       } else if (process.argv[3] === '--resume-cmd') {
         const id = process.argv[4];
         if (process.argv.length !== 5 || typeof id !== 'string' || id.length === 0) {
@@ -146,7 +149,9 @@ try {
         }
         resumeCmd(id);
       } else {
-        console.error('usage: nomad doctor [--check-shared | --resume-cmd <session-id>]');
+        console.error(
+          'usage: nomad doctor [--check-shared | --check-schema | --resume-cmd <session-id>]',
+        );
         process.exit(1);
       }
       break;

package/src/settings-keys.ts

@@ -0,0 +1,124 @@
+/**
+ * Top-level keys recognized in `~/.claude/settings.json`, used by the
+ * `nomad doctor` schema-drift check. Split by provenance so the schema half
+ * can be re-synced mechanically.
+ *
+ * `SCHEMA_KEYS`: the documented properties from the official Claude Code
+ * settings JSON schema (https://json.schemastore.org/claude-code-settings.json).
+ * Regenerated by scripts/sync-settings-keys.mjs (run weekly by the
+ * settings-schema-drift workflow); do not hand-edit this array.
+ *
+ * `APP_ONLY_KEYS`: keys Claude Code writes to settings.json that the published
+ * schema has not caught up to yet (the running app runs ahead of the schema).
+ * These cannot be derived from the schema and are hand-maintained.
+ */
+export const SCHEMA_KEYS = [
+  '$schema',
+  'agent',
+  'allowedChannelPlugins',
+  'allowedHttpHookUrls',
+  'allowedMcpServers',
+  'allowManagedHooksOnly',
+  'allowManagedMcpServersOnly',
+  'allowManagedPermissionRulesOnly',
+  'alwaysThinkingEnabled',
+  'apiKeyHelper',
+  'attribution',
+  'autoMemoryDirectory',
+  'autoMemoryEnabled',
+  'autoMode',
+  'autoUpdatesChannel',
+  'availableModels',
+  'awsAuthRefresh',
+  'awsCredentialExport',
+  'blockedMarketplaces',
+  'channelsEnabled',
+  'claudeMdExcludes',
+  'cleanupPeriodDays',
+  'companyAnnouncements',
+  'defaultShell',
+  'deniedMcpServers',
+  'disableAllHooks',
+  'disableDeepLinkRegistration',
+  'disabledMcpjsonServers',
+  'disableSkillShellExecution',
+  'effortLevel',
+  'enableAllProjectMcpServers',
+  'enabledMcpjsonServers',
+  'enabledPlugins',
+  'env',
+  'extraKnownMarketplaces',
+  'fastMode',
+  'fastModePerSessionOptIn',
+  'feedbackSurveyRate',
+  'fileSuggestion',
+  'forceLoginMethod',
+  'forceLoginOrgUUID',
+  'forceRemoteSettingsRefresh',
+  'hooks',
+  'httpHookAllowedEnvVars',
+  'includeCoAuthoredBy',
+  'includeGitInstructions',
+  'language',
+  'minimumVersion',
+  'model',
+  'modelOverrides',
+  'otelHeadersHelper',
+  'outputStyle',
+  'parentSettingsBehavior',
+  'permissions',
+  'plansDirectory',
+  'pluginConfigs',
+  'pluginTrustMessage',
+  'prefersReducedMotion',
+  'prUrlTemplate',
+  'respectGitignore',
+  'sandbox',
+  'showClearContextOnPlanAccept',
+  'showThinkingSummaries',
+  'showTurnDuration',
+  'skillOverrides',
+  'skipDangerousModePermissionPrompt',
+  'skippedMarketplaces',
+  'skippedPlugins',
+  'skipWebFetchPreflight',
+  'spinnerTipsEnabled',
+  'spinnerTipsOverride',
+  'spinnerVerbs',
+  'statusLine',
+  'strictKnownMarketplaces',
+  'strictPluginOnlyCustomization',
+  'subagentStatusLine',
+  'teammateMode',
+  'terminalProgressBarEnabled',
+  'tui',
+  'useAutoModeDuringPlan',
+  'viewMode',
+  'voiceEnabled',
+  'worktree',
+  'wslInheritsWindowsSettings',
+];
+
+export const APP_ONLY_KEYS = [
+  'agentPushNotifEnabled',
+  'agents',
+  'apiKeyHelperTimeoutMs',
+  'awsLoginRefresh',
+  'awsRegion',
+  'awsRetryMode',
+  'disableNonEssentialModelCalls',
+  'enabledExperimentalFeatures',
+  'inputNeededNotifEnabled',
+  'installMethod',
+  'pluginGroups',
+  'pluginRepositoryEnabled',
+  'pluginsLocalConfig',
+  'proxy',
+  'skipAutoPermissionPrompt',
+  'statsig',
+  'subagents',
+  'theme',
+];
+
+/** Union of schema-documented and app-only settings keys; unknown top-level keys trigger a doctor WARN. */
+export const KNOWN_SETTINGS_KEYS = new Set<string>([...SCHEMA_KEYS, ...APP_ONLY_KEYS]);