Vault, data, and backup

Wrengle is designed around local ownership. Your vault is the folder that contains your notes and app-managed local metadata.

What is local

Notes live in local files. App metadata, sidecar data, local indexes, temporary meeting recovery records, and plugin-managed state are kept with or beside the vault depending on the feature.

Plugin capability grants are local app-install decisions. Plugin-scoped JSON state and secret aliases are separated by plugin id and canonical local path identity; secret values live in the OS keychain rather than in note files. Write capabilities create app-mediated write proposals before notes or blocks change. Configured app-owned secure items are preloaded into a zeroizing native session cache before the workspace opens. They are never copied into the vault or its backup, and the preload does not run a plugin, action, workflow, provider, or network request.

Wrengle also keeps local recovery state for open notes and chart documents in vault app data. The local CRDT database under .app/crdt.db can restore recent unsaved editor or chart state after an app reload or ordinary crash. It is local-only; it is not server sync, presence, or cross-device collaboration.

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

If recovered note content cannot be represented as valid Markdown, or a historical recovery bug stored a Wrengle-managed region as degraded raw source, Wrengle shows the saved Markdown in a read-only preview with Reset local recovery. The reset is always explicit: it discards unsaved recovery only for that note, keeps the Markdown file unchanged, and creates a fresh local recovery identity from the saved file. When Copy recovered Markdown is offered, use it first if you want to preserve the malformed local version, and check the saved preview before confirming. If Wrengle closes during a reset, the note reopens in the same read-only recovery state until the saved and recovered versions have been reconciled and durably recorded.

After the first note reset, the vault's local CRDT identity index uses schema v3 to keep the old-to-new identity lineage downgrade-safe. Older builds that only understand v2 can report local recovery as unavailable, but the saved Markdown is unaffected. Reopen the vault with the resetting build or a newer build instead of deleting individual files under .app/.

An older Wrengle build could lose a single path mapping during concurrent document opens even though .app/crdt.db still retained that document's payload. Markdown does not carry durable document identity, so opening the affected path leaves both the saved file and local payload untouched and offers Recover local state. Wrengle attaches the historical payload only after that explicit choice. A chart can reconnect automatically only when its valid saved projection names the exact same database-owned document ID. Both paths require an existing same-vault index with no path, kind, tombstone, or pending operation conflict, and the backend retains its app-owned store locks through candidate lookup, secure file revalidation, and identity publication. A missing whole index or ambiguous owner remains repair-needed.

When Wrengle migrates well-formed legacy CRDT identity metadata up to the 16 MiB identity-metadata safety limit from schema v1 to v2, it preserves the existing vault and document IDs and permanently retires the v1 identity index. Oversized or malformed identity state fails closed. This is a downgrade boundary: older builds that only understand v1 cannot reopen that migrated recovery state. Do not delete individual identity or migration files. Restore the full .app/ tree together so the v2 identity index, migration and advancement journals, and CRDT database keep the same identity lineage. The advancement journal is normally short-lived; if an update is interrupted, startup uses it to finish a published transition or discard one that was only prepared.

The local CRDT database has a 256 MiB safety limit. Wrengle also refuses to use an interrupted-replace database backup without durable commit-lineage proof, even if a canonical database image is present. It leaves the backup untouched for explicit repair instead of risking rollback to stale recovery state. Automatic snapshot compaction is not available in this build, so recovery history can grow to the cap. Where the repair UI offers Reset local recovery, that action removes the affected document's local recovery payload but keeps its saved Markdown or chart projection.

Ordinary Markdown notes, chart projection files, and editor sidecars have a 16 MiB per-file read limit. Wrengle opens those files and performs app-owned create, replace, and sidecar cleanup through identity-bound, no-follow filesystem operations. Hardlinked files, symlink or reparse-point paths, and a parent or target replaced by sync software during an operation fail closed instead of redirecting the read or mutation outside the vault.

Wrengle binds later operations to the exact canonical vault-root identity captured when the vault opens. Replacing that root, or using a symlink/reparse point for the managed .app layout, fails closed; Wrengle explicitly rejects that linked .app layout. The rebuildable search/RAG index is stored in Wrengle's private OS app-data directory, outside vault sync or backup. It can contain derived copies of note text and rejects symlinked or hardlinked database targets. Search content is safe to delete and rebuild from vault notes; deleting the index also resets local-only index preferences and workspace layout metadata.

What to back up

Back up the full vault folder, not only individual notes. That preserves notes, chart projection files, sidecar metadata, action references, meeting state, local app metadata, and other state that makes the workspace useful.

A vault-folder backup does not include the private OS app-data search index. That omission does not remove saved note content because the searchable copies are rebuilt from the vault, but local-only index preferences and workspace layout metadata reset if the app-data index is deleted or not migrated.

Wrengle keeps a private OS app-data workflow.db as a connection and durable effect foundation. It is not part of a vault-folder backup. The existing Workflows builder uses it for Gmail connection metadata plus encrypted prepared draft intents and complete recovery snapshots (workflow configuration, objective, artifact bodies and paths, manager/audit state), approval recovery, and content-safe bridge receipts; it does not expose a second authoring experience or general durable run history. Prepared Gmail payloads can remain encrypted for seven days, while only the new bridge's content-safe plaintext metadata, opaque keyed request bindings, or receipts can remain for 90 days. Editable Gmail recipient and subject values remain in normal local workflow settings until edited or deleted. Legacy preview-authored definitions and revisions can contain plaintext names, descriptions, and action configuration and remain until explicit app-data cleanup or uninstall; they are not covered by the seven-day payload rule.

Encrypted workflow.db content is device/install-bound to a matching operating-system keychain item. Preserve the database separately on the same installation if you need a waiting Gmail approval. A database copy by itself is only an archival copy on another installation unless the matching keychain item is also still available; vault backup does not include that key. Current workflow drafts, schedules, and pinned live versions remain in local app settings rather than as vault documents, so they also require an app-settings backup when moving to another installation.

Wrengle initializes git inside the vault for note history. Assets and the complete app-managed .app/ tree—including sidecars, action state, local CRDT recovery, and temporary meeting recovery—are excluded from that history. Git history is not a substitute for an independent backup.

Include the full vault folder, including vault .app state, in your independent backup if you want editor metadata, action state, or local recovery data preserved. If you only copy individual note or chart projection files, you keep the saved document projection but not the app-managed state behind it.

Meeting recovery artifacts

Meeting recovery records are app-managed local files, not saved notes. During recording, finalization, saving, and report generation, Wrengle writes strict, versioned records under .app/live/. They can contain completed transcript text, selected meeting context, the exact note target and identity, provider exposure state, and a contiguous report attempt revision. They contain no raw meeting audio or memory-only prepared report state. Content-free exposure claims are recorded before cloud preparation requests so an interrupted request is not silently replayed; they do not contain report text. The directory is ignored by vault git history, and records are deleted after successful save/report, recovery, discard, or no-speech cleanup.

Because .app/live/ is inside the vault, filesystem sync or backup configured for the full vault can copy temporary recovery records to its service or another device while they exist. They do not necessarily remain only on the machine recording the meeting.

A live meeting also writes a content-free active-owner lease with a random owner identifier and timestamps. It is refreshed every 15 seconds through capture, finalization, save, and detached automatic report work. A monotonic generation and OS file lock fence cooperating Wrengle processes only when they open the same underlying lock-capable filesystem object in one clock domain. Orderly completion attempts release without waiting indefinitely for another process or a stalled filesystem. It normally completes promptly; otherwise the item becomes recoverable when that filesystem's clock observes the last heartbeat as at least two minutes old. Ordinary synced replicas are separate, potentially stale objects, not a distributed lock; independently clocked or future-skewed replicas have no cross-device fencing guarantee. Do not recover the same temporary item concurrently on synced devices.

Back up the whole vault folder if you intentionally need to preserve an unsaved recovery item that is currently waiting for action. Do not treat .app/live/ as a transcript archive; if cleanup fails, Wrengle surfaces a cleanup-needed row so stale records can be cleared instead of remaining hidden.

All recovery artifact reads and enumerations are bounded. An oversized or malformed session is isolated as unsupported and discard-only while valid sessions continue to scan. If the owner lease itself is unreadable or oversized, that session remains hidden and fails closed while valid siblings still scan. A root-wide overflow fails closed rather than returning an incomplete recovery list.

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 a user may keep in a vault.

Import and export

Data safety caveats

Wrengle is in beta. Keep independent backups of important notes and review known limitations before relying on meeting, AI, or plugin workflows for critical work.