@z29k/notabene 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 z29k
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,200 @@
+# notabene
+
+**Comment your docs like Google Docs — then let your AI coding agent apply the
+feedback, resolve the threads, and journal *what changed and why*.**
+
+notabene renders your repo's Markdown/MDX as a navigable site with
+**Google-Docs-style commenting**, and ships the **human↔agent review protocol**
+that turns those comments into edits. The viewer is the support; **the protocol is
+the product.**
+
+> *nota bene* — the margin mark that means "note this." A comment.
+
+**MIT** · Node ≥ 18.20 · MDX **and** CommonMark/GFM · dev-local, zero backend ·
+_pre-1.0, dogfooded on a real multi-service platform._
+
+---
+
+## Why
+
+Doc review today is scattered across PR line-comments, chat threads, and "can you
+fix the wording in section 3." The feedback is disconnected from the doc, and
+applying it is manual and lossy.
+
+notabene puts the comments **on the rendered doc**, stores them **in your git**
+(no SaaS, no database), and closes the loop: your agent reads the comments, edits
+the docs, marks them resolved, and writes a journal entry linking *what changed* to
+*why*.
+
+- **Stateless tool, data in your git.** Comments and journal are JSON files under
+  `.notabene/`. They travel with your repo, diff in PRs, and are readable by your
+  agent. No account, no server to deploy, no central state.
+- **Agent-native.** The review loop ships as a Claude Code skill — and as a
+  plain-text protocol any agent can follow.
+- **MDX *and* CommonMark/GFM.** Point it at `.md` (lenient) or `.mdx` (strict), or
+  mix them — selectable via config.
+- **Dev-local & safe by default.** The write API only runs under `notabene dev`,
+  binds loopback (`127.0.0.1`) by default, and never ships in a build.
+
+## How it works (30 seconds)
+
+1. `npx notabene dev` → open the site, **select any text → leave a comment** (or
+   comment a whole page). Threads, resolve, hold, a global `/comments` view.
+2. Tell your agent: **"address the doc comments."**
+3. The agent reads `.notabene/`, edits the docs faithfully, marks each comment
+   **resolved**, and appends a **journal** entry (what / why / which comments).
+4. Read the trail at `/journal`.
+
+> 📽️ _Live in 30s — run `npx notabene dev` and select some text. (Demo GIF coming.)_
+
+## Install
+
+notabene is **two installable pieces**: the **renderer** (an npm package + CLI) and
+the **review skill** (a Claude Code plugin). Install one or both.
+
+### 1 · The renderer — npm package
+
+```bash
+npm install -D @z29k/notabene   # or: pnpm add -D @z29k/notabene · bun add -d @z29k/notabene
+npx notabene init               # writes notabene.config.mjs + creates the .notabene store
+npx notabene dev                # → http://localhost:3009
+```
+
+> The npm package is scoped (`@z29k/notabene`); the CLI command it installs is
+> just **`notabene`**, so `npx notabene …` works as-is.
+
+`init` is the **only** thing that touches your repo — it writes `notabene.config.mjs`
+and creates the `.notabene/` store. The renderer itself **runs from the package**
+(nothing is scaffolded or copied into your repo; upgrades are just `npm update`).
+
+CLI:
+
+| Command | What it does |
+| --- | --- |
+| `notabene init` | Write `notabene.config.mjs` + create the store (no-op if present) |
+| `notabene dev` | Start the review server over this repo's docs (live-reload) |
+| `notabene build` | Build the static site (no write API in the artifact) |
+| `notabene preview` | Serve the built site |
+
+Flags: `--port <n>` · `--config <path>` · `--root <path>` · `--host` (expose on the
+LAN — trusted networks only).
+
+### 2 · The review skill — Claude Code plugin
+
+In Claude Code:
+
+```
+/plugin marketplace add z29k/notabene
+/plugin install notabene@z29k
+```
+
+Then just say **"address the doc comments"** (or *"review the docs"*, *"apply the
+review feedback"*). The skill reads your `notabene.config.mjs`, processes the `open`
+(non-held) comments, edits the docs, marks them resolved, appends the journal, and
+runs your `verify` checks — never committing without asking.
+
+Prefer manual install? Copy `packages/plugin/skills/notabene/` into your project's
+`.claude/skills/`. Using another agent? The skill file **is** the protocol spec —
+point your agent at it.
+
+## Configure
+
+`notabene.config.mjs` at your repo root is the only wiring. Paths are repo-relative.
+
+```js
+// notabene.config.mjs
+export default {
+  siteName: "My Project",
+  tagline: "docs",
+  locale: "en",
+
+  // Input format. "mdx": .mdx STRICT + .md CommonMark/GFM lenient (mix by extension).
+  // "commonmark": everything CommonMark/GFM, no MDX dependency/strictness.
+  format: "commonmark",
+
+  // Doc spaces. `key` = url slug + store space; `path` = repo-relative folder.
+  roots: [
+    { key: "docs", label: "Docs", path: "docs", exclude: [".notabene/**"] },
+  ],
+
+  store: "docs/.notabene",   // comments + journal (commit this folder)
+  port: 3009,
+  host: false,               // loopback only — the write API edits your git
+  verify: [],                // consumer checks your agent runs after editing
+};
+```
+
+| Key | Default | Meaning |
+| --- | --- | --- |
+| `siteName` / `tagline` | `"Docs"` / `"docs"` | Header brand |
+| `locale` | `"en"` | UI language + nav sort collation |
+| `format` | `"mdx"` | `"mdx"` or `"commonmark"` (see below) |
+| `roots[]` | `[{docs}]` | Doc spaces: `{ key, label, path, exclude, description }` |
+| `store` | `"docs/.notabene"` | Comments + journal folder |
+| `port` | `3009` | `astro dev` port |
+| `host` | `false` | `true`/`NOTABENE_HOST=1`/`--host` exposes the write API to the LAN |
+| `verify[]` | `[]` | Post-edit checks the agent runs (the renderer build always runs) |
+
+## MDX and CommonMark/GFM
+
+The renderer picks the processor **by file extension**:
+
+- **`.md`** → CommonMark/GFM, **lenient**. `<email@x>`, `Promise<T>`, `{var}`, raw
+  HTML and GFM tables all render without a crash.
+- **`.mdx`** → **strict** MDX (JSX/expressions) — importable components, but `<`/`{`
+  outside code fences must be escaped.
+
+`format: "mdx"` (default) enables both, mixable in one repo. `format: "commonmark"`
+drops the MDX dependency entirely — best for a plain-Markdown repo.
+
+## The `.notabene` contract
+
+The store is a **versioned contract** (`<store>/meta.json` → `schemaVersion`), so
+your data stays portable and diffable. A comment:
+
+```jsonc
+{ "id", "space", "page", "scope",
+  "anchor": { "quote", "prefix", "suffix", "section" } | null,   // text-quote anchor
+  "thread": [{ "author", "body", "ts" }],
+  "status": "open" | "addressed" | "resolved",
+  "hold": false,                                                 // agent skips held comments
+  "resolution": { "note", "journalEntryId"? } | null,
+  "createdAt", "updatedAt" }
+```
+
+A journal entry: `{ id, date, title, summary, changes[] { page, commentIds[], what, why } }`.
+
+## Why not Starlight / Docusaurus / Google Docs?
+
+- **Starlight / Docusaurus** render docs beautifully — but there's no commenting and
+  no review loop.
+- **Google Docs** has commenting — but your docs aren't in Google Docs. They're in
+  your repo, in Markdown, next to your code, in your PRs.
+- **notabene** is the missing middle: review your **repo's** docs in the browser,
+  keep **everything in git**, and let your **agent** close the loop.
+
+## Safety
+
+The comments API writes into your git. So:
+
+- It **only runs under `notabene dev`** — it is not part of a build artifact
+  (writes return `403` outside dev).
+- It **binds loopback by default** — not reachable from your network unless you opt
+  in with `--host` / `NOTABENE_HOST=1` on a trusted network.
+- The agent skill **never commits without asking** and **never bulk-deletes** the
+  store.
+
+## Repo layout
+
+- **`packages/renderer`** — the `notabene` npm package (Astro renderer + CLI).
+- **`packages/plugin`** — the Claude Code plugin (the review skill).
+
+## Status & roadmap
+
+Pre-1.0 and **dogfooded on a real multi-service platform** before this release.
+Positioned as a **Claude Code companion** today; the protocol is agent-agnostic by
+design. Feedback and issues welcome.
+
+## License
+
+[MIT](./LICENSE).

package/astro.config.mjs

@@ -0,0 +1,37 @@
+// @ts-check
+import { defineConfig } from "astro/config";
+import mdx from "@astrojs/mdx";
+import node from "@astrojs/node";
+import { remarkRewriteLinks } from "./src/remark/rewrite-links.mjs";
+import { REPO_ROOT, host, mdxEnabled, port, roots } from "./src/config.mjs";
+
+// notabene renderer — a navigable site over a repo's docs + a human↔agent review
+// loop. DEV-LOCAL tool, not deployed. Plain Astro (not Starlight): content lives
+// OUTSIDE the app (glob `base` derived from notabene.config `roots[]`), and we keep
+// full control of the 3-column layout for the comments right-rail. Run-from-package:
+// the app renders the consumer's repo (NOTABENE_ROOT), only data lives there.
+export default defineConfig({
+  // SAFETY (§3): the comments API writes into the consumer's git. Default bind is
+  // LOOPBACK (host: false = 127.0.0.1) — the write endpoint is NOT reachable from
+  // the LAN. Explicit opt-in only (config `host: true` or NOTABENE_HOST=1), trusted
+  // networks only.
+  server: { host, port },
+  // Doc pages are static (prerendered); /api/comments is `prerender = false`
+  // (on-demand) → the Node adapter serves the write API. Dev-only.
+  adapter: node({ mode: "standalone" }),
+  // MDX only in "mdx" format (§10.bis). In "commonmark", .md files go through
+  // Astro's native markdown pipeline (lenient CommonMark/GFM).
+  integrations: mdxEnabled ? [mdx()] : [],
+  markdown: {
+    // GFM on by default. Shiki syntax highlighting.
+    shikiConfig: { theme: "github-dark", wrap: true },
+    // Rewrite inter-doc .md links → site routes (see src/remark/). Tuple form
+    // [attacher, options]: unified calls remarkRewriteLinks(roots).
+    remarkPlugins: [[remarkRewriteLinks, roots]],
+  },
+  vite: {
+    // Consumer content (docs, notabene.config) lives outside the Astro root
+    // (the app is in node_modules) → let Vite serve it.
+    server: { fs: { allow: [REPO_ROOT] } },
+  },
+});

package/bin/notabene.mjs

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+// notabene CLI — run-from-package. Renders a consumer repo's docs from this
+// package (no app is copied into the consumer). Only DATA lives in the consumer:
+// notabene.config.mjs + the .notabene store.
+//
+//   notabene init          write notabene.config.mjs + create the store (no-op if present)
+//   notabene dev           start the review server (astro dev) over the current repo
+//   notabene build         build the static site (no write API in the artifact)
+//   notabene preview       serve the built site
+//
+// Flags: --config <path> (default <cwd>/notabene.config.mjs), --root <path>
+// (consumer repo root, default cwd), --host (expose on the LAN — trusted only).
+import { spawn } from "node:child_process";
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+import fs from "node:fs";
+
+const require = createRequire(import.meta.url);
+// bin/ is at <package>/bin → the Astro app root is the package root.
+const APP_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+
+const argv = process.argv.slice(2);
+const cmd = argv[0];
+const flag = (name) => {
+  const i = argv.indexOf(name);
+  return i !== -1 ? (argv[i + 1] ?? true) : undefined;
+};
+
+const repoRoot = path.resolve(flag("--root") || process.cwd());
+const configPath = path.resolve(flag("--config") || path.join(repoRoot, "notabene.config.mjs"));
+const exposeHost = argv.includes("--host");
+
+function fail(msg) {
+  console.error(`notabene: ${msg}`);
+  process.exit(1);
+}
+
+const TEMPLATE_CONFIG = path.join(APP_DIR, "templates", "notabene.config.mjs");
+
+function readStore(cfgPath) {
+  // Best-effort: read the `store` value from an existing config to create it.
+  try {
+    const txt = fs.readFileSync(cfgPath, "utf8");
+    const m = txt.match(/store\s*:\s*["'`]([^"'`]+)["'`]/);
+    return m ? m[1] : "docs/.notabene";
+  } catch {
+    return "docs/.notabene";
+  }
+}
+
+function doInit() {
+  if (fs.existsSync(configPath)) {
+    console.log(`notabene: ${path.relative(repoRoot, configPath)} already exists — leaving it.`);
+  } else {
+    fs.copyFileSync(TEMPLATE_CONFIG, configPath);
+    console.log(`notabene: wrote ${path.relative(repoRoot, configPath)}`);
+  }
+  const store = path.resolve(repoRoot, readStore(configPath));
+  fs.mkdirSync(store, { recursive: true });
+  const meta = path.join(store, "meta.json");
+  if (!fs.existsSync(meta)) fs.writeFileSync(meta, `${JSON.stringify({ schemaVersion: 1 }, null, 2)}\n`);
+  console.log(`notabene: store ready at ${path.relative(repoRoot, store)}/`);
+  console.log("notabene: run `notabene dev` to start reviewing.");
+}
+
+function runAstro(astroCmd) {
+  if (!fs.existsSync(configPath)) {
+    fail(`no config at ${configPath}. Run \`notabene init\` first (or pass --config).`);
+  }
+  // Astro CLI entry, resolved from this package's deps. Astro's `exports` blocks
+  // deep subpaths, so resolve via package.json + its `bin` field.
+  const astroPkgPath = require.resolve("astro/package.json");
+  const astroPkg = JSON.parse(fs.readFileSync(astroPkgPath, "utf8"));
+  const binRel = typeof astroPkg.bin === "string" ? astroPkg.bin : astroPkg.bin.astro;
+  const astroBin = path.join(path.dirname(astroPkgPath), binRel);
+  // Note: build output goes to <APP_DIR>/dist (next to the renderer's deps, so
+  // Astro's prerender step resolves them). It's a throwaway verification artifact,
+  // gitignored, inside the installed package — not the consumer's source.
+  const args = [astroBin, astroCmd, "--root", APP_DIR];
+  const port = flag("--port");
+  if (port && port !== true) args.push("--port", String(port));
+  if (exposeHost) args.push("--host");
+  const child = spawn(process.execPath, args, {
+    stdio: "inherit",
+    cwd: repoRoot,
+    env: {
+      ...process.env,
+      NOTABENE_ROOT: repoRoot,
+      NOTABENE_CONFIG: configPath,
+      ...(exposeHost ? { NOTABENE_HOST: "1" } : {}),
+    },
+  });
+  child.on("exit", (code) => process.exit(code ?? 0));
+}
+
+switch (cmd) {
+  case "init":
+    doInit();
+    break;
+  case "dev":
+  case "build":
+  case "preview":
+    runAstro(cmd);
+    break;
+  default:
+    console.log(
+      "notabene — docs review tool\n\n" +
+        "  notabene init       write notabene.config.mjs + create the store\n" +
+        "  notabene dev        start the review server over this repo's docs\n" +
+        "  notabene build      build the static site\n" +
+        "  notabene preview    serve the built site\n\n" +
+        "Flags: --config <path>  --root <path>  --host",
+    );
+    process.exit(cmd ? 1 : 0);
+}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@z29k/notabene",
+  "version": "0.1.0",
+  "description": "Navigable docs renderer + human↔agent review loop. Comment your docs like Google Docs; an agent reads .notabene/, applies the feedback, and journals it.",
+  "type": "module",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "notabene": "bin/notabene.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "templates",
+    "astro.config.mjs",
+    "tsconfig.json"
+  ],
+  "scripts": {
+    "dev": "node bin/notabene.mjs dev",
+    "build": "node bin/notabene.mjs build"
+  },
+  "dependencies": {
+    "@astrojs/mdx": "5.0.6",
+    "@astrojs/node": "10.0.6",
+    "astro": "^6.0.0"
+  },
+  "keywords": ["docs", "documentation", "review", "comments", "mdx", "markdown", "astro", "ai", "agent"],
+  "engines": {
+    "node": ">=18.20.8"
+  }
+}