/notabene-setup

name: notabene-setup
description: >-
  Install, configure, OR reconfigure notabene (the docs review tool) and start its
  review server — for a user who drives everything through the agent, on any stack
  (Rust/Python/Go/JS, no toolchain needed). Use to GET STARTED / LAUNCH: "set up
  notabene", "install notabene", "set up docs review/commenting", "start the review
  server", "open the review UI", "I want to leave comments on / review my docs", "get
  notabene running". Use to RECONFIGURE (a notabene.config.mjs already exists):
  "add/remove/rename a docs folder", "move the store", "switch review to
  approve/validation mode", "change notabene's port", "rename the site", "change the
  language", "add a verify step", "expose it on the LAN". This skill does NOT act on
  existing comments — processing review feedback is the `notabene` skill, which it hands
  off to once the server is up. Writes/edits notabene.config.mjs (shown first), creates
  the store, launches the server. Never commits; never exposes the LAN without an
  explicit request.

notabene setup (install · reconfigure · run)

Get a user from nothing (or from a config they want changed) to an open review server, **with zero npm/build commands typed by hand**, on any repo. The renderer is fetched and run **through `npx`** — nothing is installed into the user's repo; only **data** lives there (`notabene.config.mjs` + the `.notabene/` store + their docs).

Everything routes on **`doctor`** (read-only state) — you encode **no** defaults yourself. This skill only sets things up; **processing comments is the `notabene` skill** (hand off at the end).

The forwarder — how you call the tool

Never call `npx notabene` (unscoped — that package does not exist on npm) and never hardcode a version. Always go through the plugin forwarder, which pins the right renderer:

node "${CLAUDE_PLUGIN_ROOT}/bin/nb.mjs" <subcommand> --root <repo-root> [flags…]

`<repo-root>` = the current project directory (the repo whose docs you're reviewing). Use its absolute path. `nb.mjs` forwards to `npx -y --prefer-offline @z29k/notabene@<pinned>`.

Golden rules (no exceptions)

• **Never commit / push / rewrite history** without an explicit request. Tell the user to

commit the config + `.notabene/` store; don't do it for them. (Offering `git init` on a non-repo is fine — that's not a commit.)

• **Never expose the LAN** (`host: true` / `--host`) unless the user explicitly asks. It's

loopback-only by default; keep it that way.

• **Never `rm -rf` the store** or regenerate a config from the template over an existing

one — those hold the user's real comments and settings.

• **Confirm every config write/edit** by showing the diff first — in **express mode**,

still **print** the config you wrote (show, don't ask); never write invisibly.

• **Re-entrant & read-only-first**: `doctor` writes nothing, `init` is idempotent. Safe to

re-run at any point.

Step 0 — Preflight (always)

Run once and read the JSON:

node "${CLAUDE_PLUGIN_ROOT}/bin/nb.mjs" doctor --root <repo-root> --json

• **`{ "error": "npx-unavailable" }`** → the fallback branch. `npx` isn't on PATH (Claude

Code's bundled Node isn't always exposed). Guide the user to install Node — nodejs.org, their OS package manager, or `nvm` — then re-run Step 0. Don't proceed silently.

• **`node.ok: false`** → their Node is older than the required ≥ 22.12. `init` may still

work but the server (Astro) will fail silently in the daemon log. Warn and point to the Node requirement **before proceeding** — same install fixes as `npx-unavailable`.

• **First run is slow (~30 s, ~100 MB)**: the first `npx` fetches the renderer + Astro.

**Say so** before/while it runs, so the wait isn't mistaken for a hang.

• Then check `git.isRepo`. If false, offer `git init` (the store is meant to be committed).
• On a configured repo the report also carries **`protocol`** (`{ present, version, current }`

— the `<store>/protocol.md` copy) and **`agents`** (`{ present, block }` — the `AGENTS.md` entry point). Anything missing or `current: false` → re-run `init`, it repairs both.

• **Route on the config state**:
• `config.exists: false` → **Branch A** (fresh install).
• `config.exists: true, config.valid: true` → **Branch B** (reconfigure).
• `config.exists: true, config.valid: false` → **Branch C** (repair).

Branch A — fresh install (`config.exists: false`)

The report has no `config`/`store`/`port` blocks yet (there's no config to resolve) — it has **`docs.detected`** instead.

1. **Confirm the doc folders.** Present `docs.detected`. Keep only folders that are *actually* documentation; drop stray matches (a top-level `README`, `CHANGELOG`, generated dirs). If `docs.detected` is empty, ask where the docs live (don't guess). 2. **Choose the shape** — confirm with the user:

• `roots[]`: one entry per doc space, each `{ key (unique url slug), label, path,

exclude }`. Derive readable `key`/`label` from the paths; keep `key`s unique.

• `store`: put it under the primary root (e.g. `docs/.notabene`, or `<root>/.notabene`

if there's no `docs/`). It gets committed.

• `format`: **`commonmark`** by default (lighter, no MDX-safety traps). Write it

**explicitly** — the renderer's *code* default is `mdx`. Use `mdx` only if `.mdx` files exist or the user asks.

• `mdxComponents` (mdx only): if those `.mdx` files USE components (`<Something/>` they

don't import), the build fails without it — *"Expected component `X` to be defined"*. Grep the pages for such tags, then point the key at a repo-relative JS/TS module whose **default export** is a `{ Name: Component }` map. The repo often has one already (a site's component folder); if not, say so and let the user write it — never invent components. Per space: the same key on a `roots[]` entry replaces the global map. 3. **Write `notabene.config.mjs`** at the repo root — **show the di