55 lines
2.7 KiB
Markdown
55 lines
2.7 KiB
Markdown
# 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.
|