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`, and move the quarantine mcp-upload/ to quarantine/ - 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, intake (the old upload file becomes its channel mcp), 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.

10.0.0 also renames the quarantine of the intake channels from mcp-upload/ to quarantine/, because it no longer holds only what the MCP submit tool received. A checkout whose mcp-upload/ still holds submissions that wait for review moves that directory once, by hand - nothing moves it automatically, since material that waits for a decision is not the tool's to relocate. Until it is moved, doctor reports a FAIL on upload-intake with the command, the upload commands exit 1 naming it, and the MCP server does not start.

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, and an mcp-upload/ that still holds submissions is a FAIL on the upload-intake line. Neither, and the checkout has nothing to move: go to step 5.

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. Move the quarantine, if mcp-upload/ still holds submissions. In the instance root:

   mv mcp-upload quarantine              # POSIX shells
   Move-Item mcp-upload quarantine       # PowerShell
   

   If quarantine/ exists already (the new version created it), move the entries of mcp-upload/ into it one by one - each is a directory named by its id, plus ledger.jsonl, which is appended to the existing ledger rather than replacing it - and remove the empty mcp-upload/ afterwards. Open submissions keep their ids and are listed by upload list again. The root .gitignore of an instance carries /quarantine/ from this version on; dist upgrade brings the entry, and the quarantine writes its own .gitignore as well.

4. Check it:

   tools/wikitool doctor
   git status --short
   

   doctor shows no legacy-settings line, the upload-intake line is not a FAIL, 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.

5. 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, or an mcp-upload/ that still holds submissions; 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. The upload limits become the channel mcp of the intake section. 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 and the mcp-upload/ directory, 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.