Notabene Setup

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 keys 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.

3. Write notabene.config.mjs at the repo root — show the diff and confirm first. Keep the safety default host: false. Shape:

   // notabene.config.mjs — points the generic docs review tool at YOUR docs.
   // Your data (docs, comments, journal) lives in your git, not in the tool.
   export default {
     siteName: "Docs",
     tagline: "docs",
     locale: "en",              // UI language + nav sort collation
     format: "commonmark",      // "mdx" only if you have .mdx files
     roots: [
       { key: "docs", label: "Docs", path: "docs", exclude: [".notabene/**"] },
     ],
     store: "docs/.notabene",   // comments + journal; commit it
     port: 3009,
     host: false,               // true / --host exposes the LAN — trusted networks only
     verify: [],                // extra post-edit checks the review loop runs
     review: "auto",            // "approve" = you validate each edit (with a diff) at /review
     // pdf: { enabled: true, pageSize: "A4", margin: "18mm" },  // PDF export (optional)
     // publish: { site: "https://user.github.io", base: "/repo" },  // `build --public` target (optional)
     // home: "docs/home.md",  // custom landing page above the space cards (optional)
     // branding: { logo: "assets/logo.svg", favicon: "assets/favicon.svg" },  // identity (optional)
     // theme: { tokens: { accent: "#7c3aed" }, css: "docs/theme.css" },  // --nb-* overrides (optional)
     // nav: { header: [{ label: "GitHub", href: "https://github.com/OWNER/REPO", icon: "github", iconOnly: true }] },  // outbound links (optional)
     // editPattern: "https://github.com/OWNER/REPO/edit/main/{path}",  // "Edit this page" footer link (builds/published sites; optional)
     // edit: { enabled: true, requireGit: true },  // in-page editor under `dev` — on by default; requireGit:false writes untracked files (optional)
     // author: "Alex", authorEmail: "alex@x.io",  // comment identity default (else git user.name/.email)
   };
   

4. Create the store: node "${CLAUDE_PLUGIN_ROOT}/bin/nb.mjs" init --root <repo-root> (idempotent; reads store from the config you just wrote, makes the dir + meta.json). It also writes the agent entry point: <store>/protocol.md (the full review protocol, so any agent — not just Claude Code — can run the loop offline) and a bounded <!-- notabene:begin -->…<!-- notabene:end --> block in the repo's AGENTS.md (created if absent, appended otherwise; nothing outside the markers is touched). Say what it wrote and offer --no-protocol / --no-agents-md if the user would rather not have them. Remind the user to commit .notabene/ + AGENTS.md — but don't commit them.

5. Check it's not ignored: git check-ignore <store>. A repo that ignores dotfolders could silently exclude .notabene/ (the contract is that it's committed). Warn if so.

6. Go to Launch & handoff.

Branch B — reconfigure (config.exists: true, config.valid: true)

The user wants to change an existing setup. Do not re-run onboarding and do not regenerate from the template.

1. Restate the current config from the report (config.roots/format/port/host/review/ store), then ask what to change.
2. Edit in place (Edit tool) — leave untouched fields and comments alone, show the diff, confirm. Common changes: add/remove/rename a roots[] entry; format; port; review (auto ↔ approve); siteName/tagline/locale; author/authorEmail; pdf (PDF export); publish ({ site, base, exclude } — the notabene build --public target: a read-only static site for public hosting; scope with roots[].publish: false / exclude globs / per-page frontmatter publish: false; the optional pagefind dev dep upgrades search — dev app AND public artifact — to full-text); home (a repo-relative Markdown file — or per-locale map — rendered as the landing page above the space cards); branding ({ logo, logoDark, favicon, socialImage } — repo-relative image files); theme ({ tokens, css, assets, code, mermaid } — --nb-* design-token overrides, validated, and/or a consumer stylesheet, a repo folder of fonts/images served at /_nb/assets/…, and a Shiki code theme; only the --nb-* contract, never internal variables); nav ({ header, sidebar, footer } — outbound links in the topbar, a titled sidebar block and a site footer: one item shape { label, href, icon, iconOnly, publish }, labels may be per-locale maps, and publish: false keeps a link out of public builds); editPattern (a URL template with a literal {path} placeholder — renders the page footer's "Edit this page" link, in builds and published sites only: under dev the in-page editor supersedes it); edit ({ enabled, requireGit } — the in-page editor, dev-only and on by default; requireGit: false lets it write a file git isn't tracking, which is the only undo it has, so leave it on unless asked; per space, roots[].edit: false makes that space read-only); verify[]; host (⚠ security — only on explicit request).
3. Surface the consequences — never silently (some edits orphan comments):
   • store moved → existing comments stay at the old path. Offer to move the store dir.
   • roots[].key renamed → changes URL slugs and the stored space/page prefix → re-anchoring breaks. Warn; offer to migrate the affected page values, or advise against it.
   • format mdx ↔ commonmark → different globbing + MDX strictness. Flag the MDX-safety implications.
4. Re-run init after any config edit — it's idempotent and it refreshes the agent entry point (<store>/protocol.md + the AGENTS.md block), which otherwise still points at the old store path or space keys. doctor reports the drift (protocol.current: false, agents.block: false).
5. Most changes (port, roots, format, host…) take effect only after a restart. Go to Launch & handoff and restart the server (see there).

Branch C — repair (config.exists: true, config.valid: false)

The config is present but failed to load. Do not overwrite it with the template.

1. Show config.error (from doctor) — it's the import/syntax failure.
2. Read the file, fix the syntax (a stray comma, a bad quote, an accidental import), and re-run Step 0 to confirm it now resolves (valid: true), then continue on Branch B.

Non-interactive mode (power user)

Detect an express signal — invoked as /notabene:setup … --yes, or the user gives explicit roots/format, or the phrasing is terse ("just set it up on docs/") — and cut the confirmations: defaults-first, write the config (print it — show, don't ask), init, launch, return the URL, no questions. Only stop on an undefaultable ambiguity (e.g. no doc folder detected and none given). Safety rails are never bypassed even with --yes: host, committing, and rm stay explicit.

Launch & handoff

1. Launch a detached daemon. dev --detach self-selects a free port, starts a real background server that survives this session, is idempotent (reuses a live one instead of starting a second), and prints the URL itself once the port answers — so run it as a normal Bash call (not run_in_background); it returns on its own:

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

   Pass --port <n> only to pin a specific port (e.g. port.suggested from doctor); to persist a port, edit the config instead. The first run also does the ~30 s renderer fetch, so this call can take a bit — say so. Give the user the http://localhost:<port> URL from its output.

2. Lifecycle (managed across sessions):

   • node "${CLAUDE_PLUGIN_ROOT}/bin/nb.mjs" status --json → { running, pid, port, url } (or /notabene:status).
   • node "${CLAUDE_PLUGIN_ROOT}/bin/nb.mjs" stop → stop it (or /notabene:stop).

3. On Branch B, most changes take effect only after a restart: stop then dev --detach. Confirm the current state first with status.

4. Hand off. Explain the loop in one line — leave comments on the rendered docs; the agent reads them, edits, journals, verifies — and point to the notabene skill (or /notabene:review) for processing those comments. If doctor reported store.openComments > 0 (typically a Branch B reconfigure of a populated repo), say so — N comment(s) already waiting; run /notabene:review. Setup's job ends here.

Fallback — npx unavailable

If Step 0 returns npx-unavailable, notabene can't run yet. Explain plainly: notabene runs via npx, which comes with Node, and Node isn't on PATH. Offer the concrete fixes (nodejs.org installer / OS package manager / nvm install --lts), then re-run Step 0. Don't attempt any renderer command until doctor succeeds.