# 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.