settings: the four per-feature files .wikitool-remotes/-telemetry/-upload/-tasks.json move into the three tiers and disappear; new command config migrate; 10.0.0-beta.1 (#208)

Files changed: - .gitignore - AGENTS.md - CHANGES.md - INSTALL.md - VERSION - docs/explanation/knowledge-and-commitment.md - docs/explanation/telemetry-and-evaluation.md - docs/explanation/why-gates-are-code.md - docs/how-to/run-the-weekly-review.md - docs/how-to/set-up-the-mcp-server.md - docs/how-to/trace-and-score-sessions.md - docs/how-to/troubleshoot.md - docs/reference/commands/README.md - docs/reference/commands/configuration.md - docs/reference/commands/finding-and-checking.md - docs/reference/commands/git.md - docs/reference/commands/instance-health.md - docs/reference/commands/pages.md - docs/reference/commands/raw-material-and-uploads.md - docs/reference/configuration.md - docs/reference/exit-codes.md - instructions/dev/doc-pull-through.md - instructions/dev/tracker-testing.md - instructions/gates.md - instructions/ingest-queue.md - instructions/mcp-read-server.md - instructions/migrate-corpus.md - instructions/migrations/10.0.0-settings-tiers.md - instructions/setup-instance.md - raw/CONTRACT.md - reports/CONTRACT.md - tools/CONTRACT.md - tools/README.md - tools/bugreport.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/commands/export_cmd.py - tools/chemenu/commands/git_publish.py - tools/chemenu/commands/new_page.py - tools/chemenu/commands/review_cmd.py - tools/chemenu/commands/task_cmd.py - tools/chemenu/commands/upload_cmd.py - tools/chemenu/config.py - tools/chemenu/config_shapes.py - tools/chemenu/legacy_settings.py - tools/chemenu/mcp/__main__.py - tools/chemenu/mcp/server.py - tools/chemenu/reference_doc.py - tools/chemenu/review.py - tools/chemenu/settings.py - tools/chemenu/tasks/__init__.py - tools/chemenu/tasks/caldav.py - tools/chemenu/tasks/config.py - tools/chemenu/tasks/superproductivity.py - tools/chemenu/telemetry/policy.py - tools/chemenu/tests/conftest.py - tools/chemenu/tests/record_sp_fixtures.py - tools/chemenu/tests/test_bugreport.py - tools/chemenu/tests/test_caldav.py - tools/chemenu/tests/test_config_shapes.py - tools/chemenu/tests/test_doctor.py - tools/chemenu/tests/test_git_publish.py - tools/chemenu/tests/test_legacy_settings.py - tools/chemenu/tests/test_mcp_server.py - tools/chemenu/tests/test_new_page.py - tools/chemenu/tests/test_review.py - tools/chemenu/tests/test_settings.py - tools/chemenu/tests/test_sp_recorded.py - tools/chemenu/tests/test_superproductivity.py - tools/chemenu/tests/test_task_cmd.py - tools/chemenu/tests/test_tasks_config.py - tools/chemenu/tests/test_telemetry_policy.py - tools/chemenu/tests/test_tracker_live.py - tools/chemenu/tests/test_upload.py - tools/chemenu/tests/tracker_live.py - tools/chemenu/upload.py Co-Authored-By: Claude Code <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01SnAJ7Z3CpVD3PRbN73QtU2
2026-10-11 06:54:35 +02:00
1 parent e085a8b6c1
commit db8f90c229
@@ -0,0 +1,117 @@
+---
+type: types/instruction.md
+name: 10.0.0-settings-tiers
+description: Move the settings of the four per-feature files .wikitool-telemetry.json, .wikitool-remotes.json, .wikitool-upload.json and .wikitool-tasks.json into the tiered settings with `wikitool config migrate` - run once per checkout; without it the Publish-Remote Gate and the upload limits are not in effect and the commands that need them exit 42.
+manual: true
+migrates_to: 10.0.0
+migration_kind: mechanical
+obligation: required
+---
+# Move the per-feature settings files into the tiered settings (10.0.0)
+
+Until 10.0.0 four features kept their settings in a file of their own at the root of the
+checkout: `.wikitool-telemetry.json`, `.wikitool-remotes.json`, `.wikitool-upload.json` and
+`.wikitool-tasks.json`. 10.0.0 reads none of them. The same settings are now sections of the
+[tiered settings](../../docs/reference/configuration.md#tiered-settings) - `telemetry`,
+`remotes`, `upload`, and `tasks` with `superproductivity` and `caldav` - and each field sits in
+the file its tier names: `wikitool.json` (committed) for what is the same in every clone,
+`.wikitool-local.json` for what is true of one checkout, and for a token or a password the
+secrets file, with only a reference in `wikitool.json`.
+
+A file that is left behind is not read, so the setting it held is **not in effect**: no
+Publish-Remote Gate, no upload limits, no tracker. `wikitool config migrate` moves the content and
+removes the old files. It is `mechanical` because nothing is decided per file: every setting keeps
+its effective value, defaults included.
+
+<!-- wikitool:toc -->
+## Contents
+
+- [When to run](#when-to-run)
+- [Steps](#steps)
+- [How to tell a migrated checkout from an unmigrated one](#how-to-tell-a-migrated-checkout-from-an-unmigrated-one)
+- [Decision points](#decision-points)
+- [Scope](#scope)
+<!-- /wikitool:toc -->
+
+## When to run
+
+After installing 10.0.0 machinery over an instance on 9.x - step 12 of
+[upgrade-instance.md](../upgrade-instance.md), once `tools/wikitool migrate status` names this
+document - **in every checkout of the instance that has one of the four files**. The files are
+per checkout and gitignored, so another clone does not see them and runs the step for itself.
+Until it has run, `tools/wikitool doctor` reports each leftover as a `FAIL`, and `publish`
+(with a `.wikitool-remotes.json`), `task`, `review` and `new project` (with a
+`.wikitool-tasks.json`) and the MCP server (with a `.wikitool-upload.json`) exit 42 and name the
+command below.
+
+## Steps
+
+1. **See what is there:**
+
+   ```bash
+   tools/wikitool doctor
+   ```
+
+   Each old file that is still present is one `legacy-settings` line. None, and the checkout has
+   nothing to move: go to step 4.
+
+2. **Move it:**
+
+   ```bash
+   tools/wikitool config migrate
+   ```
+
+   It prints, per setting, which file the value went to - never the value. A secret's value goes
+   into the secrets file in the user's configuration directory, and only a reference into
+   `wikitool.json`. It writes the new files first, reads them back and checks them, and only then
+   removes the old ones; if anything fails, nothing is changed and the old files are as they were.
+   A second run says there is nothing to move.
+
+3. **Check it:**
+
+   ```bash
+   tools/wikitool doctor
+   git status --short
+   ```
+
+   `doctor` shows no `legacy-settings` line, and the settings lines are `OK`. `git status` shows
+   `wikitool.json` as new or changed: it holds the instance-tier values and the references, and it
+   is committed with the next `publish`. `.wikitool-local.json` does not appear, being ignored.
+
+4. **Record it, once per instance** - not once per checkout:
+
+   ```bash
+   tools/wikitool migrate done 10.0.0 --pages 0
+   ```
+
+   `--pages 0` because no `kb/` page changes. The migration is `required`, so this advances
+   `kb_version`.
+
+## How to tell a migrated checkout from an unmigrated one
+
+An unmigrated checkout has at least one of the four files at its root, and `doctor` names each.
+A migrated one has none; `.wikitool-tools.json` is not among them and stays.
+
+## Decision points
+
+- **`config migrate` stops: a key already holds a different value?** The target files already
+  have the key, set by hand or by `config set`, and the old file says something else. It cannot
+  know which one stands. Decide, remove the other from its file, and run it again.
+- **A value was read before but only coerced** - a number written as a string, say? It is
+  carried over as the number it was read as. Anything an old file held that was never read (an
+  unknown key, the section of a provider that is not chosen) is named in the output and not
+  carried over.
+- **The old Publish-Remote allowlist or upload limits go where?** Into `.wikitool-local.json`:
+  both affect a gate, so `config set` does not write them, and the migration is the one command
+  that does. Later changes to them are the user's own edit.
+- **A profile file `WIKITOOL_TASKS_CONFIG` points at still holds a plain token?** It is not
+  touched by `config migrate`, and it is no longer read as the old format: a profile has the layout of
+  `.wikitool-local.json` and holds references only
+  ([Profiles](../../docs/reference/configuration.md#profiles)). Rewrite it by hand, with the
+  value in `WIKITOOL_SECRET_<NAME>` or the secrets file.
+
+## Scope
+
+The four files named above, in the checkout the command runs in. `.wikitool-tools.json` and the
+two tiered settings files are not old files. The machinery - the readers, `config migrate`,
+`doctor`'s check - arrived with `dist upgrade` and needs nothing from this document.