Initial commit: LinkSyncServer and LinkSyncExtension projects with complete documentation, models, API endpoints, tests, and extension implementation

Linkding Browser Extension/LinkdingSync/docs/design.md

@@ -302,4 +302,112 @@ This document should be referenced during implementation to ensure all requireme
 
 ---
 
-**Last Updated:** 2026-05-06
+**Last Updated:** 2026-05-06
+
+# LinkdingSync - Version Compatibility Notes
+
+## Version 1.0.x - Basic Structured Notes
+
+### Notes Structure
+```json
+{
+  "version": "1.0",
+  "path": "",
+  "userNotes": "",
+  "autoTags": [],
+  "bundleTag": "bundle_links_blabber1565_firefox_42",
+  "keyword": ""
+}
+```
+
+### Auto-Generate Tags Feature
+
+When `autoGenerateTags` is **enabled** in settings:
+- Tags are automatically derived from the `path` folder structure
+- Example: `path = "Work/Resources/Development"` → `autoTags = ["Work", "Resources", "Development"]`
+- These tags are added to the bookmark on Linkding
+- **Important**: Tags are only auto-generated if this setting is enabled
+- Tags will always be present in the structured notes field
+
+When `autoGenerateTags` is **disabled** (default):
+- Tags array remains empty (`[]`)
+- Only `bundleTag` is added to the bookmark
+- Old bookmarks without structured notes are migrated without tags
+
+### Bundle Tag Behavior
+
+**Always Applied:**
+- The `bundleTag` (e.g., `bundle_links_blabber1565_firefox_42`) is **always** added to new bookmarks
+- This enables Linkding bundle filtering via the `all=` API parameter
+- When viewing bookmarks in Linkding UI with this tag filter, you'll see only bookmarks from this browser
+- Bundle feature works as expected: queries by tag filter, UI shows filtered results
+
+**Not Applied:**
+- `path` field is used for folder organization
+- `userNotes` stores user-provided notes
+- `autoTags` is populated only when `autoGenerateTags` is enabled
+- `keyword` field is used for Firefox-style quick-access bookmarks
+
+### Migrations
+
+**Old Non-JSON Notes:**
+```
+"old text notes"
+```
+→ Migrated to:
+```json
+{
+  "version": "1.0",
+  "path": "",
+  "userNotes": "old text notes",
+  "autoTags": [],
+  "bundleTag": "bundle_...",
+  "keyword": ""
+}
+```
+
+**Old Structured Notes (no version field):**
+```json
+{
+  "path": "",
+  "userNotes": "notes",
+  "autoTags": []
+}
+```
+→ Migrated to:
+```json
+{
+  "version": "1.0",
+  "path": "",
+  "userNotes": "notes",
+  "autoTags": [],
+  "bundleTag": "bundle_...",
+  "keyword": ""
+}
+```
+
+## Version 2.x - Future Features
+
+Version 2.x will add new fields while maintaining backward compatibility. Older extension versions will continue to work but won't use new fields.
+
+---
+
+## Implementation Notes
+
+### Current State (v1.0.x)
+- `bundleTag` is **always** added to bookmarks (enables bundle filtering)
+- `autoTags` is only populated when `autoGenerateTags` setting is enabled
+- Old bookmarks get migrated with empty `autoTags` array
+- Firefox tags (`autoTags`) are stored in Linkding bookmarks when present in Firefox
+
+### Bundle Feature
+- Linkding bundle is created with `all_tags` set to the `bundleTag`
+- All bookmarks with this tag appear in the bundle
+- Bundle filtering uses `all=` API parameter (exact match on all tags)
+- Querying works correctly with pagination for large bookmark sets
+
+### Cross-Browser Sync
+- All browsers share the same Linkding collection via tag filtering
+- Firefox bookmarks with tags sync to Linkding
+- Other browsers read from Linkding with same tag filter
+- Keywords are preserved in structured notes but not synced (Linkding doesn't support keywords)