diffninja 0.3.0 → 0.3.2

package/README.md

@@ -48,9 +48,12 @@ npx -y diffninja@latest setup
 It installs diffninja and adds it to every agent CLI it finds on your machine.
 Then restart your agent CLI.
 
-To update later, run the same command again. To remove diffninja from your
-agent CLIs, run `npx -y diffninja setup --uninstall`. Other options:
-`npx -y diffninja setup --help`.
+To update later, run the same command again: setup brings an older global
+install up to its own version, then restart your agent CLI. (Setup from
+0.3.0 or earlier does not update an existing install; if yours reports an
+older version, run `npm install -g diffninja@latest` once.) To remove
+diffninja from your agent CLIs, run `npx -y diffninja@latest setup --uninstall`.
+Other options: `npx -y diffninja@latest setup --help`.
 
 ## How to use it
 

package/dist/review/call-flow-html.d.ts

@@ -21,7 +21,9 @@ import type { ReviewReport } from "./types.js";
  * reaches the reviewer as a glyph plus color for a call that was added,
  * removed, or contains a change, and plain dimmed text for an unchanged call.
  */
-export declare function renderCallFlows(report: ReviewReport): string;
+export declare function renderCallFlows(report: ReviewReport, options?: {
+    readonly treeOnly?: boolean;
+}): string;
 export declare const CALL_FLOW_STYLES = "\n.cf {\n  display: flex; flex-direction: column; gap: 12px; margin-top: 18px;\n  --cf-add: #1a7f37; --cf-add-soft: #dafbe1;\n  --cf-del: #cf222e; --cf-del-soft: #ffebe9;\n  --cf-chg: #9a6700; --cf-chg-soft: #fff8c5;\n  --cf-quiet: var(--ink-soft);\n}\n@media (prefers-color-scheme: dark) {\n  .cf {\n    --cf-add: #3fb950; --cf-add-soft: rgba(46, 160, 67, 0.15);\n    --cf-del: #f85149; --cf-del-soft: rgba(248, 81, 73, 0.12);\n    --cf-chg: #d29922; --cf-chg-soft: rgba(187, 128, 9, 0.15);\n  }\n}\n/* Mode sections, folded files and the breadcrumb are toggled with the hidden\n   attribute, so the module carries that rule itself instead of relying on the page. */\n.cf [hidden] { display: none !important; }\n.cf-head { display: flex; flex-direction: column; gap: 4px; }\n.cf-prov { font-size: 12px; color: var(--ink-soft); }\n.cf-note { font-size: 12px; color: var(--ink-soft); overflow-wrap: anywhere; }\n.cf-absence { padding: 16px 0; }\n.cf-bounds {\n  margin: 10px 0 0;\n  padding: 2px 0 2px 10px;\n  border-left: 2px solid var(--cf-chg);\n  color: var(--ink-soft);\n  font-size: 12px;\n  overflow-wrap: anywhere;\n}\n.cf-controls { display: flex; align-items: center; flex-wrap: wrap; gap: 10px; }\n.cf-ready .cf-controls { position: sticky; top: var(--toolbar-height, 0px); z-index: 4; background: var(--bg); padding: 8px 0; }\n.cf, .cf-files, .cf-file-body, .cf-mode { min-width: 0; }\n.cf-modes {\n  display: inline-flex;\n  align-items: stretch;\n  border: 1px solid var(--line);\n  border-radius: 6px;\n  overflow: hidden;\n  background: var(--panel);\n}\n.cf-mode-link {\n  display: inline-flex;\n  align-items: center;\n  padding: 5px 14px;\n  font-size: 12px;\n  color: var(--ink-soft);\n  text-decoration: none;\n  border-right: 1px solid var(--line);\n}\n.cf-mode-link:last-child { border-right: 0; }\n.cf-mode-link:hover, .cf-mode-link:focus-visible { color: var(--ink); background: var(--sunken); }\n.js .cf-mode-link[aria-current] { color: var(--ink); background: var(--sunken); font-weight: 600; }\n.cf-jump ul {\n  display: flex;\n  flex-wrap: wrap;\n  gap: 8px;\n  list-style: none;\n  margin: 0;\n  padding: 0;\n  max-height: 22vh;\n  overflow-y: auto;\n}\n.cf-jump-link {\n  display: inline-flex;\n  align-items: center;\n  gap: 8px;\n  max-width: 100%;\n  min-width: 0;\n  padding: 4px 10px 4px 9px;\n  border: 1px solid var(--line);\n  border-radius: 6px;\n  background: var(--panel);\n  color: var(--ink);\n  font-size: 12px;\n  text-decoration: none;\n}\n.cf-jump-link:hover, .cf-jump-link:focus-visible { border-color: var(--cursor); }\n.cf-jump-path { min-width: 0; max-width: 32ch; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }\n.cf-jump-count { color: var(--ink-soft); white-space: nowrap; }\n.cf-crumbs {\n  display: flex;\n  align-items: center;\n  flex-wrap: nowrap;\n  gap: 6px;\n  font-size: 12.5px;\n  padding-bottom: 3px;\n  overflow-x: auto;\n  overscroll-behavior-x: contain;\n}\n.cf-crumb {\n  display: inline-flex;\n  align-items: center;\n  gap: 6px;\n  flex: 0 0 auto;\n  max-width: 34ch;\n  font: inherit;\n  font-size: 12px;\n  padding: 3px 10px;\n  border: 1px solid var(--line-strong);\n  border-radius: 999px;\n  background: var(--panel);\n  color: var(--ink);\n  cursor: pointer;\n  white-space: nowrap;\n}\n.cf-crumb[aria-current] { border-color: var(--cursor); font-weight: 600; }\n.cf-crumb-label { overflow: hidden; text-overflow: ellipsis; }\n.cf-crumb-file {\n  flex: 0 0 auto;\n  max-width: 22ch;\n  overflow: hidden;\n  text-overflow: ellipsis;\n  font-size: 11px;\n  color: var(--ink-soft);\n}\n.cf-sep { flex: 0 0 auto; color: var(--ink-soft); }\n.cf-files { display: flex; flex-direction: column; gap: 12px; }\n.cf-file {\n  background: var(--panel);\n  border: 1px solid var(--line);\n  border-left: 3px solid var(--line-strong);\n  border-radius: 6px;\n  overflow: hidden;\n}\n.cf-file { --cf-color: var(--ink-soft); --cf-fill: var(--sunken); }\n.cf-file-attention { border-left-color: var(--alarm); --cf-color: var(--alarm); --cf-fill: var(--alarm-bg); }\n.cf-file-uncertain { border-left-color: var(--warn); --cf-color: var(--warn); --cf-fill: var(--warn-bg); }\n.cf-file-low { border-left-color: var(--line-strong); }\n.cf-file-passed { border-left-color: var(--teal); --cf-color: var(--teal); --cf-fill: var(--teal-bg); }\n.cf-file-head {\n  display: flex;\n  align-items: center;\n  flex-wrap: wrap;\n  gap: 10px;\n  padding: 8px 12px;\n  background: var(--sunken);\n  cursor: pointer;\n  list-style: none;\n}\n.cf-file-head::-webkit-details-marker { display: none; }\n.cf-file-head::after {\n  content: \"\u25B8\";\n  margin-left: auto;\n  font-size: 11px;\n  color: var(--ink-soft);\n  transition: transform 0.15s ease;\n}\n.cf-file[open] > .cf-file-head::after { transform: rotate(90deg); }\n.cf-file-head:focus-visible { outline: 2px solid var(--cursor); outline-offset: -2px; }\n.cf-file-path { flex: 1 1 260px; min-width: 0; font-size: 12.5px; font-weight: 600; overflow-wrap: anywhere; }\n.cf-file-count { font-size: 12px; color: var(--ink-soft); white-space: nowrap; }\n.cf-diff-link { font-size: 12px; white-space: nowrap; }\n.cf-file-body { border-top: 1px solid var(--line); padding: 0 12px 12px; }\n.cf-mode { padding-top: 12px; }\n.cf-noscript { display: block; }\n.cf-noscript .cf-note { margin: 6px 0 0; }\n.cf-mode + .cf-mode { margin-top: 12px; border-top: 1px dashed var(--line); }\n.cf-mode-head {\n  margin: 0 0 8px;\n  font-size: 11.5px;\n  font-weight: 700;\n  letter-spacing: 0.08em;\n  text-transform: uppercase;\n  color: var(--ink-soft);\n}\n.cf-ready .cf-mode-head { display: none; }\n.cf-ready .cf-mode + .cf-mode { margin-top: 0; border-top: 0; }\n.cf-tree, .cf-children { list-style: none; margin: 0; padding: 0; }\n.cf-children { margin-left: 15px; padding-left: 10px; border-left: 1px dashed var(--line); }\n.cf-row { display: flex; align-items: center; flex-wrap: wrap; gap: 0 8px; padding: 2px 6px; border-radius: 6px; min-width: 0; }\n.cf-row:hover { background: var(--sunken); }\n.cf-fold > .cf-row { cursor: pointer; list-style: none; }\n.cf-fold > .cf-row::-webkit-details-marker { display: none; }\n.cf-fold > .cf-row::before { content: \"\u25B8\"; font-size: 10px; color: var(--ink-soft); transition: transform 0.15s ease; }\n.cf-fold[open] > .cf-row::before { transform: rotate(90deg); }\n.cf-badge, .cf-chip-badge {\n  display: inline-flex;\n  align-items: center;\n  justify-content: center;\n  flex: 0 0 auto;\n  min-width: 16px;\n  height: 16px;\n  border: 1px solid transparent;\n  border-radius: 4px;\n  font-family: var(--mono);\n  font-size: 11px;\n  font-weight: 700;\n}\n.cf-badge, .cf-chip-badge { color: var(--cf-node-color); background: var(--cf-node-fill); }\n.cf-label {\n  font: 400 12.5px/1.5 var(--mono);\n  padding: 0 2px;\n  border: 1px solid transparent;\n  border-radius: 4px;\n  background: none;\n  text-align: left;\n  /* Capped so a long call never pushes its row onto a second line; the\n     location takes what is left and truncates first. */\n  flex: 0 1 auto;\n  min-width: 0;\n  max-width: 62%;\n  white-space: nowrap;\n  overflow: hidden;\n  text-overflow: ellipsis;\n}\n.js .cf-label { cursor: pointer; }\n.js .cf-label:hover, .cf-label:focus-visible { text-decoration: underline; }\n.cf-label:focus-visible { outline: 2px solid var(--cursor); outline-offset: 1px; }\n.cf-loc { flex: 1 1 0; min-width: 0; font-size: 11px; color: var(--ink-soft); white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }\n.cf-loc-none { font-style: italic; }\n.cf-node, .cf-gnode, .cf-chip { --cf-node-color: var(--cf-chg); --cf-node-fill: var(--cf-chg-soft); --cf-node-weight: 600; --cf-node-decoration: none; }\n.cf-st-added { --cf-node-color: var(--cf-add); --cf-node-fill: var(--cf-add-soft); }\n.cf-st-removed { --cf-node-color: var(--cf-del); --cf-node-fill: var(--cf-del-soft); --cf-node-decoration: line-through; }\n.cf-node.cf-st-same, .cf-gnode.cf-st-same, .cf-chip.cf-st-same { --cf-node-color: var(--ink-soft); --cf-node-fill: var(--sunken); --cf-node-weight: 400; }\n.cf-label { color: var(--cf-node-color); font-weight: var(--cf-node-weight); text-decoration: var(--cf-node-decoration); }\n.cf-node.cf-ancestor > .cf-fold > .cf-row { display: none; }\n.cf-node.cf-ancestor > .cf-fold > .cf-children { margin: 0; padding: 0; border: 0; }\n.cf-svg-wrap {\n  max-width: 100%;\n  overflow: auto;\n  border: 1px solid var(--line);\n  border-radius: 6px;\n  background: var(--sunken);\n  overscroll-behavior: contain;\n}\n.cf-svg { display: block; max-width: none; }\n.cf-ready .cf-svg-wrap { height: clamp(220px, 42vh, 400px); overflow: hidden; touch-action: none; cursor: grab; }\n.cf-diagram-btn, .cf-diagram-close {\n  display: inline-flex; align-items: center; gap: 6px; height: 29px; padding: 0 12px;\n  border: 1px solid var(--line); border-radius: 6px; background: var(--panel);\n  font: 500 12px/1 var(--sans, inherit); color: var(--ink); cursor: pointer;\n}\n.cf-diagram-btn { color: var(--cursor); border-color: var(--cursor); }\n.cf-diagram-btn::after { content: \"\\2197\"; font-size: 12px; }\n.cf-diagram-btn:hover, .cf-diagram-close:hover { background: var(--sunken); }\n.cf-diagram-close { margin-left: auto; }\n.cf-diagram-hint { margin: 0 0 0 auto; font-size: 12px; color: var(--ink-soft); }\n.cf-diagram-hint + .cf-diagram-close { margin-left: 12px; }\n.cf.cf-diagram-open .cf-head { display: none; }\n/* The diagram view fills the browser window, and the graph gets nearly all of its height. */\n.cf.cf-diagram-open {\n  position: fixed; inset: 0; z-index: 50; margin: 0; padding: 12px 20px 20px;\n  background: var(--bg); overflow: auto; overscroll-behavior: contain;\n}\n.cf.cf-diagram-open .cf-controls { position: sticky; top: -12px; z-index: 5; background: var(--bg); padding: 10px 0; }\n.cf.cf-diagram-open .cf-modes, .cf.cf-diagram-open .cf-diagram-btn { display: none !important; }\n.cf.cf-diagram-open { padding-left: 292px; }\n.cf.cf-diagram-open .cf-svg-wrap { height: calc(100vh - 150px); min-height: 320px; }\n/* One canvas at a time: the entry point picked in the list, in its own file. */\n.cf.cf-diagram-open .cf-jump, .cf.cf-diagram-open .cf-bounds, .cf.cf-diagram-open .cf-omitted { display: none !important; }\n.cf.cf-diagram-open .cf-file:not(.cf-file-current) { display: none; }\n.cf.cf-diagram-open .cf-graph-frame:not(.cf-frame-current) { display: none; }\n.cf.cf-diagram-open .cf-file-body { padding-bottom: 0; }\n.cf-diagram-nav {\n  position: fixed; top: 0; bottom: 0; left: 0; width: 276px; overflow-y: auto; z-index: 6;\n  padding: 16px 12px; background: var(--sunken); border-right: 1px solid var(--line);\n}\n.cf-diagram-nav-head { margin: 0 0 10px; font-size: 13px; font-weight: 600; color: var(--ink); }\n.cf-diagram-nav-file {\n  margin: 14px 0 4px; font: 600 12px var(--mono); color: var(--ink-soft);\n  white-space: nowrap; overflow: hidden; text-overflow: ellipsis;\n}\n.cf-diagram-nav ul { list-style: none; margin: 0; padding: 0; display: flex; flex-direction: column; gap: 2px; }\n.cf-diagram-nav button {\n  display: flex; flex-direction: column; align-items: flex-start; gap: 1px; width: 100%;\n  padding: 6px 8px; border: 0; border-radius: 6px; background: none; color: var(--ink); text-align: left; cursor: pointer;\n}\n.cf-diagram-nav button:hover { background: var(--panel); }\n.cf-diagram-nav button[aria-current] { background: var(--panel); box-shadow: inset 3px 0 0 var(--cursor); }\n.cf-diagram-nav-name { max-width: 100%; font: 600 12px/1.35 var(--mono); overflow-wrap: anywhere; }\n.cf-diagram-nav-count { max-width: 100%; font-size: 11px; color: var(--ink-soft); white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }\n@media (max-width: 760px) {\n  .cf.cf-diagram-open { padding-left: 12px; padding-top: 12px; }\n  .cf-diagram-nav { position: static; width: auto; max-height: 30vh; margin: 0 0 8px; border: 1px solid var(--line); border-radius: 6px; }\n}\n.cf-ready .cf-svg-wrap:focus-visible { outline: 2px solid var(--cursor); outline-offset: 2px; }\n.cf-ready .cf-svg-wrap.cf-dragging { cursor: grabbing; user-select: none; }\n.cf-ready .cf-svg { width: 100%; height: 100%; }\n.cf-graph-frame + .cf-graph-frame { margin-top: 14px; }\n.cf-camera-tools { align-items: center; flex-wrap: wrap; gap: 5px; margin-bottom: 6px; }\n.cf-camera-tools button { min-height: 28px; padding: 0 10px; font-size: 12px; }\n.cf-scale { min-width: 4ch; text-align: center; font: 11px var(--mono); color: var(--ink-soft); }\n.cf-omitted { display: none; }\n.cf-ready .cf-omitted { display: block; }\n.cf-node.cf-selected > .cf-row, .cf-node.cf-selected > .cf-fold > .cf-row,\n.cf-chip.cf-selected { outline: 2px solid var(--cursor); outline-offset: 1px; border-radius: 5px; }\n.cf-edge { fill: none; stroke: var(--line-strong); stroke-width: 1.5; }\n.cf-gnode rect { fill: var(--panel); stroke: var(--line-strong); stroke-width: 1.5; }\n.cf-gnode:focus-visible { outline: none; }\n.cf-gzoom circle { fill: var(--panel); stroke: var(--line-strong); }\n.cf-gzoom text { fill: var(--ink); font: 14px var(--mono); }\n.cf-gzoom:hover circle, .cf-gzoom:focus-visible circle { stroke: var(--cursor); stroke-width: 2; }\n.cf-gzoom:focus-visible { outline: none; }\n.cf-glabel { font-family: var(--mono); font-size: 12px; fill: var(--ink); }\n.cf-gloc { font-family: var(--mono); font-size: 10px; fill: var(--ink-soft); }\n.cf-gnode.cf-st-same rect { stroke: var(--line); fill: transparent; }\n.cf-gnode.cf-st-same .cf-glabel { fill: var(--ink-soft); }\n.cf-gnode:not(.cf-st-same) rect { stroke: var(--cf-node-color); fill: var(--panel); }\n.cf-gnode:not(.cf-st-same) .cf-glabel { fill: var(--cf-node-color); font-weight: 600; }\n.cf-gnode:hover rect, .cf-gnode:focus-visible rect { stroke: var(--cursor); stroke-width: 2.5; }\n.cf-gnode.cf-selected rect { stroke: var(--cursor); stroke-width: 3; }\n.cf-paths { display: flex; flex-direction: column; gap: 6px; list-style: none; margin: 0; padding: 0; }\n.cf-path {\n  display: flex;\n  align-items: center;\n  flex-wrap: wrap;\n  gap: 4px 6px;\n  padding: 6px 8px;\n  border: 1px solid var(--line);\n  border-radius: 6px;\n  background: var(--panel);\n}\n.cf-chip {\n  display: inline-flex;\n  align-items: center;\n  gap: 6px;\n  max-width: 100%;\n  min-width: 0;\n  padding: 2px 8px 2px 4px;\n  border: 1px solid var(--line);\n  border-left: 3px solid var(--cf-node-color);\n  border-radius: 6px;\n  background: var(--panel);\n  color: var(--ink);\n}\n.cf-chip:hover, .cf-chip:focus-within { border-color: var(--cursor); }\n.cf-chip-zoom {\n  display: inline-flex;\n  align-items: center;\n  gap: 6px;\n  max-width: 100%;\n  min-width: 0;\n  color: inherit;\n  text-decoration: none;\n}\n.cf-chip-label { min-width: 0; max-width: 36ch; font-size: 12px; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }\n.cf-chip-loc { min-width: 0; max-width: 28ch; font-size: 10.5px; color: var(--ink-soft); white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }\n.cf-chip.cf-st-same .cf-chip-label { color: var(--ink-soft); }\n.cf-chip:not(.cf-st-same) .cf-chip-label { color: var(--cf-node-color); font-weight: 600; }\n.cf-chip .cf-desc { max-width: 28ch; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }\n.cf-arrow { color: var(--ink-soft); font-size: 12px; }\n/* One description line per call, only when the backend attached one. */\n.cf-desc { font-size: 11.5px; color: var(--ink-soft); font-style: italic; overflow-wrap: anywhere; }\n.cf-business { display: flex; flex-direction: column; gap: 6px; margin: 4px 0 10px; }\n.cf-business-note { font-size: 13px; color: var(--ink-soft); }\n.cf-plumbing-toggle { display: inline-flex; align-items: center; gap: 7px; font-size: 13px; color: var(--ink-soft); cursor: pointer; width: fit-content; }\n.cf:has(.cf-show-plumbing:not(:checked)) .cf-node.cf-plumbing { display: none; }\n.cf-purpose { font-family: var(--sans); font-size: 13.5px; font-weight: 550; color: var(--ink); overflow-wrap: anywhere; }\n.cf-row > .cf-purpose { flex: 1 0 100%; order: -1; padding-left: 26px; }\n.cf-fold > .cf-row > .cf-purpose { padding-left: 16px; }\n.cf-node.cf-explained > .cf-row .cf-label, .cf-node.cf-explained > .cf-fold > .cf-row .cf-label { font-size: 11.5px; }\n.cf-chip .cf-purpose { font-size: 12.5px; max-width: 34ch; }\n.cf-gpurpose { font-family: var(--sans); font-size: 12px; font-weight: 600; fill: var(--ink); }\n.cf-diagram-nav-name.cf-diagram-nav-purpose { font-family: var(--sans); white-space: normal; }\n.cf-row > .cf-desc { flex: 1 0 100%; order: 5; padding-left: 26px; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }\n.cf-row > .cf-src-link { order: 4; }\n.cf-depth { align-items: center; gap: 4px; }\n.cf-depth-label { font-size: 12px; color: var(--ink-soft); }\n.cf-depth-btn { padding: 3px 9px; font-size: 12px; }\n.cf-depth-btn[aria-pressed=\"true\"] { border-color: var(--cursor); color: var(--cursor); font-weight: 600; }\n/* Numbered, clickable call order on the graph edges. */\n.cf-edge-num circle { fill: var(--panel); stroke: var(--line-strong); stroke-width: 1.5; }\n.cf-edge-num text { font-family: var(--mono); font-size: 10.5px; fill: var(--ink-soft); }\n.cf-edge-num:hover circle, .cf-edge-num:focus-visible circle { stroke: var(--cursor); stroke-width: 2; }\n.cf-edge-num:hover text, .cf-edge-num:focus-visible text { fill: var(--cursor); font-weight: 700; }\n.cf-edge-num:focus-visible { outline: none; }\n.cf-gdesc { font-family: var(--mono); font-size: 10px; font-style: italic; fill: var(--ink-soft); }\n/* Resolved definition of one call: a native disclosure without the script, and\n   the body the script clones into its single shared panel. */\n.cf-source { margin: 3px 0 3px 24px; }\n.cf-ready .cf-source { display: none; }\n.cf-src-sum { width: fit-content; cursor: pointer; list-style: none; font-size: 11.5px; color: var(--ink-soft); }\n.cf-src-sum::-webkit-details-marker { display: none; }\n.cf-src-sum::before { content: \"\u25B8\"; margin-right: 6px; font-size: 10px; transition: transform 0.15s ease; display: inline-block; }\n.cf-source[open] > .cf-src-sum::before { transform: rotate(90deg); }\n.cf-src-sum:hover, .cf-src-sum:focus-visible { color: var(--cursor); }\n.cf-src-body { padding: 6px 0 4px; }\n.cf-src-ref { margin: 0 0 5px; font-size: 11.5px; color: var(--ink-soft); overflow-wrap: anywhere; }\n.cf-src-code {\n  margin: 0;\n  padding: 6px 9px;\n  border: 1px solid var(--line);\n  border-radius: 6px;\n  background: var(--sunken);\n  font-family: var(--mono);\n  font-size: 11.5px;\n  line-height: 1.5;\n  overflow-x: auto;\n}\n.cf-src-line { display: block; white-space: pre; }\n.cf-src-no {\n  display: inline-block;\n  width: 4ch;\n  margin-right: 10px;\n  text-align: right;\n  color: var(--ink-soft);\n  user-select: none;\n}\n.cf-src-note { margin: 0; font-size: 11.5px; color: var(--ink-soft); font-style: italic; }\n.cf-src-panel {\n  padding: 8px 12px 10px;\n  border: 1px solid var(--line-strong);\n  border-radius: 6px;\n  background: var(--panel);\n}\n.cf-src-panel-sum { width: fit-content; cursor: pointer; font-size: 12.5px; font-weight: 600; }\n.cf-src-panel-body { padding-top: 6px; }\n.cf-src-panel-body { max-height: 40vh; overflow: auto; }\n.cf-src-head-line { margin: 0 0 6px; font-size: 12px; color: var(--ink-soft); overflow-wrap: anywhere; }\n.cf-src-missing { margin: 0; }\n.cf-src-link {\n  flex: 0 0 auto;\n  font-size: 11px;\n  color: var(--ink-soft);\n  text-decoration: none;\n  white-space: nowrap;\n  padding: 0 6px;\n  border: 1px solid var(--line);\n  border-radius: 999px;\n}\n.cf-src-link:hover { text-decoration: none; }\n.cf-src-link:hover, .cf-src-link:focus-visible { color: var(--cursor); }\n@media (max-width: 680px) {\n  .cf-jump ul { max-height: 38vh; }\n  .cf-jump-link { width: 100%; }\n  .cf-jump-path { max-width: none; flex: 1 1 auto; }\n  .cf-file-body { padding: 0 11px 12px; }\n  .cf-crumb { max-width: 24ch; }\n  .cf-crumb-file { max-width: 12ch; }\n  .cf-source { margin-left: 10px; }\n  .cf-src-no { width: 3ch; margin-right: 7px; }\n  .cf-chip, .cf-chip-zoom { min-width: 0; flex-wrap: wrap; }\n  .cf-chip-loc { overflow-wrap: anywhere; }\n}\n";
 /**
  * Progressive enhancement for the rendered call flow. Nothing here is

package/dist/review/call-flow-html.js

@@ -24,7 +24,8 @@ import { nodeFunctionId, purposesOf, wrapPurpose } from "./explanation.js";
  * reaches the reviewer as a glyph plus color for a call that was added,
  * removed, or contains a change, and plain dimmed text for an unchanged call.
  */
-export function renderCallFlows(report) {
+export function renderCallFlows(report, options = {}) {
+    const treeOnly = options.treeOnly === true;
     const purposes = purposesOf(report);
     const files = collectFiles(report.callFlows, report.items, purposes);
     if (files.length === 0) {
@@ -35,7 +36,7 @@ export function renderCallFlows(report) {
         '<div class="cf">',
         renderSummary(files, new Set(report.items.map(item => item.file)).size),
         renderPlumbingToggle(plumbing, report.agentExplanation?.explainedBy),
-        renderControls(),
+        treeOnly ? "" : renderControls(),
         renderJump(files),
         '<nav class="cf-crumbs" id="cf-crumbs" aria-label="Visited call trail" hidden></nav>',
         // One panel the script fills with the focused call's definition; without the
@@ -45,7 +46,7 @@ export function renderCallFlows(report) {
         '<div class="cf-src-panel-body" id="cf-src-panel-body"></div>',
         "</details>",
         '<div class="cf-files">',
-        files.map((view, index) => renderFile(view, index + 1)).join("\n"),
+        files.map((view, index) => renderFile(view, index + 1, treeOnly)).join("\n"),
         "</div>",
         "</div>",
     ].join("\n");
@@ -267,7 +268,7 @@ function renderJump(files) {
     ].join("\n");
 }
 /** One file section: severity, path, call count and its diff link. */
-function renderFile(view, at) {
+function renderFile(view, at, treeOnly) {
     const { dot, tone, count } = fileFacts(view);
     const status = view.status;
     const diff = `<a class="cf-diff-link" data-open-hunk href="#item-${view.rank}">View diff #${view.rank}</a>`;
@@ -284,8 +285,8 @@ function renderFile(view, at) {
         view.truncated
             ? `<p class="cf-bounds">Bounds reached for this file: ${escapeHtml(BOUNDS_TEXT)}. Calls cut at a bound are omitted.</p>`
             : "",
-        modesNote(),
-        renderModes(view, at),
+        treeOnly ? "" : modesNote(),
+        treeOnly ? renderTreeMode(view, at, false) : renderModes(view, at),
         "</div>",
         "</details>",
     ]
@@ -303,7 +304,7 @@ function renderFile(view, at) {
  */
 function renderModes(view, at) {
     return [
-        renderTreeMode(view, at),
+        renderTreeMode(view, at, true),
         lazyMode("graph", at, renderGraphMode(view, at)),
         lazyMode("sequence", at, renderSequenceMode(view, at)),
     ].join("\n");
@@ -321,10 +322,10 @@ function modesNote() {
         `resolved definition opens on its own. The diff holds every changed line.` +
         `</p></noscript>`);
 }
-function modeSection(mode, at, body) {
+function modeSection(mode, at, body, headed = true) {
     return [
         `<section class="cf-mode cf-mode-${mode}" id="cf-f${at}-${mode}" data-cf-mode-body="${mode}">`,
-        `<h3 class="cf-mode-head">${MODE_LABEL[mode]}</h3>`,
+        headed ? `<h3 class="cf-mode-head">${MODE_LABEL[mode]}</h3>` : "",
         body,
         "</section>",
     ].join("\n");
@@ -333,11 +334,11 @@ function modeSection(mode, at, body) {
 function lazyMode(mode, at, section) {
     return `<template data-cf-lazy-mode="${mode}" data-cf-file="${at}">${section}</template>`;
 }
-function renderTreeMode(view, at) {
+function renderTreeMode(view, at, headed) {
     const trees = view.trees
         .map((tree, root) => renderTreeNode(tree, [root], at, view.file, view.purposes))
         .join("\n");
-    return modeSection("tree", at, `<ul class="cf-tree">${trees}</ul>`);
+    return modeSection("tree", at, `<ul class="cf-tree">${trees}</ul>`, headed);
 }
 /** The resolved definition of one call. It is a native disclosure, so the actual
  *  source is readable without the script, and the script clones this body into

package/dist/review/connected-html.js

@@ -1843,7 +1843,8 @@ function script(csrf) {
     for (var i = 0; i < list.length; i += 1) {
       var s = list[i];
       var shaped = s && typeof s === 'object' && typeof s.path === 'string' && typeof s.line === 'number'
-        && (s.side === 'LEFT' || s.side === 'RIGHT') && typeof s.body === 'string' && s.body !== '';
+        && (s.side === 'LEFT' || s.side === 'RIGHT') && typeof s.body === 'string' && s.body !== ''
+        && SEVERITY_LABELS[s.severity] !== undefined;
       if (!shaped || !currentLine(s) || settled[suggestionKey(current.snapshotId, s)]) continue;
       out.push(s);
     }
@@ -1910,12 +1911,17 @@ function script(csrf) {
     render();
   }
 
+  var SEVERITY_LABELS = { critical: 'Critical', major: 'Major', minor: 'Minor' };
+
   function suggestionRow(suggestion, disabled) {
     var wrap = make('div', 'suggestion');
     var head = make('p', 'suggestion-by');
     head.appendChild(make('span', 'agent-dot', ''));
     head.appendChild(make('strong', '', suggestedBy()));
     head.appendChild(document.createTextNode(' suggests'));
+    var severity = make('span', 'severity severity-' + suggestion.severity, SEVERITY_LABELS[suggestion.severity]);
+    severity.title = 'How much the agent thinks this matters';
+    head.appendChild(severity);
     wrap.appendChild(head);
     wrap.appendChild(make('p', 'suggestion-body', suggestion.body));
     var actions = make('div', 'suggestion-actions');
@@ -3071,8 +3077,14 @@ kbd {
 .editor { border-color: var(--accent); box-shadow: 0 0 0 1px var(--accent-soft); }
 .editor-row { display: flex; flex-wrap: wrap; gap: 8px; align-items: center; }
 .editor-input { flex: 1 1 240px; min-width: 0; }
-.suggestion-by { font-size: 12px; color: var(--ink-soft); }
+.suggestion-by { display: flex; flex-wrap: wrap; align-items: center; gap: 4px; font-size: 12px; color: var(--ink-soft); }
 .suggestion-by strong { color: var(--ink); font-weight: 600; }
+.severity {
+  margin-left: 6px; padding: 1px 7px; border-radius: 4px; font-size: 11.5px; font-weight: 600; letter-spacing: 0.02em;
+  color: var(--ink-soft); background: var(--neutral-soft);
+}
+.severity-critical { color: var(--alarm); background: var(--alarm-bg); }
+.severity-major { color: var(--warn); background: var(--warn-soft); }
 .suggestion-body { font-size: 14px; line-height: 1.5; overflow-wrap: anywhere; }
 .suggestion-actions { display: flex; flex-wrap: wrap; gap: 6px; align-items: center; }
 

package/dist/review/html.d.ts

@@ -35,7 +35,8 @@ export declare function renderBusinessPage(report: ReviewReport): string;
 /**
  * The call flows of one review as a page of their own, for the connected pull
  * request page to show beside its diff: every changed file with call flows, or
- * only `file` when given. Tree, Graph and Sequence work as in the report; links
- * into the report's diff are dropped, since the page showing this has its own.
+ * only `file` when given. Only the Tree view is offered, and the business view
+ * stays out of it: the page around it already shows that view. Links into the
+ * report's diff are dropped, since the page showing this has its own.
  */
 export declare function renderCallFlowPage(report: ReviewReport, file?: string): string;

package/dist/review/html.js

@@ -110,7 +110,6 @@ const BUSINESS_VIEW_STYLES = `
 .business { padding-top: 14px; }
 .business-title { font-size: 20px; }
 .business-lede { margin-top: 4px; color: var(--ink-soft); font-size: 14px; max-width: 90ch; }
-.flow-section-title { margin: 22px 0 0; font-size: 18px; }
 `;
 /**
  * Posts the document's height to the page that frames it, so the pull request
@@ -122,7 +121,9 @@ const BUSINESS_FRAME_SCRIPT = `
   'use strict';
   function post() {
     if (window.parent === window) return;
-    window.parent.postMessage({ type: 'diffninja-business-height', height: Math.ceil(document.documentElement.scrollHeight) }, window.location.origin);
+    // The html element's own box, not scrollHeight: scrollHeight never drops below the frame's
+    // height, so the frame could grow but never shrink back around its content.
+    window.parent.postMessage({ type: 'diffninja-business-height', height: Math.ceil(document.documentElement.getBoundingClientRect().height) }, window.location.origin);
   }
   window.addEventListener('load', post);
   if (typeof ResizeObserver !== 'undefined') new ResizeObserver(post).observe(document.body);
@@ -173,8 +174,9 @@ body { background: var(--bg); font-family: var(--sans); }
 /**
  * The call flows of one review as a page of their own, for the connected pull
  * request page to show beside its diff: every changed file with call flows, or
- * only `file` when given. Tree, Graph and Sequence work as in the report; links
- * into the report's diff are dropped, since the page showing this has its own.
+ * only `file` when given. Only the Tree view is offered, and the business view
+ * stays out of it: the page around it already shows that view. Links into the
+ * report's diff are dropped, since the page showing this has its own.
  */
 export function renderCallFlowPage(report, file) {
     const scoped = file === undefined ? report : { ...report, callFlows: report.callFlows.filter((entry) => entry.file === file) };
@@ -186,20 +188,11 @@ export function renderCallFlowPage(report, file) {
         '<meta name="viewport" content="width=device-width, initial-scale=1">',
         '<meta name="color-scheme" content="light dark">',
         `<title>${escapeHtml(file === undefined ? "Call flows" : `Call flow: ${file}`)}</title>`,
-        `<style>${STYLES}\n${CALL_FLOW_STYLES}\n${PALETTE_STYLES}\n${BUSINESS_STYLES}\n${BUSINESS_VIEW_STYLES}\n${EMBEDDED_FLOW_STYLES}</style>`,
+        `<style>${STYLES}\n${CALL_FLOW_STYLES}\n${PALETTE_STYLES}\n${EMBEDDED_FLOW_STYLES}</style>`,
         "</head>",
         "<body>",
-        report.agentExplanation === undefined
-            ? ""
-            : [
-                '<section class="flow-embed business" aria-labelledby="flow-business-title">',
-                `<h2 class="business-title" id="flow-business-title">${file === undefined ? "How it works" : "How this file fits the process"}</h2>`,
-                renderBusinessView(report, { file, glossary: false }),
-                "</section>",
-            ].join("\n"),
         `<section id="view-call-flow" class="flow-embed${file === undefined ? "" : " flow-single"}" aria-label="Call flow">`,
-        report.agentExplanation === undefined ? "" : '<h2 class="flow-section-title">Call flow</h2>',
-        renderCallFlows(scoped),
+        renderCallFlows(scoped, { treeOnly: true }),
         "</section>",
         `<script>document.documentElement.classList.add('js');\n${CALL_FLOW_SCRIPT}</script>`,
         "</body>",

package/dist/review/mcp.js

@@ -9,7 +9,9 @@ import { detectPullRequest } from "./pr-input.js";
 import { renderBusinessPage, renderCallFlowPage, renderReview } from "./html.js";
 import { MAX_SUGGESTED_COMMENTS, ReportPages } from "./report-pages.js";
 import { reviewDiff } from "./service.js";
+import { COMMENT_SEVERITIES } from "./types.js";
 import { MAX_BRANCH_CHARS, MAX_DETAIL_CHARS, MAX_EXPLAINED_FUNCTIONS, MAX_PROCESSES, MAX_PROCESS_STEPS, MAX_PURPOSE_CHARS, MAX_RULES, MAX_RULE_CHARS, MAX_STEP_CHARS, MAX_STEP_EXITS, MAX_TITLE_CHARS, MIN_PROCESS_STEPS, } from "./explanation.js";
+import { packageVersion } from "./version.js";
 const PR_LINK_ERROR = "A pull request review needs exactly one full github.com pull request URL, for example https://github.com/OWNER/REPO/pull/123. Ask the user for their link; do not guess, search, or invent one.";
 const STATIC_MODE_ERROR = "mode static reviews a diff or git range and accepts no pr or input. Use mode connected to review a pull request link.";
 /**
@@ -220,7 +222,7 @@ class ReviewServer extends McpServer {
     sessions;
     reports;
     constructor(sessions, reports) {
-        super({ name: "diffninja", version: "0.1.0" });
+        super({ name: "diffninja", version: packageVersion() });
         this.sessions = sessions;
         this.reports = reports;
         this.server.onclose = () => {
@@ -244,8 +246,9 @@ const commentSchema = z.object({
     line: z.number().int().positive().describe("The line number on that side."),
     side: z.enum(["LEFT", "RIGHT"]).describe("RIGHT for an added or context line (new side), LEFT for a removed line (old side)."),
     body: z.string().max(1000).describe("The comment, as the reviewer would write it: one short line, no labels or formatting."),
+    severity: z.enum(COMMENT_SEVERITIES).describe("How much it matters, so the human can triage: critical for a bug, data loss, security or contract break that should block the merge; major for a real risk or missing case worth fixing before merge; minor for a nit, naming or style point. Give it here, never inside the body."),
 }).strict();
-const COMMENT_RULES = "Only comment where a maintainer would actually ask for something or point something out: a bug, a risk, a missing case, a confusing name, a missing test; never pad. Write each one as the reviewer would type it on GitHub, in their own voice: short (one line, at most 280 characters), concrete, conversational, e.g. \"This drops the error from Close(); should we return it?\" or \"nit: could this reuse parseVersion?\". No report scaffolding: no headings, bold, list markers, numbering, or labels such as Finding, Issue, Attention, Error, Severity. Each names a line of the diff: path, line, and side RIGHT for an added or context line, LEFT for a removed line; at most one per line and 30 in all.";
+const COMMENT_RULES = "Only comment where a maintainer would actually ask for something or point something out: a bug, a risk, a missing case, a confusing name, a missing test; never pad. Write each one as the reviewer would type it on GitHub, in their own voice: short (one line, at most 280 characters), concrete, conversational, e.g. \"This drops the error from Close(); should we return it?\" or \"nit: could this reuse parseVersion?\". No report scaffolding: no headings, bold, list markers, numbering, or labels such as Finding, Issue, Attention, Error, Severity. Each names a line of the diff: path, line, and side RIGHT for an added or context line, LEFT for a removed line; at most one per line and 30 in all. Each also carries a severity (critical, major or minor) in its own field, which the page shows next to the comment so the human reviews the important ones first; the words critical, major and minor do not belong in the body.";
 /**
  * What the goal summary is for. It is the agent's own paragraph for the human
  * reading the pull request, written from the author's own title and
@@ -461,12 +464,7 @@ export function createReviewServer() {
         description: "Update the line comments suggested for a pull request review after finish_review, or before it. " + COMMENT_RULES + " The whole call is refused, and the previous suggestions kept, if any comment breaks these rules. A later call replaces the earlier suggestions; an empty list clears them. Nothing is posted: the page shows each suggestion under its line, attributed to this MCP client, and the human adds it to their own review, edits it, or dismisses it. This returns no page link: only finish_review does.",
         inputSchema: z.object({
             reviewId: z.string().regex(/^[a-f0-9]{32}$/).describe("The reviewId a review_diff result returned on this connection."),
-            comments: z.array(z.object({
-                path: z.string().min(1).max(1024).describe("The file's path in the diff."),
-                line: z.number().int().positive().describe("The line number on that side."),
-                side: z.enum(["LEFT", "RIGHT"]).describe("RIGHT for an added or context line (new side), LEFT for a removed line (old side)."),
-                body: z.string().max(1000).describe("The comment, as the reviewer would write it: one short line, no labels or formatting."),
-            }).strict()).max(MAX_SUGGESTED_COMMENTS),
+            comments: z.array(commentSchema).max(MAX_SUGGESTED_COMMENTS),
         }).strict(),
         annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     }, async ({ reviewId, comments }) => {

package/dist/review/process-html.d.ts

@@ -22,8 +22,6 @@ import type { ReviewReport } from "./types.js";
 export interface BusinessViewOptions {
     /** Link for a hunk id, or undefined when this page has no diff to link to. */
     readonly hunkHref?: (itemId: string) => string | undefined;
-    /** Draw only the processes and rules that touch this changed file. */
-    readonly file?: string;
     /** Leave out the function glossary (the call-flow view shows the purposes). */
     readonly glossary?: boolean;
     /** Leave out the attribution line when the page around it already says who explained it. */
@@ -32,9 +30,7 @@ export interface BusinessViewOptions {
     readonly stepsOpen?: boolean;
 }
 /**
- * The whole business view, or a note saying why there is none. `options.file`
- * scopes it to one changed file: the processes whose steps name a hunk or a
- * function of that file, and the rules that name one of its hunks.
+ * The whole business view, or a note saying why there is none.
  */
 export declare function renderBusinessView(report: ReviewReport, options?: BusinessViewOptions): string;
 interface StepBox {

package/dist/review/process-html.js

@@ -49,9 +49,7 @@ const LANE_GAP = 18;
 const CHART_PAD = 14;
 const DECISION_INSET = 16;
 /**
- * The whole business view, or a note saying why there is none. `options.file`
- * scopes it to one changed file: the processes whose steps name a hunk or a
- * function of that file, and the rules that name one of its hunks.
+ * The whole business view, or a note saying why there is none.
  */
 export function renderBusinessView(report, options = {}) {
     const explanation = report.agentExplanation;
@@ -62,11 +60,7 @@ export function renderBusinessView(report, options = {}) {
     const purposes = purposesOf(report);
     const ranks = new Map(report.items.map((item, index) => [item.id, index + 1]));
     const itemFiles = new Map(report.items.map((item) => [item.id, item.file]));
-    const touches = (hunks, fns) => options.file === undefined ||
-        (hunks ?? []).some((id) => itemFiles.get(id) === options.file) ||
-        (fns ?? []).some((id) => functions.get(id)?.file === options.file);
-    const processes = explanation.processes.filter((process) => process.steps.some((step) => touches(step.hunks, step.functions)));
-    const rules = explanation.rules.filter((rule) => touches(rule.hunks, undefined));
+    const { processes, rules } = explanation;
     const context = { functions, purposes, ranks, itemFiles, hunkHref: options.hunkHref, stepsOpen: options.stepsOpen !== false };
     const parts = [
         '<div class="bp">',
@@ -77,13 +71,10 @@ export function renderBusinessView(report, options = {}) {
         renderLegend(),
         "</div>",
     ].filter((part) => part !== "");
-    if (processes.length === 0 && rules.length === 0) {
-        parts.push(`<p class="bp-note">No process or rule in the explanation names this file's hunks or functions.</p>`);
-    }
     processes.forEach((process, index) => parts.push(renderProcess(process, index + 1, context)));
     if (rules.length > 0)
         parts.push(renderRules(rules, context));
-    if (options.glossary !== false && options.file === undefined)
+    if (options.glossary !== false)
         parts.push(renderGlossary(report.functions ?? [], purposes));
     parts.push("</div>");
     return parts.join("\n");

package/dist/review/report-pages.js

@@ -117,7 +117,7 @@ function checkComments(report, comments) {
 }
 function applyComments(report, comments, suggestedBy) {
     report.agentComments = {
-        comments: comments.map(({ path, line, side, body }) => ({ path, line, side, body: body.trim() })),
+        comments: comments.map(({ path, line, side, body, severity }) => ({ path, line, side, body: body.trim(), severity })),
         suggestedBy,
         suggestedAt: new Date().toISOString(),
     };

package/dist/review/setup.d.ts

@@ -3,13 +3,15 @@
  * agent CLI (Claude Code, Codex, OMP, pi) with one command.
  *
  * The setup installs the package globally first so the registration points
- * at a permanent binary instead of the npx cache. When the global install is
- * unavailable it falls back to an npx-based entry and says so. The server
+ * at a permanent binary instead of the npx cache, and brings a global install
+ * older than itself up to its own version, so running the newest setup is how
+ * a user updates. When the global install is unavailable it falls back to an
+ * npx-based entry pinned to its own version and says so. The server
  * needs no key or environment: reviews are local, and connected reviews reuse
  * the `gh` session.
  */
 import { type Stats } from "node:fs";
-export declare const setupHelp = "diffninja setup. Register the diffninja MCP server on every detected agent CLI.\n\n  npx -y diffninja setup [--cli claude,codex,omp,pi] [--dry-run]\n  diffninja setup --uninstall [--cli codex]\n\nDetects Claude Code, Codex, OMP, and pi from their config files or binaries\nand registers the diffninja MCP server in each user config, pointing at the\nglobally installed package. Installs the package globally first\n(`npm install -g diffninja`) so the registration keeps working; when that\ninstall fails it registers an npx-based entry instead and says so.\n\nOptions:\n  --cli NAMES    Only these CLIs, comma-separated: claude,codex,omp,pi.\n  --uninstall    Remove the diffninja server from every detected CLI.\n  --dry-run      Show what would change, without installing or writing.\n  --no-install   Skip the global install and register npx-based entries.\n  --help         Show this help.\n\nThe server needs no API key: static reviews run locally, and pull request\nreviews reuse your authenticated gh session.\n";
+export declare const setupHelp = "diffninja setup. Register the diffninja MCP server on every detected agent CLI.\n\n  npx -y diffninja@latest setup [--cli claude,codex,omp,pi] [--dry-run]\n  diffninja setup --uninstall [--cli codex]\n\nDetects Claude Code, Codex, OMP, and pi from their config files or binaries\nand registers the diffninja MCP server in each user config, pointing at the\nglobally installed package. Installs the package globally first\n(`npm install -g diffninja@<this version>`) so the registration keeps\nworking, and updates a global install older than this setup, so running\n`npx -y diffninja@latest setup` again is how you update. When that install\nfails it registers an npx-based entry pinned to this version and says so.\n\nOptions:\n  --cli NAMES    Only these CLIs, comma-separated: claude,codex,omp,pi.\n  --uninstall    Remove the diffninja server from every detected CLI.\n  --dry-run      Show what would change, without installing or writing.\n  --no-install   Skip installing or updating the global package; without one,\n                 register npx-based entries.\n  --help         Show this help.\n\nThe server needs no API key: static reviews run locally, and pull request\nreviews reuse your authenticated gh session.\n";
 export declare const CLI_NAMES: readonly ["claude", "codex", "omp", "pi"];
 export type CliName = (typeof CLI_NAMES)[number];
 export interface McpEntry {
@@ -29,7 +31,8 @@ export interface SetupOptions {
 }
 export interface Npm {
     rootG(): Promise<string>;
-    installG(): Promise<boolean>;
+    /** `npm install -g <spec>`, e.g. `diffninja@0.3.1`; true on success. */
+    installG(spec: string): Promise<boolean>;
 }
 export interface CliReport {
     cli: CliName;
@@ -44,9 +47,16 @@ export interface SetupReport {
 }
 export interface SetupDeps {
     npm?: Npm;
+    /** Version this setup installs and pins; defaults to the running package's. */
+    version?: string;
 }
-/** Entry that runs the published package on demand, without an install. */
-export declare function npxEntry(platform?: NodeJS.Platform): McpEntry;
+/**
+ * Entry that runs the published package on demand, without an install. It
+ * names this setup's version: an unversioned package lets npx keep running
+ * whichever copy it cached first, while a pinned one changes with each newer
+ * setup, which rewrites the entry.
+ */
+export declare function npxEntry(platform?: NodeJS.Platform, version?: string): McpEntry;
 /**
  * Entry for a command that Windows ships only as a `.cmd` shim, which a client
  * that spawns without a shell cannot launch. Running npm's JS entry point with
@@ -60,6 +70,14 @@ export declare function windowsCliEntry(name: string, args: readonly string[], c
 /** Entry that runs the globally installed package. `globalRoot` is `npm root -g`. */
 export declare function globalEntry(globalRoot: string): McpEntry;
 export declare function globalEntryExists(globalRoot: string): boolean;
+/** Version of the globally installed package, or undefined when its manifest is missing or unreadable. */
+export declare function globalVersion(globalRoot: string): string | undefined;
+/**
+ * Whether a global install at `installed` should be brought up to `version`.
+ * A manifest that cannot be read or compared counts as older, so a broken
+ * install is repaired; a newer one is never downgraded.
+ */
+export declare function globalIsOlder(installed: string | undefined, version: string): boolean;
 /**
  * npm runner. Shell-free by design: on Windows npm is a `.cmd` shim, so runs
  * go through `npmSpawnSpec`, which resolves npm's JS entry point instead.

package/dist/review/setup.js

@@ -3,37 +3,43 @@
  * agent CLI (Claude Code, Codex, OMP, pi) with one command.
  *
  * The setup installs the package globally first so the registration points
- * at a permanent binary instead of the npx cache. When the global install is
- * unavailable it falls back to an npx-based entry and says so. The server
+ * at a permanent binary instead of the npx cache, and brings a global install
+ * older than itself up to its own version, so running the newest setup is how
+ * a user updates. When the global install is unavailable it falls back to an
+ * npx-based entry pinned to its own version and says so. The server
  * needs no key or environment: reviews are local, and connected reviews reuse
  * the `gh` session.
  */
 import { spawn } from "node:child_process";
 import { randomBytes } from "node:crypto";
 import { once } from "node:events";
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { lstat, mkdir, open, readFile, readlink, realpath, rename, rm, stat } from "node:fs/promises";
 import { homedir } from "node:os";
 import { basename, delimiter, dirname, join, resolve } from "node:path";
 import { z } from "zod";
 import { npmCliPath, npmSpawnSpec } from "../languages/grammars.js";
 import { removeTomlTable, upsertTomlTable } from "./toml.js";
+import { compareVersions, packageVersion } from "./version.js";
 export const setupHelp = `diffninja setup. Register the diffninja MCP server on every detected agent CLI.
 
-  npx -y diffninja setup [--cli claude,codex,omp,pi] [--dry-run]
+  npx -y diffninja@latest setup [--cli claude,codex,omp,pi] [--dry-run]
   diffninja setup --uninstall [--cli codex]
 
 Detects Claude Code, Codex, OMP, and pi from their config files or binaries
 and registers the diffninja MCP server in each user config, pointing at the
 globally installed package. Installs the package globally first
-(\`npm install -g diffninja\`) so the registration keeps working; when that
-install fails it registers an npx-based entry instead and says so.
+(\`npm install -g diffninja@<this version>\`) so the registration keeps
+working, and updates a global install older than this setup, so running
+\`npx -y diffninja@latest setup\` again is how you update. When that install
+fails it registers an npx-based entry pinned to this version and says so.
 
 Options:
   --cli NAMES    Only these CLIs, comma-separated: claude,codex,omp,pi.
   --uninstall    Remove the diffninja server from every detected CLI.
   --dry-run      Show what would change, without installing or writing.
-  --no-install   Skip the global install and register npx-based entries.
+  --no-install   Skip installing or updating the global package; without one,
+                 register npx-based entries.
   --help         Show this help.
 
 The server needs no API key: static reviews run locally, and pull request
@@ -42,9 +48,14 @@ reviews reuse your authenticated gh session.
 export const CLI_NAMES = ["claude", "codex", "omp", "pi"];
 const jsonValueSchema = z.lazy(() => z.union([z.string(), z.number(), z.boolean(), z.null(), z.array(jsonValueSchema), z.record(z.string(), jsonValueSchema)]));
 const jsonObjectSchema = z.object({}).catchall(jsonValueSchema);
-/** Entry that runs the published package on demand, without an install. */
-export function npxEntry(platform = process.platform) {
-    const args = ["-y", "-p", "diffninja", "diffninja-mcp"];
+/**
+ * Entry that runs the published package on demand, without an install. It
+ * names this setup's version: an unversioned package lets npx keep running
+ * whichever copy it cached first, while a pinned one changes with each newer
+ * setup, which rewrites the entry.
+ */
+export function npxEntry(platform = process.platform, version = packageVersion()) {
+    const args = ["-y", "-p", `diffninja@${version}`, "diffninja-mcp"];
     return platform === "win32" ? windowsCliEntry("npx", args) : { command: "npx", args };
 }
 /**
@@ -70,6 +81,27 @@ export function globalEntry(globalRoot) {
 export function globalEntryExists(globalRoot) {
     return existsSync(join(globalRoot, "diffninja", "dist", "review", "mcp-cli.js"));
 }
+const installedManifestSchema = z.object({ version: z.string() });
+/** Version of the globally installed package, or undefined when its manifest is missing or unreadable. */
+export function globalVersion(globalRoot) {
+    try {
+        const manifest = installedManifestSchema.safeParse(JSON.parse(readFileSync(join(globalRoot, "diffninja", "package.json"), "utf8")));
+        return manifest.success ? manifest.data.version : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Whether a global install at `installed` should be brought up to `version`.
+ * A manifest that cannot be read or compared counts as older, so a broken
+ * install is repaired; a newer one is never downgraded.
+ */
+export function globalIsOlder(installed, version) {
+    if (installed === undefined)
+        return true;
+    return (compareVersions(installed, version) ?? -1) < 0;
+}
 /**
  * npm runner. Shell-free by design: on Windows npm is a `.cmd` shim, so runs
  * go through `npmSpawnSpec`, which resolves npm's JS entry point instead.
@@ -90,8 +122,8 @@ export function createNpm(overrides = {}) {
             });
             return (await exitCode(child)) === 0 ? out.trim() : "";
         },
-        async installG() {
-            return (await exitCode(run(["install", "-g", `--allow-scripts=${INSTALL_SCRIPT_PACKAGES.join(",")}`, "diffninja"], true))) === 0;
+        async installG(spec) {
+            return (await exitCode(run(["install", "-g", `--allow-scripts=${INSTALL_SCRIPT_PACKAGES.join(",")}`, spec], true))) === 0;
         },
     };
 }
@@ -123,35 +155,70 @@ async function globalRoot(npm) {
         return undefined;
     }
 }
+/** Run one global install; a throw counts as a failed install. */
+async function installGlobal(npm, spec) {
+    try {
+        return await npm.installG(spec);
+    }
+    catch {
+        return false;
+    }
+}
 /**
- * Resolve the registration entry. `--dry-run` never installs: it reports the
- * install it would have run and the entry that install would have produced.
+ * Resolve the registration entry. A global install older than `version` is
+ * updated to it first; one that cannot be updated keeps its entry, with a
+ * warning naming the command that updates it. `--dry-run` never installs: it
+ * reports the install it would have run and the entry that install would have
+ * produced.
  */
-async function resolveEntry(noInstall, npm, quiet, dryRun) {
+async function resolveEntry(noInstall, npm, quiet, dryRun, version) {
+    const spec = `diffninja@${version}`;
     const root = await globalRoot(npm);
-    if (root !== undefined && globalEntryExists(root))
+    if (root !== undefined && globalEntryExists(root)) {
+        const installed = globalVersion(root);
+        if (!globalIsOlder(installed, version))
+            return { entry: globalEntry(root), viaNpx: false };
+        const from = installed ?? "an unknown version";
+        const update = `npm install -g ${spec}`;
+        if (noInstall) {
+            if (!quiet)
+                console.error(`diffninja: the global install is ${from}, older than this setup (${version}); update it with ${update}.`);
+        }
+        else if (dryRun) {
+            if (!quiet)
+                console.log(`diffninja: dry run: would update the global install from ${from} to ${version} (${update}).`);
+        }
+        else {
+            if (!quiet)
+                console.log(`diffninja: updating the global install from ${from} to ${version} (${update})...`);
+            const updated = await installGlobal(npm, spec);
+            const updatedRoot = updated ? await globalRoot(npm) : undefined;
+            if (updatedRoot !== undefined && globalEntryExists(updatedRoot))
+                return { entry: globalEntry(updatedRoot), viaNpx: false };
+            if (!globalEntryExists(root)) {
+                if (!quiet)
+                    console.error("diffninja: global update failed and left no install; registering npx-based entries instead.");
+                return { entry: npxEntry(process.platform, version), viaNpx: true };
+            }
+            if (!quiet)
+                console.error(`diffninja: update failed; the global install is still ${globalVersion(root) ?? from}. Update it with ${update}.`);
+        }
         return { entry: globalEntry(root), viaNpx: false };
+    }
     if (dryRun) {
         if (!noInstall && root !== undefined) {
             if (!quiet)
-                console.log("diffninja: dry run: would install the package globally (npm install -g diffninja).");
+                console.log(`diffninja: dry run: would install the package globally (npm install -g ${spec}).`);
             return { entry: globalEntry(root), viaNpx: false };
         }
         if (!quiet)
             console.error("diffninja: dry run: global install unavailable; would register npx-based entries instead.");
-        return { entry: npxEntry(), viaNpx: true };
+        return { entry: npxEntry(process.platform, version), viaNpx: true };
     }
     if (!noInstall) {
         if (!quiet)
-            console.log("diffninja: installing the package globally (npm install -g diffninja)...");
-        let installed = false;
-        try {
-            installed = await npm.installG();
-        }
-        catch {
-            installed = false;
-        }
-        if (installed) {
+            console.log(`diffninja: installing the package globally (npm install -g ${spec})...`);
+        if (await installGlobal(npm, spec)) {
             const installedRoot = await globalRoot(npm);
             if (installedRoot !== undefined && globalEntryExists(installedRoot)) {
                 return { entry: globalEntry(installedRoot), viaNpx: false };
@@ -160,7 +227,7 @@ async function resolveEntry(noInstall, npm, quiet, dryRun) {
     }
     if (!quiet)
         console.error("diffninja: global install unavailable; registering npx-based entries instead.");
-    return { entry: npxEntry(), viaNpx: true };
+    return { entry: npxEntry(process.platform, version), viaNpx: true };
 }
 function findOnPath(name, pathDirs) {
     const candidates = process.platform === "win32" ? [name, `${name}.cmd`, `${name}.exe`] : [name];
@@ -486,10 +553,11 @@ export async function runSetup(options = {}, deps = {}) {
     const quiet = options.quiet === true;
     const uninstall = options.uninstall === true;
     const dryRun = options.dryRun === true;
+    const version = deps.version ?? packageVersion();
     let entry;
     let viaNpx = false;
     if (!uninstall) {
-        const resolved = await resolveEntry(options.noInstall === true, deps.npm ?? realNpm, quiet, dryRun);
+        const resolved = await resolveEntry(options.noInstall === true, deps.npm ?? realNpm, quiet, dryRun, version);
         entry = resolved.entry;
         viaNpx = resolved.viaNpx;
     }
@@ -545,5 +613,5 @@ export async function runSetup(options = {}, deps = {}) {
             console.log("note: pi needs the pi-mcp-extension for MCP support (pi install npm:pi-mcp-extension)");
         }
     }
-    return { entry: entry ?? npxEntry(), viaNpx, clis: reports };
+    return { entry: entry ?? npxEntry(process.platform, version), viaNpx, clis: reports };
 }

package/dist/review/types.d.ts

@@ -132,12 +132,16 @@ export interface AgentOrder {
     /** diffninja's own order of the same items, kept so the page can still offer it. */
     diffninjaIds: string[];
 }
+/** How much a suggested comment matters, most to least: what a reviewer triages by. */
+export declare const COMMENT_SEVERITIES: readonly ["critical", "major", "minor"];
+export type CommentSeverity = (typeof COMMENT_SEVERITIES)[number];
 /** One line comment the reviewing agent suggests; the human adds it to their review or not. */
 export interface SuggestedComment {
     path: string;
     line: number;
     side: "LEFT" | "RIGHT";
     body: string;
+    severity: CommentSeverity;
 }
 export interface AgentComments {
     comments: SuggestedComment[];

package/dist/review/types.js

@@ -1 +1,2 @@
-export {};
+/** How much a suggested comment matters, most to least: what a reviewer triages by. */
+export const COMMENT_SEVERITIES = ["critical", "major", "minor"];

package/dist/review/version.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The version of the running diffninja package, read from its own
+ * `package.json`. Both layouts put it two levels up: `src/review/` in a
+ * checkout and `dist/review/` in the published package, which always ships
+ * `package.json`.
+ */
+export declare function packageVersion(): string;
+/**
+ * Compare two `major.minor.patch` versions: negative when `left` is older,
+ * zero when equal, positive when newer. A prerelease sorts before its release;
+ * two prereleases of one release compare by their tags as text. Undefined when
+ * either is not a version.
+ */
+export declare function compareVersions(left: string, right: string): number | undefined;

package/dist/review/version.js

@@ -0,0 +1,44 @@
+/**
+ * The version of the running diffninja package, read from its own
+ * `package.json`. Both layouts put it two levels up: `src/review/` in a
+ * checkout and `dist/review/` in the published package, which always ships
+ * `package.json`.
+ */
+import { readFileSync } from "node:fs";
+import { z } from "zod";
+const manifestSchema = z.object({ version: z.string() });
+let cached;
+export function packageVersion() {
+    cached ??= manifestSchema.parse(JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8"))).version;
+    return cached;
+}
+/**
+ * Compare two `major.minor.patch` versions: negative when `left` is older,
+ * zero when equal, positive when newer. A prerelease sorts before its release;
+ * two prereleases of one release compare by their tags as text. Undefined when
+ * either is not a version.
+ */
+export function compareVersions(left, right) {
+    const a = parseVersion(left);
+    const b = parseVersion(right);
+    if (a === undefined || b === undefined)
+        return undefined;
+    for (let index = 0; index < 3; index += 1) {
+        const difference = a.core[index] - b.core[index];
+        if (difference !== 0)
+            return difference;
+    }
+    if (a.prerelease === b.prerelease)
+        return 0;
+    if (a.prerelease === undefined)
+        return 1;
+    if (b.prerelease === undefined)
+        return -1;
+    return a.prerelease < b.prerelease ? -1 : 1;
+}
+function parseVersion(text) {
+    const match = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/.exec(text.trim());
+    if (match === null)
+        return undefined;
+    return { core: [Number(match[1]), Number(match[2]), Number(match[3])], prerelease: match[4] };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "diffninja",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "Local, deterministic PR review for coding agents over MCP: call flows, change facts, and a human review workspace",
   "type": "module",
   "exports": {