torbenandClaude Code
cceb9a7bfe
Files changed: - .gitignore - CHANGES.md - VERSION - docs/explanation/architecture.md - docs/explanation/pipeline-rationale.md - docs/how-to/README.md - docs/how-to/back-up-to-a-synced-folder.md - docs/how-to/collect-from-a-synced-folder.md - docs/how-to/ingest-a-source.md - docs/how-to/set-up-the-mcp-server.md - docs/reference/commands/README.md - docs/reference/commands/git.md - docs/reference/commands/instance-health.md - docs/reference/commands/raw-material-and-uploads.md - docs/reference/configuration.md - instructions/gates.md - instructions/ingest-queue.md - instructions/mcp-read-server.md - instructions/migrations/10.0.0-settings-tiers.md - instructions/wiki-ingest/SKILL.md - raw/CONTRACT.md - tools/CONTRACT.md - tools/README.md - tools/chemenu/cli_contract.py - tools/chemenu/collect.py - tools/chemenu/commands/backup_cmd.py - tools/chemenu/commands/docs_verify.py - tools/chemenu/commands/doctor.py - tools/chemenu/commands/raw/pending.py - tools/chemenu/commands/upload_cmd.py - tools/chemenu/config.py - tools/chemenu/config_shapes.py - tools/chemenu/legacy_settings.py - tools/chemenu/mcp/server.py - tools/chemenu/reference_doc.py - tools/chemenu/tests/test_backup.py - tools/chemenu/tests/test_collect.py - tools/chemenu/tests/test_config_shapes.py - tools/chemenu/tests/test_doctor.py - tools/chemenu/tests/test_legacy_settings.py - tools/chemenu/tests/test_mcp_server.py - tools/chemenu/tests/test_upload.py - tools/chemenu/tests/test_upload_cmd.py - tools/chemenu/upload.py Co-Authored-By: Claude Code <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01SnAJ7Z3CpVD3PRbN73QtU2
144 lines
7.1 KiB
Markdown
144 lines
7.1 KiB
Markdown
---
|
|
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`, 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.
|
|
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`, `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.
|
|
|
|
<!-- 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, 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:**
|
|
|
|
```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. **Move the quarantine, if `mcp-upload/` still holds submissions.** In the instance root:
|
|
|
|
```bash
|
|
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:**
|
|
|
|
```bash
|
|
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:
|
|
|
|
```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, 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](../../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 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.
|