@volcanic-dev/tephra 0.2.0 → 0.4.0

package/README.md

@@ -1,6 +1,6 @@
 # Tephra
 
-**A clipboard for AI agents.** Tephra is an MCP server that lets a model copy an exact character range from a file — start `(line, char)` to end `(line, char)` — and paste it at an exact position somewhere else. Byte-for-byte, no retyping, no transcription drift, no tokens spent regenerating code that already exists.
+**A clipboard for AI agents.** When a model moves code by regenerating it, it retypes 200 lines from memory — and sometimes what lands isn't quite what left. That transcription drift is a correctness bug, not just a token cost. Tephra is an MCP server for byte-exact copy and paste: name whole lines (or exact `(line, char)` ranges), copy them byte-for-byte, paste them at an exact position anywhere else. **Your agent will never subtly mangle code it's moving.**
 
 The clipboard is a **private in-process buffer, deliberately not the OS clipboard**. An agent can never read what you last copied (passwords, tokens, anything) and can never overwrite what you're about to paste. Nothing touches disk; the buffer dies with the session.
 
@@ -18,11 +18,14 @@ npx -y @volcanic-dev/tephra
 
 | Tool | What it does |
 |------|--------------|
-| `copy` | Copy one or more ranges `{start_line, start_char, end_line, end_char, slot?, expect?}` from a file into clipboard slots. Both ends inclusive, 1-indexed. Newlines inside a range are included. |
-| `cut` | Same as `copy`, but removes the ranges from the source file (ranges must be disjoint). |
-| `paste` | Insert clipboard slots into a file at one or more targets `{line, char, slot?, expect?}` — before the character at `(line, char)`; `char` may be line length + 1 to append to a line. Never overwrites — text shifts to make room. |
+| `copy` | Copy one or more ranges `{start_line, end_line, whole_lines?, start_char?, end_char?, slot?, expect?}` from a file into clipboard slots. Both ends inclusive, 1-indexed. Newlines inside a range are included. |
+| `cut` | Same as `copy`, but removes the ranges from the source file (ranges must be disjoint). Whole-line cuts take the newline too — no empty line left behind. |
+| `paste` | Insert clipboard slots into a file at one or more targets `{line, char?, slot?, expect?}` — before the character at `(line, char)`; `char` defaults to 1 and may be line length + 1 to append to a line. Add `end_line` (or `whole_lines: true`) to **replace** that range with the slot instead — the result shows exactly what was removed. |
+| `move` | Cut + paste in **one atomic call**: `move(file, ranges, to: {file?, line, char?, expect?})`. Source ranges *and* destination are all given in the file's current coordinates — the server does the shift arithmetic, so "move lines 120–184 to line 200" just works even though the cut renumbers line 200. Cross-file moves allowed. |
 | `peek` | List the slots that hold text, or show one slot's size and preview. |
 
+The commonest workflows are one call each: relocate code with `move`, overwrite a stale block with a replace-mode `paste`, duplicate with `copy` + `paste`.
+
 ## Named slots
 
 Every range and target takes an optional `slot` (default `"default"`). Gather many snippets in one pass — each into its own slot — then paste them in any order, any number of times. Multi-range calls must name a distinct slot per range.
@@ -37,9 +40,11 @@ Cutting or pasting lines shifts the numbering of everything below the edit — t
 
 ## Addressing
 
-- Lines and characters are **1-indexed**: the first character of a file is `(1, 1)`.
-- Copy/cut ranges are **inclusive on both ends**: copying `(2, 5)` → `(2, 7)` yields exactly 3 characters.
-- To copy whole lines 10–14: start `(10, 1)`, end `(14, <length of line 14>)`.
+Models read line numbers well and count characters badly, so the common case never counts:
+
+- **Whole lines** (the usual move): `{start_line: 10, end_line: 14, whole_lines: true}`. Linewise, vim-style — the trailing newline comes along, so a cut lifts the lines out cleanly and a paste at `{line: 42}` drops them in as complete lines.
+- Character positions are optional refinements: omitted `end_char` means end-of-line, omitted `start_char` (or paste `char`) means column 1.
+- When given, everything is **1-indexed** and ranges are **inclusive on both ends**: copying `(2, 5)` → `(2, 7)` yields exactly 3 characters.
 - A file ending in a newline has an addressable empty final line, so appending at end-of-file is `paste` at `(lastLine, 1)`.
 - Out-of-range positions return the line's real length and a preview of it, so an agent can self-correct in one step.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volcanic-dev/tephra",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "MCP server that gives AI agents a clipboard of their own: copy an exact line:char range from a file, paste it anywhere — byte-for-byte, without touching the OS clipboard.",
   "license": "MIT",
   "type": "module",

package/server.js

@@ -2,11 +2,17 @@
 // @tephra-server
 // Tephra — an MCP server that gives AI agents a clipboard of their own.
 //
-// Models are bad at retyping: moving 80 lines of code by regenerating them
-// invites transcription drift and burns tokens. Tephra lets an agent name an
-// exact range — start (line, char) to end (line, char), both 1-indexed and
-// inclusive — copy it byte-for-byte, and paste it at an exact position in
-// another file.
+// Models are bad at retyping: regenerating 200 lines to move them invites
+// transcription drift — a correctness bug, not just a token cost. Tephra
+// lets an agent name an exact range — whole lines, or (line, char) to
+// (line, char), 1-indexed and inclusive — copy it byte-for-byte, and paste
+// it at an exact position in another file.
+//
+// Models are also bad at counting characters within a line, so character
+// positions are optional everywhere: whole_lines ranges take line numbers
+// only (linewise, including the trailing newline, so cuts leave no empty
+// husk), an omitted end_char means end-of-line, an omitted start_char or
+// paste char means column 1.
 //
 // The clipboard is a private in-process buffer, deliberately NOT the OS
 // clipboard: an agent must not be able to read whatever the human last
@@ -18,9 +24,12 @@
 // mismatch modifies nothing and reports where that text actually is now.
 // Batched ranges/targets are applied bottom-up, so one read of a file
 // yields coordinates that stay valid for the whole call, and any edit that
-// changes line numbering reports the shift.
+// changes line numbering reports the shift. The commonest workflows are
+// single atomic calls: `move` is cut + paste with the server doing the
+// shift arithmetic, and a paste target with end_line/whole_lines REPLACES
+// a range instead of inserting.
 //
-// Tools: copy, cut, paste, peek.
+// Tools: copy, cut, paste, move, peek.
 
 import { readFile, writeFile } from 'node:fs/promises'
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
@@ -153,6 +162,8 @@ function shiftNote(afterLine, delta) {
 // addressed against the same read of the file; cut applies them bottom-up so
 // none invalidates another. Multi-range calls must name a distinct slot per
 // range (defaulting them all to "default" would silently overwrite).
+// whole_lines ranges are linewise: they include the end line's terminator,
+// so cutting them removes the lines entirely instead of leaving empty husks.
 function resolveRanges(text, lines, ranges, forCut) {
   const resolved = ranges.map((r, idx) => {
     const label = ranges.length === 1 ? 'range' : `range ${idx + 1}`
@@ -161,10 +172,25 @@ function resolveRanges(text, lines, ranges, forCut) {
       if (ranges.length > 1) throw new PositionError(`${label}: when passing multiple ranges, every range must name its own slot (otherwise they would overwrite each other).`)
       slot = 'default'
     }
-    const startOff = charOffset(text, lines, r.start_line, r.start_char, `${label} start`, 0)
-    const endOff = charOffset(text, lines, r.end_line, r.end_char, `${label} end`, 0) + 1 // end is inclusive
+    let startOff
+    let endOff
+    if (r.whole_lines) {
+      if (r.start_char !== undefined || r.end_char !== undefined) {
+        throw new PositionError(`${label}: whole_lines ranges take only start_line and end_line — omit start_char and end_char.`)
+      }
+      startOff = lineAt(lines, r.start_line, `${label} start`).start
+      lineAt(lines, r.end_line, `${label} end`)
+      endOff = r.end_line < lines.length ? lines[r.end_line].start : text.length
+    } else {
+      startOff = r.start_char === undefined
+        ? lineAt(lines, r.start_line, `${label} start`).start
+        : charOffset(text, lines, r.start_line, r.start_char, `${label} start`, 0)
+      endOff = r.end_char === undefined
+        ? lineAt(lines, r.end_line, `${label} end`).contentEnd
+        : charOffset(text, lines, r.end_line, r.end_char, `${label} end`, 0) + 1 // end is inclusive
+    }
     if (endOff <= startOff) {
-      throw new PositionError(`${label}: the end position (line ${r.end_line}, char ${r.end_char}) comes before the start position (line ${r.start_line}, char ${r.start_char}).`)
+      throw new PositionError(`${label}: the range from ${rangeDesc(r)} is empty or reversed — the end does not come after the start.`)
     }
     if (r.expect !== undefined) verifyExpect(text, lines, startOff, r.expect, label)
     return { ...r, idx, label, slot, startOff, endOff }
@@ -185,8 +211,13 @@ function resolveRanges(text, lines, ranges, forCut) {
   return resolved
 }
 
+function rangeDesc(r) {
+  if (r.whole_lines) return r.start_line === r.end_line ? `line ${r.start_line}` : `lines ${r.start_line}–${r.end_line}`
+  return `${r.start_line}:${r.start_char ?? 1} → ${r.end_line}:${r.end_char ?? 'end-of-line'}`
+}
+
 function rangeSummary(r, snippet) {
-  return `slot "${r.slot}": ${describe(snippet)} (${r.start_line}:${r.start_char} → ${r.end_line}:${r.end_char}) — ${inlinePreview(snippet)}`
+  return `slot "${r.slot}": ${describe(snippet)} (${rangeDesc(r)}) — ${inlinePreview(snippet)}`
 }
 
 function ok(message) {
@@ -206,7 +237,7 @@ async function guarded(fn) {
 }
 
 // @tephra-tools
-const server = new McpServer({ name: 'tephra', version: '0.2.0' })
+const server = new McpServer({ name: 'tephra', version: '0.4.0' })
 
 const expectSchema = z
   .string()
@@ -217,9 +248,10 @@ const expectSchema = z
 
 const rangeItem = z.object({
   start_line: z.number().int().describe('Line of the first character (1-indexed)'),
-  start_char: z.number().int().describe('Character position on start_line of the first character (1-indexed)'),
+  start_char: z.number().int().optional().describe('Character position on start_line of the first character (1-indexed). Omit to start at the beginning of the line.'),
   end_line: z.number().int().describe('Line of the last character (1-indexed, inclusive)'),
-  end_char: z.number().int().describe('Character position on end_line of the last character (1-indexed, inclusive)'),
+  end_char: z.number().int().optional().describe('Character position on end_line of the last character (1-indexed, inclusive). Omit to run to the end of the line. Prefer omitting over counting characters.'),
+  whole_lines: z.boolean().optional().describe('Take start_line through end_line as complete lines, INCLUDING the trailing newline (so cutting removes the lines entirely, leaving no empty line behind). With this set, omit start_char/end_char. Preferred for any whole-line move.'),
   slot: z.string().min(1).max(64).optional().describe('Clipboard slot to store this range in. Optional for a single range (defaults to "default"); required, and distinct, when passing multiple ranges.'),
   expect: expectSchema,
 })
@@ -238,9 +270,9 @@ server.registerTool(
   {
     title: 'Copy ranges to clipboard',
     description:
-      "Copy one or more exact character ranges from a file into Tephra's clipboard slots, byte-for-byte. " +
-      'Each range runs (start_line, start_char) → (end_line, end_char), inclusive on both ends, 1-indexed; newlines inside a range are included. ' +
-      'Use this instead of retyping text you intend to move or duplicate. ' +
+      "Copy one or more exact ranges from a file into Tephra's clipboard slots, byte-for-byte — use this instead of retyping text you intend to move or duplicate, so nothing gets subtly mangled in transit. " +
+      'For whole lines (the common case), set whole_lines: true and give line numbers only. ' +
+      'Character positions are optional: each range runs (start_line, start_char) → (end_line, end_char), inclusive on both ends, 1-indexed; omit start_char for column 1 and end_char for end-of-line rather than counting characters. ' +
       "Pass `expect` (the range's first characters) to verify the coordinates still match the content before copying. " +
       'The clipboard is private to this session, not the operating system clipboard.',
     inputSchema: rangesSchema,
@@ -254,7 +286,7 @@ server.registerTool(
       resolved.forEach((r, i) => slots.set(r.slot, snippets[i]))
       if (resolved.length === 1) {
         const [r] = resolved
-        return ok(`Copied ${describe(snippets[0])} from ${file} (${r.start_line}:${r.start_char} → ${r.end_line}:${r.end_char}) to slot "${r.slot}".\n\nPreview:\n${preview(snippets[0])}`)
+        return ok(`Copied ${describe(snippets[0])} from ${file} (${rangeDesc(r)}) to slot "${r.slot}".\n\nPreview:\n${preview(snippets[0])}`)
       }
       return ok(`Copied ${resolved.length} ranges from ${file}:\n${resolved.map((r, i) => `- ${rangeSummary(r, snippets[i])}`).join('\n')}`)
     }),
@@ -266,6 +298,7 @@ server.registerTool(
     title: 'Cut ranges to clipboard',
     description:
       'Same as copy, but also removes the ranges from the source file (they must not overlap). ' +
+      'For moving whole lines, set whole_lines: true — the trailing newline comes along, so the lines are removed entirely with no empty line left behind. ' +
       'Ranges are removed bottom-up, so every range is addressed against the file exactly as you last read it. The file is written back immediately. ' +
       'CAUTION: removing lines shifts the line numbers of everything below a cut — the result says by how much; recompute stale positions before reusing them.',
     inputSchema: rangesSchema,
@@ -285,7 +318,7 @@ server.registerTool(
       const finalCount = indexLines(out).length
       if (resolved.length === 1) {
         const [r] = resolved
-        return ok(`Cut ${describe(snippets[0])} from ${file} (${r.start_line}:${r.start_char} → ${r.end_line}:${r.end_char}) to slot "${r.slot}". The file has been updated (${finalCount} addressable lines).${shiftNote(r.end_line, -newlineCount(snippets[0]))}\n\nPreview:\n${preview(snippets[0])}`)
+        return ok(`Cut ${describe(snippets[0])} from ${file} (${rangeDesc(r)}) to slot "${r.slot}". The file has been updated (${finalCount} addressable lines).${shiftNote(r.end_line, -newlineCount(snippets[0]))}\n\nPreview:\n${preview(snippets[0])}`)
       }
       const removedLines = snippets.reduce((acc, s) => acc + newlineCount(s), 0)
       return ok(
@@ -298,30 +331,75 @@ server.registerTool(
     }),
 )
 
+// @tephra-paste-targets — a paste target either inserts at an anchor or, when
+// end_line/whole_lines is present, REPLACES a range with the slot contents.
+function resolveTarget(text, lines, t, label) {
+  const clip = slots.get(t.slot)
+  if (clip === undefined || clip.length === 0) {
+    throw new PositionError(`${label}: slot "${t.slot}" is empty — nothing to paste. ${slots.size > 0 ? `Slots that do hold text: ${slotList()}.` : 'Use copy or cut first.'}`)
+  }
+  const isReplace = t.end_line !== undefined || t.whole_lines === true
+  if (t.end_char !== undefined && t.end_line === undefined) {
+    throw new PositionError(`${label}: end_char requires end_line.`)
+  }
+  let off
+  let endOff
+  if (isReplace && t.whole_lines) {
+    if (t.end_char !== undefined) throw new PositionError(`${label}: whole_lines replacement takes only line and end_line — omit end_char.`)
+    off = lineAt(lines, t.line, label).start
+    const endLine = t.end_line ?? t.line
+    lineAt(lines, endLine, `${label} end`)
+    endOff = endLine < lines.length ? lines[endLine].start : text.length
+  } else if (isReplace) {
+    off = charOffset(text, lines, t.line, t.char, label, 1)
+    endOff = t.end_char === undefined
+      ? lineAt(lines, t.end_line, `${label} end`).contentEnd
+      : charOffset(text, lines, t.end_line, t.end_char, `${label} end`, 0) + 1
+    if (endOff <= off) throw new PositionError(`${label}: the range to replace is empty or reversed — the end does not come after the start.`)
+  } else {
+    off = charOffset(text, lines, t.line, t.char, label, 1)
+    endOff = off
+  }
+  if (t.expect !== undefined) verifyExpect(text, lines, off, t.expect, label)
+  return { off, endOff, clip, isReplace }
+}
+
+function targetDesc(t) {
+  if (!(t.end_line !== undefined || t.whole_lines === true)) return `${t.line}:${t.char}`
+  if (t.whole_lines) {
+    const endLine = t.end_line ?? t.line
+    return t.line === endLine ? `line ${t.line}` : `lines ${t.line}–${endLine}`
+  }
+  return `${t.line}:${t.char} → ${t.end_line}:${t.end_char ?? 'end-of-line'}`
+}
+
 server.registerTool(
   'paste',
   {
     title: 'Paste clipboard into file',
     description:
-      "Insert Tephra clipboard slot contents into a file at one or more exact positions. " +
-      'Text is inserted before the character at (line, char); char may be one past the end of the line to append to it. ' +
+      "Insert Tephra clipboard slot contents into a file at one or more exact positions, or replace ranges with them. " +
+      'By default text is inserted before the character at (line, char) and nothing is overwritten; char defaults to 1 (right for whole lines) and may be one past the end of the line to append to it. ' +
+      'REPLACE MODE: give end_line (plus optional end_char, or whole_lines: true for complete lines) and the slot contents replace that range instead — the result shows exactly what was removed. ' +
       'Multiple targets are applied bottom-up, so they all use the coordinates of the file as you last read it. ' +
-      'Pass `expect` (the text that currently begins at the position) to verify before pasting. ' +
-      'Existing text is never overwritten — it shifts to make room, and the result says how line numbers moved.',
+      'Pass `expect` (the text that currently begins at the position) to verify before touching anything.',
     inputSchema: {
       file: z.string().describe('Absolute path of the file to paste into'),
       targets: z
         .array(
           z.object({
-            line: z.number().int().describe('Line to paste at (1-indexed)'),
-            char: z.number().int().describe('Character position to paste at (1-indexed; the clipboard is inserted before this character; line length + 1 means end of line)'),
+            line: z.number().int().describe('Line of the anchor (1-indexed); in replace mode, the first line of the range being replaced'),
+            char: z.number().int().default(1).describe('Character position of the anchor (1-indexed; text is inserted before this character; line length + 1 means end of line). Omit for column 1 — the right choice for whole lines.'),
+            end_line: z.number().int().optional().describe('Replace mode: replace from the anchor through this line (1-indexed, inclusive) with the slot contents instead of inserting'),
+            end_char: z.number().int().optional().describe('Replace mode: last character replaced on end_line (1-indexed, inclusive). Omit for end-of-line.'),
+            whole_lines: z.boolean().optional().describe('Replace mode: replace complete lines line..end_line (end_line defaults to line), INCLUDING the trailing newline. Omit char/end_char.'),
             slot: z.string().min(1).max(64).default('default').describe('Clipboard slot to paste from (defaults to "default")'),
             expect: expectSchema,
           }),
         )
         .min(1)
         .max(20)
-        .describe('One or more paste positions, all addressed against the file as it is right now — they are applied bottom-up, so earlier targets never invalidate later ones.'),
+        .describe('One or more paste/replace targets, all addressed against the file as it is right now — they are applied bottom-up, so earlier targets never invalidate later ones.'),
     },
   },
   async ({ file, targets }) =>
@@ -329,45 +407,133 @@ server.registerTool(
       const text = await readFile(file, 'utf8')
       const lines = indexLines(text)
       const resolved = targets.map((t, idx) => {
-        const label = targets.length === 1 ? 'paste position' : `target ${idx + 1}`
-        const clip = slots.get(t.slot)
-        if (clip === undefined || clip.length === 0) {
-          throw new PositionError(`${label}: slot "${t.slot}" is empty — nothing to paste. ${slots.size > 0 ? `Slots that do hold text: ${slotList()}.` : 'Use copy or cut first.'}`)
-        }
-        const off = charOffset(text, lines, t.line, t.char, label, 1)
-        if (t.expect !== undefined) verifyExpect(text, lines, off, t.expect, label)
-        return { ...t, idx, label, off, clip }
+        const label = targets.length === 1 ? 'paste target' : `target ${idx + 1}`
+        return { ...t, idx, label, ...resolveTarget(text, lines, t, label) }
       })
+      const byOff = [...resolved].sort((a, b) => a.off - b.off || a.idx - b.idx)
+      for (let i = 1; i < byOff.length; i++) {
+        if (byOff[i].off < byOff[i - 1].endOff) {
+          throw new PositionError(`${byOff[i].label} falls inside the range replaced by ${byOff[i - 1].label} — targets must not overlap. Nothing was modified.`)
+        }
+      }
       let out = text
       for (const t of [...resolved].sort((a, b) => b.off - a.off || b.idx - a.idx)) {
-        out = out.slice(0, t.off) + t.clip + out.slice(t.off)
+        out = out.slice(0, t.off) + t.clip + out.slice(t.endOff)
       }
       await writeFile(file, out, 'utf8')
       const finalLines = indexLines(out)
-      // final coordinates: shift each target by everything inserted above it
+      // final coordinates: shift each target by the net effect of everything applied above it
       const placed = resolved.map((t) => {
-        const delta = resolved.reduce((acc, o) => acc + (o.off < t.off || (o.off === t.off && o.idx < t.idx) ? o.clip.length : 0), 0)
+        const delta = resolved.reduce((acc, o) => acc + (o.off < t.off || (o.off === t.off && o.idx < t.idx) ? o.clip.length - (o.endOff - o.off) : 0), 0)
         return {
           t,
+          removed: text.slice(t.off, t.endOff),
           start: positionOf(finalLines, t.off + delta),
           end: positionOf(finalLines, t.off + delta + t.clip.length),
         }
       })
       if (placed.length === 1) {
-        const [{ t, start, end }] = placed
-        return ok(`Pasted ${describe(t.clip)} from slot "${t.slot}" into ${file} at ${t.line}:${t.char}. The inserted text now spans ${start.line}:${start.char} → ${end.line}:${end.char} (exclusive end).${shiftNote(t.line, newlineCount(t.clip))}\n\nPreview:\n${preview(t.clip)}`)
+        const [{ t, removed, start, end }] = placed
+        const span = `now spans ${start.line}:${start.char} → ${end.line}:${end.char} (exclusive end)`
+        if (t.isReplace) {
+          const anchorLine = t.whole_lines || t.end_char === undefined ? (t.end_line ?? t.line) : t.end_line
+          return ok(`Replaced ${targetDesc(t)} in ${file} (removed ${describe(removed)} — ${inlinePreview(removed)}) with slot "${t.slot}" (${describe(t.clip)}). The new text ${span}.${shiftNote(anchorLine, newlineCount(t.clip) - newlineCount(removed))}\n\nPreview:\n${preview(t.clip)}`)
+        }
+        return ok(`Pasted ${describe(t.clip)} from slot "${t.slot}" into ${file} at ${t.line}:${t.char}. The inserted text ${span}.${shiftNote(t.line, newlineCount(t.clip))}\n\nPreview:\n${preview(t.clip)}`)
       }
-      const addedLines = resolved.reduce((acc, t) => acc + newlineCount(t.clip), 0)
+      const netLines = placed.reduce((acc, { t, removed }) => acc + newlineCount(t.clip) - newlineCount(removed), 0)
       return ok(
-        `Pasted ${placed.length} targets into ${file}, applied bottom-up (file updated, ${finalLines.length} addressable lines):\n` +
-        placed.map(({ t, start, end }) => `- slot "${t.slot}" (${describe(t.clip)}) at ${t.line}:${t.char} → final span ${start.line}:${start.char} → ${end.line}:${end.char}`).join('\n') +
-        (addedLines > 0
-          ? `\n${addedLines} line${addedLines === 1 ? '' : 's'} of numbering inserted in total — line numbers below each paste have shifted down; recompute any positions you noted earlier before using them.`
+        `Applied ${placed.length} targets to ${file}, bottom-up (file updated, ${finalLines.length} addressable lines):\n` +
+        placed.map(({ t, removed, start, end }) =>
+          `- slot "${t.slot}" (${describe(t.clip)}) ${t.isReplace ? `replaced ${targetDesc(t)} (removed ${describe(removed)})` : `at ${t.line}:${t.char}`} → final span ${start.line}:${start.char} → ${end.line}:${end.char}`,
+        ).join('\n') +
+        (netLines !== 0
+          ? `\nNet line-numbering change: ${netLines > 0 ? '+' : ''}${netLines} — recompute any positions you noted earlier before using them.`
           : ''),
       )
     }),
 )
 
+server.registerTool(
+  'move',
+  {
+    title: 'Move ranges (atomic cut + paste)',
+    description:
+      'Move one or more ranges to a destination in ONE atomic call — the compound of cut and paste. ' +
+      'All coordinates, source ranges AND destination, are addressed against the file(s) exactly as they are right now: do not pre-adjust the destination for the lines the cut removes — the server does that arithmetic. ' +
+      'The destination may be in a different file. Multiple ranges are concatenated at the destination in listed order, and the moved text is also stored in the clipboard slot(s). ' +
+      'For whole lines, set whole_lines: true on the range and give the destination as a line number only.',
+    inputSchema: {
+      file: z.string().describe('Absolute path of the source file'),
+      ranges: rangesSchema.ranges,
+      to: z
+        .object({
+          file: z.string().optional().describe('Destination file (defaults to the source file)'),
+          line: z.number().int().describe('Destination line (1-indexed), in the destination file as it is NOW — do not adjust for the cut'),
+          char: z.number().int().default(1).describe('Destination character (1-indexed; the text is inserted before it; line length + 1 means end of line). Omit for column 1 — the right choice for whole lines.'),
+          expect: expectSchema,
+        })
+        .describe('Where the text goes; it is inserted before the character at (line, char)'),
+    },
+  },
+  async ({ file, ranges, to }) =>
+    guarded(async () => {
+      const text = await readFile(file, 'utf8')
+      const lines = indexLines(text)
+      const resolved = resolveRanges(text, lines, ranges, true)
+      const snippets = resolved.map((r) => text.slice(r.startOff, r.endOff))
+      const payload = snippets.join('')
+      const sameFile = to.file === undefined || to.file === file
+      const destText = sameFile ? text : await readFile(to.file, 'utf8')
+      const destLines = sameFile ? lines : indexLines(destText)
+      const destOff = charOffset(destText, destLines, to.line, to.char, 'destination', 1)
+      if (to.expect !== undefined) verifyExpect(destText, destLines, destOff, to.expect, 'destination')
+      if (sameFile) {
+        for (const r of resolved) {
+          if (destOff > r.startOff && destOff < r.endOff) {
+            throw new PositionError(`destination ${to.line}:${to.char} falls inside ${r.label} (${rangeDesc(r)}) — a range cannot be moved into itself. Nothing was modified.`)
+          }
+        }
+      }
+      resolved.forEach((r, i) => slots.set(r.slot, snippets[i]))
+      let srcOut = text
+      for (const r of [...resolved].sort((a, b) => b.startOff - a.startOff)) {
+        srcOut = srcOut.slice(0, r.startOff) + srcOut.slice(r.endOff)
+      }
+      let start
+      let end
+      let destFinalCount
+      if (sameFile) {
+        const adjDest = destOff - resolved.reduce((acc, r) => acc + (r.endOff <= destOff ? r.endOff - r.startOff : 0), 0)
+        const out = srcOut.slice(0, adjDest) + payload + srcOut.slice(adjDest)
+        await writeFile(file, out, 'utf8')
+        const finalLines = indexLines(out)
+        destFinalCount = finalLines.length
+        start = positionOf(finalLines, adjDest)
+        end = positionOf(finalLines, adjDest + payload.length)
+      } else {
+        // insert into the destination before cutting the source, so a failure
+        // between the two writes duplicates text rather than losing it
+        const destOut = destText.slice(0, destOff) + payload + destText.slice(destOff)
+        await writeFile(to.file, destOut, 'utf8')
+        await writeFile(file, srcOut, 'utf8')
+        const finalLines = indexLines(destOut)
+        destFinalCount = finalLines.length
+        start = positionOf(finalLines, destOff)
+        end = positionOf(finalLines, destOff + payload.length)
+      }
+      const destName = sameFile ? file : to.file
+      const slotsDesc = resolved.length === 1 ? `slot "${resolved[0].slot}"` : `slots ${resolved.map((r) => `"${r.slot}"`).join(', ')}`
+      return ok(
+        `Moved ${describe(payload)} from ${file} (${resolved.map((r) => rangeDesc(r)).join(', ')}) to ${destName} ${to.line}:${to.char}. ` +
+        `It now spans ${start.line}:${start.char} → ${end.line}:${end.char} (final coordinates, exclusive end; ${sameFile ? 'file' : 'destination file'} has ${destFinalCount} addressable lines${sameFile ? '' : `; source file has ${indexLines(srcOut).length}`}). ` +
+        `Also stored in ${slotsDesc}.` +
+        '\nLine numbers around both the cut and the insertion have shifted — the span above is authoritative; recompute anything you noted earlier.' +
+        `\n\nPreview:\n${preview(payload)}`,
+      )
+    }),
+)
+
 server.registerTool(
   'peek',
   {