# description
Shape of `.skill-map/settings.json` (and its `.skill-map/settings.local.json` partner) inside a scope. Loaded by the layered config hierarchy (library defaults → user → user-local → project → project-local → env/flags) and deep-merged per key. All fields optional; defaults apply when absent. camelCase keys throughout — consistent with the rest of the spec.

# properties.schemaVersion.description
Config file shape version. Bumped on breaking changes to this schema.

# properties.autoMigrate.description
Apply pending kernel and plugin migrations automatically at startup, after auto-backing-up the DB. Default true. When false, startup fails with exit 2 if migrations are pending; the user runs `sm db migrate` manually.

# properties.tokenizer.description
Name of the offline tokenizer used to compute per-node token counts during scan. Default `cl100k_base`. Stored alongside each token count in `scan_nodes` so consumers know which encoder produced the numbers. Changing this invalidates prior counts on next scan.

# properties.providers.description
Provider ids to enable, in priority order when multiple match. Empty/absent = use all registered.

# properties.roots.description
Directories (relative to the config file) to scan. Defaults to the scope root.

# properties.ignore.description
Glob patterns to exclude, in addition to `.skill-mapignore`.

# properties.scan.properties.tokenize.description
Whether to compute token counts. Default true.

# properties.scan.properties.strict.description
Promote frontmatter warnings to errors. Default false.

# properties.scan.properties.maxFileSizeBytes.description
Files larger than this are skipped with an `info`-level log entry. Default 1048576 (1 MiB). Protects against scanning accidental binary drops or generated artefacts.

# properties.scan.properties.watch.description
File-watcher knobs for `sm watch` and `sm scan --watch`. The watcher subscribes to the same roots `sm scan` walks, applies the `.skill-mapignore` filter, and triggers an incremental scan after each batch.

# properties.scan.properties.watch.properties.debounceMs.description
Milliseconds to wait after the last filesystem event before triggering an incremental scan. Groups bursts (editor saves, branch switches, package installs) into a single scan pass. Default 300. Set to 0 to disable debouncing — every filesystem event triggers a scan immediately.

# properties.plugins.description
Per-plugin enable/disable overrides. Keys are plugin ids. Absent = use installed default (enabled).

# properties.plugins.additionalProperties.properties.config.description
Plugin-specific config passed to extensions at load time. Shape defined by the plugin.

# properties.history.properties.share.description
When true, `./.skill-map/skill-map.db` is expected to be committed — teams remove it from `.gitignore` so the execution log becomes a shared artefact. Stability: experimental. Default false.

# properties.jobs.properties.ttlSeconds.description
Global fallback TTL (seconds) used when an action manifest omits `expectedDurationSeconds` — typically `mode: local` actions where the field is advisory. Default 3600. The submit-time resolution still applies `graceMultiplier` and `minimumTtlSeconds`.

# properties.jobs.properties.graceMultiplier.description
Default grace multiplier applied to `expectedDurationSeconds`. Default 3.

# properties.jobs.properties.perActionTtl.description
Per-action TTL overrides (seconds). Keys are action ids.

# properties.jobs.properties.perActionPriority.description
Per-action priority overrides. Keys are action ids, values are integers (higher runs first, negatives allowed). Frozen on `state_jobs.priority` at submit time. Overrides `defaultPriority` from the action manifest; `--priority` on `sm job submit` overrides both.

# properties.jobs.properties.retention.description
Garbage-collection policy for `state_jobs` rows and their job files. `sm job prune` reads this; no implicit pruning during normal verbs.

# properties.jobs.properties.retention.properties.completed.description
Seconds after `finishedAt` before a `completed` job is eligible for pruning. `null` = never auto-prune. Default 2592000 (30 days).

# properties.jobs.properties.retention.properties.failed.description
Seconds after `finishedAt` before a `failed` job is eligible for pruning. `null` = never auto-prune. Default `null` — failed jobs are kept for post-mortem.