From 45ae04cfee50cf6bca1a850a20dd2c15b29a892e Mon Sep 17 00:00:00 2001 From: Torben Nehmer Date: Wed, 7 Oct 2026 16:34:46 +0200 Subject: [PATCH] docs(how-to): update-an-instance names the interrupted required migration (#195) The guide said a required migration is simply carried out, which contradicts upgrade-instance.md: the agent can stop after the first publish, leaving a valid intermediate state that migrate status resumes and doctor warns about. The guide now says so without retelling the instruction's steps. Files changed: - docs/how-to/update-an-instance.md Co-Authored-By: Claude Code Claude-Session: https://claude.ai/code/session_01SnAJ7Z3CpVD3PRbN73QtU2 --- docs/how-to/update-an-instance.md | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/docs/how-to/update-an-instance.md b/docs/how-to/update-an-instance.md index 7af0599..06b6c8f 100644 --- a/docs/how-to/update-an-instance.md +++ b/docs/how-to/update-an-instance.md @@ -80,10 +80,19 @@ In the order you'll meet them: - **The session restart.** The running session still holds the *old* `AGENTS.md`, contracts and skills, so the agent asks you to restart it before migrating content. The new session picks up where the old one stopped. -- **An offered migration.** A required migration is simply carried out. An *offered* one changes a - file the instance owns, so taking it or declining it is your decision. +- **A required migration.** The agent carries it out, and may come back to you with a question + while doing so: a migration document can reach a point that is yours to decide, such as a page + that contradicts another. +- **An offered migration.** It changes a file the instance owns, so taking it or declining it is + your decision. - **The second publish,** of the migrated content, behind the same gate. +**A required migration can also be interrupted.** If the agent cannot complete one now, it stops +after the first publish and leaves it. That is a valid state: new machinery, content still in its +old form. `doctor` keeps warning until the migration is done, and a later session resumes with +`tools/wikitool migrate status`. The agent never records a migration it did not carry out, because +the content's version would then describe a shape the pages are not in. + If a step fails for a reason that isn't obvious, the agent stops and offers you a bug report rather than improvising ([Troubleshoot](troubleshoot.md)).