Editing your files outside visualOS (and AI agents)

The rule

The complete workspace lives in canvas-data.json. The board.json files, .md documents and media files next to them are written from the app, so your work is always readable in the open.

Images, PDFs, Office and other files can be edited in another app and saved under the same name. visualOS keeps your file and shows the change the next time it loads the folder: after a restart, after reconnecting, or when changes from another device arrive. Video and audio files are kept too; this device may keep playing its stored copy for a while.

Documents and board.json are written from the app. Changes you make to a .md document elsewhere do not reach the canvas and are replaced the next time visualOS starts or the document changes; board.json is generated metadata.

What works well

• Reading and searching. Search through your notes, open documents in any Markdown editor, preview images: it’s all ordinary files.
• Feeding a project to an AI agent. Every board folder is self-contained: give an agent one project folder and it sees that project’s board.json, documents and images, nothing else.
• Adding new files. New images, PDFs and other files dropped into a board’s folder appear in the New Items pool. A file saved under a new name becomes a new item there.
• Archiving and sharing. Zip a folder and send it; the recipient can read everything without visualOS.

What to avoid

• Editing board.json or .md documents in the expectation that the canvas updates. Make those changes in the app.
• Editing or deleting canvas-data.json by hand. It holds the whole workspace; Versions can help if something goes wrong.
• Moving or renaming board folders and files in Finder or Explorer. Do it in the app; visualOS keeps the folder structure in step with your canvas. To move the whole connected folder, see moving your folder.
• Letting automation rewrite existing files. Give tools read access and have them write new output files, which the New Items pool picks up.