@@ -107,12 +107,18 @@ Repeating the same idempotency key returns the original applied result, includin
 its source and revision, even after later edits or a server restart. A changed
 payload under that key returns `idempotency-conflict`. Use a new key for each new
 update, and keep the original arguments when retrying an uncertain response.
-
-Source validation returns `issues`, as creation does. Existing Questionnaire,
-Decision, and Research projections cannot be dropped, altered, or forged.
-Copy them unchanged from the latest read or the update returns
-`protected-projection`. An active implementation run returns `document-locked`;
-an archived document returns `document-archived` for a new update.
+A replay's title and URL also reflect the original update. Read the document
+again for current metadata before handing off its canonical URL after a rename.
+
+Initial source validation returns `issues`, as creation does. Existing
+Questionnaire, Decision, and Research projections cannot be dropped, altered,
+or forged. Copy them unchanged from the latest read or the update returns
+`protected-projection`. That code also covers later rewrite validation or
+reconciliation refusals, so it does not identify a particular changed projection.
+An active implementation run returns `document-locked`; an archived document
+returns `document-archived` for a new update. Changing source before an approved
+graph is claimed makes its plan revision stale; revise and reapprove the graph
+before starting implementation.
 
 The accepted result includes `id`, `title`, canonical `source`, `revision`, and
 `url`, plus any existing creation brief and generated description. The MCP client
@@ -222,7 +228,8 @@ grant it.
 
 Use the optional
 [creating-chopin-plans skill](../skills/creating-chopin-plans/SKILL.md) to turn a
-settled coding-agent conversation into one initial document. The
+settled coding-agent conversation into one initial document or safely revise an
+existing document after review. The
 [implementing-chopin-plans skill](../skills/implementing-chopin-plans/SKILL.md)
 applies only after an implementation graph has been approved through a future or
 operator-provided approval path. Current MCP initialization instructions and
 
@@ -1,13 +1,15 @@
 ---
 name: creating-chopin-plans
-description: Use when a coding-agent conversation has settled enough context to create a new Chopin document through the create_document MCP tool.
+description: Use when a coding-agent conversation has settled enough context to create a Chopin document, or when revising an existing document through update_document after review or new findings.
 ---
 
-# Creating a Chopin plan
+# Creating and revising a Chopin plan
 
 Create one initial Chopin document from the useful outcome of the settled
-conversation. Chopin's current MCP instructions and tool descriptions are
-authoritative.
+conversation, then revise that same document as the plan develops. Chopin's
+current MCP instructions and tool descriptions are authoritative. If
+`update_document` is unavailable, report that limitation instead of creating a
+replacement document or trying to trigger the Planner.
 
 ## Prepare the brief
 
@@ -28,16 +30,64 @@ expressions, raw HTML, arbitrary JSX, or component ids owned by Chopin.
 Generate one idempotency key for the attempt, then use the current
 `create_document` descriptor to submit the brief, provenance, title, and plan.
 If it reports validation issues, repair the relevant content and retry with the
-same key. Once creation succeeds, do not call `create_document` again. Later
-revisions of that same document use `update_document` against the revision
-returned by `read_document`, with a new idempotency key.
+same key. Once creation succeeds, do not call `create_document` again for that
+document. Follow the revision flow below to preserve its Conversation and
+Decisions.
+
+## Revise an existing document
+
+1. Read the supplied canonical document URL or UUID with `read_document`. Work
+   from its latest `source` and `revision`, not a copied plan or an earlier tool
+   result. Confirm that the requested change belongs to this document.
+2. Prepare the full replacement MDX in `plan`, including unchanged prose. Copy
+   existing Questionnaire, Decision, and Research projections unchanged,
+   including their ids and answers. Do not invent, remove, or rewrite those
+   server-owned components to make the edit pass validation.
+3. Call `update_document` with `id`, the revision just read, the complete `plan`,
+   and a new nonblank `idempotencyKey` of at most 128 characters. Keep the exact
+   arguments until the outcome is known. The caller needs repository push or
+   administration access; its MCP bearer does not acquire Planner ownership.
+4. If the response is lost or uncertain, retry with the same key and identical
+   arguments, including the original URL or UUID. Do not switch identifiers or
+   change the source during a retry. A replay returns the original applied
+   source and revision, which may no longer be the latest document. Read again
+   before planning another edit.
+
+If the document already has an approved implementation graph, changing its
+source makes that graph's plan revision stale even before a run is claimed.
+Coordinate a graph revision and renewed approval before expecting implementation
+to start; a successful document update does not update or approve the graph.
+
+Handle refusals without overwriting collaborators' work:
+
+- `revision-conflict`: re-read the complete document, reconcile the requested
+  edit with intervening changes, and submit a new update with a new key. Do not
+  merely replace the revision number on stale source.
+- `idempotency-conflict`: the key was reused with different arguments. Recover
+  the original request for an uncertain retry; use a new key only for an
+  intentional new update after reading the current document.
+- `issues`: repair the reported validation problem. Treat changed arguments as
+  a new update with a new key.
+- `protected-projection`: re-read and preserve the exact server-owned projections.
+  This code also covers other rewrite validation or reconciliation refusals. If
+  unchanged projections still fail, stop and report the refusal rather than
+  repeatedly retrying or stripping components to get past it.
+- `document-locked`: stop document edits and follow the implementation's
+  revision and graph-release process. Do not bypass the lock by creating a copy.
+- `document-archived`: stop and ask whether to restore the document; do not
+  restore or replace it implicitly.
+- `repository-forbidden` or `document-unavailable`: report the access or
+  availability problem instead of recreating the document.
 
 ## Hand off
 
-Return the created document's human-readable `url` as the canonical handoff,
+Return the created or updated document's human-readable `url` as the canonical handoff,
 with its title. Treat the returned `id` as an internal MCP identifier: include it
 separately when useful, but never replace the `/documents/...` URL with a
 `/channels/<id>` link. Do not open it automatically.
+After an idempotent replay, use a fresh `read_document` result for the current
+title and canonical URL, since the stored response may predate a rename. Keep
+the replay's accepted revision distinct from the latest revision.
 
-Use [prompt.md](prompt.md) as a starter when handing an already-settled
-conversation to an agent with this skill installed.
+Use [prompt.md](prompt.md) as a starter for creation or revision with this skill
+installed.
@@ -23,32 +23,47 @@ function creation(): CreateDocument<string> {
 	};
 }
 
-test("the MCP service publishes its creation contract without implementation guidance", async () => {
-	let mcp = handler({
-		caller: () => "operator",
-		documents: {
-			async list() {
-				return [];
+test.each([false, true])(
+	"authoring instructions with updates=%s",
+	async updating => {
+		let mcp = handler({
+			caller: () => "operator",
+			documents: {
+				async list() {
+					return [];
+				},
+				async read() {
+					return undefined;
+				},
 			},
-			async read() {
-				return undefined;
-			},
-		},
-		create: creation(),
-	});
-	let initialized = await mcp(request({
-		jsonrpc: "2.0",
-		id: 1,
-		method: "initialize",
-		params: {},
-	}));
-	let initialization = await initialized.json() as {
-		result: { instructions?: string };
-	};
-	expect(initialization.result.instructions).toBe(
-		[
-			"Chopin's MCP contract and current tool descriptions are authoritative.",
-			"create_document: Create a Chopin document from a structured brief and canonical plan.",
-		].join("\n"),
-	);
-});
+			create: creation(),
+			update: updating
+				? {
+					async update() {
+						return { kind: "forbidden" };
+					},
+				}
+				: undefined,
+		});
+		let initialized = await mcp(request({
+			jsonrpc: "2.0",
+			id: 1,
+			method: "initialize",
+			params: {},
+		}));
+		let initialization = await initialized.json() as {
+			result: { instructions?: string };
+		};
+		expect(initialization.result.instructions).toBe(
+			[
+				"Chopin's MCP contract and current tool descriptions are authoritative.",
+				"create_document: Create a Chopin document from a structured brief and canonical plan.",
+				...(updating
+					? [
+						"update_document: Replace a Chopin document's canonical plan against the revision last read.",
+					]
+					: []),
+			].join("\n"),
+		);
+	},
+);
@@ -9,3 +9,15 @@ Chopin MCP initialize instructions and tool descriptions.
 ...
 
 </SETTLED_CONVERSATION>
+
+## Revise an existing document
+
+Use this prompt instead of the creation prompt when the document already exists:
+
+Revise `<CANONICAL_CHOPIN_DOCUMENT_URL>` to incorporate `<REQUESTED_CHANGES>`.
+Follow the installed `creating-chopin-plans` skill and the current Chopin MCP
+instructions. Read the latest source and revision before calling
+`update_document`; preserve server-owned projections and do not create a second
+document. Reconcile revision conflicts with a fresh read, and retry uncertain
+responses only with identical arguments and the same idempotency key. Return
+the canonical document URL and summarize the accepted changes.
@@ -25,6 +25,24 @@ Re-read the implementation before every lifecycle action, then follow the servic
 - Perform a separate review pass after implementation. Prefer a fresh reviewer sub-agent; otherwise review independently after stepping away. Resolve in-scope findings and run focused checks.
 - Create exactly one pull request per task. Update that pull request if later verification returns the task to work.
 
+## When the document needs revision
+
+`update_document` is for document authoring, not an implementation lifecycle
+shortcut. An active implementation locks the document and returns
+`document-locked` for a new update. If scope, acceptance criteria, or dependencies
+must change, stop code work and follow the current `request_revision` contract
+to release the graph. A task blocker alone does not release that lock.
+
+After release, hand the required document changes back to the authoring workflow.
+It should read the latest source and revision, preserve server-owned projections,
+and use a new revision-guarded update rather than recreate the document. Do not
+silently switch from implementing to rewriting or approving the plan. Resume
+implementation only after the service exposes an approved graph and a new claim
+succeeds against its current revisions and checkout context.
+Approval currently has no production UI or route. If no operator-provided
+approval path is available, report that blocker rather than promising an
+automatic resume.
+
 ## Verify the graph
 
 After every task is complete, perform an independent whole-graph verification. Run all relevant checks and capture command names, outcomes, and limitations as evidence for every task. Submit that evidence through the current service contract and follow the returned lifecycle state; only an accepted passing result releases a successful implementation.