chemenu/instructions/migrations/10.0.0-settings-tiers.md

type, name, description, manual, migrates_to, migration_kind, obligation

type	name	description	manual	migrates_to	migration_kind	obligation
types/instruction.md	10.0.0-settings-tiers	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.	true	10.0.0	mechanical	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 - 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.

Contents

• When to run
• Steps
• How to tell a migrated checkout from an unmigrated one
• Decision points
• Scope

When to run

After installing 10.0.0 machinery over an instance on 9.x - step 12 of 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:

   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:

   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:

   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:

   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). 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.