backup: an instance backs up into a synced folder - backup init makes a bare repository under <target>/git its origin, backup run and publish mirror the machine data into <target>/<machine>/, doctor warns about .git in a synced folder (#186); 10.0.0-beta.10

Files changed: - CHANGES.md - INSTALL.md - VERSION - docs/explanation/configuration-tiers.md - docs/how-to/README.md - docs/how-to/back-up-to-a-synced-folder.md - docs/reference/commands/README.md - docs/reference/commands/git.md - docs/reference/commands/instance-health.md - docs/reference/configuration.md - instructions/publish-cycle.md - instructions/setup-instance.md - tools/CONTRACT.md - tools/README.md - tools/chemenu/backup.py - tools/chemenu/cli.py - tools/chemenu/cli_contract.py - tools/chemenu/commands/backup_cmd.py - tools/chemenu/commands/doctor.py - tools/chemenu/commands/git_publish.py - tools/chemenu/config_shapes.py - tools/chemenu/reference_doc.py - tools/chemenu/tests/conftest.py - tools/chemenu/tests/test_backup.py - tools/chemenu/tests/test_config_shapes.py Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01SnAJ7Z3CpVD3PRbN73QtU2
2026-10-12 19:39:49 +02:00
1 parent e789146116
commit 9736472f48
@@ -14,7 +14,7 @@ place only: `instructions/dev/version-parts.md` § The candidate model.
 ---
-## 10.0.0-beta.9 - 2026-10-11 - Gesprächssprache: AGENTS.md § Conversation language legt fest, dass der Agent im Chat die KB-Sprache spricht; instructions sync schreibt den Sprachwert als generierte Zeile in jedes veröffentlichte SKILL.md, instructions verify und doctor melden eine geänderte Sprache als Drift
+## 10.0.0-beta.10 - 2026-10-12 - Backup in einen Sync-Ordner (OneDrive): backup init legt ein Bare-Repo unter <ziel>/git als origin an, backup run und publish spiegeln die Maschinendaten nach <ziel>/<maschine>/, doctor warnt vor .git im Sync-Ordner
 **Author:** Torben Nehmer
@@ -33,6 +33,7 @@ place only: `instructions/dev/version-parts.md` § The candidate model.
 - raw fetch --scope: eine Seite und die Unterseiten, die ihr Site-Handler anbietet, als ein Bündel in incoming/
 - raw fetch hinter einem Login: raw login speichert die Session des Nutzers als Secret, raw fetch holt damit; gerenderte Seiten über die optionale Browser-Komponente, externe Abrufer pro Host
 - Gesprächssprache: AGENTS.md § Conversation language legt fest, dass der Agent im Chat die KB-Sprache spricht; instructions sync schreibt den Sprachwert als generierte Zeile in jedes veröffentlichte SKILL.md, instructions verify und doctor melden eine geänderte Sprache als Drift
 - Backup in einen Sync-Ordner (OneDrive): backup init legt ein Bare-Repo unter <ziel>/git als origin an, backup run und publish spiegeln die Maschinendaten nach <ziel>/<maschine>/, doctor warnt vor .git im Sync-Ordner
 **Low impact**
 - Ketten von Paketen: stack-dev schreibt ## Kette, stack-close nennt das nächste Glied
@@ -62,6 +63,10 @@ Der Abschnitt `fetch` der Einstellungen ordnet einem Host einen Abrufweg zu. Bei
 Die vier Einzeldateien `.wikitool-remotes.json`, `.wikitool-telemetry.json`, `.wikitool-upload.json` und `.wikitool-tasks.json` gibt es nicht mehr; ihre Felder sind die Abschnitte `remotes`, `telemetry`, `upload`, `tasks`, `superproductivity` und `caldav` der drei Stufen. Zugangsdaten sind dort nur noch Verweise. Der Code liest die alten Dateien nicht mehr: ein Kommando, das die Einstellung braucht, endet mit Exit 42 und nennt `tools/wikitool config migrate`, `doctor` meldet FAIL, der Telemetrie-Hook bleibt still. `config migrate` läuft einmal je Checkout, ist wiederholbar und lässt bei jedem Abbruch die alten Dateien unverändert. `WIKITOOL_TASKS_CONFIG` zeigt auf ein Profil im Format von `.wikitool-local.json`. Nur `.wikitool-tools.json` bleibt eine eigene Datei.
 ### Backup in einen Sync-Ordner (#186)
 Ohne Git-Server bleibt der Arbeitsbaum außerhalb des Sync-Ordners; gesichert wird in das Ziel, das die Sektion `backup` von `.wikitool-local.json` nennt. `backup init` legt `<ziel>/git` als Bare-Repo an und macht es zu `origin`, wenn keins existiert. Mit `machine_data: true` spiegelt jedes `publish` nach dem Push `.wikitool-local.json`, `ENVIRONMENT.md`, `incoming/` und die `extra`-Pfade nach `<ziel>/<maschine>/` samt Manifest; `backup run` tut dasselbe von Hand. Geschrieben wird nur dort und atomar, gelesen nur innerhalb der Instanz, Secrets nie. Eine gescheiterte Sicherung nach dem Push ist eine `WARN`-Zeile mit Exit 0, eine fehlerhafte Sektion stoppt `publish` vor dem Commit. `doctor` meldet `sync-folder` und `backup`. Ablauf und Wiederherstellung: `docs/how-to/back-up-to-a-synced-folder.md`.
 ---
 ## 9.0.0 - 2026-10-09 - Docs sorted into four areas, generated references, raw derive for real documents
@@ -100,7 +100,9 @@ repository:
  needed).
 - <!-- setup-question: remote --> **Remote** - for an empty clone, only the confirmation that
  `origin` is right; otherwise a URL, if you want to push to a server. Without a remote the
-  instance stays local, and every `publish` runs with `--no-push`.
+  instance stays local, and every `publish` runs with `--no-push`. Without a git server but with a
  synced folder (OneDrive and the like), the agent offers a backup into that folder instead:
  [docs/how-to/back-up-to-a-synced-folder.md](docs/how-to/back-up-to-a-synced-folder.md).
 - <!-- setup-question: kb-language --> **Language and tone of the pages** - they go into
  `kb/CONVENTIONS.md`, plus `kb/<name>/COLLECTION.md` per collection. Ready-made profiles,
  including a complete German one, are in `instructions/kb-profiles.md`. Decide this **before the
@@ -1 +1 @@
-10.0.0-beta.9
+10.0.0-beta.10
@@ -7,6 +7,16 @@ command that writes them are in [the configuration reference](../reference/confi
 the rules an agent follows are in [AGENTS.md § Settings](../../AGENTS.md#settings). This page is
 about why it is built this way, and what it does not do.
 <!-- wikitool:toc -->
 ## Contents
 - [Three kinds of data that used to share files](#three-kinds-of-data-that-used-to-share-files)
 - [One place per value, not an override](#one-place-per-value-not-an-override)
 - [What runs, and where it pushes, never travels with a pull](#what-runs-and-where-it-pushes-never-travels-with-a-pull)
 - [References instead of values](#references-instead-of-values)
 - [What this does not protect against](#what-this-does-not-protect-against)
 <!-- /wikitool:toc -->
 ## Three kinds of data that used to share files
 Before the tiers, every feature kept its settings in a gitignored file of its own. Three kinds of
@@ -57,6 +67,13 @@ same value. In CI, `op` runs with a service-account token and resolves the same
 references. Alternatively, 1Password's own action resolves values into variables before
 `wikitool` starts, which serves references by name. This repository's CI does the second.
 A plain private value in `.wikitool-local.json` stays on this machine only as long as that file
 does. A backup into a synced folder (the `backup` section) copies the file as it is, because it is
 the one record of how this checkout is set up, and a restore without it starts from nothing. That
 trade is the operator's, made by writing the section by hand. A reference keeps the value out of
 that copy as well, and the secrets file is never in it: it lies outside the instance, and a backup
 reads nothing outside it.
 A reference is resolved only when a command asks for that one value, never when the files are
 read, and the value stays in that process's memory. `doctor` reports whether each reference
 resolves, never what it resolves to.
@@ -30,5 +30,7 @@ Running the instance:
 - [Trace and score agent sessions](trace-and-score-sessions.md)
 - [Use 1Password for settings](use-1password-for-settings.md) - secrets and private values out
  of the tree, on the desktop and in CI
 - [Back up to a synced folder](back-up-to-a-synced-folder.md) - OneDrive and the like as the
  backup of an instance without a git server, and restoring from it
 Installing a new instance is [INSTALL.md](../../INSTALL.md) at the repository root.
@@ -0,0 +1,158 @@
 # Back up to a synced folder
 Back an instance up into a folder a sync client uploads - OneDrive, or any other client that keeps a
 local folder in step with a server - when there is no git server to push to. The instance itself
 stays in a folder the sync client does not touch; the synced folder receives a git repository to
 push to and a copy of the files on this machine that are not in git. What the settings look like:
 [configuration reference](../reference/configuration.md#backup-to-a-synced-folder).
 <!-- wikitool:toc -->
 ## Contents
 - [Why the instance does not live in the synced folder](#why-the-instance-does-not-live-in-the-synced-folder)
 - [Set it up](#set-it-up)
 - [What is backed up, and what is not](#what-is-backed-up-and-what-is-not)
 - [Restore](#restore)
 - [One device writes](#one-device-writes)
 <!-- /wikitool:toc -->
 ## Why the instance does not live in the synced folder
 Putting the whole instance - `.git` included - into the synced folder looks like the simplest
 backup, and fails in three ways:
 - **Locks.** On Windows, OneDrive holds a file it is uploading open for a moment. `git gc` and
  `git repack` then fail to delete or replace a file under `.git` ("unlink failed").
 - **Placeholders.** With Files On-Demand, the client offloads files it considers unused and leaves a
  placeholder behind; git then reads objects that first have to be downloaded, or are not there
  when the machine is offline.
 - **Conflict copies.** As soon as a second device syncs the same folder, two writers meet inside
  `.git`, and the client resolves that by making copies of the files both changed - a repository
  git can no longer read.
 So the instance lives outside the synced folder, and the synced folder gets a layout git writes to
 in a way a sync client handles well:
 ```
 <target>/git/          a bare repository - origin of the instance; publish pushes to it
 <target>/<machine>/    a copy of this machine's files that are not in git, plus .chemenu-backup.json
 ```
 Git writes into the bare repository only on a push, and then mostly adds new files that never
 change again.
 `tools/wikitool doctor` reports `sync-folder` as a `WARN` when the instance's git directory lies in
 a synced folder. On Windows, check that line even if you never chose such a folder: when Documents
 or Desktop is redirected into OneDrive (Known Folder Move), an instance under Documents lies in
 OneDrive without looking like it. Move the instance to a folder outside it - `C:\Wiki\<name>`, say -
 before you go on.
 ## Set it up
 1. **Pick the target**: a folder inside the synced folder, for example
   `C:\Users\<you>\OneDrive - <company>\Chemenu-Backup`. It must not lie inside the instance.
 2. **Write the `backup` section** into `.wikitool-local.json` at the root of the instance - by hand,
   since its fields decide what leaves this machine and `config set` refuses them:
   ```json
   {
     "backup": {
       "target": "C:\\Users\\<you>\\OneDrive - <company>\\Chemenu-Backup",
       "machine_data": true,
       "machine_name": "WORK-LAPTOP",
       "extra": [".claude/settings.local.json"]
     }
   }
   ```
   Backslashes in a JSON string are doubled. `machine_name` defaults to the computer's host name;
   `extra` lists further paths inside the instance to copy, and can be left out.
 3. **Tell the agent:**
   > Set up the backup target from the `backup` section.
   The agent runs `tools/wikitool backup init`. It creates `<target>/git` as a bare repository and
   makes it `origin` - unless the instance already has an `origin` that points elsewhere: then it
   changes nothing and shows you both URLs, and whether `origin` moves is yours to decide
   (`git remote set-url origin "<target>\git"`).
 4. **Allow the push target**, if your `.wikitool-local.json` has a `remotes` section: `backup init`
   then prints that section with `<target>\git` added. Copy it into the file yourself - the list is
   the Publish-Remote Gate, and no agent edits it. Without a `remotes` section there is nothing to do.
 5. **Publish.** The next `tools/wikitool publish` pushes the whole history to `<target>/git` and,
   with `machine_data` on, copies the machine data into `<target>/<machine>/`. From then on every
   publish that pushes does both. `tools/wikitool backup run` copies the machine data on its own,
   whenever you want it current without publishing - after dropping a file into `incoming/`, for
   instance, which is otherwise only copied by the next publish.
 6. **Check it:** `tools/wikitool doctor`. The `backup` line names the target and how old the last
   copy of the machine data is; a `WARN` there names what is missing.
 If a publish reports a `WARN` that the machine-data backup failed, the commit and the push have
 still happened. Fix what the line names - a synced folder that is not there, a folder that is not
 writable - and run `tools/wikitool backup run`. Another publish does not help: it has nothing new to
 push.
 ## What is backed up, and what is not
 | Path | Backed up | Why |
 |------|-----------|-----|
 | Everything committed (`kb/`, `raw/`, `wikitool.json`, ...) | yes, in `<target>/git` | that is what `publish` pushes |
 | `.wikitool-local.json` | yes | the settings of this checkout |
 | `ENVIRONMENT.md` | yes, if present | written by hand |
 | Everything in `incoming/` but `.gitkeep` | yes | sources waiting there are backed up nowhere else |
 | The `extra` paths | yes | what you named |
 | `mcp-upload/` | no | material submitted from outside that nobody has reviewed yet |
 | `reports/` | no | regenerated by `lint`; telemetry holds prompts |
 | `.wikitool-tools.json`, `tools/.venv/`, the published skills | no | the preflight and `instructions sync` rebuild them |
 | The secrets file | **never** | it lies outside the instance, and a backup reads nothing outside it |
 **Private values reach the synced folder.** `.wikitool-local.json` is copied as it is, so a plain
 private value in it - an internal host name, an internal URL - ends up in OneDrive. A secret does
 not: a secret is never in that file, only a reference to it, and the secrets file it resolves
 through (`%APPDATA%\chemenu\<instance_id>\secrets.json`, with the sessions `raw login` stored)
 lies outside the instance. An `extra` path that leads outside the instance - through `..` or a
 link - is refused, so no setting can copy it either.
 In `<target>/<machine>/` a run writes and deletes only what is its own: it removes a file only when
 its previous run copied it and the instance no longer has it (a source `raw accept` moved out of
 `incoming/`, say), and refuses a folder that is not empty and has no `.chemenu-backup.json`, rather
 than copying into somebody else's folder. A link inside a copied directory is skipped and named,
 never followed.
 ## Restore
 On the same machine or a new one:
 1. **Clone the repository and check it:**
   ```bash
   git clone "<target>/git" "<new folder>"
   cd "<new folder>"
   git fsck --full
   ```
   The clone is outside the synced folder, like the original; its `origin` is the bare repository
   already.
 2. **Copy the machine data back**: everything in `<target>/<machine>/` except
   `.chemenu-backup.json`, into the new folder, keeping the paths. On Windows:
   `robocopy "<target>\<machine>" "<new folder>" /E /XF .chemenu-backup.json`; elsewhere:
   `rsync -a --exclude .chemenu-backup.json "<target>/<machine>/" "<new folder>/"`.
 3. **Bootstrap the checkout** - tell the agent:
   > Bootstrap this checkout.
   It follows [instructions/bootstrap.md](../../instructions/bootstrap.md): the preflight, the
   published skills, `doctor`.
 4. **Provide the secrets again.** They were never in the backup. Put each value back where its
   reference reads it - 1Password, the secrets file, or a `WIKITOOL_SECRET_<NAME>` variable
   ([use-1password-for-settings.md](use-1password-for-settings.md)) - and sign in again with
   `raw login` for each host that needs it. `doctor`'s `settings-secrets` line names every reference
   that does not resolve yet.
 `doctor` must then run through without a `FAIL`.
 ## One device writes
 Only one device publishes to `<target>/git`. Two devices pushing into the same synced folder are two
 writers again, only one step removed - and the sync client resolves that with conflict copies, not
 with a merge. An instance on a second device gets a target of its own. The sync client is a backup
 here, not a way to work on one instance from two devices.
@@ -97,6 +97,8 @@ Full records: [git.md](git.md)
 - [`sync`](git.md#sync) - Fetch `<remote>/<branch>` and bring the local branch up to date with it.
 - [`publish`](git.md#publish) - Reconcile with `<remote>/<branch>`, then stage all changes, commit, and push.
 - [`backup init`](git.md#backup-init) - Create the backup target's bare repository and make it `origin` when there is none.
 - [`backup run`](git.md#backup-run) - Mirror this machine's files that are not in git into `<target>/<machine>/`.
 ## Guideline export
@@ -1,12 +1,15 @@
 # Git
-Pulling in the remote and publishing a change - the only way a change leaves this checkout.
+Pulling in the remote and publishing a change - the only way a change leaves this checkout - and
 backing the checkout up into a synced folder.
 <!-- wikitool:toc -->
 ## Contents
 - [`sync`](#sync)
 - [`publish`](#publish)
 - [`backup init`](#backup-init)
 - [`backup run`](#backup-run)
 <!-- /wikitool:toc -->
 <!-- wikitool:reference-commands -->
@@ -130,6 +133,7 @@ tools/wikitool publish --confirm-rebase <token> --message "ingest: docker-cheats
 - The remotes settings file of an earlier version is not read: while it exists this exits 42 and names `tools/wikitool config migrate`, so a restriction is never lost silently.
 - `--path` (repeatable) scopes the whole operation - gate count, staging and commit - to that subtree, with one exception: uncommitted generated files outside `--path` (`kb/index.md`, `kb/log.md`, `kb/provenance.md`, every `INDEX.md` under `kb/`) are staged and committed too, and a line names them - whether a reconcile or the change itself wrote them. They stay out of the gate count, and the `--confirm` token and the re-run line cover the `--path` given. Every other file outside `--path` is left as it is.
 - Commit message: `--message`, then a `Files changed:` paragraph listing every committed path. When `--message` ends in a paragraph git reads as a trailer block (`Co-Authored-By:` and the like), that block stays the last paragraph and the list goes in front of it, since git reads trailers from the last paragraph only. `git interpret-trailers` decides whether there is such a block, and the list moves only when git reads the same trailers from the result; otherwise it is appended at the end. `--message` is not part of any gate token.
 - Machine-data backup: with a `backup` section in `.wikitool-local.json` whose `machine_data` is true, a call that pushed then mirrors this machine's files that are not in git into `<target>/<machine>/` - the same step as `backup run`. A failure there prints a `WARN` line with the reason and still exits 0, since the commit and the push stand. No backup with `--no-push`, after a failed push, or when there was nothing to push. A malformed `backup` section stops the call with exit 1 before anything is committed, `--no-push` included.
 - After a successful commit or push whose changed files include `tools/`, `types/`, `instructions/`, `AGENTS.md` or a path ending in `CONTRACT.md`, prints one reminder line: the phase past this point (an issue-body rewrite, `docs/` staleness, a changelog entry's accuracy) is not covered by `docs verify`, `instructions verify` or `pytest`. It is not a gate: no exit code change, nothing to clear, and silent for an ordinary content publish.
 **Properties**
@@ -144,11 +148,12 @@ tools/wikitool publish --confirm-rebase <token> --message "ingest: docker-cheats
 **Exit codes**
 - `0` - success
 - `0` - The machine-data backup after the push failed: a `WARN` line names the reason, and the commit and the push stand
 - `1` - git failed - `git add`, `git commit`, `git push`, or the reconcile's automatic rebase (a conflict outside the generated files, an edited `kb/log.md`, or an uncommitted change on a path the incoming commits change)
 - `1` - The push target (`--branch`) is not the checked-out branch, or HEAD is detached; the unborn branch of a fresh `git init` is not this case
 - `1` - No `--no-push`, and the remote is not configured or cannot be reached; nothing was committed
 - `1` - `--yes`/`-y` was passed - the flag does not exist and fails with an explicit error
- `1` - The settings files do not pass their check, or `remotes.allowed_push_urls` is not a list of strings
+- `1` - The settings files do not pass their check, `remotes.allowed_push_urls` is not a list of strings, or the `backup` section is malformed; nothing was committed
 - `42` - The remotes settings file of an earlier version is still there
 - `42` - Mass-Update Gate: `--threshold` (default 10) or more counted files would be committed, or the `--confirm` token does not match this changeset
 - `42` - Rebase-Review Gate: `<remote>/<branch>` moved and both sides changed the same file; the output lists the upstream commits, the overlapping files and their diff
@@ -159,4 +164,103 @@ tools/wikitool publish --confirm-rebase <token> --message "ingest: docker-cheats
 - `wikitool sync` - the same reconcile on its own, without committing or pushing
 - `instructions/gates.md` - the gate procedure
 - `instructions/setup-instance.md` - the first publish of a new instance
 - `wikitool backup run` - the machine-data backup on its own
 ## `backup init`
 Create the backup target's bare repository and make it `origin` when there is none.
 **Synopsis**
 - `wikitool backup init`
 **Options**
 ```text
  -h, --help  Show this message and exit.
 ```
 **Examples**
 ```bash
 tools/wikitool backup init
 ```
 **Behaviour**
 - Reads the `backup` section of `.wikitool-local.json` and creates `<target>/` and `<target>/git`, the latter as a bare repository (`git init --bare -b main`). An existing bare repository there, or an empty directory, is used as it is.
 - Sets `origin` to `<target>/git` when the checkout has no `origin`. An `origin` that already pushes there is left as it is; one that pushes anywhere else stops the command.
 - When `remotes.allowed_push_urls` exists and lacks the URL `origin` pushes to, prints the `remotes` section with that URL added, for the user to copy into `.wikitool-local.json`. It never writes that file: the field is a gate.
 - Pushes nothing: the next `publish` sends the history to the new `origin`.
 **Properties**
 - Changes files: yes
 - Idempotent: yes
 - Atomic: Every precondition is checked first; a refusal changes nothing
 - Counts toward the session call budget: yes
 - Can reach the network: no
 **Exit codes**
 - `0` - success
 - `1` - No `backup` section in `.wikitool-local.json`, or a malformed one - a target that is not absolute or lies inside the instance, a `machine_name` that cleans to nothing or to `git`, an `extra` path that resolves outside the instance or into `.git/`
 - `1` - `<target>/git` exists and is not a bare repository; nothing was changed
 - `1` - `origin` already pushes to another URL; the message names both and nothing was changed
 **See also**
 - `wikitool backup run` - the machine-data half of the backup
 - `wikitool publish` - pushes to the bare repository and runs the machine-data backup after it
 - `docs/how-to/back-up-to-a-synced-folder.md` - the whole procedure, restoring included
 ## `backup run`
 Mirror this machine's files that are not in git into `<target>/<machine>/`.
 **Synopsis**
 - `wikitool backup run`
 **Options**
 ```text
  -h, --help  Show this message and exit.
 ```
 **Examples**
 ```bash
 tools/wikitool backup run
 ```
 **Behaviour**
 - Mirrors `.wikitool-local.json`, `ENVIRONMENT.md` if present, every file in `incoming/` but `.gitkeep`, and the `extra` paths of the `backup` section into `<target>/<machine>/`, then writes the manifest `.chemenu-backup.json` there: time, stack version, machine name, and per file its relative path, size and sha256.
 - Never mirrors `mcp-upload/`, `reports/`, `.wikitool-tools.json`, `tools/.venv/`, the published skills or `.git/` - unless an `extra` path names one of the first ones. The secrets file lies outside the instance and is never read.
 - Writes and deletes only under `<target>/<machine>/`. Deletes only a file the previous manifest lists and the instance no longer has; a file there the manifest does not list stays as it is. A file whose size and sha256 match the previous manifest is not rewritten.
 - A symbolic link or junction inside a mirrored directory is skipped and named in the output, never followed.
 - `publish` runs the same step after every push when `machine_data` is true.
 **Properties**
 - Changes files: yes
 - Idempotent: yes
 - Atomic: Per file - each is written to a temporary file and renamed, the manifest last; an interrupted run leaves whole files and the previous manifest
 - Counts toward the session call budget: yes
 - Can reach the network: no
 **Exit codes**
 - `0` - success
 - `1` - No `backup` section in `.wikitool-local.json`, or a malformed one - a target that is not absolute or lies inside the instance, a `machine_name` that cleans to nothing or to `git`, an `extra` path that resolves outside the instance or into `.git/`
 - `1` - `machine_data` is false
 - `1` - `<target>/<machine>/` is not empty and has no manifest, or its manifest cannot be read; nothing was written
 - `1` - The target is not a directory (the synced folder is missing or not mounted), or a write failed
 **See also**
 - `wikitool backup init` - sets up the target's bare repository
 - `wikitool doctor` - the `backup` line reports the age of the last run
 - `docs/how-to/back-up-to-a-synced-folder.md` - the whole procedure, restoring included
 <!-- /wikitool:reference-commands -->
@@ -36,6 +36,8 @@ tools/wikitool doctor --json
 - KB conventions: `kb/CONVENTIONS.md` present, unsentinelled, and naming all three tool-owned section headings - a `FAIL` on any of the three.
 - Environment note: `ENVIRONMENT.md` is optional, so absent is `OK`; a still-templated one is a `WARN`.
 - Legacy settings (`legacy-settings`): one `FAIL` for each per-feature settings file of an earlier version (telemetry, remotes, upload, task tracker) that is still there. Nothing reads them any more, so the settings they hold are not in effect; the fix is `tools/wikitool config migrate`.
 - Synced folder (`sync-folder`): a `WARN` when the git directory, links and junctions resolved, lies under a folder named by `OneDrive`, `OneDriveCommercial` or `OneDriveConsumer` (compared without regard to case on Windows) or under `~/Library/CloudStorage/` (macOS); `OK` otherwise, never a `FAIL`.
 - Backup (`backup`): the `backup` section absent is `OK`, malformed is a `FAIL`. Configured, a `WARN` when `<target>/git` is not a bare repository, `origin` does not push there, or - with `machine_data` true - no machine-data backup exists yet; otherwise `OK` with the age of the last machine-data backup.
 - MCP `submit` tool: whether the `upload` section of the settings is present, absent or malformed, its limits, and how many submissions wait in `mcp-upload/`. Absent is `OK` and means the write path does not exist at all; malformed is a `FAIL`.
 - Task tracker: the `tasks` section present, absent or malformed - absent is `OK` (no tracker configured), malformed is a `FAIL`. When `WIKITOOL_TASKS_CONFIG` is set, the profile it names is read instead of the `tasks`, `superproductivity` and `caldav` sections and the finding names it; a set variable that names no file is a `FAIL`, never `OK`.
 - For a configured `superproductivity` provider, the configured `access` path's own state: `access: "api"` reports whether its local REST API answers `GET /health` with a ready renderer right now, `access: "snapshot"` whether a backup file is ready. The other access path is never attempted, and neither state is ever a `FAIL`.
@@ -67,5 +69,6 @@ tools/wikitool doctor --json
 - `instructions/preflight.md` - what `tool-paths` and `install-dir` point back to
 - `docs/reference/configuration.md` - the per-checkout configuration files and the tiered settings
 - `docs/explanation/telemetry-and-evaluation.md` - telemetry state and caps
 - `docs/how-to/back-up-to-a-synced-folder.md` - what `sync-folder` and `backup` point to
 - `instructions/session-setup.md` - setting `WIKITOOL_SESSION_ID`
 <!-- /wikitool:reference-commands -->
@@ -30,6 +30,7 @@ something you run.
 - [MCP submissions](#mcp-submissions)
 - [Site handlers](#site-handlers)
 - [Fetch routes](#fetch-routes)
 - [Backup to a synced folder](#backup-to-a-synced-folder)
 - [Files of earlier versions](#files-of-earlier-versions)
 <!-- /wikitool:toc -->
@@ -91,7 +92,8 @@ Each file is a JSON object of sections, one per feature, beside two keys of its
 `instance_id` sits in `wikitool.json` only. The first `wikitool config set` creates the file and
 the id; the id names the directory of the secrets file below. The sections are [telemetry](#telemetry),
 [remotes](#allowed-push-urls), [tasks, superproductivity and caldav](#task-tracker) and
-[upload](#mcp-submissions), [sites](#site-handlers) and [fetch](#fetch-routes). `config set` names the sections it knows, and `doctor` reports a
+[upload](#mcp-submissions), [sites](#site-handlers), [fetch](#fetch-routes) and
 [backup](#backup-to-a-synced-folder). `config set` names the sections it knows, and `doctor` reports a
 section it does not read as a `WARN`.
 **One place per value.** A value in the file its tier does not name is an error naming the file,
@@ -533,6 +535,55 @@ Example:
 ```
 <!-- /wikitool:reference-config-fetch -->
 ## Backup to a synced folder
 The `backup` section of `.wikitool-local.json` backs this checkout up into a folder a sync client
 uploads - OneDrive and the like - while the working tree itself stays outside it. The target gets
 two kinds of content:
 ```
 <target>/git/          bare repository, the checkout's origin; publish pushes here
 <target>/<machine>/    mirror of this machine's files that are not in git, plus .chemenu-backup.json
 ```
 `tools/wikitool backup init` creates `<target>/git` and makes it `origin` when the checkout has none.
 With `machine_data` on, every `publish` that pushed mirrors `.wikitool-local.json`, `ENVIRONMENT.md`,
 what waits in `incoming/` and the `extra` paths into `<target>/<machine>/`; `tools/wikitool backup
 run` does the same on its own. The secrets file is never among them - it lies outside the instance,
 and a backup reads nothing outside it. Plain private values in `.wikitool-local.json`, an internal
 host name for one, do reach the synced folder.
 <!-- wikitool:reference-config-backup -->
 | Field | Tier | Type | Required | Default | Description |
 |-------|------|------|----------|---------|-------------|
 | `target` | checkout, gate | string | yes | - | The backup folder: an absolute path outside the instance. `backup init` creates `<target>/git` in it, `backup run` writes only to `<target>/<machine>/`. |
 | `machine_data` | checkout, gate | boolean | no | `false` | Mirror this machine's files after every `publish` that pushed, and with `backup run`: `.wikitool-local.json`, `ENVIRONMENT.md`, what waits in `incoming/`, and `extra`. |
 | `machine_name` | checkout | string | no | the host name | The name of this machine's folder under the target. Every character outside letters, digits, `-` and `_` becomes `-`, and leading and trailing `-` are dropped; a name that is empty afterwards, or `git` in any case, is an error. |
 | `extra` | checkout, gate | array of strings | no | `[]` | Further files or directories to mirror, relative to the instance. One that resolves outside the instance, or into `.git/`, is an error. |
 - **Absent:** No backup: `publish` behaves as without it, and `backup init` and `backup run` stop with exit 1 naming the section.
 - **Malformed:** An error. `publish` stops with exit 1 before it commits anything, `backup init` and `backup run` stop with exit 1, and `doctor` reports `FAIL`. A broken section is never read as "no backup".
 Example:
 ```json
 {
  "backup": {
    "target": "C:\\Users\\<user>\\OneDrive - <company>\\Chemenu-Backup",
    "machine_data": true,
    "machine_name": "WORK-LAPTOP",
    "extra": [
      ".claude/settings.local.json"
    ]
  }
 }
 ```
 <!-- /wikitool:reference-config-backup -->
 `target`, `machine_data` and `extra` decide what leaves this machine, so they are marked `gate`:
 `config set` exits 42 for them, and only you write them. The procedure, restoring included:
 [back-up-to-a-synced-folder.md](../how-to/back-up-to-a-synced-folder.md).
 ## Files of earlier versions
 Until version 10 every feature above had a file of its own at the root: `.wikitool-telemetry.json`,
@@ -52,7 +52,12 @@ consistent.
  to commit locally with `--no-push`, and run that only on their answer. Never push by hand
  (AGENTS.md invariant 5): the next `publish` that reaches the remote sends the local commit
  together with whatever is new. A local-only instance, which has no remote at all, passes
-  `--no-push` on every call ([setup-instance.md](setup-instance.md), step 4).
+  `--no-push` on every call ([setup-instance.md](setup-instance.md), step 3).
 - **A `WARN` that the machine-data backup failed?** The commit and the push stand, and `publish`
  exited 0. Show the user the line - it names the reason, a synced folder that is not there or not
  writable, say. Do **not** run `publish` again: it would have nothing to push and back nothing up.
  Once the user has fixed the cause, `tools/wikitool backup run` repeats the backup
  ([docs/how-to/back-up-to-a-synced-folder.md](../docs/how-to/back-up-to-a-synced-folder.md)).
 - **Query or lint pass?** Neither auto-publishes. Run `publish` only if asked to.
 - **Nothing under `kb/` changed?** Skip steps 1 and 2; a change to `tools/` or `instructions/`
  does not affect the catalog.
@@ -122,6 +122,14 @@ one it needs before that.
   - Not given: stay local - then **every** later `tools/wikitool publish` needs a `--no-push`
     (which also drops its branch check, see step 1). Without it, `publish` ends with exit 1
     before it commits anything, because there is no remote to publish to.
   - No git server, but a folder a sync client uploads (OneDrive and the like): offer a backup
     into it. The working tree stays where it is - outside that folder - and a bare repository in
     the folder becomes `origin`, with the files of this machine that are not in git mirrored
     beside it. The user writes the `backup` section of `.wikitool-local.json` by hand (its
     fields are gates, so `config set` refuses them); then run `tools/wikitool backup init` and
     show the user any `remotes.allowed_push_urls` entry it prints, for them to add. The whole
     procedure is [docs/how-to/back-up-to-a-synced-folder.md](../docs/how-to/back-up-to-a-synced-folder.md).
     Until it is done, treat the instance as local.
 4. **Decision point - authoring conventions.** The release ships no filled-in conventions, only
   `kb/CONVENTIONS.md.template` and one `kb/<name>/COLLECTION.md.template` per collection. Both
@@ -136,6 +136,8 @@ upload accept         write non-idempotent budget:counted              exit:0,1,
 upload reject         write non-idempotent budget:counted              exit:0,1    Delete a submission's material, keeping only its ledger trail.
 sync                  write idempotent     budget:counted              exit:0,1,42 Fetch `<remote>/<branch>` and bring the local branch up to date with it.
 publish               write non-idempotent budget:counted              exit:0,1,42 Reconcile with `<remote>/<branch>`, then stage all changes, commit, and push.
 backup init           write idempotent     budget:counted              exit:0,1    Create the backup target's bare repository and make it `origin` when there is none.
 backup run            write idempotent     budget:counted              exit:0,1    Mirror this machine's files that are not in git into `<target>/<machine>/`.
 export guidelines     write idempotent     budget:counted              exit:0,1,42 Render the guideline pages into one generated `GUIDELINES.md`, or push it into the captured repositories that opted in (**Guideline Push Gate**).
 work new              write non-idempotent budget:counted              exit:0,1    Scaffold `work/<runkey>/` for one workshop run.
 work close            write non-idempotent budget:counted              exit:0,1    Delete a finished workshop.
@@ -2120,11 +2122,12 @@ Reconcile with `<remote>/<branch>`, then stage all changes, commit, and push.
 **EXIT STATUS**
 - 0    success
 - 0    The machine-data backup after the push failed: a `WARN` line names the reason, and the commit and the push stand
 - 1    git failed - `git add`, `git commit`, `git push`, or the reconcile's automatic rebase (a conflict outside the generated files, an edited `kb/log.md`, or an uncommitted change on a path the incoming commits change)
 - 1    The push target (`--branch`) is not the checked-out branch, or HEAD is detached; the unborn branch of a fresh `git init` is not this case
 - 1    No `--no-push`, and the remote is not configured or cannot be reached; nothing was committed
 - 1    `--yes`/`-y` was passed - the flag does not exist and fails with an explicit error
- 1    The settings files do not pass their check, or `remotes.allowed_push_urls` is not a list of strings
+- 1    The settings files do not pass their check, `remotes.allowed_push_urls` is not a list of strings, or the `backup` section is malformed; nothing was committed
 - 42   The remotes settings file of an earlier version is still there
 - 42   Mass-Update Gate: `--threshold` (default 10) or more counted files would be committed, or the `--confirm` token does not match this changeset
 - 42   Rebase-Review Gate: `<remote>/<branch>` moved and both sides changed the same file; the output lists the upstream commits, the overlapping files and their diff
@@ -2132,11 +2135,12 @@ Reconcile with `<remote>/<branch>`, then stage all changes, commit, and push.
 **ON FAILURE**
 - The machine-data backup after the push failed: a `WARN` line names the reason, and the commit and the push stand -> Show the `WARN` line to the user. Do not publish again - once the cause is fixed, `tools/wikitool backup run` repeats the backup
 - git failed - `git add`, `git commit`, `git push`, or the reconcile's automatic rebase (a conflict outside the generated files, an edited `kb/log.md`, or an uncommitted change on a path the incoming commits change) -> Do not retry and do not force - report and ask the user. `publish` has already made its one retry of a rejected push itself, where a reconcile resolved the rejection
 - The push target (`--branch`) is not the checked-out branch, or HEAD is detached; the unborn branch of a fresh `git init` is not this case -> Check out the branch you mean to publish, or pass `--branch <checked-out branch>`, then retry once
 - No `--no-push`, and the remote is not configured or cannot be reached; nothing was committed -> Show the message to the user and ask whether to commit locally with `--no-push`. Never push by hand - the next `publish` that reaches the remote sends that commit
 - `--yes`/`-y` was passed - the flag does not exist and fails with an explicit error -> Drop it. The Mass-Update Gate is cleared only with `--confirm <token>` from the gate's own refusal output
- The settings files do not pass their check, or `remotes.allowed_push_urls` is not a list of strings -> Show the error to the user and stop - a malformed section is not permission, and fixing it is theirs to do
+- The settings files do not pass their check, `remotes.allowed_push_urls` is not a list of strings, or the `backup` section is malformed; nothing was committed -> Show the error to the user and stop - a malformed section is not permission, and fixing it is theirs to do
 - The remotes settings file of an earlier version is still there -> Show the output to the user verbatim and stop; `tools/wikitool config migrate` moves it, and the user decides when
 - Mass-Update Gate: `--threshold` (default 10) or more counted files would be committed, or the `--confirm` token does not match this changeset -> Show the user the command's full output verbatim and stop. Once they have approved it, run the re-run line the output prints, which carries `--confirm <token>`. Without that token, or with a wrong, invented or superseded one, it exits 42 again with the current state
 - Rebase-Review Gate: `<remote>/<branch>` moved and both sides changed the same file; the output lists the upstream commits, the overlapping files and their diff -> Show the user the command's full output verbatim and stop. Once they have approved it, run the re-run line the output prints, which carries `--confirm-rebase <token>`. Without that token, or with a wrong, invented or superseded one, it exits 42 again with the current state
@@ -2165,6 +2169,7 @@ Reconcile with `<remote>/<branch>`, then stage all changes, commit, and push.
 - The remotes settings file of an earlier version is not read: while it exists this exits 42 and names `tools/wikitool config migrate`, so a restriction is never lost silently.
 - `--path` (repeatable) scopes the whole operation - gate count, staging and commit - to that subtree, with one exception: uncommitted generated files outside `--path` (`kb/index.md`, `kb/log.md`, `kb/provenance.md`, every `INDEX.md` under `kb/`) are staged and committed too, and a line names them - whether a reconcile or the change itself wrote them. They stay out of the gate count, and the `--confirm` token and the re-run line cover the `--path` given. Every other file outside `--path` is left as it is.
 - Commit message: `--message`, then a `Files changed:` paragraph listing every committed path. When `--message` ends in a paragraph git reads as a trailer block (`Co-Authored-By:` and the like), that block stays the last paragraph and the list goes in front of it, since git reads trailers from the last paragraph only. `git interpret-trailers` decides whether there is such a block, and the list moves only when git reads the same trailers from the result; otherwise it is appended at the end. `--message` is not part of any gate token.
 - Machine-data backup: with a `backup` section in `.wikitool-local.json` whose `machine_data` is true, a call that pushed then mirrors this machine's files that are not in git into `<target>/<machine>/` - the same step as `backup run`. A failure there prints a `WARN` line with the reason and still exits 0, since the commit and the push stand. No backup with `--no-push`, after a failed push, or when there was nothing to push. A malformed `backup` section stops the call with exit 1 before anything is committed, `--no-push` included.
 - After a successful commit or push whose changed files include `tools/`, `types/`, `instructions/`, `AGENTS.md` or a path ending in `CONTRACT.md`, prints one reminder line: the phase past this point (an issue-body rewrite, `docs/` staleness, a changelog entry's accuracy) is not covered by `docs verify`, `instructions verify` or `pytest`. It is not a gate: no exit code change, nothing to clear, and silent for an ordinary content publish.
 **SEE ALSO**
@@ -2172,6 +2177,110 @@ Reconcile with `<remote>/<branch>`, then stage all changes, commit, and push.
 - `wikitool sync` - the same reconcile on its own, without committing or pushing
 - `instructions/gates.md` - the gate procedure
 - `instructions/setup-instance.md` - the first publish of a new instance
 - `wikitool backup run` - the machine-data backup on its own
 #### `backup init`
 Create the backup target's bare repository and make it `origin` when there is none.
 **SYNOPSIS**
 - `wikitool backup init`
 **PROPERTIES**
 - effect: write
 - idempotent: yes
 - atomic: Every precondition is checked first; a refusal changes nothing
 - budget: counted
 - network: no
 **EXAMPLES**
 - `tools/wikitool backup init`
 **EXIT STATUS**
 - 0    success
 - 1    No `backup` section in `.wikitool-local.json`, or a malformed one - a target that is not absolute or lies inside the instance, a `machine_name` that cleans to nothing or to `git`, an `extra` path that resolves outside the instance or into `.git/`
 - 1    `<target>/git` exists and is not a bare repository; nothing was changed
 - 1    `origin` already pushes to another URL; the message names both and nothing was changed
 **ON FAILURE**
 - No `backup` section in `.wikitool-local.json`, or a malformed one - a target that is not absolute or lies inside the instance, a `machine_name` that cleans to nothing or to `git`, an `extra` path that resolves outside the instance or into `.git/` -> Show the message to the user and stop. The section is theirs to write or fix by hand - `config set` refuses its fields; docs/how-to/back-up-to-a-synced-folder.md has the procedure
 - `<target>/git` exists and is not a bare repository; nothing was changed -> Show the message to the user - whether that folder moves, or the target does, is their decision
 - `origin` already pushes to another URL; the message names both and nothing was changed -> Show both URLs to the user and stop. Never repoint `origin` yourself - `git remote set-url` is theirs to run
 **NEVER**
 - Never add the printed URL to `remotes.allowed_push_urls` yourself - that field is a gate, and editing it is the user's.
 **NOTES**
 - Reads the `backup` section of `.wikitool-local.json` and creates `<target>/` and `<target>/git`, the latter as a bare repository (`git init --bare -b main`). An existing bare repository there, or an empty directory, is used as it is.
 - Sets `origin` to `<target>/git` when the checkout has no `origin`. An `origin` that already pushes there is left as it is; one that pushes anywhere else stops the command.
 - When `remotes.allowed_push_urls` exists and lacks the URL `origin` pushes to, prints the `remotes` section with that URL added, for the user to copy into `.wikitool-local.json`. It never writes that file: the field is a gate.
 - Pushes nothing: the next `publish` sends the history to the new `origin`.
 **SEE ALSO**
 - `wikitool backup run` - the machine-data half of the backup
 - `wikitool publish` - pushes to the bare repository and runs the machine-data backup after it
 - `docs/how-to/back-up-to-a-synced-folder.md` - the whole procedure, restoring included
 #### `backup run`
 Mirror this machine's files that are not in git into `<target>/<machine>/`.
 **SYNOPSIS**
 - `wikitool backup run`
 **PROPERTIES**
 - effect: write
 - idempotent: yes
 - atomic: Per file - each is written to a temporary file and renamed, the manifest last; an interrupted run leaves whole files and the previous manifest
 - budget: counted
 - network: no
 **EXAMPLES**
 - `tools/wikitool backup run`
 **EXIT STATUS**
 - 0    success
 - 1    No `backup` section in `.wikitool-local.json`, or a malformed one - a target that is not absolute or lies inside the instance, a `machine_name` that cleans to nothing or to `git`, an `extra` path that resolves outside the instance or into `.git/`
 - 1    `machine_data` is false
 - 1    `<target>/<machine>/` is not empty and has no manifest, or its manifest cannot be read; nothing was written
 - 1    The target is not a directory (the synced folder is missing or not mounted), or a write failed
 **ON FAILURE**
 - No `backup` section in `.wikitool-local.json`, or a malformed one - a target that is not absolute or lies inside the instance, a `machine_name` that cleans to nothing or to `git`, an `extra` path that resolves outside the instance or into `.git/` -> Show the message to the user and stop. The section is theirs to write or fix by hand - `config set` refuses its fields; docs/how-to/back-up-to-a-synced-folder.md has the procedure
 - `machine_data` is false -> Show the message to the user; turning it on is their edit of `.wikitool-local.json`
 - `<target>/<machine>/` is not empty and has no manifest, or its manifest cannot be read; nothing was written -> Show the message to the user - the folder is not one this backup wrote. They set another `machine_name` or empty it
 - The target is not a directory (the synced folder is missing or not mounted), or a write failed -> Show the message to the user; once the cause is fixed, run `backup run` again
 **NEVER**
 - Never point `extra` at a path outside the instance to back something else up - the command refuses it, and the secrets belong in no synced folder.
 **NOTES**
 - Mirrors `.wikitool-local.json`, `ENVIRONMENT.md` if present, every file in `incoming/` but `.gitkeep`, and the `extra` paths of the `backup` section into `<target>/<machine>/`, then writes the manifest `.chemenu-backup.json` there: time, stack version, machine name, and per file its relative path, size and sha256.
 - Never mirrors `mcp-upload/`, `reports/`, `.wikitool-tools.json`, `tools/.venv/`, the published skills or `.git/` - unless an `extra` path names one of the first ones. The secrets file lies outside the instance and is never read.
 - Writes and deletes only under `<target>/<machine>/`. Deletes only a file the previous manifest lists and the instance no longer has; a file there the manifest does not list stays as it is. A file whose size and sha256 match the previous manifest is not rewritten.
 - A symbolic link or junction inside a mirrored directory is skipped and named in the output, never followed.
 - `publish` runs the same step after every push when `machine_data` is true.
 **SEE ALSO**
 - `wikitool backup init` - sets up the target's bare repository
 - `wikitool doctor` - the `backup` line reports the age of the last run
 - `docs/how-to/back-up-to-a-synced-folder.md` - the whole procedure, restoring included
 ### Guideline export
@@ -3907,6 +4016,8 @@ Check that this instance is correctly configured.
 - KB conventions: `kb/CONVENTIONS.md` present, unsentinelled, and naming all three tool-owned section headings - a `FAIL` on any of the three.
 - Environment note: `ENVIRONMENT.md` is optional, so absent is `OK`; a still-templated one is a `WARN`.
 - Legacy settings (`legacy-settings`): one `FAIL` for each per-feature settings file of an earlier version (telemetry, remotes, upload, task tracker) that is still there. Nothing reads them any more, so the settings they hold are not in effect; the fix is `tools/wikitool config migrate`.
 - Synced folder (`sync-folder`): a `WARN` when the git directory, links and junctions resolved, lies under a folder named by `OneDrive`, `OneDriveCommercial` or `OneDriveConsumer` (compared without regard to case on Windows) or under `~/Library/CloudStorage/` (macOS); `OK` otherwise, never a `FAIL`.
 - Backup (`backup`): the `backup` section absent is `OK`, malformed is a `FAIL`. Configured, a `WARN` when `<target>/git` is not a bare repository, `origin` does not push there, or - with `machine_data` true - no machine-data backup exists yet; otherwise `OK` with the age of the last machine-data backup.
 - MCP `submit` tool: whether the `upload` section of the settings is present, absent or malformed, its limits, and how many submissions wait in `mcp-upload/`. Absent is `OK` and means the write path does not exist at all; malformed is a `FAIL`.
 - Task tracker: the `tasks` section present, absent or malformed - absent is `OK` (no tracker configured), malformed is a `FAIL`. When `WIKITOOL_TASKS_CONFIG` is set, the profile it names is read instead of the `tasks`, `superproductivity` and `caldav` sections and the finding names it; a set variable that names no file is a `FAIL`, never `OK`.
 - For a configured `superproductivity` provider, the configured `access` path's own state: `access: "api"` reports whether its local REST API answers `GET /health` with a ready renderer right now, `access: "snapshot"` whether a backup file is ready. The other access path is never attempted, and neither state is ever a `FAIL`.
@@ -3925,6 +4036,7 @@ Check that this instance is correctly configured.
 - `instructions/preflight.md` - what `tool-paths` and `install-dir` point back to
 - `docs/reference/configuration.md` - the per-checkout configuration files and the tiered settings
 - `docs/explanation/telemetry-and-evaluation.md` - telemetry state and caps
 - `docs/how-to/back-up-to-a-synced-folder.md` - what `sync-folder` and `backup` point to
 - `instructions/session-setup.md` - setting `WIKITOOL_SESSION_ID`
 <!-- /wikitool:commands -->
 ## Design notes
@@ -130,6 +130,7 @@ tools/
    browser.py             the optional browser component (Playwright, `requirements-browser.txt`): `raw login`'s visible window and the headless fetch of a page a handler declares `render` - imported lazily, so a venv without it runs everything else
    sites/                 the site handlers behind `raw fetch`: a registry (`__init__.py`), the JSON file format (`site.schema.json`, `data.py`) and the stack's handlers as one file per website under `handlers/`, each stating the standard form of its URLs, the page furniture to leave out of the derived text, hint lines, which links are subpages for `raw fetch --scope`, a website's login page and the sign of a signed-in page, and whether its pages need a browser - all of it data (rewrites, selectors, text); the instance's own sit in `sites/` at the root
    filters/               the import filters behind `raw derive`: a registry (`__init__.py`) and one module per format family (HTML, mail, Outlook MSG, Office, PDF, ZIP), each registering the extensions it reads - standard library, or a package imported lazily so a missing one fails only its own format
    backup.py              `backup init`/`backup run`'s core and the step `publish` runs after a push: the bare repository under `<target>/git`, the machine-data mirror under `<target>/<machine>/` with its manifest, and which synced folders `doctor` knows
    repo_capture.py        `raw capture`/`raw status`'s core: resolve a ref rule, fetch it into a bare cache, select files by glob as blobs, the `_capture.json` manifest - git with the host's credentials, never a prompt; plus the one write back, a single-file commit pushed without force for `export guidelines`
    guideline_export.py    `export guidelines`' core: select pages by `search` predicates, render them into one deterministic GUIDELINES.md, and recognise an export again (`EXPORT_MARKER`) - with no CLI attached
    search/                pluggable search backends, plus service.py - the search core
@@ -0,0 +1,563 @@
 """Backing an instance up into a folder a sync client uploads (OneDrive and the like).
 The working tree stays out of that folder: a sync client locks files under
 `.git` for a moment (which breaks `git gc` and `repack`), offloads them as
 placeholders, and makes conflict copies inside `.git` as soon as a second device
 syncs the same folder. What goes into the synced folder is a backup target with
 this layout (`config_shapes.BACKUP` is the section that names it):
    <target>/git/          a bare repository, the checkout's `origin`; `publish` pushes to it
    <target>/<machine>/    a mirror of this machine's files that are not in git,
                           plus the manifest `.chemenu-backup.json`
 Git writes into the bare repository only on a push, with one writer, so the
 sync client sees mostly new, immutable object files.
 What a machine-data run guarantees - each one has its test:
 - It writes and deletes only under `<target>/<machine>/`. Nothing outside it
  changes - not `<target>/git`, not another machine's folder.
 - It deletes only what the previous manifest lists and is gone locally. A file
  in the folder the manifest does not list stays as it is.
 - It refuses a non-empty `<target>/<machine>/` without a manifest, before it
  writes anything: it never mirrors into a folder it did not write.
 - It reads nothing outside the instance. An `extra` path that resolves outside
  is an error of the section; a symbolic link (or junction) inside a mirrored
  directory is skipped and reported, never followed; `.git` is never mirrored.
 - Every file is written atomically - a temporary file in the same directory,
  then `os.replace` - and the manifest last, so an interrupted run leaves whole
  files and the previous run's manifest.
 The secrets file lives outside the instance (`config.secrets_file`), so the last
 two rules keep it out of the synced folder as well.
 """
 from __future__ import annotations
 import hashlib
 import json
 import os
 import socket
 import subprocess
 import tempfile
 import time
 from dataclasses import dataclass, field
 from datetime import datetime, timezone
 from pathlib import Path
 from typing import Optional
 from chemenu import config, config_shapes, settings, toolpaths
 from chemenu.errors import ValidationError
 MANIFEST_NAME = ".chemenu-backup.json"
 MANIFEST_SCHEMA = 1
 INCOMING_DIR = "incoming"
 INCOMING_KEEP = ".gitkeep"
 GIT_NAME = ".git"
 # The files at the root of the instance a machine-data run mirrors when they exist.
 ROOT_FILES = (config.LOCAL_SETTINGS_FILENAME, config.ENVIRONMENT_FILE)
 # Where a sync client keeps its folder: the variables the OneDrive client sets on
 # Windows, and the folder macOS's File Provider puts every sync client under.
 SYNC_ENV_VARS = ("OneDrive", "OneDriveCommercial", "OneDriveConsumer")
 MAC_CLOUD_STORAGE = ("Library", "CloudStorage")
 # Windows compares paths without regard to case; a test sets this to compare
 # that way on another platform.
 IGNORE_CASE = os.name == "nt"
 # OneDrive holds a file it is uploading open for a moment; `os.replace` onto it
 # then fails with a sharing violation that is gone a second later.
 _REPLACE_ATTEMPTS = 5
 _REPLACE_PAUSE_SECONDS = 0.4
 class BackupError(ValidationError):
    """A backup step refused or failed; exit 1 with the message."""
@dataclass(frozen=True)
 class BackupConfig:
    target: Path
    machine_data: bool
    machine_name: str
    extra: tuple[str, ...]
    @property
    def git_dir(self) -> Path:
        return self.target / config_shapes.BACKUP_GIT_DIR
    @property
    def machine_dir(self) -> Path:
        return self.target / self.machine_name
    @property
    def manifest(self) -> Path:
        return self.machine_dir / MANIFEST_NAME
 # ---------------------------------------------------------------------------
 # Paths
 # ---------------------------------------------------------------------------
 def _is_link(path: Path) -> bool:
    is_junction = getattr(path, "is_junction", None)  # Python 3.12+
    return path.is_symlink() or bool(is_junction and is_junction())
 def _real(path: Path) -> Path:
    return Path(os.path.realpath(path))
 def is_under(path: Path, root: Path, ignore_case: Optional[bool] = None) -> bool:
    """Whether `path` is `root` or lies below it, both taken as given."""
    ignore_case = IGNORE_CASE if ignore_case is None else ignore_case
    inner, outer = str(path), str(root).rstrip("/\\")
    if ignore_case:
        inner, outer = inner.casefold(), outer.casefold()
    return inner == outer or inner.startswith(outer + os.sep) or inner.startswith(outer + "/")
 def _names_git(parts) -> bool:
    return any(part.casefold() == GIT_NAME for part in parts)
 def _safe_relative(rel: str) -> bool:
    """Whether `rel`, a `/`-separated path, stays below the folder it is joined
    to on every platform: no empty, `.` or `..` part, no backslash, no drive."""
    parts = rel.split("/")
    return bool(rel) and all(part not in ("", ".", "..") and "\\" not in part and ":" not in part
                             for part in parts)
 def _within(machine_dir: Path, rel: str) -> Path:
    """`rel` below `machine_dir`, refusing a path that would leave it - by its
    spelling, or through a link somewhere in the folder."""
    if not _safe_relative(rel):
        raise BackupError(f"{rel!r} is not a path below {machine_dir} - nothing further was written")
    dest = machine_dir.joinpath(*rel.split("/"))
    current = machine_dir
    for part in rel.split("/")[:-1]:
        current = current / part
        if _is_link(current):
            raise BackupError(f"{current} is a link - a backup writes nothing through one")
    return dest
 # ---------------------------------------------------------------------------
 # Reading the section
 # ---------------------------------------------------------------------------
 def _extra_problem(root: Path, real_root: Path, entry: str) -> Optional[str]:
    if _names_git(Path(entry).parts):
        return f"backup.extra holds {entry!r}, which names {GIT_NAME}/ - it is never backed up"
    try:
        resolved = (root / entry).resolve()
    except (OSError, RuntimeError) as exc:
        return f"backup.extra holds {entry!r}, which cannot be resolved ({exc})"
    if not is_under(resolved, real_root):
        return (f"backup.extra holds {entry!r}, which resolves to {resolved}, outside the "
                "instance - a backup reads nothing outside it")
    if _names_git(resolved.relative_to(real_root).parts):
        return f"backup.extra holds {entry!r}, which resolves into {GIT_NAME}/ - it is never backed up"
    return None
 def read_config(root: "Path | str | None" = None) -> Optional[BackupConfig]:
    """The `backup` section, or None when the settings carry none. Raises
    `ValidationError` for a section that is broken - including what the record
    cannot judge without the instance: a target inside it, an `extra` path that
    leaves it, a host name that cleans to nothing."""
    root = Path(config.ROOT if root is None else root)
    key = config_shapes.BACKUP.key
    section = settings.load(root, only=(key,)).section(key)
    if not section.configured:
        return None
    problems = []
    real_root = _real(root)
    target = Path(section["target"])
    if not os.path.isabs(section["target"]):
        problems.append(f"backup.target {section['target']!r} is not an absolute path on this machine")
    else:
        real_target = _real(target)
        if is_under(real_target, real_root):
            problems.append(f"backup.target {target} lies inside the instance - it belongs outside it")
    if "machine_name" in section.given:
        name, origin = section["machine_name"], ""
    else:
        name, origin = socket.gethostname(), " (the host name, since machine_name is not set)"
    problem = config_shapes.machine_name_problem(name)
    if problem:
        problems.append(f"backup.machine_name {name!r}{origin} {problem} - set machine_name")
    machine_name = config_shapes.machine_name(name)
    if not problems:
        for inner in (target / config_shapes.BACKUP_GIT_DIR, target / machine_name):
            if is_under(real_root, _real(inner)):
                problems.append(f"the instance lies inside {inner}, which the backup writes to")
    for entry in section["extra"]:
        found = _extra_problem(root, real_root, entry)
        if found:
            problems.append(found)
    if problems:
        raise ValidationError("; ".join(problems))
    return BackupConfig(target=target, machine_data=section["machine_data"],
                        machine_name=machine_name, extra=tuple(section["extra"]))
 def require_config(root: "Path | str | None" = None) -> BackupConfig:
    found = read_config(root)
    if found is None:
        raise BackupError(
            f"no backup section in {config.LOCAL_SETTINGS_FILENAME} - the user adds it by hand "
            "(docs/how-to/back-up-to-a-synced-folder.md)"
        )
    return found
 # ---------------------------------------------------------------------------
 # git
 # ---------------------------------------------------------------------------
 def _git(args: list[str], cwd: Path) -> subprocess.CompletedProcess:
    return subprocess.run([toolpaths.git(), *args], cwd=cwd, capture_output=True, text=True,
                          encoding="utf-8", errors="replace")
 def is_bare_repo(path: Path) -> bool:
    if not path.is_dir():
        return False
    result = _git(["--git-dir", str(path), "rev-parse", "--is-bare-repository"], cwd=path)
    return result.returncode == 0 and result.stdout.strip() == "true"
 def push_url(root: Path, remote: str = "origin") -> Optional[str]:
    result = _git(["remote", "get-url", "--push", remote], cwd=root)
    if result.returncode != 0:
        return None
    return result.stdout.strip() or None
 def same_location(url: str, path: Path, root: Path) -> bool:
    """Whether the remote URL `url` names the directory `path`. A URL with a
    scheme other than `file://`, or an scp-like `host:path`, never does."""
    local = url[len("file://"):] if url.startswith("file://") else url
    if "://" in local or (":" in local and not os.path.isabs(local)):
        return False
    a, b = os.path.normcase(_real(root / local)), os.path.normcase(_real(path))
    return a.casefold() == b.casefold() if IGNORE_CASE else a == b
 def _directory_state(path: Path) -> str:
    if not path.exists() and not _is_link(path):
        return "absent"
    if path.is_dir() and not _is_link(path) and not any(path.iterdir()):
        return "empty"
    return "bare" if is_bare_repo(path) else "other"
@dataclass
 class InitResult:
    git_dir: Path
    created_repo: bool
    set_origin: bool
    allowlist_entry: Optional[str]
 def allowlist_entry(root: Path, url: str) -> Optional[str]:
    """The `remotes` section as it would read with `url` added, when it exists
    and lacks `url` - printed for the user to copy, never written: the field is
    a gate."""
    key = config_shapes.REMOTES.key
    section = settings.load(root, only=(key,)).section(key)
    if not section.configured:
        return None
    allowed = list(section["allowed_push_urls"])
    if url in allowed:
        return None
    return json.dumps({key: {"allowed_push_urls": [*allowed, url]}}, indent=2, ensure_ascii=False)
 def init(cfg: BackupConfig, root: "Path | str | None" = None) -> InitResult:
    """Create `<target>/git` as a bare repository and make it `origin` when
    there is none. Checks everything first and changes nothing on a refusal."""
    root = Path(config.ROOT if root is None else root)
    state = _directory_state(cfg.git_dir)
    if state == "other":
        raise BackupError(
            f"{cfg.git_dir} exists and is not a bare git repository - nothing was changed. Move it "
            "away, or point backup.target at another folder"
        )
    current = push_url(root)
    if current is not None and not same_location(current, cfg.git_dir, root):
        raise BackupError(
            f"origin already pushes to {current}, not to {cfg.git_dir} - nothing was changed. "
            f"Whether origin moves is the user's decision: git remote set-url origin \"{cfg.git_dir}\""
        )
    created = False
    if state != "bare":
        cfg.git_dir.mkdir(parents=True, exist_ok=True)
        result = _git(["init", "--bare", "--quiet", "-b", "main", str(cfg.git_dir)], cwd=root)
        if result.returncode != 0:
            raise BackupError(f"git init --bare {cfg.git_dir} failed:\n{result.stderr}")
        created = True
    set_origin = False
    if current is None:
        result = _git(["remote", "add", "origin", str(cfg.git_dir)], cwd=root)
        if result.returncode != 0:
            raise BackupError(f"git remote add origin failed:\n{result.stderr}")
        set_origin, current = True, str(cfg.git_dir)
    return InitResult(cfg.git_dir, created, set_origin, allowlist_entry(root, current))
 # ---------------------------------------------------------------------------
 # Machine data
 # ---------------------------------------------------------------------------
@dataclass
 class Collected:
    files: dict = field(default_factory=dict)   # relative posix path -> source Path
    skipped: list = field(default_factory=list)  # "<path> (<why>)"
 def _walk(path: Path, rel: str, out: Collected) -> None:
    if _is_link(path):
        out.skipped.append(f"{rel} (a link - not followed)")
        return
    if path.name.casefold() == GIT_NAME:
        return
    if path.is_file():
        if rel == MANIFEST_NAME:
            out.skipped.append(f"{rel} (the manifest's own name)")
        elif not _safe_relative(rel):
            out.skipped.append(f"{rel} (a name that cannot be mirrored on every platform)")
        else:
            out.files.setdefault(rel, path)
        return
    if path.is_dir():
        for child in sorted(path.iterdir()):
            _walk(child, f"{rel}/{child.name}" if rel else child.name, out)
 def collect(cfg: BackupConfig, root: "Path | str | None" = None) -> Collected:
    """What a machine-data run mirrors: the root files that exist, everything in
    `incoming/` but its `.gitkeep`, and `extra`."""
    root = Path(config.ROOT if root is None else root)
    real_root = _real(root)
    out = Collected()
    for name in ROOT_FILES:
        if (root / name).exists() or _is_link(root / name):
            _walk(root / name, name, out)
    incoming = root / INCOMING_DIR
    if _is_link(incoming):
        out.skipped.append(f"{INCOMING_DIR} (a link - not followed)")
    elif incoming.is_dir():
        for child in sorted(incoming.iterdir()):
            if child.name != INCOMING_KEEP:
                _walk(child, f"{INCOMING_DIR}/{child.name}", out)
    for entry in cfg.extra:
        resolved = (root / entry).resolve()
        if not is_under(resolved, real_root):  # read_config refuses this; never read it anyway
            raise BackupError(f"backup.extra {entry!r} resolves outside the instance")
        if not resolved.exists():
            out.skipped.append(f"{entry} (not present)")
            continue
        rel = resolved.relative_to(real_root).as_posix()
        _walk(resolved, "" if rel == "." else rel, out)
    return out
 def _digest(path: Path) -> tuple[int, str]:
    sha, size = hashlib.sha256(), 0
    with open(path, "rb") as handle:
        for chunk in iter(lambda: handle.read(1 << 20), b""):
            sha.update(chunk)
            size += len(chunk)
    return size, sha.hexdigest()
 def _replace(tmp: str, dest: Path) -> None:
    for attempt in range(_REPLACE_ATTEMPTS):
        try:
            os.replace(tmp, dest)
            return
        except PermissionError:
            if attempt == _REPLACE_ATTEMPTS - 1:
                raise
            time.sleep(_REPLACE_PAUSE_SECONDS)
 def _write_atomic(dest: Path, chunks) -> tuple[int, str]:
    dest.parent.mkdir(parents=True, exist_ok=True)
    fd, tmp = tempfile.mkstemp(prefix=".chemenu-", suffix=".tmp", dir=str(dest.parent))
    sha, size = hashlib.sha256(), 0
    try:
        with os.fdopen(fd, "wb") as out:
            for chunk in chunks:
                out.write(chunk)
                sha.update(chunk)
                size += len(chunk)
            out.flush()
            os.fsync(out.fileno())
        _replace(tmp, dest)
    except BaseException:
        Path(tmp).unlink(missing_ok=True)
        raise
    return size, sha.hexdigest()
 def _copy_atomic(src: Path, dest: Path) -> tuple[int, str]:
    with open(src, "rb") as handle:
        return _write_atomic(dest, iter(lambda: handle.read(1 << 20), b""))
 def read_manifest(machine_dir: Path) -> Optional[dict]:
    """The manifest of the last run into `machine_dir`, or None when there is
    none. Raises `BackupError` for one that cannot be read as one."""
    path = machine_dir / MANIFEST_NAME
    if not path.exists():
        return None
    try:
        data = json.loads(path.read_text(encoding="utf-8"))
    except (OSError, ValueError) as exc:
        raise BackupError(f"{path} cannot be read ({exc}) - nothing was written") from None
    files = data.get("files") if isinstance(data, dict) else None
    if not isinstance(files, list) or not all(
        isinstance(entry, dict) and isinstance(entry.get("path"), str)
        and _safe_relative(entry["path"]) and isinstance(entry.get("size"), int)
        and isinstance(entry.get("sha256"), str)
        for entry in files
    ):
        raise BackupError(f"{path} is not a backup manifest - nothing was written")
    return data
@dataclass
 class RunResult:
    machine_dir: Path
    written: list = field(default_factory=list)
    unchanged: list = field(default_factory=list)
    removed: list = field(default_factory=list)
    skipped: list = field(default_factory=list)
    def summary(self) -> str:
        line = (f"Machine data backed up to {self.machine_dir}: {len(self.written)} written, "
                f"{len(self.unchanged)} unchanged, {len(self.removed)} removed")
        if self.skipped:
            line += f"; skipped: {', '.join(self.skipped)}"
        return line
 def _prune_empty(directory: Path, stop: Path) -> None:
    while directory != stop and is_under(directory, stop):
        try:
            directory.rmdir()
        except OSError:
            return
        directory = directory.parent
 def _stack_version() -> Optional[str]:
    from chemenu import version as version_mod
    try:
        return str(version_mod.read_version())
    except version_mod.VersionError:
        return None
 def run(cfg: BackupConfig, root: "Path | str | None" = None) -> RunResult:
    """Mirror this machine's files into `<target>/<machine>/` and write its
    manifest. See the module docstring for what it guarantees."""
    root = Path(config.ROOT if root is None else root)
    if not cfg.target.is_dir():
        raise BackupError(
            f"the backup target {cfg.target} is not a directory - nothing was written. Is the "
            "synced folder there? `tools/wikitool backup init` creates the target"
        )
    machine_dir = cfg.machine_dir
    if _is_link(machine_dir) or (machine_dir.exists() and not machine_dir.is_dir()):
        raise BackupError(f"{machine_dir} is not a plain directory - nothing was written")
    previous = read_manifest(machine_dir)
    if previous is None and machine_dir.is_dir() and any(machine_dir.iterdir()):
        raise BackupError(
            f"{machine_dir} is not empty and has no {MANIFEST_NAME} - it is not a folder this "
            "backup wrote, so nothing was written. Set another backup.machine_name, or empty it"
        )
    collected = collect(cfg, root)
    result = RunResult(machine_dir, skipped=list(collected.skipped))
    before = {entry["path"]: entry for entry in (previous or {}).get("files", [])}
    entries = []
    machine_dir.mkdir(exist_ok=True)
    for rel, source in sorted(collected.files.items()):
        dest = _within(machine_dir, rel)
        size, digest = _digest(source)
        old = before.get(rel)
        if (old and old["size"] == size and old["sha256"] == digest and dest.is_file()
                and not _is_link(dest) and dest.stat().st_size == size):
            result.unchanged.append(rel)
        else:
            size, digest = _copy_atomic(source, dest)
            result.written.append(rel)
        entries.append({"path": rel, "size": size, "sha256": digest})
    for rel in sorted(set(before) - set(collected.files)):
        dest = _within(machine_dir, rel)
        if dest.is_file() and not _is_link(dest):
            dest.unlink()
            result.removed.append(rel)
            _prune_empty(dest.parent, machine_dir)
    manifest = {
        "schema": MANIFEST_SCHEMA,
        "created": datetime.now(timezone.utc).isoformat(timespec="seconds"),
        "stack_version": _stack_version(),
        "machine": cfg.machine_name,
        "files": entries,
    }
    text = json.dumps(manifest, indent=2, ensure_ascii=False) + "\n"
    _write_atomic(cfg.manifest, [text.encode("utf-8")])
    return result
 # ---------------------------------------------------------------------------
 # Synced folders (`doctor`)
 # ---------------------------------------------------------------------------
 def sync_roots() -> list[Path]:
    """The folders a sync client keeps on this machine, as far as it says."""
    roots = [Path(value) for value in (os.environ.get(var, "").strip() for var in SYNC_ENV_VARS) if value]
    roots.append(Path.home().joinpath(*MAC_CLOUD_STORAGE))
    return roots
 def synced_folder_of(path: Path) -> Optional[Path]:
    """The synced folder `path` lies in, links and junctions resolved on both
    sides, or None."""
    real = _real(path)
    for candidate in sync_roots():
        if is_under(real, _real(candidate)):
            return candidate
    return None
 def age_text(created: str, now: Optional[datetime] = None) -> str:
    try:
        then = datetime.fromisoformat(created)
    except (TypeError, ValueError):
        return "of unknown age"
    seconds = ((now or datetime.now(timezone.utc)) - then).total_seconds()
    for limit, unit in ((86400, "d"), (3600, "h"), (60, "min")):
        if seconds >= limit:
            return f"{int(seconds // limit)} {unit} old"
    return "less than a minute old"
@@ -26,6 +26,7 @@ from chemenu import toolpaths  # noqa: E402
 try:
    from chemenu.commands import (
        _util,
        backup_cmd,
        cite_cmd,
        config_cmd,
        dist_cmd,
@@ -182,6 +183,7 @@ app.add_typer(migrate_cmd.app, name="migrate")
 app.add_typer(task_cmd.app, name="task")
 app.add_typer(export_cmd.app, name="export")
 app.add_typer(config_cmd.app, name="config")
 app.add_typer(backup_cmd.app, name="backup")
 app.command("new")(new_page.new_page_command)
 app.command("touch")(touch_module.touch_command)
 app.command("rename")(page_ops.rename_command)
@@ -291,7 +291,7 @@ GROUPS: tuple[tuple[str, tuple[str, ...]], ...] = (
        "upload list", "upload show", "upload accept", "upload reject",
    )),
    ("Git", (
-        "sync", "publish",
+        "sync", "publish", "backup init", "backup run",
    )),
    ("Guideline export", (
        "export guidelines",
@@ -0,0 +1,169 @@
 """`wikitool backup init` and `backup run` - back an instance up into a synced folder.
 The mechanism and what a run guarantees are `chemenu.backup`'s; this module only
 turns its results and refusals into output and exit codes. `publish` runs the
 same machine-data step after a push (`git_publish.publish_command`).
 """
 from __future__ import annotations
 import typer
 from chemenu import backup, cli_contract, config
 from chemenu.commands._util import fail, success
 from chemenu.errors import ChemenuError
 app = typer.Typer(help="Back this instance up into a synced folder (OneDrive and the like).")
 HOW_TO = "docs/how-to/back-up-to-a-synced-folder.md"
 _SECTION_FAILURE = cli_contract.Failure(
    cause=f"No `backup` section in `{config.LOCAL_SETTINGS_FILENAME}`, or a malformed one - a "
    "target that is not absolute or lies inside the instance, a `machine_name` that cleans to "
    "nothing or to `git`, an `extra` path that resolves outside the instance or into `.git/`",
    reaction=f"Show the message to the user and stop. The section is theirs to write or fix by "
    f"hand - `config set` refuses its fields; {HOW_TO} has the procedure",
 )
@app.command("init")
@cli_contract.record(cli_contract.CommandRecord(
    path="backup init",
    summary="Create the backup target's bare repository and make it `origin` when there is none.",
    synopsis=(cli_contract.Variant(usage="backup init"),),
    properties=cli_contract.Properties(
        effect=cli_contract.Effect.WRITE,
        idempotent=cli_contract.Idempotent.YES,
        atomic="Every precondition is checked first; a refusal changes nothing",
        budget=cli_contract.Budget.COUNTED,
    ),
    notes=(
        "Reads the `backup` section of `.wikitool-local.json` and creates `<target>/` and "
        "`<target>/git`, the latter as a bare repository (`git init --bare -b main`). An existing "
        "bare repository there, or an empty directory, is used as it is.",
        "Sets `origin` to `<target>/git` when the checkout has no `origin`. An `origin` that "
        "already pushes there is left as it is; one that pushes anywhere else stops the command.",
        "When `remotes.allowed_push_urls` exists and lacks the URL `origin` pushes to, prints the "
        "`remotes` section with that URL added, for the user to copy into "
        "`.wikitool-local.json`. It never writes that file: the field is a gate.",
        "Pushes nothing: the next `publish` sends the history to the new `origin`.",
    ),
    failures=(
        _SECTION_FAILURE,
        cli_contract.Failure(
            cause="`<target>/git` exists and is not a bare repository; nothing was changed",
            reaction="Show the message to the user - whether that folder moves, or the target "
            "does, is their decision",
        ),
        cli_contract.Failure(
            cause="`origin` already pushes to another URL; the message names both and nothing was "
            "changed",
            reaction="Show both URLs to the user and stop. Never repoint `origin` yourself - "
            "`git remote set-url` is theirs to run",
        ),
    ),
    examples=("tools/wikitool backup init",),
    never=(
        "Never add the printed URL to `remotes.allowed_push_urls` yourself - that field is a gate, "
        "and editing it is the user's.",
    ),
    see_also=(
        "`wikitool backup run` - the machine-data half of the backup",
        "`wikitool publish` - pushes to the bare repository and runs the machine-data backup "
        "after it",
        f"`{HOW_TO}` - the whole procedure, restoring included",
    ),
 ))
 def init_command():
    """Create the backup target's bare repository and make it `origin` when there is none."""
    try:
        cfg = backup.require_config()
        result = backup.init(cfg)
    except ChemenuError as exc:
        fail(str(exc))
    if result.created_repo:
        typer.echo(f"Created the bare repository {result.git_dir}.")
    else:
        typer.echo(f"{result.git_dir} is already a bare repository - left as it is.")
    if result.set_origin:
        typer.echo(f"Set origin to {result.git_dir}.")
    if result.allowlist_entry:
        typer.echo(
            "remotes.allowed_push_urls does not list this push target, so `publish` will stop at "
            "the Publish-Remote Gate. THE USER CANNOT SEE THIS OUTPUT - show them this section, to "
            f"put into {config.LOCAL_SETTINGS_FILENAME} themselves:\n{result.allowlist_entry}"
        )
    success("Backup target ready; the next `publish` pushes to it.")
@app.command("run")
@cli_contract.record(cli_contract.CommandRecord(
    path="backup run",
    summary="Mirror this machine's files that are not in git into `<target>/<machine>/`.",
    synopsis=(cli_contract.Variant(usage="backup run"),),
    properties=cli_contract.Properties(
        effect=cli_contract.Effect.WRITE,
        idempotent=cli_contract.Idempotent.YES,
        atomic="Per file - each is written to a temporary file and renamed, the manifest last; an "
        "interrupted run leaves whole files and the previous manifest",
        budget=cli_contract.Budget.COUNTED,
    ),
    notes=(
        "Mirrors `.wikitool-local.json`, `ENVIRONMENT.md` if present, every file in `incoming/` "
        "but `.gitkeep`, and the `extra` paths of the `backup` section into "
        "`<target>/<machine>/`, then writes the manifest `.chemenu-backup.json` there: time, "
        "stack version, machine name, and per file its relative path, size and sha256.",
        "Never mirrors `mcp-upload/`, `reports/`, `.wikitool-tools.json`, `tools/.venv/`, the "
        "published skills or `.git/` - unless an `extra` path names one of the first ones. The "
        "secrets file lies outside the instance and is never read.",
        "Writes and deletes only under `<target>/<machine>/`. Deletes only a file the previous "
        "manifest lists and the instance no longer has; a file there the manifest does not list "
        "stays as it is. A file whose size and sha256 match the previous manifest is not "
        "rewritten.",
        "A symbolic link or junction inside a mirrored directory is skipped and named in the "
        "output, never followed.",
        "`publish` runs the same step after every push when `machine_data` is true.",
    ),
    failures=(
        _SECTION_FAILURE,
        cli_contract.Failure(
            cause="`machine_data` is false",
            reaction="Show the message to the user; turning it on is their edit of "
            "`.wikitool-local.json`",
        ),
        cli_contract.Failure(
            cause="`<target>/<machine>/` is not empty and has no manifest, or its manifest cannot "
            "be read; nothing was written",
            reaction="Show the message to the user - the folder is not one this backup wrote. "
            "They set another `machine_name` or empty it",
        ),
        cli_contract.Failure(
            cause="The target is not a directory (the synced folder is missing or not mounted), "
            "or a write failed",
            reaction="Show the message to the user; once the cause is fixed, run `backup run` "
            "again",
        ),
    ),
    examples=("tools/wikitool backup run",),
    never=(
        "Never point `extra` at a path outside the instance to back something else up - the "
        "command refuses it, and the secrets belong in no synced folder.",
    ),
    see_also=(
        "`wikitool backup init` - sets up the target's bare repository",
        "`wikitool doctor` - the `backup` line reports the age of the last run",
        f"`{HOW_TO}` - the whole procedure, restoring included",
    ),
 ))
 def run_command():
    """Mirror this machine's files that are not in git into `<target>/<machine>/`."""
    try:
        cfg = backup.require_config()
        if not cfg.machine_data:
            fail(f"backup.machine_data is false in {config.LOCAL_SETTINGS_FILENAME} - there is "
                 "nothing to back up with `backup run`; the user sets it to true by hand")
        result = backup.run(cfg)
    except ChemenuError as exc:
        fail(str(exc))
    except OSError as exc:
        fail(f"the machine-data backup failed: {exc}")
    success(result.summary())
@@ -16,6 +16,7 @@ import shutil
 import subprocess
 import sys
 from dataclasses import dataclass
 from pathlib import Path
 from typing import Optional
 import typer
@@ -51,6 +52,7 @@ def _git(args: list[str]) -> Optional[subprocess.CompletedProcess]:
 PREFLIGHT_FIX = f"Run tools/preflight.sh (PowerShell 7: {toolpaths.PREFLIGHT_PWSH})"
 BACKUP_HOW_TO = "docs/how-to/back-up-to-a-synced-folder.md"
 def check_python() -> Check:
@@ -260,7 +262,8 @@ def check_git_repo() -> list[Check]:
            Check(
                "git-remote", "WARN", "No 'origin' remote configured",
                "A local-only instance is valid - `git remote add origin <url>` if you want one. "
-                "Every `publish` needs --no-push until then",
+                "Every `publish` needs --no-push until then. Without a git server, a synced "
                f"folder can serve: {BACKUP_HOW_TO}",
            )
        )
    return checks
@@ -492,6 +495,77 @@ def check_publish_remotes() -> Check:
    )
 def check_sync_folder() -> Check:
    """Whether the git directory lies in a folder a sync client uploads. Never a
    `FAIL`: the instance works there, until the sync client locks, offloads or
    conflict-copies a file under `.git` - which is what the `WARN` is for."""
    from chemenu import backup
    result = _git(["rev-parse", "--absolute-git-dir"])
    if result is None or result.returncode != 0 or not result.stdout.strip():
        return Check("sync-folder", "OK", "no git directory to check")
    git_dir = result.stdout.strip()
    synced = backup.synced_folder_of(Path(git_dir))
    if synced is None:
        return Check("sync-folder", "OK", f"{git_dir} lies outside every synced folder this machine names")
    return Check(
        "sync-folder", "WARN",
        f"{git_dir} lies in the synced folder {synced} - a sync client locks files under .git for "
        "a moment (which breaks `git gc`), offloads them as placeholders, and makes conflict "
        "copies once a second device syncs it",
        f"Move the instance out of the synced folder and back it up into it instead: {BACKUP_HOW_TO}. "
        "On Windows, check whether Documents or Desktop is redirected into OneDrive (Known Folder "
        "Move) - an instance there lies in OneDrive without looking like it",
    )
 def check_backup() -> Check:
    """The `backup` section: absent is `OK` (no backup configured), malformed is
    a `FAIL`, and a configured one whose target or `origin` is not set up, or
    whose machine data was never backed up, is a `WARN`."""
    from chemenu import backup
    try:
        cfg = backup.read_config()
    except ChemenuError as exc:
        return Check(
            "backup", "FAIL", str(exc),
            "Fix the backup section as the message says - a broken one is not 'no backup'",
        )
    if cfg is None:
        return Check("backup", "OK", "absent - no backup section in the settings")
    problems, details = [], [f"target {cfg.target}"]
    if not backup.is_bare_repo(cfg.git_dir):
        problems.append(f"{cfg.git_dir} is not a bare repository")
    else:
        url = backup.push_url(config.ROOT)
        if url is None or not backup.same_location(url, cfg.git_dir, config.ROOT):
            problems.append(f"origin pushes to {url or 'nothing'}, not to {cfg.git_dir}")
    if cfg.machine_data:
        try:
            manifest = backup.read_manifest(cfg.machine_dir)
        except ChemenuError as exc:
            manifest = None
            problems.append(str(exc))
        else:
            if manifest is None:
                problems.append(f"no machine-data backup in {cfg.machine_dir} yet")
            else:
                details.append(
                    f"last machine-data backup {backup.age_text(manifest.get('created'))} "
                    f"({len(manifest['files'])} file(s) in {cfg.machine_dir})"
                )
    else:
        details.append("machine data not backed up (machine_data is false)")
    if problems:
        return Check(
            "backup", "WARN", "; ".join([*details, *problems]),
            f"Run `tools/wikitool backup init`, then `publish` or `tools/wikitool backup run` - "
            f"see {BACKUP_HOW_TO}",
        )
    return Check("backup", "OK", "; ".join(details))
 def check_generated_files() -> Check:
    missing = [
        rel_path(path)
@@ -950,6 +1024,8 @@ def run_doctor() -> list[Check]:
        check_environment(),
        *check_legacy_settings(),
        check_publish_remotes(),
        check_sync_folder(),
        check_backup(),
        check_upload_intake(),
        check_tasks_provider(),
        *check_settings(),
@@ -1002,6 +1078,14 @@ def run_doctor() -> list[Check]:
        "Legacy settings (`legacy-settings`): one `FAIL` for each per-feature settings file of "
        "an earlier version (telemetry, remotes, upload, task tracker) that is still there. Nothing reads them any more, so the settings they hold are not in effect; "
        "the fix is `tools/wikitool config migrate`.",
        "Synced folder (`sync-folder`): a `WARN` when the git directory, links and junctions "
        "resolved, lies under a folder named by `OneDrive`, `OneDriveCommercial` or "
        "`OneDriveConsumer` (compared without regard to case on Windows) or under "
        "`~/Library/CloudStorage/` (macOS); `OK` otherwise, never a `FAIL`.",
        "Backup (`backup`): the `backup` section absent is `OK`, malformed is a `FAIL`. "
        "Configured, a `WARN` when `<target>/git` is not a bare repository, `origin` does not "
        "push there, or - with `machine_data` true - no machine-data backup exists yet; "
        "otherwise `OK` with the age of the last machine-data backup.",
        "MCP `submit` tool: whether the `upload` section of the settings is present, absent or "
        "malformed, its limits, and how many submissions wait in `mcp-upload/`. Absent is `OK` "
        "and means the write path does not exist at all; malformed is a `FAIL`.",
@@ -1059,6 +1143,7 @@ def run_doctor() -> list[Check]:
        "`docs/reference/configuration.md` - the per-checkout configuration files and the tiered "
        "settings",
        "`docs/explanation/telemetry-and-evaluation.md` - telemetry state and caps",
        f"`{BACKUP_HOW_TO}` - what `sync-folder` and `backup` point to",
        "`instructions/session-setup.md` - setting `WIKITOOL_SESSION_ID`",
    ),
 ))
@@ -63,7 +63,7 @@ from typing import NamedTuple, Optional
 import typer
 from chemenu import cli_contract, config, config_shapes, toolpaths
-from chemenu.commands._util import fail, load_settings, needs_clearance, refuse_leftover, success
+from chemenu.commands._util import console, fail, load_settings, needs_clearance, refuse_leftover, success
 from chemenu.telemetry import emit
 # "Farza's Rule" from the Mass-Update Gate concept: halt and request
@@ -159,6 +159,45 @@ def publish_remote_refusal(remote: str, branch: str) -> Optional[str]:
    )
 # --- Machine-data backup ------------------------------------------------------
 #
 # With a `backup` section whose `machine_data` is true, a publish that pushed
 # also mirrors this machine's files that are not in git (`chemenu.backup`). By
 # then the commit and the push have happened, so a failing backup is a WARN and
 # exit 0: exit 1 would read as "publish failed" and invite a second publish,
 # which cannot fix a target that is not writable - `backup run` after the cause
 # is fixed does.
 def read_backup_config():
    """The `backup` section, None when absent; exit 1 for a broken one."""
    from chemenu import backup
    from chemenu.errors import ChemenuError
    try:
        return backup.read_config()
    except ChemenuError as exc:
        fail(str(exc))
 def back_up_machine_data(cfg) -> None:
    from rich.markup import escape
    from chemenu import backup
    from chemenu.errors import ChemenuError
    try:
        result = backup.run(cfg)
    except (ChemenuError, OSError) as exc:
        console.print(
            f"[yellow]WARN[/yellow] The machine-data backup failed: {escape(str(exc))}\n"
            "  The commit and the push stand. Show this to the user; once the cause is fixed, "
            "`tools/wikitool backup run` repeats the backup - another `publish` does not."
        )
        return
    typer.echo(result.summary())
 # The status letters `git diff --cached --raw` emits under `--no-renames` (renames and copies
 # are switched off, so neither R nor C can appear). Anything else - M, and T for a type change -
 # is a modification.
@@ -1568,6 +1607,13 @@ def commit_regenerated(remote: str, branch: str) -> None:
        "`git interpret-trailers` decides whether there is such a block, and the list moves "
        "only when git reads the same trailers from the result; otherwise it is appended at "
        "the end. `--message` is not part of any gate token.",
        "Machine-data backup: with a `backup` section in `.wikitool-local.json` whose "
        "`machine_data` is true, a call that pushed then mirrors this machine's files that are "
        "not in git into `<target>/<machine>/` - the same step as `backup run`. A failure there "
        "prints a `WARN` line with the reason and still exits 0, since the commit and the push "
        "stand. No backup with `--no-push`, after a failed push, or when there was nothing to "
        "push. A malformed `backup` section stops the call with exit 1 before anything is "
        "committed, `--no-push` included.",
        "After a successful commit or push whose changed files include `tools/`, `types/`, "
        "`instructions/`, `AGENTS.md` or a path ending in `CONTRACT.md`, prints one reminder "
        "line: the phase past this point (an issue-body rewrite, `docs/` staleness, a "
@@ -1604,11 +1650,18 @@ def commit_regenerated(remote: str, branch: str) -> None:
            "from the gate's own refusal output",
        ),
        cli_contract.Failure(
-            cause="The settings files do not pass their check, or `remotes.allowed_push_urls` is "
+            cause="The settings files do not pass their check, `remotes.allowed_push_urls` is "
-            "not a list of strings",
+            "not a list of strings, or the `backup` section is malformed; nothing was committed",
            reaction="Show the error to the user and stop - a malformed section is not "
            "permission, and fixing it is theirs to do",
        ),
        cli_contract.Failure(
            cause="The machine-data backup after the push failed: a `WARN` line names the reason, "
            "and the commit and the push stand",
            reaction="Show the `WARN` line to the user. Do not publish again - once the cause is "
            "fixed, `tools/wikitool backup run` repeats the backup",
            code=0,
        ),
        cli_contract.Failure(
            cause="The remotes settings file of an earlier version is still there",
            reaction="Show the output to the user verbatim and stop; `tools/wikitool config "
@@ -1656,6 +1709,7 @@ def commit_regenerated(remote: str, branch: str) -> None:
        "`wikitool sync` - the same reconcile on its own, without committing or pushing",
        "`instructions/gates.md` - the gate procedure",
        "`instructions/setup-instance.md` - the first publish of a new instance",
        "`wikitool backup run` - the machine-data backup on its own",
    ),
 ))
 def publish_command(
@@ -1703,6 +1757,10 @@ def publish_command(
    if yes:
        fail(YES_REMOVED_MESSAGE)
    # Read before anything is committed, `--no-push` included: a broken section
    # stops here rather than turning into a skipped backup after the push.
    backup_cfg = read_backup_config()
    paths = list(path or [])
    # What is staged and committed: `paths` plus any uncommitted generated file outside them.
    # The gate token and its re-run line keep `paths`.
@@ -1872,5 +1930,7 @@ def publish_command(
        },
    )
    success(f"Published changes to {remote}/{branch}." if push else "Committed changes (not pushed).")
    if push and backup_cfg is not None and backup_cfg.machine_data:
        back_up_machine_data(backup_cfg)
    if touches_stack_machinery(changed_files):
        typer.echo(STACK_MACHINERY_NOTE)
@@ -31,6 +31,8 @@ every tool call without the venv.
 from __future__ import annotations
 import json
 import ntpath
 import posixpath
 import re
 from dataclasses import dataclass, field as dc_field
 from typing import Any, Callable, Optional
@@ -576,11 +578,101 @@ FETCH = Shape(
    "of that host the same way.",
 )
 def strict_bool(value: Any) -> bool:
    if not isinstance(value, bool):
        raise TypeError("not a boolean")
    return value
 _MACHINE_NAME_INVALID = re.compile(r"[^A-Za-z0-9_-]")
 # The one subdirectory name of a backup target that is not a machine's.
 BACKUP_GIT_DIR = "git"
 def machine_name(value: str) -> str:
    """`value` cleaned to a directory name of a backup target: every character
    outside `[A-Za-z0-9_-]` becomes `-`, and leading and trailing `-` go."""
    return _MACHINE_NAME_INVALID.sub("-", value).strip("-")
 def machine_name_problem(value: str) -> Optional[str]:
    cleaned = machine_name(value)
    if not cleaned:
        return "is empty once cleaned to letters, digits, `-` and `_`"
    if cleaned.casefold() == BACKUP_GIT_DIR:
        return f"cleans to {cleaned!r}, the name of the target's git directory"
    return None
 def absolute_path_problem(value: str) -> Optional[str]:
    # Either platform's form, so a record's example holds on both; whether the
    # path is absolute *on this machine* is `chemenu.backup.read_config`'s check.
    return None if ntpath.isabs(value) or posixpath.isabs(value) else "must be an absolute path"
 def relative_paths_problem(value: list[str]) -> Optional[str]:
    for entry in value:
        if not entry.strip():
            return "must not contain an empty path"
        if ntpath.isabs(entry) or posixpath.isabs(entry):
            return f"holds {entry!r}, an absolute path - each entry is relative to the instance"
    return None
 BACKUP = Shape(
    key="backup",
    title="Backup to a synced folder",
    purpose="Backs this checkout up into a folder a sync client (OneDrive and the like) uploads, "
    "without the working tree living in it: a bare repository under `<target>/git` as the push "
    "target of `publish`, and a mirror of the files of this machine that are not in git under "
    "`<target>/<machine>/`.",
    fields=(
        Field(
            "target", "string", "The backup folder: an absolute path outside the instance. "
            "`backup init` creates `<target>/git` in it, `backup run` writes only to "
            "`<target>/<machine>/`.",
            required=True, json_type="string", coerce=exact_str, check=absolute_path_problem,
            tier=CHECKOUT, gate=True,
        ),
        Field(
            "machine_data", "boolean", "Mirror this machine's files after every `publish` that "
            "pushed, and with `backup run`: `.wikitool-local.json`, `ENVIRONMENT.md`, what waits "
            "in `incoming/`, and `extra`.",
            default=False, json_type="boolean", coerce=strict_bool, tier=CHECKOUT, gate=True,
        ),
        Field(
            "machine_name", "string", "The name of this machine's folder under the target. "
            "Every character outside letters, digits, `-` and `_` becomes `-`, and leading and "
            "trailing `-` are dropped; a name that is empty afterwards, or `git` in any case, is "
            "an error.",
            default_text="the host name", json_type="string", coerce=exact_str,
            check=machine_name_problem, tier=CHECKOUT,
        ),
        Field(
            "extra", "array of strings", "Further files or directories to mirror, relative to "
            "the instance. One that resolves outside the instance, or into `.git/`, is an error.",
            default=[], json_type="array", coerce=str_list, check=relative_paths_problem,
            tier=CHECKOUT, gate=True,
        ),
    ),
    examples=({
        "target": "C:\\Users\\<user>\\OneDrive - <company>\\Chemenu-Backup",
        "machine_data": True,
        "machine_name": "WORK-LAPTOP",
        "extra": [".claude/settings.local.json"],
    },),
    absent="No backup: `publish` behaves as without it, and `backup init` and `backup run` stop "
    "with exit 1 naming the section.",
    malformed="An error. `publish` stops with exit 1 before it commits anything, `backup init` and "
    "`backup run` stop with exit 1, and `doctor` reports `FAIL`. A broken section is never read as "
    "\"no backup\".",
 )
 # The sections of the tiered settings files, `wikitool.json` and
 # `.wikitool-local.json` (`chemenu.settings`), read at call time so a test can
 # stand in a section of its own.
 SETTINGS_SECTIONS: tuple[Shape, ...] = (
-    TELEMETRY, REMOTES, UPLOAD, TASKS, SUPERPRODUCTIVITY, CALDAV, SITES, FETCH,
+    TELEMETRY, REMOTES, UPLOAD, TASKS, SUPERPRODUCTIVITY, CALDAV, SITES, FETCH, BACKUP,
 )
 # The sections `WIKITOOL_TASKS_CONFIG` replaces as a whole: a profile names a
@@ -70,6 +70,7 @@ CONFIG_REGIONS = (
    ("reference-config-upload", "UPLOAD"),
    ("reference-config-sites", "SITES"),
    ("reference-config-fetch", "FETCH"),
    ("reference-config-backup", "BACKUP"),
 )
 _SLUG_RE = re.compile(r"[^a-z0-9]+")
@@ -39,6 +39,10 @@ _WIKITOOL_ENV = (
    "CHEMENU_PREFLIGHT_POLICY",
    "CHEMENU_PREFLIGHT_MARKED",
    "CHEMENU_PREFLIGHT_MOVE_FAIL",
    # Where a sync client keeps its folder - `doctor`'s sync-folder check reads them.
    "OneDrive",
    "OneDriveCommercial",
    "OneDriveConsumer",
 ) + tuple(var for var, _harness in HARNESS_ENV_VARS)
 # Environment git reads for identity or for where its repo lives. A stray
@@ -0,0 +1,562 @@
 """`backup init`, `backup run`, the machine-data step of `publish`, and the two
 `doctor` lines - against a real checkout and a target directory in `tmp_path`.
 The target's path carries a space on purpose: the folder a sync client keeps on
 Windows is `OneDrive - <company>`, and every path that reaches git or the file
 system has to survive that."""
 from __future__ import annotations
 import json
 import os
 import subprocess
 from pathlib import Path
 import pytest
 import typer
 from typer.testing import CliRunner
 from chemenu import backup, config, config_shapes, settings
 from chemenu.cli import app
 from chemenu.commands import doctor
 from chemenu.commands.git_publish import publish_command
 runner = CliRunner()
 def _git(root: Path, *args: str) -> str:
    result = subprocess.run(["git", *args], cwd=root, capture_output=True, text=True)
    assert result.returncode == 0, result.stderr
    return result.stdout.strip()
 def _write_local(root: Path, **sections) -> None:
    (root / config.LOCAL_SETTINGS_FILENAME).write_text(
        json.dumps({"schema": 1, **sections}, indent=2), encoding="utf-8")
@pytest.fixture
 def instance(tmp_path, monkeypatch):
    """A checkout with one commit and no remote, and an empty synced folder
    beside it - whose name has a space in it."""
    root = tmp_path / "instance"
    root.mkdir()
    _git(root, "init", "-b", "main")
    _git(root, "config", "user.name", "Test")
    _git(root, "config", "user.email", "test@example.com")
    (root / "kb").mkdir()
    (root / "incoming").mkdir()
    (root / "incoming" / ".gitkeep").write_text("", encoding="utf-8")
    (root / ".gitignore").write_text(
        "/incoming/*\n!/incoming/.gitkeep\n/.wikitool-local.json\n/ENVIRONMENT.md\n/mcp-upload/\n"
        "/reports/\n/.wikitool-tools.json\n", encoding="utf-8")
    (root / "README.md").write_text("init\n", encoding="utf-8")
    _git(root, "add", "-A")
    _git(root, "commit", "-m", "init")
    synced = tmp_path / "OneDrive - Example"
    synced.mkdir()
    monkeypatch.setattr(config, "ROOT", root)
    monkeypatch.setenv("WIKITOOL_SESSION_ID", "test-session")
    return root
 def _target(root: Path) -> Path:
    return root.parent / "OneDrive - Example" / "Chemenu-Backup"
 def _configure(root: Path, **overrides) -> Path:
    target = _target(root)
    section = {"target": str(target), "machine_data": True, "machine_name": "WORK-LAPTOP"}
    section.update(overrides)
    _write_local(root, backup=section)
    return target
 def _snapshot(directory: Path) -> dict:
    """Every file below `directory` with its bytes - what "unchanged" is measured against."""
    return {p.relative_to(directory).as_posix(): p.read_bytes()
            for p in sorted(directory.rglob("*")) if p.is_file()}
 def _mirrored(target: Path, machine: str = "WORK-LAPTOP") -> set[str]:
    return set(_snapshot(target / machine))
 def _flat(text: str) -> str:
    """Output with Rich's line wrapping undone."""
    return " ".join(text.split())
 def _publish(**overrides):
    kwargs = dict(message="change", push=True, confirm=None, confirm_rebase=None, yes=False,
                  threshold=10, remote="origin", branch="main", path=None)
    kwargs.update(overrides)
    publish_command(**kwargs)
 # --- the section -------------------------------------------------------------
 def test_no_section_reads_as_none_and_the_commands_name_it(instance):
    assert backup.read_config() is None
    for command in ("init", "run"):
        result = runner.invoke(app, ["backup", command])
        assert result.exit_code == 1
        assert "no backup section" in _flat(result.output)
@pytest.mark.parametrize("name", ["", "...", "  ", "git", "GIT", ".git", "-Git-"])
 def test_a_machine_name_that_cleans_to_nothing_or_git_is_an_error(instance, name):
    _configure(instance, machine_name=name)
    with pytest.raises(settings.ValidationError, match="machine_name"):
        backup.read_config()
 def test_a_machine_name_is_cleaned_to_a_directory_name(instance):
    _configure(instance, machine_name="Work Laptop.corp")
    assert backup.read_config().machine_name == "Work-Laptop-corp"
 def test_without_a_machine_name_the_host_name_is_used(instance, monkeypatch):
    monkeypatch.setattr(backup.socket, "gethostname", lambda: "host.example")
    _configure(instance)
    data = json.loads((instance / config.LOCAL_SETTINGS_FILENAME).read_text(encoding="utf-8"))
    del data["backup"]["machine_name"]
    (instance / config.LOCAL_SETTINGS_FILENAME).write_text(json.dumps(data), encoding="utf-8")
    assert backup.read_config().machine_name == "host-example"
 def test_a_target_inside_the_instance_is_an_error(instance):
    _configure(instance, target=str(instance / "backup"))
    with pytest.raises(settings.ValidationError, match="inside the instance"):
        backup.read_config()
 def test_a_relative_target_is_an_error(instance):
    _configure(instance, target="backup")
    with pytest.raises(settings.ValidationError, match="absolute"):
        backup.read_config()
@pytest.mark.parametrize("field, value", [("machine_data", "yes"), ("extra", "a")])
 def test_a_field_of_the_wrong_type_is_an_error(instance, field, value):
    _configure(instance, **{field: value})
    with pytest.raises(settings.ValidationError, match=field):
        backup.read_config()
 def test_the_gate_fields_are_refused_by_config_set(instance):
    for name in ("target", "machine_data", "extra"):
        assert config_shapes.BACKUP.field(name).user_only
    result = runner.invoke(app, ["config", "set", "backup.target", "/tmp/x"])
    assert result.exit_code == 42
 # --- backup init -------------------------------------------------------------
 def test_init_creates_a_bare_repository_and_makes_it_origin(instance):
    target = _configure(instance)
    result = runner.invoke(app, ["backup", "init"])
    assert result.exit_code == 0, result.output
    assert backup.is_bare_repo(target / "git")
    assert _git(instance, "remote", "get-url", "--push", "origin") == str(target / "git")
    before = _snapshot(target)
    again = runner.invoke(app, ["backup", "init"])
    assert again.exit_code == 0, again.output
    assert "left as it is" in _flat(again.output)
    assert _snapshot(target) == before
    assert _git(instance, "remote", "get-url", "--push", "origin") == str(target / "git")
 def test_init_into_an_empty_directory_uses_it(instance):
    target = _configure(instance)
    (target / "git").mkdir(parents=True)
    assert runner.invoke(app, ["backup", "init"]).exit_code == 0
    assert backup.is_bare_repo(target / "git")
 def test_init_leaves_an_origin_that_points_elsewhere_and_changes_nothing(instance, tmp_path):
    target = _configure(instance)
    _git(instance, "remote", "add", "origin", "https://example.org/other.git")
    result = runner.invoke(app, ["backup", "init"])
    assert result.exit_code == 1
    assert "https://example.org/other.git" in _flat(result.output)
    assert str(target / "git") in _flat(result.output)
    assert _git(instance, "remote", "get-url", "--push", "origin") == "https://example.org/other.git"
    assert not target.exists()
 def test_init_refuses_a_git_folder_that_is_not_a_bare_repository(instance):
    target = _configure(instance)
    (target / "git").mkdir(parents=True)
    (target / "git" / "notes.txt").write_text("mine\n", encoding="utf-8")
    before = _snapshot(target)
    result = runner.invoke(app, ["backup", "init"])
    assert result.exit_code == 1
    assert "not a bare git repository" in _flat(result.output)
    assert _snapshot(target) == before
    assert subprocess.run(["git", "remote", "get-url", "origin"], cwd=instance,
                          capture_output=True).returncode != 0
 def test_init_prints_the_allowlist_entry_and_never_writes_it(instance):
    target = _configure(instance)
    data = json.loads((instance / config.LOCAL_SETTINGS_FILENAME).read_text(encoding="utf-8"))
    data["remotes"] = {"allowed_push_urls": ["https://example.org/kb.git"]}
    (instance / config.LOCAL_SETTINGS_FILENAME).write_text(json.dumps(data), encoding="utf-8")
    before = (instance / config.LOCAL_SETTINGS_FILENAME).read_bytes()
    result = runner.invoke(app, ["backup", "init"])
    assert result.exit_code == 0, result.output
    entry = json.loads(result.output[result.output.index("{"):result.output.rindex("}") + 1])
    assert entry == {"remotes": {"allowed_push_urls": ["https://example.org/kb.git", str(target / "git")]}}
    assert (instance / config.LOCAL_SETTINGS_FILENAME).read_bytes() == before
 # --- backup run --------------------------------------------------------------
 def _fill(root: Path) -> None:
    (root / "ENVIRONMENT.md").write_text("# env\n", encoding="utf-8")
    (root / "incoming" / "paper.pdf").write_bytes(b"%PDF-1.7 fixture")
    (root / "incoming" / "old").mkdir()
    (root / "incoming" / "old" / "note.md").write_text("note\n", encoding="utf-8")
    for relative in ("mcp-upload/sub-1/x.md", "reports/lint.md", ".wikitool-tools.json"):
        (root / relative).parent.mkdir(parents=True, exist_ok=True)
        (root / relative).write_text("not mirrored\n", encoding="utf-8")
    (root / ".claude").mkdir()
    (root / ".claude" / "settings.local.json").write_text("{}\n", encoding="utf-8")
 def test_run_mirrors_exactly_the_machine_data(instance):
    target = _configure(instance, extra=[".claude/settings.local.json"])
    target.mkdir(parents=True)
    _fill(instance)
    result = runner.invoke(app, ["backup", "run"])
    assert result.exit_code == 0, result.output
    assert _mirrored(target) == {
        ".wikitool-local.json", "ENVIRONMENT.md", "incoming/paper.pdf", "incoming/old/note.md",
        ".claude/settings.local.json", backup.MANIFEST_NAME,
    }
    machine = target / "WORK-LAPTOP"
    assert (machine / "incoming" / "paper.pdf").read_bytes() == b"%PDF-1.7 fixture"
    manifest = json.loads((machine / backup.MANIFEST_NAME).read_text(encoding="utf-8"))
    assert manifest["machine"] == "WORK-LAPTOP"
    assert {entry["path"] for entry in manifest["files"]} == _mirrored(target) - {backup.MANIFEST_NAME}
    assert all(len(entry["sha256"]) == 64 and entry["size"] >= 0 for entry in manifest["files"])
 def test_run_never_mirrors_git_even_through_extra(instance):
    _configure(instance, extra=[".git"])
    with pytest.raises(settings.ValidationError, match=r"\.git"):
        backup.read_config()
    target = _configure(instance, extra=["kb"])
    target.mkdir(parents=True)
    (instance / "kb" / ".git").mkdir()
    (instance / "kb" / ".git" / "HEAD").write_text("ref\n", encoding="utf-8")
    (instance / "kb" / "page.md").write_text("page\n", encoding="utf-8")
    assert runner.invoke(app, ["backup", "run"]).exit_code == 0
    assert "kb/page.md" in _mirrored(target)
    assert not any(".git/" in path for path in _mirrored(target))
 def test_a_second_run_removes_what_left_incoming_and_keeps_a_foreign_file(instance):
    target = _configure(instance)
    target.mkdir(parents=True)
    _fill(instance)
    assert runner.invoke(app, ["backup", "run"]).exit_code == 0
    foreign = target / "WORK-LAPTOP" / "kept-by-hand.txt"
    foreign.write_bytes(b"mine")
    (instance / "incoming" / "paper.pdf").unlink()
    result = runner.invoke(app, ["backup", "run"])
    assert result.exit_code == 0, result.output
    assert "1 removed" in _flat(result.output)
    assert not (target / "WORK-LAPTOP" / "incoming" / "paper.pdf").exists()
    assert foreign.read_bytes() == b"mine"
 def test_an_unchanged_file_is_not_rewritten(instance):
    target = _configure(instance)
    target.mkdir(parents=True)
    _fill(instance)
    assert runner.invoke(app, ["backup", "run"]).exit_code == 0
    copy = target / "WORK-LAPTOP" / "incoming" / "paper.pdf"
    stamp = copy.stat().st_mtime_ns
    os.utime(copy, ns=(stamp - 10**9, stamp - 10**9))
    result = runner.invoke(app, ["backup", "run"])
    assert "0 written" in _flat(result.output)
    assert copy.stat().st_mtime_ns == stamp - 10**9
 def test_run_refuses_a_non_empty_folder_without_a_manifest(instance):
    target = _configure(instance)
    (target / "WORK-LAPTOP").mkdir(parents=True)
    (target / "WORK-LAPTOP" / "somebody-elses.txt").write_text("x\n", encoding="utf-8")
    _fill(instance)
    before = _snapshot(target)
    result = runner.invoke(app, ["backup", "run"])
    assert result.exit_code == 1
    assert "no .chemenu-backup.json" in _flat(result.output)
    assert _snapshot(target) == before
 def test_run_writes_nothing_outside_its_own_folder(instance):
    target = _configure(instance)
    target.mkdir(parents=True)
    (target / "OTHER-PC").mkdir()
    (target / "OTHER-PC" / "a.txt").write_text("other\n", encoding="utf-8")
    (target / "git").mkdir()
    (target / "git" / "b").write_text("repo\n", encoding="utf-8")
    before = {k: v for k, v in _snapshot(target).items()}
    _fill(instance)
    assert runner.invoke(app, ["backup", "run"]).exit_code == 0
    after = _snapshot(target)
    assert {k: v for k, v in after.items() if not k.startswith("WORK-LAPTOP/")} == before
 def test_a_manifest_entry_that_leaves_the_folder_is_refused(instance):
    target = _configure(instance)
    (target / "WORK-LAPTOP").mkdir(parents=True)
    (target / "victim.txt").write_text("keep\n", encoding="utf-8")
    (target / "WORK-LAPTOP" / backup.MANIFEST_NAME).write_text(json.dumps(
        {"schema": 1, "files": [{"path": "../victim.txt", "size": 5, "sha256": "0" * 64}]}),
        encoding="utf-8")
    assert runner.invoke(app, ["backup", "run"]).exit_code == 1
    assert (target / "victim.txt").read_text(encoding="utf-8") == "keep\n"
 def test_an_extra_path_outside_the_instance_is_refused_before_anything_is_written(instance, tmp_path):
    target = _configure(instance, extra=["../outside.txt"])
    target.mkdir(parents=True)
    (tmp_path / "outside.txt").write_text("secret\n", encoding="utf-8")
    result = runner.invoke(app, ["backup", "run"])
    assert result.exit_code == 1
    assert "outside the instance" in _flat(result.output)
    assert not (target / "WORK-LAPTOP").exists()
@pytest.mark.skipif(not hasattr(os, "symlink") or os.name == "nt", reason="symlinks")
 def test_an_extra_symlink_to_outside_is_refused(instance, tmp_path):
    (tmp_path / "secrets").mkdir()
    (tmp_path / "secrets" / "secrets.json").write_text("{}\n", encoding="utf-8")
    (instance / "linked").symlink_to(tmp_path / "secrets")
    target = _configure(instance, extra=["linked"])
    target.mkdir(parents=True)
    assert runner.invoke(app, ["backup", "run"]).exit_code == 1
    assert not (target / "WORK-LAPTOP").exists()
@pytest.mark.skipif(not hasattr(os, "symlink") or os.name == "nt", reason="symlinks")
 def test_a_symlink_in_incoming_is_skipped_and_named(instance, tmp_path):
    (tmp_path / "elsewhere.txt").write_text("not mine\n", encoding="utf-8")
    (instance / "incoming" / "link.txt").symlink_to(tmp_path / "elsewhere.txt")
    target = _configure(instance)
    target.mkdir(parents=True)
    result = runner.invoke(app, ["backup", "run"])
    assert result.exit_code == 0, result.output
    assert "incoming/link.txt (a link - not followed)" in _flat(result.output)
    assert "incoming/link.txt" not in _mirrored(target)
 def test_run_refuses_while_machine_data_is_off(instance):
    _configure(instance, machine_data=False)
    result = runner.invoke(app, ["backup", "run"])
    assert result.exit_code == 1
    assert "machine_data is false" in _flat(result.output)
 def test_run_refuses_a_missing_target(instance):
    target = _configure(instance)
    result = runner.invoke(app, ["backup", "run"])
    assert result.exit_code == 1
    assert "not a directory" in _flat(result.output)
    assert not target.exists()
 # --- publish -----------------------------------------------------------------
 def _ready(root: Path, **overrides) -> Path:
    target = _configure(root, **overrides)
    assert runner.invoke(app, ["backup", "init"]).exit_code == 0
    return target
 def test_publish_pushes_to_the_target_and_backs_the_machine_data_up(instance):
    target = _ready(instance, extra=[".claude/settings.local.json"])
    _fill(instance)
    (instance / "kb" / "page.md").write_text("page\n", encoding="utf-8")
    _publish()
    assert _git(target / "git", "rev-parse", "main") == _git(instance, "rev-parse", "HEAD")
    assert _mirrored(target) == {
        ".wikitool-local.json", "ENVIRONMENT.md", "incoming/paper.pdf", "incoming/old/note.md",
        ".claude/settings.local.json", backup.MANIFEST_NAME,
    }
 def test_publish_without_machine_data_backs_nothing_up(instance):
    target = _ready(instance, machine_data=False)
    (instance / "kb" / "page.md").write_text("page\n", encoding="utf-8")
    _publish()
    assert _git(target / "git", "rev-parse", "main") == _git(instance, "rev-parse", "HEAD")
    assert not (target / "WORK-LAPTOP").exists()
 def test_a_failed_machine_backup_is_a_warning_after_the_push(instance, capsys):
    target = _ready(instance)
    (target / "WORK-LAPTOP").mkdir()
    (target / "WORK-LAPTOP" / "somebody-elses.txt").write_text("x\n", encoding="utf-8")
    (instance / "kb" / "page.md").write_text("page\n", encoding="utf-8")
    _publish()  # no typer.Exit: exit 0
    out = capsys.readouterr().out
    assert "WARN" in out and "backup run" in out
    assert _git(target / "git", "rev-parse", "main") == _git(instance, "rev-parse", "HEAD")
 def test_an_unwritable_target_is_a_warning_after_the_push(instance, capsys, monkeypatch):
    target = _ready(instance)
    def refuse(*args, **kwargs):
        raise PermissionError(13, "Permission denied", str(target))
    monkeypatch.setattr(backup, "_copy_atomic", refuse)
    (instance / "kb" / "page.md").write_text("page\n", encoding="utf-8")
    _publish()
    out = capsys.readouterr().out
    assert "WARN" in out and "Permission denied" in out
    assert _git(target / "git", "rev-parse", "main") == _git(instance, "rev-parse", "HEAD")
 def test_publish_no_push_backs_nothing_up(instance):
    target = _ready(instance)
    (instance / "kb" / "page.md").write_text("page\n", encoding="utf-8")
    _publish(push=False)
    assert not (target / "WORK-LAPTOP").exists()
 def test_a_malformed_section_stops_publish_before_the_commit(instance):
    _configure(instance, machine_name="git")
    (instance / "kb" / "page.md").write_text("page\n", encoding="utf-8")
    head = _git(instance, "rev-parse", "HEAD")
    for push in (True, False):
        with pytest.raises(typer.Exit) as exc:
            _publish(push=push)
        assert exc.value.exit_code == 1
        assert _git(instance, "rev-parse", "HEAD") == head
 # --- doctor ------------------------------------------------------------------
 def _check(name: str):
    return next(check for check in doctor.run_doctor() if check.name == name)
@pytest.fixture
 def doctor_instance(instance, monkeypatch):
    # `run_doctor` runs every check; the two under test only need the checkout.
    for name in ("check_skills", "check_structure", "check_personalization", "check_conventions",
                 "check_generated_files", "check_tool_paths"):
        monkeypatch.setattr(doctor, name, lambda: doctor.Check(name, "OK", "stubbed"))
    return instance
@pytest.mark.parametrize("var", backup.SYNC_ENV_VARS)
 def test_sync_folder_warns_under_a_onedrive_folder(doctor_instance, monkeypatch, var):
    monkeypatch.setenv(var, str(doctor_instance.parent))
    check = _check("sync-folder")
    assert check.status == "WARN"
    assert "back-up-to-a-synced-folder.md" in check.fix and "Known Folder Move" in check.fix
 def test_sync_folder_warns_under_cloud_storage(doctor_instance, tmp_path, monkeypatch):
    cloud = tmp_path / "home" / "Library" / "CloudStorage"
    cloud.mkdir(parents=True)
    monkeypatch.setenv("HOME", str(tmp_path / "home"))
    moved = cloud / "OneDrive-Example" / "instance"
    moved.parent.mkdir()
    doctor_instance.rename(moved)
    monkeypatch.setattr(config, "ROOT", moved)
    assert _check("sync-folder").status == "WARN"
@pytest.mark.skipif(not hasattr(os, "symlink") or os.name == "nt", reason="symlinks")
 def test_sync_folder_sees_through_a_symlink(doctor_instance, tmp_path, monkeypatch):
    synced = tmp_path / "OneDrive - Example"
    real = synced / "instance"
    doctor_instance.rename(real)
    (tmp_path / "via-link").symlink_to(real)
    monkeypatch.setattr(config, "ROOT", tmp_path / "via-link")
    monkeypatch.setenv("OneDrive", str(synced))
    assert _check("sync-folder").status == "WARN"
 def test_sync_folder_is_ok_elsewhere_and_never_sets_the_exit_code(doctor_instance, tmp_path, monkeypatch):
    monkeypatch.setenv("OneDrive", str(tmp_path / "OneDrive - Example"))
    assert _check("sync-folder").status == "OK"
 def test_sync_folder_compares_without_case_on_windows(doctor_instance, monkeypatch):
    monkeypatch.setenv("OneDrive", str(doctor_instance.parent).upper())
    monkeypatch.setattr(backup, "IGNORE_CASE", False)
    assert _check("sync-folder").status == "OK"
    monkeypatch.setattr(backup, "IGNORE_CASE", True)
    assert _check("sync-folder").status == "WARN"
 def test_backup_check_absent_is_ok(doctor_instance):
    check = _check("backup")
    assert (check.status, check.detail) == ("OK", "absent - no backup section in the settings")
 def test_backup_check_fails_on_a_malformed_section(doctor_instance):
    _configure(doctor_instance, machine_name="GIT")
    check = _check("backup")
    assert check.status == "FAIL" and "machine_name" in check.detail
 def test_backup_check_warns_until_init_and_the_first_run(doctor_instance):
    target = _configure(doctor_instance)
    check = _check("backup")
    assert check.status == "WARN" and "not a bare repository" in check.detail
    assert runner.invoke(app, ["backup", "init"]).exit_code == 0
    check = _check("backup")
    assert check.status == "WARN" and "no machine-data backup" in check.detail
    assert runner.invoke(app, ["backup", "run"]).exit_code == 0
    check = _check("backup")
    assert check.status == "OK" and "last machine-data backup" in check.detail
    assert str(target) in check.detail
 def test_backup_check_warns_on_an_origin_elsewhere(doctor_instance):
    target = _configure(doctor_instance, machine_data=False)
    subprocess.run(["git", "init", "--bare", "-q", "-b", "main", str(target / "git")], check=True)
    _git(doctor_instance, "remote", "add", "origin", "https://example.org/other.git")
    check = _check("backup")
    assert check.status == "WARN" and "https://example.org/other.git" in check.detail
 def test_a_warning_from_either_check_leaves_doctors_exit_code_alone(doctor_instance, monkeypatch):
    monkeypatch.setenv("OneDrive", str(doctor_instance.parent))
    _configure(doctor_instance)
    checks = {check.name: check.status for check in doctor.run_doctor()}
    assert checks["sync-folder"] == "WARN" and checks["backup"] == "WARN"
    assert all(status != "FAIL" for name, status in checks.items() if name in ("sync-folder", "backup"))
 def test_the_git_remote_warning_names_the_how_to(doctor_instance):
    assert "back-up-to-a-synced-folder.md" in _check("git-remote").fix
 def test_age_text():
    from datetime import datetime, timezone
    now = datetime(2026, 10, 12, 12, 0, tzinfo=timezone.utc)
    assert backup.age_text("2026-10-12T11:59:30+00:00", now) == "less than a minute old"
    assert backup.age_text("2026-10-12T09:00:00+00:00", now) == "3 h old"
    assert backup.age_text("2026-10-10T12:00:00+00:00", now) == "2 d old"
    assert backup.age_text("garbage", now) == "of unknown age"
@@ -79,6 +79,7 @@ def test_the_telemetry_policy_reads_the_record():
 def test_one_record_per_section():
    assert [shape.key for shape in config_shapes.SETTINGS_SECTIONS] == [
        "telemetry", "remotes", "upload", "tasks", "superproductivity", "caldav", "sites", "fetch",
        "backup",
    ]