readmark

Serve a folder of markdown docs as a rendered review website, leave line-anchored comments like a PR review, and hand those comments to an AI as structured, self-contained feedback.

Most docs under review are AI-generated — PRDs, tech designs, specs. readmark's reason to exist is the AI feedback loop: you review a generated doc, leave comments anchored to specific lines, and readmark comments emits a digest an AI can act on without opening the file. Markdown rendering is table stakes; the feedback loop is the point.

• No hosted backend, no auth, no database.
• Sharing is git: comments live as JSON under <dir>/.review/. Commit, push, teammate pulls.
• Fully offline — mermaid and KaTeX render client-side from vendored npm dist, never a CDN.

Install

npx @matheuspoleza/readmark serve docs        # no install needed
# or install globally, then the command is just `readmark`:
npm install -g @matheuspoleza/readmark

Author identity comes from your git config — no login:

git config user.name "Your Name"
git config user.email "[email protected]"

Quickstart

readmark serve docs

  readmark  v0.1.0

  Serving   docs/  (7 documents)
  Review    docs/.review/  (12 comments across 4 threads)
  Author    Your Name <[email protected]>   (from git config)

  ➜  Local:  http://localhost:4600

  Ready. Reload a doc in the browser to re-reconcile its comments. Press Ctrl+C to stop.

Open the URL. Pick a doc from the file tree.

The comment flow

1. Hover a line. A faint + fades in at the left edge of the block.
2. Click the + (or select a range of text first for a multi-line anchor). An inline composer opens, pre-anchored, with a header like "Commenting on line 14".
3. Type, then press Cmd/Ctrl+Enter (or click Comment). One click, typing, one keypress.

The comment card settles into the right gutter, aligned to its line, with a dot in the margin. A file docs/.review/<doc>/<threadId>.json is written. Reply and Resolve are on the card.

Comments track text, not line numbers

Each comment stores a snapshot of the lines it anchors to. On every reload, readmark reconciles that snapshot against the current file:

• Text moved (the doc grew or shrank above it) → the comment silently re-anchors and follows the sentence. No noise.
• Text deleted → the comment is marked outdated, floats to the top of the gutter, and shows the stored snapshot of what it pointed to — so you are warned, never silently misled.

This is what makes readmark usable on living, regenerated docs.

Sharing a review over git

There is no server to host. The review is just files:

git add docs/.review
git commit -m "review: comments on the PRD"
git push

A teammate pulls and runs the CLI — the status panel tells them feedback is waiting:

git pull
readmark serve docs        # "Review  docs/.review/  (12 comments across 4 threads)"

Each thread is one JSON file with a random-hex id, so two reviewers commenting offline never collide on merge.

The AI feedback loop

This is the payload. After a human review, hand the comments to an AI:

readmark comments docs            # self-contained text digest (for an AI or a human)
readmark comments docs --json     # canonical machine-readable shape

readmark — 4 threads, 12 comments  (3 open · 8 resolved · 1 outdated)
Author of this digest: Your Name <[email protected]>

════════════════════════════════════════════════════════════════════════
 docs/prd.md
════════════════════════════════════════════════════════════════════════

▸ Thread a3f2 · OPEN · lines 14
  ┃ > "The system SHALL sync transactions every 5 minutes."
  │
  │  Your Name · 2026-06-01
  │    5 minutes is too aggressive for the Pluggy rate limit — make it
  │    15 and say why.

▸ Thread c901 · OUTDATED · was lines 8
  ┃ ⚠ anchored text no longer found in file (showing stored snapshot)
  ┃ > "We will use a Redis queue for the import jobs."
  │
  │  Your Name · 2026-05-30
  │    Why Redis? A SQLite-backed queue is enough at this volume.

(8 resolved comments hidden. Run with --all to include them.)

Every emitted comment carries its file path, the quoted anchored doc text, and the body — so an AI can act without re-opening the source. A line-number-only digest would be useless; that is a defined failure mode here.

The loop:

1. Review the doc in the browser, leave comments.
2. readmark comments — pipe the digest (or --json) to your AI agent.
3. Regenerate the doc with the AI acting on the feedback.
4. Re-review — reload in the browser. Comments on surviving text stay anchored; comments on rewritten text flip to outdated, so you see exactly what changed.

readmark comments flags

| Flag | Effect | |---|---| | (default) | Show open + outdated comments. Resolved are hidden but counted. | | --all | Include resolved comments. | | --open | Only open comments. | | --json | Emit the canonical machine-readable shape. Composes: --json --open. |

readmark comments always exits 0; an empty review prints No comments.. When the output is piped (not a TTY), color and box-drawing are dropped but the > "..." quotes survive, so AI-captured output stays clean and self-contained.

Commands

readmark serve [dir]      Serve <dir> (default ./docs) as a review website.
                          --port <n>   Port to listen on (default 4600, auto-fallback).
readmark comments [dir]   Print a self-contained comment digest (default ./docs).
                          --json  --all  --open
readmark --help           Top-level help.
readmark --version        Print version.

Scope (v1)

In: serve + render (tables, mermaid, KaTeX, all offline) · file tree · one-click line-anchored comments · reply / resolve / reopen · one JSON file per thread · snapshot-based anchoring with silent re-anchor and outdated state · the comments digest · git-based sharing.

Out: hosted sharing, real-time collaboration, auth, avatars, a database, notifications, fuzzy re-anchoring. Sharing is git only.

License

MIT