settings: three tiers - wikitool.json (instance), .wikitool-local.json (checkout), secrets by reference incl. 1Password CLI; new command config set (#207)

Every settings field declares its tier; a value in the wrong file is an error naming
file, key and tier. A field naming a program or affecting a gate cannot be declared
instance. Secrets are references only: {"ref": "<name>"} via WIKITOOL_SECRET_<NAME> or
a user-only secrets file, {"ref": "op://..."} via op read (locked 1Password: exit 42).
The preflight records op as an optional tool. doctor gains one line per tier, docs
verify checks a committed wikitool.json for plaintext secrets, CI resolves a real
op:// value through 1password/load-secrets-action. No feature reads its settings
this way yet; without the two files every other command is unchanged.

Files changed:
- .gitea/workflows/ci.yml
- .gitignore
- AGENTS.md
- CHANGES.md
- INSTALL.md
- VERSION
- docs/explanation/README.md
- docs/explanation/configuration-tiers.md
- docs/how-to/README.md
- docs/how-to/use-1password-for-settings.md
- docs/reference/commands/README.md
- docs/reference/commands/configuration.md
- docs/reference/commands/instance-health.md
- docs/reference/commands/types-instructions-and-docs.md
- docs/reference/configuration.md
- docs/reference/exit-codes.md
- instructions/dev/doc-pull-through.md
- instructions/dev/testing-conventions.md
- instructions/preflight.md
- tools/CONTRACT.md
- tools/README.md
- tools/chemenu/cli.py
- tools/chemenu/cli_contract.py
- tools/chemenu/commands/_util.py
- tools/chemenu/commands/config_cmd.py
- tools/chemenu/commands/docs_verify.py
- tools/chemenu/commands/doctor.py
- tools/chemenu/config.py
- tools/chemenu/config_shapes.py
- tools/chemenu/prerequisites.py
- tools/chemenu/settings.py
- tools/chemenu/tests/conftest.py
- tools/chemenu/tests/test_dist_cmd.py
- tools/chemenu/tests/test_preflight.py
- tools/chemenu/tests/test_preflight_pwsh.py
- tools/chemenu/tests/test_settings.py
- tools/chemenu/toolpaths.py
- tools/preflight.ps1
- tools/preflight.sh
- tools/prerequisites.txt

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SnAJ7Z3CpVD3PRbN73QtU2

docs/reference/configuration.md

@@ -1,7 +1,7 @@
 # Configuration
 
-The environment variables `wikitool` reads, and the per-checkout files an operator may create at the
-root of an instance. None of them is needed for an instance to work: an instance installed from a
+The environment variables `wikitool` reads, the per-checkout files an operator may create at the
+root of an instance, and the two tiered settings files. None of them is needed for an instance to work: an instance installed from a
 release runs against the origin's public release feed with no configuration at all.
 
 The shape of each file - its fields, what an absent or a malformed file means, an example - is
@@ -24,6 +24,7 @@ something you run.
   - [Super Productivity](#super-productivity)
   - [CalDAV](#caldav)
 - [MCP submissions](#mcp-submissions)
+- [Tiered settings](#tiered-settings)
 <!-- /wikitool:toc -->
 
 ## Environment variables
@@ -35,6 +36,7 @@ something you run.
 | `WIKITOOL_UPDATE_URL` | The release feed `version check`, `version notes` and `dist upgrade --latest` ask | The value in `.wikitool-release.json`, else the origin's feed |
 | `WIKITOOL_UPDATE_TOKEN` | A Gitea token for the release feed, sent only to downloads on the feed's own host | None. Not needed against the origin, only against a feed in a private repository |
 | `WIKITOOL_TASKS_CONFIG` | Path to a tracker configuration that `task`, `review` and `doctor` read instead of `.wikitool-tasks.json`, for running one checkout against several trackers in turn | `.wikitool-tasks.json` at the root. A path to a file that does not exist is an error, never "no tracker configured" |
+| `WIKITOOL_SECRET_<NAME>` | The value behind a settings reference `{"ref": "<name>"}`, for CI and containers - `<NAME>` is the name upper-cased | The secrets file in the user's configuration directory ([below](#tiered-settings)) |
 | `CHEMENU_ROOT` | Which corpus the package works on, for a caller outside the checkout itself | The checkout the package sits in. `tools/wikitool` behaves the same without it |
 | `WIKI_TRACE` | `0`/`1` turns telemetry off or on, beating both the default and `.wikitool-telemetry.json` | The installation-form default ([below](#telemetry)) |
 | `WIKI_TRACE_DIR` | Writes traces somewhere other than `reports/telemetry/` | `reports/telemetry/` |
@@ -84,7 +86,10 @@ both caps. What the caps do and what never reaches a trace:
 ## Tool paths
 
 **The preflight writes this file, not you.** `.wikitool-tools.json` at the root holds the absolute
-paths of Python, git and ripgrep, as the preflight found them on this machine. `wikitool` starts git
+paths of Python, git and ripgrep, as the preflight found them on this machine - and of the
+1Password CLI `op` when it is installed. `op` is optional: the preflight records it when it finds
+it, reports `ABSENT` when it does not, and never asks for it. Only an `op://` reference in the
+[tiered settings](#tiered-settings) needs it. `wikitool` starts git
 and rg from there instead of from `PATH`. It is per checkout and gitignored, because a path on one
 machine says nothing about the next.
 
@@ -330,3 +335,61 @@ Example:
 <!-- /wikitool:reference-config-upload -->
 
 Size and quota are your deployment's decision, not defaults worth copying blindly.
+
+## Tiered settings
+
+Two files at the root hold the settings of the features that read them this way, and every field
+declares the tier it belongs to:
+
+| Tier | File | Holds |
+|------|------|-------|
+| `instance` | `wikitool.json`, committed | What belongs to the corpus and is the same in every clone |
+| `checkout` | `.wikitool-local.json`, gitignored | What is true only for this clone on this machine |
+| `secret` | neither | Tokens and passwords - both files hold only a reference |
+
+Each file is a JSON object of sections, one per feature, beside two keys of its own:
+
+```json
+{
+  "schema": 1,
+  "instance_id": "6f1c0e52-3d1b-4b8e-9a51-2f0e7d1c9b44",
+  "<section>": {"<field>": "<value>"}
+}
+```
+
+`instance_id` sits in `wikitool.json` only. The first `wikitool config set` creates the file and
+the id; the id names the directory of the secrets file below. No feature reads its settings this
+way yet, so this version declares no section: `config set` names the sections it knows, and
+`doctor` reports a section it does not read as a `WARN`.
+
+**One place per value.** A value in the file its tier does not name is an error naming the file,
+the key and the right tier - never an override. The same holds for a key set in both files.
+
+**References.** A field of tier `secret` takes only a reference; a field marked private - a host
+name, an internal URL - takes a plain value in `.wikitool-local.json` or a reference in either
+file. No other field takes one.
+
+| Reference | Resolves through |
+|-----------|------------------|
+| `{"ref": "<name>"}` - lower-case letters, digits and single `_` | `WIKITOOL_SECRET_<NAME>`, else the key `<name>` in the secrets file |
+| `{"ref": "op://<vault>/<item>/<field>"}` | `op read`, the 1Password CLI the preflight recorded |
+
+The secrets file is `~/.config/chemenu/<instance_id>/secrets.json` (`$XDG_CONFIG_HOME` instead of
+`~/.config` when it is set; `%APPDATA%\chemenu\<instance_id>\secrets.json` on Windows), a JSON object of
+names to strings. Outside Windows it must be readable by its owner only (`chmod 600`); a file
+others can read is refused.
+
+A reference is resolved when a command asks for that value, never when the files are read. A name
+nobody provides, an `op` that is not installed, or an item 1Password does not have ends the command
+with exit 1; a 1Password that is locked, signed out or waiting for an approval ends it with exit 42,
+for a human to unlock. Setting 1Password up: [use-1password-for-settings.md](../how-to/use-1password-for-settings.md).
+
+**Never in the committed file:** a field that names a program to run or affects a gate - not even
+as a reference. `config set` does not write such a field either; the user edits
+`.wikitool-local.json` by hand, and `doctor` checks it afterwards.
+
+`wikitool doctor` reports one line per tier - `settings-instance`, `settings-checkout`,
+`settings-secrets` - and for the references only whether they resolve. `docs verify` holds a
+committed `wikitool.json` to the placement rules above, a plain secret or private value above
+all. Neither file ships with `dist export`. Why the tiers exist, and what keeping secrets out of
+the tree does not protect against: [configuration-tiers.md](../explanation/configuration-tiers.md).