When a document moves
Renaming a document keeps its old address working. Moving it to another folder does not. That is inconsistent, it is deliberate, and you will meet it — so it is written down here rather than left to be discovered.
The two rules
- Change a document's name inside its folder and the old address still resolves. It redirects to the new one.
- Change which folder it is in and the old address is not found.
A document keeps its identity either way. The id in its front matter, its
creation time, and its body all survive — it is the same document in a different
place, recorded as one git commit and as a rename, so git log --follow keeps
working across it.
Why they differ
Renaming keeps an alias in the document's front matter, so the old name stays resolvable. Doing the same for folders would mean a large reorganisation accumulating aliases indefinitely — every document carrying a growing list of places it used to be.
The cost of not doing it is real and lands exactly where it hurts most: a reorganisation invalidates saved links and any path an AI client has already retrieved, and reorganising is precisely when the most paths change at once.
Neither half of this is obviously right. What is certainly wrong is the pair, because nobody using the product can predict which rule applies. If it is revisited it should go one way or the other.
What this means in practice
Before a reorganisation, expect links to break. Documents that other documents link to are the ones to think about; a link inside a document body is just text and nothing rewrites it for you.
Tell your AI client to search rather than remember. A path a model retrieved
last week is a guess about the present. search_documents and list_documents
give current paths; a cached one does not. This is worth putting in the client's
instructions if you reorganise often.
A move is refused on a stale version, like every other write. If the document changed since you opened it, nothing happens and you are told.
Addresses, and why a folder never shadows a document
A document and a folder of the same name in the same place are both reachable,
each by an address that names it and nothing else — the document's address ends
in .md, the folder's does not. Nothing wins, and no page has to explain that
what you asked for was ambiguous.
The MCP surface splits them by the same rule, so a path a model reads from one surface and uses on the other behaves the same way.
Addresses are derived from the file rather than stored beside it, so they survive a projection rebuild.
Deleting, for comparison
Deleting a document removes it from the workspace, and its content stays in git history — annoying to retrieve, but there.
Deleting an uploaded file is different: it destroys the bytes, deliberately, because that is what makes an erasure request answerable. Its name and checksum remain in history; the file does not.
Next: getting your content out.