wikai
Download

Comments and highlights

A book chapter, an ingested PDF, a harvested article — the pages Wikai brings in verbatim are the ones you read closely and want to write in the margin of. Comments are that margin. The note lives in the panel beside the text, the words it is about stay marked, and the chapter itself is never edited: every comment is kept on a companion page of its own.

Comments work on verbatim pages in read mode — chapters, ingested documents, anything Wikai imported and you don’t edit. A note you write yourself is edited instead, so it has no Comment action.

Make a comment

Select a few words — within one paragraph — and a small bar appears with three actions: Highlight, Comment, and Copy link. The bar only offers them while the selection stays inside a single paragraph; a selection that crosses into the next one gets nothing, by design.

Comment opens a card in the right-hand panel with the cursor in it. It saves as you type, the way the editor does: the first save, a second after you start, creates the comment; every save after that edits it. ⌘↵, Esc or Done close the card. Esc on a card you haven’t typed in discards it — nothing was made yet.

Each comment has a marker color: yellow by default, or green, blue, pink or orange. A dot on the new card opens the five swatches; Wikai remembers the last color you used, per wiki, and preselects it next time.

⌘K inside a comment opens the same page picker the editor has. With words selected it wraps them in a link; at the cursor it inserts the page’s title as a link; a page that doesn’t exist yet is created first, filed beside the page you are commenting on.

Read them

The info panel beside a page has a switch: Connections or Comments. A page that has comments opens on Comments, with the panel open if it wasn’t.

Cards are stacked in the order of their words on the page. A card at rest shows the quoted words and the first lines of the note; open, it shows the whole note and any replies. Hover a card and its words light up in the text; hover the words and the card does. Click a card and the page scrolls to its words; click it again, once they are in view, and the card folds. Click the words in the text and the card opens — and the panel switches to Comments if it was showing something else.

A comment’s words wear a thin dashed underline in its color, so they read as commented and not merely marked. Two comments on overlapping words stack; a click on the overlap opens both.

The title bar counts what the page carries — 3 comments · 12 highlights. Click it to hide the marks for this page when you want to read clean. The count then reads · hidden, Wikai remembers the choice per page, and the cards stay in the panel.

Edit, recolor, promote, delete

The pencil on an open card edits the note in place; it saves as you type and closes the same way the new card does. The ⋯ menu holds the rest:

  • Color — the five swatches. The words and the card change together.
  • Promote to a page… — when a comment has outgrown a remark. Give it a title and a type (concept, synthesis, entity or person); the note’s text moves to the new page and the card keeps a pointer to it. The marked words stay where they are.
  • Delete — after a confirmation. Replies go with the comment; the words are left as they were.

Replies are not written from the card yet. An agent can add one with add_comment (see below), or you can write one on the companion page — a ### heading under the comment.

A comment whose words can no longer be found — the companion page was edited by hand and the quote no longer matches, say — is listed at the bottom of the panel under Could not be placed, and lint reports it.

Highlights

Highlight marks the selected words in the last color you used and makes nothing else: no card, no underline, no entry in the panel. The tint is the whole highlight. Click the stroke and a small popover offers the five swatches, Comment — which turns it into a comment, keeping the words and the color — and Remove, with no confirmation, because nothing is lost but the stroke.

Copy link writes nothing. If the words are already a comment or a highlight, you get a link to that entry. Otherwise you get a link to the paragraph with the words carried along:

[the Belgae are the bravest](pages/books/the-gallic-war/01-book-i.md#^id00059:~:text=the%20Belgae%20are%20the%20bravest)

Following either one lands on the page with those words in view and flashes them. With an editor open on another tab, Copy link inserts the link there instead of copying it — the same rule the rest of Wikai’s link copying follows.

This one isn’t limited to verbatim pages. Hover a paragraph on any page in read mode (a daily note’s timeline has its own affordances) and a small handle appears in the left gutter. Click it to copy [first words of the paragraph…](pages/x.md#^id) to the clipboard; ⌘⇧C does the same for the paragraph your cursor or selection is in. With an editor open elsewhere, the handle reads Insert link and puts the link at the caret.

Where comments live

All comments on one page live together on one companion page, at the source’s path mirrored under pages/comments/:

pages/books/the-gallic-war/01-book-i.md            the chapter
pages/comments/books/the-gallic-war/01-book-i.md   its comments

The companion page is ordinary Markdown with type: comments and a source: field. Each comment is a heading whose text is the quoted words and whose link is the paragraph they sit in, followed by the note; the color, when it isn’t yellow, sits between the link and the block id. Replies are ### headings under their comment.

## [the most distinguished and wealthy](pages/books/the-gallic-war/01-book-i.md#^p7q2m) {green} ^c02

"Wealthy" is doing the work here: Caesar reads Gallic politics as Roman
politics, where money buys a faction.

### Reply ^c03
Compare Book 6, where he says the opposite about the druids.

The source page’s file is byte-for-byte what it was before you commented. Fifty comments on a chapter cost one file.

Companion pages are hidden from the wiki overview, and any link to one — a backlink, a search hit, a block reference from another page — lands on the source page with that comment open. You will rarely open the file itself, though you can: it is a page like any other, and the editor accepts it.

The agent_edit policy of a companion page defaults to allow: a comment never changes the page it is about, so there is nothing to protect. If you would rather vet what an agent writes in your margins, set the shield on that companion page to Review, as on any page.

What agents see

Four MCP tools cover comments. list_comments_for returns every comment on a page — the quoted words, the paragraph, the note, replies, and whether each one could be placed — so “what did I say about this chapter?” is one call. add_comment adds a comment, a reply (reply_to), or, with an empty body, a highlight. edit_comment changes a comment’s text or color and delete_comment removes one with its replies. All four go through the same edit policy as any page write.

Limits worth knowing

  • One paragraph per comment. A comment spanning paragraphs is designed and deliberately not built until the one-paragraph version has been lived with.
  • Verbatim pages only. Comments anchor to text that doesn’t change. On a page you edit, the words could drift from under the comment; that is a second feature, not this one.
  • No reply from the card yet, as above.

Last updated 2026-10-07.