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
@@ -40,7 +40,7 @@ touched; a row that does not apply needs no action.
   | The reasoning behind a gate, boundary, or design decision | The `docs/explanation/` page that carries it, if one exists (AGENTS.md § File naming lists all seven reached from AGENTS.md itself, plus an eighth reached only from CLAUDE.md). **A decision with no page yet is the gap worth closing**: reasoning that lives only in a Gitea issue never ships - `dist export` carries `docs/explanation/` and no issue tracker, so a distributed instance gets the mechanism without the why |
   | A task-tracker adapter (`tools/chemenu/tasks/`), its recorded fixtures, or the live suite | [instructions/dev/tracker-testing.md](tracker-testing.md), and `MANIFEST.json` beside the fixtures when they were re-recorded |
   | A skill's own step sequence or catalogue | The skill's `SKILL.md` source under `instructions/<name>/` or `instructions/dev/<name>/`; for a shipped skill (not under `instructions/dev/`) whose name or `description` changed, or one added or removed, `wikitool docs reference --apply` for the skill catalogue `docs/reference/skills.md` |
-   | A per-checkout configuration file an instance owns (`.wikitool-tasks.json`, `.wikitool-telemetry.json`, `.wikitool-remotes.json`, `.wikitool-upload.json`), or a section of the tiered settings (`wikitool.json`, `.wikitool-local.json`; `config_shapes.SETTINGS_SECTIONS`) | Its shape - a field, a default, what is required or tolerated - is its record in `tools/chemenu/config_shapes.py`, which the loader reads; change it there, then `wikitool docs reference --apply` for its region in [docs/reference/configuration.md](../../docs/reference/configuration.md). What a setting *does* is the hand-written prose around that region. Also the [setup-instance.md](../setup-instance.md) decision point that offers the file during setup, and `doctor`'s own row in [tools/CONTRACT.md](../../tools/CONTRACT.md), since `doctor` is what reports the file's state |
+   | A section of the tiered settings (`wikitool.json`, `.wikitool-local.json`; `config_shapes.SETTINGS_SECTIONS`) | Its shape - a field, a default, what is required or tolerated - is its record in `tools/chemenu/config_shapes.py`, which the loader reads; change it there, then `wikitool docs reference --apply` for its region in [docs/reference/configuration.md](../../docs/reference/configuration.md). What a setting *does* is the hand-written prose around that region. Also the [setup-instance.md](../setup-instance.md) decision point that offers the section during setup, and `doctor`'s own row in [tools/CONTRACT.md](../../tools/CONTRACT.md), since `doctor` is what reports the section's state |
   | An installation instruction - [preflight.md](../preflight.md), [setup-instance.md](../setup-instance.md), [bootstrap.md](../bootstrap.md), [upgrade-instance.md](../upgrade-instance.md) - or `tools/prerequisites.txt` | [INSTALL.md](../../INSTALL.md), the human guide to the same procedure - for `upgrade-instance.md`, [docs/how-to/update-an-instance.md](../../docs/how-to/update-an-instance.md) instead. Read it against the instruction: what to prepare, the sentence for the agent, what the agent asks, where it stops and why. `docs verify` checks only the two enumerable overlaps - the prerequisites lists, which `wikitool docs prerequisites --apply` regenerates from the manifest, and the setup questions: a question the agent asks the user carries `<!-- setup-question: <key> -->` where it is asked in `setup-instance.md`, and `INSTALL.md` § "What the agent asks you" names it with the same marker. Every other sentence is this session's to compare. `INSTALL.md` does not retell the steps, so a change to their order or wording alone moves nothing there |
   | [dev-setup.md](dev-setup.md), the release workflow (`version bump`/`version release`/`publish`/CI), or another developer-facing process | [docs/dev/development.md](../../docs/dev/development.md), read against it the same way - nothing checks this pair at all. A page under `docs/dev/` is never shipped, so it may link into `instructions/dev/` and cite issue numbers |
   | A new page type the stack requires, or a new collection | Its type-spec and `COLLECTION.md` (both as the `.template` an instance adopts), the collection table in [kb/CONTRACT.md](../../kb/CONTRACT.md), and **both adoption paths**: [setup-instance.md](../setup-instance.md) for a fresh instance and [upgrade-instance.md](../upgrade-instance.md) for an existing one, where an unadopted template is what `docs verify` refuses. A new or changed `root: kb` type-spec or its schema - description, `layout:`, subtype enum, required fields - also needs `wikitool docs reference --apply` for `docs/reference/page-types.md` |
@@ -36,15 +36,15 @@ plain `pytest` run unless you set it.
 |---|---|---|
 | `CHEMENU_LIVE_SP_BINARY` | The packaged Super Productivity (`.deb` layout). The suite starts its own headless copy on a fresh profile, seeded from `fixtures/sp/seed-backup.json`, and stops it again. | The suite |
 | `CHEMENU_LIVE_CALDAV_URL`, `_USER`, `_PASSWORD` (optional `_VERSION` for the report line) | A CalDAV collection. In CI it is a throwaway Radicale started by `.gitea/scripts/start-radicale.sh`. | The suite - it may create the marker calendar |
-| `CHEMENU_LIVE_PROFILE=<name>` | A tracker of your own, described by `.wikitool-tasks.d/<name>.json` in the checkout, used exactly as configured. | You - the suite never creates anything but items |
+| `CHEMENU_LIVE_PROFILE=<name>` | A tracker of your own, described by a profile `.wikitool-tasks.d/<name>.json` in the checkout, used exactly as configured. | You - the suite never creates anything but items |

 `CHEMENU_LIVE_REQUIRE=sp,caldav,profile` (any subset) turns "no such tracker configured" into
 a failure instead of a skip. CI sets it; without it a workflow that lost its server would go
 green by skipping, which is the outcome the suite exists to rule out.

-The commands under test read their configuration from `.wikitool-tasks.json`, or from the file
-`WIKITOOL_TASKS_CONFIG` names when that variable is set. The live suite sets the variable per
-test, so it never touches the checkout's own `.wikitool-tasks.json`; you can use the same
+The commands under test read the `tasks`, `superproductivity` and `caldav` sections of the
+settings, or those of the profile `WIKITOOL_TASKS_CONFIG` names when that variable is set. The
+live suite sets the variable per test, so it never touches the checkout's own settings; you can use the same
 variable to run `task` and `review` by hand against a second tracker.

 ## What the suite writes, and what it never does
@@ -72,19 +72,23 @@ that fails against theirs. The steps differ per tracker only in the profile and

 1. **Create the marker project in that tracker**, by hand, named exactly `Chemenu Live-Test`.
   Nothing else in the tracker is touched, but this project's items are created and closed.
-2. **Write the profile** to `.wikitool-tasks.d/<name>.json` (gitignored - it holds
-   credentials). It is a normal `.wikitool-tasks.json` plus one optional key,
-   `live_test_version`, which is stripped before use and only names the tracker's version in
-   the report line. Paths are absolute.
+2. **Write the profile** to `.wikitool-tasks.d/<name>.json` (gitignored). It is in the format of
+   `.wikitool-local.json`, holds only the sections `tasks`, `superproductivity` and `caldav`, and
+   takes one optional key, `live_test_version`, which is stripped before use and only names the
+   tracker's version in the report line. Paths are absolute. **A secret in a profile is a
+   reference, never a value** - `{"ref": "<name>"}` - so the file holds no credential. Put the
+   value where the reference resolves: the environment variable `WIKITOOL_SECRET_<NAME>` (name in
+   capitals) for a run, or 1Password / the secrets file for a standing profile
+   ([configuration reference](../../docs/reference/configuration.md#profiles)). The user does
+   that; a value never goes through the chat or onto a command line.

   Super Productivity, API access (the app must be running with the Local REST API on):

   ```json
   {
     "schema": 1,
-     "provider": "superproductivity",
-     "thresholds": {"stalled_waiting_days": 14, "unpaged_project_weeks": 3, "someday_stale_months": 5},
-     "superproductivity": {"access": "api", "api_base_url": "http://127.0.0.1:3876", "api_token": "<token>"},
+     "tasks": {"provider": "superproductivity", "stalled_waiting_days": 14, "unpaged_project_weeks": 3, "someday_stale_months": 5},
+     "superproductivity": {"access": "api", "api_base_url": "http://127.0.0.1:3876", "api_token": {"ref": "live_sp_token"}},
     "live_test_version": "19.1.0"
   }
   ```
@@ -94,9 +98,8 @@ that fails against theirs. The steps differ per tracker only in the profile and
   ```json
   {
     "schema": 1,
-     "provider": "caldav",
-     "thresholds": {"stalled_waiting_days": 14, "unpaged_project_weeks": 3, "someday_stale_months": 5},
-     "caldav": {"url": "https://<server>/<user>/", "username": "<user>", "app_password": "<password>",
+     "tasks": {"provider": "caldav", "stalled_waiting_days": 14, "unpaged_project_weeks": 3, "someday_stale_months": 5},
+     "caldav": {"url": "https://<server>/<user>/", "username": "<user>", "app_password": {"ref": "live_caldav_password"},
                "inbox_list": "Inbox", "someday_list": "Someday"},
     "live_test_version": "<server and version>"
   }
@@ -86,29 +86,30 @@ puts a private corpus on a public repository. That is not cheaply reversible: a
 the branch, but the objects stay fetchable by SHA until someone expires the server's reflogs and
 runs `git gc --prune=now` on the bare repo.

-`.wikitool-remotes.json` names the push URLs a checkout permits:
+The `remotes` section of `.wikitool-local.json` names the push URLs a checkout permits:

 ```json
-{ "schema": 1, "allowed_push_urls": ["ssh://git@example.net:22/you/your-wiki.git"] }
+{ "schema": 1, "remotes": { "allowed_push_urls": ["ssh://git@example.net:22/you/your-wiki.git"] } }
 ```

 It pins **URLs, not remote names** - a name-based list would wave through a `publish` whose
 `origin` had been repointed, which is the failure it exists to catch. It reads the remote's
 `pushurl` when one is set, because that is where `git push` actually writes.

-The file is per-checkout and gitignored, for the same reason `ENVIRONMENT.md` is: two clones push
+The list lives in the per-checkout settings file, which is gitignored, for the same reason `ENVIRONMENT.md` is: two clones push
 to two different places, so a committed copy would tell a private clone that a public remote is a
 legitimate target for its own content. **Absent means unrestricted** - a single-remote
 checkout with nothing private in it has nothing to protect, and `doctor` reports which state a
 checkout is in, WARNing only when there is more than one remote and no allowlist. A malformed
-file is an error rather than "no restriction": a corrupted safeguard must not read as a disabled
+section is an error rather than "no restriction": a corrupted safeguard must not read as a disabled
 one.

 **This gate has no `--confirm` token, on purpose.** The others clear with a token because the
 question they ask ("is this change right?") is one the agent can put to the user and the user can
 answer for that one changeset. This one asks "does this content belong to that repository?", which
 is a standing property of the checkout, not a per-push judgment. The way past it is for the user
-to add the URL to the file. **An agent must never edit `.wikitool-remotes.json` to get past a
+to add the URL to the list - `config set` exits 42 for it, because the field is marked `gate`.
+**An agent must never edit `remotes.allowed_push_urls` to get past a
 refusal** - that is opening a gate on your own initiative, which AGENTS.md invariant 6 forbids.

 Arm it *before* a second remote is added and before the first `publish` to it: added afterwards
@@ -116,7 +117,7 @@ it leaves open exactly the window it closes.

 ### Upload Review Gate

-The MCP server's opt-in `submit` tool (`.wikitool-upload.json`) writes into a
+The MCP server's opt-in `submit` tool (the `upload` section of `.wikitool-local.json`) writes into a
 quarantine, `mcp-upload/`, that no other command reads. This gate is the only door out of it:
 `wikitool upload accept <id>` refuses without a matching `--confirm <token>`, printing the
 submission's manifest in full - filename, size, sha256, submitter, and `submitter_source` (the
@@ -159,7 +160,7 @@ with exit 0 and no gate.

 **Not the Publish-Remote Gate.** That one stays on `publish`. The targets here are declared by
 the committed `_capture.json` manifests under `raw/`; asking for the same URLs in
-`.wikitool-remotes.json` as well would be a second declaration of the same thing. What this gate
+`remotes.allowed_push_urls` as well would be a second declaration of the same thing. What this gate
 asks instead is the per-run question - whether this content belongs in these repositories now -
 which is the kind a token answers.

@@ -6,7 +6,7 @@ description: Review a document submitted from outside through the MCP submit too

 # Reviewing an external submission

-`.wikitool-upload.json` opts a checkout into a sixth MCP tool, `submit` -
+An `upload` section in `.wikitool-local.json` opts a checkout into a sixth MCP tool, `submit` -
 documents pushed by a caller that is not this terminal, into a quarantine no
 ordinary command reads. This is the human half of that path: what a reviewer
 checks before letting one through, and how `upload accept`/`upload reject`
@@ -92,9 +92,9 @@ this when a submission is already waiting and a decision is due.

 ## Arming the intake

-`submit` does not exist as a tool until `.wikitool-upload.json` is created at
-the served root - absence means the write path is not registered at all, not
-that it is unrestricted (see the file's own shape in
+`submit` does not exist as a tool until the `upload` section exists in the
+served root's `.wikitool-local.json` - absence means the write path is not registered at all, not
+that it is unrestricted (see the section's own shape in
 [raw/CONTRACT.md](../raw/CONTRACT.md) and `tools/chemenu/upload.py`). Two
 things belong to the *deployment*, not to this repository, and are named here
 because a reviewer needs to know they hold, not because this file configures
@@ -9,7 +9,7 @@ description: Run and keep current the MCP read server that serves this wiki to a
 Chemenu has a second consumer. `search`, `types`, `describe_type`, `lint` and `status` are
 served over MCP to callers that are not this terminal - the CLI and the server are two adapters
 over one core (`chemenu.api.Corpus`), not a CLI with a network interface bolted on. A sixth
-tool, `submit`, is opt-in: a checkout that creates `.wikitool-upload.json` also
+tool, `submit`, is opt-in: a checkout whose `.wikitool-local.json` has an `upload` section also
 offers a quarantined write path for documents pushed from outside - see
 [instructions/ingest-queue.md](ingest-queue.md) for reviewing what lands there.

@@ -112,7 +112,7 @@ everything an operator needs that is *true of the software* rather than of one i
 - **Asked to expose a write tool?** Five of the six tools have none, structurally: the server
  imports nothing under `chemenu.commands`, so `new`, `touch`, `xref`, `cite`, `publish` and
  `migrate` are unreachable from it rather than filtered out of a list. The one exception is
-  `submit` (opt-in via `.wikitool-upload.json`): it may write, but only into
+  `submit` (opt-in via the `upload` settings section): it may write, but only into
  `mcp-upload/`, a quarantine no other command reads - a **positive list** enforced in code
  (`chemenu.upload._write_atomic_within`), not an absence. The commands that move a submission
  *out* of that quarantine (`upload accept`/`upload reject`) still have the absence property:
@@ -105,6 +105,10 @@ declared by a migration document under `instructions/migrations/`. A single page
 - **The check finds something mid-unit.** Fix it in that unit and re-run `verify`. Never carry
  a finding into the next unit "to fix later": the next unit's diff baseline is this unit's
  commit, so an uncorrected drop becomes invisible.
+- **A step the agent must not do by hand?** A file it would have to write is generated, or holds a
+  secret, or is per checkout: then the step is a command of the group whose files it writes
+  (`config migrate` for the settings files), and the migration document names that command
+  instead of a recipe to follow by hand.
 - **Contradiction with an existing page.** Never overwrite. Record both, ask the user, and hedge
  the page's prose to the weaker of the two sources if it stays unresolved (kb/CONVENTIONS.md §
  Hedging).
@@ -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.
@@ -274,21 +274,21 @@ one it needs before that.
   it, and nobody reads up on telemetry before the first file is written anyway. This step only asks
   whether the operator wants to reverse that.

-   Ask the user once: telemetry on? If yes, create `.wikitool-telemetry.json` in the repo root
-   (per checkout, gitignored, no `.template` - like `.wikitool-remotes.json`):
+   Ask the user once: telemetry on? If yes, run `tools/wikitool config set telemetry.enabled true`.
+   It writes the `telemetry` section of `.wikitool-local.json` (per checkout, gitignored):

   ```json
-   { "enabled": true }
+   { "schema": 1, "telemetry": { "enabled": true } }
   ```

-   The file's two optional caps and their defaults are in
+   The section's two optional caps and their defaults are in
   [docs/reference/configuration.md](../docs/reference/configuration.md#telemetry); most instances
   need not touch them. If no, do nothing - the default is already
-   off, and no file is created. `WIKI_TRACE` still overrides in both directions, should a
+   off, and nothing is written. `WIKI_TRACE` still overrides in both directions, should a
   single session need to differ.

   `tools/wikitool doctor` reports the result in step 12 (`telemetry`): on/off, why
-   (installation form, this file, or `WIKI_TRACE`), and the current volume against both caps -
+   (installation form, this setting, or `WIKI_TRACE`), and the current volume against both caps -
   never a `FAIL`, since both directions are a valid state. More on this:
   [telemetry-and-evaluation.md](../docs/explanation/telemetry-and-evaluation.md#whether-it-runs-at-all).

@@ -300,15 +300,17 @@ one it needs before that.
   end state - the pages work alone, `review` simply says so and refuses - so ask rather than
   assume.

-   Ask the user once: is there a task tracker to connect? If yes, create `.wikitool-tasks.json`
-   in the repo root (per checkout, no `.template`, **gitignored once it holds a token** - like
-   `.wikitool-telemetry.json` and `.wikitool-remotes.json`), with the provider's own section and
-   the three thresholds the review reads as configuration rather than schema. The shape, the
+   Ask the user once: is there a task tracker to connect? If yes, set the `tasks`
+   section (provider and the three thresholds the review reads as configuration rather than
+   schema) and the provider's own section with `tools/wikitool config set`. What the tiers decide
+   goes there too: the account's address and login are per checkout, and a token or password is
+   never typed into the chat - the user puts it into 1Password, the secrets file or a
+   `WIKITOOL_SECRET_<NAME>` variable, and the setting holds a reference to it. The shape, the
   shipped providers, and what Super Productivity in particular needs are in
   [configuration.md](../docs/reference/configuration.md#task-tracker); do not restate them here. If no, do nothing - no
-   file is created, and adding one later needs nothing from this procedure.
+   section is written, and adding one later needs nothing from this procedure.

-   `doctor` reports the result in step 12 (`tasks`): absent is `OK`, a malformed file is the one
+   `doctor` reports the result in step 12 (`tasks`): absent is `OK`, a malformed section is the one
   `FAIL` here (a broken opt-in must not read as "no tracker configured"), and a configured
   provider that is simply not running is never a fault.