Your vault and backups

Your vault is the folder you chose when you set up Wrengle: an ordinary folder of Markdown notes, plus the local metadata Wrengle keeps alongside them. Rename it, move it, or back it up like any other folder on your machine — as long as you know what has to travel with your notes for the copy to be complete.

Live document sync

Sync is optional and off by default. It needs a signed-in Wrengle account and is turned on per vault from Settings → Account. When it is on, that vault's notes, charts, whiteboards, whiteboard images, note frontmatter, and folder structure are kept the same on your own computers, including documents you do not have open. Attachments outside whiteboards do not sync. Server copies are encrypted in transit and at rest, but Wrengle can technically read them to operate the service. Turning sync off keeps your local files and does not delete existing server copies. The full guide — what is stored, devices, removing a vault from the server, and the 30-day retention window — is Sync across your computers.

Do not combine Wrengle sync with a service such as Dropbox or iCloud mirroring the same vault; independently mirrored recovery data is not a shared lock.

Naming and moving files

Note and folder names in your vault follow one naming scheme, on every platform, including Windows. Wrengle won't create or rename something to a name that Windows can't represent safely, that hides part of the path, that's ambiguous only by case or Unicode formatting, or that collides with an old-style short name — even on a filesystem that would otherwise allow it. Moving or renaming into a different folder requires that folder to already exist first; the file tree creates or selects it for you before it lets you complete the move.

Vaults with older, non-portable names still open and read normally, and you can rename them into the new scheme whenever you like. Each name you create or rename — including the file extension, like .md, .wrchart, or .wrboard — has to fit in both 231 UTF-8 bytes and 231 UTF-16 code units. That leaves enough room, on every filesystem Wrengle supports, for the hidden crash-recovery backup file described below. A longer, legacy name can still be opened, deleted, or renamed as-is, but it has to be renamed into the new scheme before Wrengle will save new content to it.

Back up your vault

Back up the whole vault folder, not just your notes. That's the only way to also capture chart and whiteboard files, whiteboard image assets, reusable whiteboard libraries, sidecar metadata, action references, meeting recovery state, and the rest of Wrengle's local app metadata alongside them. If you only copy an individual note, chart, or whiteboard file, you get the saved document itself, but not every referenced asset or piece of app-managed recovery state behind it. Include hidden folders in the copy: each vault's reusable whiteboard library lives at .app/whiteboard-library.excalidrawlib. A separate .excalidrawlib export is also available from the whiteboard Library panel.

A vault-folder backup does not include the private search index — see What Wrengle stores where, below. That's fine: no saved note content is lost, since the index rebuilds itself from your vault. If the index is missing or out of date, though, your local-only search preferences and workspace layout reset.

Wrengle also keeps a Git history inside your vault, for note history. It excludes your assets/ folder, plus the whole .app/ folder — sidecars, action state, reusable whiteboard libraries, local recovery, and meeting recovery — and it also excludes Wrengle's own temporary and replacement-backup files wherever they appear next to your documents, so an ordinary external Git scan won't pick up crash-left files by accident. Git history is not a substitute for an independent backup. Ignoring a file going forward doesn't retroactively remove it from history if it was already tracked; if you need to remove a previously tracked recovery file, do that only after you've saved the version you need and finished the manual reconciliation described below.

A separate workflow.db file, outside your vault, holds Workflows connection and recovery data, and it is not included in a vault-folder backup. The Workflows builder uses it for your Gmail connection, encrypted prepared draft intents, and full recovery snapshots — the workflow's configuration, objective, artifact bodies and paths, and manager and audit state — plus approval recovery and content-safe bridge receipts. It doesn't give you a second place to author workflows, and it isn't a general durable run history.

Prepared Gmail draft payloads can stay encrypted in workflow.db for seven days; only the newer bridge's content-safe plaintext metadata, opaque keyed request bindings, or receipts can stay for 90 days. The recipient and subject you typed for a Gmail step live in your ordinary local workflow settings until you edit or delete them — they aren't on that seven-day clock. Older, preview-authored workflow definitions and revisions can also hold plaintext names, descriptions, and action configuration, and they remain until you clean up app data or uninstall; the seven-day rule doesn't cover them either.

The encrypted content in workflow.db only unlocks with a matching key in your operating system's keychain, on that same installation. If you have a Gmail draft still waiting for approval, back up the database and keep using that installation — copying the database alone, without that keychain item, only gives you an archive you can't unlock elsewhere. Your current workflow drafts, schedules, and the version pinned as live also live in local app settings rather than as vault documents, so moving to a new installation needs an app-settings backup too, not just your vault.

What Wrengle stores where

Wrengle keeps local data in one of three places: inside your vault, in a .app folder beside your notes, or in a private folder outside the vault entirely. Which place depends on the feature.

Plugin capability grants are local, app-install decisions. Plugin settings are scoped by plugin and matched to your vault by file path, so they never mix between plugins. Secret values a plugin needs, such as an API key, live in the operating-system keychain, not in note files. Before a plugin can write to a note, it always creates a proposal for you to approve first — see How Wrengle works.

Wrengle preloads any secure items a plugin, action, workflow, or provider is already configured to use into a protected area of memory before the workspace opens. This never copies anything into your vault or its backup, and the preload itself never runs a plugin, action, workflow, or provider, and never makes a network request.

Wrengle keeps its own recovery state for open notes, charts, and whiteboards in a vault .app folder beside your notes. A local database there, .app/crdt.db, can restore recent unsaved document state after a reload or an ordinary crash. This database stays on your device. Separately enabled live document sync sends validated note and chart state to Wrengle; it does not upload the database file or whiteboard recovery.

Wrengle binds every operation to the exact folder identity of your vault root, captured the moment you open it. If that root folder is replaced, Wrengle fails closed instead of using it. If the .app folder inside it turns out to be a symlink or reparse point standing in for the real one, Wrengle fails closed there too: it refuses that linked .app folder rather than write through it.

The search/RAG index — the private, rebuildable index Wrengle searches against — lives in Wrengle's private OS app-data folder, outside vault sync or backup. It holds derived copies of note text, and it rejects any symlinked or hardlinked database target. It is safe to delete and rebuild: delete it, and Wrengle rebuilds it from your vault notes, though your local-only index preferences and workspace layout reset.

Wrengle also keeps a small maintenance queue of its own, in a state.db file in that same private app-data folder. It records operation labels and vault-relative file paths — never note bodies or content hashes. If that queue can't accept an entry right after a file operation finishes, Wrengle keeps a separate, equally body-free record instead, and keeps retrying it. A note or chart save, and its local recovery update, are complete on disk before Wrengle reports the save finished; rebuilding the search index and recording Git history checkpoints happen afterward, in the background. Related edits and file operations can be grouped into a single Git checkpoint, so Git history reflects meaningful points in your work rather than one commit per keystroke. Opening History first finishes any Git work still queued. A clean quit tries to make a final checkpoint; interrupted work is replayed the next time you open the vault. Deleting state.db can lose some queued maintenance work, but reopening the vault rebuilds the search index and runs a Git recovery pass from your current saved files.

If Wrengle cannot safely open state.db at startup because it is inaccessible, corrupt, or belongs to a newer app version, it leaves the file untouched and shows a recovery banner. Your vault notes and editing stay available, but background job, maintenance, and cache queues use session-only storage until you repair access or install a compatible Wrengle version and restart. Do not delete or replace the preserved database unless support or your recovery plan specifically calls for it.

Wrengle refuses to write through a hardlink or a symlink. Ordinary document and editor-sidecar operations, plus privacy-sensitive recovery inputs, reject hardlinked files, unsafe symlink/reparse paths, and parent or target identity swaps. This single-link/no-follow rule is scoped to those app-managed document, sidecar, and recovery paths — it does not describe every file you might keep in a vault.

If Wrengle needs to repair something

If your local recovery state ever looks inconsistent with a note, chart, or whiteboard path, Wrengle fails closed instead of silently replacing it with your saved version. Opening, moving, deleting, saving, or switching vaults can all surface a repair-needed message until that local recovery metadata is reset or repaired.

If recovered content can't be represented as valid Markdown, or an older recovery bug stored part of a note in a degraded form, Wrengle shows your saved Markdown in a read-only preview with Reset local recovery. The reset is always explicit: it discards unsaved recovery only for that document, leaves the saved Markdown, chart projection, whiteboard projection, and whiteboard image assets unchanged, and starts a fresh local recovery copy from the saved file. If Copy recovered Markdown is offered, use it first if you want to keep the malformed local version, and check the saved preview before you confirm. If Wrengle closes while a reset is running, the note reopens in that same read-only recovery state until the saved and recovered versions have been reconciled and durably recorded.

An older version of Wrengle can't always read newer local recovery data. Opening older recovery data with a newer Wrengle build upgrades it automatically, keeping your existing vault and document IDs unchanged. Go back to an older build afterward, and — depending on which recovery data changed — it will either refuse to open that upgraded copy outright, or just report local recovery as unavailable for that vault. Either way, your saved Markdown notes and chart files are never affected — only the unsaved-edit recovery copy is. Reopen the vault with the build that did the upgrade, or a newer one. Do not delete individual files under .app/ to work around this; restore the whole folder together instead, rather than mixing recovery files from different versions or installs.

If an older Wrengle build ever lost track of which recovery record belonged to which note — this could happen during simultaneous note opens — opening the affected note today leaves your saved file and that orphaned recovery record both untouched, and offers Recover local state. Nothing is overwritten until you make that choice. A chart reconnects to its own recovery record automatically, but only when the saved chart file still points at the exact same record. Both paths need an existing, healthy same-vault recovery index first — free of any path, kind, tombstone, or pending-operation conflict — before Wrengle will offer either one; a missing index, or an owner it can't resolve, stays a repair-needed message instead.

The local recovery database has a 256 MiB safety limit, and there's a separate 16 MiB internal limit on the metadata a migration between recovery-format versions can process at once — oversized or corrupted metadata fails closed instead of migrating partway. Automatic snapshot compaction isn't available in this build, so recovery history can grow up to that 256 MiB cap. Notes, chart files, and editor sidecars themselves have their own, separate 16 MiB per-file read limit. If an update is interrupted partway through a migration, Wrengle finishes or safely discards the incomplete step the next time it starts. Wrengle also refuses to use an interrupted-replace database backup without proof it committed cleanly, even if a database file appears to be in place; it leaves that backup untouched for you to repair explicitly, rather than risk rolling back to stale recovery state.

If Wrengle is interrupted while replacing a file, it leaves the previous version as a hidden sibling named .filename.wrengle-replace-backup (older versions used a random ID in the name instead; Wrengle still recognizes and cleans up those older names once, when it opens the vault). While Wrengle still recognizes that file from the process that created it, it only ever retries cleaning it up itself, and never copies the old bytes back over a later external replacement. After a crash, Wrengle can no longer tell which process owns it, so it treats the hidden backup as untouchable: it won't restore it, won't delete it, and it blocks normal saving and autosaving for that file until you resolve it by hand. Reopening the app does not clear this on its own.

To resolve one by hand: close Wrengle, make an independent copy of the whole vault, and compare the visible file with every hidden backup next to it in that folder. Save the version you want to keep under a new, ordinary filename. Only then move the matching hidden backup out of the vault (or delete it), reopen Wrengle, and reload the visible file before saving again. Do not rename a hidden backup directly over the visible file, and do not delete similarly named files in bulk. If you can't tell which version is right, leave both alone, restore from your own backup, or contact support.

Restoring and undoing changes

If a restore's Git checkpoint can't be confirmed yet, History still keeps the verified pre-restore undo point available and shows a recovery warning while it keeps retrying the checkpoint. Restoring a note whose folder was deleted after the commit recreates the missing folders on the way back, so History still reaches versions of a note whose folder is gone.

If you keep editing while a restore or undo is running, Wrengle keeps your newer edits open instead of overwriting them with the restored version. It never shows a misleading success or undo action; save your newer edits, or reopen the note, to reconcile them with the version that was restored on disk.

If Wrengle can't confirm the exact file and bytes it just saved, the editor keeps that document marked unsaved and blocks further manual and automatic saves for that tab. Reopen and reconcile the on-disk file before saving again — Wrengle never assumes its saved copy still matches what's on disk.

Renaming, moving, or deleting an open note waits for any in-progress local recovery updates to finish first. If an edit is temporarily rejected while saving, Wrengle cancels the rename or move until that edit is fixed — retry the operation once the note is valid again.

Meeting recovery and your privacy

Temporary meeting recovery records are app-managed local files, not saved notes. While recording, finalizing, saving, and generating a report, Wrengle writes versioned recovery records under .app/live/. They can hold completed transcript text, the meeting context you selected, the exact note and identity they belong to, what's been sent to a provider so far, and one in-progress report revision. Long-report checkpoints can contain derived summary, decision, action-item, follow-up, discussion, and open-question content from completed transcript shards. The complete rendered report draft stays in memory, and raw meeting audio never enters the vault recovery record. Before Wrengle sends anything to a cloud provider for a report, it records a separate content-free marker so an interrupted request is never silently retried behind your back; that exposure marker contains no report text. Wrengle deletes these records once a meeting is safely saved or reported, once you recover or discard them, or once cleanup finds nothing worth keeping.

Current recovery sessions page live and final transcript records into bounded 256-record files. Long report generation checkpoints the contiguous transcript evidence it has already covered. These files remain subject to aggregate read limits and are recovery state, not a second transcript archive.

Raw meeting audio follows a different boundary. It is stored as encrypted, authenticated blocks under Wrengle's private operating-system app-data directory, outside the vault, .app/live/, vault sync, and vault Git history. Wrengle removes that timeline after canonical finalization succeeds and retains it when finalization needs attention. Backing up only the vault therefore does not back up retained meeting audio; use the in-app recovery flow on the same device before deleting app data.

Because .app/live/ sits inside your vault, whatever you point at the vault folder — a backup drive, an external file-sync service — receives these records too, while they exist. They are not guaranteed to stay only on the machine that recorded the meeting.

While a meeting is recording, Wrengle also keeps a small, content-free marker showing which process currently owns that recovery record, refreshed every 15 seconds. If Wrengle quits unexpectedly, that marker goes stale, and after about two minutes the record becomes eligible for recovery the next time you open the vault. A synced copy of that marker on another device isn't a live lock — it can be stale or out of sync — so don't try to recover the same waiting item from two synced devices at once.

On Unix, a filesystem remount can change only the device identifier of the same lock file. Recovery discovery can safely re-attest a released marker in that narrow case while holding the current file lock and advancing its generation. It does not rebind the meeting note. Fresh ownership, replaced files, and malformed markers continue to fail closed. Independent synced copies remain outside the locking guarantee and must not be recovered concurrently.

.app/live/ is not a transcript archive. Back up the whole vault if you specifically need to preserve an item that's still waiting for your decision. If cleanup itself ever fails, Wrengle shows a cleanup-needed entry instead of leaving stale records hidden.

Wrengle limits how much recovery data it will scan at once. An oversized or corrupted session is set aside as unsupported — you can only discard it — while Wrengle keeps scanning the rest normally. If the ownership marker for one session is unreadable or too large, that session stays hidden while its valid siblings keep scanning. If the whole scan runs over its own limit, Wrengle fails closed rather than show you an incomplete list.

Import and export

If Wrengle can verify the exact file it just saved, it inserts the attachment even if a later step still needs a repair — you'll see a warning, and you shouldn't retry that import until the vault is reopened or repaired. If Wrengle can't verify that exact saved file, it skips inserting the attachment block entirely and blocks repeat imports for the rest of that vault session, so it never creates duplicate files it can't account for.

Keep independent backups

Wrengle is in beta. Keep independent backups of anything that matters, and check Known limitations before you rely on meeting, AI, or plugin workflows for work you can't afford to lose.

Where to go next

• How Wrengle works — the full picture of what stays local and what reaches the network.
• Getting started — choose a folder and write your first note.
• AI and privacy — the data boundary for every AI feature.
• Known limitations — what this release does not do yet.