feat: knowledge base notes redesign

docs/knowledge-base-notes/01-current-state.md

@@ -0,0 +1,160 @@
+# Current State
+
+## Data Model
+
+The original annotation system has three main concepts:
+
+- `Highlight`
+  - Stored in the `highlights` table.
+  - Fields include `book_id`, `cfi`, selected `text`, `color`, optional inline
+    `note`, `chapter_title`, timestamps, and sync metadata after migration.
+- `Note`
+  - Stored in the `notes` table.
+  - Fields include `book_id`, optional `highlight_id`, optional `cfi`, `title`,
+    Markdown `content`, `chapter_title`, `tags`, timestamps, and sync metadata.
+- `Bookmark`
+  - Stored in `bookmarks`.
+
+Important mismatch:
+
+- The global Notes UI mostly uses `highlightsWithBooks` and treats
+  `highlight.note` as the user's note.
+- The standalone `notes` table exists and is synced, but it is not the main
+  product workflow.
+
+The current knowledge-base branch adds the document graph that this model was
+missing:
+
+- `knowledge_documents`
+  - Stores canonical Tiptap JSON plus deterministic Markdown projection.
+  - Covers book home pages, standalone notes, highlight notes, reviews,
+    summaries, imported Markdown, and compact AI memory fields.
+- `knowledge_links`
+  - Connects documents to books, highlights, CFIs, URLs, Obsidian paths, and
+    other knowledge documents.
+- `knowledge_attachments`
+  - Represents document-owned assets for editor rendering, export, and file
+    sync workflows.
+  - Desktop and mobile can persist local image attachments into the app data
+    directory, attach them to a knowledge document, and insert portable image
+    nodes that keep the attachment ID.
+- `knowledge_card_templates`
+  - Stores built-in and user-created card templates.
+
+## Desktop Editing
+
+Desktop still has the legacy Tiptap-based Markdown editor for older note flows:
+
+- File: `packages/app/src/components/ui/markdown-editor.tsx`
+- Uses `@tiptap/react`, `@tiptap/starter-kit`, `@tiptap/markdown`, and
+  placeholder support.
+- Initializes with `contentType: "markdown"`.
+- Persists `editor.getMarkdown()` through the existing note field.
+
+The knowledge-base branch also introduces the reusable document editor:
+
+- File: `packages/app/src/components/knowledge/KnowledgeEditor.tsx`
+- Uses canonical Tiptap JSON and shared Markdown projection.
+- Supports surface profiles, inline marks, headings, lists, task lists, source
+  references, internal links, and ReadAny card nodes.
+- Loads synced card templates and renders card node views for desktop.
+
+## Mobile Editing
+
+Mobile still uses the native React Native editor in legacy quick-note surfaces:
+
+- File: `packages/app-expo/src/components/ui/RichTextEditor.tsx`
+- Uses a multiline `TextInput`.
+- Has a Markdown toolbar and preview mode.
+- Used by note cards, reader note modal, and selection popover.
+
+The knowledge-base branch now ships a WebView-backed Tiptap editor for knowledge
+documents:
+
+- File: `packages/app-expo/src/components/knowledge/MobileKnowledgeEditor.tsx`
+- Bundle: `packages/app-expo/assets/editor/knowledge-editor.html`, generated by
+  `packages/app-expo/scripts/build-knowledge-editor.js`.
+- Uses a typed RN bridge for init, content changes, selection state, height,
+  commands, errors, retry, fallback editing, and draft recovery.
+- Reuses the shared editor profiles and card registry from core.
+
+## Notes UI
+
+Desktop and mobile both present notes as book-grouped notebooks:
+
+- Desktop: `packages/app/src/components/notes/NotesPage.tsx`
+- Mobile: `packages/app-expo/src/screens/NotesView.tsx`
+
+The original tabs are essentially:
+
+- Notes: highlights with `note`
+- Highlights: highlights without `note`
+
+The knowledge-base branch adds a Knowledge tab with:
+
+- Auto-created book home documents.
+- Additional standalone/review/summary documents per book.
+- Tags, document strip navigation, backlinks, related links, recent excerpts,
+  export, and compact AI memory controls.
+
+## Export
+
+The original annotation exporter supports:
+
+- Markdown
+- JSON
+- Obsidian Markdown with frontmatter and callouts
+- Notion-friendly clipboard text
+
+The knowledge-base branch adds a document graph exporter:
+
+- File: `packages/core/src/export/knowledge-exporter.ts`
+- Exports book home, highlight notes, standalone notes, reviews, summaries,
+  links, attachments, frontmatter, manifests, and linked-vault packages.
+- ReadAny cards render to Obsidian-friendly callouts by default.
+- Optional `:::readany-card ... :::` metadata blocks preserve card attrs for
+  round-tripping.
+
+## Sync
+
+The current sync service is per-device JSON changesets:
+
+- File: `packages/core/src/sync/simple-sync.ts`
+- `SYNC_TABLES` includes books, highlights, notes, bookmarks, threads, messages,
+  skills, tags, groups, and reading sessions.
+- Deletions use `sync_tombstones`.
+- Conflict behavior is mostly last-write-wins based on timestamp columns.
+
+The knowledge tables are now part of simple sync. File-backed knowledge
+attachments are also included in file sync manifests: local attachment files can
+upload to `/readany/data/knowledge/attachments`, missing local files can be
+downloaded from manifest paths, and stale local remote paths are reconciled from
+the manifest. Obsidian vault outputs remain export/import artifacts rather than
+the sync backbone.
+
+## Testing Baseline
+
+Relevant existing tests:
+
+- `packages/core/src/db/__tests__/note-queries.test.ts`
+- `packages/core/src/stores/annotation-store.test.ts`
+- `packages/core/src/sync/__tests__/simple-sync.integration.test.ts`
+- `packages/core/src/sync/__tests__/sync-files.test.ts`
+- `packages/core/src/db/__tests__/knowledge-queries.test.ts`
+- `packages/core/src/knowledge/*.test.ts`
+- `packages/core/src/export/knowledge-exporter.test.ts`
+- `packages/core/src/ai/tools/knowledge-tools.test.ts`
+
+The next feature should add tests at the DB, store, conversion, and sync layers
+before large UI work lands.
+
+## Current Risks
+
+- Legacy `highlights.note` and knowledge documents can diverge if both remain
+  writable without compatibility projection.
+- Markdown projection and Markdown import must keep expanding as cards,
+  attachments, and Obsidian round-trips get more capable.
+- Mobile WebView editing has robust bridge/error/draft behavior now, but still
+  needs device-level validation across iOS and Android keyboards.
+- Obsidian "live sync" can create hard conflict cases if ReadAny and Obsidian
+  edit the same file independently.