open/ktg-plugin-marketplace
1
0
Fork 0
Code Issues Pull requests Releases Wiki Activity Actions
ktg-plugin-marketplace/plugins/voyage/docs/annotation-quickstart.md

2.7 KiB
Raw Blame History

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.