File-over-App Philosophy
File-over-app means durable user-owned state should live in inspectable files where the workflow supports it. It does not mean every runtime record or provider transcript is ordinary Markdown.
Storage boundaries
| State | Primary location | What to verify |
|---|---|---|
| Vault notes, Context codeblocks, provider thread URLs, and Active/Done fields | Markdown files in the vault | The file contains the intended source path, state, or bookmark. |
| Smart Environment indexes and Smart Chat Pro API records | Linked application data under .smart-env/ |
Reopened records still contain the expected sources, messages, and context. |
| Provider conversation transcript | The selected provider unless explicitly copied into the vault | The saved URL reopens the intended conversation. |
| Copied Context or Template request | Clipboard until pasted or saved | The pasted package contains only the reviewed sources and instructions. |
| Generated or downloaded binary media | The destination explicitly chosen by the user | The file list, labels, and content match the reviewed output. |
What remains portable
- Markdown stays inspectable. Notes, manifests, thread bookmarks, and review state can be searched, diffed, synced, and edited with normal file tools.
- Application data has a separate lifecycle.
.smart-envrecords and indexes are not ordinary notes. Test sync methods for concurrent writes and conflict recovery before treating them as multi-device canonical state. - Provider history remains provider state. Saving a URL in Markdown does not copy the transcript into the vault.
- Exports become durable only when saved. Clipboard text, composite media, and ZIP output become files after the user pastes or saves them to a chosen destination.
Why it matters
- Users can see which parts of a workflow are normal vault files and which depend on application or provider state.
- Reviewers can diff durable Markdown artifacts before promoting them into trusted notes.
- Teams can choose sync, backup, and retention policies appropriate to each storage class.
- Switching tools is easier when the durable work product remains in open, user-controlled formats.
The principle is not "no hidden state." The principle is to keep the durable work product user-owned, make non-Markdown state explicit, and verify every boundary before relying on it.