Skip to content

Latest commit

 

History

History
943 lines (865 loc) · 221 KB

CHANGELOG.md

File metadata and controls

943 lines (865 loc) · 221 KB

Changelog

v2.10.0 - 2026-11-14

Added

  • Settings → Layout has a new Note width choice for how wide a note's text may run in the Reading view and the editor, for everyone using the server: Default (today's width, about 80 characters a line), Wide (about 100) or Full (the whole pane). Each is an upper limit, so a screen narrower than it looks the same with all three, and phones are unchanged. Source keeps its own wider column unless Full is picked, and Help's manual stays at the default width. A change shows the next time a note is drawn, with no reload. In .env it is HATCHDOOR_NOTE_WIDTH=default|wide|full. #698
  • Settings has a new Layout section with two switches, Show Changed on disk and Show Recently viewed, both on by default. Turning one off removes that list from the sidebar, the phone's drawer and Home for everyone using the server; turning it back on brings it back up to date. In .env they are HATCHDOOR_SIDEBAR_CHANGED_ON_DISK and HATCHDOOR_SIDEBAR_RECENTLY_VIEWED. #684
  • Highlights can now be coloured the Obsidian way: ==🔴text==, with one of 🔴 🟠 🟡 🟢 🔵 🟣 straight after the opening signs, is drawn red, orange, yellow, green, blue or purple in the Reading view, the source-mode preview, Help and the editor, with the emoji hidden; the editor shows it while the cursor is on that line. The emoji stays in the file, any other character is ordinary text, a highlight without one looks as before, and search snippets drop the emoji with the signs. The Highlight button still writes a plain highlight. #577
  • A note embedded in another note, ![[Other note]], now shows that note's content in the Reading view and the source-mode preview, inside a frame that names the note and links to it. ![[Other note#Heading]] shows that heading's section and ![[Other note#^id]] the one block that carries ^id. Embeds inside an embedded note show too, up to three levels deep; an embed of a note that does not exist, of a missing heading or block, of a note it is already inside, or a fourth level down shows the plain link it showed before. The live editor still shows the ![[...]] text, and agents still read the file as written. #699
  • Obsidian canvases (.canvas files) now survive a rename, and you can see them. Renaming, moving or archiving a note or an attachment, in the Web UI or through an agent, changes the path on every canvas card that shows that file and leaves every other byte of the canvas as it was; a rename used to leave the card pointing at a file that no longer existed, which only showed up later in Obsidian. Deleting leaves the card alone, so Obsidian shows it as missing, and a canvas that is not valid JSON or is over 8 MB is left untouched and named in the result. The explorer lists each canvas in its folder and selecting it downloads the file, as does a link or embed of one in a note, and get_attachment can fetch one. Hatchdoor does not draw a canvas, search it or count its cards as links. #579
  • A link to a block, [[Note#^id]] or [text](Note.md#^id), now opens the note at the paragraph, list item, quote or table that carries ^id, in the Reading view, the source-mode preview and Help. It used to open the note at the top. This works from another note, from the same note and when the page is loaded at the link's address; a block id that no longer exists opens the note at the top. A heading and a block of the same name are two places. A ^id written inside a code block is now shown as written, where the Reading view used to delete it, and one on a line of its own under a quote or a table is hidden like the rest. #578
  • An agent can now read a note and edit it in one batch call. A write that passes "from_batch" as its expected_content_hash is checked against the hash an earlier get_note, get_note_outline, get_note_section or get_frontmatter item in the same batch returned for that note, where it used to take a second call to fetch the hash first. If the note changed in between, the write fails with write_conflict as before; "from_batch" with no earlier item for the note, or outside batch, fails with the new code batch_hash_unavailable and writes nothing. A real hash is still checked exactly as sent. #599
  • Agents can use find_link_problems to page through one Vault's broken or ambiguous note links, isolated notes and dead ends. The read-only lists carry no score and change nothing; each finding needs a judgement. #575
  • An agent that connects over MCP is now told to read the manual page How to work in a Vault as an agent before its first write, so it learns to search before creating a note, read a note before changing it and prefer small edits without you pointing it there. Connect your agent gains an example skill to copy into your agent's skills folder, which sends it to the same page on the Hatchdoor it is connected to. #568

Changed

  • Docker and Podman now run the same Hatchdoor image, so Podman users can use the plain latest and <version> tags like everyone else. The podman-latest and podman-<version> tags still move with every release, as a second name for the same image, until the third release after this one, and then stop: an install still on them should switch its image: line to the plain tag before then. The opt-in usage report still sends image: docker or image: podman, now read from the engine the container runs under. #705
  • The manual now says that deleting a note in a Git-backed Vault never removes it from the remote or its Git history, since Hatchdoor commits the delete as a move into .hatchdoor-trash, and that a note's address can change hands when another note with the same file name is added, moved, renamed or deleted. How to set up a Git-backed Vault, Understand where your data lives, Supported Markdown reference, the MCP and HTTP references and How to work in a Vault as an agent carry it, with the advice to keep file names unique when an address must stay put and, for agents, to find a stored slug again instead of trusting it. #704
  • The web token in an ?access_token= query parameter now works only where the browser cannot send a header: a GET of an attachment (/api/v1/vaults/{vault_id}/assets/...), a note download (/api/v1/vaults/{vault_id}/notes/{slug}/download) and the live update stream (/api/v1/vaults/events). Every other route, writes and POST /api/settings/web-token/reveal included, answers 401 to it, and the manual's private pages under /docs/ no longer show for it, so a link that leaks with the token in it can no longer change notes or reveal the token. A script that sends ?access_token= to any other route must send Authorization: Bearer <token> instead. Transfer links and the MCP token are not affected. #703
  • Hatchdoor can no longer be shown inside another page: a dashboard tile, a Home Assistant iframe panel or any site that puts it in a frame now gets an empty box or a "refused to connect" message, and has to link to it instead. Every response now carries X-Frame-Options: DENY and Content-Security-Policy: frame-ancestors 'none', so a malicious page cannot load Hatchdoor in a hidden frame and trick you into clicking its buttons. An SVG attachment keeps its sandbox policy alongside, and no other browser rule changes: the app, Mermaid, math and PDF previews load as before. #702
  • An agent can now add or move a Vault only to a folder inside the Vault mount (VAULT_PATH, /data/vault in the stock install). create_vault and edit_vault refuse any other folder on the server with vault_path_outside_mount, so a note carrying planted instructions cannot get an agent to open /etc or a home folder as a Vault. Symlinks and .. are resolved first. A Vault you added outside the mount from Settings keeps working for agents, and the web app can still add any folder Hatchdoor can read. Git-backed Vaults that Hatchdoor clones itself are not affected. #700
  • MCP agents on the 2026-07-28 revision now get a refused tool call, such as an unknown tool, a write while writes are off or an invalid argument, with HTTP 200 and the JSON-RPC error in the body, where it was HTTP 400; the error code and message are unchanged, so a client that reads the body sees no difference. An initialize that names 2026-07-28, a revision with no handshake, now opens a 2025-11-25 session, and that session no longer claims tools.listChanged: true, which only the modern revision can deliver. A request with no session that is not initialize is refused with 400 Bad Request: Session ID is required instead of 422 Unexpected message, expect initialize request. These come with the MCP library moving to 3.8.0. #621
  • Mermaid diagrams are drawn by Mermaid 12. Flowcharts, sequence, class, state, ER, Gantt, pie, mindmap, Git graph and timeline diagrams, math labels included, render as they did, and a broken diagram shows the same error. The web app's offline cache grows by about 250 KB. #621
  • The search index no longer stores a second, normalised copy of every note's title and path, each with its own index, that nothing has read since links stopped being resolved from the index. An existing index drops them at the first start after the upgrade, with no re-embedding, and an index written by 2.9.0 gets this and the keyword index change of #634 in the same conversion. #655

Fixed

  • In a long note, the editor now draws callouts, diagrams, saved queries, formulas, PDF previews and images near the end of the note as soon as it has read that far. They used to stay as plain text until you typed something. Shorter notes look as before. #783
  • A heading with a highlight in it, such as ## Plan for ==this week==, now shows in the note's "On this page" outline without the == signs, and without the colour emoji when the highlight opens with one, the way the outline already drops * and _. A == inside backticks, math or a bare web address stays, in the outline and now also in search snippets and Help search excerpts, and links to the heading land where they did. #782
  • An agent that connects after search model setup failed, on an instance whose model was chosen earlier, now opens its session with the normal instructions, led by a line saying setup failed, that note tools are refused until Retry setup in the web app, and that get_model_setup_status gives the reason. It used to be told to accept or decline the Gemma terms, which would switch the instance to the other model, and kept that advice for the whole session. An instance with no model chosen yet still gets the first-run instructions. #779
  • When search model setup fails on an instance whose model was chosen earlier, an agent's tool call is now told that setup failed, to read get_model_setup_status for the reason and to have Retry setup pressed in the web app's search, which keeps the chosen model. It used to be told to accept or decline the Gemma terms, and doing so replaced the saved choice and switched the instance to the other model. An instance with no model chosen yet still asks for the choice. #775
  • An agent that connects right after a restart, while Hatchdoor checks and loads a search model chosen earlier, now opens its session with the normal instructions, led by a line saying the model is loading and note tools ask to retry until it has. It used to be told to complete first-run setup and accept or decline the Gemma terms, and kept that for the whole session. An instance with no model chosen yet still gets the first-run instructions. #774
  • In the few seconds after a restart while Hatchdoor checks and loads its search model, an agent's tool call is now told the model is downloading or loading and to retry in a moment. It used to be told to accept or decline the Gemma terms, even on an instance set up long ago, and those tools then answered that a model was already set up. An instance with no model chosen yet still asks for the choice. #762
  • A PDF embed with a page anchor, such as ![[report.pdf#page=2]], now shows its preview and opens on an instance with a web token. The token was added after the #page=2, a part of the address the browser never sends, so the PDF answered 401; it now goes before it, and the Open link lands on that page. #755
  • A Vault added on a folder inside or around the folder of a Vault you just paused and disconnected no longer writes beside a sync the old Vault was still running there. Only a Vault on the very same folder used to wait; one on a subfolder, or on a parent folder holding one or more such Vaults, got a write lock of its own and could change files in the middle of the old sync. It now waits for every old sync on an overlapping folder to finish. A Vault added on an unrelated folder still starts at once. #745
  • A Markdown link that a move rewrites now spells the extension the linked file has. A link written [deep](../../Sub/Deep.MD) used to come out as [deep](../Sub/Deep.md) once its note moved, which Hatchdoor still followed but a tool that matches file names exactly might not; it now comes out as [deep](../Sub/Deep.MD). Moving or renaming the .MD note itself writes the extension of its new file into the links that point to it. #740
  • Moving or renaming an attachment no longer hangs when a sync tool or another program replaces the file with a pipe at the moment Hatchdoor reads it back, which blocked every other write to that Vault until something wrote to the pipe; the move is now refused at once, the notes that link to the attachment are put back as they were, and the error says the attachment itself could not be restored, since the other program replaced it. Hatchdoor no longer follows a symbolic link when it reads an attachment's size and hash, so a link swapped in to point at a device can no longer be read without end, and list_note_attachments now leaves out a reference to a symbolic link where it used to list the file the link pointed to. #736
  • An agent that calls a tool Hatchdoor does not have, such as a misspelt name, now gets the "Unknown MCP tool" error at every moment. In the few seconds after a restart while the search model loads, it used to be told instead that Hatchdoor was still being set up and to accept the Gemma terms, even on an instance set up long ago. #733
  • Opening a folder in the folder picker, in Add a Vault or the first-run checklist, now moves keyboard focus straight to the new level's "Use" row. It used to get there a moment after the new folder was drawn, with focus on the page itself in between. #728
  • A link to a heading or block in the note it is written in, [[#Heading]] or [[#^id]], now works in the Reading view, the source-mode preview and the editor: it shows the heading's name, or its alias, and jumps to that place in the note. It used to show as a missing link. #727
  • Deleting, moving or archiving a note at the top of the Vault no longer takes along attachments that other notes still show. Such a note has the whole Vault as its folder, so every attachment it embedded by path went with it, from any folder: a delete put another note's picture in the trash and broke or repointed that note's embed, and a move copied a shared attachments folder into the destination. An attachment now goes with a top-level note only when no other note embeds or links to it, by path, by bare name such as ![[image.png]] or with a Markdown link. Notes in a folder keep the rule they had: attachments in their own folder go with them. #701
  • Coming back to a note you left while its save was still on its way no longer warns that the note has changed since. When you kept typing after that save went out and then opened another note, the newer edit was kept for your next visit but still marked as made against the version before your own save, so the note showed "An unsaved edit to this note is being held, but the note has changed since" and asked you to review it in Source. The newer edit now comes back as it was, with no warning; an edit held from another tab or an older version still gets the warning. #695
  • The startup warning about variables left in your .env no longer tells you to remove HATCHDOOR_GIT_AUTHOR_NAME and HATCHDOOR_GIT_AUTHOR_EMAIL. It said they had no effect, but they still sign the commits of every Vault that has no commit identity of its own, so removing them changed who signed those commits. The other HATCHDOOR_GIT_* variables and HATCHDOOR_EXCLUDE are still named. #687
  • A Vault added on the folder of a Vault you just paused and disconnected no longer writes beside a sync the old Vault was still running there. The new Vault got a write lock of its own at once, so its edits could land in the middle of the old sync or in its commit; it now waits for that sync to finish, as a Vault resumed during its Pause already did. A Vault added on another folder still starts at once. #681
  • A Local history Vault whose .git folder went missing no longer commits its notes into a Git repository further up, such as a home folder kept in Git. Hatchdoor used to search upward for a repository, so after a restore without .git, or with the Vault inside another checkout, the next commit landed in that other repository's history and reported success. It now commits only into the Vault's own repository; when that is gone it commits nothing and reports the new existing_git_local_history_repository_missing, which is not retried. #678
  • One folder Hatchdoor may not open, such as a .trash/private or lost+found with no permissions, no longer stops the once-a-minute folder re-scan from noticing changes. Every round used to fail with a warning, so on a folder that sends no change events, such as a Windows folder shared through Docker Desktop, edits made outside Hatchdoor never reached the index; the re-scan now skips that folder, as indexing already does, and a passing read error on a network share still makes it try again next minute. #674
  • The README's Quick Start now prepares data/cache and models for Hatchdoor's user along with data/state, as the manual's install guide already did, so following it no longer leaves a first start unable to open its cache. Contributors get just smoke-install, which runs those steps with an image built from their checkout and is now on the release checklist. #569
  • Following a link right after typing no longer stops the next note from saving. The save of the note you left, still on its way, was booked against the note you opened: once it came back, the next note's edits were refused with "Edits aren't saving. This note changed somewhere else." although nothing had changed, and an edit made in the next note before it came back could be written into the note you left. Each note now saves on its own, and the note you left still gets its save, or keeps its unsaved edit for your next visit when the save is refused. #658
  • The Graph page now works from the keyboard and with a screen reader. Tab reaches the graph, which a screen reader names "Note graph"; the arrow keys step through the notes by title, Home and End jump to the first and last, Enter opens the selected note and Escape clears the selection. A note out of view is brought to the middle of the screen, and the selected title is read out. Rename, Move, Archive, Delete and New note now put focus back on the button that opened them when they close, where it used to drop to the top of the page. The browser bar colour and the installed app's splash screen now follow the theme colours themselves instead of a copy of them. #648
  • Note downloads and attachments answer properly in three cases that used to give 500 internal_error. A note whose zip, with its images and PDFs, passed the 64 MiB download limit now answers 413 note_export_too_large, as documented, instead of a 500 and an error in the server log. A downloaded note, and the files inside its zip, keep their names in Greek, Chinese, Arabic or any other script, and accented letters such as ß, where every non-ASCII letter used to become -, so 中文笔记 downloaded as ----.md. An attachment path no file can have, such as one with a NUL byte or a name too long for the filesystem, now answers 400 invalid_asset_path, and a path running through a file, such as a mistyped embed note.md/x.png, 404 asset_not_found, on the asset route, get_attachment and download links alike, where each logged a server error on every view. #647
  • An open tab now keeps following Vault changes after the server restarts behind a reverse proxy. A proxy's 502 or 503 while Hatchdoor was down, or a 401 after the web token changed, closed the tab's update stream for good, so the explorer and graph stopped showing Vaults added, paused, renamed or disconnected until a reload; the tab now reopens it, waiting 1 second and doubling up to 30 seconds, reads the Vault list again whenever it reconnects, comes back to the tab or comes back online, and a 401 brings up the token prompt. A Vault renamed or paused and resumed in quick succession could also show its old name, or vanish, until the next change, because an older list answer arriving last replaced a newer one; older answers are now dropped. #646
  • The Settings page no longer loses edits or reports the wrong thing after an action. Generate then Discard on the MCP password used to leave the discarded password in the field as if it were the saved one; the field now goes back to the saved password, masked, or empty when none is saved. After a Vault's Git setup was changed, or a change was rolled back, the next Save was refused as "changed elsewhere"; it now goes through. A Vault disconnected from another tab or by an agent now shows as disconnected, with no Save, instead of staying on screen and refusing each Save. Pause, Resume and Rebuild search index keep the fields you are typing in, each says what it did instead of "Saved.", and the message no longer follows you to the next Vault. A failed Try again on a Vault in the Settings list now shows the reason. #645
  • Saving a retired setting no longer stops Hatchdoor from starting. PATCH /api/settings accepted HATCHDOOR_GIT_SYNC_ENABLED and HATCHDOOR_EXCLUDE although nothing reads them, and the next start exited on a value it rejected, such as remote with no Git token or an invalid exclusion pattern; HATCHDOOR_GIT_SYNC_ENABLED=true in .env did the same, before the warning that the variable does nothing was logged. A save of HATCHDOOR_EXCLUDE or any retired HATCHDOOR_GIT_* key is now refused with 400 and a field error naming it as retired, startup no longer reads them, the .env warning is logged before any other startup check, and every start names any the settings file still holds, ahead of every other startup check, and removes them, so an instance that already saved one starts again after the upgrade. #644
  • Hatchdoor now checks every search model file against a SHA-256 it ships, before every load, and loads Nomic Embed Text v1.5 from one fixed revision. A model file changed on disk, by a sync tool, a restore or a hand edit, used to be loaded and then trusted from then on, and Nomic followed whatever Hugging Face published next; such a file is now removed and fetched again before anything loads it. A Docker setup with HF_HOME in its .env no longer fails setup on every start: Hatchdoor ignores HF_HOME, says so in the log, and keeps its models in the models folder. A damaged selection.json or Gemma terms receipt, as a power cut could leave, no longer stops the server; Hatchdoor asks for the model choice again, and these records now reach the disk before setup moves on. A cached model now loads on a volume with less than 512 MB free; the free-space check applies only when a download is needed. Each model's revision is now part of what the search index records, and an upgrade keeps the index and its vectors when the model files on disk already match the pinned revision; the index is rebuilt only when a model file had to be fetched again at that start. #643 #693
  • A model download that stops receiving data no longer leaves first-run setup stuck until a restart. Behind a captive portal, a dropped connection or a hung proxy, setup used to stay on downloading for ever while Accept, Decline and Retry setup all answered 409 and /ready stayed 503. A download that receives nothing for 60 seconds, or runs past two hours, is now stopped, setup turns failed with a message saying the download stalled, and Retry setup or POST /api/model/retry starts it again, continuing the files already fetched. Nomic now shows download progress like Gemma, GET /api/startup-status and get_model_setup_status add step, download then load, so a slow load reads differently from a stuck download, and HF_ENDPOINT now applies to the Gemma download too. The setup screen and Retry setup now show why a request was refused, or that Hatchdoor could not be reached, where they used to do nothing. #642
  • A Vault on a folder you provide, plain or an existing Git checkout, now follows that folder while Hatchdoor runs. A folder missing at startup that appeared later got indexed and served while the Vault still said unavailable, refused writes and never noticed a later change; a folder made read-only kept saying read_write and failed each create with 500 internal_error, and one made writable again stayed read-only. Hatchdoor now looks at each such folder every minute and whenever it notices a change there, so within a minute the Vault turns active with its watcher and first index, unavailable, read_only or read_write as the folder now stands. An unavailable Vault is never indexed, reports search: unavailable and serves no note, listing or search result, even from an index built before its folder went away. Try again now appears on the Vault's Settings page and retry_vault and POST /api/v1/vaults/{id}/retry work for such a Vault, where they answered 409: they look at the folder at once and answer vault_unavailable with the reason if it still cannot be read. refresh_vault looks first too. #641
  • Pausing, editing or disconnecting a Vault while it indexes now answers in seconds, and so does stopping the server. A running index used to finish its whole embedding pass first, so Pause and rename timed out at 30 seconds while the page already showed the change, and an upgrade during a first index ran out Docker's 3-minute grace period and was killed. It now stops at the next chunk and resumes from its saved progress. Resuming a Vault while its Pause still waited for a sync no longer lets a write slip past that sync and land in its commit as hatchdoor: vault update with no origin. A sync answered "queued", a pending commit or a recovery-branch request is no longer lost when the Vault is renamed or its settings are saved. A copy of the Vault list, Git tokens included, that a crash left in the state folder is now removed at the next start. #640
  • Changing a Vault's Git setup works again. A new repository URL, branch or folder on a managed checkout, even the same host spelled differently, left the Vault failing every sync with managed_git_validation_failed while it kept taking edits that never synced; the edit now commits the old checkout's pending notes, moves the checkout whole into vaults/<Vault ID>/retired-checkouts/ in the state folder, and the Vault clones the new remote when it starts back up. edit_vault and PATCH /api/v1/vaults/{id} report what was kept in a new retired_checkout field, and refuse with the new checkout_set_aside_failed when the old notes cannot be committed, leaving everything where it was. Choosing Local history for a plain folder, in Settings or when adding a Vault, was refused with "existing Git location must be a readable working checkout" although the confirmation promised a new .git folder; Hatchdoor now creates the repository there, with no commit. #639
  • Git sync no longer hammers a remote with a rejected token, leaks the token on a redirect, or stops on one oddly named file. An expired or revoked token was sent a dozen times per attempt and reported as "remote unreachable", then retried about every 75 seconds for ever, around 670 failed logins an hour; the token now goes out once per attempt, a 401 or 403 is reported as managed_git_authentication_failed, and Hatchdoor waits for a new token or Try again. A remote that redirected to another host received the token there; the token now goes only to the scheme, host and port in the Vault's repository URL. A branch the remote does not have, such as mian, downloaded the whole repository again every 75 seconds; it is now the new non-retryable managed_git_branch_not_found, and a branch name Git does not allow is refused when the Vault is saved. One file name that is not valid UTF-8 stopped every commit and sync without naming the file; everything else now commits and syncs, and the new managed_git_unsupported_file_names (existing_git_local_history_unsupported_file_names for Local history) lists the files left out. SECURITY.md now says where to watch for sync failures and that anyone who can manage Vaults can make the server connect to any host, LAN addresses included. #638
  • One odd file or folder no longer hides notes or takes a Vault offline. A folder Hatchdoor cannot open, such as a root-owned lost+found, even inside .trash/, used to refuse every read and write in the Vault and stop its indexing; it is now skipped and logged. A note whose bytes are not valid UTF-8 now stays in the tree, search, graph and statistics, and find_text matches it, where it used to vanish while find_text reported nothing unread; opening it answers note_unreadable, not retryable, from every read, where get_note said to retry. Files whose names are not valid UTF-8 are left out with a warning instead of all showing as one Untitled note at the root that hid a real Untitled.md. A .MD or .Md file is now a note to reads and writes alike, and create_note and note uploads write Report.MD as named instead of Report.MD.md or Report.md. .git/ is now a built-in exclusion, so a Git-backed Vault's history no longer slows every read or serves its files as notes; !.git/ brings it back. #637
  • One huge note no longer crashes the server. Indexing read every note whole, so a 200 MB note in a Vault grew the server by 8 GB until the system killed it, and a 9 MB one held the Vault's search on the old note list for over 25 minutes. Indexing now leaves out the text of a note larger than 8 MiB without reading it, and skips a note that has become a pipe or device, logs either with the reason, and indexes the rest; the large note still shows in the explorer, get_note still answers note_too_large, and a note that grew past 8 MiB no longer turns up in search with its old text. An edit, move or delete of such a note is refused with invalid_write_input instead of reading it whole, and renaming, moving or deleting another note or an attachment, or renaming or deleting a tag, leaves it untouched instead of reading it to rewrite its links. #670
  • A write no longer hangs, or reads a huge file whole, when a sync tool or another program changes a note while Hatchdoor is writing it. A note turned into a pipe at that moment held the write, and every other write to the Vault, until something wrote into the pipe; it is now refused at once with invalid_write_input, and a note that grew past 8 MiB while a rename was rewriting its links fails that rename with write_conflict, undone, instead of being read whole. A note that turned into a pipe or device while the Vault was indexing no longer stays in search with its old text. #672
  • A Vault's files can no longer hang or exhaust the server. A .obsidian/app.json that a sync or Git pull turned into a pipe made every Vault listing hang, and one pointing at /dev/zero filled memory until the process was killed; Hatchdoor now reads that file only when it is a regular file of at most 64 KB, and reads anything else as Obsidian's default link style. A note larger than 8 MiB is refused with note_too_large (HTTP 413) by get_note, the note page, downloads, section, frontmatter and attachment reads and saved queries, where a 200 MB note used to produce a 1.2 GB reply. find_text lists such a note, or a note that has become a pipe since the last index, as unreadable instead of never answering. #636
  • A search hit's heading_path is now always a real heading of the note, so get_note_section finds it. A line of tags such as #meeting #acme, a # comment inside a ~~~ code block, or a # line inside a code block that shows another code block used to be taken for a heading, and a hit carried that text as its path; the search snippet also showed the code of a block with a shorter fence inside it as prose. Code in a full hit's content now keeps the fence the note used. The index re-chunks every note once at the first start after the upgrade, and embeds again only the chunks whose text or heading changed. #635
  • Keyword search now finds a Chinese, Japanese, Korean or Thai word inside a sentence. Those scripts have no spaces between words, so a search for 本文 or 中文 found nothing unless the word sat between punctuation. The index now stores each pair of neighbouring characters and searches a word as its pairs, a single character still finds every note holding it, and a Korean note saved in decomposed Unicode is found by a normally typed query. An existing index is converted at the first start after the upgrade from the text it already holds, in seconds, with no re-embedding. #634
  • Repeated-word keyword searches no longer stall other reads: queries are deduplicated and bounded, with a time limit on SQLite work. Oversized YAML frontmatter is rejected before parsing, BOM-prefixed notes expose their metadata and keep the marker through property edits, and damaged search caches are quarantined and rebuilt automatically at startup or during use. #633
  • MCP's limits now hold for every agent, and write refusals are readable. An agent on the older 2025-11-25 revision could run any number of searches at once, because its slot was freed as soon as the reply started; slots now stay taken until the reply ends. Opening sessions is limited: 60 handshakes a minute and 32 open sessions per MCP password, refused with 429 and Retry-After, and a session that sends nothing after its handshake closes within 45 seconds, where thousands could be opened, each holding memory for five minutes. A batch of base64 attachments no longer reads hundreds of megabytes before refusing the reply: each item has to fit in what is left of the reply's 8 MB, a base64 attachment that would not is refused with attachment_too_large_for_base64 before it is read, and any other read that would not fit fails with the new code batch_reply_too_large. A write to an unknown, paused or read-only Vault now returns the structured tool error read tools give, with code, retryable and a docs page, instead of a -32602 error whose message was JSON text. The base64 limit is now at most what one reply can carry, about 5.95 MiB, whatever HATCHDOOR_MCP_MAX_BASE64_BYTES says, for get_attachment and for import_attachment uploads alike, and get_attachment_import_config reports that number, so a larger download is refused with attachment_too_large_for_base64 instead of an unexplained error; download links still follow the setting. #632
  • A rename, move, archive or delete that Hatchdoor could not finish because it was stopped part-way is now finished the next time it starts. It used to leave the note under its new name with most backlinks still naming the old one, and nothing noticed. Hatchdoor now saves the plan of every change that rewrites several notes, tag renames and attachment moves included, before it starts, completes it at the next start, and logs any note edited in between instead of overwriting it. Temporary files a stopped save left beside notes are moved out of the Vault into the state folder at the same time, since one can hold an edit made in another editor. #631
  • A note's owner can still save it after Hatchdoor edits it. On Linux, with the deploy guide's setfacl setup, Hatchdoor's user cannot hand an edited note back to its owner, so the note came back belonging to Hatchdoor and its owner could only read it, or not even that for a private note. The edited note now keeps an access entry for its former owner and group with the rights they had, and keeps any access list the note already carried, through every later edit. A filesystem without access lists still takes the write. #661
  • Saving a note no longer changes who can read it. Every edit used to leave the note readable only by Hatchdoor's own user, so after an edit the note's owner, or anyone sharing the folder through the install guide's permission setup, could no longer open it; a note now keeps its permissions, and its owner where Hatchdoor runs as root. A write refused because the target is a symlink or a folder no longer leaves a hidden .hatchdoor-tmp copy of its content in the Vault, where Git committed it, and is now refused for good (invalid_write_input) instead of as a conflict worth retrying. A Vault whose folder is stored through a symlink, in a hand-edited or older registry, now takes writes instead of reporting itself writable and failing every one. Importing an attachment without overwrite no longer replaces a file of the same name that Obsidian or a sync tool created while the upload was being written; the import is refused as a conflict. #630
  • A Hatchdoor running with no web token on its own computer (HOST=127.0.0.1, the default outside Docker) no longer lets websites you visit read or change your Vaults. It used to answer any address, so a page that pointed its own domain at 127.0.0.1 could list Vaults, read and delete notes and change settings, and any page could upload an attachment or accept the search model's licence, starting a download of over 500 MB. Without a token it now answers only requests addressed to localhost, 127.0.0.1, [::1] or HATCHDOOR_PUBLIC_URL, and refuses changes sent from another website, with 403. Behind a proxy that forwards your own domain to a token-less loopback Hatchdoor, set HATCHDOOR_PUBLIC_URL or a web token. A first Docker start without a web token no longer prints the new token to the log, where it stayed in docker compose logs: it saves it in data/state/new-web-token.env, readable by its owner only, keeps the same token across Docker's restarts, and the install guide shows how to add it to .env. The web API and /mcp now accept the word Bearer in any case and followed by any number of spaces. #629
  • The note editor keeps your typing when a background refresh returns late, and its two-second autosave no longer gets cancelled by other page updates. "Saved" appears only once the current text has reached the Vault. An unrelated save no longer deletes a refused edit, older edits displaced by new typing remain under Settings, Unsaved drafts, and closing a tab with unsaved text asks for confirmation. Editor links open only web and email addresses. #628
  • The note editor no longer saves into a different note when a note with the same name is created in a folder that sorts earlier and takes over the open note's address. It used to write your typing into the new note while showing "Saved", or swap the new note's text onto the page. Now it stops saving, says the address opens a different note, keeps your edit, and offers to open the note at its new address, where the edit is saved. When a note is moved, renamed or deleted outside Hatchdoor and its address now opens another file, the editor stops and asks instead of switching to that file. The save request takes an optional expected_relative_path, refused with 409 note_moved when the address names another file. Unsaved edits are now kept per file rather than per address, so an edit held in your browser from before this update is listed under Settings, Unsaved drafts, instead of reopening on its own. #627
  • Wikilinks now reach the note their author meant. [[b/Plan]] opens b/Plan instead of the first Plan in the Vault, a link whose capitals match a note's exactly beats one that matches with case ignored, a link between two same-named notes picks the one nearest the linking note, and [[Meeting 2]] shows as a broken link when no such note exists instead of opening the second Meeting. Links typed on most keyboards now reach Korean or Japanese notes whose filenames a Mac stored in decomposed form. Renaming or deleting a note now changes only the links that clearly point at it: a link written for a same-named note elsewhere is left alone, a link the move would hand to a same-named note gets its folder path written in, other links keep their exact spacing, and a note that is not valid UTF-8 no longer blocks renames, moves and deletes of notes it does not link to. Korean and Japanese notes with decomposed filenames get a new address once, which breaks old bookmarks to them. #626
  • Section edits no longer mistake YAML comments for headings and erase the rest of a note, or refuse a body heading because a frontmatter comment has the same text. Section reads and writes also leave indented code inside its enclosing section instead of treating its # lines as headings. #625
  • Writes now check exclusion patterns against the filename they actually use, after converting backslashes to slashes and adding .md for notes. Alternate path spellings can no longer overwrite trashed notes, change Obsidian settings or move files into excluded folders. A note named x.tmp is allowed because its file is x.tmp.md, while Drawing.excalidraw is refused when *.excalidraw.md is excluded. #624
  • Libraries with published security advisories are updated. In the server: the Markdown parser used to split notes for search could take exponential time on some wikilinks, so a note could stall indexing; the TLS library behind the update check and model downloads, the HTTP/2 library and the archive library are updated too. In the web app: DOMPurify, which Mermaid uses to clean diagrams; pdf.js, past an advisory that let a crafted PDF run script when opened; and React Router. #621
  • A Git sync no longer destroys a note kept in a path your ignore rules cover. Hatchdoor writes notes in folders a .gitignore, .git/info/exclude or core.excludesFile ignores, and never commits them, so they exist only on that disk. When the remote then brought a file at the same path, or a plain file named like an ignored folder, or a folder named like an ignored file, the sync replaced or deleted the note and still reported the Vault as ready. The sync now stops before writing anything and reports a conflict that names the notes in the way, as it does for any other local edit the remote would overwrite. An ignored note the remote does not touch never blocks a sync, nor does a submodule the remote moves. The troubleshooting guide says how to clear this kind of conflict, which a recovery branch cannot. #623
  • A search result's snippet in the Web UI no longer shows code from a ~~~ block, or from a code block that shows another code block, as if it were text. It now drops every code block, backticks or tildes of any length, inside a list item or a callout too, and a code span written with three backticks shows its words. #668
  • A note whose file ends .MD or .Md is now treated like a .md one in three more places. A Markdown link written [text](Upper.MD) now counts as a link, so it shows in outgoing links and backlinks, the graph and the link checks, and a rename or move rewrites it, where it used to be ignored and left broken; the Web UI opens it as a note link too. In a Git-backed Vault such a note's created date now comes from the commit that added it instead of the file's modification time, and in queries and saved queries its file.name and file.path read Upper.MD, not Upper.md, while a saved query's link to it still reads Upper. A rename that only changes the extension's case, Draft.md to Draft.MD, is now noticed by the index too. #675

v2.9.0 - 2026-10-27

Added

  • A Git-backed Vault's history now says where each change came from. Every commit Hatchdoor names from its own writes ends with one Hatchdoor-Origin: line per origin: web for the web UI, mcp/<name> for an agent with the name its client gave, mcp for an agent that gave none, and unknown when the commit holds a file Hatchdoor has no record of writing, such as an edit made in Obsidian. An upload through an upload link counts as the write of the agent that asked for the link. The name is a label the client chooses, not proof of who wrote, and the client's version is not recorded. The first line of the message and its summary lines are unchanged, so anything that reads only those is unaffected; a script that compares the whole message will see the new lines. See "Where each change came from" in the Git-backed Vault guide. #570

Fixed

  • Hatchdoor's memory no longer grows with every index update. The search index filed each vector under its Vault's ID as text, and the vector library Hatchdoor uses never frees the memory it uses to write or delete such a value, so every index pass that changed something kept about 1.6 MB on a 5,000-chunk Vault, and a long-running container grew by around 0.6 GB a day until the system killed it. Vectors are now filed under a number. Upgrading keeps your existing index: once the embedding model has loaded, Hatchdoor migrates the index in place, checks the result, and re-indexes from your notes only if a check fails. #600
  • The Docker verification stage now includes the shared note-comment cases so the Rust link-preview test can compile against them. #596
  • A highlight now shows as one on the rendered page. The editor's Highlight button wraps text in ==, Obsidian's highlight syntax, and the editor draws it on a tint, but the note page printed the equals signs instead, and a read-only or demo Vault always opens on that page. The note page, the editor's preview and Help now draw ==text== with the editor's tint, and search snippets show the words without the signs. Equals signs in code, in math and in a comparison such as a == b stay as written. The Supported Markdown reference now lists highlights. #572
  • Search matches are readable in the dark theme, on the rendered note page and in the search dialog's results. The matched words were drawn in black on the dark yellow match colour; they now take the theme's text colour, as they already did in the editor. #605
  • A folder condition no longer picks up a note named after the folder. file.inFolder("Subscriptions") in a saved query, and a path_prefix of Subscriptions in query_notes and find_text, also returned a note Subscriptions.md sitting beside the folder; they now return only the notes inside it. #584
  • today() and now() in a saved query now follow the server's TZ setting. The Docker image runs on UTC, so for a reader east of UTC, today() named yesterday between their midnight and UTC's, and nothing said which zone applied. Set TZ, such as TZ=Europe/Paris, in .env. With TZ unset, a server run outside Docker now uses UTC too, instead of its host's zone. .env.example, docker-compose.yml and the Supported Markdown reference now show the setting. #584
  • An agent now gets the manual's page for a Git sync failure or a Vault folder Hatchdoor cannot open. 2.8.0 promised a docs pointer on these codes, but they never come back as a refused tool call: an agent meets them as a Vault's status in list_vaults, which carried no pointer. list_vaults now adds docs to each status error the manual explains, and the MCP tools reference says where docs appears. The HTTP Vault list is unchanged. #583
  • The web app's "Vaults Unavailable" screen now explains itself. Its Help link loads the manual from the server, which fails for the same reasons the screen appears, so a reader whose server was down only saw "The manual could not be loaded". The screen now says what the error means and what to try, with no network needed, and keeps the Help link for when the server is back. #583
  • Changed on disk and search no longer print a sentence with no Vault in it. When the only Vault short of fresh was a stale one, which still answered from its previous index, Changed on disk showed " did not answer." and search showed an empty red "Nothing Found" or a blank line under the results. Both now look as they do for a complete answer. A note opened from a search for its own title now lands on the first match you can see: the hidden copy of the title at the top of the body no longer counts as match 1. #585
  • create_upload_link now takes a commit_summary, like every other write tool. Uploading through a link, the recommended route for attachments and the only one for importing a Markdown file as a note, refused the argument, so the commit that recorded the upload had no line saying why the file was added. The summary given when the link is minted now reaches that commit, just as it does on import_attachment. It is held by the server, never put in the link. #598
  • A search match that makes up all the text of its piece of formatting, such as a heading that reads just Homelab, a bold or highlighted word, a link's text or a table cell holding only that word, is now highlighted on the note page when you arrive from a search. It was left unmarked, missing from the "Match N of M" count and never landed on, so a note whose only matches looked like that opened with no match navigator at all. #609
  • A search match on the note page is now marked on exactly the matched words when the text before it holds a letter such as the Turkish capital İ, which becomes two characters when lowercased. Each such letter shifted the mark one letter to the left, so a long note could mark the wrong words. #612

v2.8.2 - 2026-10-14

Fixed

  • The deploy page now tells an installing agent to read the whole page before it starts. The page is about 35 KB, and in a test install from its public address the agent printed only the first 30,000 bytes, never came back for the rest and so missed the last step, which tells it to show you the web token. A web-fetch tool can also return a summary with no commands in it. The agent part of the page now opens with that instruction: save the page to a file with curl and read the file to the end. #529
  • Transfer links no longer reach the logs under any RUST_LOG setting. Hatchdoor kept the MCP library's message logging off by naming three of its modules, so a RUST_LOG that named a deeper one, such as rmcp::transport::streamable_http_server::tower=trace, logged tool results with their download and upload links. Nothing the library logs below info gets through now, whatever RUST_LOG says. #587
  • Changing the MCP token now strands every transfer link. A tool call that arrived just before the change and finished just after got a link that worked under the new token. The link is now signed with the token the call came in on, so the new token refuses it. #587
  • A transfer link for a path spelled with ./, such as ./Media/a shot.png, now works. get_attachment and create_upload_link accept that spelling, but the link kept the ./, and curl removes it before sending the request, so Hatchdoor refused the link as invalid and told the agent to ask for a new one that failed the same way. Links now carry the path without . segments or doubled slashes, and an upload form that repeats the original spelling still matches. #586
  • What's new now shows every release since your browser last opened Hatchdoor. If the server moved from 2.8.0 to 2.9.0 to 2.10.0 while that browser stayed away, the pop-up listed 2.10.0 alone and marked it read, so 2.9.0's highlights, Action needed items included, never showed. Its Full changelog button also opens again on an instance with no web token, where Help used to say the page is only shown after signing in. #582
  • Settings now shows an on/off setting as On whenever Hatchdoor treats it as on. A value set in .env as 1, yes, on or TRUE turned the setting on but showed as Off, so HATCHDOOR_USAGE_REPORT_ENABLED=1 read Off above the install ID it had created. The settings response now sends every on/off setting as true or false, the value the server acts on. #581
  • The note page no longer shows a note's comments. Text between %% marks, which Obsidian shows only while you edit, and HTML comments <!-- --> both appeared in full on the rendered page, and a read-only or demo Vault always opens on that page, so its visitors read remarks the author meant to keep to themselves. The rendered page, the editor's preview and search result snippets now leave comments out, and a heading inside one stays out of the table of contents. The live editor still shows them. An embedded note, ![[Other note]], now shows as a link to that note instead of a broken image. Hiding is a display rule only: search and agents still read the comment. The Supported Markdown reference now lists the Obsidian syntax Hatchdoor does not handle. #573
  • Help hides comments too. A page in the manual, and a search excerpt in Help, showed %% and HTML comments that the note page hides, so the Markdown feature showcase's new comment example would have printed its comment there. Both now leave comments out, by the same rule as the note page. #573

v2.8.1 - 2026-10-11

Added

  • You can turn the optional usage report on straight from What's new. The pop-up you see after upgrading to 2.8.1 mentions the report a second time, and this time the line carries the switch itself, so saying yes takes one click and no trip to Settings. The switch is off unless you had already turned the report on, nothing changes until you click it, and a value set in .env shows as locked. The exact report is still shown in Settings under Usage report, and the line says so. This is the one release that repeats the question: 2.8.0 said What's new would mention the report once, so the manual's Usage report page now says what happens instead, and no later release asks again. Help and agents read the same line without a switch. ADR-48 records the change. #563

Fixed

  • An agent that installs Hatchdoor from the deploy page now always shows you the web token in its last message. In two test installs the agent ended by pointing to the .env file instead, which leaves a beginner without the password the browser asks for. The page's hand-over step now tells the agent to read the token and put it in that message. #529
  • The Docker and Podman images now describe themselves as a release in the usage report. The 2.8.0 images reported channel: dev and image: source, the values of a copy built from source, because the release build passed the Dockerfile neither VERSION nor HATCHDOOR_IMAGE. The 2.8.1 images report stable and docker or podman. Only installs that turned the usage report on sent the wrong values, and nothing else in the image differs. A published version is never rebuilt, so 2.8.0 stays as it is: upgrade to 2.8.1 for the correct report. #565

v2.8.0 - 2026-10-10

⚠️ Breaking changes — action required on upgrade

  • A fresh install now starts with no Vaults, and installs from 2.4.x or earlier can no longer upgrade directly. Hatchdoor no longer turns the folder VAULT_PATH names into a Vault by itself, whatever it holds: a start with no Vault registry writes an empty one and opens on No Vaults Yet, and every Vault is one you added in Settings, through POST /api/v1/vaults or with create_vault. Existing registries and their Vaults start exactly as before. The one-time import that turned a pre-registry single-Vault deployment into a Vault is gone, with its legacy_migration_required recovery, the Start with no Vaults action and its POST /api/v1/vaults/start-with-no-vaults route, the legacy_migration_recovery field of GET /api/v1/vaults and list_vaults, and the legacy_migration_recovery_not_pending and legacy_environment_cleanup_required codes. HATCHDOOR_EXCLUDE or HATCHDOOR_GIT_* variables left in .env no longer hold the instance in a restricted recovery screen; Hatchdoor names them in a startup warning instead, because they do nothing there. Action: the minimum version that can upgrade directly to this release is 2.5.0. An install still on 2.4.x or earlier must first upgrade to a 2.5.0 to 2.7.x release and start it once, which moves its Vault into the registry. If it skips that step and still stores its old Git settings, Hatchdoor refuses to start and names docs/migrations/legacy-single-vault.md rather than opening empty. On a new install, add your notes folder as a Vault after the first start. #427
  • An agent session that stayed open across the upgrade can no longer search until it is restarted. search_notes hits are compact by default in this release (#501) and no longer carry content, outbound_links, metadata or chunk_id. An MCP client checks each reply against the tool list it read when it connected, and a session that was open during the upgrade can keep the old list, which requires those four fields and has no detail argument to ask for them. Every search_notes call in that session then fails, in keyword and semantic mode, with Structured content does not match the tool's output schema: data/data/results/0 must have required property 'chunk_id' and the same for the other three fields. The client raises it before the agent reads the reply, so Hatchdoor cannot reword it. Seen with Claude Code 2.1.293: it re-reads the tool list by itself only when Hatchdoor is back within about seven seconds of stopping, which an image pull and restart rarely manage. The same session also lacks the tools this release adds, such as find_text. Action: after upgrading, start a new session in every agent that was connected to Hatchdoor, or reconnect Hatchdoor from the agent's list of MCP servers, which /mcp opens in Claude Code. Clearing the conversation is not enough. See "Compact and full search hits" in the MCP tools reference. #542

Added

  • The Docker image now says where it comes from. It carries the standard org.opencontainers.image labels for its source repository, licence, documentation, title and description, so Renovate can show Hatchdoor's release notes in its update pull requests and image scanners and update notifiers can link battermanz/hatchdoor to the project. A build that passes --build-arg VERSION=<version> and --build-arg GIT_SHA=<commit> also records them as the version and revision labels. The image also carries io.modelcontextprotocol.server.name, set to io.github.BatterWorks/hatchdoor, which the official MCP registry reads to prove who owns an image before it lists a server. Check with docker inspect battermanz/hatchdoor:latest --format '{{json .Config.Labels}}'. #485
  • Hatchdoor now carries its own manual, and agents can read it. Every page of the manual is built into the binary, so an install always has the version that matches what it runs, and two new read-only MCP tools reach it. read_docs with no argument returns the Home page and the name and title of every page; given a page name, such as guides/how-to-set-up-a-git-backed-vault, it returns that page as Markdown, with links between pages pointing at page names. search_docs finds pages by plain word matching, title matches first, and returns each page's name, title and a matching line. Neither needs a Vault or the search model, so they answer while model setup is still pending, which is when an agent helping someone install Hatchdoor needs them most. They work with MCP writes on or off, cannot go inside batch, and the manual never appears in note search, the tree, stats, the graph or the Vault list. A name that matches no page is refused with docs_page_not_found. #421
  • The signed-in app can now ask which folders Hatchdoor sees under its Vault mount, the folder VAULT_PATH names, so a folder picker can offer them instead of asking for a container path. GET /api/v1/folders?path=<relative> lists the folders inside one folder with how many Markdown notes each holds, counted down through its subfolders, whether it is already a Vault and which one, and whether it has subfolders of its own. Counting stops at 10,000 notes per folder or after about two seconds, and the answer then says "at least". It never follows a symlink, never leaves the mount, leaves out hidden folders and Hatchdoor's own state, returns no file names or content, and writes nothing. It needs the web token and is refused in demo mode. A missing mount answers with an empty list rather than an error. #429
  • Every instance now serves its manual as plain Markdown at open addresses, so you can tell an agent "Read /docs/deploy.md and install Hatchdoor for me" and an ordinary web fetch is enough. /docs/<page>.md returns one page, with links between pages turned into links to other /docs/ addresses, /docs/index.md returns the Home page and the list of pages, /docs/deploy.md is a short address for the agent deploy guide, /docs/search?q=<words> returns the same word search as search_docs as JSON, and /llms.txt lists every page for agents, the deploy guide first. They answer without any token, in demo mode too, and they serve the manual built into the running version and nothing else: no Vault content, Vault names or paths, settings or tokens. A page marked private: true answers only with the web token and stays out of llms.txt, and out of the index and search for anyone without it. #422
  • Hatchdoor now remembers which version it ran before an upgrade, and every release will come with a few plain lines on what changed. The manual has a new What's new page, kept off the public /docs/ addresses because it names the running version, and the signed-in app can read GET /api/v1/whats-new, which returns the running version, the one before it, whether the install started fresh, and the highlights of every release in between. Agents are pointed to the page from the MCP opening instructions, and just release-prepare now drafts each release's lines from the changelog and refuses until there are 3 to 6 of them, action-needed lines first. #424
  • Settings now shows whether your agent actually got through. Agent access (MCP) names the last agent that used a Hatchdoor tool and how long ago, such as "Claude Code connected 2 minutes ago", or says "No agent has connected yet", so a working connection no longer looks the same as one that silently fails. Hatchdoor keeps the name the agent gives itself and the time, nothing else: no tools, arguments, results, addresses or tokens. Names are cut to 100 characters with control and invisible characters removed. The record lives in instance.json beside the Vault list, so it survives a restart, and is saved at most once a minute while one agent keeps calling. The signed-in app reads it as the new read-only last_agent field of the settings response; it is never offered over MCP. #426
  • Help now opens beside whatever you are doing. Select the ? button in the top bar, or Help at the top of the … menu on a phone, and the manual for your version slides in over the right side of the screen, without moving what is under it. It renders pages like notes, with callouts, tables, code and diagrams, keeps links between pages inside the panel, has Back and Home, and searches the manual by the words in it, saying so when nothing matches. Open full width gives a long page the whole work area; on a phone Help takes the whole screen with a Close button, and Escape closes it and puts you back where you were. It works signed out too: the token prompt now links to Help and straight to a new "Where do I find my token?" section of the install guide. Signed out, Help shows only the public manual; signed in, it also lists What's new. Help reads only the manual, never a Vault, so a saved-query block in the manual shows as its source. In demo mode, Help's Home starts with installing Hatchdoor and letting an agent install it. #417
  • After an upgrade, the app now tells you what changed. The first time you open Hatchdoor in a browser after upgrading, a short What's new dialog lists the highlights of every release since that browser last looked, newest first, with anything you must do pinned at the top. A highlight's link opens Help at the page that explains it, and Full changelog opens the What's new page. Select Got it and that browser does not show it again until the next upgrade. It never appears on a fresh install, in demo mode, or when the browser blocks site data. #418
  • The screens where people get stuck now link straight to the page of the manual that explains them. A How does this work? link opens Help at the right section on the "No Vaults Yet" screen, the model-choice screen, the Vault registry recovery and "Vaults Unavailable" screens, each section of Settings and the Let assistants change notes switch, and a Vault's own Settings page, where it follows the Vault's condition: paused, a folder Hatchdoor cannot read, a Vault that will not index, and each Git sync failure. Agents get the same help: a tool call refused with a code the manual explains, such as vault_disabled, capability_unavailable, write_failed or a Git sync failure, now carries a docs field naming the page and section, which read_docs opens. Every other error, batch item errors, and the writes-off and setup refusals are unchanged. The install guide gains a "Choose a search model" section for the model-choice screen to point at. #423
  • Hatchdoor can now tell you when a newer release is out, if you ask it to. Turn on Settings → Updates → Tell me about new releases, or set HATCHDOOR_UPDATE_CHECK_ENABLED=true, and once a day Hatchdoor asks GitHub's public release list for the latest version. When it is newer than yours, a line at the top of the page says so, with a What's new link to the release notes on GitHub and a How to upgrade link to a new manual page that covers upgrading with Docker Compose and the sentence to give an agent that should do it for you. Close the line and it stays closed in that browser until the next release. The check is off by default and never runs in demo mode. The request carries your IP address and the user-agent Hatchdoor, without a version or anything else about the instance. A failed request is logged and tried again the next day, and turning the setting on or off takes effect within a minute, with no restart. Hatchdoor never downloads or installs anything. The signed-in app reads the result as the new read-only update_check field of the settings response. #425
  • Add a Vault now lets you pick your notes folder from a list instead of typing a path inside the container. Choosing A folder on this server shows the folders Hatchdoor can see, with how many notes each holds ("at least" when counting stopped early) and an Already a Vault marker, one level at a time: the arrow on a row opens it and the trail above the list goes back up. Picking a folder fills in its path. When the shared folder holds no notes the list says "No notes found yet", and My folder isn't here explains that Hatchdoor only sees the folders shared with it at install, links to the new "Add a folder Hatchdoor cannot see yet" section of Connect your first Vault, and suggests asking your agent. Type a path instead brings back the old Folder path field for folders mounted elsewhere. Help opened from inside a Settings dialog now sits beside it rather than over it, and Escape closes Help before the dialog, so nothing typed is lost. GET /api/v1/folders gains a root field, the mount's absolute path, which joined with a folder's path gives the path a Vault is created from. #430
  • A new install now opens on a setup checklist that takes you from nothing to an agent searching your notes. It sits where No Vaults Yet would be and has four steps that tick themselves off from what really happened: Add your notes embeds the folder picker (or opens Add a Vault for a Git repository) and links to the public demo for anyone who wants example Vaults first; Choose a search model shows as done; Connect your agent turns agent access on read-only in one click, makes the MCP password and shows a ready-made config for Claude Code, Codex, OpenClaw, Hermes or any other MCP client with the address and password filled in, then names the agent once it connects; Try a search ticks after a search in that browser finds something. An optional switch turns on the update check. The password is shown only that once; Make a new password replaces it. Close the checklist and that browser remembers; reopen it any time from Help → Setup checklist. An upgraded install never sees it unless reopened, and demo mode never does. The one-click connect never lets an agent change notes: that stays a separate setting. #419
  • The manual has three new pages carried over from the old starter notes. How to work in a Vault as an agent gives an agent the habits that keep notes safe: search first, read before changing, make the smallest edit, and treat note text as data. How to choose a folder layout suggests a simple PARA-style layout for a new Vault. Markdown feature showcase shows every Markdown feature Hatchdoor renders on one page and is linked from the Supported Markdown reference. All three are in Help, read_docs and the public /docs/ addresses. The starter notes themselves are gone from the repository; the dev fixtures now generate their own sample notes. #431
  • Add a Vault can now make the folder for a new Vault, so starting one from nothing no longer needs a shell or a script. Under the folder list, New folder asks for a name and makes one empty folder in the folder you are looking at, at the top of the shared folder or inside any folder you opened, including when no notes were found yet. The new folder appears in the list already picked, and Create Vault then works as before. Hatchdoor makes one folder at a time, only inside the Vault mount (the folder VAULT_PATH names), never inside a folder that is already a Vault, and puts nothing in it. A name with a slash, a leading dot, or a space at either end is refused, and so is a name already in use. If you cancel the form afterwards the empty folder stays: Hatchdoor never deletes folders. For API clients this is POST /api/v1/folders with parent and name, behind the web token and refused in demo mode, answering 201 with the folder or one of folder_name_invalid, folder_name_taken, folder_parent_not_found, folder_mount_not_found, folder_outside_root, folder_inside_vault, folder_not_writable and folder_vaults_unknown. Typing a path that does not exist is still refused, and agents get no new tool: create_vault is unchanged. See ADR-44. #494
  • Hatchdoor can now show you the usage report it would send, before anything is sent. This is telemetry, and it is off unless you turn it on. Settings has a new Usage report section with a Send a usage report switch, also settable as HATCHDOOR_USAGE_REPORT_ENABLED, and under it the exact report for your install, whether the switch is on or off: the version, operating system and image it runs, which search model is chosen, how many Vaults and notes it has as ranges, how its Vaults sync, whether agents may connect and write, and which kinds of agent connected lately. Every value is a fixed word, a yes or no, or a range, and nothing about your notes, Vault names, machine or tokens is in it. Turning the switch on makes a random install ID, shown in Settings; turning it off deletes that ID and everything kept for the report, and turning it on again makes a new one. The manual's new Usage report reference page lists every field, and a public demo never keeps an ID. Image builds can pass --build-arg HATCHDOOR_IMAGE=docker or podman so the report can say which image it runs. #477
  • Hatchdoor now sends the usage report once a day, and only if you turned it on. This is telemetry, and it stays off unless you switch on Settings → Usage report → Send a usage report or set HATCHDOOR_USAGE_REPORT_ENABLED=true. The first report goes within a minute of turning it on, and after that at most one in any 24 hours, also across restarts. Each is one POST of the report Settings shows to https://telemetry-hatchdoor.battercloud.cc/v1/report, with the user-agent Hatchdoor and no version. If a report does not get through, Hatchdoor tries again an hour later and saves nothing to send later. Turning the report off stops it at once, with no last report, and an install that never turned it on never contacts that address, nor does a public demo. While the report is on, Settings shows Last report with how long ago the last one got through. #478
  • Hatchdoor now asks about the usage report once in each place you might set it up, and never reminds you. This is telemetry, and it stays off unless you say yes. The setup checklist of a new install has a second optional switch, Optional: send a usage report, off, below the one for new releases; the two are independent, and a value set in .env shows it locked. An agent installing Hatchdoor from /docs/deploy.md asks one more question in fixed wording, defaults to no, turns the report on through the settings API only on a clear yes and never writes the variable to .env, so you can always switch it off in Settings. On an install upgraded to this release, the first agent to open an MCP session, by initialize or server/discover, gets one extra sentence at the start of the opening instructions, where a client that cuts long instructions short still reads it whole and on that one connection loses the end of the usual text instead, saying the report exists, is off, is described on the manual page reference/usage-report-reference, and is turned on in Settings; Hatchdoor records that in a new usage_report_notice section of state/instance.json and never sends it again. A fresh install, a demo instance, and an install where the report is already on or set in .env never send it. No MCP tool reads or changes the setting. For people who install by hand, the README now names HATCHDOOR_USAGE_REPORT_ENABLED under Configuration, and .env.example no longer carries a block for it, so the file you copy never suggests an answer. The agent's own connection check on that page now gives the name its client really sends, so the report counts it as that agent and not as an unknown one. The Usage report reference page lists the five places. #479 #480
  • Agents can now ask which notes contain an exact string. The new read-only MCP tool find_text takes a scope and one literal text, and returns every note that contains it, with the number of occurrences in each note and across the whole scope. Nothing is ranked, every character means itself, and the string is looked for in the body, the frontmatter block and the file path, with each match labelled by its place. Case is ignored unless case_sensitive is true, and accents always count. It covers every layer unless layers narrows it, reads each note's file when the call runs so an edit is matched before indexing catches up, and lists any note it could not read under unread. path_prefix, limit (up to 500) and snippets_per_note (0 to 3) shape the answer, and it works as a batch item. The search_notes description now sends exact questions to it. See "Finding every note that contains a string" in the MCP tools reference. #500
  • Agents can now read part of a long note instead of all of it. Two new read-only MCP tools do it. get_note_outline takes a vault_id and a slug and returns the note's headings in order, each with its text, level, heading path and the size of its section in bytes, plus the size of the whole file, of its frontmatter and of the text before the first heading, and no note text at all. get_note_section takes one to ten headings, each a heading's exact text or a heading path such as Rules > Filing, and returns each section whole, subsections included, in the order asked. A heading that matches nothing, or matches several, gets an error in its own entry that lists the paths to ask for, and the other sections still come back. Both return the whole note's content_hash, the one get_note reports, so edit_note or replace_section can follow without reading the rest, and both work as batch items. A section is the span replace_section replaces. get_note is unchanged and still returns the whole file. See "Reading part of a long note" in the MCP tools reference. #502
  • A link to a public demo now shows a preview when you share it. On an instance in demo mode (HATCHDOOR_DEMO_MODE=true), a link pasted into WhatsApp, Telegram or a similar app shows a title, a short description and a picture instead of a bare address, and a search engine reads a plain title and description from the same page. A note's link shows the note's title and its description property, or its opening sentence when it has none; every other page shows Hatchdoor's own title and description. The picture is the same for every link and appears only once Public address (HATCHDOOR_PUBLIC_URL) is set, because Hatchdoor never takes its address from the request. A preview never names a note the demo does not already serve to anyone. An instance that is not in demo mode is unchanged: its page is the same for every address and names no note. #512
  • The formatting toolbar over a selection in the live editor has three more buttons: heading, bullet and to-do. They turn the line you are on into one, and pressing the same button again on that line turns it back into plain text. Until now a line you had already written could only become a heading or a to-do by typing the marker yourself, because the / menu opens only on a new line. The phone's keyboard bar already had these. #556

Changed

  • The live editor now renders what the Reading view renders. A mermaid fence draws as its diagram, $$ and $ math through KaTeX, a base fence as the saved-query table the server evaluated for the note on disk, a ![[file.pdf]] embed as the PDF preview under its line, and a > [!kind] callout with the kind's accent and title, each turning back into its source when the caret lands on it and rendering again when it leaves. Wikilinks in the editor are now looked up by the server, by title, alias or path, the way the Reading view looks them up, so they read as resolved or missing the same in both views, and clicking [[Note#Heading]] opens the note at that heading. Image and PDF embeds in the editor are also placed by the server now, so a file named from the Vault root, or by name alone, shows in a note several folders deep as it already did in the Reading view. An embed of another note still shows as its source in both views. #544
  • A note on a Vault Hatchdoor can write to now opens straight into a live editor over its whole body, the way Obsidian's Live Preview works. Click anywhere and type: Markdown syntax shows only on the line you are on and renders everywhere else, you can select across paragraphs, and undo covers the whole note. Ctrl+B, Ctrl+I, Ctrl+E and Ctrl+K format and link, a small toolbar appears over a selection, typing / at the start of a line opens a menu of headings, lists, to-dos, quotes, callouts, code blocks, dividers and tables, and typing [[ offers your notes' titles, written in the Vault's link style. On a phone there is no floating toolbar; a bar above the keyboard carries indent, outdent, bullet, to-do, heading, bold, italic, strikethrough, code, highlight, link, undo, redo and Done. Images show under the line that embeds them; mermaid diagrams, math, saved-query tables, PDFs and other embeds show as their source in the editor and render in the new Reading view, which the button above the note switches to and the browser remembers. Saving is unchanged: edits go to the Vault after a short pause and when you leave the editor, the badge above the note reports it, and a draft stays in the browser until the Vault has it. The Edit button is now Source and still opens the whole note as Markdown with a Save button. The one-block-at-a-time editor, its double-tap entry on phones and its hint are gone. Read-only Vaults and the public demo show the rendered page only, as before. #541
  • The note page reads from the top. Links now sit after the note's text, folded under a Links heading in the same style as the sidebar's sections, instead of between the properties and the first sentence. A note whose first line repeats its own title as a # heading shows the title once, and the heading list skips it. Edit shows its key, E, which now opens the editor. On a phone, Properties start folded and remember their own answer, and On this page is a chip in the row under the top bar that opens a sheet of the note's headings, so nothing sits between the title and the text; between tablet and desktop widths the folded heading strip stays. While the editor is open, the properties grid and links are out of the way. #530
  • The sidebar changed shape. The Stats, Graph and Settings buttons moved to the bottom, beside New note, and on a phone Help sits there too instead of at the top of the … menu. Changed on disk is now a folding section at the top of the list, like Recently viewed, and starts folded with its count showing; the inbox button that opened it is gone. The Scope zone starts folded, since its head already names the scope and its state; its folded head shows 5 of 8 with the full sentence on hover, and everywhere else that reading says 5 of 8 answering. The Vault name in front of a note in Recently viewed, Changed on disk and search results is now small and grey and takes at most part of the row, so the note title always has room. #530
  • The landing page with no note open is a home page. It shows the scope's name, how many Vaults and notes it holds, the six notes last changed on disk and the six last viewed, each with its Vault and when, and New note and Search. It replaced the "Select any note from the explorer" box. The breadcrumb in the top bar now says Home, Stats, Graph or Settings on those pages instead of "Notes Explorer". #530
  • The … menu is about the open note: Rename, Move, Copy note text, Download .md file, Copy note link, Archive and Delete. New note and Edit note left it, since both have their own buttons, and Escape closes it. The theme button opens a menu with System, Light and Dark instead of cycling through them on each click. Search has one Mode control at every width, a two-way Semantic / Keyword switch, in place of a checkbox on desktop and a drop-down on a phone, and the no answer marks in its Vault filter are amber rather than red. The graph's tag chips fold behind the Tags button on desktop as they already did on a phone. The Stats page lost its subtitle, Settings' section save button says Save, the two Recorded as fields sit under a History (Git) heading, and a Vault page's Disconnect Vault stands apart from Pause and Rebuild search index. #530
  • Hatchdoor no longer writes starter notes into a new Vault. Creating a Vault on an empty folder, through Settings, the API or an agent, now leaves the folder empty, and so does a first start on an empty VAULT_PATH. Notes seeded by earlier versions stay where they are; nothing in an existing Vault is changed or deleted. The Docker image no longer carries the starter notes. #428
  • The manual's getting-started pages, guides and concept pages are rewritten for people new to Hatchdoor. They lead with what you want to do and what to click, use the words people search for when stuck (token, password, sync, not showing up), and describe the 2.8.0 first run: no Vaults until you add one, the setup checklist, the folder picker, Help and What's new. The troubleshooting guide gains a list of symptoms and a section for notes that are not showing up, the install guide now says that Gemma uses less memory than Nomic, and asides about Hatchdoor's internals are gone. Reference pages are unchanged. #432
  • The agent deploy guide, served at /docs/deploy.md, is rewritten so a beginner can install Hatchdoor by giving their agent one line: "Read https://hatchdoor.battercloud.cc/docs/deploy.md and install Hatchdoor for me". The agent checks for Docker, asks every question once (which computer, where the notes are, this computer or the home network, read only or changes, Gemma or Nomic, and on Linux whether it may install Docker), then installs, creates the Vault through the HTTP API, connects itself read-only with its own MCP token, proves a search works and hands over the web address and web token. It never offers internet access, never answers the model licence for you, keeps MCP settings out of .env so writes can still be allowed in Settings, and writes tokens only to .env, Hatchdoor's settings and its own client config. When Hatchdoor can read your notes folder but not write to it, the hand-over says so, because allowing changes in Settings would not be enough. On a Linux computer that asks for your password before administrator commands, the agent stops once and gives you one line to run yourself, since it cannot type the password. On a Mac or a Windows PC without Docker, it asks you to install Docker Desktop before any question, and to give it the same line again if the install restarts your computer. The guide also stops saying that declining Gemma saves memory. The README and the manual's Home page carry the one-line prompt. #433 #434
  • A screen reader now says what each How does this work? link explains. The link reads the same on screen everywhere, so on a screen with several of them, such as the setup checklist or Settings, every one used to be announced with the same words. Each is now announced as the question followed by its topic, for example "How does this work? Adding your notes" or "How does this work? Letting your agent change notes". The words on screen do not change, and with voice control you still say "How does this work?". #460
  • The agent deploy guide, served at /docs/deploy.md, fixes four places where an installing agent was left to guess or told you something untrue. When your notes come from a Git repository, the agent now tells you up front that they start read-only in Hatchdoor, and its closing message no longer claims that Let assistants change notes alone lets it change them: it says the Vault must be switched to Two-way with an access token that can push, and points to How to set up a Git-backed Vault. An agent whose client reads its token only from an environment variable now has a procedure: it creates the MCP token as its last action, proves a search works in the same command, and shows you the token once with the name of the variable to set. The guide gives one command each for Linux, macOS and Windows that finds the computer's home-network address, the one its default route uses, so Docker's own networks are no longer mistaken for it, and says what to do when a VPN holds the default route. The question about installing Docker on Linux now says it has no default. #459
  • The agent deploy guide, served at /docs/deploy.md, fixes three things a full install on Windows turned up. On Windows the search model is slow to load after it has downloaded, about 17 minutes on a slow test computer, and an agent that saw nothing happen restarted Hatchdoor, which started the loading over: the guide now says how long the wait can be, what it looks like, and to leave the container alone. When you asked for Hatchdoor on your home network, other devices could not open it until you chose Allow in a Windows Security window about Docker Desktop Backend that the agent cannot see: its closing message now tells you to look for it. And the agent no longer passes on the log's compare-and-swap warning as if it were a problem with your install, since every Windows folder gets it. #463
  • search_notes hits are now compact by default, so an agent pays for locating a note, not for reading ten chunks of it. Each hit carries vault_id, note_slug, note_title, note_path, heading_path, score, layer and a new snippet of at most 200 characters: centred on the first matched query word in keyword mode, and the start of the matched chunk in semantic mode. For a #tag query it names the matched tag, as Matched tag: #<tag>. A hit no longer carries content, outbound_links, metadata or chunk_id unless asked. A search at limit: 50 over full-size chunks now comes to about 25 KB in a Vault written in a Latin script, and somewhat more in scripts whose characters take more bytes, where it used to overflow an MCP client's result budget. If your agent or script reads content, outbound_links, metadata or chunk_id from a search hit, pass the new argument detail: "full", which returns exactly the earlier reply. Ranking, scores, order, limit and per_note_cap are the same in both shapes, a search_notes item inside batch follows the same default, and the tool's outputSchema describes both. The web search dialog and the HTTP search API are unchanged. See "Compact and full search hits" in the MCP tools reference. #501
  • The browser tab now names the page you are on. A note shows as its title followed by "· Hatchdoor", and the graph, stats and settings pages as Graph · Hatchdoor, Stats · Hatchdoor and Settings · Hatchdoor; the home page stays Hatchdoor, and an address that leads nowhere reads Page not found · Hatchdoor. The name follows you as you move around and updates when you rename the open note, so several open tabs, bookmarks and history entries can be told apart. Until now every tab read "Hatchdoor". #514
  • The manual was checked page by page against 2.8.0 and reworded in plainer language, with shorter sentences and no em dashes. Home has a new section, Hatchdoor on the web, that links the public demo, the online manual, the source code with its release notes and issue tracker on GitHub, and the Docker image. The upgrade guide says how to come from 2.4.x or earlier, by way of 2.7.0. Several statements that had drifted are corrected: search in the browser has no layer choice and looks at the default surface only, nine Vault tools need write access and not five, the settings table in the HTTP API reference lists HATCHDOOR_UPDATE_CHECK_ENABLED and HATCHDOOR_USAGE_REPORT_ENABLED and no longer calls HATCHDOOR_ARCHIVE_PREFIX retired, find_text refuses a string over 4,096 bytes, and the troubleshooting section on the save failure that 2.7.0 fixed no longer tells you to upgrade to a version you already run. The README and the Docker Hub page describe the 2.8.0 first run. #528
  • The access token prompt now looks like the rest of Hatchdoor and follows the light and dark themes. It used to be a dark grey panel with a blue button and rounded corners whatever the theme. It is now built like the other dialogs, with square corners and the same field and button, and it says and does what it did before. A few smaller colours moved onto the theme as well: in the source editor, the properties panel, the drop target, the highlighted autocomplete row, the two sides of the conflict view and the failed-attachment notice, and elsewhere the header strip of a code block and the graph's filter count badge, which lost its rounded corners. #547
  • The manual's editing guide covers more of the live editor. It now lists Ctrl+Shift+X for strikethrough and Ctrl+F for find and replace within the note, says to press Cmd for Ctrl on a Mac, says the floating toolbar shows only for a selection on one line and lists its heading, bullet and to-do buttons, and says / can turn a line back into plain text. It describes the find bar and the 75-character column, and no longer says a failed save retries by itself: saving stays stopped until you reload the page or save from Source. It and the attachments guide say where a pasted or dropped file's embed is written: on a line of its own beside your caret or where you dropped it, and at the cursor in Source. The attachments guide also says a PDF can be pasted, not only dropped, and the editing guide no longer says the file is uploaded beside the note, since it goes to Attachments/ at the Vault root. The README's feature list names the live editor. #555
  • A note is now set in a narrower column, about 75 characters a line, where it used to run the full width of the page, about 120 characters on a wide screen. Long lines are tiring to read: the usual guidance for a single column is 45 to 75 characters. The title, the Properties line, tables, callouts, code blocks and diagrams keep to the same column, so the page has one edge, and the outline stays beside it. A table wider than the column scrolls sideways inside its frame, in both views. Source and the conflict review keep the wide layout. A screen narrower than the column, such as a phone held upright, is unchanged; a tablet or a phone on its side now gets the column too. #557

Fixed

  • Dropping or pasting a file into a note now follows the upload limit you set. The browser refused every attachment over 10 MB before sending it, so with Settings → Uploads → Largest file from this app (HATCHDOOR_MAX_ATTACHMENT_BYTES) raised to 20 MB, a 15 MB PDF was still turned away with "The limit is 10 MB", although an agent could upload the same file. The browser now reads the limit from the server for each file, so a raised limit works at once, without a restart or a reload, and the message for a file that is too large quotes the real limit. Where the browser cannot read the limit, it sends the file and shows the server's answer. #558
  • The Docker verification stage now includes the link-preview image, so the test checks the real asset's dimensions and size. #552
  • Inline code is readable again while editing a note in the light theme. In the Editing view a span such as `npm run build` showed as a solid black box, black text on a black fill, and in other places as orange or grey text on that same box. It now looks as it does in the Reading view in both themes: dark monospace text on a pale chip with square corners, in paragraphs, lists, headings, quotes and callouts. Fenced code blocks are unchanged. #550
  • A Vault with Git sync no longer stays marked stale when its index is current. Saving a commit while the index was being rebuilt counted as an edit to the notes, so the rebuild labelled its own result out of date, and since no file had changed nothing queued the rebuild that would clear the label. The web app then showed stale beside the Vault, list_vaults reported "search": "stale" and collection reads came back partial: true, until an unrelated edit, a sync or refresh_vault. A commit, a sync that pulls nothing and a recovery branch publish no longer count as edits. A sync that pulls remote changes still marks the index stale and queues the rebuild that brings it up to date, and its line in the server log now reads outcome=Pulled. A sync that fails during a rebuild queues the next one itself. #549
  • Search results spell a numbered folder's path the right way round. A note at 30-areas/Homelab.md was listed as areas/Homelab.md-30, because the path was laid out right to left to shorten it from the front. Snippets no longer show [[ around wikilinks or the source of a fenced code block, and a result whose matching section sits under the note's own title no longer repeats the title on a second line. #530
  • Search no longer says Could not load above a list of results. While the search index is still being built, the dialog now shows one line saying so, with the percentage and which mode already answers, and Keyword results show under it; Semantic with nothing to show yet says the index is building rather than "No matching notes". A model that is missing or failed still gets its block, unless Keyword results are on screen, where it shrinks to the same quiet line. #530
  • The sidebar no longer names a Vault as "did not answer" while that Vault's notes are listed right above the sentence. A Vault answering from its previous index generation during a rebuild answered; only one that sat out is named. A note opened for the first time no longer flashes "This note's source and rendered lines don't line up" for a second while its links resolve. Copy note link copies the note's address without the ?q= search terms it arrived with. #530
  • Searching the manual for a tool name, a setting or an error code now finds the pages that mention it. search_docs, the Help search box and /docs/search used to split a word such as find_text or HATCHDOOR_PUBLIC_URL into find and text, or hatchdoor, public and url, so pages that only held those common words came first and the settings reference did not appear in a search for a setting it defines. A query word with punctuation inside it is now also looked for exactly as typed, ignoring case, in each page's title and text, code blocks included. Pages that hold it come first, with an excerpt that shows the line it is on, and pages that only hold its parts fill the remaining places. A query of plain words returns what it returned before. #522
  • Reading a note now returns its tags, aliases and other properties. The MCP tool get_note and GET /api/v1/vaults/{vault_id}/notes/{slug} answered metadata: {"tags": [], "aliases": [], "properties": null} for every note, whatever its frontmatter held, so an agent reading note.metadata.tags concluded the note had no tags. note.metadata now carries the same values get_frontmatter returns. A note with no frontmatter block answers with two empty lists and an empty properties object, no longer null. A note whose frontmatter does not parse still reads in full and answers metadata: null, so null now means "could not read the frontmatter" and a client that assumed an object there has to allow for it. #521
  • The manual names the browser's controls the way they now read. The tour of the browser says where the Vault selector is (the Scope section at the top of the sidebar, opened with a click or V), calls the page with no note open the home page and the statistics page Stats, the troubleshooting guide says to switch Mode to Keyword where it said Keyword mode and says where Retry setup goes while Keyword results are showing, and the Markdown reference calls the note's links the Links section under the note. #530
  • The usage report now tells a release from a development build correctly. Before, a copy built from source reported channel: stable, and a release image built with its commit for the image label would have reported dev and shown its version as 2.8.0 (dev abc123). A build is now a release only when its image build passes --build-arg VERSION=<version> and that matches the version in Cargo.toml: it reports stable and a plain version. Every other build, a nightly image or one built from source, reports dev. Image builds for a release must pass VERSION. #504
  • Running the test suite in Docker with docker build --target verification . works again. Two tests failed there: one needs the git program, which the build image did not install, and one reads frontend/vite.config.ts, which the verification stage did not copy. The image Hatchdoor ships is unchanged. #482
  • Notes changed from Windows now show up when Hatchdoor runs under Docker Desktop. A Windows folder shared with the container sends no file change events, so a note added, edited or deleted in another program never reached the file tree or search until a restart or a manual refresh, while the Vault still reported its watcher as running. Hatchdoor now also compares every Vault's folder with what it last saw once a minute, by file names, sizes and modification times, and reindexes when something changed, so an outside change shows within about a minute on any folder that sends no events and within seconds everywhere else, as before. There is no setting for it. The install page now also says that a Windows folder under Docker Desktop uses the two-step save, which it used to describe for ZFS and FUSE only. #458
  • The Add a Vault dialog no longer has the open Settings section's buttons drawn over it on a wide screen, and it now fits a phone screen. Every Settings dialog now draws above the whole page, and on screens 640px wide or narrower the Where is this Vault? choices stack one above the other, each on one line, instead of pushing the dialog past both edges of the screen. #448
  • /ready now answers 200 on an instance with no Vaults. A new install starts with none, so it kept answering 503 not ready, and /api/startup-status kept reporting scanning, long after the search model had loaded, and a script or agent waiting on /ready hung until someone added a Vault. Hatchdoor is now ready as soon as the search model is set up and no active Vault is waiting on its first index, which covers a fresh install, a restart with no Vaults, an install whose Vaults are all disabled, and disabling or disconnecting the last Vault still in its first index. A Vault registry that needs operator recovery still keeps /ready at 503. After a restart, an instance whose Vaults were all indexed before is ready when the model has loaded, without waiting for its first catch-up index. #453
  • The What's new dialog now holds keyboard focus from the moment it appears. It used to be drawn first and take focus an instant later, and the rule that keeps Tab inside it started at that same later moment, so a key pressed in between went to the page behind it. #468
  • Loading the EmbeddingGemma search model no longer looks up its own folder thousands of times. Each load made between 13,000 and 22,000 path lookups on the models folder, more the deeper the folder sits, which costs nothing on a local disk but took about 17 minutes on a Windows install under Docker Desktop, where every lookup is a round trip to Windows, and it happened again on every restart. Hatchdoor now reads the model files once and hands them to the model runtime from memory, which makes none of those lookups. The time on Windows has not been measured again yet, so the deploy guide keeps its warning about the wait. The log also says what is going on now: Search model downloaded, loading it when the download is done, Search model is still loading every 30 seconds with the time so far, and Search model loaded with how long it took. The cost is memory: with EmbeddingGemma loaded Hatchdoor now holds about 110 MB more, 675 MB instead of 565 MB on a small test Vault. Search results and existing indexes are unchanged. #469
  • Polling /ready while Hatchdoor starts no longer fills the log with errors. Every 503 not ready answer was written as an ERROR line, one per poll, so an install that waits on /ready as the deploy guide tells it to buried the lines that mattered under a few hundred of these. A not-ready answer from /ready is now logged like any other finished request, at DEBUG, during startup and whenever else the instance is not ready. /ready answers exactly as before, and a 5xx from any other address is still logged at ERROR. The agent deploy guide no longer tells the installing agent to expect those lines. #472
  • Search snippets no longer show the source of a code block or a diagram as if it were prose. A note with a Mermaid diagram used to come back with a snippet such as "graph LR; Net --> Gate", because the index kept the lines inside a fenced block and dropped the ``` lines around them. A search hit's content now has those lines back, with the block's language, so a reader can tell code from text, and the snippet an agent gets from search_notes leaves fenced blocks out. A hit that is nothing but code has an empty snippet, and its heading still says where it is. Semantic search returns the same results as before: the text the search model reads has not changed, so no note is embedded again. A keyword search still finds a word that appears only inside a code block. Because the language name on a block's opening line is now part of the indexed text, a keyword search for mermaid or bash also finds the notes that hold such a block. The first indexing pass after the upgrade goes through every note once to store the new text, and reuses the vectors it already has. The search box in the web app leaves the block out as well. #532
  • Opening Hatchdoor in a browser no longer contacts Google, and the app now shows the fonts it was designed with. Every page load asked Google for four font families, which gave Google the address of each visitor, and since 2.0.0 Google refused the request because the link was malformed, so the app fell back to whatever fonts the device had. The four families (Bricolage Grotesque, Newsreader, Inter Tight and JetBrains Mono) now ship inside the app, about 1 MB in all, of which a browser downloads only the scripts a page uses. Headings, body text, the reading view and code blocks therefore look different after this upgrade, and they look the same offline. #475
  • The bundled fonts now draw the app's heaviest text themselves. The bracket logo mark and the small label on the startup screen, the section numbers in Settings and bold italic words in notes ask for a weight above what the fonts were first allowed to use, and the browser would have thickened a lighter weight instead, which looks blunt. The font files already hold those weights, so nothing more is downloaded. #491
  • Hatchdoor now says which Vault is in the way when it refuses a folder for a new or edited Vault. The old message, "Vault path overlaps another connected Vault, including disabled definitions", named nothing, so someone who typed the top of their notes folder into Add a Vault could read it as "this folder can never be a Vault". The refusal now names the Vault and says how the two folders relate: the folder is already that Vault, is inside it, or contains it, as in This folder contains the Vault "Notes". Two Vaults cannot share notes, so choose a folder with no Vault in it. A disabled Vault is called a disabled Vault, since those are easy to forget, and when the folder contains several Vaults the message names one and counts the others. Agents get the same sentence from create_vault and edit_vault. The message never includes another Vault's folder path, and the vault_path_overlap code, the 409 status and the cases that are refused are unchanged. #495
  • A Vault that is reindexing no longer tells agents it cannot be searched. Every reindex of a Vault that was already searchable, including the short one after each saved note, made list_vaults and GET /api/v1/vaults report search: "indexing" and capabilities.search: false until it finished, although search kept answering from the previous index the whole time. An agent that checks capabilities before it searches stopped searching for that long and walked the file tree instead. Such a Vault now reports search: "stale" and keeps capabilities.search: true while it reindexes, with index_turn: "running" saying a rebuild is under way. indexing now only means a Vault building its first index, with nothing to search yet. In the sidebar such a Vault keeps its note count while it reindexes, where a long reindex used to replace the count with a moving placeholder. #483
  • Two pieces of built-in help now say what Hatchdoor does. The help under Settings → Meaning search in demoted layers said a folder marked with a .hatchdoor-layer file stays out of the browser. It only stays out of normal search, and its notes still show in the sidebar, which the help now says. And an agent whose write fails with write_failed is now sent to the troubleshooting section "A write fails for some other reason", which says where to look. It used to be sent to a section about one cause that 2.7.0 removed. #527
  • On a phone, the Edit button on an open note no longer shows an unexplained E in a small pill beside its label. The E is the hint for the keyboard shortcut that opens the editor, so it now appears only in the desktop layout. Pressing e still opens the editor at every width. #537
  • Bullet lists in a note are indented again. In the Reading view the dash of every plain bullet was drawn on top of the first letter of its text, at every depth, on phones and desktops alike, because the indent had been lost when the old block editor was removed. Bullets are back to their indent, with the dash clear of the text. Numbered lists, task lists and lists in the live editor were not affected and have not changed. #547
  • Two notices and a drop hint name the right things. When a note has an unsaved edit that the note on disk has since moved past, the notices said "Use Edit to review it" and "Open Edit to compare the two", but the live editor renamed that button to Source. They now say Source. The hint shown while dragging a file over Source said "Drop image to attach" although a PDF is accepted too; it now says "Drop an image or PDF to attach". #555
  • The find and replace bar in the live editor now follows the theme and is easier to use. Ctrl+F in a note opened a bar with near-black buttons and grey labels, rounded fields, serif text and the browser's own checkboxes, the same in the light and dark themes. It now uses the same fields and buttons as the rest of Hatchdoor, in three rows: find, its options, then replace. Its wording is plainer: Select all where it said all, and Match case, Regex and Whole word for the options. The bar stays at the top of the note while Next scrolls to a match further down. On a narrow screen each field takes the full width, with Next, Previous and Select all side by side under the find field, and on a touch screen the buttons are finger-sized. Matches in the note are marked like search hits, and the current one in the accent colour. The formatting toolbar no longer pops up over each match while the bar is open. #556
  • The formatting toolbar over a selection in the live editor is dark with square corners again, as designed. It showed as a pale box with rounded corners, because the editor library's own tooltip style was overriding Hatchdoor's. #556

v2.7.0 - 2026-10-02

Added

  • A note can now hold a live table of other notes. Write a fenced base block in it, in the syntax Obsidian's Bases feature uses, and the note page draws the notes it selects as a table, each row linking to its note. The definition of something like "active subscription" then lives in the Vault as one thing, instead of being worked out again by whoever asks. The table is worked out each time the note is read, from that note's own Vault and no other, and it is never written into the file: the Markdown on disk is exactly what you wrote, and search, backlinks, the graph and statistics see the block and not the rows. A filter against now() or today() therefore changes its answer as time passes with no file changing. Hatchdoor supports part of the Bases syntax: filters over tags, folders, file names and frontmatter properties with comparisons, and, or, not, emptiness checks and the current time, plus one table view with its columns, their order and a row limit. Anything beyond that is refused with the reason shown in place of the table, rather than half applied, because a filter only partly understood gives a wrong list that looks right. Rows are sorted by note title. A note may hold several blocks, each drawn where it sits and evaluated on its own, and a <!-- hatchdoor-query: name --> comment on the line before a block names it without changing what Obsidian reads. The saved queries in one note scan at most 20,000 notes between them, one saved query shows at most 500 rows, and one note holds at most 10; past any of those it says so instead of quietly stopping short. A date written with a space, 2026-09-18 10:00, or with a time zone compares correctly against now(), and query_notes benefits from the same rule: two values that both read as dates or times are compared as moments rather than as text. The rows are also available over HTTP at GET /api/v1/vaults/{vault_id}/notes/{slug}/saved-queries. #275
  • A saved query that cannot be drawn now says exactly why, and the three outcomes can no longer be mistaken for one another. A refused block names the part it could not use, such as daysUntil() or the line where its YAML breaks, instead of leaving you to delete things until the table appears. A block that is fine but matches nothing says No matches. and that it checked every note, so an empty answer cannot pass for a broken one, and a broken one can never show up as an empty table. Grouping, summaries and view types other than table no longer refuse the whole block: they only change how rows are drawn, so Hatchdoor draws the plain table with every row and says under it which instruction it left out. A filter it does not understand still refuses everything, since there is no honest partial answer to it. Problems with the <!-- hatchdoor-query: name --> markers now show on the page: a marker with no block after it gets a note where it sits, a name that is not usable gets a note under its table, and two blocks sharing a name both still draw their tables, each noting that the name addresses neither until one is renamed. Clicking a column heading sorts that table on your screen, and only that table; the sort is never written to the note and a reload forgets it. Over HTTP the statuses are now populated, empty, refused (with a construct naming the part) and stopped, presentation instructions that were set aside come back as ignored, and marker problems come back beside the queries as marker_problems instead of as per-query notices. #276
  • Agents can now read a saved query's rows as data. get_note still returns the note exactly as the file holds it and never anything computed. Beside it, a new saved_queries list names each saved query in the note. A new tool, evaluate_saved_query, takes a note and a saved query's name and returns the notes it selects as rows: each note's Vault, slug and path, plus one value per column the definition picked. The agent picks a saved query by name and never reads the definition, so it cannot drop a condition by rebuilding it as its own query. That was the risk this closes. The name can be left out when the note holds only one saved query. Without it, a note holding several is refused and the refusal lists the names. A saved query is never picked by its position in the note, so moving blocks around changes nothing. An unknown name, a name two saved queries share, a note with no saved query, a definition Hatchdoor cannot evaluate and one stopped at a limit each come back as their own structured error, never as zero rows. An agent that asks about a broken definition cannot report that nothing matched. A query that really matches nothing answers empty, and one held back by its own limit or by the 500-row cap says so. The query always reads its own note's Vault, and the tool takes no scope. #277
  • Agents can rename a tag across a whole Vault in one operation, rename_tag, instead of reading and rewriting every note that carries it. Before this, collapsing domain/homelab into topic/homelab over a few hundred notes meant walking the whole Vault, since tag search stops at 50 results, and then driving the rewrites through batches of 20. The rename always takes two calls. The first writes nothing and answers with the plan: every note that would change, how many change in their frontmatter and how many in their body text, and a plan_hash. The second call sends that hash back and applies the plan, but only if the Vault still produces exactly the same plan; if anything changed in between, it is refused and nothing is written. Renaming a tag also renames every tag nested under it, so domain takes domain/homelab and domain/plans with it, even when no note carries domain on its own. Matching ignores case, the way tag search does. Renaming into a tag that already exists is a merge: a note left carrying the target twice keeps it once, and the plan tells you how many notes already carried it, which is the number that separates a rename from a merge. Only the renamed characters change. A one-line tags: [a, b] list stays on one line, a block list stays a block list, and key order, quoting and every other byte of the note stay as they were. A hashtag inside a code block or inline code is not a tag, so it is left alone. If any note carries the tag in a way that cannot be changed like that, a list the frontmatter editor would restyle for instance, the plan is refused, names each such note and says why, and nothing is written, because a half-renamed Vault is the thing this exists to prevent. If a write fails partway through, every note already rewritten is put back. A synced Vault records the rename as one commit. Deleting a tag is a separate tool, below. #242
  • Agents can delete a tag across a whole Vault with delete_tag. Before this, the only way to get rid of a tag was to rename it into a junk tag and then strip that by hand. It takes the same two calls as rename_tag: the first writes nothing and lists every note that would change with a plan_hash, and the second applies that plan only if the Vault still produces it. It removes the tag from frontmatter tags lists and does nothing else, and it promises that afterwards a tag search for it finds no notes. That promise is why it refuses, writing nothing, in two cases. If any note carries a tag nested under it, deleting domain while domain/work exists for example, the refusal lists each nested tag and how many notes carry it, since a search for domain would still find those notes. Delete them first, deepest first; there is no cascading delete. And if any note carries the tag as a hashtag in its text, the refusal names those notes, because delete_tag never edits note bodies. A note that loses its last tag keeps an empty tags: [] list rather than losing the key or its frontmatter, and only the removed item changes. Matching ignores case. It is not allowed inside batch. On a synced Vault the delete is one commit that names the tag, which is also how you get a tag back if you deleted the wrong one. #258
  • A sync conflict on a Two-way Git Vault can now be resolved on your Git host, without access to the server (#80). Until now Hatchdoor kept its side of the conflict only in its own checkout, so fixing it meant a shell on the server. The Vault's page now offers Publish my side to a branch, which pushes that side to hatchdoor-recovery/<branch>/<vault id> on the remote. Merge it there, and the next sync picks up by itself. Hatchdoor only ever fast-forwards that branch: it never force-pushes, never touches the Vault's own branch while publishing, and never deletes the branch. Agents get the same action as publish_recovery_branch and read the outcome from list_vaults. A note that is part of the conflict now shows a notice in the editor, and stays editable.
  • Agents can now move attachments of any size without the file passing through the conversation. Until now an agent inside an MCP client had no way to use the bearer download URL or the multipart upload, since it holds neither the MCP token nor the server's address, and base64 through the conversation fails past about a megabyte. get_attachment now returns an absolute download link that carries its own credential, and a new write tool, create_upload_link, makes an upload link for one target path. get_attachment_import_config recommends the links; the bearer route stays as an alternative and import_attachment as the base64 fallback. A link names one Vault and one path and expires five minutes after it is made. A restart, or any change to the MCP token, makes every outstanding link stop working. Turning MCP off refuses every link and turning write mode off refuses every upload, checked when the link is used. A download counts against the MCP tool budget and stops at HATCHDOOR_MCP_MAX_BASE64_BYTES. An upload keeps the HATCHDOOR_MAX_ATTACHMENT_BYTES limit, works once, and checks again that its target is still free. Behind a proxy, set the new HATCHDOOR_PUBLIC_URL setting, from the environment or Settings, to the address links should use. Link signatures never reach a log. #310
  • An agent can import an existing Markdown file as a note without retyping it. create_upload_link with a target ending in .md makes a note upload link, and the uploaded file goes through the same checks and normalisation create_note applies: it must be UTF-8 with no NUL bytes, line endings become LF, a missing final newline is added, and quality warnings come back as usual. Replacing an existing note needs overwrite and the note's expected_content_hash. Hatchdoor checks the hash when the link is made and again when the file arrives, so no link can replace a note that changed in the meantime. Attachment links work exactly as before. #303
  • New links follow the Vault's own link style. Editor autocomplete and the attachment inserts (paste, upload, drop) used to write wikilinks everywhere. A Vault with .obsidian/app.json now gets the form its useMarkdownLinks and newLinkFormat settings ask for, and any other Vault gets whichever form most of its existing links and embeds already use. A wikilink Vault gets exactly what it got before. GET /api/v1/vaults and list_vaults report link_style and link_path_form for each readable Vault so agents can match it; Hatchdoor never rewrites an agent's text to fit, and never writes to .obsidian/. Markdown images written with a root-anchored or bare-name path now render on the note page. #357
  • A Markdown link to a .md file, such as [Trip plan](Plans/Trip.md), now counts as a link to that note, the same as a wikilink. It opens the note inside the app, and it counts toward backlinks, the Links panel, the graph, statistics and the MCP link tools. Renaming, moving or deleting the note updates it: a rename or move changes only the path and keeps the form you wrote, and a delete removes the link and keeps its text. Inline, angle-bracketed and reference-style links are all recognised; links inside code are left alone. resolve-batch gains note_link_targets and note_link_results, an addition existing callers can ignore. #293
  • Maintainers cut a release with two commands. just release-prepare <version> opens the pull request that sets the version and dates the changelog, carrying the release review checklist, beside a draft GitHub Release. A fix the review needs is committed to that pull request's branch and ships in the release; once it merges, the next run opens the release pull request into main. just release-publish <version> refuses until every box on that checklist is ticked, the draft has a title and notes, ## Unreleased on development is empty and nothing has merged into development since the version bump. It then merges the release pull request, tags the merge v<version>, and calls the executable named by HATCHDOOR_RELEASE_HOOK as <hook> images <version> before publishing the release and as <hook> deploy <version> after. Both commands work out where a release stands from git and GitHub, so a re-run after a failure picks up at the step that failed. Neither ever force-pushes, moves a tag or overwrites a published version. #402 #403 #408

Changed

  • The Stats page chart now counts the notes you started each month, where it used to count the notes last touched. It is called Notes created now. The old count broke whenever a Vault's files got new timestamps all at once, which a Git-backed Vault does every time it is cloned or restored, since Git keeps no file times: every note landed in the month of the clone and the rest of the chart went flat. A note's created date now comes from a created: property in the note when it has one that reads as a date, and otherwise, in a Git-backed Vault, from the commit that first added it. A rename or move keeps that date, including a move into the Vault's folder from elsewhere in the repository. A note that was deleted and written again, or copied from another, counts from when that happened. A plain folder with no created: property still falls back to the file's last-changed time, as does a note nobody has committed yet. When a repository was cloned with only part of its history, or its history cannot be read, the chart says under it that some dates are estimated, and while the history is still being read it says that and updates itself when done. The history is read once in the background and kept, not read again for every visit. Modified This Week, the recently changed list and recently_modified still follow the last change, because that is the question they answer. For anyone reading the HTTP API directly: in GET /api/v1/vaults/{vault_id}/stats/detail, each activity_by_month entry's modified_count is renamed to created_count, with no alias, and a new created_date_status field is complete, estimated or reading. #300
  • Git sync no longer waits behind another Vault's indexing. All background work used to share one queue, so a sync or commit could sit for minutes while a large Vault re-embedded. Git, commit and recovery work now run in their own lane, up to four Vaults at once and one at a time per Vault. Indexing and repair keep their single shared slot. A sync still waits for its own Vault's write to finish, but never for an embedding pass. #81
  • An index build that gets cut short no longer starts over. Embedding a large Vault for the first time can take hours on a small server, and a restart, crash or shutdown partway through used to throw away every chunk already embedded, so a restart at 90% meant doing the whole job again. The chunks are now saved to the cache as they are embedded, never more than about ten seconds behind, and the next build picks up from them: only the chunks it has not got yet are embedded, and the progress bar and the time left start from where the last build stopped instead of from zero. A note you edit in between is embedded again; the others are not. Search is unchanged. A Vault becomes searchable only once every chunk is embedded, and until then one that was searchable before keeps answering from its previous index, marked stale. The saved chunks are a disposable part of the cache: a change of search model discards them, removing a Vault deletes them and disabling it keeps them, and deleting the cache still rebuilds everything from your notes. #382
  • A small Vault no longer waits hours behind a large one's first index. Vaults still index one at a time, but a Vault that has been embedding for five minutes now checks whether another Vault is queued, and if one is, it pauses at the next chunk, keeps what it has embedded, and goes to the back of the queue. In the case that prompted this, a 49-note Vault added while a 759-note Vault was embedding for the first time waited about two hours; it now waits about five minutes plus its own indexing. With only one Vault, or nothing waiting, nothing pauses. The large Vault finishes somewhat later while others are waiting, because each time it resumes it reads its notes again. A Vault waiting for its turn now says so: the sidebar, the graph caption and the Settings list show waiting where they used to show it indexing, and GET /api/v1/vaults and list_vaults carry a new index_turn field, running or waiting, absent when nothing is queued. A Vault that was searchable keeps answering from its previous index while it waits. The time left on the All Vaults row counts embedding time only, so it does not run while a Vault waits, and the percent never drops when one resumes. #383
  • The MCP tool descriptions now say two things agents kept tripping over. Every collection read (get_tree, get_graph, get_stats, recently_modified, search_notes, query_notes) explains partial and participants[].state, what stale means, that refresh_vault is the action for a stale Vault, and that collection_revision counts Vault status changes rather than note content. #259 And create_note, update_note, append_to_note, edit_note and replace_section say that they write LF line endings and a final newline, that quality_warnings reports it, and that the returned hash is of the file as written. Behaviour did not change. #260

Fixed

  • During first-run setup with more than one Vault, the indexing progress bar went back to 0% each time the next Vault started, so a three-Vault first index filled the bar three times with no hint of how much was left. Vaults still index one at a time, but the percent and the time left on the All Vaults row now cover the whole job: the bar never moves backwards, and the estimate counts the Vaults still waiting. A waiting Vault is sized from a quick count of its notes until its own indexing starts. With one Vault nothing changes. In /api/startup-status and the model setup status tool, percent and eta_seconds now describe the whole collection, while the note, chunk and token counters still describe the Vault indexing right now. #373

  • The explorer took seconds to appear on a Vault of any size, and got slower as the collection grew rather than as the Vault did. On 600 notes the tree took about nine tenths of a second to answer and the sidebar a little over two seconds to draw; at 2400 notes the read alone was over two seconds, and adding a second Vault slowed down the first one. The cause was that every read that lists notes — the tree, the recently changed list, the graph, the statistics, query_notes — loaded the whole Vault out of the cache first, including the search vectors behind every chunk of every note, and then discarded all of it to send back a list of names and paths. The vectors were 97% of the work and nothing read them: search fetches its own. They are no longer loaded, and neither is the text of your notes, which only the statistics page counts words in and which now asks for it separately. The tree read is around fifteen times faster on 600 notes and thirty on 2400, and it no longer degrades as you connect more Vaults. Two smaller things came out with it. The tree and the recently changed list were each fetched twice on every page load, because the event stream announces the current state when it connects and that was being read as a change; the app now knows which state it already has. And a collapsed folder no longer builds the rows for the notes inside it, which the browser was hiding anyway. One consequence of that last one: your browser's own find-on-page, Ctrl+F, no longer matches a note's name inside a folder you have not opened. Hatchdoor's own search, in the top bar, is unaffected and searches every note whether its folder is open or not. #301

  • An accent was dropped from a note's address rather than folded into it, so correcting a title's spelling moved the note. A slug kept ASCII letters and digits and silently discarded every other character, which made Gerard Veá into gerard-ve and Café into caf. Renaming a note to add the accent it should have had all along therefore changed the address anything outside the Vault was holding, a bookmark or a link pasted into a chat, while the links inside the Vault were rewritten correctly and gave no sign of it. Two quieter faults came out of the same line. A title written with a combining accent instead of a precomposed letter produced a different address than the visually identical precomposed spelling, so a note's address depended on which machine created the file. And a title with no ASCII letters at all produced no slug, leaving the indexer to fall back to untitled, then untitled-2 and untitled-3 in the order it happened to walk the folders, so a Vault written in Cyrillic, Greek or any CJK script had no stable addresses: adding one note could move every other note's. The rule now is that European languages give a plain ASCII address and every other script keeps its own letters. An accent folds to the letter it sits on, so Veá and Vea are one address. The European letters that no accent-stripping reaches are spelled the way their own languages spell them without the letter available: ß becomes ss, ø becomes o, æ becomes ae, œ becomes oe, ł becomes l, đ and ð become d, þ becomes th. Letters and digits from every other writing system are kept as they are, marks included where the script needs them, and nothing is romanised: 資料 stays 資料 rather than turning into zi-liao, which would need a dictionary that cannot tell a Japanese reading from a Chinese one. Punctuation and symbols are still dropped, and a name made only of those still falls back to untitled. The cost is that a note whose name carries an accent or a non-Latin letter moves address once, from wrong to right, and holds it from then on. There is no redirect from the old spelling; it returns note_not_found, because keeping it alive would make the defect a supported way to address a note. Nothing has to be rebuilt to get there. The first index turn after the upgrade notices that the slug it computes for a note no longer matches the one it cached and replaces just those rows. Heading anchors inside a note follow the same rule, so a link to [[Note#Café]] lands where it did before. #306

  • Editing a note failed on some servers while creating one worked, and nothing in Hatchdoor's own log said why. Every save of an existing note, and every rename, move, archive, delete and attachment operation, came back as write_failed: Invalid argument (os error 22) in the client that asked for it. Creating a note still worked, and so did reading, searching and Git sync, so the instance looked healthy. Setting up a Vault from a Git repository failed on the same servers, reporting only that it "could not be installed atomically". The cause is a filesystem feature. Since 2.5.0 a save has been committed by asking the operating system to swap the new copy of the note with the old one in a single step, which is what lets Hatchdoor notice that you also saved the note in Obsidian and refuse rather than overwrite you. Not every filesystem can do that swap. ZFS could not until version 2.2, and Ubuntu 22.04 ships 2.1.5 in its standard kernel, which makes this an ordinary setup rather than an exotic one; anything mounted through FUSE cannot do it either. There was no other way to save, so on those servers there was no way to save at all, and anyone who upgraded from 2.4.0 to 2.5.0 on one lost note editing at that moment with no warning. Nothing was damaged by it: the writes were refused, not half written. Hatchdoor now checks whether the filesystem under each Vault can do the swap, by trying it once rather than by looking at the filesystem's name, and where it cannot, a save checks the note and then replaces it as two steps, which is how Hatchdoor worked before 2.5.0. Everything works again, and the refusals you rely on still refuse: saving against a note that changed under you is still rejected, and moving a note onto a name already taken is still rejected. What you lose is the protection against a change made outside Hatchdoor in the moment between the check and the replacement; that change is overwritten instead of reported. Because that is a real cost, it is said out loud rather than assumed: the log names the Vault once at startup and explains what it means, the Vault's write capabilities carry it so the web UI can tell you, and a save that fails for any filesystem reason is now written to Hatchdoor's log instead of only to your client's. Git-backed Vault setup falls back the same way and its failures now say what went wrong. #345

  • append_to_note, edit_note and replace_section rewrote the line endings of the whole note, not just the part they changed. On a note saved with Windows line endings, a one-word edit_note turned every line into Unix endings and added a final newline, so the Git diff for that edit touched the whole file. These three tools now leave every byte they were not asked to change exactly as it was, including line endings and a missing final newline. Line breaks in the text you send are written in the note's own line ending, CRLF or LF, whichever the note mostly uses. quality_warnings from these tools now names only what happened to your text: a converted line ending, or a line break added before or after it so it does not run into the next line. It no longer claims the note was normalised. append_to_note used to add a separating line break without saying so and now reports it. It also stops trimming the text you send, so a trailing newline you supplied is kept rather than stripped and added back, and leading spaces or blank lines reach the note as you wrote them; text made only of whitespace is still refused. create_note and update_note still normalise the whole note as before. Notes an earlier call already converted stay as they are. #316

  • A #tag search said it had run the mode you asked for when it had not. A query like #project always runs as a tag match, whichever mode it was sent with, but the response echoed the requested semantic or keyword back, so an agent could not tell that its rows came from a tag lookup with every score set to 1 rather than from a ranked search. The response from search_notes and GET /api/v1/vaults/{scope}/search now reports "mode": "tag" for such a query. Every other query still reports the mode it asked for, and tag cannot be sent as a requested mode. A client that only expects semantic or keyword in the response now has a third value to handle. #354

  • Behind a proxy that adds HTTPS, a file link from get_attachment or create_upload_link started with http://, and downloading it as the tool suggested saved the proxy's redirect page instead of the file. The proxy answered the http:// address with a redirect to https://, and curl -o, the example the tool response gives, saved that short HTML page under the file's name and reported success. A client that followed the redirect sent the link, credential included, over plain HTTP first. Hatchdoor only ever saw the plain HTTP hop from the proxy. It now reads the address the client actually used from the proxy's Forwarded header, or else from X-Forwarded-Proto and X-Forwarded-Host, so links start with https:// and the proxy's host with nothing to configure. Caddy, Traefik and Nginx Proxy Manager send those headers by default; plain nginx and openresty need proxy_set_header lines, which the Docker Compose install guide now shows. Public address in Settings still wins whenever it is set, and remains the fix for a proxy that sends neither header or serves Hatchdoor under a path. A value that is not http/https, or not a plain host, is ignored and never fails the call. #358

  • One Markdown file Hatchdoor could not read as text made every rename, move, archive and delete in its Vault fail with a bare 500 internal_error, whichever note you were moving. Before moving a note, Hatchdoor reads every other note to fix the links pointing at it, and it gave up on the first file that was not valid UTF-8, such as a Latin-1 export from an older tool, or that could not be opened at all, such as a broken .md symlink. The error did not name the file, so the only way out was to go looking for it. A file that cannot be opened is now skipped, as the search index already skips it. A file that is not valid UTF-8 is still checked for links: when it has none to what is moving, it is skipped and its bytes are left alone. When it does link there, Hatchdoor cannot fix that link without rewriting the bytes that are not text, so the whole operation is refused before anything is written, with the code link_rewrite_unsupported (409 over HTTP) and a message naming every such note so you can fix them all at once. The same applies to moving or renaming an attachment that such a note references. Renaming or deleting a tag no longer fails on a broken .md symlink either. #360

  • The sidebar never showed conflict or sync stopped for a Git-backed Vault. It looked for two error codes the server never sends, so a sync stopped on a conflict, or on files changed by hand in the checkout, showed the milder amber sync failed. Both now show in red. Neither stops you editing: a note in such a Vault still saves to disk, and only the Vault's commit and sync wait until the problem is dealt with from its settings. #372

  • Opening a note left its folders open in the explorer for good. Showing the note's folders was saved as if you had clicked them open, and closing a folder above the open note was undone as soon as another note inside it opened. Folders opened only to show the current note now close again when you move on, and a folder you close stays closed for that note. #365

  • Opening a folder inside another folder in the explorer showed it open and empty. The outer folder's update wiped out the inner one's. Nested folders now open with their contents. #305

  • Opening a note was slow on a large Vault. Every note read reread every note in the Vault to rebuild the link graph, and the page waited for the note and then its links one after the other; on 4,000 notes that was about six seconds, twice. A note read now only looks up paths, and the link graph is kept until the Vault changes. The page loads the note and its links at the same time and shows the text as soon as it arrives, with the Links panel filling in after. #361

  • Indexing log lines now say which Vault they belong to. The start, progress, link pass, completion and per-note warnings of an index run carried no Vault, so on an instance with several Vaults they could not be told apart. Each now carries the Vault ID, also at RUST_LOG=warn. Only the ID is logged, never the Vault's name, path or remote. #155

  • On a public demo, downloading a note bundled images the demo refuses to serve, such as ones under a demoted layer or an excluded folder. The download now leaves those out and keeps their links as written, the same as for a missing file. Ordinary instances are unchanged. #342

  • On a public demo, every image on a note page made the server walk the whole Vault before sending it, so a note with ten images walked it ten times. The demo now checks images against the list its last indexing pass made, and walks the Vault only before that first pass. One visible difference: an image added to a demo Vault is served once the indexing pass that follows it finishes, usually within seconds, instead of straight away. Ordinary instances are unchanged. #377

  • The Changed on disk panel never showed more than five notes, so its "and N more" line and count could never say more existed. It now shows fifteen, newest first across all Vaults, and the count is right up to 25. Recently viewed keeps its five. #341

  • The server-wide Git commit name and email were missing from Settings on most installs. The rows only appeared when a retired setting that defaults to off was turned on, so a fresh install could neither see nor change the identity every Vault without its own falls back to. They now always show, and their help says a Vault's own commit identity overrides them. #340

  • Opening an address the app does not know, directly or after a reload, gave an empty 404 page instead of the app's own not-found screen. The server now answers with the app and a 404 status. Paths under /api/, /vault-assets/ and /health still get a bare 404. #302

  • Search was slower and less honest than it should have been. One common word in keyword search pulled every matching chunk out of the cache; keyword search now stops at 200 candidates, like semantic search. Semantic scores were computed with the wrong formula, which pushed every hit at or below a similarity of 0.5 down to exactly 0; scores are now the real cosine similarity, so they run higher than before (around 0.6 to 0.7 for a good match where the old formula gave about 0.2). A #tag search over several Vaults could fill its whole limit from the Vault whose folders sort first; each matching Vault now gets a turn. A layer search while a Vault is still loading returns a partial answer instead of an invalid_layer_selection error. When some selected notes have no embeddings, the app now says semantic search could not reach them and that Keyword search can, rather than claiming search is still being built. #328

  • Stopping or restarting Hatchdoor hung while a browser tab or an agent was connected. The live-update stream every tab holds, and MCP's listening connections, never ended on their own, so a stop waited until the supervisor killed the process and the Vault shutdown steps never ran. They now close when shutdown starts; a stop with three connected clients went from over 40 seconds to 0.1. #353

  • Unlocking the web UI did nothing in a browser that blocks site storage, such as Safari with site data blocked: the page reloaded straight back to "Access token required". The token is now kept for the open page when the browser will not store it. A public demo no longer shows first-time visitors model setup buttons that do nothing. An open tab notices when the server restarts in demo mode and drops editing without a reload. An unknown address inside the app shows a Page Not Found screen with a way back to your notes. #339

  • Several Settings pages could get stuck or show the wrong thing. A Vault's page no longer dead-ends after another tab or an agent changes the Vault list: Pause, Resume and Disconnect use the latest state, and a Save that loses the race asks you to save again in plain words. Switching a Vault's Git behaviour resets the fields it hides. The last-change line no longer shows another Vault's date. Each section's Save and Discard affect only that section. The three Settings dialogs now handle focus, Tab and Escape properly. The unsaved-drafts picker says why a Vault cannot take a draft. #338

  • The graph was slow and hard to use on phones. It now draws only what is on screen and caps the number of labels, island captions stay readable as you zoom out, trackpad and mouse-wheel zoom behave the same, touch targets are bigger, tapping the selected note opens it, and a bar offers Open note on every device. An island still being indexed says so instead of showing a note count. #337

  • The graph jumped around on every change. It rebuilt its whole layout whenever anything changed, including a Vault's status during indexing or a Git check. Notes now keep their places, new notes appear next to a linked neighbour, and your pan and zoom stay put; only changing scope or island mode lays it out again. A drag that ends outside the window no longer leaves the graph spinning, and resizing the window keeps the view centred. #336

  • The explorer could stay pinned to a Vault that had been paused, disconnected or had stopped answering, showing nothing but refused reads. A remembered scope naming such a Vault now falls back to All Vaults with a notice. #335

  • Several lists showed a wrong or empty answer when a read failed or only some Vaults answered. A slow answer for all Vaults could overwrite the answer for the one you had narrowed to. The explorer now names Vaults that did not answer and offers Retry when the tree could not load. Changed on disk says it could not load instead of "Nothing has changed on disk yet". On an instance with one Vault, that Vault's condition shows on the Notes heading, stays in view while you scroll, and appears in the top bar on phones. #334

  • When the server could not list the Vaults, the app showed "No Vaults Yet" as if you had none, and could forget the note you had open. It now says the Vaults are unavailable, with Try again, and keeps your place. A note count it does not know shows as a dash, never as 0, and a Vault left out of a partial answer keeps its last count. While the server is unreachable, the startup check backs off from every second to every 30 seconds. #333

  • An app update could reload the page in the middle of a source-mode edit; the reload now waits for that too. Checking for updates while the server was unreachable no longer logs errors, and checks no longer run twice. Installing the app stores 1.8 MB up front instead of 4.8 MB: the diagram and PDF viewers download on first use and then work offline. #332

  • The editor's conflict review and undo could act on the wrong note. A review left open while you moved to another note could resolve one note's text into the other. The review now compares line by line, so one inserted line no longer makes every later line look changed. Ctrl+Z typed into a search box or another field no longer undoes note edits, and the first undo after moving between notes no longer writes the previous note's text over the new one. Dropping an attachment while a block is open lands it on the right line. #331

  • An inline edit could be lost to a crash, a reload, a closed tab or an app update. Only source mode kept a local draft. Every edit now does, including text in a block you still have open, and the draft is written out when the tab closes or is hidden. Reopen the note and the edit comes back with a notice and finishes saving. If the note changed on disk in the meantime, the draft is held rather than written over the newer version. If your browser will not store drafts, a notice says so. #330

  • A batch of robustness fixes: an index run that a newer one replaced no longer reports its Vault ready; saved-query columns show aliases correctly and refuse tags in favour of file.tags; query_notes uses less memory on large Vaults; and create_note without overwrite refuses a file created a moment after it checked, instead of replacing it. #329

  • MCP errors are now structured where they were not. Every failed batch item carries a string code. get_attachment on a file too large for base64 returns attachment_too_large_for_base64 instead of a raw protocol error. While a legacy setup still needs cleaning up, MCP refuses only the tools that change things, with legacy_environment_cleanup_required, instead of refusing every request. Pasting an image into the editor no longer fails with 401 when only an MCP token is configured. A batch with searches in it now counts toward the search limits. #327

  • One Vault failing to index made /ready answer 503 for the whole instance until a restart. Readiness now waits only for every active Vault's first index run to finish, whether it worked or not, and the failure shows on that Vault. A failed index run is retried after 30 seconds, doubling up to five times. A crash inside one Vault's background work no longer stops background work for every Vault. #326

  • A Vault folder could be placed inside Hatchdoor's own state, cache or settings folder, or contain one. Hatchdoor now refuses that with invalid_vault_definition. An unreadable Vault registry is now reported as an error instead of being read as an empty one. #325

  • A note written through Hatchdoor was not always reindexed. Reindexing relied on the file watcher, which did not always exist or see every change. A write now marks search stale and asks for its own reindex, a Git-backed Vault gets a watcher once its first clone lands, and a burst of changes too large for the watcher to report triggers a full rescan. #324

  • Git sync is more careful after a conflict and more honest about failures. A merge that hits a conflict now always puts the checkout back as it was, with no conflict markers left behind, and keeps a note you saved in another editor during the sync. Hatchdoor refuses to commit a checkout that is in the middle of a merge or rebase (managed_git_operation_in_progress) instead of committing the markers. A remote that refuses a push now fails the sync with managed_git_push_rejected, where before the Vault reported a successful sync while nothing reached the remote. A conflict stays on the Vault's status until a sync actually succeeds. Git error messages no longer include paths on the server. #323

  • A Git remote that stopped answering could freeze a Vault until Hatchdoor was restarted. Hatchdoor now gives up after 15 seconds trying to connect or 120 seconds with no data, and tries again later. A clone that failed partway no longer blocks every later attempt. If you run Hatchdoor with your own Compose file, add stop_grace_period: 3m to its service, as the shipped file now does: Docker's default of 10 seconds can kill Hatchdoor in the middle of a sync. #322

  • Two writes could land on the same Vault at once in rare cases. Editing a Vault's settings while a write or sync was running gave the Vault a second, independent lock for a moment. Two batch calls touching the same two Vaults in opposite orders could freeze both until a restart. And renaming a note could overwrite a manual save made to one of its backlinking notes while the rename was running. All three are fixed; the overwritten save now gets a Conflict and survives. #321

  • Renaming, moving, archiving or deleting a note, moving an attachment, or renaming a tag updated the modification time of every note whose links it rewrote, so one batch of renames could make most of a Vault look edited that day. Those notes now keep their original modification times. #299

  • batch named only the first unexpected field it found, so a call with two mistakes took two round trips to fix. It now names all of them at once, along with the shape it accepts, and its description says that vault_id and commit_summary belong on each item rather than on the batch. #297

  • Moving or renaming a note sometimes turned a short backlink into a full path. A link such as [[some-note]], or a title typed with a different dash than the filename, came back with the folder path added even though it never had one. Any link without a folder path now stays short; it only gets the full path when another note already has the new title. #256

  • The Stats page's Writing Activity chart, headed "last 6 months", actually showed the six most recent months that had any notes, which could be years old and not next to each other. It now always shows the last six calendar months, with empty months as zero, and the average is taken over all six. #298

v2.6.1 - 2026-09-08

The follow-up release, and there is nothing new to learn in it. These are the fixes that came out of running v2.6.0 in earnest, plus one tool that should never have gone missing. Vaults that were quietly not committing your notes now commit them. Links inside tables, and links a note makes to itself, stop breaking on rename. The editor puts the caret where you clicked, and query_notes is back.

Added

  • Switching the Vault selector now takes you to that Vault's own last note. Until now it narrowed the sidebar and left the previous Vault's note sitting on screen, so every switch meant hunting for where you had been. Hatchdoor already remembers the note you were last reading and returns you to it when you reopen the app; it now remembers one per Vault and applies the same rule to a switch. Pick a Vault you have not read anything in yet and you land on the empty start page with that Vault's notes in the explorer, rather than on someone else's note. Choosing All Vaults moves you nowhere, and neither does switching while you are in Settings, Statistics or the graph, where the selector is a filter rather than a request to go and read something. A Vault that you remove or pause loses its remembered note, and a note deleted since you last read it shows as missing once, until you open another note in that Vault. #291
  • Agents can now tell which build they are talking to. The MCP server instructions end with the running version, and get_stats reports it as hatchdoor_version. Release builds report the plain version (for example 2.6.1); images built with the new GIT_SHA Docker build arg report it as 2.6.1 (dev abc1234), which also appears in the startup log and MCP serverInfo. #263, #264

Under the hood

No behaviour change, but it affects anyone who builds the image from source.

  • Building the Docker image now requires BuildKit, which current Docker releases use by default. A client pinned to the legacy builder fails outright rather than silently skipping the new cache steps. Cargo's registry, Git checkouts and target/ directory persist between builds through BuildKit cache mounts, so a rebuild after an ordinary source edit reuses the previous compilation instead of repeating it. A new verification build target runs cargo test --locked as a non-root user inside the image. Prune the layer cache and the cache mounts together or not at all; clearing only the mounts leaves the build in a state that recompiles every dependency. #270

Fixed

  • Following a link to another note from inside a note body reloaded the whole app. The explorer, the recently-viewed list and every Vault tree were thrown away and rebuilt from scratch, which on a large collection is a visible wait, and the same click from the sidebar or the Links panel had always been instant. Those links were plain browser links; they now go through the app's own navigation, like every other way of opening a note. Only note links change. An attachment, a PDF and an external link still hand the click to the browser, because that is what opening a file means. A link that carries a heading, [[Note#Section]], still lands on the heading: with the page no longer reloading, Hatchdoor scrolls there itself once the note it names has rendered, rather than the browser doing it on the way in. #294
  • Clicking into the second line of a wrapped list item shoved its text to the right, further the deeper the list was nested. Hatchdoor hides the Markdown you are not looking at, so entering a block slides that hidden syntax out into the left margin and the words you are reading stay put. The leading spaces that carry a wrapped line onto its next line were never treated as hidden, so they arrived as ordinary text and pushed the line over. They are now, and so is the indentation in front of an indented heading or quote, which had the same problem. Two neighbouring faults came out with it. Every heading moved about 23 pixels on entry, indented or not, because the size of its # was being measured in the wrong font, and by a different amount depending on which block you had clicked before it; headings now hold still. An indented code block, the kind written with four leading spaces rather than fences, keeps its spaces on screen on purpose, so it is now left alone instead of being dragged left. One limit worth knowing: the margin a line hides its indentation in is much narrower on a phone than on a desktop, so a heavily nested line still shifts a little there, just less than it did. #286
  • The caret landed too far left in a wrapped or indented block, further off the deeper the nesting went. The map from what you see to your Markdown skipped the block's leading marker once, at the top, and then counted every later line's indentation as text that renders, so clicking the first word of a list item's second line put the caret inside the indent. The map now finds the source line your click fell on and measures within it, skipping that line's own indent and marker. A single-line block has exactly one line, so every answer it gave before is unchanged. A fenced code block had two faults pulling opposite ways: its offset arrived inflated by the language label and the Copy button, which have no character behind them in your Markdown, while the opening fence was read as emphasis followed by the language name. Neither could be fixed alone. The caret is now measured across the code block it landed in, and the fences are skipped whole. #284
  • Clicking into a paragraph that holds a wikilink put the caret somewhere else, usually inside the link's target. Hatchdoor opens a block for editing at the character you clicked, and it works out which character that is from an offset the browser reports. The browser measures that offset inside the one small piece of text under the pointer; Hatchdoor read it as an offset across the whole block. The two agree only when a block is a single unbroken run of text, which is why plain prose had always been right and anything carrying a link, bold, italic or inline code had not. The offset is converted before it is used now, so the caret lands where you clicked. #269
  • Narrowing the Vault selector quietly pinned search to that one Vault, and the search panel's Vault list, the one thing that would have said so, was hidden in exactly that state. A query whose matches lived in another Vault came back as "No matching notes", with nothing on screen to suggest anything had been left out. Search now asks every enabled Vault whatever the sidebar is set to, and the Vault list is always there: it opens on the Vault you were browsing, so what you see first is unchanged, and the other Vaults sit beside it with their match counts, one click away. On a phone the same list is the Scope field under the search box. One consequence worth knowing: a search now shares its 50 results across your whole collection rather than spending them on one Vault, so a single Vault can show fewer rows than it used to. #289
  • Typing quickly into search could take the rest of the app down with it. A semantic search took one of the four available read leases on the database and only then ran your query through the embedding model, which handles one query at a time. Every queued search sat on a lease while touching no database at all, so four keystrokes ahead of the model were enough to hold all four, and anything else arriving, a folder tree, the recent list, another search, was refused immediately with 503 for as long as you kept typing. The query is embedded before a lease is taken now, so a lease covers only the database work. A request that arrives with all four in use waits for the next free one rather than taking an error, because that ceiling exists to bound how many database handles are open at once and was never meant to shed load. #287
  • A note write could be reported as failed after it had already been saved. Hatchdoor commits a conditional write by swapping the new file into place and then reading back what it displaced, to check the note had not changed since you read it. If that read-back failed, the swap was supposed to be undone, but the result of the undo was never checked. The undo needs the same file the read just failed on, so when something outside Hatchdoor removed that file mid-write, the undo failed too and was ignored: the new content stayed saved while the API answered 500, and an agent retrying then got a conflict because the note no longer matched the hash it had sent. One user's server log showed exactly this on a PUT. A write that lands but cannot be verified now reports write_recovery_required and says so in full, naming the note and the leftover file holding the previous content, because only a person can decide what the note should say. The same reporting fix covers two neighbouring cases: a concurrent change that could not be restored, and a fully verified write whose leftover file could not be cleaned up, which used to fail an otherwise perfect save. A write that Hatchdoor did undo still reports the original failure, and nothing about the normal conflict answer changes. Recovery messages carry the note's name only, never the server path it sits at. #288
  • Selecting notes by tag, path or frontmatter property came back. It shipped in v2.3.0 as query_notes, the multi-vault rewrite retired the tool, and nothing replaced it, so "every note tagged project/active", "everything under 40-reference" and "notes whose review-date has passed" had no answer for anyone. A #tag prefix on a search query was the only survivor and it answers the simplest case alone. The tool is back with an explicit Vault scope, like every other collection read: a list of conditions over tags (nested tags included), a Vault-relative folder prefix, and frontmatter properties tested for equality, ordered comparison, existence or emptiness. It selects rather than searches — a note either qualifies or it does not, results come back unranked in the same order every time, and no embedding is involved, so a Vault that is still being indexed answers in full. Nothing about search itself changed. #274
  • Setting one frontmatter field rewrote the whole block. update_frontmatter used to read the block, apply your change, and write the block back out from scratch, which meant it also re-sorted every key into alphabetical order and broke every one-line list, tags: [work, urgent], into a line per item. Nobody asked for either. Across the sample Vaults that ship with Hatchdoor, 530 of the 531 notes with frontmatter write their lists on one line, so in practice an agent doing routine tagging reformatted every note it touched, and the change you actually made was buried in the noise. Only the keys you name change now. Everything else in the block comes back exactly as you wrote it: your key order, your one-line lists, your indentation, your quote marks, your comments, your blank lines. A value like 1.50 stays 1.50 instead of becoming 1.5. A list you replace keeps the shape it had, and a key that did not exist is added at the bottom of the block with any list on one line. Two things are refused now that were not before, in both cases without touching the file: naming a key that the note writes twice, because there is no way to tell which one you meant, and a block laid out so unusually that Hatchdoor cannot edit it without risking the rest of it. Notes an earlier version already reformatted stay as they are; there is no repair pass. #257
  • Renaming a note left that note's links to itself pointing at the name it used to have. The pass that retargets every link to a moving note walks the whole Vault and skipped exactly one note: the one being moved, on the assumption that a note has nothing to say about its own name. A note that links to itself, ordinary enough in an index or a hub page, is the case that assumption misses, and nothing surfaced it. The write reported success and the stale link was counted nowhere. A moving note is now one more note holding links to the target, on rename, move and archive alike, and its self-links follow the same rules as every other note's. The reported count of rewritten notes still means other notes, since the moved note's own change is already reported by the operation itself. Delete is unchanged. #254
  • A wikilink written inside a Markdown table was invisible to everything in Hatchdoor that reads links. A bare | closes a table cell, so an alias in a table has to be escaped as [[Some Note\|alias]]. Every link reader cut the link at the first | without checking what preceded it, so the target came out as Some Note\, the trailing backslash was then read as a folder separator, and the lookup asked for a note that cannot exist. A link resolving to nothing is the one case where leaving it alone is correct, which is why a run of 384 renames broke eight links and reported success. The escape is understood everywhere links are read from, out of one shared place rather than five copies: rename, move, archive and delete retarget such a link and count the note, it appears in outgoing links, backlinks and the graph, resolve_wikilink resolves it to the same note as the unescaped form, the reader renders it labelled with its alias, and ![[image.png\|200]] resolves its image. The escape travels with the rewritten link, so the table row stays valid. An escaped link inside inline code or a fenced block is left byte for byte alone, as an unescaped one already was. Links a previous version already broke are not repaired; the next rename that touches one fixes it. #252
  • An agent could be told its write was refused and not notice. When a tool call fails for an actionable reason, a stale content hash being the common one, Hatchdoor marks the whole result as an error and puts the reason in the result's structured half. Some clients read only that structured half, because every tool publishes a schema for it and that is the documented way to get a typed answer. The problem: the refusal used to arrive with nothing in it saying "this is a refusal", so a client following that path read a rejected rename as a completed one and moved on. One user hit exactly this and only found the missing rename afterwards, by diffing their whole Vault against a snapshot. A refused call now carries ok: false in its structured result alongside the existing code, message and retryable. Nothing else moves: the error flag on the result is unchanged, a successful write still returns ok: true, read results still carry no ok field, per-item results inside batch are untouched, and every tool's published schema is byte for byte what it was. The rule for a client is now simply that an ok field present and false means the call did not happen. #255
  • A file in your Vault that Hatchdoor would not accept as an upload could not be moved, renamed or deleted either, which made every .mp4 clip, voice memo, .csv and .zip permanently immovable. The upload allowlist is a policy about what may enter a Vault; it was being applied to bytes the Vault already stores. Worse was the quiet half: the planner that decides what travels with a moving note did not recognise those files at all, so a note moved to a new folder left its videos behind pointing at nothing, reported success, and list_note_attachments showed no sign of them. Attachment operations now accept any file that is not Markdown, whatever its extension, and every non-Markdown file a note references is listed and travels with it under the existing rules. What may be uploaded is unchanged, and so is what Hatchdoor will display: a video can now be organised but still cannot be fetched or rendered, which the attachment guide spells out. Four things the attachment tools will not touch, some of which the old extension check was only blocking by accident: a note, a .hatchdoor-layer marker, anything under .git, and anything in a folder the Vault excludes as noise, .obsidian/ included. #247
  • A Vault set to Local history committed once, when it was activated, and never again. Every note written after that sat uncommitted until the process restarted, while the Vault reported ready and each write returned success. Two-way had a milder form of the same fault: its commit was bundled into the turn that also fetches and pushes, and that turn runs on the sync schedule, which defaults to once a day. Committing is local, free, and cannot fail for a reason outside your machine; talking to a remote is none of those and already has a schedule you set. They are separate pieces of background work now. The file watcher asks for a commit as soon as your changes land, and asks for it before the search reindex so a commit does not wait out a rebuild that can run for minutes. Fetch, merge and push stay exactly where they were, on the Vault's poll interval. Every way a commit can fail needs a person, so a Vault that hits one stops committing automatically for five minutes, then resumes already owing the turn it missed and catches up on its own once you have fixed the cause. Sync now and Try again stop refusing a Vault that has no remote and commit it instead; the refusal now narrows to a Vault with no Git at all. A Pull-only Vault plans no commit turn, because it refuses writes and has to leave a folder its operator dirtied alone. #267
  • Every write tool advertised a commit_summary, the operating rules handed to agents told them to send one on every write, and the value was read and then dropped. Local history committed with nothing in the message body and two-way committed the literal line hatchdoor: record local Vault changes every turn, so agents spent tokens composing summaries that reached nothing and a Vault's history could not answer why any note changed. The summaries reach the commit now. One commit usually records several writes, so each write's summary waits between landing on disk and being committed, and the commit that records them names itself from the batch: a title saying what changed, then one line per summary. A turn that commits nothing, or fails, keeps the lines it still owes rather than swallowing them. A write from a surface that has no such field still shapes the commit title and simply adds no body line. #249
  • Hatchdoor invented tags out of citation numbers and code samples. A link written as [discussion #1177](https://example.com/x/1177) is one whitespace-separated word, and the test for a namespace slash ran against the whole of it, URL included, while only the leading #1177 was stored. So a bare 1177 was filed as a tag, even though bare numbers are meant to be rejected. The test now runs against the same text that gets stored. Tag extraction is aware of code as well: a hashtag inside a fenced block or an inline code span is not a tag, so a note documenting a tag convention is no longer filed under the tags it documents. Tags are derived from your Markdown, so an existing Vault corrects itself on its next index turn with nothing for you to do. #248
  • A public demo told its visitors they could write to it. The unauthenticated Vault list copied each Vault's capabilities straight from the running instance, where they answer a question about the Vault, is this folder writable, does this source have a remote to pull, is there a failure worth retrying. That is the right answer for an operator, whose request is admitted. On a demo it is the wrong one: every mutating route and every Vault-control route is refused before its handler runs, so mutate, pull and retry all named requests that could only fail, and the live demo advertised mutate: true on all four of its Vaults. No door was open and nothing here weakens the guard; it is a reporting fix, and a demo reports those four as false. Browse and search stay as they were, because those reads do real work on a demo, and a demo Vault sitting on a writable folder still reports that folder read-write next to mutate: false, the same pairing a pull-only Git Vault already has. The authenticated list is unchanged. #243

v2.6.0 - 2026-09-03

The MCP release. Agents get five new tools, a modern protocol revision, and a get_tree that no longer hands over the entire Vault when you asked about one folder. Everyone else gets a Git schedule that actually fires, a read-only mount that actually mounts, and a write layer that stops refusing to rename a note because of the picture sitting next to it.

⚠️ Breaking changes — action required on upgrade

  • GET /api/index-status, GET /api/git-status and GET /api/vault-status are gone, and all three return 404. Each described a single Vault back when there was only ever one. The two Settings consoles they fed, Search index and Versioning, leave the Settings page with them, along with their two-second polling. Each Vault's own settings page keeps its condition, its last error, and its Sync now, Try again and Rebuild search index buttons, and the scope zone and explorer still show a Vault as indexing. Action: point uptime checks at /api/startup-status, which is unchanged and remains the unauthenticated startup probe, and anything asking about a specific Vault at GET /api/v1/vaults, which reports each Vault's condition, its last search or versioning error, and whether it is indexing. Nothing in Hatchdoor's configuration brings the old routes back. #183
  • PATCH /api/settings no longer asks you to confirm git_init or git_downgrade. Those consequences belonged to the instance-wide versioning lifecycle that the retired Versioning console explained, and no current deployment reaches it. A save that turns on local versioning, or switches off remote versioning, now applies on the first request instead of answering 409 and waiting for a resend. Action: remove those two values from any API client, since an unknown consequence is refused as a validation error. reindex is unaffected and still confirmed exactly as before, and per-Vault Git changes keep their own confirmations on /api/v1/vaults/{vault_id}.
  • MCP protocol revisions 2025-03-26 and 2025-06-18 are no longer served. The endpoint advertises and accepts exactly 2026-07-28 and 2025-11-25. A client pinned to a dropped revision is refused on the protocol-version header rather than silently downgraded. Action: if an MCP client stops connecting after this upgrade, check which revision it pins and update it. Nothing in Hatchdoor's own configuration restores the dropped ones.
  • Notes inside a get_tree result no longer carry vault_id. It was a third of the payload, and the tree already names its Vault once at the top. Action: read the Vault from the tree root. Flat results that mix Vaults in one list, search_notes and recently_modified, keep their per-note vault_id and need no change. #211
  • The instance-wide Git and exclusion environment variables no longer do anything at runtime. HATCHDOOR_GIT_SYNC_ENABLED, HATCHDOOR_GIT_REMOTE, HATCHDOOR_GIT_BRANCH, HATCHDOOR_GIT_HTTPS_USERNAME, HATCHDOOR_GIT_HTTPS_TOKEN, HATCHDOOR_GIT_DEBOUNCE_SECONDS and HATCHDOOR_EXCLUDE stay in Settings and keep their values, but nothing acts on them while the server runs. They are inputs to importing a pre-2.5.0 deployment on first boot, and are otherwise only checked for validity at startup. Each Vault's own exclusion patterns and Git mode are what apply, and saving one of these no longer creates or reconfigures a Git repository as a side effect. Action: set exclusions and Git mode per Vault, in that Vault's settings. HATCHDOOR_GIT_AUTHOR_NAME and HATCHDOOR_GIT_AUTHOR_EMAIL are unaffected. They remain the commit identity a Vault without its own falls back to, and a change to either still reaches the next Git turn without a restart. #185

Added

  • Read and write a note's properties without touching its body. get_frontmatter returns the tags, aliases and other keys alone; update_frontmatter merges keys in and leaves your Markdown byte-for-byte identical. #175
  • get_frontmatter also hands back the note's content_hash. Every hash-protected write wants one, and the only way to get one was to pull the whole note body over the wire. A migration over hundreds of notes no longer reads every body to learn a 16-character string. #227
  • get_attachment pulls a file back out of a Vault, the mirror image of importing one. A download URL by default, base64 inline for clients that cannot fetch out of band. #176
  • batch runs up to 50 reads or 20 writes as one call and one commit. Content hashes chain inside it, so an agent can create a note and edit it again later in the same batch without reading it back. Best-effort, no rollback. #177
  • get_tree takes folder, max_depth and include_notes. Asking about one folder used to cost you the whole Vault. On a 530-note Vault the orientation call is 13x smaller than the full tree. #192, #211
  • refresh_vault asks one Vault for its next index turn. Collection reads have always said when they have fallen behind the Markdown, and an agent had no way to act on that: sync_vault and retry_vault both resolve a Git poll interval first and refuse any Vault without a remote, so a plain local Vault had no MCP path to a rebuild at all. It answers queued on an idle Vault and coalesced when a turn is already pending, so repeat requests cannot pile turns onto one Vault. #228
  • Every MCP tool ships an outputSchema, so a client can validate a result instead of inferring its shape. #167
  • The MCP endpoint speaks protocol revision 2026-07-28: stateless discovery, no handshake, and one opt-in subscriptions/listen stream in place of SSE subscribe and unsubscribe. Clients on 2025-11-25 are unaffected. #169, #170
  • MCP now has rate limits. 120 calls a minute per token, 8 concurrent calls and 2 concurrent searches, refused with 429 and a Retry-After. Set HATCHDOOR_MCP_RATE_LIMITS_ENABLED=false to switch them off. #171
  • The Vault asset route accepts an MCP bearer token, so an agent can fetch the URL get_attachment hands it without also holding the web token. It spends the same quota and size limits as any MCP call. #174
  • The public documentation Vault gained Guides, Concepts and a settings reference, and the README links into it rather than duplicating it.
  • The public demo and the documentation site link to each other now. Each demo Vault points at the documentation page behind its layout, and the documentation's layout table links to the live Vault demonstrating each method.

Fixed

  • A Vault on a :ro Docker bind mount refused to come up at all, which is an awkward position for a product that supports read-only browsing. Read-only mounts answer the write probe with EROFS, and only "permission denied" counted as present but not writable. Such a Vault now activates read-only. #178
  • If you redeployed more often than your Git poll interval, a scheduled sync never fired once. Every process start re-armed the countdown from zero, so the only Git turns that ever ran were activations and manual syncs. The schedule was, in the strict sense, decorative. Each Vault now remembers when its last turn completed and resumes the countdown across a restart. #200
  • Straight after a restart, a Vault whose Git credentials were failing reported pending with no error, for up to a day on the default schedule. Activation now republishes the last known outcome, message included. #200
  • A Vault's read model could wedge permanently, and one new note was enough to do it. A slug comes from a filename alone, so two notes with the same stem in different folders compete for it, and the index build tried to give it to the arriving note while the departing one still held it. That failed the whole Index turn, and the next turn seeded from the same snapshot and failed at the same note, forever: get_tree, get_graph and get_stats reported partial at a frozen collection_revision while exact note reads stayed correct. The build now releases a moving slug before any note claims it, and a wedged cache recovers on its first turn with nothing deleted and no cache wiped. #226
  • An Index turn held the Vault's write lock for the whole turn, embedding included, so a write arriving during a multi-minute pass on a CPU-only host did not slow down, it parked. The caller's transport gave up on a write that then landed anyway, which is an at-least-once hazard the moment the caller retries. The lock now covers the turn's read phase only, and a Vault that took a write while it was released publishes itself stale rather than fresh and lets the watcher's catch-up turn sort it out. #223
  • A note holding a real image, PDF or archive could not be moved, renamed, archived or deleted, and neither could the file itself. The check run after an asset move read the file as text, so any byte that was not valid UTF-8 rolled the whole write back with "refusing to move unsafe source". The suite stayed green on this because every attachment fixture wrote the ASCII string png into a file named .png. The check now asserts an ordinary file and reads nothing. #220
  • A note referencing an asset outside its own folder could not be moved at all. The planner assumed every referenced asset was a sibling and built its destination by joining the reference onto the note's folder, so a link such as ../Attachments/image.png carried its .. all the way down to the move primitives, which refuse anything but plain names. An asset now travels with a note only when it already lives inside that note's own folder, or a subfolder of it. One kept elsewhere, such as the shared attachments folder of the usual Obsidian layout, stays exactly where it is; only the moving note's own link is repointed, and no other note is touched. A note in the Vault root has the whole Vault as its folder, so everything it references still travels when it moves. #225, #231
  • rename_note refused any note that kept its picture beside it, and every note in the Vault root. A rename leaves the note in its folder, so an asset in that folder was already sitting at the destination computed for it, and the collision guard could not tell that apart from a genuine collision. A move to nowhere is now recognised as one: nothing moves, nothing is rewritten, and moved_assets reports 0. A different file at an asset's destination still refuses, as before. #238
  • One rename could rewrite a Vault's prose out of the style it was written in. Every backlink to the moved note was retargeted to its full vault-relative path, so [[Some Note]] came back as [[folder/subfolder/Some Note]]. The links still resolved, but the prose got noisier on every rename and nothing rewrote it back. A backlink now keeps the form it was authored in, with the full path as the fallback where the new title is one another note already carries. Aliases, anchors and fenced code are untouched. #235
  • A writer saving faster than the watcher's quiet window deferred freshness for the whole burst. Every qualifying event restarted the 500 ms timer with no upper bound, so no Index turn was armed and the published snapshot could not advance until the writing stopped. The documented ceiling on that window is now enforced, and whichever of the two fires first wins. #229
  • An agent that edited a note was told Hatchdoor was still being set up, on instances that finished setting up months ago, and was then handed model-setup tools that could change nothing. Following that advice produced a second, differently wrong answer. The routine reindex behind the write was sharing one status field with first-run model setup. #191
  • After the backend restarted, the Vault list and its counts stopped updating until you reloaded the page. A new server counts revisions from zero again, and the client read that as stale. #194
  • Opening a Vault's settings page mid-refresh could leave it describing a Vault the Settings index disagreed with for the rest of the visit. #194
  • Dragging the sidebar resizer moved the note path in the topbar and left the pane itself where it was. The layout grid redeclared --sidebar-width at its 280px default, and a local declaration beats the live value inherited from the shell.
  • Asking for a folder that no Vault has picked one Vault at random and blamed it by id. The refusal now names none of them, because none is more at fault than the others. #211
  • Uploading a file called .hatchdoor-layer through the HTTP API silently reclassified a whole subtree as a demoted layer. It now returns 400 layer_marker_write, as the MCP tools always did.
  • In demo mode, an attachment in a hidden layer was still served to anyone who knew its URL. Asset requests now go through the same browse surface as note reads.
  • Every semantic search embedded your query twice, once to retrieve and again during diversity backfill. It embeds it once.
  • Setting HOST=localhost failed to parse and the server refused to start. It is accepted now, and the container health probe follows the listener's address family instead of guessing at it.
  • A large note written through update_note or archive_note held up other MCP traffic while it was written. Both now write off the request thread, the way the HTTP routes always have, which also made three of their error payloads agree with their HTTP twins.
  • The length of your configured bearer token could be measured from outside, because the comparison returned early on a length mismatch. Both sides are hashed to a fixed width first now.

Under the hood

No behaviour change in any of these, but they are why the list above is as short as it is.

  • The /mcp protocol boundary is the rmcp library rather than a hand-written JSON-RPC layer. Tool names, arguments, response shapes and the per-request security ordering are unchanged. #168
  • The legacy single-Vault indexing and Git lane is deleted. Hatchdoor had been carrying a second, unreachable copy of both since v2.5.0. #185
  • Every write, read and management operation crosses one Vault-qualified core now, with HTTP and MCP as thin adapters over it. That is why three MCP error payloads above could stop disagreeing with their HTTP twins. #184, #186, #187, #188
  • Index turns and Git turns run behind a single Vault work executor. #197
  • The frontend reads the Vault collection through one client instead of several. #198
  • The eval harness is behind a non-default eval cargo feature, cutting 17 crates from a default build. #195
  • YAML parsing moved from the archived serde_yaml to serde_yaml_ng. #196
  • The unreachable search filters, and the second semantic retrieval path they gated, are deleted. #210

v2.5.0 - 2026-08-17

  • Attachment embeds written the way Obsidian writes them now render. A bare ![[Some document.pdf]] resolves by filename anywhere in the Vault, rather than only next to the note, so a vault using a single top-level attachments folder no longer shows broken images and PDFs. Note-relative paths keep working, a leading / reads from the Vault root, and where a filename is carried by several files the one nearest the note wins.
  • First startup now makes each Vault browseable from its structure-only cache before vector embedding finishes. Model setup no longer launches a duplicate legacy single-Vault index that held the shared SQLite writer for the entire embedding pass.
  • Existing-Git remote synchronization now selects the unique repository remote matching the Vault's configured HTTPS URL instead of assuming origin, so an unrelated operator-owned SSH origin no longer blocks a migrated Vault.

⚠️ Breaking changes — action required on upgrade

  • A read-only MCP token can no longer upload attachments over HTTP. The multipart attachment endpoint now accepts an MCP bearer token only while MCP and MCP writes are both currently enabled. Previously it accepted that token whenever MCP was enabled, including in read-only mode, while the import_attachment MCP tool already refused: the same credential performing the same action got two different answers depending on which surface it came through. Disabling MCP, or MCP write mode, is now an immediate revocation of that credential's upload capability, checked per request. Unaffected: the web bearer token, which still works regardless of MCP write mode; the web UI's own paste and drop upload, which uses it; and deployments with no token configured, where the route stays open as before. Action: if an agent uploads attachments over HTTP using the MCP bearer token, either enable MCP write mode or move that workflow to the web bearer token. Call get_attachment_import_config to see the methods and limits currently available to a session.
  • A single-Vault deployment is imported into a Vault collection on first start. Your existing vault becomes the first Vault in a registry Hatchdoor stores alongside the cache, and the per-vault environment variables it was configured with (HATCHDOOR_EXCLUDE, the HATCHDOOR_GIT_* family) are read once and stored as that Vault's own settings. Hatchdoor then serves a restricted recovery screen until those obsolete environment lines are removed and the container is restarted. They are per-Vault questions now, and a server-wide answer cannot survive a second Vault. Nothing on disk moves and no note is touched; the import only writes the registry. If it cannot be proven safe, Hatchdoor starts and says what stopped it rather than guessing. Action: leave the variables in place for the first upgraded start, then remove the variables named by Hatchdoor and start it again. Change them in Settings instead, per Vault.
  • Hatchdoor will not activate Vaults while imported per-Vault settings are still set in the environment. Once your Vault owns them, an .env value does nothing: the file and the running server disagree, and every later change made in Settings looks overridden by a line that has no effect. Rather than ignore them quietly, Hatchdoor stops and names each one. VAULT_PATH is exempt, since Compose sets it on every deployment. Action: start once so the import runs, then delete the named HATCHDOOR_GIT_* and HATCHDOOR_EXCLUDE lines from your .env and start again.

Added

  • Hatchdoor holds more than one Vault. Add, pause, and disconnect Vaults from Settings, then browse them together or one at a time. A single-Vault install is unchanged: the collection interface appears only once there is a collection to show.
  • A Vault can be backed by Git. Connect a repository you already have, clone one for Hatchdoor to manage, or keep local history inside a folder you own. Remotes that need one take an access token, and a sync console reports what actually happened rather than a status light.
  • A New note button now sits at the bottom of the sidebar, always reachable without scrolling. The per-folder + stays for creating in a specific folder.
  • A changes panel, opened from the sidebar rail, listing notes that changed on disk. It replaces the old "Last Modified" sidebar list. It deliberately carries no unread count yet: Hatchdoor cannot currently tell an agent's write from your own, and a count that ticked up every time you saved a note would mean the opposite of what it should.
  • Recently viewed is now collapsible, and remembers whether you folded it away.

Changed

  • The sidebar says what you are browsing. A Scope zone at the top switches between one Vault and all of them, each row ending in a note count or the reason there is no count to give. On phones it moves into the topbar as a scope row and a bottom sheet, since the sidebar is a drawer there.
  • The explorer becomes a per-Vault accordion when you browse everything, one Vault unfolded at a time. Narrow to a single Vault and the accordion disappears: a collection of one is just a vault.
  • The graph draws every Vault as its own labelled island in one field, rather than merging separate collections into a single cloud of dots.
  • Search filters by Vault without changing what you are browsing. A rail beside the results on desktop, a Scope field on phones. It narrows only the results in front of you, changes no ranking, and is forgotten when the dialog closes.
  • Search says so when a Vault could not answer, naming it instead of quietly returning fewer results as though that were all there was.
  • Settings is the collection. Every Vault is a section in the settings index, beside the sections that belong to the server itself.
  • The sidebar is restructured into three zones: a fixed rail of whole-vault destinations at top, the scrolling note navigation in the middle, and the create action pinned at the bottom. Only the middle scrolls.
  • Stats and Graph moved out of the sidebar header into that rail, as icons. Settings sits alongside them and is now a live link.
  • Notes in the tree now carry a small index, so note rows and folder rows no longer look identical.
  • The topbar's ··· menu on desktop is left-aligned sentence case with borderless rows, grouped into create/edit, utilities, and destructive actions — with Archive and Delete last. Mobile already looked like this; desktop did not.
  • Interface icons are now Material Symbols Sharp rather than typed unicode characters, so they render consistently across platforms. Attribution is in the new THIRD_PARTY_NOTICES.md.
  • The note Properties heading is now the disclosure itself; the separate Show/Hide button is gone.
  • The create-note dialog is rebuilt. Labels are distinguishable from the fields, the fields are actually visible, the folder chooser is a dropdown with a "New folder…" option instead of a free-text box beside a wall of chips, and a live line shows the path you are about to create.

Fixed

  • The MCP server told agents to call get_attachment_import_config before uploading a file, but the Vault-scoping migration had removed the tool: an agent following the server's own instructions got "Unknown MCP tool". It is restored, now taking one vault_id and reporting the Vault-scoped upload path. It also reports the instance-wide write switch and the Vault's own mutation capability as separate fields, so an agent that cannot upload is told which of the two closed the door instead of guessing.
  • An agent could not create its first Vault over MCP without guessing. The source and credential arguments of create_vault and edit_vault were advertised as bare objects described in a sentence, while the server rejects unknown fields: every guess came back as a rejection with nothing to correct against. Both now publish their real per-variant shapes, including which mode each source accepts, the poll-interval floor, and the fact that a managed Vault has no local-history mode.
  • edit_vault replaces a Vault definition wholesale, so omitting a field cleared it. It said none of this; it now says to read the Vault from list_vaults and send back what you are not changing, and explains what confirm_identity_change consents to and that the Vault must be disabled first.
  • list_note_attachments required MCP write mode, though it only reads. A read-only agent could not see what a note referenced without fetching the whole note. It is now a read tool, and works on Vaults that do not accept writes at all.
  • Opening a note highlighted it in up to three sidebar lists at once. The highlight is now canonical in the folder tree only.
  • Browsing no longer waits on the search index. A Vault's structure is published as soon as it is read, so you can open notes while its vectors are still being built.
  • The explorer kept showing notes, and whole Vaults, after they had left the collection.
  • A public demo deployment no longer reveals local filesystem paths, disabled Vaults, or notes on demoted layers.
  • One unreadable file no longer fails the indexing run for the Vault containing it.

Your notes and folders are untouched, and the cache is not rebuilt. Two upgrade notes apply: the one-time Vault import described above, which is automatic, and the attachment authorization change, which matters only if an agent uploads over HTTP with the MCP bearer token.

v2.4.0 - 2026-07-27

⚠️ Breaking changes — action required on upgrade

  • The MCP attachment staging folder is removed. Agents no longer import attachments by dropping a file into a shared, mounted inbox and calling import_attachment with a staged_filename. Instead, import_attachment now takes the file bytes directly as base64 (content + target_relative_path), and larger files use the existing multipart POST /api/attachment. Action: remove the HATCHDOOR_MCP_ATTACHMENT_STAGING_PATH, HOST_ATTACHMENT_STAGING_PATH, and HATCHDOOR_MCP_ADVERTISE_HOST_PATHS variables from your .env, and delete the attachments-inbox volume mount from your Docker Compose file. Any agent workflow that placed files in the inbox must switch to sending base64 via import_attachment (call get_attachment_import_config to see the methods and limits).
  • HATCHDOOR_MCP_MAX_ATTACHMENT_BYTES is renamed to HATCHDOOR_MAX_ATTACHMENT_BYTES (it caps the web UI and HTTP uploads, not just MCP). Action: rename it in your .env if you set it; otherwise the old name is ignored and the default (10 MiB) applies.
  • The cache schema is upgraded from 7 to 8 for vault layers. The generated SQLite cache is rebuilt on the first startup after upgrade. Source Markdown is unchanged, but the initial indexing run re-embeds the vault.

Added

  • First-run semantic-search setup. Hatchdoor now asks the single user to accept the Gemma terms before downloading the default multilingual EmbeddingGemma model, shows model-download and indexing progress in the UI and logs, and keeps a local acceptance receipt with the persistent model files. Declining Gemma removes its partial files and starts the Nomic Embed Text v1.5 fallback; Nomic is explicitly identified as English-only and lower quality for multilingual vaults. Public images ship neither model.
  • Direct attachment upload for agents: the import_attachment MCP tool accepts base64 file bytes inline (universal fallback for any MCP client), capped by the new HATCHDOOR_MCP_MAX_BASE64_BYTES (default 5 MiB, measured on the decoded file). get_attachment_import_config now enumerates both upload methods, their size limits, and which to use.
  • Vault layers: add a .hatchdoor-layer marker to a folder to place its notes on a named, demoted surface. Browser routes remain default-surface only; MCP clients can explicitly select named layers.
  • HATCHDOOR_EXCLUDE for comma-separated gitignore-style noise patterns, HATCHDOOR_EMBED_LAYERS to opt demoted layers out of vector embedding, and diagnostics via GET /api/diagnostics or the layer_diagnostics MCP tool.
  • Layer-aware note-write and attachment responses, so automation can tell which surface a created, moved, archived, or uploaded item belongs to.
  • Cross-platform inline previews for linked PDF vault assets, with internal PDF links resolving as vault assets rather than ordinary note links.

Changed

  • The /mcp request-body limit is raised to fit base64 attachment inflation so a legitimately sized upload is not rejected before the tool's own size check.
  • POST /api/attachment now accepts the MCP bearer token as an alternative to the web bearer token, so an agent uploading larger files over HTTP can reuse its existing MCP credential instead of needing HATCHDOOR_WEB_BEARER_TOKEN provisioned separately. The rest of the web API is unaffected — this route was pulled out of the shared protected-routes group so the MCP token is not granted any broader access.
  • Built-in noise exclusions now omit .obsidian/, .trash/, .hatchdoor-trash/, .DS_Store, *.tmp, and *.sync-conflict-* from the index. In particular, Markdown under .obsidian/ or .trash/ and Syncthing conflict copies are no longer searchable unless a deployment negates the relevant default with HATCHDOOR_EXCLUDE.
  • FastEmbed is upgraded from v4 to v5. Each chunk is now embedded with its note title and heading path as context, improving retrieval relevance while preserving chunk-level search results.

v2.3.0 - 2026-07-19

Added

  • The UI is now available during initial indexing and shows live token-weighted progress, note/chunk counts, and a measured ETA while vault and MCP data remain unavailable until the index commits.
  • Indexing logs a human-readable heartbeat every minute and detailed performance diagnostics at debug level.
  • MCP search_notes now supports exact tag, path-prefix, property-existence, and typed property-equality filters with explicit property projection.
  • Added the metadata-only query_notes MCP tool and structured tags, aliases, and frontmatter properties to get_note.

Changed

  • Chunks are embedded individually to avoid batch-longest padding and reduce peak memory pressure.
  • The cache schema is upgraded to version 6 for note-level frontmatter metadata. The first 2.3.0 startup automatically rebuilds the generated SQLite cache from the Markdown vault.
  • Rust and frontend dependencies are refreshed within their current compatibility lines, including git2 0.21, resolving the current RustSec and npm audit findings.

v2.1.1 - 2026-06-13

Security, performance, and operational hardening from the 2026-06-11 codebase audit, plus an iOS PWA download fix.

Fixed

  • Markdown downloads no longer arrive as HTML on iOS standalone PWAs. The service worker's SPA navigation fallback was intercepting /api/*, /vault-assets/*, and /health navigations (iOS ignores the <a download> attribute and treats the click as a navigation) and serving the cached index.html. Added a navigateFallbackDenylist so those requests reach the network.

Security

  • Added optional web API authentication: when HATCHDOOR_WEB_BEARER_TOKEN is set, all /api/* routes, /vault-assets/*, and note downloads require the token (via Authorization: Bearer header or access_token query parameter). The PWA prompts for the token on a 401. (F-01)
  • Changed the default bind host to 127.0.0.1; exposing on 0.0.0.0 is now an explicit opt-in documented to require auth or a reverse proxy. (F-01)
  • Coalesced concurrent /api/refresh requests so a request loop can no longer trigger overlapping full reindexes. (F-02)
  • Compared bearer tokens (MCP and web) in constant time. (F-06)
  • Served SVG vault assets with Content-Security-Policy: sandbox and Content-Disposition: attachment to neutralize script execution on direct navigation. (F-09)
  • Stopped leaking absolute filesystem paths and raw internal error strings in HTTP error bodies; details now go to logs only. (F-10)
  • Capped POST /api/resolve-batch at 200 targets. (F-11)

Performance

  • Moved vault reindexing, embedding, and query embedding off the async runtime via spawn_blocking, holding the cache write lock only for the final swap so reads no longer freeze during a refresh. (F-03)
  • MCP write tools now resolve the target note from the SQLite cache instead of rebuilding the full vault index from disk on every write. (F-04)
  • Enabled SQLite WAL mode and added a pooled set of read connections so concurrent reads run in parallel instead of serializing on a single mutex. (F-05)

Correctness & operations

  • Validated McpConfig once at startup (failing fast when write mode is enabled without a bearer token) instead of re-parsing the environment on every MCP request. (F-07)
  • Git sync now refuses to force-checkout over uncommitted manual edits to tracked vault files, surfacing them as an error instead of silently discarding them. (F-08)
  • Moved the hard-coded 90-archive/ prefix to HATCHDOOR_ARCHIVE_PREFIX. (F-12)
  • Added a CI workflow (fmt, clippy, test for the backend; lint, typecheck, test, build for the frontend) and a Docker Compose healthcheck. (F-13)
  • The SSE vault-events stream now emits the current revision on broadcast lag instead of silently dropping it, so a slow client always resyncs. (F-16)
  • /health now runs a SELECT 1 against the cache so it reports unhealthy if the database is unreachable, and the binary gained a --healthcheck mode for the container probe. (F-17)

v2.1.0 - 2026-06-xx

Added

  • Optional automatic git sync of the vault: successful MCP write tools commit and push changes to the configured remote with debounced batching, conflict-abort semantics, and an immediate flush of stranded commits on startup.
  • get_git_sync_status MCP tool and a git-sync warning on write-tool responses.

Changed

  • Richer git sync status reporting with plural-aware commit messages.

Fixed

  • Enabled the git2 https feature for TLS remote transport.
  • The vault watcher now ignores .git/ so sync churn does not trigger reindexing.

v2.0.0 - 2026-xx-xx

Added

  • SQLite read model (FTS5 + sqlite-vec embeddings) backing the vault index, with chunking, embedding, and hybrid/semantic/keyword retrieval.
  • Streamable-HTTP MCP endpoint exposing read tools always and write tools (create/update/edit/replace-section/append/move/rename/delete notes and attachments) gated by env flag and bearer token.

Changed

  • Pinned the Rust toolchain to 1.96.0 and reformatted the tree.

v1.1.0 - 2026-02-20

Compared with v1.0.0.

Added

  • Added a Download .md action in the note actions menu.
  • Added a server download endpoint: GET /api/note/{slug}/download.

Changed

  • Switched markdown download flow to server-driven delivery for native mobile handoff.
  • Updated frontend download trigger to use an anchor download flow instead of popup navigation.
  • Added UTF-8-aware filename handling in Content-Disposition for markdown downloads.

Fixed

  • Improved iOS/Safari file handoff behavior for .md downloads by using attachment headers.
  • Added and updated frontend/backend tests for the download path and response headers.