@oh-my-pi/hashline 16.1.22 → 16.2.0

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 ## [Unreleased]
 
+## [16.2.0] - 2026-06-27
+
+### Added
+
+- Added `REM` (remove) and `MV` (move/rename) section operations to hashline patches, allowing files to be deleted or relocated (with snapshot history migration) directly within the edit tool.
+
+## [16.1.23] - 2026-06-26
+
+### Added
+
+- Updated prompt documentation to include support for Markdown section operations
+
+### Fixed
+
+- Improved file path recovery to correctly handle read-only or incorrectly typed paths
+
 ## [16.1.14] - 2026-06-22
 
 ### Fixed

package/README.md

@@ -52,6 +52,8 @@ Inside a section:
 - `DEL A.=B` / `DEL.BLK A` — delete concrete lines or a resolved block.
 - `INS.PRE A:` / `INS.POST A:` / `INS.HEAD:` / `INS.TAIL:` — insert following body rows.
 - `INS.BLK.POST A:` — insert following body rows after the resolved block's last line.
+- `REM` — delete the whole file named by the section header.
+- `MV DEST` — move/rename the section file to `DEST` (optionally after line edits).
 - `+TEXT` — literal body row (use `+` alone for a blank line).
 
 ## Abstractions

package/dist/types/format.d.ts

@@ -29,6 +29,10 @@ export declare const HL_REPLACE_BLOCK_KEYWORD = "SWAP.BLK";
 export declare const HL_DELETE_BLOCK_KEYWORD = "DEL.BLK";
 /** Hunk-header keyword: `INS.BLK.POST N:` inserts after the last line of the tree-sitter block at N. */
 export declare const HL_INSERT_AFTER_BLOCK_KEYWORD = "INS.BLK.POST";
+/** File-level keyword: `REM` deletes the whole file named by the section header. */
+export declare const HL_REM_KEYWORD = "REM";
+/** File-level keyword: `MV DEST` renames/moves the section file to `DEST`. */
+export declare const HL_MOVE_KEYWORD = "MV";
 export declare const HL_HEADER_COLON = ":";
 /** Separator between a hashline file path and its opaque snapshot tag. */
 export declare const HL_FILE_HASH_SEP = "#";

package/dist/types/fs.d.ts

@@ -7,6 +7,11 @@ export interface WriteResult {
     /** Final text that was persisted. May differ from the input if the FS transformed it. */
     text: string;
 }
+import type { FileOp } from "./types";
+/** Optional hints for {@link Filesystem.preflightWrite}. */
+export interface PreflightWriteOptions {
+    fileOp?: FileOp;
+}
 /**
  * ENOENT-like error thrown by {@link Filesystem.readText} when a path is
  * missing. Carrying a `code` property keeps the contract compatible with
@@ -33,9 +38,16 @@ export declare abstract class Filesystem {
     /** Read the file's full text content. Throw on missing file. */
     abstract readText(path: string): Promise<string>;
     /** Validate that `path` is writable before a prepared batch starts committing. */
-    preflightWrite(_path: string): Promise<void>;
+    preflightWrite(_path: string, _options?: PreflightWriteOptions): Promise<void>;
     /** Persist `content` at `path`. Returns the actual final text that was written. */
     abstract writeText(path: string, content: string): Promise<WriteResult>;
+    /** Delete the file at `path`. Default: not supported. */
+    delete(path: string): Promise<void>;
+    /**
+     * Move/rename `from` to `to`. When `content` is provided the destination
+     * receives that text; otherwise implementations may preserve the source bytes.
+     */
+    move(from: string, to: string, content?: string): Promise<void>;
     /** Return true when the path exists and can be read. Default: probe via {@link readText}. */
     exists(path: string): Promise<boolean>;
     /**
@@ -67,13 +79,13 @@ export declare class InMemoryFilesystem extends Filesystem {
     constructor(initial?: Iterable<readonly [string, string]>);
     readText(path: string): Promise<string>;
     writeText(path: string, content: string): Promise<WriteResult>;
+    delete(path: string): Promise<void>;
+    move(from: string, to: string, content?: string): Promise<void>;
     exists(path: string): Promise<boolean>;
     /** Synchronous helper for setting up fixtures without awaiting. */
     set(path: string, content: string): void;
     /** Synchronous helper for inspecting state without awaiting. */
     get(path: string): string | undefined;
-    /** Remove a single entry. Returns true when something was removed. */
-    delete(path: string): boolean;
     /** Wipe all entries. */
     clear(): void;
     /** Iterate `[path, content]` pairs. */
@@ -87,6 +99,8 @@ export declare class InMemoryFilesystem extends Filesystem {
 export declare class NodeFilesystem extends Filesystem {
     readText(path: string): Promise<string>;
     writeText(path: string, content: string): Promise<WriteResult>;
+    delete(path: string): Promise<void>;
+    move(from: string, to: string, content?: string): Promise<void>;
     canonicalPath(path: string): string;
     exists(path: string): Promise<boolean>;
 }

package/dist/types/input.d.ts

@@ -1,4 +1,4 @@
-import type { ApplyResult, BlockResolver, Edit, SplitOptions } from "./types";
+import type { ApplyResult, BlockResolver, Edit, FileOp, SplitOptions } from "./types";
 interface RawSection {
     path: string;
     fileHash?: string;
@@ -24,15 +24,18 @@ export declare class PatchSection {
     constructor(raw: RawSection);
     /**
      * Parse this section's diff body. Cached: subsequent calls return the
-     * same `{ edits, warnings }` object so callers can safely call this from
+     * same `{ edits, fileOp?, warnings }` object so callers can safely call this from
      * multiple paths (preflight, apply, diff-preview).
      */
     parse(): {
         edits: Edit[];
+        fileOp?: FileOp;
         warnings: readonly string[];
     };
     /** Parsed edits for this section. */
     get edits(): readonly Edit[];
+    /** Optional whole-file operation (`REM` / `MV`). */
+    get fileOp(): FileOp | undefined;
     /** Warnings emitted during parsing of this section. */
     get warnings(): readonly string[];
     /**

package/dist/types/messages.d.ts

@@ -56,6 +56,10 @@ export declare function insertAfterBlockUnresolvedLoweredWarning(line: number):
 export declare const UNRESOLVED_BLOCK_INTERNAL = "internal error: unresolved `SWAP.BLK` edit reached the applier (resolveBlockEdits was not run).";
 /** Delete hunk received a body row. */
 export declare const DELETE_TAKES_NO_BODY = "`DEL N.=M` does not take body rows. Remove the body, or use `SWAP N.=M:`.";
+/** `REM` received a body row or coexists with line edits. */
+export declare const REM_TAKES_NO_BODY = "`REM` deletes the whole file and takes no body rows or line ops. Issue it alone under the header.";
+/** `MV` received a body row. */
+export declare const MOVE_TAKES_NO_BODY = "`MV DEST` does not take body rows. Put line edits above the `MV` row; the destination path follows `MV` on the same line.";
 /** `delete_block N` hunk received a body row. */
 export declare const DELETE_BLOCK_TAKES_NO_BODY = "`DEL.BLK N` does not take body rows. Remove the body, or use `SWAP.BLK N:`.";
 /** Insert hunk with no body. */

package/dist/types/parser.d.ts

@@ -1,23 +1,27 @@
 import { type Token } from "./tokenizer";
-import type { Edit } from "./types";
+import type { Edit, FileOp } from "./types";
 export declare class Executor {
     #private;
     feed(token: Token): void;
     end(): {
         edits: Edit[];
+        fileOp?: FileOp;
         warnings: string[];
     };
     endStreaming(): {
         edits: Edit[];
+        fileOp?: FileOp;
         warnings: string[];
     };
     reset(): void;
 }
 export declare function parsePatch(diff: string): {
     edits: Edit[];
+    fileOp?: FileOp;
     warnings: string[];
 };
 export declare function parsePatchStreaming(diff: string): {
     edits: Edit[];
+    fileOp?: FileOp;
     warnings: string[];
 };

package/dist/types/patcher.d.ts

@@ -3,7 +3,7 @@ import type { Patch, PatchSection } from "./input";
 import { type LineEnding } from "./normalize";
 import { Recovery } from "./recovery";
 import type { SnapshotStore } from "./snapshots";
-import type { ApplyResult, BlockResolution, BlockResolver } from "./types";
+import type { ApplyResult, BlockResolution, BlockResolver, FileOp } from "./types";
 export interface PatcherOptions {
     /** Storage backend used for all reads and writes. */
     fs: Filesystem;
@@ -22,8 +22,8 @@ export interface PatchSectionResult {
     path: string;
     /** Filesystem-canonical key for this section (e.g. absolute path). */
     canonicalPath: string;
-    /** `"noop"` when the apply produced no change; otherwise `"create"` / `"update"`. */
-    op: "create" | "update" | "noop";
+    /** `"noop"` when the apply produced no change; `"delete"` removes the file; otherwise `"create"` / `"update"`. */
+    op: "create" | "update" | "delete" | "noop";
     /** Pre-edit text (LF-normalized, BOM-stripped). */
     before: string;
     /** Post-edit text (LF-normalized, BOM-stripped). For `"noop"` equals `before`. */
@@ -40,6 +40,8 @@ export interface PatchSectionResult {
     firstChangedLine?: number;
     /** Warnings collected by the parser, applier, and (optionally) recovery. */
     warnings: string[];
+    /** Destination path when this section includes `MV DEST`. */
+    moveDest?: string;
     /**
      * Resolved spans for any `replace_block`/`delete_block` ops, present when the
      * apply matched the tagged content. Undefined for patches with no block ops
@@ -65,9 +67,10 @@ export declare class PreparedSection {
     readonly normalized: string;
     readonly applyResult: ApplyResult;
     readonly parseWarnings: readonly string[];
+    readonly fileOp: FileOp | undefined;
     /** @internal */
-    constructor(section: PatchSection, canonicalPath: string, exists: boolean, rawContent: string, bom: string, lineEnding: LineEnding, normalized: string, applyResult: ApplyResult, parseWarnings: readonly string[]);
-    /** Convenience: returns true when the apply produced no change. */
+    constructor(section: PatchSection, canonicalPath: string, exists: boolean, rawContent: string, bom: string, lineEnding: LineEnding, normalized: string, applyResult: ApplyResult, parseWarnings: readonly string[], fileOp: FileOp | undefined);
+    /** Convenience: returns true when the apply produced no change and no file op. */
     get isNoop(): boolean;
 }
 /**

package/dist/types/snapshots.d.ts

@@ -56,6 +56,12 @@ export declare abstract class SnapshotStore {
     abstract recordSeenLines(path: string, hash: string, lines: Iterable<number>): void;
     /** Drop the version history for a single path. */
     abstract invalidate(path: string): void;
+    /**
+     * Move retained version history (and read provenance) from `from` to `to`.
+     * No-op when `from` has no history. Used by file moves so tags minted from
+     * reads of the source path stay valid at the destination.
+     */
+    abstract relocate(from: string, to: string): void;
     /** Drop every version history. */
     abstract clear(): void;
 }
@@ -89,5 +95,6 @@ export declare class InMemorySnapshotStore extends SnapshotStore {
     record(path: string, fullText: string, seenLines?: Iterable<number>): string;
     recordSeenLines(path: string, hash: string, lines: Iterable<number>): void;
     invalidate(path: string): void;
+    relocate(from: string, to: string): void;
     clear(): void;
 }

package/dist/types/tokenizer.d.ts

@@ -24,6 +24,11 @@ export type BlockTarget = {
 } | {
     kind: "insert_after_block";
     anchor: Anchor;
+} | {
+    kind: "rem";
+} | {
+    kind: "move";
+    dest: string;
 } | {
     kind: "bof";
 } | {

package/dist/types/types.d.ts

@@ -66,6 +66,13 @@ export type Edit = {
     lineNum: number;
     index: number;
 };
+/** File-level operation parsed from a section body (`REM` / `MV`). */
+export type FileOp = {
+    kind: "rem";
+} | {
+    kind: "move";
+    dest: string;
+};
 /** Result of applying a parsed set of edits to a text body. */
 export interface ApplyResult {
     /** Post-edit text body. */

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/hashline",
-	"version": "16.1.22",
+	"version": "16.2.0",
 	"description": "Hashline: a compact, line-anchored patch language and applier. Pluggable FS/IO so it works over disk, in-memory, or any custom backend.",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",

package/src/format.ts

@@ -33,6 +33,10 @@ export const HL_REPLACE_BLOCK_KEYWORD = "SWAP.BLK";
 export const HL_DELETE_BLOCK_KEYWORD = "DEL.BLK";
 /** Hunk-header keyword: `INS.BLK.POST N:` inserts after the last line of the tree-sitter block at N. */
 export const HL_INSERT_AFTER_BLOCK_KEYWORD = "INS.BLK.POST";
+/** File-level keyword: `REM` deletes the whole file named by the section header. */
+export const HL_REM_KEYWORD = "REM";
+/** File-level keyword: `MV DEST` renames/moves the section file to `DEST`. */
+export const HL_MOVE_KEYWORD = "MV";
 export const HL_HEADER_COLON = ":";
 
 /** Separator between a hashline file path and its opaque snapshot tag. */

package/src/fs.ts

@@ -8,6 +8,7 @@
  * {@link Filesystem.readText} and {@link Filesystem.writeText}; the FS deals
  * only in raw text strings.
  */
+import * as fs from "node:fs/promises";
 import * as pathModule from "node:path";
 
 /**
@@ -20,6 +21,13 @@ export interface WriteResult {
 	text: string;
 }
 
+import type { FileOp } from "./types";
+
+/** Optional hints for {@link Filesystem.preflightWrite}. */
+export interface PreflightWriteOptions {
+	fileOp?: FileOp;
+}
+
 /**
  * ENOENT-like error thrown by {@link Filesystem.readText} when a path is
  * missing. Carrying a `code` property keeps the contract compatible with
@@ -58,11 +66,25 @@ export abstract class Filesystem {
 	abstract readText(path: string): Promise<string>;
 
 	/** Validate that `path` is writable before a prepared batch starts committing. */
-	async preflightWrite(_path: string): Promise<void> {}
+	async preflightWrite(_path: string, _options?: PreflightWriteOptions): Promise<void> {}
 
 	/** Persist `content` at `path`. Returns the actual final text that was written. */
 	abstract writeText(path: string, content: string): Promise<WriteResult>;
 
+	/** Delete the file at `path`. Default: not supported. */
+	async delete(path: string): Promise<void> {
+		throw new Error(`Filesystem does not support delete: ${path}`);
+	}
+
+	/**
+	 * Move/rename `from` to `to`. When `content` is provided the destination
+	 * receives that text; otherwise implementations may preserve the source bytes.
+	 */
+	async move(from: string, to: string, content?: string): Promise<void> {
+		void content;
+		throw new Error(`Filesystem does not support move: ${from} -> ${to}`);
+	}
+
 	/** Return true when the path exists and can be read. Default: probe via {@link readText}. */
 	async exists(path: string): Promise<boolean> {
 		try {
@@ -125,6 +147,18 @@ export class InMemoryFilesystem extends Filesystem {
 		return { text: content };
 	}
 
+	async delete(path: string): Promise<void> {
+		if (!this.#files.delete(path)) throw new NotFoundError(path);
+	}
+
+	async move(from: string, to: string, content?: string): Promise<void> {
+		const existing = this.#files.get(from);
+		if (existing === undefined) throw new NotFoundError(from);
+		const finalContent = content ?? existing;
+		this.#files.set(to, finalContent);
+		this.#files.delete(from);
+	}
+
 	async exists(path: string): Promise<boolean> {
 		return this.#files.has(path);
 	}
@@ -139,11 +173,6 @@ export class InMemoryFilesystem extends Filesystem {
 		return this.#files.get(path);
 	}
 
-	/** Remove a single entry. Returns true when something was removed. */
-	delete(path: string): boolean {
-		return this.#files.delete(path);
-	}
-
 	/** Wipe all entries. */
 	clear(): void {
 		this.#files.clear();
@@ -172,6 +201,29 @@ export class NodeFilesystem extends Filesystem {
 		return { text: content };
 	}
 
+	async delete(path: string): Promise<void> {
+		try {
+			await fs.rm(path);
+		} catch (error) {
+			if (isNotFound(error)) throw new NotFoundError(path, error);
+			throw error;
+		}
+	}
+
+	async move(from: string, to: string, content?: string): Promise<void> {
+		if (content !== undefined) {
+			await Bun.write(to, content);
+			await this.delete(from);
+			return;
+		}
+		try {
+			await fs.rename(from, to);
+		} catch (error) {
+			if (isNotFound(error)) throw new NotFoundError(from, error);
+			throw error;
+		}
+	}
+
 	canonicalPath(path: string): string {
 		return pathModule.resolve(path);
 	}

package/src/grammar.lark

@@ -7,13 +7,15 @@ file_header: "[" filename "#" file_hash "]" LF
 file_hash: /[0-9A-F]{4}/
 filename: /[^#\r\n]+/
 
-hunk: replace_hunk | replace_block_hunk | insert_hunk | insert_block_hunk | delete_hunk | delete_block_hunk
+hunk: replace_hunk | replace_block_hunk | insert_hunk | insert_block_hunk | delete_hunk | delete_block_hunk | remove_hunk | move_hunk
 replace_hunk: replace_anchor LF emit_op*
 replace_block_hunk: replace_block_anchor LF emit_op+
 insert_hunk: insert_anchor LF emit_op+
 insert_block_hunk: insert_block_anchor LF emit_op+
 delete_hunk: "DEL " header_range LF
 delete_block_hunk: "DEL.BLK " LID LF
+remove_hunk: "REM" LF
+move_hunk: "MV " filename LF emit_op*
 replace_anchor: "SWAP " header_range ":"
 replace_block_anchor: "SWAP.BLK " LID ":"
 insert_anchor:  "INS." insert_pos ":"

package/src/input.ts

@@ -13,7 +13,7 @@ import { resolveBlockEdits } from "./block";
 import { HL_FILE_HASH_EXAMPLES, HL_FILE_HASH_LENGTH, HL_FILE_HASH_SEP, HL_FILE_PREFIX, HL_FILE_SUFFIX } from "./format";
 import { parsePatch, parsePatchStreaming } from "./parser";
 import { Tokenizer } from "./tokenizer";
-import type { ApplyResult, BlockResolver, Edit, SplitOptions } from "./types";
+import type { ApplyResult, BlockResolver, Edit, FileOp, SplitOptions } from "./types";
 
 // Pure classification — single shared tokenizer is safe.
 const TOKENIZER = new Tokenizer();
@@ -237,7 +237,7 @@ export class PatchSection {
 	readonly path: string;
 	readonly fileHash: string | undefined;
 	readonly diff: string;
-	#parsed: { edits: Edit[]; warnings: string[] } | undefined;
+	#parsed: { edits: Edit[]; fileOp?: FileOp; warnings: string[] } | undefined;
 
 	constructor(raw: RawSection) {
 		this.path = raw.path;
@@ -247,12 +247,21 @@ export class PatchSection {
 
 	/**
 	 * Parse this section's diff body. Cached: subsequent calls return the
-	 * same `{ edits, warnings }` object so callers can safely call this from
+	 * same `{ edits, fileOp?, warnings }` object so callers can safely call this from
 	 * multiple paths (preflight, apply, diff-preview).
 	 */
-	parse(): { edits: Edit[]; warnings: readonly string[] } {
+	parse(): { edits: Edit[]; fileOp?: FileOp; warnings: readonly string[] } {
 		this.#parsed ??= parsePatch(this.diff);
-		return this.#parsed;
+		const parsed = this.#parsed;
+		const fileOp =
+			parsed.fileOp === undefined
+				? undefined
+				: parsed.fileOp.kind === "move"
+					? { kind: "move" as const, dest: normalizeHashlinePath(parsed.fileOp.dest) }
+					: parsed.fileOp;
+		return fileOp === parsed.fileOp
+			? parsed
+			: { edits: parsed.edits, ...(fileOp === undefined ? {} : { fileOp }), warnings: parsed.warnings };
 	}
 
 	/** Parsed edits for this section. */
@@ -260,6 +269,11 @@ export class PatchSection {
 		return this.parse().edits;
 	}
 
+	/** Optional whole-file operation (`REM` / `MV`). */
+	get fileOp(): FileOp | undefined {
+		return this.parse().fileOp;
+	}
+
 	/** Warnings emitted during parsing of this section. */
 	get warnings(): readonly string[] {
 		return this.parse().warnings;

package/src/messages.ts

@@ -119,6 +119,14 @@ export const UNRESOLVED_BLOCK_INTERNAL =
 /** Delete hunk received a body row. */
 export const DELETE_TAKES_NO_BODY = `\`DEL N${HL_RANGE_SEP}M\` does not take body rows. Remove the body, or use \`SWAP N${HL_RANGE_SEP}M:\`.`;
 
+/** `REM` received a body row or coexists with line edits. */
+export const REM_TAKES_NO_BODY =
+	"`REM` deletes the whole file and takes no body rows or line ops. Issue it alone under the header.";
+
+/** `MV` received a body row. */
+export const MOVE_TAKES_NO_BODY =
+	"`MV DEST` does not take body rows. Put line edits above the `MV` row; the destination path follows `MV` on the same line.";
+
 /** `delete_block N` hunk received a body row. */
 export const DELETE_BLOCK_TAKES_NO_BODY = "`DEL.BLK N` does not take body rows. Remove the body, or use `SWAP.BLK N:`.";
 

package/src/parser.ts

@@ -11,10 +11,12 @@ import {
 	EMPTY_BLOCK,
 	EMPTY_INSERT,
 	MINUS_ROW_REJECTED,
+	MOVE_TAKES_NO_BODY,
+	REM_TAKES_NO_BODY,
 } from "./messages";
 import { stripOneLeadingHashlinePrefix } from "./prefixes";
 import { type BlockTarget, cloneCursor, type ParsedRange, type Token, Tokenizer } from "./tokenizer";
-import type { Anchor, Cursor, Edit } from "./types";
+import type { Anchor, Cursor, Edit, FileOp } from "./types";
 
 function validateRangeOrder(range: ParsedRange, lineNum: number): void {
 	if (range.end.line < range.start.line) {
@@ -110,6 +112,7 @@ export class Executor {
 	#warnings: string[] = [];
 	#editIndex = 0;
 	#pending: Pending | undefined;
+	#fileOp: FileOp | undefined;
 	#terminated = false;
 	#skippableComments: PendingComment[] = [];
 
@@ -161,27 +164,47 @@ export class Executor {
 				if (token.target.kind === "replace" || token.target.kind === "delete") {
 					validateRangeOrder(token.target.range, token.lineNum);
 				}
+				if (token.target.kind === "rem") {
+					this.#flushPending();
+					this.#setFileOp({ kind: "rem" }, token.lineNum);
+					return;
+				}
+				if (token.target.kind === "move") {
+					this.#flushPending();
+					this.#setFileOp({ kind: "move", dest: token.target.dest }, token.lineNum);
+					return;
+				}
 				this.#flushPending();
 				this.#pending = { target: token.target, lineNum: token.lineNum, payloads: [], deferredBlanks: [] };
 				return;
 		}
 	}
 
-	end(): { edits: Edit[]; warnings: string[] } {
+	end(): { edits: Edit[]; fileOp?: FileOp; warnings: string[] } {
 		this.#consumePendingSkippableComments();
 		this.#flushPending();
+		this.#validateFileOp();
 		this.#validateNoOverlappingDeletes();
-		return { edits: this.#edits, warnings: this.#warnings };
+		return {
+			edits: this.#edits,
+			...(this.#fileOp === undefined ? {} : { fileOp: this.#fileOp }),
+			warnings: this.#warnings,
+		};
 	}
 
-	endStreaming(): { edits: Edit[]; warnings: string[] } {
+	endStreaming(): { edits: Edit[]; fileOp?: FileOp; warnings: string[] } {
 		this.#consumePendingSkippableComments();
 		if (this.#pending && this.#pending.payloads.length > 0) this.#flushPending();
 		else if (this.#pending?.target.kind === "delete" || this.#pending?.target.kind === "delete_block")
 			this.#flushPending();
 		else this.#pending = undefined;
+		this.#validateFileOp();
 		this.#validateNoOverlappingDeletes();
-		return { edits: this.#edits, warnings: this.#warnings };
+		return {
+			edits: this.#edits,
+			...(this.#fileOp === undefined ? {} : { fileOp: this.#fileOp }),
+			warnings: this.#warnings,
+		};
 	}
 
 	reset(): void {
@@ -189,10 +212,30 @@ export class Executor {
 		this.#warnings = [];
 		this.#editIndex = 0;
 		this.#pending = undefined;
+		this.#fileOp = undefined;
 		this.#skippableComments = [];
 		this.#terminated = false;
 	}
 
+	#setFileOp(fileOp: FileOp, lineNum: number): void {
+		if (this.#fileOp !== undefined) {
+			throw new Error(
+				`line ${lineNum}: only one file-level op (\`REM\` or \`MV\`) per section. Merge them under one header.`,
+			);
+		}
+		if (fileOp.kind === "rem" && this.#edits.length > 0) {
+			throw new Error(`line ${lineNum}: ${REM_TAKES_NO_BODY}`);
+		}
+		this.#fileOp = fileOp;
+	}
+
+	#validateFileOp(): void {
+		if (this.#fileOp?.kind !== "rem") return;
+		if (this.#edits.length > 0) {
+			throw new Error("`REM` deletes the whole file and cannot be combined with line ops.");
+		}
+	}
+
 	#validateNoOverlappingDeletes(): void {
 		const sourceLinesByAnchor = new Map<number, number[]>();
 		for (const edit of this.#edits) {
@@ -217,6 +260,7 @@ export class Executor {
 	#handleLiteralPayload(text: string, lineNum: number): void {
 		const pending = this.#pending;
 		if (!pending) {
+			if (this.#fileOp !== undefined) throw new Error(`line ${lineNum}: ${MOVE_TAKES_NO_BODY}`);
 			throw new Error(
 				`line ${lineNum}: payload line has no preceding hunk header. ` +
 					`Got ${JSON.stringify(`${HL_PAYLOAD_REPLACE}${text}`)}.`,
@@ -231,6 +275,7 @@ export class Executor {
 	#handleRaw(text: string, lineNum: number): void {
 		const contamination = detectApplyPatchContamination(text, this.#pending !== undefined);
 		if (contamination !== null) throw new Error(`line ${lineNum}: ${contamination}`);
+		if (this.#fileOp !== undefined) throw new Error(`line ${lineNum}: ${MOVE_TAKES_NO_BODY}`);
 		if (this.#pending) {
 			if (text.trim().length === 0) {
 				this.#handleBlank(text, lineNum);
@@ -390,19 +435,19 @@ export class Executor {
 	}
 }
 
-function drain(executor: Executor, tokenizer: Tokenizer): { edits: Edit[]; warnings: string[] } {
+function drain(executor: Executor, tokenizer: Tokenizer): { edits: Edit[]; fileOp?: FileOp; warnings: string[] } {
 	for (const token of tokenizer.end()) executor.feed(token);
 	return executor.end();
 }
 
-export function parsePatch(diff: string): { edits: Edit[]; warnings: string[] } {
+export function parsePatch(diff: string): { edits: Edit[]; fileOp?: FileOp; warnings: string[] } {
 	const tokenizer = new Tokenizer();
 	const executor = new Executor();
 	for (const token of tokenizer.feed(diff)) executor.feed(token);
 	return drain(executor, tokenizer);
 }
 
-export function parsePatchStreaming(diff: string): { edits: Edit[]; warnings: string[] } {
+export function parsePatchStreaming(diff: string): { edits: Edit[]; fileOp?: FileOp; warnings: string[] } {
 	const tokenizer = new Tokenizer();
 	const executor = new Executor();
 	for (const token of tokenizer.feed(diff)) executor.feed(token);

package/src/patcher.ts

@@ -39,7 +39,7 @@ import { MismatchError } from "./mismatch";
 import { detectLineEnding, type LineEnding, normalizeToLF, restoreLineEndings, stripBom } from "./normalize";
 import { Recovery, type RecoveryResult } from "./recovery";
 import type { SnapshotStore } from "./snapshots";
-import type { ApplyResult, BlockResolution, BlockResolver, Edit } from "./types";
+import type { ApplyResult, BlockResolution, BlockResolver, Edit, FileOp } from "./types";
 
 export interface PatcherOptions {
 	/** Storage backend used for all reads and writes. */
@@ -60,8 +60,8 @@ export interface PatchSectionResult {
 	path: string;
 	/** Filesystem-canonical key for this section (e.g. absolute path). */
 	canonicalPath: string;
-	/** `"noop"` when the apply produced no change; otherwise `"create"` / `"update"`. */
-	op: "create" | "update" | "noop";
+	/** `"noop"` when the apply produced no change; `"delete"` removes the file; otherwise `"create"` / `"update"`. */
+	op: "create" | "update" | "delete" | "noop";
 	/** Pre-edit text (LF-normalized, BOM-stripped). */
 	before: string;
 	/** Post-edit text (LF-normalized, BOM-stripped). For `"noop"` equals `before`. */
@@ -78,6 +78,8 @@ export interface PatchSectionResult {
 	firstChangedLine?: number;
 	/** Warnings collected by the parser, applier, and (optionally) recovery. */
 	warnings: string[];
+	/** Destination path when this section includes `MV DEST`. */
+	moveDest?: string;
 	/**
 	 * Resolved spans for any `replace_block`/`delete_block` ops, present when the
 	 * apply matched the tagged content. Undefined for patches with no block ops
@@ -107,11 +109,12 @@ export class PreparedSection {
 		readonly normalized: string,
 		readonly applyResult: ApplyResult,
 		readonly parseWarnings: readonly string[],
+		readonly fileOp: FileOp | undefined,
 	) {}
 
-	/** Convenience: returns true when the apply produced no change. */
+	/** Convenience: returns true when the apply produced no change and no file op. */
 	get isNoop(): boolean {
-		return this.applyResult.text === this.normalized;
+		return this.fileOp === undefined && this.applyResult.text === this.normalized;
 	}
 }
 
@@ -251,18 +254,22 @@ export class Patcher {
 	 * tag mismatch ({@link MismatchError}).
 	 */
 	async prepare(section: PatchSection): Promise<PreparedSection> {
-		const parseWarnings = [...section.parse().warnings];
+		const parsed = section.parse();
+		const parseWarnings = [...parsed.warnings];
+		const fileOp = parsed.fileOp;
 		assertSectionHashPresent(section.path, section.fileHash);
 
 		let target = section;
 		let canonicalPath = this.fs.canonicalPath(target.path);
-		await this.fs.preflightWrite(target.path);
 		let read = await this.#tryRead(target.path);
 
 		// Path recovery: the authored path doesn't exist on disk, but its
 		// filename + snapshot tag may name a file the model read this session
 		// (it supplied a bare filename, or the wrong directory). Rebind to that
-		// file so the edit lands where the tag points, and warn.
+		// file so the edit lands where the tag points, and warn. This runs
+		// before the write gate so a recoverable bare/mis-typed path is rebound
+		// to its real (writable) location instead of being rejected against the
+		// literal — possibly read-only — path it was authored as.
 		if (!read.exists) {
 			const recovered = this.#recoverSectionPathFromTag(target, canonicalPath);
 			if (recovered && this.fs.allowTagPathRecovery(target.path, recovered.section.path)) {
@@ -271,25 +278,43 @@ export class Patcher {
 				);
 				target = recovered.section;
 				canonicalPath = recovered.canonicalPath;
-				await this.fs.preflightWrite(target.path);
 				read = await this.#tryRead(target.path);
 			}
 		}
+
+		// Gate the final (possibly recovered) target before any write work, so
+		// an unrecoverable read-only target (e.g. a plan-mode working-tree path)
+		// fails with the write guard rather than a misleading "file not found".
+		await this.fs.preflightWrite(target.path, { fileOp });
+
 		if (!read.exists) {
 			throw new Error(`File not found: ${target.path}. Use the write tool to create new files.`);
 		}
 
+		if (fileOp?.kind === "move" && this.fs.canonicalPath(fileOp.dest) === canonicalPath) {
+			throw new Error(`MV destination is the same as ${target.path}.`);
+		}
+
 		const { bom, text } = stripBom(read.rawContent);
 		const lineEnding = detectLineEnding(text);
 		const normalized = normalizeToLF(text);
 
-		const applyResult = this.#applyWithRecovery({
-			section: target,
-			canonicalPath,
-			exists: read.exists,
-			normalized,
-			edits: target.parse().edits,
-		});
+		const applyResult =
+			fileOp?.kind === "rem"
+				? this.#applyWithRecovery({
+						section: target,
+						canonicalPath,
+						exists: read.exists,
+						normalized,
+						edits: [],
+					})
+				: this.#applyWithRecovery({
+						section: target,
+						canonicalPath,
+						exists: read.exists,
+						normalized,
+						edits: parsed.edits,
+					});
 
 		return new PreparedSection(
 			target,
@@ -301,6 +326,7 @@ export class Patcher {
 			normalized,
 			applyResult,
 			parseWarnings,
+			fileOp,
 		);
 	}
 
@@ -343,11 +369,31 @@ export class Patcher {
 	 * filesystem-canonical path.
 	 */
 	async commit(prepared: PreparedSection): Promise<PatchSectionResult> {
-		const { section, normalized, bom, lineEnding, parseWarnings, exists, applyResult, canonicalPath } = prepared;
+		const { section, normalized, bom, lineEnding, parseWarnings, exists, applyResult, canonicalPath, fileOp } =
+			prepared;
 		const after = applyResult.text;
 		const warnings = mergeWarnings(parseWarnings, applyResult.warnings);
+		const moveDest = fileOp?.kind === "move" ? fileOp.dest : undefined;
+		const resultPath = moveDest ?? section.path;
 
-		if (after === normalized) {
+		if (fileOp?.kind === "rem") {
+			await this.fs.delete(section.path);
+			this.snapshots.invalidate(canonicalPath);
+			return {
+				path: section.path,
+				canonicalPath,
+				op: "delete",
+				before: normalized,
+				after: normalized,
+				persisted: prepared.rawContent,
+				written: prepared.rawContent,
+				fileHash: computeFileHash(normalized),
+				header: formatHashlineHeader(section.path, computeFileHash(normalized)),
+				warnings,
+			};
+		}
+
+		if (after === normalized && moveDest === undefined) {
 			const hash = this.#recordFullSnapshot(canonicalPath, normalized);
 			return {
 				path: section.path,
@@ -364,6 +410,29 @@ export class Patcher {
 		}
 
 		const persisted = bom + restoreLineEndings(after, lineEnding);
+
+		if (moveDest !== undefined) {
+			const destCanonical = this.fs.canonicalPath(moveDest);
+			this.snapshots.relocate(canonicalPath, destCanonical);
+			await this.fs.move(section.path, moveDest, persisted);
+			const fileHash = this.#recordFullSnapshot(destCanonical, after);
+			return {
+				path: resultPath,
+				canonicalPath: destCanonical,
+				op: "update",
+				before: normalized,
+				after,
+				persisted,
+				written: persisted,
+				fileHash,
+				header: formatHashlineHeader(moveDest, fileHash),
+				firstChangedLine: applyResult.firstChangedLine,
+				blockResolutions: applyResult.blockResolutions,
+				moveDest,
+				warnings,
+			};
+		}
+
 		const write: WriteResult = await this.fs.writeText(section.path, persisted);
 		const fileHash = this.#recordFullSnapshot(canonicalPath, after);
 		const op = exists ? "update" : "create";

package/src/prompt.md

@@ -13,6 +13,8 @@ Every file section starts with `[PATH#TAG]`. `TAG` = 4-hex snapshot tag from you
 `INS.POST N:` — insert the body rows immediately after line N.
 `INS.BLK.POST N:` — insert the body rows after the END of the block that BEGINS on line N — outside it, at sibling depth. To append inside a block, use `INS.POST`.
 `INS.HEAD:` / `INS.TAIL:` — insert the body rows at the very start / end of the file.
+`REM` — delete the whole file named by the section header. No body, no line ops.
+`MV DEST` — move/rename the section file to `DEST` (a path, quoted when it contains spaces). Line edits above `MV` land on the source first, then the final content is written at `DEST`.
 Single line: `SWAP N.=N:` / `DEL N`. The range is the ORIGINAL lines you touch; body length is irrelevant (replacing 1 line with 10 is still `SWAP N.=N:`).
 </ops>
 
@@ -34,6 +36,7 @@ Body rows appear only under a `:` header. Every body row is `+TEXT` — add a li
 - Whole construct → `SWAP.BLK N` (tree-sitter resolves the end); lines inside it → `SWAP N.=M`.
 - `SWAP.BLK N` resolves EXACTLY the node at N. Leading decorators/attributes/doc-comments are separate nodes: point N at the FIRST decorator to sweep both; standalone line-comments are never swept — use `SWAP N.=M`.
 - Block ops (`SWAP.BLK`/`DEL.BLK`/`INS.BLK.POST`) anchor the OPENING line of a MULTI-LINE construct — never its closer, last line, or a bare inner statement. Anchoring one statement resolves to ONE line and is REJECTED: use the plain op (`SWAP N.=N` / `DEL N` / `INS.POST N`), or point N at the real opener. Saw the closer? Use plain `INS.POST M:`.
+- Markdown: a heading line IS a block opener — `SWAP.BLK`/`DEL.BLK`/`INS.BLK.POST` on a `##`/`###` heading resolves its WHOLE section (heading through every nested deeper heading, up to the next same-or-higher heading). So `DEL.BLK` drops the section, `SWAP.BLK` rewrites it, `INS.BLK.POST` lands after it (end the inserted body with a blank line to keep the next heading separated).
 - Non-adjacent changes = separate hunks; untouched lines stay out of every range.
 - Pure additions use `INS.PRE` / `INS.POST` / `INS.HEAD` / `INS.TAIL`, never a widened `SWAP` — retyped keepers are exactly what gets dropped. (A multi-line `SWAP` whose body restates the line just past the range is auto-dropped as an off-by-one keeper with a warning — issue the payload for the range only; never lean on the repair.)
 - NEVER format/restyle code with this tool; run the project formatter instead.
@@ -70,6 +73,27 @@ Delete line 3:
 DEL 3
 ```
 
+Delete the whole file:
+```
+[greet.py#A1B2]
+REM
+```
+
+Rename or move the file:
+```
+[greet.py#A1B2]
+MV greet_v2.py
+```
+
+Move after editing:
+```
+[greet.py#A1B2]
+SWAP 1.=3:
++def greet(name):
++    print(f"Hi, {name}")
+MV lib/greet.py
+```
+
 Add a header and trailer:
 ```
 [greet.py#A1B2]

package/src/snapshots.ts

@@ -90,6 +90,13 @@ export abstract class SnapshotStore {
 	/** Drop the version history for a single path. */
 	abstract invalidate(path: string): void;
 
+	/**
+	 * Move retained version history (and read provenance) from `from` to `to`.
+	 * No-op when `from` has no history. Used by file moves so tags minted from
+	 * reads of the source path stay valid at the destination.
+	 */
+	abstract relocate(from: string, to: string): void;
+
 	/** Drop every version history. */
 	abstract clear(): void;
 }
@@ -197,6 +204,26 @@ export class InMemorySnapshotStore extends SnapshotStore {
 		this.#versions.delete(path);
 	}
 
+	relocate(from: string, to: string): void {
+		const sourceHistory = this.#versions.get(from);
+		if (sourceHistory === undefined || sourceHistory.length === 0) return;
+		const relocated = sourceHistory.map(version => ({ ...version, path: to }));
+		const destHistory = this.#versions.get(to);
+		if (destHistory === undefined) {
+			this.#versions.set(to, relocated);
+		} else {
+			const seen = new Set<string>();
+			const merged: Snapshot[] = [];
+			for (const version of [...relocated, ...destHistory]) {
+				if (seen.has(version.hash)) continue;
+				seen.add(version.hash);
+				merged.push(version);
+			}
+			this.#versions.set(to, merged.slice(0, this.#maxVersionsPerPath));
+		}
+		this.#versions.delete(from);
+	}
+
 	clear(): void {
 		this.#versions.clear();
 	}

package/src/tokenizer.ts

@@ -23,7 +23,9 @@ import {
 	HL_INSERT_HEAD,
 	HL_INSERT_KEYWORD,
 	HL_INSERT_TAIL,
+	HL_MOVE_KEYWORD,
 	HL_PAYLOAD_REPLACE,
+	HL_REM_KEYWORD,
 	HL_REPLACE_BLOCK_KEYWORD,
 	HL_REPLACE_KEYWORD,
 } from "./format";
@@ -212,6 +214,8 @@ export type BlockTarget =
 	| { kind: "insert_before"; anchor: Anchor }
 	| { kind: "insert_after"; anchor: Anchor }
 	| { kind: "insert_after_block"; anchor: Anchor }
+	| { kind: "rem" }
+	| { kind: "move"; dest: string }
 	| { kind: "bof" }
 	| { kind: "eof" };
 
@@ -259,9 +263,54 @@ function scanInsertTarget(line: string, index: number, end: number): TargetScan
 	return null;
 }
 
+function unquotePath(pathText: string): string {
+	if (pathText.length < 2) return pathText;
+	const first = pathText[0];
+	const last = pathText[pathText.length - 1];
+	if ((first === '"' || first === "'") && first === last) return pathText.slice(1, -1);
+	return pathText;
+}
+
+function scanMoveDest(line: string, index: number, end: number): string | null {
+	const cursor = skipWhitespace(line, index, end);
+	if (cursor >= end) return null;
+	const first = line.charCodeAt(cursor);
+	if (first === 34 /* " */ || first === 39 /* ' */) {
+		const quote = line[cursor];
+		let next = cursor + 1;
+		while (next < end) {
+			const ch = line[next];
+			if (ch === "\\" && next + 1 < end) {
+				next += 2;
+				continue;
+			}
+			if (ch === quote) {
+				const after = skipWhitespace(line, next + 1, end);
+				return after === end ? unquotePath(line.slice(cursor, next + 1)) : null;
+			}
+			next++;
+		}
+		return null;
+	}
+	return unquotePath(line.slice(cursor, end).trim());
+}
+
 function scanHunkAnchor(line: string, start: number, end: number): TargetScan | null {
 	const cursor = skipWhitespace(line, start, end);
 
+	const remEnd = scanKeyword(line, cursor, end, HL_REM_KEYWORD);
+	if (remEnd !== null) {
+		const next = skipWhitespace(line, remEnd, end);
+		if (next !== end) return null;
+		return { target: { kind: "rem" }, nextIndex: next };
+	}
+	const moveEnd = scanKeyword(line, cursor, end, HL_MOVE_KEYWORD);
+	if (moveEnd !== null) {
+		const dest = scanMoveDest(line, moveEnd, end);
+		if (dest === null || dest.length === 0) return null;
+		return { target: { kind: "move", dest }, nextIndex: end };
+	}
+
 	// `replace_block N:` — resolve N to a tree-sitter block range at apply time.
 	const replaceBlockEnd = scanKeyword(line, cursor, end, HL_REPLACE_BLOCK_KEYWORD);
 	if (replaceBlockEnd !== null) {
@@ -406,7 +455,9 @@ function classifyLine(line: string, lineNum: number): Token {
 	const isHunkLead =
 		line.startsWith(HL_REPLACE_KEYWORD, lead) ||
 		line.startsWith(HL_DELETE_KEYWORD, lead) ||
-		line.startsWith(HL_INSERT_KEYWORD, lead);
+		line.startsWith(HL_INSERT_KEYWORD, lead) ||
+		line.startsWith(HL_REM_KEYWORD, lead) ||
+		line.startsWith(HL_MOVE_KEYWORD, lead);
 	if (isHunkLead) {
 		const hunk = tryParseHunkHeader(line);
 		if (hunk !== null) return { kind: "op-block", lineNum, target: hunk.target };

package/src/types.ts

@@ -61,6 +61,9 @@ export type Edit =
 			index: number;
 	  };
 
+/** File-level operation parsed from a section body (`REM` / `MV`). */
+export type FileOp = { kind: "rem" } | { kind: "move"; dest: string };
+
 /** Result of applying a parsed set of edits to a text body. */
 export interface ApplyResult {
 	/** Post-edit text body. */