Supported Behavior

This page answers what the backend reads, what it writes, and what it refuses.

ScopeCopy Anchor Link

• The backend is native Rust. It does not depend on an external Markdown toolchain or runtime.
• --project-path is the folder whose Markdown files are checked. It may be relative (.) and is resolved against the working directory. Without it, the files below the folder that all moved paths share are checked.
• Files and folders are found with the ignore rules of the project. .gitignore and .ignore files inside the project path are read even where there is no git repository. Hidden folders such as .github/ and .agents/ are searched. .git/ and node_modules/ are never searched.

Incoming updatesCopy Anchor Link

When a path moves, every link to it is updated, wherever the link is written. The destination forms that are read:

• Inline links and images: [Guide](./guide.md) and ![Logo](img/logo.png), each with a #fragment, a ?query, or both.
• Reference definitions, including collapsed, shortcut, titled, angle-bracket, and multi-line ones, where the destination sits on the next line.
• Angle-bracket destinations with spaces: [a](<docs/My Notes.md>).
• Percent-encoded destinations: docs/My%20Notes.md is the file docs/My Notes.md.
• Raw HTML in Markdown: href, src, and poster values, and every URL in a srcset, for example <img src="docs/logo.png" width="64">.
• Links in table cells, list items, block quotes, link text that continues on the next line, and an image inside a link.
• Links to a folder (docs/), which follow the folder when it moves, and links to a file inside a moved folder.

Outgoing recalculationCopy Anchor Link

When the Markdown file moves, or sits inside a folder that moves, its own relative destinations are measured from the new place. A link that already says the right thing is not touched. Two files that move together keep their links byte for byte, even when a link was spelled oddly (x/../a.md).

How a link is writtenCopy Anchor Link

The rewrite changes the destination text and nothing else.

• The author's habits are kept. A ./ prefix is written only where the old path had one and the new path does not climb, so ../x never gets one. A trailing / on a folder link stays. A destination that was percent-encoded stays encoded. A space in an unwrapped destination is written as %20, and a destination in angle brackets keeps its space.
• Special characters are escaped. Characters that cannot stand in a destination (%, #, ?, brackets, quotes) are escaped, and balanced parentheses such as a_(b).md stay as they are.
• Anchors and queries survive. Fragments and queries are preserved when the path changes.
• Some destinations are never touched. Web addresses (https://, mailto:, and any other scheme), #anchors, site-root paths (/docs/a.md), paths with template syntax ({{ x }}, ${x}), and paths with an HTML entity are left unchanged.
• Everything around the destination stays. Line endings, a byte-order mark, and all text around a destination stay byte for byte.

Reference-style MarkdownCopy Anchor Link

Usage text such as [Text][id], [id][], or [id] is never renamed. The matching [id]: ... definition is updated, so those usages keep resolving.

Links to codeCopy Anchor Link

After a TypeScript, Python, Rust, Go, Dart, or Kotlin move, one pass over the Markdown files of the project fixes the links to what moved, files and folders alike. A link is only changed when its old target is gone and the new one exists, so a half-moved folder never sends a link to a file that was not moved.

The response gets a section // Markdown links to the moved files: with the number of files checked and links changed. If this pass fails, the command fails with an error that says the files were moved but the links were not updated.

SafetyCopy Anchor Link

• The whole change is planned before the disk is touched: the moves first, then the rewritten Markdown. Any failure undoes everything in reverse order, with written files restored and moved files moved back. The error says whether the rollback was complete, and a failed move inshallah won't leave links pointing nowhere.
• Refused before anything changes: a missing source, an existing target, a Markdown file moved to a name that is not Markdown (and the reverse), a folder moved into itself, two moves that overlap, and a folder that holds code.
• Markdown files that are not valid UTF-8 are not read and not changed. The response names them so you can check them by hand.

OutputCopy Anchor Link

The response lists each moved path, then a note such as Checked 2 Markdown files; updated 4 links in 2 files. With --dry-run it lists the moves and the edits per file, and changes nothing.