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

docs/reference/commands/README.md

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

docs/reference/commands/git.md

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

docs/reference/commands/instance-health.md

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