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