From da80172558a3b086630afd86a4a0e9b9de8f6194 Mon Sep 17 00:00:00 2001 From: Codex Date: Thu, 30 Jul 2026 10:21:18 -0400 Subject: [PATCH 1/2] docs(agent): sync Quarry guidance --- crates/quarry-server/resources/prompt.md | 24 +++++++---- crates/quarry-server/resources/setup.md | 21 +++++----- crates/quarry-server/tests/rest_onboarding.rs | 42 ++++++++----------- 3 files changed, 43 insertions(+), 44 deletions(-) diff --git a/crates/quarry-server/resources/prompt.md b/crates/quarry-server/resources/prompt.md index 98e5aa2..c7e371b 100644 --- a/crates/quarry-server/resources/prompt.md +++ b/crates/quarry-server/resources/prompt.md @@ -1,33 +1,39 @@ - ## Quarry Use Quarry when a Markdown document needs review, comments, collaboration, or user markup. 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 ` 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. +Before the first edit, comment, or suggestion, read https://quarry.lithos.computer/quarry.SKILL.md for transaction schemas and block types. The full API reference is https://quarry.lithos.computer/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: ```bash -curl -sS -X POST __QUARRY_ORIGIN__/v1/tmp/documents \ +curl -sS -X POST https://quarry.lithos.computer/v1/tmp/documents \ -H 'Content-Type: application/json' \ -d '{"content": "# Draft\n\nBody text."}' ``` -The response includes the document's secret. Fetch `__QUARRY_ORIGIN__/v1/tmp/documents//agent-prompt` and follow it, and give the user the browser URL `__QUARRY_ORIGIN__/tmp/`. +The response includes the document's secret. Fetch `https://quarry.lithos.computer/v1/tmp/documents//agent-prompt` and follow it, and give the user the browser URL `https://quarry.lithos.computer/tmp/`. Quarry document URLs are bearer capabilities: anyone with the URL can read and edit the document, and documents on shared servers expire (30 days by default). Never put sensitive content on an untrusted server or log/repost a document URL. - diff --git a/crates/quarry-server/resources/setup.md b/crates/quarry-server/resources/setup.md index a330620..d5884e2 100644 --- a/crates/quarry-server/resources/setup.md +++ b/crates/quarry-server/resources/setup.md @@ -86,11 +86,10 @@ If no persistent instruction file exists and the user has not specified a tool, Use imports or symlinks only when the target agent supports normal Markdown files at that path. For UI-only settings such as Cursor User Rules or GitHub Copilot personal instructions, tell the user what text to add rather than editing an unknown file. -The canonical Quarry instruction block is hosted at __QUARRY_ORIGIN__/prompt.md and delimited by stable markers: +The canonical Quarry instruction section is hosted at __QUARRY_ORIGIN__/prompt.md. It starts with: ```text - - +## Quarry ``` After identifying or creating the right instruction file, fetch the canonical block: @@ -102,20 +101,20 @@ curl -fsSL __QUARRY_ORIGIN__/prompt.md -o "$canonical_quarry_block" Update the instruction file idempotently: -1. If the marker pair already exists, replace the entire marked block with the fetched block. -2. Otherwise, if a legacy unmarked `## Quarry` section exists, replace that section through the next level-two heading (or end of file) with the fetched block. Preserve any user-authored Quarry rules that are not part of the old canonical section by moving them outside the managed markers. +1. If an older `` and `` marker pair exists, replace the entire marked block with the fetched section. +2. Otherwise, if a `## Quarry` section exists, replace that section through the next level-two heading or end of file with the fetched section. 3. Otherwise, append the fetched block with one blank line separating it from existing content. -Never add a second Quarry heading or marker pair, and never overwrite unrelated instructions. Re-read the file afterward, verify that each marker appears exactly once and the surrounding content is unchanged, then remove the temporary canonical block. +Never add a second Quarry heading or overwrite unrelated instructions. Preserve user-authored Quarry rules that are outside the replaced section. Re-read the file afterward, verify that `## Quarry` appears exactly once and the surrounding content is unchanged, then remove the temporary canonical block. After updating your instructions, briefly tell the user which file you changed. ## Key Behaviors -- Share a document with `quarry open ` (or use `quarry new` for an empty one). Its printed connection instructions are the source of truth. +- Share a document with `quarry open `. 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. diff --git a/crates/quarry-server/tests/rest_onboarding.rs b/crates/quarry-server/tests/rest_onboarding.rs index cd7ff70..bf44f35 100644 --- a/crates/quarry-server/tests/rest_onboarding.rs +++ b/crates/quarry-server/tests/rest_onboarding.rs @@ -63,11 +63,11 @@ async fn onboarding_documents_render_the_forwarded_origin() { assert!(body.contains("https://quarry.lithos.computer/prompt.md")); assert!(body.contains("https://quarry.lithos.computer/example.md")); assert!(body.contains("## Install or Refresh Your Persistent Instructions")); - 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("replace the entire marked block with the fetched section")); + assert!(body.contains("if a `## Quarry` section exists")); + assert!(body.contains("verify that `## Quarry` appears exactly once")); + 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__")); @@ -79,37 +79,31 @@ async fn prompt_document_teaches_the_review_workflow() { assert_eq!(status, StatusCode::OK); assert_eq!(content_type, "text/markdown; charset=utf-8"); - assert_eq!( - body.matches("") - .count(), - 1 - ); - assert_eq!( - body.matches("") - .count(), - 1 - ); + assert!(!body.contains("")); + assert!(!body.contains("")); assert!(body.contains( "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( "Never put sensitive content on an untrusted server or log/repost a document URL." )); - assert!(body.contains("http://127.0.0.1:7831/quarry.SKILL.md")); + assert!(body.contains("https://quarry.lithos.computer/quarry.SKILL.md")); assert!(!body.contains("send `X-Agent-Id` on every request")); assert!(!body.contains("__QUARRY_ORIGIN__")); } From 9075ebb3f88669d60af492decd6e427acb83d88e Mon Sep 17 00:00:00 2001 From: Codex Date: Thu, 30 Jul 2026 10:23:29 -0400 Subject: [PATCH 2/2] docs(agent): restore prompt markers and origin tokens --- crates/quarry-server/resources/prompt.md | 8 +++++--- crates/quarry-server/resources/setup.md | 11 +++++----- crates/quarry-server/tests/rest_onboarding.rs | 20 +++++++++++++------ 3 files changed, 25 insertions(+), 14 deletions(-) diff --git a/crates/quarry-server/resources/prompt.md b/crates/quarry-server/resources/prompt.md index c7e371b..b7bef46 100644 --- a/crates/quarry-server/resources/prompt.md +++ b/crates/quarry-server/resources/prompt.md @@ -1,3 +1,4 @@ + ## Quarry Use Quarry when a Markdown document needs review, comments, collaboration, or user markup. @@ -22,18 +23,19 @@ When the review process is complete, sync the content from Quarry back to the fi ### Using Quarry -Before the first edit, comment, or suggestion, read https://quarry.lithos.computer/quarry.SKILL.md for transaction schemas and block types. The full API reference is https://quarry.lithos.computer/agent-docs. +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 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: ```bash -curl -sS -X POST https://quarry.lithos.computer/v1/tmp/documents \ +curl -sS -X POST __QUARRY_ORIGIN__/v1/tmp/documents \ -H 'Content-Type: application/json' \ -d '{"content": "# Draft\n\nBody text."}' ``` -The response includes the document's secret. Fetch `https://quarry.lithos.computer/v1/tmp/documents//agent-prompt` and follow it, and give the user the browser URL `https://quarry.lithos.computer/tmp/`. +The response includes the document's secret. Fetch `__QUARRY_ORIGIN__/v1/tmp/documents//agent-prompt` and follow it, and give the user the browser URL `__QUARRY_ORIGIN__/tmp/`. Quarry document URLs are bearer capabilities: anyone with the URL can read and edit the document, and documents on shared servers expire (30 days by default). Never put sensitive content on an untrusted server or log/repost a document URL. + diff --git a/crates/quarry-server/resources/setup.md b/crates/quarry-server/resources/setup.md index d5884e2..7a19f14 100644 --- a/crates/quarry-server/resources/setup.md +++ b/crates/quarry-server/resources/setup.md @@ -86,10 +86,11 @@ If no persistent instruction file exists and the user has not specified a tool, Use imports or symlinks only when the target agent supports normal Markdown files at that path. For UI-only settings such as Cursor User Rules or GitHub Copilot personal instructions, tell the user what text to add rather than editing an unknown file. -The canonical Quarry instruction section is hosted at __QUARRY_ORIGIN__/prompt.md. It starts with: +The canonical Quarry instruction block is hosted at __QUARRY_ORIGIN__/prompt.md and delimited by stable markers: ```text -## Quarry + + ``` After identifying or creating the right instruction file, fetch the canonical block: @@ -101,11 +102,11 @@ curl -fsSL __QUARRY_ORIGIN__/prompt.md -o "$canonical_quarry_block" Update the instruction file idempotently: -1. If an older `` and `` marker pair exists, replace the entire marked block with the fetched section. -2. Otherwise, if a `## Quarry` section exists, replace that section through the next level-two heading or end of file with the fetched section. +1. If the marker pair already exists, replace the entire marked block with the fetched block. +2. Otherwise, if a legacy unmarked `## Quarry` section exists, replace that section through the next level-two heading (or end of file) with the fetched block. Preserve any user-authored Quarry rules that are not part of the old canonical section by moving them outside the managed markers. 3. Otherwise, append the fetched block with one blank line separating it from existing content. -Never add a second Quarry heading or overwrite unrelated instructions. Preserve user-authored Quarry rules that are outside the replaced section. Re-read the file afterward, verify that `## Quarry` appears exactly once and the surrounding content is unchanged, then remove the temporary canonical block. +Never add a second Quarry heading or marker pair, and never overwrite unrelated instructions. Re-read the file afterward, verify that each marker appears exactly once and the surrounding content is unchanged, then remove the temporary canonical block. After updating your instructions, briefly tell the user which file you changed. diff --git a/crates/quarry-server/tests/rest_onboarding.rs b/crates/quarry-server/tests/rest_onboarding.rs index bf44f35..cfdf132 100644 --- a/crates/quarry-server/tests/rest_onboarding.rs +++ b/crates/quarry-server/tests/rest_onboarding.rs @@ -63,9 +63,9 @@ async fn onboarding_documents_render_the_forwarded_origin() { assert!(body.contains("https://quarry.lithos.computer/prompt.md")); assert!(body.contains("https://quarry.lithos.computer/example.md")); assert!(body.contains("## Install or Refresh Your Persistent Instructions")); - assert!(body.contains("replace the entire marked block with the fetched section")); - assert!(body.contains("if a `## Quarry` section exists")); - assert!(body.contains("verify that `## Quarry` appears exactly once")); + 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 review or feedback request authorizes comments")); assert!(body.contains("authorizes that direct edit")); assert!(body.contains("already authorized")); @@ -79,8 +79,16 @@ async fn prompt_document_teaches_the_review_workflow() { assert_eq!(status, StatusCode::OK); assert_eq!(content_type, "text/markdown; charset=utf-8"); - assert!(!body.contains("")); - assert!(!body.contains("")); + assert_eq!( + body.matches("") + .count(), + 1 + ); + assert_eq!( + body.matches("") + .count(), + 1 + ); assert!(body.contains( "Use Quarry when a Markdown document needs review, comments, collaboration, or user markup." )); @@ -103,7 +111,7 @@ async fn prompt_document_teaches_the_review_workflow() { assert!(body.contains( "Never put sensitive content on an untrusted server or log/repost a document URL." )); - assert!(body.contains("https://quarry.lithos.computer/quarry.SKILL.md")); + assert!(body.contains("http://127.0.0.1:7831/quarry.SKILL.md")); assert!(!body.contains("send `X-Agent-Id` on every request")); assert!(!body.contains("__QUARRY_ORIGIN__")); }