docs(voyage): CLAUDE.md + README + CHANGELOG + annotation-quickstart + late doc-consistency pins — v4.2 Step 13

plugins/voyage/docs/annotation-quickstart.md

@@ -0,0 +1,55 @@
+# Annotation playground — quickstart
+
+The `/trekrevise` command and the `playground/voyage-playground.html` page
+let you annotate any voyage artifact (`brief.md`, `plan.md`, or `review.md`)
+and fold the annotations back in-place with a deterministic audit trail.
+
+This is **Handover 8** in `docs/HANDOVER-CONTRACTS.md`. For schema details,
+read that document first.
+
+## Hands-on with the example fixture
+
+The plugin ships a canonical fixture at
+`tests/fixtures/annotation/annotation-example.md` that is the same shape an
+operator would annotate. Use it to verify your playground works before
+touching a real project.
+
+## Seven steps from artifact to revised file
+
+1. **Open the playground.** Open `plugins/voyage/playground/voyage-playground.html`
+   in any modern browser. No build, no server, no network calls — the page
+   ships vendored `markdown-it` and `highlight.js` under `playground/lib/`.
+
+2. **Paste the artifact content.** Copy the full body of your `brief.md`,
+   `plan.md`, or `review.md` (including frontmatter) into the textarea on
+   the left. The right pane renders the markdown live. For larger artifacts
+   you can also generate the rendered HTML offline with
+   `node plugins/voyage/scripts/render-artifact.mjs <path> --out /tmp/x.html`.
+
+3. **Anchor a comment.** Drag-select text inside a paragraph, or hover a
+   block-level element and click the anchor button that appears. The
+   playground refuses anchors inside list items, mid-paragraph, or at
+   line-start collision points — only block boundaries are valid (per the
+   placement discipline in `lib/parsers/anchor-parser.mjs`).
+
+4. **Fill the modal.** Choose an intent (`change`, `add`, `remove`,
+   `clarify`, or `risk`), write your comment, save. Repeat for every
+   anchor you want in this batch. The sidebar shows your batch growing as
+   a critique-card-list.
+
+5. **Export the batch.** Click "Eksporter batch". The playground copies a
+   complete `/trekrevise --project <dir> --apply '{...JSON...}'` invocation
+   to your clipboard. The JSON encodes every anchor, intent, and comment.
+
+6. **Apply via `/trekrevise`.** Paste the command in your Claude Code chat.
+   The command parses + validates the batch, atomically writes anchor
+   comment blocks back into the source artifact, increments `revision:`,
+   appends entries to `source_annotations:`, and recomputes
+   `annotation_digest`. Body content outside anchor blocks remains
+   byte-identical.
+
+7. **Verify and iterate.** Re-open the revised file in the playground to
+   see anchors as inline comment markers. If you want another revision
+   pass, repeat from step 3 — each batch produces one `revision:` bump.
+   Single-iteration MVP per research-05; multi-iteration loops are
+   deferred.