ai-agentmanager 1.6.0 → 1.7.0

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 1.7.0 (2026-10-31)
+
+- **Split view:** **◫ Split** in the terminal bar: the terminal (or a shell, or a browser tab) on the left, and Code, Docs (Diagrams by default, or any other document) or Changes on the right. Resizable and remembered.
+- **Review: changes explained one by one:** **Explain changes** in Review changes puts an explanation above each hunk (what, why, risk, what to check) and **◀ / ▶** or **[ / ]** step through them in reading order, skipping hunks that moved since. A notice and **Explain again** when the code changed after.
+
 ## 1.6.0 (2026-10-31)
 
 - **Changes explained one by one:** `agentmgr doc <agent> walkthrough` explains each hunk of an agent's changes (what, why, risk, what to check) in the order a reviewer should read them, from the same diff the review screen shows. The review screen and a split view for it come next.

package/README.md

@@ -84,13 +84,13 @@ Runs on macOS and Linux; on Windows, use WSL2. Requires Node 20+, `git`, and the
 
 ```sh
 npm install -g ai-agentmanager          # the latest release
-npm install -g ai-agentmanager@1.6.0    # or a specific one
+npm install -g ai-agentmanager@1.7.0    # or a specific one
 ```
 
 Or from the repository, at a release tag:
 
 ```sh
-git clone --branch v1.6.0 --depth 1 https://github.com/jdmunta/ai-agentmanager-core.git
+git clone --branch v1.7.0 --depth 1 https://github.com/jdmunta/ai-agentmanager-core.git
 cd ai-agentmanager-core
 npm install
 npm link            # optional: puts `agentmgr` on your PATH
@@ -110,7 +110,7 @@ npm link
 | Installed with | Update |
 | --- | --- |
 | npm | `npm install -g ai-agentmanager@latest` |
-| A clone at a release tag | `git fetch --tags && git checkout v1.6.0 && npm install` (the tag you want) |
+| A clone at a release tag | `git fetch --tags && git checkout v1.7.0 && npm install` (the tag you want) |
 | A clone of `main` | `git pull && npm install` |
 
 **Check your setup.** `agentmgr doctor` checks Node.js, Claude Code and its sign-in, git, `gh`, the data folder, the daemon's port and Chrome, and says how to fix anything missing.
@@ -384,6 +384,7 @@ Each card has at most **three points of about 12 words each**, so they're easy t
 
 - **Files and diff.** The changed files on the left with lines added and removed, and the diff file by file on the right. Click a file header to fold it; very large files start folded.
 - **Line comments.** Click **+** next to a line (or its line number) to comment on it, and add an overall comment if you like. **Send to agent** types them into the agent as one message, each with its file, line and the code it is about, and asks it to address them. Comments not sent yet are kept in this browser.
+- **Explain changes** explains each change one by one: a title, what it changes, why (from the request and the conversation), the risk and what to check, in the order a reviewer should read them. Each explanation sits above its hunk, and **◀ / ▶** (or **[** and **]**) step through them, opening folded files on the way. When the agent changes the code afterwards, the page says so and **Explain again** brings it up to date. From the CLI: `agentmgr doc <agent> walkthrough`.
 - **Commit all** commits everything in the worktree, new files included, with your git name and email.
 - **Push & open PR** pushes the branch and opens a pull request with `gh`, against the branch the agent started from (title from your text, or from the commits; **Draft** if you like). With a pull request already open, it pushes to it. The pull request is linked to the agent.
 
@@ -909,6 +910,7 @@ Usage comes from the session transcripts and is refreshed every few seconds whil
 ## Studio: code and terminals
 
 - **Code** (a tab next to **Claude** in the terminal pane) opens the agent's folder: a file tree, tabs, and Monaco, the editor inside VS Code, with syntax highlighting and search within a file. **Save** (Ctrl/Cmd+S) writes into the agent's folder. If the agent changed the file since you opened it, you're asked before anything is overwritten. Files you haven't edited pick up the agent's changes as it makes them. **Search** finds text across the folder (git grep, so ignored files are skipped). **Diff** compares the file with where the agent started, side by side, and you can edit on the right. **＋ / ▣ / ✎ / 🗑** create, rename and delete. Every path stays inside the agent's folder: `..`, and links that point outside, are refused.
+- **◫ Split** (in the terminal bar) keeps the terminal, a shell or a browser tab on the left and opens a pane on the right with **Code**, **Docs** (Diagrams by default; Design, Flow, Analysis, Proposal or Explain from the menu, written there if missing) or **Changes** (the change-by-change explanations, each with its diff). Drag the divider to resize; the pane, its tab and its width are remembered in this browser. Desktop only.
 - **VS Code / Cursor** opens the agent's folder (and the open file) in the editor installed on this computer. The buttons show when its `code` or `cursor` command is found.
 - Monaco loads from the jsDelivr CDN the first time you open **Code**. Offline, a plain text editor takes its place.
 - **Terminal** in the top bar opens a shell on this computer in your home folder, not tied to any agent. It works from any device you're signed in on, so you can run any command from your phone. **+ Terminal** opens more. They keep running when hidden; **×** ends one. Plugins can refuse it with the `terminal.open` policy (`kind: "machine"`).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-agentmanager",
-  "version": "1.6.0",
+  "version": "1.7.0",
   "description": "Run background coding agents (Claude Code, Codex) per intent, and keep track of them from a web UI, your phone or the CLI",
   "keywords": [
     "claude",

package/public/app.js

@@ -5,6 +5,7 @@ import DOMPurify from '/vendor/dompurify/purify.es.mjs';
 import { touchScroll } from '/touchscroll.js';
 import { openStream, post, REMOTE } from '/transport.js';
 import { attachBox } from '/attach.js';
+import { initSide } from '/side.js';
 import { initReview } from '/review.js';
 import { initLand, prChips } from '/land.js';
 import { initTriggers } from '/triggers.js';
@@ -111,7 +112,8 @@ initSetup({ api, esc, $ });
 const updateUi = initUpdate({ api, esc, toast, $ });
 initMenu({ api, esc, toast, $ });
 initMachine({ api, esc, toast, $, Terminal, FitAddon });
-const codeUi = initCode({ api, esc, toast, $, agents, isOpen: () => term.kind === 'code' });
+let sidePane = null; // the split view's right pane (set up once the terminal is)
+const codeUi = initCode({ api, esc, toast, $, agents, isOpen: () => term.kind === 'code' || Boolean(sidePane?.showing('code')) });
 const playbooksUi = initPlaybooks({ api, esc, toast, $, select: (id) => (showTab('agents'), select(id)) });
 $('#new-playbook').onclick = () => {
   const f = $('#new-form');
@@ -1899,6 +1901,7 @@ const term = {
     const a = this.agentId && agents.get(this.agentId);
     // The agent's own session tab is named after its engine (Codex, Muse Code, …).
     $('.term-tab[data-kind="claude"]').textContent = ENGINE_LABEL[a?.engine] ?? 'Claude';
+    sidePane?.follow(this.agentId);
     const nums = new Set(a?.runtime.shells ?? []);
     if (isShell(this.kind)) nums.add(shellNum(this.kind));
     $('#shell-tabs').innerHTML = [...nums]
@@ -1930,6 +1933,7 @@ const term = {
     $('#term-wrap').hidden = false;
     $('#detail').classList.add('with-term');
     $('#term-wrap').classList.remove('browsing');
+    sidePane?.mainShowsCode();
     $('#term-wrap').classList.add('coding');
     this.ensure();
     this.disconnect();
@@ -2095,6 +2099,20 @@ $('#term-fit').onclick = () => term.refit();
 
 // ------------------------------------------------------------------ resizing, expanding, full screen
 
+sidePane = initSide({
+  api,
+  esc,
+  toast,
+  $,
+  agents,
+  codeUi,
+  docHtml,
+  renderDiagrams,
+  mainKind: () => term.kind,
+  setMain: (kind) => term.agentId && term.open(term.agentId, kind),
+  refit: () => requestAnimationFrame(() => term.refit()),
+});
+
 const layoutPref = {
   get(key) {
     try {
@@ -2114,6 +2132,8 @@ function applyLayout() {
   const side = layoutPref.get('sideWidth');
   const brief = layoutPref.get('briefHeight');
   document.documentElement.style.setProperty('--side-w', side ? `${side}px` : '340px');
+  const pane = layoutPref.get('paneWidth');
+  document.documentElement.style.setProperty('--pane-w', pane ? `${pane}%` : '45%');
   if (brief) document.documentElement.style.setProperty('--brief-h', `${brief}px`);
   else document.documentElement.style.removeProperty('--brief-h');
   $('#detail').classList.toggle('brief-sized', Boolean(brief));
@@ -2156,6 +2176,14 @@ dragHandle($('#split-side'), 'cols', (ev) => {
   return w;
 }, 'sideWidth');
 
+// The split view's divider: the right pane's share of the panel, in percent.
+dragHandle($('#split-pane'), 'cols', (ev) => {
+  const r = $('#term-split').getBoundingClientRect();
+  const pct = Math.min(Math.max(((r.right - ev.clientX) / r.width) * 100, 20), 75);
+  layoutPref.set('paneWidth', Math.round(pct));
+  return pct;
+}, 'paneWidth');
+
 dragHandle($('#split-term'), 'rows', (ev) => {
   const top = $('#detail').getBoundingClientRect().top;
   const h = Math.min(Math.max(ev.clientY - top, 60), $('#detail').clientHeight - 160);
@@ -2863,7 +2891,14 @@ $('#term-file').onchange = (e) => {
 function upsert(a) {
   agents.set(a.id, a);
   render();
+  agentChanged(a);
+}
+
+/** Views that show one agent's details outside the main render: keep them current. */
+function agentChanged(a) {
   if (a.id === term.agentId) term.renderTabs();
+  reviewUi.agentChanged(a);
+  sidePane?.agentChanged(a);
 }
 
 $('#counts').addEventListener('click', (e) => {
@@ -3498,7 +3533,7 @@ function handleEvent(msg) {
   } else if (msg.t === 'agent') {
     agents.set(msg.agent.id, msg.agent);
     watchDocs(msg.agent);
-    if (msg.agent.id === term.agentId) term.renderTabs();
+    agentChanged(msg.agent);
   } else if (msg.t === 'removed') {
     agents.delete(msg.id);
     if (selectedId === msg.id) select(null);

package/public/index.html

@@ -96,41 +96,59 @@
             <button id="term-attach" class="ghost small" title="Attach files or images (you can also drop or paste them into the terminal)">📎 Attach</button>
             <input type="file" id="term-file" multiple hidden>
             <button id="term-fit" class="ghost small" title="Refit the terminal to the panel">Fit</button>
+            <button id="term-split-btn" class="ghost small desk-only" title="Split: the terminal on the left, and Code, Docs (diagrams) or Changes on the right">◫ Split</button>
             <button id="term-max" class="ghost small desk-only" title="Expand to fill the window (Ctrl+Shift+E)">⤢ Expand</button>
             <button id="term-full" class="ghost small desk-only" title="Full screen (Esc to leave)">⛶ Full screen</button>
             <button id="term-close" class="ghost small" title="Hide the terminal (the agent keeps running)">Hide terminal</button>
           </div>
           <div id="signin-bar" class="signin-bar" hidden></div>
-          <div id="terminal" class="terminal"></div>
-          <div id="code" class="code"></div>
-          <div id="browser" class="browser">
-            <form id="browser-bar" class="browser-bar" autocomplete="off">
-              <button type="button" id="browser-back" class="ghost small live-only" title="Back">◀</button>
-              <button type="button" id="browser-fwd" class="ghost small live-only" title="Forward">▶</button>
-              <button type="button" id="browser-reload" class="ghost small" title="Reload the page">⟳</button>
-              <input id="browser-url" placeholder="localhost:5173, a port, or any address" spellcheck="false" autocapitalize="off" autocorrect="off" enterkeyhint="go">
-              <button class="small">Go</button>
-              <button type="button" id="browser-sound" class="ghost small live-only" title="Hear the page: sound from videos and audio playing on that machine">🔇</button>
-              <button type="button" id="browser-keys" class="ghost small live-only touch-only" title="Show the keyboard to type into the page">⌨</button>
-              <button type="button" id="browser-mode" class="ghost small" hidden></button>
-              <a id="browser-pop" class="ghost small button" target="_blank" rel="noopener" title="Open in a new browser tab on this device" hidden>↗</a>
-            </form>
-            <div id="browser-hint" class="browser-hint" hidden>Blank? Many sites refuse to show inside another page. Open it with ↗ instead.</div>
-            <div id="browser-cert" class="browser-start" hidden>
-              <p><b>One more step on this device.</b> Each browser tab goes through its own port, and this device hasn't accepted AI Agent Manager's certificate for this one yet.</p>
-              <p>Open it, accept the warning the same way you did for AI Agent Manager (Safari: Show Details → visit this website), then come back here. You only do this once per site; it keeps its port.</p>
-              <div><a id="browser-cert-open" class="button primary small" target="_blank" rel="noopener">Open and accept</a> <button type="button" id="browser-cert-retry" class="small">Done, load it</button></div>
+          <div class="term-split" id="term-split">
+            <div class="term-main" id="term-main">
+            <div id="terminal" class="terminal"></div>
+            <div id="code" class="code"></div>
+            <div id="browser" class="browser">
+              <form id="browser-bar" class="browser-bar" autocomplete="off">
+                <button type="button" id="browser-back" class="ghost small live-only" title="Back">◀</button>
+                <button type="button" id="browser-fwd" class="ghost small live-only" title="Forward">▶</button>
+                <button type="button" id="browser-reload" class="ghost small" title="Reload the page">⟳</button>
+                <input id="browser-url" placeholder="localhost:5173, a port, or any address" spellcheck="false" autocapitalize="off" autocorrect="off" enterkeyhint="go">
+                <button class="small">Go</button>
+                <button type="button" id="browser-sound" class="ghost small live-only" title="Hear the page: sound from videos and audio playing on that machine">🔇</button>
+                <button type="button" id="browser-keys" class="ghost small live-only touch-only" title="Show the keyboard to type into the page">⌨</button>
+                <button type="button" id="browser-mode" class="ghost small" hidden></button>
+                <a id="browser-pop" class="ghost small button" target="_blank" rel="noopener" title="Open in a new browser tab on this device" hidden>↗</a>
+              </form>
+              <div id="browser-hint" class="browser-hint" hidden>Blank? Many sites refuse to show inside another page. Open it with ↗ instead.</div>
+              <div id="browser-cert" class="browser-start" hidden>
+                <p><b>One more step on this device.</b> Each browser tab goes through its own port, and this device hasn't accepted AI Agent Manager's certificate for this one yet.</p>
+                <p>Open it, accept the warning the same way you did for AI Agent Manager (Safari: Show Details → visit this website), then come back here. You only do this once per site; it keeps its port.</p>
+                <div><a id="browser-cert-open" class="button primary small" target="_blank" rel="noopener">Open and accept</a> <button type="button" id="browser-cert-retry" class="small">Done, load it</button></div>
+              </div>
+              <div id="browser-start" class="browser-start" hidden>
+                <p>Open a page as this machine sees it: the agent's dev server, a site on its network or VPN, or any address. It works from your phone or laptop too: AI Agent Manager relays it over its own secure connection, for signed-in devices only.</p>
+                <div id="browser-suggest"></div>
+              </div>
+              <div id="browser-frames" class="browser-frames"></div>
+              <div id="browser-live" class="browser-live" hidden>
+                <img id="browser-live-img" alt="" draggable="false">
+                <textarea id="browser-live-keys" class="browser-live-keys" autocapitalize="off" autocomplete="off" autocorrect="off" spellcheck="false" aria-label="Type into the page"></textarea>
+                <div id="browser-live-msg" class="browser-live-msg" hidden></div>
+              </div>
             </div>
-            <div id="browser-start" class="browser-start" hidden>
-              <p>Open a page as this machine sees it: the agent's dev server, a site on its network or VPN, or any address. It works from your phone or laptop too: AI Agent Manager relays it over its own secure connection, for signed-in devices only.</p>
-              <div id="browser-suggest"></div>
-            </div>
-            <div id="browser-frames" class="browser-frames"></div>
-            <div id="browser-live" class="browser-live" hidden>
-              <img id="browser-live-img" alt="" draggable="false">
-              <textarea id="browser-live-keys" class="browser-live-keys" autocapitalize="off" autocomplete="off" autocorrect="off" spellcheck="false" aria-label="Type into the page"></textarea>
-              <div id="browser-live-msg" class="browser-live-msg" hidden></div>
             </div>
+            <div class="splitter split-pane" id="split-pane" role="separator" aria-orientation="vertical" title="Drag to resize; double-click to reset" hidden></div>
+            <aside class="side-pane" id="side-pane" hidden>
+              <div class="side-bar">
+                <div class="term-tabs" role="tablist">
+                  <button class="term-tab" data-side="code" role="tab" title="The agent's files">Code</button>
+                  <button class="term-tab" data-side="docs" role="tab" title="Diagrams and the other documents">Docs</button>
+                  <button class="term-tab" data-side="changes" role="tab" title="Its changes, explained one by one">Changes</button>
+                </div>
+                <span class="spacer"></span>
+                <button type="button" class="ghost small" id="side-close" title="Close the split">✕</button>
+              </div>
+              <div class="side-body" id="side-body"></div>
+            </aside>
           </div>
           <div id="term-drop" class="term-drop" hidden>Drop files to attach</div>
           <div class="keybar" id="keybar" aria-label="Terminal keys">

package/public/review.js

@@ -1,5 +1,7 @@
 // Review screen: an agent's changes file by file, line comments sent back to the agent as one
 // message, and Commit / Push & open PR. Comments not sent yet are kept per agent in this browser.
+// With a walkthrough, each hunk shows its explanation and ◀ / ▶ step through them in reading order.
+import { cardHtml, explainButton, stepOf, walkthroughOf } from './walkthrough.js';
 
 /** Unified diff -> [{ path, status, binary, hunks: [{ head, lines: [{ t, old, new, text }] }] }] */
 export function parseDiff(text) {
@@ -56,7 +58,8 @@ const BIG = 600; // files with more changed lines start collapsed
 export function initReview({ api, esc, toast, agents, $ }) {
   const dlg = $('#review-dialog');
   const body = $('#review-body');
-  const st = { id: null, data: null, files: [], comments: [], collapsed: new Set(), editing: null, loading: false };
+  const st = { id: null, data: null, files: [], comments: [], collapsed: new Set(), editing: null, loading: false, step: null };
+  const walk = () => walkthroughOf(agents.get(st.id), st.data?.diffHash);
 
   const key = (id) => `agentmgr.review.${id}`;
   const loadDrafts = (id) => {
@@ -80,6 +83,7 @@ export function initReview({ api, esc, toast, agents, $ }) {
     st.collapsed = new Set();
     st.editing = null;
     st.data = null;
+    st.step = null;
     $('#review-title').textContent = `Review: ${agents.get(id)?.name ?? ''}`;
     body.innerHTML = '<p class="hint">Loading changes…</p>';
     if (!dlg.open) dlg.showModal();
@@ -129,7 +133,10 @@ export function initReview({ api, esc, toast, agents, $ }) {
     if (collapsed) return `<div class="rv-file" id="rv-${encodeURIComponent(f.path)}">${head}</div>`;
     if (f.binary) return `<div class="rv-file" id="rv-${encodeURIComponent(f.path)}">${head}<p class="hint rv-pad">Binary file</p></div>`;
     const rows = [];
+    const w = walk();
     for (const h of f.hunks) {
+      const i = w.doc ? stepOf(w.doc, f.path, h.head) : -1;
+      if (i >= 0) rows.push(`<tr class="rv-explain ${st.step === i ? 'current' : ''}" id="rv-step-${i}"><td colspan="3">${cardHtml(w.doc.data.changes[i], i, w.doc.data.changes.length, esc)}</td></tr>`);
       rows.push(`<tr class="rv-hunk"><td colspan="3">${esc(h.head)}</td></tr>`);
       for (const l of h.lines) {
         const side = l.t === 'del' ? 'old' : 'new';
@@ -149,6 +156,48 @@ export function initReview({ api, esc, toast, agents, $ }) {
     return `<div class="rv-file" id="rv-${encodeURIComponent(f.path)}">${head}<table class="rv-table">${rows.join('')}</table></div>`;
   }
 
+  /** Explain changes, then ◀ n of N ▶ once there is a walkthrough. */
+  function walkNav() {
+    const w = walk();
+    const n = w.doc?.data.changes.length ?? 0;
+    const nav = n
+      ? `<span class="rv-walk"><button type="button" class="small ghost" data-rv-step="-1" title="Previous change ([)">◀</button><span class="hint">${st.step == null ? `${n} changes` : `${st.step + 1} of ${n}`}</span><button type="button" class="small ghost" data-rv-step="1" title="Next change (])">▶</button></span>`
+      : '';
+    return `${nav}${explainButton(w, 'data-rv-explain')}`;
+  }
+
+  function walkNote() {
+    const w = walk();
+    if (w.error && !w.pending) return `<p class="error rv-pad">Couldn't explain the changes: ${esc(w.error)}</p>`;
+    if (!w.doc) return '';
+    const notes = [esc(w.doc.data.summary)];
+    if (w.stale) notes.push('<b>The changes moved since this was written</b>; explanations for hunks that changed are missing. Explain again for the latest.');
+    if (w.doc.cut) notes.push('The diff was too long to explain all of it; the rest has no explanation.');
+    return `<p class="hint rv-walk-note">${notes.join(' ')}</p>`;
+  }
+
+  /** Explanations whose hunk is still in the diff (after more edits, some may be gone). */
+  const present = (w) => (w.doc?.data.changes ?? []).map((c, i) => (st.files.some((f) => f.path === c.file && f.hunks.some((h) => h.head === c.head)) ? i : -1)).filter((i) => i >= 0);
+
+  /** Step `dir` (+1 / -1) from the current explanation: open its file, mark it and scroll to it. */
+  function step(dir) {
+    const w = walk();
+    const ok = present(w);
+    if (!ok.length) return toast('These explanations no longer match the changes; Explain again');
+    const at = st.step == null ? -1 : ok.indexOf(st.step);
+    const next = at < 0 ? (dir > 0 ? ok[0] : ok.at(-1)) : ok[(at + dir + ok.length) % ok.length];
+    gotoStep(next);
+  }
+
+  function gotoStep(i) {
+    const w = walk();
+    st.step = i;
+    st.collapsed.delete(w.doc.data.changes[st.step].file);
+    keepInputs();
+    render();
+    body.querySelector(`#rv-step-${st.step}`)?.scrollIntoView({ block: 'center', behavior: 'smooth' });
+  }
+
   function render() {
     const d = st.data;
     if (!d) return;
@@ -168,8 +217,10 @@ export function initReview({ api, esc, toast, agents, $ }) {
         ${d.unpushed ? `<span class="tag">${d.unpushed} not pushed</span>` : ''}
         ${openPr ? `<a href="${esc(openPr.url)}" target="_blank" rel="noopener">PR #${esc(openPr.number ?? '')}</a>` : ''}
         <span class="spacer"></span>
+        ${d.files.length ? walkNav() : ''}
         <button type="button" class="small ghost" data-rv-reload>${st.loading ? 'Loading…' : 'Reload'}</button>
       </div>
+      ${walkNote()}
       ${d.busy ? '<p class="hint rv-warn">The agent is working, so the changes may still move. Reload when it is idle.</p>' : ''}
       ${d.truncated ? '<p class="hint rv-warn">The diff is large and was cut short; open a shell for the rest.</p>' : ''}
       <div class="rv-main">
@@ -235,6 +286,20 @@ export function initReview({ api, esc, toast, agents, $ }) {
   body.addEventListener('click', async (e) => {
     const t = e.target;
     if (t.closest('[data-rv-reload]')) return keepInputs(), reload();
+    const stepBtn = t.closest('[data-rv-step]');
+    if (stepBtn) return step(Number(stepBtn.dataset.rvStep));
+    if (t.closest('[data-rv-explain]')) {
+      keepInputs();
+      try {
+        // In the background: the agent's record says when it's done (agentChanged re-renders).
+        agents.set(st.id, await api('POST', `/agents/${st.id}/docs/walkthrough?background=1`));
+        st.step = null;
+        render();
+      } catch (err) {
+        toast(`Error: ${err.message}`, 5000);
+      }
+      return;
+    }
     const go = t.closest('[data-rv-goto]');
     if (go) {
       e.preventDefault();
@@ -339,6 +404,13 @@ export function initReview({ api, esc, toast, agents, $ }) {
     }
   });
 
+  // [ and ] step through the explained changes (not while typing).
+  dlg.addEventListener('keydown', (e) => {
+    if ((e.key !== '[' && e.key !== ']') || e.target.closest?.('textarea, input') || !walk().doc) return;
+    e.preventDefault();
+    step(e.key === ']' ? 1 : -1);
+  });
+
   body.addEventListener('keydown', (e) => {
     const form = e.target.closest?.('.rv-form');
     if (form && e.key === 'Enter' && (e.metaKey || e.ctrlKey)) {
@@ -364,5 +436,16 @@ export function initReview({ api, esc, toast, agents, $ }) {
     st.note = st.msg = st.prTitle = '';
   });
 
-  return { open, get openId() { return dlg.open ? st.id : null; } };
+  /** The agent changed (its walkthrough finished, say): redraw if it's the one under review. */
+  function agentChanged(a) {
+    if (!dlg.open || a.id !== st.id || !st.data) return;
+    const w = a.docs?.walkthrough;
+    const sig = `${w?.at}|${w?.pending}|${w?.error}`;
+    if (sig === st.walkSig) return;
+    st.walkSig = sig;
+    keepInputs();
+    render();
+  }
+
+  return { open, agentChanged, get openId() { return dlg.open ? st.id : null; } };
 }

package/public/side.js

@@ -0,0 +1,191 @@
+// The split view: the terminal (Claude, a shell or a browser tab) stays on the left, and the right
+// pane shows the same agent's Code, its Docs (Diagrams by default) or its Changes explained one by
+// one. On, the tab and the document are remembered in this browser.
+import { parseDiff } from '/review.js';
+import { cardHtml, explainButton, walkthroughOf } from '/walkthrough.js';
+
+const DOCS = [
+  ['diagrams', 'Diagrams'],
+  ['design', 'Design'],
+  ['flow', 'Flow'],
+  ['analysis', 'Analysis'],
+  ['proposal', 'Proposal'],
+  ['explain', 'Explain'],
+];
+const pref = {
+  get: (k, d) => {
+    try {
+      return localStorage.getItem(`agentmgr.side.${k}`) ?? d;
+    } catch {
+      return d;
+    }
+  },
+  set: (k, v) => {
+    try {
+      localStorage.setItem(`agentmgr.side.${k}`, v);
+    } catch {}
+  },
+};
+
+export function initSide({ api, esc, toast, $, agents, codeUi, docHtml, renderDiagrams, mainKind, setMain, refit }) {
+  const pane = $('#side-pane');
+  const body = $('#side-body');
+  const code = $('#code');
+  const codeHome = $('#term-main');
+  const st = { on: pref.get('on', '0') === '1', tab: pref.get('tab', 'docs'), doc: pref.get('doc', 'diagrams'), agentId: null, changes: null, sig: '', loading: false };
+
+  const docOf = (a, kind) => (kind === 'explain' ? a?.explanation : a?.docs?.[kind]);
+
+  function show() {
+    const on = st.on && Boolean(st.agentId);
+    pane.hidden = !on;
+    $('#split-pane').hidden = !on;
+    $('#term-split-btn').classList.toggle('on', on);
+    for (const t of pane.querySelectorAll('[data-side]')) t.classList.toggle('active', t.dataset.side === st.tab);
+    // Code lives in one place at a time: here when this tab shows it, else back in the main panel.
+    const want = on && st.tab === 'code' ? body : codeHome;
+    if (code.parentElement !== want) want === body ? body.replaceChildren(code) : codeHome.insertBefore(code, $('#browser'));
+    pane.classList.toggle('with-code', on && st.tab === 'code');
+    if (!on) return refit();
+    if (st.tab === 'code') codeUi.open(st.agentId);
+    else if (st.tab === 'docs') renderDocs(true);
+    else renderChanges(true);
+    refit();
+  }
+
+  // ------------------------------------------------------------ Docs
+  function renderDocs(force) {
+    const a = agents.get(st.agentId);
+    const d = docOf(a, st.doc);
+    const sig = `docs|${st.agentId}|${st.doc}|${d?.at}|${d?.pending}|${d?.error}`;
+    if (!force && sig === st.sig) return;
+    st.sig = sig;
+    const label = DOCS.find(([k]) => k === st.doc)?.[1] ?? st.doc;
+    const picker = `<select data-side-doc>${DOCS.map(([k, l]) => `<option value="${k}" ${k === st.doc ? 'selected' : ''}>${l}${docOf(a, k)?.markdown ? ' ✓' : ''}</option>`).join('')}</select>`;
+    const stale = d?.markdown && a?.brief?.updatedAt && d.briefUpdatedAt !== a.brief.updatedAt;
+    const action = d?.pending
+      ? `<span class="hint">Writing…</span>`
+      : `<button type="button" class="small ${d?.markdown ? 'ghost' : 'primary'}" data-side-write>${d?.markdown ? 'Again' : st.doc === 'diagrams' ? 'Draw' : 'Write'}</button>`;
+    let content;
+    if (d?.pending && !d?.markdown) content = `<p class="hint">Writing the ${esc(label.toLowerCase())} from the agent's work so far…</p>`;
+    else if (d?.error && !d?.markdown) content = `<p class="error">Couldn't write it: ${esc(d.error)}</p>`;
+    else if (d?.markdown) content = `<div class="md ${st.doc === 'diagrams' ? 'diagrams-view' : ''}">${docHtml(d.markdown)}</div>`;
+    else content = `<p class="hint">No ${esc(label.toLowerCase())} for this agent yet.</p>`;
+    body.innerHTML = `<div class="side-tools">${picker}<span class="spacer"></span>${stale ? '<span class="hint">brief changed since</span>' : ''}${action}</div><div class="side-scroll">${content}</div>`;
+    renderDiagrams(body);
+  }
+
+  // ------------------------------------------------------------ Changes
+  async function loadChanges() {
+    st.loading = true;
+    try {
+      const data = await api('GET', `/agents/${st.agentId}/changes`);
+      st.changes = { id: st.agentId, diffHash: data.diffHash, files: parseDiff(data.diff) };
+    } catch (err) {
+      st.changes = { id: st.agentId, error: err.message };
+    }
+    st.loading = false;
+    renderChanges(true);
+  }
+
+  function hunkHtml(file, head) {
+    const h = st.changes?.files?.find((f) => f.path === file)?.hunks.find((x) => x.head === head);
+    if (!h) return '<p class="hint">This hunk has changed since; Explain again for the latest.</p>';
+    const lines = h.lines.slice(0, 40).map((l) => `<div class="sd-${l.t}">${l.t === 'add' ? '+' : l.t === 'del' ? '−' : ' '}${esc(l.text)}</div>`);
+    if (h.lines.length > 40) lines.push(`<div class="hint">… ${h.lines.length - 40} more lines (Review changes shows all)</div>`);
+    return `<div class="sd-hunk"><div class="sd-head">${esc(head)}</div>${lines.join('')}</div>`;
+  }
+
+  function renderChanges(force) {
+    if (!st.changes || st.changes.id !== st.agentId) {
+      body.innerHTML = '<p class="hint side-pad">Loading the changes…</p>';
+      if (!st.loading) loadChanges();
+      return;
+    }
+    const a = agents.get(st.agentId);
+    const w = walkthroughOf(a, st.changes.diffHash);
+    const sig = `changes|${st.agentId}|${a?.docs?.walkthrough?.at}|${w.pending}|${w.error}|${st.changes.diffHash}`;
+    if (!force && sig === st.sig) return;
+    st.sig = sig;
+    const tools = `<div class="side-tools">${explainButton(w, 'data-side-explain')}<span class="spacer"></span><button type="button" class="small ghost" data-side-reload title="Load the changes again">⟳</button></div>`;
+    let content;
+    if (st.changes.error) content = `<p class="error">${esc(st.changes.error)}</p>`;
+    else if (!st.changes.files.length) content = '<p class="hint">No changes yet.</p>';
+    else if (!w.doc) content = `${w.error && !w.pending ? `<p class="error">Couldn't explain them: ${esc(w.error)}</p>` : ''}<p class="hint">${st.changes.files.length} file${st.changes.files.length === 1 ? '' : 's'} changed. <b>Explain changes</b> goes through them one by one: what, why, the risk and what to check.</p>`;
+    else {
+      const list = w.doc.data.changes;
+      content = `<p class="hint">${esc(w.doc.data.summary)}${w.stale ? ' <b>The changes moved since this was written.</b>' : ''}</p>${list
+        .map((c, i) => `<section class="sd-step"><div class="sd-file"><code>${esc(c.file)}</code></div>${cardHtml(c, i, list.length, esc)}${hunkHtml(c.file, c.head)}</section>`)
+        .join('')}`;
+    }
+    body.innerHTML = `${tools}<div class="side-scroll">${content}</div>`;
+  }
+
+  // ------------------------------------------------------------ events
+  pane.addEventListener('click', async (e) => {
+    const tab = e.target.closest('[data-side]');
+    if (tab) return setTab(tab.dataset.side);
+    if (e.target.closest('#side-close')) return toggle(false);
+    if (e.target.closest('[data-side-reload]')) return loadChanges();
+    try {
+      if (e.target.closest('[data-side-explain]')) {
+        agents.set(st.agentId, await api('POST', `/agents/${st.agentId}/docs/walkthrough?background=1`));
+        return renderChanges(true);
+      }
+      if (e.target.closest('[data-side-write]')) {
+        const route = st.doc === 'explain' ? `/agents/${st.agentId}/explain?background=1` : `/agents/${st.agentId}/docs/${st.doc}?background=1`;
+        agents.set(st.agentId, await api('POST', route));
+        return renderDocs(true);
+      }
+    } catch (err) {
+      toast(`Error: ${err.message}`, 5000);
+    }
+  });
+  pane.addEventListener('change', (e) => {
+    if (!e.target.matches('[data-side-doc]')) return;
+    st.doc = e.target.value;
+    pref.set('doc', st.doc);
+    renderDocs(true);
+  });
+
+  function setTab(tab) {
+    st.tab = tab;
+    pref.set('tab', tab);
+    // Code can't be on both sides: the main panel goes back to the agent's session.
+    if (tab === 'code' && mainKind() === 'code') setMain('claude');
+    show();
+  }
+
+  function toggle(on = !st.on) {
+    st.on = on;
+    pref.set('on', on ? '1' : '0');
+    if (on && st.tab === 'code' && mainKind() === 'code') st.tab = 'docs';
+    show();
+  }
+
+  $('#term-split-btn').onclick = () => toggle();
+
+  return {
+    /** The terminal now shows this agent (or none): follow it. */
+    follow(id) {
+      if (id === st.agentId) return;
+      st.agentId = id ?? null;
+      st.changes = null;
+      st.sig = '';
+      show();
+    },
+    /** The main panel is about to show Code: move this pane off it. */
+    mainShowsCode() {
+      if (st.on && st.tab === 'code') {
+        st.tab = 'docs';
+        show();
+      }
+    },
+    showing: (tab) => st.on && Boolean(st.agentId) && st.tab === tab,
+    agentChanged(a) {
+      if (!st.on || a.id !== st.agentId) return;
+      if (st.tab === 'docs') renderDocs(false);
+      else if (st.tab === 'changes') renderChanges(false);
+    },
+  };
+}

package/public/style.css

@@ -837,3 +837,39 @@ input.inline { display: inline-block; width: 80px; padding: 1px 4px; }
 .attach-chip.fail { border-color: var(--red); }
 .attach-chip .link { padding: 0 4px; }
 form.dropping { outline: 2px dashed var(--accent, #6b8cff); outline-offset: 4px; }
+
+/* Walkthrough: an explanation card above each hunk; the current one is marked. */
+.wt-card { display: flex; flex-direction: column; gap: 3px; padding: 8px 10px; font: 13px/1.45 var(--sans, system-ui); white-space: normal; color: var(--text); }
+.wt-head { display: flex; align-items: center; gap: 8px; flex-wrap: wrap; }
+.wt-n { font: 11px var(--mono, ui-monospace); color: var(--muted); }
+.wt-k { display: inline-block; min-width: 44px; font-size: 11px; text-transform: uppercase; letter-spacing: .04em; color: var(--muted); }
+.rv-explain td { background: var(--panel); border-top: 1px solid var(--border); }
+.rv-explain.current td { box-shadow: inset 3px 0 0 var(--accent, #6b8cff); background: var(--panel-2); }
+.rv-walk { display: inline-flex; align-items: center; gap: 4px; }
+.rv-walk-note { margin: 4px 12px 8px; }
+
+/* Split view: the terminal (or a browser tab, or Code) on the left, a pane on the right. */
+.term-split { flex: 1; display: flex; min-height: 0; min-width: 0; }
+.term-main { flex: 1; display: flex; flex-direction: column; min-width: 0; min-height: 0; }
+.split-pane { flex: none; width: 0; }
+.split-pane::after { top: 0; bottom: 0; left: -4px; width: 8px; cursor: col-resize; }
+.split-pane[hidden], .side-pane[hidden] { display: none !important; }
+.side-pane { flex: none; width: var(--pane-w, 45%); display: flex; flex-direction: column; min-height: 0; border-left: 1px solid #30363d; background: var(--bg); color: var(--text); }
+.side-bar { display: flex; align-items: center; gap: 6px; padding: 4px 8px; background: #161a22; color: #c9d1d9; font-size: 12.5px; }
+.side-bar button { color: #c9d1d9; border-color: #30363d; }
+.side-body { flex: 1; display: flex; flex-direction: column; min-height: 0; }
+.side-pane .code { display: flex; flex: 1; }
+.side-tools { display: flex; align-items: center; gap: 8px; padding: 6px 10px; border-bottom: 1px solid var(--border); }
+.side-tools select { width: auto; }
+.side-scroll { flex: 1; overflow: auto; padding: 10px 12px; }
+.side-pad { padding: 10px 12px; }
+.side-scroll .diagrams-view .diagram, .side-scroll .diagram { display: flex; justify-content: center; overflow-x: auto; }
+.side-scroll .diagram svg { max-width: 100%; height: auto; }
+.sd-step { margin-bottom: 14px; border: 1px solid var(--border); border-radius: 8px; overflow: hidden; }
+.sd-file { padding: 4px 10px; background: var(--panel-2); font-size: 12px; }
+.sd-hunk { font: 12px/1.45 var(--mono, ui-monospace, monospace); white-space: pre; overflow-x: auto; border-top: 1px solid var(--border); }
+.sd-hunk > div { padding: 0 10px; }
+.sd-head { color: var(--muted); background: var(--panel); }
+.sd-add { background: rgba(46, 160, 67, .15); }
+.sd-del { background: rgba(248, 81, 73, .15); }
+#term-split-btn.on { background: #262c38; }

package/public/walkthrough.js

@@ -0,0 +1,36 @@
+// An agent's changes explained one by one (the "walkthrough" document): shared by the review
+// screen, which shows each explanation above its hunk, and the Changes pane of the split view.
+
+const RISK = { high: 'fail', medium: '', low: 'open' };
+
+/** The walkthrough of an agent and whether it still matches the changes (diffHash from /changes). */
+export function walkthroughOf(agent, diffHash) {
+  const w = agent?.docs?.walkthrough;
+  return {
+    doc: w?.data ? w : null,
+    pending: Boolean(w?.pending),
+    error: w?.error ?? null,
+    stale: Boolean(w?.data && diffHash && w.diffHash !== diffHash),
+  };
+}
+
+/** Index of the explanation for a hunk (file + header), or -1. */
+export const stepOf = (doc, file, head) => doc?.data.changes.findIndex((c) => c.file === file && c.head === head) ?? -1;
+
+/** One explanation: title, risk, what / why / check. */
+export function cardHtml(c, i, total, esc) {
+  if (c.unexplained) return `<div class="wt-card"><div class="wt-head"><span class="wt-n">${i + 1}/${total}</span><span class="hint">Not explained (the model skipped it)</span></div></div>`;
+  return `<div class="wt-card">
+    <div class="wt-head"><span class="wt-n">${i + 1}/${total}</span><b>${esc(c.title)}</b><span class="tag ${RISK[c.risk] ?? ''}">${esc(c.risk)} risk</span></div>
+    ${c.what ? `<div><span class="wt-k">What</span> ${esc(c.what)}</div>` : ''}
+    ${c.why ? `<div><span class="wt-k">Why</span> ${esc(c.why)}</div>` : ''}
+    ${c.check ? `<div><span class="wt-k">Check</span> ${esc(c.check)}</div>` : ''}
+  </div>`;
+}
+
+/** The button that writes (or rewrites) the walkthrough, with its state. */
+export function explainButton(w, attrs = 'data-wt-explain') {
+  const label = w.pending ? 'Explaining…' : w.doc ? (w.stale ? 'Explain again (changed)' : 'Explain again') : '✨ Explain changes';
+  return `<button type="button" class="small ${w.doc && !w.stale ? 'ghost' : 'primary'}" ${attrs} ${w.pending ? 'disabled' : ''}
+    title="Explain each change one by one: what, why, the risk and what to check, in the order to read them (a separate one-off call; the agent isn't interrupted)">${label}</button>`;
+}