Why Renaming a Markdown File Can Trigger a Full Data Migration

A developer building a Vue-based local card collection manager discovered that renaming a Markdown file is far more complex than a simple edit, as it affects filenames, metadata, image assets, and cross-note links simultaneously. To maintain data integrity, the fix required a strict, ordered sequence of steps including identity validation, collision checks, link rewriting, and asset cleanup. The process closely mirrors a database migration, even though the underlying storage is plain files rather than a relational database. Key integrity rules were established, such as ensuring one stable filename per card, preventing overwrites, and never removing shared assets still referenced elsewhere. The takeaway is that local-first, file-based systems still demand explicit identity rules, safe failure handling, and repeatable audits to remain internally consistent.