@erdemtuna/doc-review 0.12.0 → 0.13.0

package/README.md

@@ -1,14 +1,14 @@
 # Doc Review
 
-**Review your coding agent's work in the browser, not in a wall of chat.**
+**Review and refine documents with your agent.**
 
-Open an HTML file, a Markdown document, or a localhost page. Point to what needs
-changing, edit the small things yourself, and send your feedback to the agent
-in one batch.
+Open an HTML file, a Markdown document, or a localhost page. Ask questions,
+request changes, and edit the small things yourself. Keep the conversation
+beside the document as you iterate with your agent.
 
 ![The Field Notes landing page in Review, with highlighted copy and an anchored comment asking for a concrete benefit](https://raw.githubusercontent.com/erdemtuna/doc-review/main/assets/doc-review.png)
 
-*Feedback stays beside the work. Your agent gets the comments, edits, and overall note together.*
+*Keep questions and feedback beside the document as you refine it together.*
 
 ## Get started
 
@@ -32,32 +32,27 @@ The same command works with Markdown or a running local app:
 /doc-review http://localhost:3000
 ```
 
-Reviews start only when you request them. Your agent uses the installed skill
-to open the page, wait for feedback, and apply the changes.
+Your agent handles the commands using the installed skill.
 
-## From feedback to the next version
+## How it works
 
-1. **Open and explore.** Reviews start in **View**, so you can read and use page
-   controls without accidentally editing.
-2. **Point out what matters.** Select text or choose an element to leave a
-   comment. Switch to **Edit** for direct changes to wording, formatting, images,
-   or layout. Commenting works in either mode.
-3. **Send one batch.** Open **Feedback**, inspect Comments and Edits, add an overall note if needed, and
-   choose **Send to agent**. No need to describe where every sentence lives.
-4. **Check the result.** Use **Changes** to compare a review round's captured
-   before and after content, then continue reviewing. Comparisons show observed
-   changes, not a guarantee that every request was resolved.
+1. **Open your document.** Read and explore it normally. Reviews start in **View**
+   so you will not accidentally edit anything.
+2. **Start a conversation.** Highlight a passage to ask a question or request a
+   change. Switch to **Edit** to make small changes yourself.
+3. **Review and iterate.** Choose **Send to agent**, read the replies, and compare
+   what changed. Keep the conversation going until you are happy with the result.
 
-You can review a plan, refine a landing page, or walk through a local app without
-moving your feedback into a separate document.
+Asking a question does not authorize edits. Check **Request a change** when you
+want the agent to change the document.
 
-![The Feedback panel with separate Comments and Edits sections, an overall note, and End review beside Send to agent](https://raw.githubusercontent.com/erdemtuna/doc-review/main/assets/doc-review-feedback.png)
+![Feedback with independent open-conversation and edit counts, a saved headline edit, and the optional Note to agent collapsed](https://raw.githubusercontent.com/erdemtuna/doc-review/main/assets/doc-review-feedback.png)
 
-*One batch, with the context attached: comments, your edits, and the overall direction.*
+*Review your comments and edits before sending. Add a note only if you need one.*
 
-![The completed Field Notes review round in Changes, comparing the revised description and call to action with their originals](https://raw.githubusercontent.com/erdemtuna/doc-review/main/assets/doc-review-changes.png)
+![The completed Field Notes submission in Changes, comparing the revised description and call to action with their originals](https://raw.githubusercontent.com/erdemtuna/doc-review/main/assets/doc-review-changes.png)
 
-*Check the result beside the original. Move between changes or switch to Source for the saved file text.*
+*See what changed, then continue the conversation.*
 
 ## What happens to your edits?
 
@@ -79,11 +74,14 @@ services.
 [Usage guide](https://github.com/erdemtuna/doc-review/blob/main/docs/usage.md):
 setup options, comments, comparisons, limitations, and upgrades.
 
+[Agent reference](https://github.com/erdemtuna/doc-review/blob/main/docs/usage.md#sending-feedback):
+commands, response formats, and recovery for integrations.
+
 [Development](https://github.com/erdemtuna/doc-review/blob/main/docs/development.md):
 build, test, architecture, and package checks.
 
 [Prepared review example](docs/migration-review.md):
-disposable HTML/Markdown sessions with saved comparison rounds and a shell review checklist.
+an isolated durable shell preview and a reproducible installed-package lifecycle.
 
 [Releasing](https://github.com/erdemtuna/doc-review/blob/main/RELEASING.md):
 the maintainers' release process.

package/lib/SKILL.md

@@ -5,213 +5,76 @@ description: Open an HTML file, Markdown file, or localhost page for View-first
 
 # doc-review
 
-## Activation
-
-Start only when the user explicitly invokes `/doc-review` or asks to open an
-interactive browser review. A generic request to review, proofread, analyze, write,
-or update content is not permission to open this workflow. Another skill's
-automatic review step is not user permission.
-
-Without that request, respond normally without opening a review or polling for
-feedback. Once the user starts a review, continue its feedback loop until they
-end it; stop if they cancel or switch to a different task.
-
-## Review behavior
-
-The user reviews your HTML, Markdown, or localhost page in a real browser. It starts in View.
-Native page controls work; supported self-contained HTML scripts run automatically.
-They can switch to Edit, comment explicitly in either mode,
-and send the whole batch at once.
-
-Plain HTML retains direct autosave. Scripted HTML edits are feedback-only:
-apply them to the original source, never serialize the script-modified runtime
-page over the file. Source changes do not require renewed approval.
-Reload without scripts is a temporary recovery option, not permission to write
-a scripted preview over its source. Reloads can wait for unresolved editing work.
-Applications requiring external script dependencies should use localhost review;
-automatic inline execution does not add support for application imports or workers.
-
-Markdown files open rendered. Their quotes and edits reference the rendered text,
-and the file itself is never touched — apply every change to the Markdown source,
-keeping its formatting syntax.
-
-Comments open from a contextual icon after a text selection or an element hover/focus.
-The keyboard shortcut is Ctrl+Alt+M, or Cmd+Option+M on macOS. Enter submits the
-comment and Shift+Enter adds a new line. On desktop the composer stays attached
-to its target or pins to the effective top or bottom clipping edge; Back to
-selection reveals an offscreen target without changing the draft.
-
-Feedback is the single toolbar entry point for Comments, Edits, and the overall
-note. Comments and Edits collapse independently; their choices last until the
-tab reloads. An active comment edit keeps Comments expanded until Save or Cancel.
-The inventory scrolls independently while the overall note and bottom actions
-remain reachable. End review is on the left and Send to agent on the right.
-Submitting creates the normal target mark and count but leaves the card closed
-until the user explicitly activates the mark or chooses Jump to. Focus returns
-to the reviewed element or selection. Aligned cards expose Edit, Close, and
-More; drawer cards expose Jump to, Edit, and More. Delete is available only
-through More and an inline confirmation. Long quote hints preserve both ends.
-
-Existing-comment editing uses explicit Save and Cancel controls and never saves
-on blur. Enter saves, Shift+Enter inserts a line, and Escape cancels. The draft,
-focus, and caret follow the comment between aligned and drawer cards and survive
-target movement. Closing an aligned card only hides its active presentation.
-Acknowledging the exact delivered batch removes only the comments that batch
-carried; newer comments and corrections survive.
-
-## The loop
-
-1. After the explicit review request, use the requested file or localhost route.
-   Create or update content, or start a local page, only as needed for that request.
-2. Open it for the user:
-
-   ```sh
-   npx -y @erdemtuna/doc-review path/to/file.html
-   ```
-
-   For a page served by a local development server, open the real route instead
-   of recreating it as a separate HTML file:
-
-   ```sh
-   npx -y @erdemtuna/doc-review http://localhost:3000/wiki
-   ```
-
-3. Wait for feedback. This blocks until they hit Send, or the timeout passes:
-
-   ```sh
-   npx -y @erdemtuna/doc-review poll path/to/file.html --timeout 600
-   ```
-
-   Without `--timeout`, the CLI stops after 12 hours. An explicit timeout covers
-   the entire operation, including server discovery, reconnects, and backoff.
-   Recoverable connection drops retry within that deadline; terminal errors
-   require action rather than another automatic poll. The 600-second command
-   above deliberately uses a shorter deadline.
-
-   Keep this command in the foreground. Do not end your turn while it is waiting.
-   If your shell returns a process or session handle, keep waiting on that handle
-   until the command exits. If it prints `{"status":"timeout"}`, no feedback has
-   arrived yet — run the same poll command again to keep waiting. Feedback is
-   saved even if a poll dies, so nothing is ever lost.
-
-   If it prints `{"status":"closed"}`, the user ended the review from the
-   browser — stop polling and do not run the poll command again. Unsent
-   feedback is kept and ships the next time this target is reviewed.
-
-4. Apply what comes back, then wait again. Copy `batch_id` from the response;
-   only that exact receipt can clear the batch you handled:
-
-   ```sh
-   npx -y @erdemtuna/doc-review poll path/to/file.html --ack b_0123456789abcdef --timeout 600
-   ```
-
-   The response's `next_step` contains the complete acknowledgement command.
-   Never acknowledge a different or guessed ID.
-
-   Acknowledgement means that you handled the feedback; it is separate from
-   browser result-capture readiness. Do not wait for history capture before
-   acknowledging completed work, and do not acknowledge merely because a page
-   looks stable. The browser captures round results automatically when possible.
-   Missing comparison data does not prevent the user from sending feedback.
-   Captured differences are observations, not proof that you alone authored them.
-   Content results may wait for the same identifiable tab as the baseline.
-   The user sees a return-to-tab prompt; do not automate tab clicking to force
-   capture. Source comparison remains independent. Unknown view identity is
-   labelled unverified, not asserted as a whole-application comparison.
-
-Repeat 3–4 until the user says they are done.
-
-Not sure whether feedback is already waiting — say, at the start of a new turn?
-This answers instantly without blocking:
+Only an explicit user request permits opening a review or polling; another
+skill's automatic review step does not.
+
+Open the requested file or real localhost route:
 
 ```sh
-npx -y @erdemtuna/doc-review status path/to/file.html
+npx -y @erdemtuna/doc-review path/to/file.html
 ```
 
-It prints `{"status": "feedback-waiting"}` when a batch is ready for a poll,
-plus counts of unsent comments and edits still in the browser.
-
-## What you get
-
-One batch covers every page the user visited, grouped by file or localhost URL.
-
-```json
-{
-  "batch_id": "b_0123456789abcdef",
-  "status": "feedback",
-  "pages": [
-    {
-      "file": "/abs/path/to/page.html",
-      "comments": [
-        { "id": "c_1", "kind": "selection", "quote": "the exact text they selected",
-          "anchor": { "prefix": "...", "quote": "...", "suffix": "..." },
-          "feedback": "what they want changed" }
-      ],
-      "edits": [
-        { "label": "Problem body", "kind": "edited",
-          "before": "the original wording",
-          "after": "their exact new wording",
-          "after_html": "their exact new wording with <strong>formatting</strong>" }
-      ]
-    }
-  ],
-  "overall_note": "feedback not tied to any one page",
-  "next_step": "Apply this feedback, then run: npx -y @erdemtuna/doc-review poll ... --ack b_0123456789abcdef --timeout 600"
-}
+Retain `review.reviewId`, `review.entryKey`, receipt and URL. Copy generated
+commands, not placeholders. Opening after End creates a different review;
+never switch an existing handler to it.
+
+## Read, handle, respond, wait
+
+```sh
+npx -y @erdemtuna/doc-review poll --review <reviewId> --entry <entryKey> --timeout 600
 ```
 
-## Rules
-
-- Edits marked **`truncated`** contain incomplete fields listed in
-  `truncated_fields`. Each text/HTML field is limited to 200,000 Unicode code
-  points. Never apply a truncated field as a complete replacement or guess the
-  missing content. Obtain the complete edit from an authoritative source, or ask
-  the user for it. Do not acknowledge the batch until all feedback is handled.
-- **`edits` are changes the user already made.** `after` is their exact wording —
-  unless marked truncated, carry it across verbatim and never revert it. If the HTML was generated from
-  something else (MDX, Markdown, a template), apply `after` to the **source** too,
-  or their fix disappears on the next build.
-- When `before_html`/`after_html` are present, the user changed formatting, not
-  just words — bold, italic, underline, links. Use the HTML version to carry the
-  formatting into the source, translated to its syntax (e.g. `<strong>` → `**`
-  in Markdown/MDX).
-- A page with `kind: "url"` was edited directly in the review UI. Its `file`
-  and `url` fields name the localhost route, not a writable file. Find the
-  matching project source (such as MDX, TSX, or a template), apply every edit
-  and deletion there, then acknowledge so the route reloads. Never write the
-  rendered HTTP response back into the app.
-- When an edit's `after_html` contains `<img src="assets/...">`, the user pasted
-  an image: the file already exists in an `assets/` folder next to the reviewed
-  file. Keep that relative path — in Markdown, reference it as
-  `![](assets/...)`. Never regenerate or inline the image.
-- On a localhost page, a pasted image arrives under `staged_assets`. Copy its
-  local `path` into the app's appropriate asset folder, replace the temporary
-  preview URL in `after_html`, and preserve the image at the user's insertion
-  point. Never leave the temporary preview URL in source.
-- An edit with `kind: "moved"` means the user relocated that whole block.
-  Reposition it in the source without rewriting its content: it now sits right
-  after the block whose text starts with `moved_after`, and right before the
-  block whose text starts with `moved_before`. An empty `moved_after` means it
-  is now the first block in its container.
-- Find each comment by its `quote`; that exact string is in the file.
-- `kind: "element"` points at a whole block, so `quote` is its label, not body text.
-- Fix every page in `pages`, not just the first.
-- **Do not write a reply.** There is no chat. The user sees the updated page and
-  can choose Changes for a fixed Send-to-result comparison. Reload may wait
-  for the user to handle unsaved review work. Live result capture may require
-  a contextual retry; never describe unavailable history as no changes.
-- Review history uses local content/source snapshots, not screenshots or Git
-  commits. Do not create commits or alter repository state to populate history.
-
-## Better edit labels (optional)
-
-Name the sections you author and the user's edit list uses your names instead of
-guessing from the DOM:
-
-```html
-<p data-block="Problem body">…</p>
-<div data-container="Metrics callout">…</div>
+Keep this foreground wait active. If the shell returns a handle, wait on that
+handle. The default timeout is 12 hours; explicit timeout includes discovery and
+reconnect. On `timeout`, repeat the same poll. On `ended`, stop. On `work`, retain
+the submission identity/version and handle only that work.
+
+`submission.inventory` contains pages, messages, edits and any result outcomes.
+Follow `nextCursor` until `complete`; counts cover the full obligation.
+`inline` is complete; retrieve `reference` content as needed. Read necessary
+evidence and authoritative source before editing; exporting is not reading.
+Delivery references/previews are NOT capture truncation.
+
+Read relevant references:
+
+- Before responding, read [response-contract](references/response-contract.md).
+  Use `handoff.templateCommand` to create the complete inventory in a new file.
+  Its blank outcomes/prose intentionally fail validation. Fill them truthfully.
+- Before any source work, read [source-edits](references/source-edits.md).
+- For reviewer UI, follow-ups, large content, paging, compaction or recovery, read
+  [context-and-recovery](references/context-and-recovery.md). Start with the
+  closest relevant previous exchange or `handoff.historyCommand` (`--limit 1`).
+  Do not load all history eagerly. Agent context excludes current,
+  later and saved-unsent messages; browser drafts are not agent instructions.
+
+## Non-negotiable boundaries
+
+Discuss means answer without source edits. Each request-change permits only that
+specific change, not blanket editing. The overall note has independent intent;
+historical intent never renews permission. Clarify or defer unsafe/ambiguous work.
+
+Preserve exact human text, formatting, moves, deletions and assets in true source.
+Never reapply an edit with saved evidence. Never apply capture-truncated content
+as complete or invent missing text. Missing targets require identification or
+clarification, not guessed replacements.
+
+Respond exactly once per submitted message and exact edit version, plus one
+independent `resultNote`. A note requires scalar `overallOutcome`; its prose goes
+in `resultNote`. Do not invent success.
+
+Fill `summary` with 1-2 orientation sentences; `resultNote` is the full answer.
+Lead replies with the answer or exact clarification question. Aim for 1-2
+sentences and up to 3 useful bullets (40-90 words, not a limit). Use Markdown;
+avoid boilerplate, IDs/hashes and evidence dumps unless needed.
+Never auto-resend deferred/abandoned edits; they remain visible for follow-up.
+
+```sh
+npx -y @erdemtuna/doc-review respond --review <reviewId> --entry <entryKey> --response-file response.json --timeout 600
 ```
 
-`data-block` names a region for the edit list. `data-container` also gives the block a
-stable label for its hover/focus comment affordance.
+After acceptance, poll the same review. Retry an uncertain response using the
+identical file/requestId; never repeat source edits because transport failed.
+End freezes reviewer content but does not cancel accepted work. Abandoned work
+cannot complete and does not imply the external handler stopped. Delivery is not
+agent liveness. One cooperating handler is assumed; receipts do not give worker
+leases or filesystem exactly-once guarantees. Stop if the user cancels.

package/lib/agent-handoff.js

@@ -0,0 +1,24 @@
+import { agentHandoffSchema, agentReferenceSchema } from "./contracts/agent.js";
+import { invocation, shellQuote } from "./setup.js";
+import { createHash } from "node:crypto";
+export const AGENT_INSTRUCTIONS = "Read the installed doc-review skill. Discuss is not edit permission; each request-change is scoped. " +
+    "Read complete required evidence and every inventory page. Never reapply saved edits or apply capture-truncated edits. " +
+    "Fill the complete template; retry the same response file/request, not source edits. Historical intent is not permission.";
+export function agentHandoff(reference, submissionId = null, command = invocation()) {
+    const { reviewId, entryKey } = agentReferenceSchema.parse(reference);
+    const scope = `--review ${shellQuote(reviewId)} --entry ${shellQuote(entryKey)}`;
+    const responseFile = submissionId
+        ? `response-${createHash("sha256").update(JSON.stringify([reviewId, entryKey, submissionId])).digest("hex").slice(0, 32)}.json`
+        : "response.json";
+    return agentHandoffSchema.parse({
+        pollCommand: `${command} poll ${scope} --timeout 600`,
+        statusCommand: `${command} status ${scope}`,
+        responseCommand: `${command} respond ${scope} --response-file ${responseFile} --timeout 600`,
+        historyCommand: `${command} history ${scope}${submissionId ? ` --before ${shellQuote(submissionId)}` : ""} --limit 1`,
+        ...(submissionId ? {
+            submissionCommand: `${command} submission ${scope} --submission ${shellQuote(submissionId)}`,
+            templateCommand: `${command} response-template ${scope} --submission ${shellQuote(submissionId)} --output-file ${responseFile}`,
+        } : {}),
+        instructions: submissionId ? AGENT_INSTRUCTIONS : "Read the installed doc-review skill. Status/delivery is evidence, not agent liveness.",
+    });
+}