diff --git a/.changes/docs-naming/work-resolve-issue-issue-18002-44954440976-1-c691b314.md b/.changes/docs-naming/work-resolve-issue-issue-18002-44954440976-1-c691b314.md new file mode 100644 index 00000000000..0a4b61a59b3 --- /dev/null +++ b/.changes/docs-naming/work-resolve-issue-issue-18002-44954440976-1-c691b314.md @@ -0,0 +1,13 @@ +--- +bump: minor +--- + +### Added + +- **A `file_names` `userConfig` option is the per-person layer** ([#18002](https://github.com/melodic-software/claude-code-plugins/issues/18002)). It holds your own `file_names` keys as one JSON object and takes the place of the user-global `~/.claude/docs-naming.json`, per the config-cascade layers. It merges where that file did: under the team and personal override files, adding to the policy-floor keys and ignored for `generated`. A value that is not one JSON object is reported and ignored, and one holding a whole old file (`{"schema": 1, "file_names": {...}}`) is read as its `file_names` object. Every skill passes the option to its scripts through a new `--user-config` flag, and `scripts/resolve-config.sh` also reads `CLAUDE_PLUGIN_OPTION_FILE_NAMES`. +- **`setup-apply.sh --user-config-value`** previews copying the old user files' keys into the option: per file, the keys it would add, then the merged value and a `values.json` for `claude plugin configure`. It writes nothing. `/docs-naming:setup apply` shows the preview, and on a yes gives the native command that saves it, leaving the old file in place. + +### Changed + +- **`~/.claude/docs-naming.json` and `~/.claude/docs-hygiene.json` are read only while the option is unset or invalid**, the first that exists, in the option's place. Each `resolve` run that finds either file prints one warning naming each file and the option. With a valid option set, neither file is read. A later change removes the read. +- **The resolver names the per-person layer `userConfig`** in `layers` provenance and in each tier's `_layer`, where it said `user-global`. `paths` prints a `userConfig file_names` row (`present`, `absent` or `invalid`), then one row per old user file (`legacy` when read, `legacy-unread` when not). `/docs-naming:setup check` shows a `layer userConfig` row and an `old user file` WARN row per file. diff --git a/docs/contracts/config-cascade/CHANGELOG.md b/docs/contracts/config-cascade/CHANGELOG.md index dc604c20cf0..d7311f3475f 100644 --- a/docs/contracts/config-cascade/CHANGELOG.md +++ b/docs/contracts/config-cascade/CHANGELOG.md @@ -11,6 +11,10 @@ adding an optional layer or relaxing a rule additively is a minor bump. No contract change. +- **The `docs-naming` row reads `userConfig`, not `~/.claude/docs-naming.json`.** Its per-person + layer is the `file_names` option; the old user files are read only while it is unset or invalid, + with a warning, until a later change removes the read. The layering axis is unchanged, so + `contract_version` stays. - **`locations.md` lists where plugin config lives.** One editable page of the four layers, the `.local` naming and the paths outside the contract, pointing at this README's sections. Plugins that teach a config location carry a generated copy at `reference/config-locations.md`. The diff --git a/docs/contracts/config-cascade/README.md b/docs/contracts/config-cascade/README.md index 85e2efd3e8d..7a35416edb2 100644 --- a/docs/contracts/config-cascade/README.md +++ b/docs/contracts/config-cascade/README.md @@ -700,7 +700,7 @@ its conformance cell. | `code-tidying` (`upkeep_*`) | no-floor | team: `/code-tidying.yaml` (schema `plugins/code-tidying/schemas/code-tidying.schema.json`) | team only | team, then the default | per-key | declared deviation: no `userConfig` option and no personal override, since `upkeep_max_open` protects a shared review queue. A value outside the schema, or a file that does not parse, is named with its file and key and resolves to the default. Keys owned by [`plugins/code-tidying/reference/config.md`](../../../plugins/code-tidying/reference/config.md); read through `skills/tidy/scripts/upkeep-setting.sh` by `open-pr-count.sh` and the upkeep gate. `upkeep_spec_issue` has no default: the upkeep gate fails without it | | `code-tidying` (`comment_lint*`) | team-only | team: `/code-tidying.yaml` (schema `plugins/code-tidying/schemas/code-tidying.schema.json`) | team only | team, then the default | per-key | declared deviation: no `userConfig` option and no personal override, since the lint is a shared gate on what a change may add. `comment_lint` defaults to `off` and `comment_lint_allow` to an empty list; a level outside the schema is named with its file and resolves to `off`. The commit-time hook reads the working tree's file; a CI gate reads the merge base's, so a branch cannot lower its own level. Read through `scripts/comment-settings.sh` by the `comment-lint` git-hook entry. This row covers `comment_lint` and `comment_lint_allow` | | `code-tidying` (`verification`) | team-only | team: `/code-tidying.yaml` (`` from the convention-home pointer line at the default branch, default `docs/conventions`; schema `plugins/code-tidying/schemas/code-tidying.schema.json`) | team only | the team file at the default branch; a skill entry over the plugin value; an invalid value resolves `standard`, no value `light` | per-key | conforms to the [location axis](#location-of-the-team-layer-a-docs-convention-file-or-claudename) ([ADR 0064](../../adr/0064-home-plugin-customization-in-docs-conventions-yaml.md)); no `userConfig` option, no `~/.claude` file and no personal override. `verification_skills.` beats `verification`. `lib/read-verification.sh` (the plugin's copy) reads the file at `origin/` after a fetch, never the working tree, so a branch cannot lower its own level, and names a working-tree copy that gives another level. An invalid value or a file that does not parse is named and resolves `standard`; no value resolves `light`. Levels owned by [`docs/contracts/verification-level/README.md`](../verification-level/README.md); read by `/code-tidying:batch-simplify`. This row covers `verification` and `verification_skills` | -| `docs-naming` | team-only | team: `docs/conventions/docs-naming.yaml` (ADR 0064; schema `plugins/docs-naming/schemas/docs-naming.schema.json`); user-global `~/.claude/docs-naming.json`; personal override `docs/conventions/docs-naming.local.yaml` | all three | later layer; team on named policy-floor keys | per-key | conforms. The old team and personal override files, `.claude/docs-naming.json`, `.claude/docs-naming.local.json` and their retired `docs-hygiene` names, are not read; retirement records `docs-naming-r001` and `docs-naming-r002` are `report-only`, `/docs-naming:setup check` names each old file it finds, and while the YAML is absent the first `/docs-naming:setup apply` write copies the old team file's keys into it. The user-global `~/.claude/docs-hygiene.json` is still read, with a WARN, while `~/.claude/docs-naming.json` is absent; per-key override on `file_names.*`, with a policy-floor class on `tiers`, `generated`, `sweep_exclude`, `sweep_exclude_sites`, and the three `exempt_*` keys: a personal layer may add entries and never remove them, and `generated` is team-layer only. Those keys decide what `/docs-naming:realign-file-names` does to a tree (which files are frozen, which reference forms are rewritten, and which shell command runs after a move), so narrowing one from a single machine would weaken a team decision, while adding a scope root or an exemption weakens nothing and stays open. `rule`, `regex`, and `redirect_map` are nearest-wins. Keys owned by [`plugins/docs-naming/reference/config.md`](../../../plugins/docs-naming/reference/config.md), which also partitions them from plugin `userConfig` (this plugin declares none, so a layer naming one is an inert unknown key). Written by `/docs-naming:setup apply`, resolved by `plugins/docs-naming/scripts/resolve-config.sh` | +| `docs-naming` | team-only | team: `docs/conventions/docs-naming.yaml` (ADR 0064; schema `plugins/docs-naming/schemas/docs-naming.schema.json`); `userConfig` option `file_names` (one JSON object of `file_names` keys); personal override `docs/conventions/docs-naming.local.yaml` | all three | later layer; team on named policy-floor keys | per-key | conforms. The old team and personal override files, `.claude/docs-naming.json`, `.claude/docs-naming.local.json` and their retired `docs-hygiene` names, are not read; retirement records `docs-naming-r001` and `docs-naming-r002` are `report-only`, `/docs-naming:setup check` names each old file it finds, and while the YAML is absent the first `/docs-naming:setup apply` write copies the old team file's keys into it. In a dual-read window, while the option is unset or invalid, the old user file `~/.claude/docs-naming.json`, else `~/.claude/docs-hygiene.json`, is read in the option's place; every `resolve` run that finds either file WARNs naming it and the option, and `/docs-naming:setup apply` previews copying its keys into the option, leaving the file in place. Removing that read is a later change; per-key override on `file_names.*`, with a policy-floor class on `tiers`, `generated`, `sweep_exclude`, `sweep_exclude_sites`, and the three `exempt_*` keys: a personal layer may add entries and never remove them, and `generated` is team-layer only. Those keys decide what `/docs-naming:realign-file-names` does to a tree (which files are frozen, which reference forms are rewritten, and which shell command runs after a move), so narrowing one from a single machine would weaken a team decision, while adding a scope root or an exemption weakens nothing and stays open. `rule`, `regex`, and `redirect_map` are nearest-wins. Keys owned by [`plugins/docs-naming/reference/config.md`](../../../plugins/docs-naming/reference/config.md), which also documents the `file_names` option (a key inside it that is not a `file_names` key is inert). Written by `/docs-naming:setup apply`, resolved by `plugins/docs-naming/scripts/resolve-config.sh` | | `rendered-views` | no-floor | team `docs/conventions/rendered-views.yaml`, personal override `docs/conventions/rendered-views.local.yaml`, and each view-lane plugin's `medium` `userConfig` option; the retired `~/.claude/rendered-views.md` and `.claude/rendered-views*.md` give a notice, never a value | `userConfig`, team and personal override | the publish trust walk, not plain precedence: the argument decides alone; a `terminal` or `file` value from any layer keeps the view local; a publishing value counts only from the untracked, gitignored personal override, then `userConfig`; a team file never publishes; with no layer deciding, the lane's own default | per-key | declared deviation from later-layer-wins: `medium` decides whether a view leaves the machine, so a branch-writable layer can keep a view local but never publish it. An invalid value is reported and ignored without dropping another layer's value. Keys owned by [`rendered-views`](../rendered-views/README.md#the-rendered-views-settings). Resolved by `lib/view-settings.mjs`, which reads each layer with `readLayers` | | `testing` (`run-e2e`) | no-floor | `.claude/testing/e2e.md` for `recording` / `browser_mode`; `docs/conventions/testing.yaml`, `~/.claude/testing.yaml` and `.claude/testing.local.yaml` for `e2e_driver` / `reuse_running_instance` / `browser_driver` and the `map` scope's `map_unit` / `map_entry_points` / `map_report_order` / `file_findings` / `file_findings_floor`, over the plugin's `userConfig` | all three | later layer | per-key | conforms; per-key override, keys owned by `/testing:run-e2e`. The YAML keys are resolved by `resolve-config.sh e2e` and `resolve-config.sh map`, which report the supplying layer and resolve an unknown or refused value to the default without stopping | | `testing` (`write`) | no-floor | `docs/conventions/testing.yaml` and `.claude/testing.local.yaml` for `tdd_refactor_step` (`on` \| `off`, default `on`) and `first_test` (`user-flow` \| `unit`, default `user-flow`); no user-global file, no `userConfig` | team + personal override | later layer | per-key | declared deviation: repository settings, so the user-global layer is skipped with a warning. Keys owned by `/testing:write`; resolved by `resolve-config.sh write`, which reports the supplying layer and resolves an unknown value to the default without stopping | diff --git a/plugins/docs-naming/.claude-plugin/plugin.json b/plugins/docs-naming/.claude-plugin/plugin.json index 07d960afc0b..7e655c10d54 100644 --- a/plugins/docs-naming/.claude-plugin/plugin.json +++ b/plugins/docs-naming/.claude-plugin/plugin.json @@ -19,5 +19,13 @@ ], "metadata": { "category": "maintenance" + }, + "userConfig": { + "file_names": { + "type": "string", + "title": "Your file-name settings (JSON)", + "description": "Your file_names keys as one JSON object, the shape of docs/conventions/docs-naming.yaml, e.g. {\"exempt_basenames\":[\"NOTES.md\"]}. Empty (default): none. Repository files win; on policy-floor keys it only adds, and generated is ignored. Invalid JSON is reported and ignored.", + "default": "" + } } } diff --git a/plugins/docs-naming/README.md b/plugins/docs-naming/README.md index d723c58fbd6..c95e2a8ad7f 100644 --- a/plugins/docs-naming/README.md +++ b/plugins/docs-naming/README.md @@ -31,7 +31,8 @@ plugin. ## Configuration -The skills read one consumer surface, layered as user-global, team +The skills read one consumer surface, layered as `userConfig` (the plugin's +`file_names` option, a JSON object of your own `file_names` keys), team (`docs/conventions/docs-naming.yaml`, tracked, validated by [`schemas/docs-naming.schema.json`](schemas/docs-naming.schema.json)), and a gitignored personal override (`docs/conventions/docs-naming.local.yaml`). All @@ -47,9 +48,15 @@ The JSON files under `.claude/` the team layer and personal override used to liv (`docs-naming.json`, `docs-naming.local.json`, and their `docs-hygiene` names) are not read. `/docs-naming:setup check` names each one it finds, and while the team YAML is absent `/docs-naming:setup apply` copies the old team file's keys -into it. A user-global file still at the retired `docs-hygiene` name -(`~/.claude/docs-hygiene.json`) is read, with a warning from the resolver; rename -it to retire the warning. +into it. + +The user-global files `~/.claude/docs-naming.json` and +`~/.claude/docs-hygiene.json` are retired in favor of the `file_names` option. +While the option is unset or invalid, the first of them that exists is still read, and +every run warns about each one. `/docs-naming:setup check` names them, and +`/docs-naming:setup apply` previews copying their keys into the option and gives +the command that saves it. The options reference below says how to set the +option. This plugin still reads, or reports as retired, the `.claude/` paths named here; until the plugin migrates, keep config where this page says it is read, then move it where [config locations](reference/config-locations.md) says. @@ -84,6 +91,41 @@ unverified; the scripts avoid the constructs that differ there (no `${x,,}`, no `sed -i`, existence asked of the git index rather than the filesystem), but no runner covers it. + + +### Options reference + +Generated from this plugin's `.claude-plugin/plugin.json`. For how Claude Code asks for +these and hands them to the plugin, see [User configuration](https://code.claude.com/docs/en/plugins/manifest-reference#user-configuration). + +| Option | Type | Default | Description | +| --- | --- | --- | --- | +| `file_names` | string | *(none)* | Your file_names keys as one JSON object, the shape of docs/conventions/docs-naming.yaml, e.g. {"exempt_basenames":\["NOTES.md"\]}. Empty (default): none. Repository files win; on policy-floor keys it only adds, and generated is ignored. Invalid JSON is reported and ignored. | + +### How to set these + +Set the options above for `docs-naming@`, replacing `` with the +marketplace you installed this plugin from: + +- **In a session or headless:** [`/plugin` in a session](https://code.claude.com/docs/en/plugins/cli-reference#plugin-in-a-session) or + [`claude plugin configure`](https://code.claude.com/docs/en/plugins/cli-reference#plugin-configure). The configure command is the preferred + headless route in the [plugin-reconfiguration convention](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/plugin-reconfiguration/README.md), which records its limits. +- **By hand:** under [`pluginConfigs`](https://code.claude.com/docs/en/settings-reference#pluginconfigs) in your **user** settings. + +Do **not** uninstall the plugin to reconfigure it: see [What an uninstall deletes and keeps](https://code.claude.com/docs/en/plugins/cli-reference#what-an-uninstall-deletes-and-keeps). +For a Claude Code release without `plugin configure`, see [Plugin install](https://code.claude.com/docs/en/plugins/cli-reference#plugin-install). + +### Upstream documentation + +- [User configuration](https://code.claude.com/docs/en/plugins/manifest-reference#user-configuration) +- [Plugin configure](https://code.claude.com/docs/en/plugins/cli-reference#plugin-configure) +- [Plugin install options](https://code.claude.com/docs/en/plugins/cli-reference#plugin-install) +- [Plugins and skills settings](https://code.claude.com/docs/en/settings-reference#plugins-and-skills) +- [Settings files and who they affect](https://code.claude.com/docs/en/settings#settings-files-and-who-they-affect) +- [Manage installed plugins](https://code.claude.com/docs/en/plugins/install#manage-installed-plugins) + + + ## License MIT (SPDX-License-Identifier: MIT). diff --git a/plugins/docs-naming/evals/setup-check-layers-and-retired-team/case.yaml b/plugins/docs-naming/evals/setup-check-layers-and-retired-team/case.yaml index a3b2c30a5f9..ccf9477c6ca 100644 --- a/plugins/docs-naming/evals/setup-check-layers-and-retired-team/case.yaml +++ b/plugins/docs-naming/evals/setup-check-layers-and-retired-team/case.yaml @@ -1,6 +1,6 @@ schema_version: "1.1" name: setup-check-layers-and-retired-team -description: 'Legacy setup 1 and 5, merged on one fixture: an old .claude/docs-hygiene.json team file with a file_names block, and no layer the resolver reads. Refit: setup sets disable-model-invocation, so the legacy natural prompts become the slash command plus their text. The check table is presented with its PASS, WARN and INFO rows and the layer rows intact (setup SKILL.md lines 36-71), docs-naming-r001 is INFO (report-only, lines 82-84), the old file is no longer read, and nothing is written. ran-check is the with-only indicator; layers-and-remedy (llm) quotes the legacy expectations the regexes do not decide. The scaffold puts the old file under the workspace .claude/, where the bundled check reads it in a run. r001-not-fail rejects FAIL stated as r001''s status (a FAIL status cell, ": FAIL", "is FAIL", in any case and through bold or backticks), so a negated FAIL ("not FAIL", "rather than FAIL", "No FAIL rows") passes; no-shell-change guards a shell rewrite, rm or mv of the old file or the team YAML. Needs --scaffold --allow-tools Bash Write Edit.' +description: 'Legacy setup 1 and 5, merged on one fixture: an old .claude/docs-hygiene.json team file with a file_names block, and no layer the resolver reads. Refit: setup sets disable-model-invocation, so the legacy natural prompts become the slash command plus their text. The check table is presented with its PASS, WARN and INFO rows and the layer rows intact (setup SKILL.md lines 44-84), docs-naming-r001 is INFO (report-only, lines 95-99), the old file is no longer read, and nothing is written. ran-check is the with-only indicator; layers-and-remedy (llm) quotes the legacy expectations the regexes do not decide. The scaffold puts the old file under the workspace .claude/, where the bundled check reads it in a run. r001-not-fail rejects FAIL stated as r001''s status (a FAIL status cell, ": FAIL", "is FAIL", in any case and through bold or backticks), so a negated FAIL ("not FAIL", "rather than FAIL", "No FAIL rows") passes; no-shell-change guards a shell rewrite, rm or mv of the old file or the team YAML. Needs --scaffold --allow-tools Bash Write Edit.' tags: [setup, check, scaffold, no-network] plugins: ["../.."] expected_outcome: 'setup-check.sh and the retirement detection run. The reply shows the table as printed, with the three layer rows absent (INFO) explained as valid because the bundled defaults supply the keys, the old team file WARN row, and docs-naming-r001 reported as INFO, not FAIL. It says the old file is no longer read and that setup apply seeds docs/conventions/docs-naming.yaml from it so its settings carry over. No file is written or edited.' @@ -19,7 +19,7 @@ graders: arm: with-only - name: table-rows-intact type: regex - pattern: '^(?=[\s\S]*\bPASS\b)(?=[\s\S]*\bINFO\b)(?=[\s\S]*\bWARN\b)(?=[\s\S]*user-global)(?=[\s\S]*personal[- ]override)' + pattern: '^(?=[\s\S]*\bPASS\b)(?=[\s\S]*\bINFO\b)(?=[\s\S]*\bWARN\b)(?=[\s\S]*userConfig)(?=[\s\S]*personal[- ]override)' target: last_message arm: both - name: r001-info diff --git a/plugins/docs-naming/evals/setup-check-layers-and-retired-team/samples/table-rows-intact.json b/plugins/docs-naming/evals/setup-check-layers-and-retired-team/samples/table-rows-intact.json index 6da6f9a211b..b2fc633e503 100644 --- a/plugins/docs-naming/evals/setup-check-layers-and-retired-team/samples/table-rows-intact.json +++ b/plugins/docs-naming/evals/setup-check-layers-and-retired-team/samples/table-rows-intact.json @@ -1,7 +1,7 @@ { "pass": [ { - "answer": "```text\nPASS jq\nPASS git\nINFO layer user-global absent; the layer below it supplies these keys\nINFO layer team absent\nINFO layer personal-override absent\nWARN old team file .claude/docs-hygiene.json is no longer read\n```" + "answer": "```text\nPASS jq\nPASS git\nINFO layer userConfig the file_names option is unset; the layer below it supplies these keys\nINFO layer team absent\nINFO layer personal-override absent\nWARN old team file .claude/docs-hygiene.json is no longer read\n```" } ], "fail": [ @@ -12,7 +12,7 @@ "answer": "PASS jq, PASS git, INFO team layer absent, WARN old team file." }, { - "answer": "| user-global | INFO |\n| team | INFO |\n| personal-override | INFO |\n| rule | PASS |" + "answer": "| userConfig | INFO |\n| team | INFO |\n| personal-override | INFO |\n| rule | PASS |" } ] } diff --git a/plugins/docs-naming/reference/config.md b/plugins/docs-naming/reference/config.md index 0f6e4feaa0a..b334d771c92 100644 --- a/plugins/docs-naming/reference/config.md +++ b/plugins/docs-naming/reference/config.md @@ -27,9 +27,9 @@ this marketplace's. Three layers, discovered independently and applied over the plugin's bundled defaults: -| Layer | Path | Git | +| Layer | Where | Git | |---|---|---| -| User-global | `docs-naming.json` under `~/.claude/` | the operator's machine | +| `userConfig` | the plugin's `file_names` option: one JSON object of `file_names` keys, e.g. `{"exempt_basenames":["NOTES.md"]}` | none; Claude Code keeps it in the operator's user settings | | Team | `/docs-naming.yaml` | committed, team-shared | | Personal override | `/docs-naming.local.yaml` | gitignored | @@ -37,9 +37,31 @@ defaults: the marked region of `AGENTS.md` (else `CLAUDE.md`) names, `docs/conventions` when there is none. The `layers` and `paths` actions of the resolver report which layer supplied each key and which file each layer was read from, naming the -layers `user-global`, `team` and `personal-override`. The user-global -layer stays a JSON document (`"schema": 1` and a `file_names` object), because -it is a machine-wide file outside any repository. +layers `userConfig`, `team` and `personal-override`. An option value that is not +one JSON object is named on stderr and ignored, so the layers above it and the +bundled defaults still apply. A value holding a whole old user file +(`{"schema": 1, "file_names": {...}}`) is read as its `file_names` object. Set +the option with `/plugin configure docs-naming@`. + +### Old user files + +The user-global file layer is retired: a per-person value goes in the option. +Until a later change removes the read, the old files are still read so no +setting in them is lost: + +- While the option is unset or invalid, `~/.claude/docs-naming.json`, else + `~/.claude/docs-hygiene.json`, is read in the `userConfig` layer's place, as a + JSON document (`"schema": 1` and a `file_names` object). Its values merge + exactly as the option's would: a nearest-wins key applies where the team + layer and personal override set none, and a policy-floor list gains its + entries. +- With a valid option set, the option wins and neither old file is read. +- Every `resolve` run that finds either file prints one warning on stderr + naming each old file and the option to move its keys into. +- `/docs-naming:setup check` shows an `old user file` row for each one, and + `/docs-naming:setup apply` previews the keys it would copy into the option and, + on a yes, gives the native command that saves them. It leaves the old file in + place. The JSON files under `.claude/` the team layer and personal override used to live in (`docs-naming.json`, `docs-naming.local.json`, and their retired `docs-hygiene` @@ -48,11 +70,6 @@ finds. While the team YAML is absent, the first `/docs-naming:setup apply` write copies the old team file's keys into it and leaves that file in place; an old personal override file's keys are moved by hand. -A user-global file absent under `docs-naming.json` but present under the retired -`docs-hygiene` name (`~/.claude/docs-hygiene.json`) is read from there, with a -stderr warning from `resolve` and a WARN row from `/docs-naming:setup check`. The -new name wins when both exist. Rename the file to retire the warning. - This plugin still reads, or reports as retired, the `.claude/` paths named here; until the plugin migrates, keep config where this page says it is read, then move it where [config locations](config-locations.md) says. All three absent is a valid state: every key has a bundled default, and the @@ -60,8 +77,8 @@ defaults are this marketplace's own values, except `generated`, which is empty. the personal override is `/*.local.*`; `/docs-naming:setup check` reports a missing one and never edits a consumer's `.gitignore`. -The user-global JSON layer declares -`"schema": 1`. A layer that omits it, or names a schema this version does not +An old user file declares +`"schema": 1`. One that omits it, or names a schema this version does not implement, stops the run rather than being skipped: a silently ignored layer is a configuration the operator believes is in effect and is not. A YAML layer carries no schema number, and one the YAML-subset parser rejects stops the run @@ -213,8 +230,8 @@ differences are the clock rather than the change. ## What this surface does not cover -- Plugin `userConfig` options. This plugin declares none, and a layer that names - one is an inert unknown key. +- Plugin `userConfig` options other than `file_names`. The plugin declares only + that one, and a key inside it that is not a `file_names` key is inert. - The audit's findings artifact, whose home is defined in `plugins/docs-naming/context/file-name-findings.md`. - Version bumping for a renamed file's consumers. A repository whose plugins, @@ -227,18 +244,28 @@ differences are the clock rather than the change. ## Reading it from a script ```bash -plugins/docs-naming/scripts/resolve-config.sh resolve --root -plugins/docs-naming/scripts/resolve-config.sh layers --root +plugins/docs-naming/scripts/resolve-config.sh resolve --root --user-config '