/notabene

name: notabene
description: >-
  notabene docs review loop: process review comments left on the docs and verify
  the docs. Use when the user says "address the comments", "process the doc
  comments", "apply the review feedback", "review/check the docs", or references
  the global /comments page. Reads the notabene store, edits the docs per the
  feedback, marks them resolved + writes the journal, then verifies (renderer
  build, links, project checks). Ignores comments on "hold". This skill does NOT
  install, configure, or launch the review server — that's `notabene-setup`. Never
  commits without an explicit request.

<!-- Generated from docs/reference/agent-protocol.md + packages/claude-plugin/overlays/notabene.md by scripts/gen-protocol.mjs — do not edit. -->

Docs review loop (comments + verification)

**notabene**: a navigable renderer over a repo's docs + a human↔agent review loop. **Stateless** — the data lives in the consumer repo's git, not in the tool. What follows is the generic, agent-agnostic protocol; **three rules override it inside this plugin**:

1. **Not set up here?** No `notabene.config.mjs` or no `.notabene/` store → **hand off to the `notabene-setup` skill** (or `/notabene:setup`) to install/configure and launch, then resume. Don't fail; delegate — ignore the generic `npx … init` fallback below. 2. **Every CLI call goes through the plugin forwarder** — `node "${CLAUDE_PLUGIN_ROOT}/bin/nb.mjs" <cmd> --root <repo-root>` — never `npx notabene` (unscoped: not our package) and never a hardcoded version. This replaces **every** `npx -y @z29k/notabene@latest …` shown below (`comments ls`, `build`, `lint`, `journal add`). The loop still never depends on the CLI: file tools are enough. 3. **Authoring palette** — for what you can put in a page (Mermaid diagrams, GFM tables, code blocks, inter-doc links) and the MDX-safety rules, use the **`notabene-authoring`** skill rather than the web page linked in Step 4.

Discovery — EVERYTHING comes from the config (nothing hardcoded)

Read **`notabene.config.mjs`** at the repo root to learn:

• **`store`** — comments + journal folder (e.g. `docs/.notabene`). **One file per

comment**: `<store>/<page>/<id>.json` (so branches don't conflict on merge). Journal: `<store>/journal.json`. Schema version: `<store>/meta.json` (`{ "schemaVersion": <n> }`, currently **3**). Older stores keep one array per page (`<store>/<page>.json`) — both are read; `notabene migrate` upgrades a store to the current schema (v3, one file per comment).

• **`roots[]`** — the doc spaces: `{ key, label, path, exclude }`. A comment's `page`

field is prefixed by a root's `path` (e.g. root `docs/plans` → `page: "docs/plans/services/x"`).

• **`i18n`** (optional, `{ locales, defaultLocale, strategy }`) — the doc is multi-language

and a comment's `page` key is **locale-encoded**, mapping straight to that language's file: `strategy: "directory"` → `page: "docs/fr/guide/x"` = file `docs/fr/guide/x.md`; `strategy: "suffix"` → `page: "docs/guide/x.fr"` = file `docs/guide/x.fr.md` (the default locale is unsuffixed: `page: "docs/guide/x"` = `docs/guide/x.md`). Edit **that** file — a comment belongs to one language; don't touch the other language's file or auto-translate unless asked.

• **`verify[]`** — project-specific checks to run after editing.
• **`review`** — `"auto"` (default) or `"approve"`. In **approve** mode you don't resolve

comments yourself: you edit, mark them **`addressed`**, and a human validates them (with a diff) at `/review`. See Step 5.

Assume **no** path, port or label. Do not require a live server or a port.

Strict rules (no exceptions)

• **NEVER commit or run git operations without an explicit request** ("continue"/

"go on" ≠ commit). Offer the commit at the end.

• **NEVER bulk-delete the store** (`rm -rf <store>`): those are the user's **real

comments** (precious, committed). To clean a test, delete a single comment by `id` (edit its page file), never the folder.

• **Ignore `hold: true`** ("⏸ on hold") and `status` ≠ `open` (`addressed`/`resolved`

already handled): only process `open` **and not on hold**.

• **Account for EVERY comment in the roster** (step 1). A pass is not "some of the

comments" — each id ends the pass either handled (`resolved`/`addressed`) or **explicitly declined**, with the reason posted as a `thread` reply so the human sees it. Leaving one silently untouched is a **failed pass**, not a partial success: an untouched comment is indistinguishable from one the human wrote a minute ago, so nothing downstream can flag it — not `/review`, which only ever shows what you DID, and not `comments verify`, for which an `open` comment is perfectly legal. You are the only check. A long roster is a reason to work in batches, never a reason to stop early.

• **MDX-safety** (format `"mdx"` only): when editing a **`.mdx`** file, don't introduce

stray `{` or `<` outside code fences (MDX parses them as expression/JSX). **`.md`** files (CommonMark/GFM) are lenient — no such constraint. Validated by the renderer build.

• **File-I/O first**: read/write the `<store>/` files **directly** with your file

tools. The `astro dev` server need NOT be running — the HTTP `/api/comments` is only a convenience when the site is already open. Depend on **neither a port nor a process**.

Step 1 — Read the comments to process

List the actionable set with the CLI (any agent can shell out — no store-parsing to reimplement, no `python3`):

npx -y @z29k/notabene@latest comments ls --open --json   # open AND not-on-hold, machine-readable
npx -y @z29k/notabene@latest comments ls --open          # …or human-readable

**That list is the pass's roster. Take it ONCE, whole, and write the ids down** — into your task list, a scratch file, whatever survives the pass. Every later step is measured against it, and step 6 reconciles with it. Neither the CLI nor the HTTP AP