Review Comments

Run the dev server with --comment to turn any preview into a review surface. A small JavaScript client lets you click a rendered block — or the page itself — and leave a note. Notes are saved into a comments.wcl sidecar (not into your document source), so adding one writes only the sidecar and the comment appears instantly — the document never rebuilds.

bash

wcl wdoc serve --comment docs/main.wcl

Click 🎯 Comment on a block in the bottom-right toolbar to enter select mode, then click any block — including whole tables and diagrams — to leave a note on it (press Esc to cancel). The 💬 Comment on page button leaves a note about the page as a whole. Saving writes the sidecar and the pin appears in place — no rebuild, no live-reload.

The toolbar's 💬 N comments button shows how many comments live on the current page; click it for a modal listing them all — each with its target, body and quote, a Jump to link (for block comments), an Edit button (change the note in place), and a Resolve button. Individual block comments also appear inline as ✓ pins you can click.

§ 1Where comments are stored

Comments live in a comments.wcl sidecar — one beside each wskill's wskill.wcl, or beside the served root document for a page that isn't inside a wskill. The dev server's watcher ignores comments.wcl, and comments are placed client-side (the JS resolves each stored locator against the live page), so a note never triggers a document rebuild. This also means a *generated* comment is just a matter of writing the same comment { … } shape into the sidecar.

Each comment block is keyed by the page name plus a positional block locator (loc) within that page. A comment with no loc is about the whole page. A target records an auto description of the block (e.g. card — "Fast builds") so a reader can tell which block was meant.

§ 2The comments.wcl sidecar

wcl

comment {
  id = "c1a2b3"
  page = "home"
  loc = "0/2/1"                  // omit for a whole-page comment
  target = "card — \"Fast builds\""
  body = "2nd card is stale"
  author = "wil"
  quote = "Fast builds"
}

Field	Meaning
id	Stable handle — survives edits, so resolve can find the comment
page	The page name the comment is on
page_file	The page's source file (disambiguates same-named pages across wskills)
loc	Positional locator of the targeted block within the page (omit for the whole page)
target	Auto description of that block
body	The reviewer's note
author	Who left it (optional)
status	:open (default) or :resolved
quote	Exact text highlighted when commenting (optional)

§ 3Reading & resolving comments

An AI agent (or you) reads the stored comments, acts on them, and removes each once addressed. wcl wdoc comments scans every comments.wcl under the doc's directory. List them as JSON:

bash

wcl wdoc comments docs/main.wcl --format json

Each entry carries the id, scope, sidecar file, the page (and page_file), the body and quote, and the loc and target describing which block the note is about. After acting on a comment, delete it by its id:

bash

wcl wdoc comments docs/main.wcl resolve c1a2b3

Or change a note's body in place (its other fields are preserved):

bash

wcl wdoc comments docs/main.wcl edit c1a2b3 "updated note"

Resolve by id, not by position

Re-rendering can shift a block's locator, so the id is the durable handle. resolve <id> finds the matching comment across the sidecars and removes just that record.

Comment mode is dev-server only

The data-wcl-* anchors that drive the comment client are emitted only under wcl wdoc serve --comment. A normal build, pdf, or markdown never includes them.