docs(agent): sync Quarry guidance

crates/quarry-server/resources/prompt.md

@@ -5,19 +5,27 @@ Use Quarry when a Markdown document needs review, comments, collaboration, or us
 
 For plans, write a Markdown file and share it through Quarry for review.
 
-Share a document:
+### Share a newly written document
+
+To share a document you've written:
 
 ```bash
 quarry open "/absolute/path/to/file.md"
 ```
 
-Use `quarry new` to start an empty document instead. By default the CLI targets https://quarry.lithos.computer; pass `--server <url>` or set `QUARRY_SERVER` to use a different server (for example a local `quarry server start` on http://127.0.0.1:7831).
+`quarry open` creates the shared document, opens it in the user's browser, and prints connection instructions. Follow the connection mechanics, but preserve the current conversation. Instructions given before the document opens remain valid. If the user already gave a concrete Quarry task, continue it after the required reads without asking the user to repeat it. Use the ready-message-and-wait handshake only when no concrete Quarry task exists.
+
+### Editing existing documents
+
+When reviewing substantive changes to an existing Markdown document, first open it in Quarry and use suggestions for proposals or unsolicited changes. Apply a direct edit only when the user asks for that concrete change.
+
+When the review process is complete, sync the content from Quarry back to the file on disk.
 
-`quarry open` creates the shared document, opens it in the user's browser, and prints connection instructions. Follow the connection mechanics, but preserve the current conversation: instructions given before `quarry open` remain valid. If the user already gave a concrete Quarry task, continue it after the required reads without asking them to repeat it. Only use the ready-message-and-wait handshake when no concrete Quarry task exists.
+### Using Quarry
 
 Before the first edit, comment, or suggestion, read __QUARRY_ORIGIN__/quarry.SKILL.md for transaction schemas and block types. The full API reference is __QUARRY_ORIGIN__/agent-docs.
 
-While the user reviews, keep the document's events stream open (`GET .../events/stream`). When a `doc.changed` event arrives, re-read `.../blocks` and `.../review`, then respond. A task to review or leave feedback, comments, or suggestions authorizes review operations only; it does not authorize direct content edits. A concrete imperative comment such as “Add this section,” “Change this wording,” or “Remove this block” authorizes that requested edit: apply it with an edit op (use `insert_markdown` for a multi-block addition), reply with `comment.reply`, and resolve the addressed thread. Do not answer an implementation request only with a promise or proposal. Use `suggestion.add`, `suggestion.add_markdown`, or `suggestion.add_block_delete` when the user asks for a proposal or when you are recommending an unsolicited change.
+While the user reviews, keep the document's events stream open (`GET .../events/stream`). When a `doc.changed` event arrives, re-read `.../blocks` and `.../review`, then respond. A review or feedback request authorizes comments and suggestions only. A concrete comment such as ‘Add this section’ or ‘Remove this block’ authorizes that direct edit: apply it, reply with comment.reply, and resolve the thread with comment.resolve. Use suggestion.add, suggestion.add_markdown, or suggestion.add_block_delete when the user asks for a proposal or when you recommend an unsolicited change.
 
 If the `quarry` CLI is not installed, use plain HTTP instead:
 

crates/quarry-server/resources/setup.md

@@ -112,10 +112,10 @@ After updating your instructions, briefly tell the user which file you changed.
 
 ## Key Behaviors
 
-- Share a document with `quarry open <file>` (or use `quarry new` for an empty one). Its printed connection instructions are the source of truth.
+- Share a document with `quarry open <file>`. Its printed connection instructions are the source of truth.
 - Documents are live and collaborative. Monitor the events stream while the user reviews, and re-read the document after activity.
-- Never edit before the user asks. A concrete imperative comment is an edit
-  request for that scoped change: perform it, reply, and resolve the thread.
-  Do not merely promise the requested edit. Use suggestions when the user asks
-  for a proposal or for unsolicited changes you discover during review.
+- A review or feedback request authorizes comments and suggestions only. A
+  concrete comment such as "Add this section" or "Remove this block"
+  authorizes that direct edit: apply it, reply, and resolve the thread. Use
+  suggestions for proposals and unsolicited changes.
 - Document URLs are bearer capabilities, and shared-server documents expire (30 days by default). Never put sensitive content on an untrusted server or log/repost a document URL.

crates/quarry-server/tests/rest_onboarding.rs

@@ -66,8 +66,8 @@ async fn onboarding_documents_render_the_forwarded_origin() {
     assert!(body.contains("replace the entire marked block"));
     assert!(body.contains("legacy unmarked `## Quarry` section"));
     assert!(body.contains("verify that each marker appears exactly once"));
-    assert!(body.contains("A concrete imperative comment is an edit"));
-    assert!(body.contains("Do not merely promise the requested edit"));
+    assert!(body.contains("A review or feedback request authorizes comments"));
+    assert!(body.contains("authorizes that direct edit"));
     assert!(body.contains("already authorized"));
     assert!(body.contains("without asking the user to repeat it"));
     assert!(!body.contains("__QUARRY_ORIGIN__"));
@@ -93,17 +93,19 @@ async fn prompt_document_teaches_the_review_workflow() {
         "Use Quarry when a Markdown document needs review, comments, collaboration, or user markup."
     ));
     assert!(body.contains("quarry open"));
+    assert!(body.contains("### Share a newly written document"));
+    assert!(body.contains("### Editing existing documents"));
+    assert!(body.contains("sync the content from Quarry back to the file on disk"));
     assert!(body.contains("creates the shared document"));
-    assert!(body.contains("instructions given before `quarry open` remain valid"));
-    assert!(body.contains("Only use the ready-message-and-wait handshake"));
-    assert!(body.contains(
-        "A task to review or leave feedback, comments, or suggestions authorizes review operations only"
-    ));
+    assert!(body.contains("Instructions given before the document opens remain valid"));
+    assert!(body.contains("Use the ready-message-and-wait handshake only"));
+    assert!(body.contains("When reviewing substantive changes to an existing Markdown document"));
+    assert!(body.contains("A review or feedback request authorizes comments and suggestions only"));
     assert!(body.contains("suggestion.add"));
     assert!(body.contains("suggestion.add_block_delete"));
-    assert!(body.contains("A concrete imperative comment"));
-    assert!(body.contains("authorizes that requested edit"));
-    assert!(body.contains("Do not answer an implementation request only with a promise"));
+    assert!(body.contains("A concrete comment"));
+    assert!(body.contains("authorizes that direct edit"));
+    assert!(body.contains("apply it, reply with comment.reply"));
     assert!(body.contains("when the user asks for a proposal"));
     assert!(body.contains("bearer capabilities"));
     assert!(body.contains(