FAQ & Troubleshooting

General

Where is my data stored?

All data lives in plain files on your filesystem. Each project is a folder containing Markdown files (.md), image subfolders, and JSON metadata (order.json, tags.json). There is no database.

Can I use Git with my notes?

Yes. The filesystem-based structure is designed for version control. Initialize a Git repository inside any project folder and track changes normally.

Can I edit notes with another editor?

Yes. Since notes are plain Markdown files, you can open and edit them with any text editor (VS Code, Vim, Typora, etc.).

How do I reload changes made outside Tessera (for example by scripts or agents)?

If files are modified on disk while Tessera is open, reopen the project (or restart the app) to reload the latest state from disk.

A dedicated in-app Refresh action and browser-style Cmd+R / Ctrl+R shortcut are planned, but not yet implemented.

Does Tessera work offline?

Yes. Tessera is a fully offline desktop application. All data is stored locally. No internet connection is required after installation.

Images

What image formats are supported?

PNG, JPEG. Other formats might work.

Tessera's context menu intentionally provides only Copy Image, since you already have direct filesystem access to all image files via the OS file manager.

Images aren't displaying in the preview

Make sure the image syntax uses the correct relative path format: ![filename](note_id/filename). Images are resolved relative to the project through Tessera's backend.

Editing

Undo isn't working

Tessera uses a custom undo/redo system that operates on the text editor. Make sure you are in edit mode (the textarea is visible) before pressing Cmd+Z / Ctrl+Z. Undo history resets each time you open or close the editor.

My title changes aren't persisting

Title edits in the card header are visual labels for the current session. The underlying note filename is set at creation time and does not change when you edit the title.

Platform-specific

macOS: "App is damaged and can't be opened"

This is a Gatekeeper warning. Right-click the app, select Open, and confirm. Alternatively, run:

xattr -cr /Applications/Tessera.app

Linux packages

./build-release.sh produces .deb, .rpm, and (by default) .AppImage under tauri-desktop/src-tauri/target/release/bundle/. Set BUILD_APPIMAGE=0 to skip the AppImage step.

Debian / Ubuntu: sudo dpkg -i tessera_*.deb (install missing deps with apt if prompted).
Fedora / RHEL: install the .rpm with your package manager.
Arch: install fuse2, then run the .AppImage (see Getting started). Or convert the .deb with debtap.

AppImage caveats

Tauri can bundle an AppImage, but it is not always the easiest Linux format:

Topic	Detail
Size	Much larger than the app alone (often 70 MB+).
Runtime	Usually needs FUSE (`fuse2` on Arch). Without it, use `--appimage-extract-and-run`.
Portability	Built against your distro/glibc; building on very new Arch may not run on older systems.
Build	Debian 13 (native or Docker) is the recommended Linux build baseline for `.deb`, `.rpm`, and AppImage. Docker sets `APPIMAGE_EXTRACT_AND_RUN=1` and `NO_STRIP=true` when bundling AppImages.

For day-to-day use on Debian or Fedora, prefer the native .deb or .rpm. AppImage is mainly for “single file, no install” workflows (including Arch when you do not want debtap).

Clipboard on Linux: install xclip (X11) or use a Wayland environment where the app’s clipboard path works; mileage on other distros may vary.

Dark mode looks different than expected

Tessera has its own dark theme, independent of your operating system's dark mode. Use the theme toggle (🌙 / ☀️) in the header to switch.