Update OpenWiki for source ingest

AGENTS.md

@@ -0,0 +1,10 @@
+## OpenWiki
+
+This repository has documentation located in the /openwiki directory.
+
+Start here:
+- [OpenWiki quickstart](openwiki/quickstart.md)
+
+OpenWiki includes repository overview, architecture notes, workflows, domain concepts, operations, integrations, testing guidance, and source maps.
+
+When working in this repository, read the OpenWiki quickstart first, then follow its links to the relevant architecture, workflow, domain, operation, and testing notes.

Marks.xcodeproj/project.pbxproj

@@ -7,6 +7,7 @@
 	objects = {
 
 /* Begin PBXBuildFile section */
+		031BC9E7B0107CD02F9BA846 /* SourceSpotlightIndexer.swift in Sources */ = {isa = PBXBuildFile; fileRef = F1656ED1A2E9858235FF98B2 /* SourceSpotlightIndexer.swift */; };
 		0360FE41EA05B1A6CAC53E5E /* MarksWidget.appex in Embed Foundation Extensions */ = {isa = PBXBuildFile; fileRef = 23F172EC9977CD5C51B228B9 /* MarksWidget.appex */; settings = {ATTRIBUTES = (RemoveHeadersOnCopy, ); }; };
 		0479C0AA16E3AFDBD4414AD0 /* PodcastIndex.swift in Sources */ = {isa = PBXBuildFile; fileRef = F75DE8BE4B3A3E0E60B8BB03 /* PodcastIndex.swift */; };
 		1095DC18A31055ED40CD9323 /* LinkdingAPI.swift in Sources */ = {isa = PBXBuildFile; fileRef = 5CCBB391B1E0E1E4EBE0EFC7 /* LinkdingAPI.swift */; };
@@ -15,6 +16,7 @@
 		1B04368962246251639D9590 /* AISummaryStore.swift in Sources */ = {isa = PBXBuildFile; fileRef = D2860AAA865515225FB9FC65 /* AISummaryStore.swift */; };
 		212F713DCC289C48087B79AE /* Log.swift in Sources */ = {isa = PBXBuildFile; fileRef = FB7728D15C17219ABFF3EFFE /* Log.swift */; };
 		22C814FD55D29B88D227C987 /* SpotlightBookmarkSearch.swift in Sources */ = {isa = PBXBuildFile; fileRef = 41DDBB04346F3BF06DE233D2 /* SpotlightBookmarkSearch.swift */; };
+		337E8272EEB3B10FD0868F76 /* IngestedSource.swift in Sources */ = {isa = PBXBuildFile; fileRef = 7DC9BBF1006495D75DE4A232 /* IngestedSource.swift */; };
 		3528AF5CB690BBCCF337581B /* Bookmark.swift in Sources */ = {isa = PBXBuildFile; fileRef = 8CA428181B35885F7D9F4D55 /* Bookmark.swift */; };
 		41F00F4E7FFC1C0ACF71E398 /* MarksApp.swift in Sources */ = {isa = PBXBuildFile; fileRef = D92575C7C710347F226EC74A /* MarksApp.swift */; };
 		44E22B6D9EE5C54A06207AFD /* BookmarkSearchTool.swift in Sources */ = {isa = PBXBuildFile; fileRef = C5A99F666A536D569171B55F /* BookmarkSearchTool.swift */; };
@@ -26,11 +28,14 @@
 		6BF0E1F0F4DEAF87B0B8DCF6 /* CollectionsView.swift in Sources */ = {isa = PBXBuildFile; fileRef = FE19F7619214271A8C12EEEB /* CollectionsView.swift */; };
 		706642006800745A0A0188D0 /* RandomBookmarkWidget.swift in Sources */ = {isa = PBXBuildFile; fileRef = 96F73C2A0B8AB36C6F80D5FE /* RandomBookmarkWidget.swift */; };
 		706CCE40744D7F382AFFE429 /* BrowserView.swift in Sources */ = {isa = PBXBuildFile; fileRef = 629C41E0BC28EB6359D50CFD /* BrowserView.swift */; };
+		70DE16F6334D0F3798C98064 /* IngestPayload.swift in Sources */ = {isa = PBXBuildFile; fileRef = 0A7D8DBB58B2F2EC835C9457 /* IngestPayload.swift */; };
 		76223AA04DF97B24C1490B20 /* ShareViewController.swift in Sources */ = {isa = PBXBuildFile; fileRef = ADEAC824576633CC77370262 /* ShareViewController.swift */; };
 		773C174263D08416248D0675 /* PodcastGenerationManager.swift in Sources */ = {isa = PBXBuildFile; fileRef = 171EF75BF9BE4592DFA2C716 /* PodcastGenerationManager.swift */; };
 		778B82E075D4DAF5E8446D6F /* BookmarkOnscreen.swift in Sources */ = {isa = PBXBuildFile; fileRef = D1EEDFAE9FCA24192640CA7A /* BookmarkOnscreen.swift */; };
 		8140EEEFBB7A3510A73D1A93 /* SwiftUI.framework in Frameworks */ = {isa = PBXBuildFile; fileRef = 093402014727A338745A06DA /* SwiftUI.framework */; };
+		81F3155F05559C648FDEB36C /* IngestedSourceStore.swift in Sources */ = {isa = PBXBuildFile; fileRef = 18204F832C8114B6B9AB5BD8 /* IngestedSourceStore.swift */; };
 		8227B9E3B5EFF6427702F376 /* BookmarkAssistant.swift in Sources */ = {isa = PBXBuildFile; fileRef = E6379451D7FD7090A9F01A01 /* BookmarkAssistant.swift */; };
+		83CC9BA3176B05358A307373 /* IngestPayload.swift in Sources */ = {isa = PBXBuildFile; fileRef = 0A7D8DBB58B2F2EC835C9457 /* IngestPayload.swift */; };
 		8456E89CFE607C2EC57BF466 /* ShareView.swift in Sources */ = {isa = PBXBuildFile; fileRef = 9B7A85A23A13D754F6A75E4D /* ShareView.swift */; };
 		849C9CB4E1E8A6ABA1BC7251 /* SettingsView.swift in Sources */ = {isa = PBXBuildFile; fileRef = 5C29CB878BC334639E6194E2 /* SettingsView.swift */; };
 		852A3E18661C190622FF5A85 /* AppIntents.framework in Frameworks */ = {isa = PBXBuildFile; fileRef = F9803BA80BEAE9A3AE4AF5E7 /* AppIntents.framework */; };
@@ -40,6 +45,7 @@
 		905FBD9468F488ACE4B81726 /* RecentPodcastsWidget.swift in Sources */ = {isa = PBXBuildFile; fileRef = 47CB3AAED5B64809B06A9650 /* RecentPodcastsWidget.swift */; };
 		927BAD5AD47217E3F396CDA7 /* TagsView.swift in Sources */ = {isa = PBXBuildFile; fileRef = B13B9F2D890C7953531AC0D2 /* TagsView.swift */; };
 		94CEF815D51433054412CB20 /* RecentBookmarksWidget.swift in Sources */ = {isa = PBXBuildFile; fileRef = 49C6260D1530C5C4F1AD063E /* RecentBookmarksWidget.swift */; };
+		95D9848F60EB303D9EACCDDA /* SourcesView.swift in Sources */ = {isa = PBXBuildFile; fileRef = CDB1DA808EE8041C4546DAAB /* SourcesView.swift */; };
 		96698499C0501D0A897D7E08 /* BookmarkRow.swift in Sources */ = {isa = PBXBuildFile; fileRef = B0C6ABE160A2C90EB965D811 /* BookmarkRow.swift */; };
 		969568D9996EB65550DAA24A /* ServerConfig.swift in Sources */ = {isa = PBXBuildFile; fileRef = 07C21567B95F5069BA946252 /* ServerConfig.swift */; };
 		A396A5DC6ED590D0CDB1024B /* WidgetKit.framework in Frameworks */ = {isa = PBXBuildFile; fileRef = 0552C13335034219DECF4F62 /* WidgetKit.framework */; };
@@ -113,10 +119,12 @@
 		0552C13335034219DECF4F62 /* WidgetKit.framework */ = {isa = PBXFileReference; lastKnownFileType = wrapper.framework; name = WidgetKit.framework; path = System/Library/Frameworks/WidgetKit.framework; sourceTree = SDKROOT; };
 		07C21567B95F5069BA946252 /* ServerConfig.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = ServerConfig.swift; sourceTree = "<group>"; };
 		093402014727A338745A06DA /* SwiftUI.framework */ = {isa = PBXFileReference; lastKnownFileType = wrapper.framework; name = SwiftUI.framework; path = System/Library/Frameworks/SwiftUI.framework; sourceTree = SDKROOT; };
+		0A7D8DBB58B2F2EC835C9457 /* IngestPayload.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = IngestPayload.swift; sourceTree = "<group>"; };
 		0D2CC53B01DF0FE51ADE5FCB /* Marks.entitlements */ = {isa = PBXFileReference; lastKnownFileType = text.plist.entitlements; path = Marks.entitlements; sourceTree = "<group>"; };
 		0EDC639E0783581A733F4C99 /* WidgetDataStore.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = WidgetDataStore.swift; sourceTree = "<group>"; };
 		11DC9EA7BF3AD8FE3D536319 /* PodcastLibrary.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = PodcastLibrary.swift; sourceTree = "<group>"; };
 		171EF75BF9BE4592DFA2C716 /* PodcastGenerationManager.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = PodcastGenerationManager.swift; sourceTree = "<group>"; };
+		18204F832C8114B6B9AB5BD8 /* IngestedSourceStore.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = IngestedSourceStore.swift; sourceTree = "<group>"; };
 		1A5FEE76168FA5AB1E047FEC /* SpotlightIndexer.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = SpotlightIndexer.swift; sourceTree = "<group>"; };
 		217E6702DE1210AC38ED16D1 /* AskView.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = AskView.swift; sourceTree = "<group>"; };
 		22E006A11D594BFC00A9C4B4 /* OnboardingView.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = OnboardingView.swift; sourceTree = "<group>"; };
@@ -135,6 +143,7 @@
 		69D868AF1DAF3F1BBEACBFF6 /* ClaudeService.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = ClaudeService.swift; sourceTree = "<group>"; };
 		759BA3FCF8BEE1D4EA1CDC17 /* String+Helpers.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = "String+Helpers.swift"; sourceTree = "<group>"; };
 		7623601C25E481DF58371F2A /* AppIntentsTests.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = AppIntentsTests.swift; sourceTree = "<group>"; };
+		7DC9BBF1006495D75DE4A232 /* IngestedSource.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = IngestedSource.swift; sourceTree = "<group>"; };
 		86B2DE40098D2B39FFE1AC36 /* Info.plist */ = {isa = PBXFileReference; lastKnownFileType = text.plist; path = Info.plist; sourceTree = "<group>"; };
 		8CA428181B35885F7D9F4D55 /* Bookmark.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = Bookmark.swift; sourceTree = "<group>"; };
 		8D650D0784B847BFEDCB3141 /* BookmarkEntity.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = BookmarkEntity.swift; sourceTree = "<group>"; };
@@ -155,6 +164,7 @@
 		CBE3C5E420F078D499B2D926 /* BookmarksView.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = BookmarksView.swift; sourceTree = "<group>"; };
 		CBFB5EFC9764B22A2622EA4A /* BookmarksViewModel.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = BookmarksViewModel.swift; sourceTree = "<group>"; };
 		CC6B10FBB227F426A2B597C8 /* BookmarkListRow.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = BookmarkListRow.swift; sourceTree = "<group>"; };
+		CDB1DA808EE8041C4546DAAB /* SourcesView.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = SourcesView.swift; sourceTree = "<group>"; };
 		D1EEDFAE9FCA24192640CA7A /* BookmarkOnscreen.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = BookmarkOnscreen.swift; sourceTree = "<group>"; };
 		D27A97922BAEBDC9C5A7385C /* PodcastRequests.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = PodcastRequests.swift; sourceTree = "<group>"; };
 		D2860AAA865515225FB9FC65 /* AISummaryStore.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = AISummaryStore.swift; sourceTree = "<group>"; };
@@ -164,6 +174,7 @@
 		DE73381C52297CDB30AACCFB /* MarksWidgetBundle.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = MarksWidgetBundle.swift; sourceTree = "<group>"; };
 		E6379451D7FD7090A9F01A01 /* BookmarkAssistant.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = BookmarkAssistant.swift; sourceTree = "<group>"; };
 		E895C34E4D2A1C4709B25FF1 /* Info.plist */ = {isa = PBXFileReference; lastKnownFileType = text.plist; path = Info.plist; sourceTree = "<group>"; };
+		F1656ED1A2E9858235FF98B2 /* SourceSpotlightIndexer.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = SourceSpotlightIndexer.swift; sourceTree = "<group>"; };
 		F75DE8BE4B3A3E0E60B8BB03 /* PodcastIndex.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = PodcastIndex.swift; sourceTree = "<group>"; };
 		F78AA3450BDFAC24591EE407 /* MarksAuth.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = MarksAuth.swift; sourceTree = "<group>"; };
 		F9803BA80BEAE9A3AE4AF5E7 /* AppIntents.framework */ = {isa = PBXFileReference; lastKnownFileType = wrapper.framework; name = AppIntents.framework; path = System/Library/Frameworks/AppIntents.framework; sourceTree = SDKROOT; };
@@ -212,6 +223,8 @@
 			isa = PBXGroup;
 			children = (
 				8CA428181B35885F7D9F4D55 /* Bookmark.swift */,
+				7DC9BBF1006495D75DE4A232 /* IngestedSource.swift */,
+				0A7D8DBB58B2F2EC835C9457 /* IngestPayload.swift */,
 				07C21567B95F5069BA946252 /* ServerConfig.swift */,
 				759BA3FCF8BEE1D4EA1CDC17 /* String+Helpers.swift */,
 			);
@@ -258,6 +271,7 @@
 				E6379451D7FD7090A9F01A01 /* BookmarkAssistant.swift */,
 				C5A99F666A536D569171B55F /* BookmarkSearchTool.swift */,
 				69D868AF1DAF3F1BBEACBFF6 /* ClaudeService.swift */,
+				18204F832C8114B6B9AB5BD8 /* IngestedSourceStore.swift */,
 				5CCBB391B1E0E1E4EBE0EFC7 /* LinkdingAPI.swift */,
 				FB7728D15C17219ABFF3EFFE /* Log.swift */,
 				F78AA3450BDFAC24591EE407 /* MarksAuth.swift */,
@@ -265,6 +279,7 @@
 				F75DE8BE4B3A3E0E60B8BB03 /* PodcastIndex.swift */,
 				11DC9EA7BF3AD8FE3D536319 /* PodcastLibrary.swift */,
 				D27A97922BAEBDC9C5A7385C /* PodcastRequests.swift */,
+				F1656ED1A2E9858235FF98B2 /* SourceSpotlightIndexer.swift */,
 				41DDBB04346F3BF06DE233D2 /* SpotlightBookmarkSearch.swift */,
 				1A5FEE76168FA5AB1E047FEC /* SpotlightIndexer.swift */,
 			);
@@ -301,6 +316,7 @@
 				A4EB8C63735A267B81030CB5 /* PodcastPlayerView.swift */,
 				BCC3BB2525F0F63445D419B9 /* SearchView.swift */,
 				5C29CB878BC334639E6194E2 /* SettingsView.swift */,
+				CDB1DA808EE8041C4546DAAB /* SourcesView.swift */,
 				B13B9F2D890C7953531AC0D2 /* TagsView.swift */,
 			);
 			path = Views;
@@ -491,6 +507,7 @@
 			buildActionMask = 2147483647;
 			files = (
 				3528AF5CB690BBCCF337581B /* Bookmark.swift in Sources */,
+				70DE16F6334D0F3798C98064 /* IngestPayload.swift in Sources */,
 				1095DC18A31055ED40CD9323 /* LinkdingAPI.swift in Sources */,
 				B085CDBFC47F0357D1A28911 /* Log.swift in Sources */,
 				B7AF3F940FEE7B8AC32628B6 /* MarksAuth.swift in Sources */,
@@ -535,6 +552,9 @@
 				BD2EAD8200FB69B95972146F /* ClaudeService.swift in Sources */,
 				6BF0E1F0F4DEAF87B0B8DCF6 /* CollectionsView.swift in Sources */,
 				C3189071834E0F8898408C37 /* EditBookmarkView.swift in Sources */,
+				83CC9BA3176B05358A307373 /* IngestPayload.swift in Sources */,
+				337E8272EEB3B10FD0868F76 /* IngestedSource.swift in Sources */,
+				81F3155F05559C648FDEB36C /* IngestedSourceStore.swift in Sources */,
 				DE32F3DC24D606926A559C06 /* IntentSnippetViews.swift in Sources */,
 				EFF8E4CD63CAE1342CE3A4F0 /* IntentSupport.swift in Sources */,
 				15077853ECD40C9B289FB608 /* LinkdingAPI.swift in Sources */,
@@ -551,6 +571,8 @@
 				EE540B8367519EDE679C1B70 /* SearchView.swift in Sources */,
 				969568D9996EB65550DAA24A /* ServerConfig.swift in Sources */,
 				849C9CB4E1E8A6ABA1BC7251 /* SettingsView.swift in Sources */,
+				031BC9E7B0107CD02F9BA846 /* SourceSpotlightIndexer.swift in Sources */,
+				95D9848F60EB303D9EACCDDA /* SourcesView.swift in Sources */,
 				22C814FD55D29B88D227C987 /* SpotlightBookmarkSearch.swift in Sources */,
 				AB0BF1F51887D25CC9D6EE1C /* SpotlightIndexer.swift in Sources */,
 				B424D50BE9E6623A4DA15FDC /* String+Helpers.swift in Sources */,

Marks/Intents/IntentSupport.swift

@@ -3,7 +3,7 @@ import AppIntents
 
 /// Which top-level tab the app is showing. Used so an intent can switch tabs.
 enum AppTab: Hashable {
-    case bookmarks, tags, podcasts, search
+    case bookmarks, tags, sources, podcasts, search
 }
 
 /// Bridges App Intents (which run in the main app process, since there is no

Marks/MarksApp.swift

@@ -39,6 +39,7 @@ struct MainContainer: View {
     @State private var selectedTab: AppTab = .bookmarks
     @State private var router = IntentRouter.shared
     @State private var library = PodcastLibrary.shared
+    @State private var sourceLibrary = IngestedSourceLibrary()
     @Environment(\.scenePhase) private var scenePhase
 
     init(config: ServerConfig, onDisconnect: @escaping () -> Void) {
@@ -56,6 +57,14 @@ struct MainContainer: View {
             Tab("Tags", systemImage: "tag", value: AppTab.tags) {
                 TagsView(viewModel: viewModel)
             }
+            Tab("Sources", systemImage: "tray.full", value: AppTab.sources) {
+                SourcesView(
+                    library: sourceLibrary,
+                    podcastPlayer: viewModel.podcastPlayer,
+                    podcastGenerator: viewModel.podcastGenerator,
+                    claude: viewModel.claude
+                )
+            }
             Tab("Podcasts", systemImage: "headphones", value: AppTab.podcasts) {
                 PodcastLibraryView(vm: viewModel.podcastPlayer, claude: viewModel.claude, podcastGenerator: viewModel.podcastGenerator)
             }

Marks/Models/Bookmark.swift

@@ -82,16 +82,35 @@ struct BookmarkCheck: Codable, Sendable {
 struct BookmarkCreate: Codable, Sendable {
     let url: String
     let title: String
+    let description: String
     let tagNames: [String]
     let isArchived: Bool
     let unread: Bool
     let shared: Bool
 
     enum CodingKeys: String, CodingKey {
-        case url, title, unread, shared
+        case url, title, description, unread, shared
         case tagNames = "tag_names"
         case isArchived = "is_archived"
     }
+
+    init(
+        url: String,
+        title: String,
+        description: String = "",
+        tagNames: [String],
+        isArchived: Bool,
+        unread: Bool,
+        shared: Bool
+    ) {
+        self.url = url
+        self.title = title
+        self.description = description
+        self.tagNames = tagNames
+        self.isArchived = isArchived
+        self.unread = unread
+        self.shared = shared
+    }
 }
 
 struct BookmarkUpdate: Codable, Sendable {

Marks/Models/IngestPayload.swift

@@ -0,0 +1,95 @@
+import Foundation
+
+struct IngestPayload: Equatable, Sendable {
+    let url: String
+    let title: String?
+    let notes: String
+}
+
+enum IngestPayloadParser {
+    static func parse(item: Any?, typeIdentifier: String? = nil) -> IngestPayload? {
+        if let url = item as? URL {
+            return payload(from: url.absoluteString, notes: "")
+        }
+
+        if let attributed = item as? NSAttributedString {
+            return payload(from: attributed.string, notes: attributed.string)
+        }
+
+        if let string = item as? String {
+            return payload(from: string, notes: shouldKeepNotes(for: typeIdentifier) ? string : "")
+        }
+
+        if let data = item as? Data,
+           let string = String(data: data, encoding: .utf8) ?? String(data: data, encoding: .ascii) {
+            return payload(from: string, notes: shouldKeepNotes(for: typeIdentifier) ? string : "")
+        }
+
+        return nil
+    }
+
+    private static func payload(from text: String, notes: String) -> IngestPayload? {
+        guard let url = firstWebURL(in: text) else { return nil }
+        return IngestPayload(url: url, title: nil, notes: cleanedNotes(notes, excluding: url))
+    }
+
+    static func firstWebURL(in text: String) -> String? {
+        if let direct = URL(string: text.trimmingCharacters(in: .whitespacesAndNewlines)),
+           isBookmarkable(direct) {
+            return direct.absoluteString
+        }
+
+        let decoded = decodeHTML(text)
+        let detector = try? NSDataDetector(types: NSTextCheckingResult.CheckingType.link.rawValue)
+        let range = NSRange(decoded.startIndex..<decoded.endIndex, in: decoded)
+        let match = detector?.matches(in: decoded, range: range).first { result in
+            guard let url = result.url else { return false }
+            return isBookmarkable(url)
+        }
+
+        guard let matchRange = match?.range,
+              let swiftRange = Range(matchRange, in: decoded) else {
+            return nil
+        }
+
+        let candidate = String(decoded[swiftRange])
+            .trimmingCharacters(in: CharacterSet(charactersIn: " \n\t\r<>\"'.,;:)］】」"))
+
+        guard let url = URL(string: candidate), isBookmarkable(url) else { return nil }
+        return url.absoluteString
+    }
+
+    private static func isBookmarkable(_ url: URL) -> Bool {
+        guard let scheme = url.scheme?.lowercased(),
+              scheme == "http" || scheme == "https",
+              url.host?.isEmpty == false else {
+            return false
+        }
+        return true
+    }
+
+    private static func cleanedNotes(_ notes: String, excluding url: String) -> String {
+        let trimmed = decodeHTML(notes)
+            .replacingOccurrences(of: url, with: "")
+            .components(separatedBy: .newlines)
+            .map { $0.trimmingCharacters(in: .whitespacesAndNewlines) }
+            .filter { !$0.isEmpty }
+            .joined(separator: "\n")
+
+        return String(trimmed.prefix(1800))
+    }
+
+    private static func decodeHTML(_ text: String) -> String {
+        text
+            .replacingOccurrences(of: "&amp;", with: "&")
+            .replacingOccurrences(of: "&lt;", with: "<")
+            .replacingOccurrences(of: "&gt;", with: ">")
+            .replacingOccurrences(of: "&quot;", with: "\"")
+            .replacingOccurrences(of: "&#39;", with: "'")
+    }
+
+    private static func shouldKeepNotes(for typeIdentifier: String?) -> Bool {
+        guard let typeIdentifier else { return true }
+        return !typeIdentifier.lowercased().contains("url")
+    }
+}

Marks/Models/IngestedSource.swift

@@ -0,0 +1,69 @@
+import Foundation
+
+enum IngestedSourceKind: String, Codable, Sendable, CaseIterable {
+    case text
+    case pdf
+    case file
+
+    var label: String {
+        switch self {
+        case .text: "Text"
+        case .pdf: "PDF"
+        case .file: "File"
+        }
+    }
+}
+
+struct IngestedSource: Identifiable, Codable, Sendable, Hashable {
+    let id: UUID
+    var kind: IngestedSourceKind
+    var title: String
+    var bodyText: String
+    var originalFilename: String?
+    var localFilename: String?
+    var tags: [String]
+    var createdAt: Date
+    var modifiedAt: Date
+
+    init(
+        id: UUID = UUID(),
+        kind: IngestedSourceKind,
+        title: String,
+        bodyText: String,
+        originalFilename: String? = nil,
+        localFilename: String? = nil,
+        tags: [String] = [],
+        createdAt: Date = Date(),
+        modifiedAt: Date = Date()
+    ) {
+        self.id = id
+        self.kind = kind
+        self.title = title
+        self.bodyText = bodyText
+        self.originalFilename = originalFilename
+        self.localFilename = localFilename
+        self.tags = tags
+        self.createdAt = createdAt
+        self.modifiedAt = modifiedAt
+    }
+
+    var displayTitle: String {
+        let trimmed = title.trimmingCharacters(in: .whitespacesAndNewlines)
+        if !trimmed.isEmpty { return trimmed }
+        return originalFilename ?? kind.label
+    }
+
+    var excerpt: String {
+        bodyText
+            .trimmingCharacters(in: .whitespacesAndNewlines)
+            .replacingOccurrences(of: "\n", with: " ")
+    }
+
+    var podcastURL: String {
+        "marks-source://\(id.uuidString)"
+    }
+
+    var podcastText: String {
+        String(bodyText.trimmingCharacters(in: .whitespacesAndNewlines).prefix(100_000))
+    }
+}

Marks/Services/ClaudeService.swift

@@ -56,9 +56,13 @@ struct ClaudeService: Sendable {
 
     // MARK: - Podcast
 
-    func generatePodcast(url: String) async throws -> String {
+    func generatePodcast(url: String, title: String? = nil, sourceText: String? = nil, sourceKind: String? = nil) async throws -> String {
         struct Response: Decodable { let job_id: String }
-        let data = try await post("/v1/podcast/generate", body: ["url": url])
+        var body: [String: Any] = ["url": url]
+        if let title, !title.isEmpty { body["title"] = title }
+        if let sourceText, !sourceText.isEmpty { body["text"] = sourceText }
+        if let sourceKind, !sourceKind.isEmpty { body["source_kind"] = sourceKind }
+        let data = try await post("/v1/podcast/generate", body: body)
         return try JSONDecoder().decode(Response.self, from: data).job_id
     }
 

Marks/Services/IngestedSourceStore.swift

@@ -0,0 +1,203 @@
+import Foundation
+import Observation
+import PDFKit
+import UniformTypeIdentifiers
+
+@MainActor
+@Observable
+final class IngestedSourceLibrary {
+    private(set) var sources: [IngestedSource] = []
+    var error: String?
+
+    private let store: IngestedSourceStore
+
+    init(store: IngestedSourceStore = IngestedSourceStore()) {
+        self.store = store
+    }
+
+    func load() {
+        do {
+            sources = try store.load()
+            Task { await SourceSpotlightIndexer.index(sources) }
+        } catch {
+            self.error = error.localizedDescription
+        }
+    }
+
+    func addText(title: String, body: String, tags: [String]) {
+        let source = IngestedSource(
+            kind: .text,
+            title: title,
+            bodyText: body.trimmingCharacters(in: .whitespacesAndNewlines),
+            tags: tags
+        )
+        upsert(source)
+    }
+
+    func importFile(from url: URL, tags: [String]) {
+        do {
+            let source = try store.importFile(from: url, tags: tags)
+            upsert(source)
+        } catch {
+            self.error = error.localizedDescription
+        }
+    }
+
+    func delete(_ source: IngestedSource) {
+        do {
+            try store.delete(source)
+            sources.removeAll { $0.id == source.id }
+            Task { await SourceSpotlightIndexer.remove(ids: [source.id]) }
+        } catch {
+            self.error = error.localizedDescription
+        }
+    }
+
+    func fileURL(for source: IngestedSource) -> URL? {
+        store.fileURL(for: source)
+    }
+
+    func search(_ query: String) -> [IngestedSource] {
+        let q = query.trimmingCharacters(in: .whitespacesAndNewlines).lowercased()
+        guard !q.isEmpty else { return sources }
+        return sources.filter { source in
+            source.displayTitle.lowercased().contains(q) ||
+            source.bodyText.lowercased().contains(q) ||
+            source.tags.contains { $0.lowercased().contains(q) } ||
+            (source.originalFilename ?? "").lowercased().contains(q)
+        }
+    }
+
+    private func upsert(_ source: IngestedSource) {
+        sources.removeAll { $0.id == source.id }
+        sources.insert(source, at: 0)
+        do {
+            try store.save(sources)
+            Task { await SourceSpotlightIndexer.index([source]) }
+        } catch {
+            self.error = error.localizedDescription
+        }
+    }
+}
+
+struct IngestedSourceStore {
+    private let rootURL: URL
+    private let metadataURL: URL
+    private let filesURL: URL
+
+    init(rootURL: URL? = nil) {
+        let base = rootURL ?? FileManager.default.urls(for: .applicationSupportDirectory, in: .userDomainMask)[0]
+        self.rootURL = base.appendingPathComponent("Sources", isDirectory: true)
+        self.metadataURL = self.rootURL.appendingPathComponent("sources.json")
+        self.filesURL = self.rootURL.appendingPathComponent("files", isDirectory: true)
+    }
+
+    func load() throws -> [IngestedSource] {
+        guard FileManager.default.fileExists(atPath: metadataURL.path) else { return [] }
+        let data = try Data(contentsOf: metadataURL)
+        return try JSONDecoder.sourceDecoder.decode([IngestedSource].self, from: data)
+            .sorted { $0.createdAt > $1.createdAt }
+    }
+
+    func save(_ sources: [IngestedSource]) throws {
+        try FileManager.default.createDirectory(at: rootURL, withIntermediateDirectories: true)
+        let data = try JSONEncoder.sourceEncoder.encode(sources)
+        try data.write(to: metadataURL, options: [.atomic])
+    }
+
+    func importFile(from url: URL, tags: [String]) throws -> IngestedSource {
+        try FileManager.default.createDirectory(at: filesURL, withIntermediateDirectories: true)
+
+        let accessed = url.startAccessingSecurityScopedResource()
+        defer {
+            if accessed { url.stopAccessingSecurityScopedResource() }
+        }
+
+        let id = UUID()
+        let originalFilename = url.lastPathComponent
+        let ext = url.pathExtension.isEmpty ? "dat" : url.pathExtension
+        let localFilename = "\(id.uuidString).\(ext)"
+        let destination = filesURL.appendingPathComponent(localFilename)
+        if FileManager.default.fileExists(atPath: destination.path) {
+            try FileManager.default.removeItem(at: destination)
+        }
+        try FileManager.default.copyItem(at: url, to: destination)
+
+        let kind = url.pathExtension.lowercased() == "pdf" ? IngestedSourceKind.pdf : .file
+        let bodyText = kind == .pdf
+            ? PDFTextExtractor.extractText(from: destination)
+            : PlainTextExtractor.extractText(from: destination)
+
+        return IngestedSource(
+            id: id,
+            kind: kind,
+            title: originalFilename.removingFileExtension,
+            bodyText: bodyText,
+            originalFilename: originalFilename,
+            localFilename: localFilename,
+            tags: tags
+        )
+    }
+
+    func delete(_ source: IngestedSource) throws {
+        if let url = fileURL(for: source), FileManager.default.fileExists(atPath: url.path) {
+            try FileManager.default.removeItem(at: url)
+        }
+        var loaded = try load()
+        loaded.removeAll { $0.id == source.id }
+        try save(loaded)
+    }
+
+    func fileURL(for source: IngestedSource) -> URL? {
+        guard let localFilename = source.localFilename else { return nil }
+        return filesURL.appendingPathComponent(localFilename)
+    }
+}
+
+private enum PDFTextExtractor {
+    static func extractText(from url: URL) -> String {
+        guard let document = PDFDocument(url: url) else { return "" }
+        var pages: [String] = []
+        for index in 0..<document.pageCount {
+            if let text = document.page(at: index)?.string?.trimmingCharacters(in: .whitespacesAndNewlines),
+               !text.isEmpty {
+                pages.append(text)
+            }
+        }
+        return pages.joined(separator: "\n\n")
+    }
+}
+
+private enum PlainTextExtractor {
+    static func extractText(from url: URL) -> String {
+        guard let data = try? Data(contentsOf: url) else { return "" }
+        return String(data: data, encoding: .utf8)
+            ?? String(data: data, encoding: .ascii)
+            ?? ""
+    }
+}
+
+private extension String {
+    var removingFileExtension: String {
+        let ns = self as NSString
+        let name = ns.deletingPathExtension
+        return name.isEmpty ? self : name
+    }
+}
+
+private extension JSONEncoder {
+    static var sourceEncoder: JSONEncoder {
+        let encoder = JSONEncoder()
+        encoder.dateEncodingStrategy = .iso8601
+        encoder.outputFormatting = [.prettyPrinted, .sortedKeys]
+        return encoder
+    }
+}
+
+private extension JSONDecoder {
+    static var sourceDecoder: JSONDecoder {
+        let decoder = JSONDecoder()
+        decoder.dateDecodingStrategy = .iso8601
+        return decoder
+    }
+}

Marks/Services/PodcastGenerationManager.swift

@@ -37,6 +37,8 @@ final class PodcastGenerationManager {
     func enqueue(articleUrl: String,
                  title: String,
                  parentBookmarkUrl: String? = nil,
+                 sourceText: String? = nil,
+                 sourceKind: String? = nil,
                  onReady: ((URL, String) -> Void)? = nil) {
         let cached = ClaudeService.cachedPodcastURL(for: articleUrl)
         if FileManager.default.fileExists(atPath: cached.path) {
@@ -52,7 +54,12 @@ final class PodcastGenerationManager {
         let task = Task { [weak self] in
             guard let self else { return }
             do {
-                let jobId = try await claude.generatePodcast(url: articleUrl)
+                let jobId = try await claude.generatePodcast(
+                    url: articleUrl,
+                    title: title,
+                    sourceText: sourceText,
+                    sourceKind: sourceKind
+                )
                 while !Task.isCancelled {
                     let status = try await claude.podcastStatus(jobId: jobId)
                     update(articleUrl) {

Marks/Services/SourceSpotlightIndexer.swift

@@ -0,0 +1,40 @@
+import CoreSpotlight
+import Foundation
+import UniformTypeIdentifiers
+
+enum SourceSpotlightIndexer {
+    private static let domainIdentifier = "com.magicive.marks.sources"
+
+    static func index(_ sources: [IngestedSource]) async {
+        guard CSSearchableIndex.isIndexingAvailable(), !sources.isEmpty else { return }
+        let items = sources.map { source in
+            let attributes = CSSearchableItemAttributeSet(contentType: source.kind == .pdf ? .pdf : .text)
+            attributes.title = source.displayTitle
+            attributes.contentDescription = source.bodyText
+            attributes.keywords = source.tags + [source.kind.label, source.originalFilename].compactMap { $0 }
+            attributes.displayName = source.originalFilename ?? source.displayTitle
+            return CSSearchableItem(
+                uniqueIdentifier: source.id.uuidString,
+                domainIdentifier: domainIdentifier,
+                attributeSet: attributes
+            )
+        }
+
+        do {
+            try await CSSearchableIndex.default().indexSearchableItems(items)
+            Log.spotlight.info("Indexed \(sources.count, privacy: .public) sources")
+        } catch {
+            Log.spotlight.error("Source index failed: \(error.localizedDescription, privacy: .public)")
+        }
+    }
+
+    static func remove(ids: [UUID]) async {
+        guard CSSearchableIndex.isIndexingAvailable(), !ids.isEmpty else { return }
+        do {
+            try await CSSearchableIndex.default().deleteSearchableItems(withIdentifiers: ids.map(\.uuidString))
+            Log.spotlight.info("Removed \(ids.count, privacy: .public) sources")
+        } catch {
+            Log.spotlight.error("Source delete failed: \(error.localizedDescription, privacy: .public)")
+        }
+    }
+}

Marks/Views/AddBookmarkView.swift

@@ -6,13 +6,44 @@ struct AddBookmarkView: View {
 
     @State private var url = ""
     @State private var title = ""
+    @State private var description = ""
     @State private var tagsText = ""
+    @State private var importText = ""
     @State private var isSaving = false
     @State private var error: String?
+    @State private var importMessage: String?
 
     var body: some View {
         NavigationStack {
             Form {
+                Section {
+                    TextEditor(text: $importText)
+                        .frame(minHeight: 96)
+                        .textInputAutocapitalization(.never)
+                        .autocorrectionDisabled()
+
+                    HStack {
+                        Button {
+                            extractImportText()
+                        } label: {
+                            Label("Extract Link", systemImage: "link.badge.plus")
+                        }
+                        .disabled(importText.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty)
+
+                        Spacer()
+
+                        if let importMessage {
+                            Text(importMessage)
+                                .font(.caption)
+                                .foregroundStyle(.secondary)
+                        }
+                    }
+                } header: {
+                    Text("Import Text")
+                } footer: {
+                    Text("Paste an email, newsletter, or message and Marks will pull out the first web link.")
+                }
+
                 Section {
                     TextField("https://", text: $url)
                         .keyboardType(.URL)
@@ -28,6 +59,13 @@ struct AddBookmarkView: View {
                     Text("Title")
                 }
 
+                Section {
+                    TextField("Optional", text: $description, axis: .vertical)
+                        .lineLimit(2...5)
+                } header: {
+                    Text("Notes")
+                }
+
                 Section {
                     TextField("comma separated", text: $tagsText)
                         .textInputAutocapitalization(.never)
@@ -63,6 +101,23 @@ struct AddBookmarkView: View {
         }
     }
 
+    private func extractImportText() {
+        guard let payload = IngestPayloadParser.parse(item: importText, typeIdentifier: "public.plain-text") else {
+            importMessage = "No link found"
+            return
+        }
+
+        url = payload.url
+        if let extractedTitle = payload.title, title.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty {
+            title = extractedTitle
+        }
+        if description.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty {
+            description = payload.notes
+        }
+        importMessage = "Link extracted"
+        error = nil
+    }
+
     private func save() {
         let urlString = url.normalizedURL
         guard URL(string: urlString) != nil else {
@@ -74,7 +129,12 @@ struct AddBookmarkView: View {
         error = nil
         Task {
             do {
-                try await viewModel.addBookmark(url: urlString, title: title.trimmingCharacters(in: .whitespaces), tags: tags)
+                try await viewModel.addBookmark(
+                    url: urlString,
+                    title: title.trimmingCharacters(in: .whitespaces),
+                    description: description.trimmingCharacters(in: .whitespacesAndNewlines),
+                    tags: tags
+                )
                 dismiss()
             } catch {
                 self.error = error.localizedDescription

Marks/Views/BookmarksViewModel.swift

@@ -128,8 +128,16 @@ final class BookmarksViewModel {
         isLoading = false
     }
 
-    func addBookmark(url: String, title: String, tags: [String]) async throws {
-        let create = BookmarkCreate(url: url, title: title, tagNames: tags, isArchived: false, unread: false, shared: false)
+    func addBookmark(url: String, title: String, description: String = "", tags: [String]) async throws {
+        let create = BookmarkCreate(
+            url: url,
+            title: title,
+            description: description,
+            tagNames: tags,
+            isArchived: false,
+            unread: false,
+            shared: false
+        )
         let bookmark = try await api.createBookmark(create)
         bookmarks.insert(bookmark, at: 0)
         Task { await SpotlightIndexer.index([bookmark]) }

Marks/Views/PodcastPlayerView.swift

@@ -76,7 +76,14 @@ final class PodcastPlayerViewModel {
     private var interruptionObserver: Any?
     private var currentPodcastTitle: String = "Marks Podcast"
 
-    func start(articleUrl: String, articleTitle: String = "", claude: ClaudeService, parentBookmarkUrl: String? = nil) {
+    func start(
+        articleUrl: String,
+        articleTitle: String = "",
+        claude: ClaudeService,
+        parentBookmarkUrl: String? = nil,
+        sourceText: String? = nil,
+        sourceKind: String? = nil
+    ) {
         // Idempotent — don't restart if already generating or playing this article
         if currentArticleUrl == articleUrl && (player != nil || pollingTask != nil) { return }
 
@@ -99,7 +106,12 @@ final class PodcastPlayerViewModel {
 
         pollingTask = Task {
             do {
-                let jobId = try await claude.generatePodcast(url: articleUrl)
+                let jobId = try await claude.generatePodcast(
+                    url: articleUrl,
+                    title: articleTitle,
+                    sourceText: sourceText,
+                    sourceKind: sourceKind
+                )
                 while !Task.isCancelled {
                     let job = try await claude.podcastStatus(jobId: jobId)
                     phase = .generating(

Marks/Views/SourcesView.swift

@@ -0,0 +1,355 @@
+import QuickLook
+import SwiftUI
+import UniformTypeIdentifiers
+
+struct SourcesView: View {
+    @Bindable var library: IngestedSourceLibrary
+    let podcastPlayer: PodcastPlayerViewModel
+    let podcastGenerator: PodcastGenerationManager
+    let claude: ClaudeService
+
+    @State private var searchText = ""
+    @State private var showTextImport = false
+    @State private var showFileImporter = false
+    @State private var selectedSource: IngestedSource?
+    @State private var showFullPlayer = false
+
+    private var results: [IngestedSource] {
+        library.search(searchText)
+    }
+
+    var body: some View {
+        NavigationStack {
+            List {
+                ForEach(results) { source in
+                    HStack(spacing: 10) {
+                        Button {
+                            selectedSource = source
+                        } label: {
+                            SourceRow(source: source)
+                        }
+                        .buttonStyle(.plain)
+
+                        Button {
+                            playOrGeneratePodcast(for: source)
+                        } label: {
+                            Image(systemName: podcastIcon(for: source))
+                                .font(.title3)
+                                .foregroundStyle(.blue)
+                                .frame(width: 36, height: 36)
+                        }
+                        .buttonStyle(.plain)
+                        .disabled(source.podcastText.isEmpty)
+                    }
+                    .swipeActions {
+                        Button {
+                            playOrGeneratePodcast(for: source)
+                        } label: {
+                            Label("Podcast", systemImage: "headphones")
+                        }
+                        .tint(.blue)
+
+                        Button(role: .destructive) {
+                            library.delete(source)
+                        } label: {
+                            Label("Delete", systemImage: "trash")
+                        }
+                    }
+                }
+            }
+            .listStyle(.plain)
+            .navigationTitle("Sources")
+            .toolbar {
+                ToolbarItem(placement: .topBarTrailing) {
+                    Menu {
+                        Button {
+                            showTextImport = true
+                        } label: {
+                            Label("Import Text", systemImage: "doc.text")
+                        }
+                        Button {
+                            showFileImporter = true
+                        } label: {
+                            Label("Import File", systemImage: "doc.badge.plus")
+                        }
+                    } label: {
+                        Image(systemName: "plus")
+                    }
+                }
+            }
+            .overlay {
+                if results.isEmpty {
+                    ContentUnavailableView(
+                        searchText.isEmpty ? "No Sources" : "No Results",
+                        systemImage: searchText.isEmpty ? "tray" : "magnifyingglass",
+                        description: Text(searchText.isEmpty ? "Import text, PDFs, or files to keep non-web material in Marks." : "Try a different search.")
+                    )
+                }
+            }
+            .searchable(text: $searchText, prompt: "Search sources")
+        }
+        .task { library.load() }
+        .sheet(isPresented: $showTextImport) {
+            ImportTextSourceView(library: library)
+        }
+        .sheet(item: $selectedSource) { source in
+            SourceDetailView(
+                source: source,
+                fileURL: library.fileURL(for: source),
+                podcastCached: podcastCached(for: source),
+                podcastGenerating: podcastGenerator.isGenerating(source.podcastURL),
+                onPodcast: {
+                    selectedSource = nil
+                    Task {
+                        try? await Task.sleep(for: .milliseconds(250))
+                        playOrGeneratePodcast(for: source)
+                    }
+                }
+            )
+        }
+        .sheet(isPresented: $showFullPlayer) {
+            PodcastPlayerView(
+                vm: podcastPlayer,
+                articleUrl: podcastPlayer.currentArticleUrl,
+                articleTitle: podcastPlayer.currentArticleTitle,
+                claude: claude,
+                stopOnDismiss: false
+            )
+        }
+        .fileImporter(
+            isPresented: $showFileImporter,
+            allowedContentTypes: [.pdf, .plainText, .text, .data],
+            allowsMultipleSelection: true
+        ) { result in
+            switch result {
+            case .success(let urls):
+                for url in urls {
+                    library.importFile(from: url, tags: [])
+                }
+            case .failure(let error):
+                library.error = error.localizedDescription
+            }
+        }
+        .alert("Source Error", isPresented: Binding(
+            get: { library.error != nil },
+            set: { if !$0 { library.error = nil } }
+        )) {
+            Button("OK") { library.error = nil }
+        } message: {
+            Text(library.error ?? "")
+        }
+    }
+
+    private func playOrGeneratePodcast(for source: IngestedSource) {
+        let podcastURL = source.podcastURL
+        let title = source.displayTitle
+        let existing = PodcastIndex.find(for: podcastURL).first
+
+        if let existing {
+            podcastPlayer.start(articleUrl: existing.articleUrl, articleTitle: existing.title ?? title, claude: claude)
+            showFullPlayer = true
+            return
+        }
+
+        if podcastPlayer.currentArticleUrl.isEmpty {
+            podcastPlayer.start(
+                articleUrl: podcastURL,
+                articleTitle: title,
+                claude: claude,
+                sourceText: source.podcastText,
+                sourceKind: source.kind.rawValue
+            )
+            showFullPlayer = true
+        } else {
+            podcastGenerator.enqueue(
+                articleUrl: podcastURL,
+                title: title,
+                sourceText: source.podcastText,
+                sourceKind: source.kind.rawValue
+            )
+        }
+    }
+
+    private func podcastCached(for source: IngestedSource) -> Bool {
+        FileManager.default.fileExists(atPath: ClaudeService.cachedPodcastURL(for: source.podcastURL).path)
+    }
+
+    private func podcastIcon(for source: IngestedSource) -> String {
+        if podcastGenerator.isGenerating(source.podcastURL) { return "waveform.circle.fill" }
+        if podcastCached(for: source) { return "headphones.circle.fill" }
+        return "headphones.circle"
+    }
+}
+
+private struct SourceRow: View {
+    let source: IngestedSource
+
+    var body: some View {
+        HStack(alignment: .top, spacing: 12) {
+            Image(systemName: iconName)
+                .font(.system(size: 18, weight: .semibold))
+                .foregroundStyle(.blue)
+                .frame(width: 30, height: 30)
+                .background(Color.blue.opacity(0.12), in: RoundedRectangle(cornerRadius: 7))
+
+            VStack(alignment: .leading, spacing: 5) {
+                Text(source.displayTitle)
+                    .font(.headline)
+                    .lineLimit(2)
+                if !source.excerpt.isEmpty {
+                    Text(source.excerpt)
+                        .font(.subheadline)
+                        .foregroundStyle(.secondary)
+                        .lineLimit(2)
+                }
+                HStack(spacing: 8) {
+                    Text(source.kind.label)
+                    Text(source.createdAt, style: .date)
+                    if !source.tags.isEmpty {
+                        Text(source.tags.joined(separator: ", "))
+                    }
+                }
+                .font(.caption)
+                .foregroundStyle(.secondary)
+            }
+        }
+        .padding(.vertical, 8)
+    }
+
+    private var iconName: String {
+        switch source.kind {
+        case .text: "doc.text"
+        case .pdf: "doc.richtext"
+        case .file: "doc"
+        }
+    }
+}
+
+private struct ImportTextSourceView: View {
+    @Bindable var library: IngestedSourceLibrary
+    @Environment(\.dismiss) private var dismiss
+
+    @State private var title = ""
+    @State private var bodyText = ""
+    @State private var tagsText = ""
+
+    var body: some View {
+        NavigationStack {
+            Form {
+                Section("Title") {
+                    TextField("Optional", text: $title)
+                }
+                Section("Text") {
+                    TextEditor(text: $bodyText)
+                        .frame(minHeight: 180)
+                        .textInputAutocapitalization(.sentences)
+                }
+                Section {
+                    TextField("comma separated", text: $tagsText)
+                        .textInputAutocapitalization(.never)
+                        .autocorrectionDisabled()
+                } header: {
+                    Text("Tags")
+                } footer: {
+                    Text("Separate tags with commas")
+                }
+            }
+            .navigationTitle("Import Text")
+            .navigationBarTitleDisplayMode(.inline)
+            .toolbar {
+                ToolbarItem(placement: .cancellationAction) {
+                    Button("Cancel") { dismiss() }
+                }
+                ToolbarItem(placement: .confirmationAction) {
+                    Button("Save") {
+                        library.addText(title: title, body: bodyText, tags: tagsText.parsedTags)
+                        dismiss()
+                    }
+                    .disabled(bodyText.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty)
+                }
+            }
+        }
+    }
+}
+
+private struct SourceDetailView: View {
+    let source: IngestedSource
+    let fileURL: URL?
+    let podcastCached: Bool
+    let podcastGenerating: Bool
+    let onPodcast: () -> Void
+
+    @State private var previewURL: URL?
+
+    var body: some View {
+        NavigationStack {
+            ScrollView {
+                VStack(alignment: .leading, spacing: 16) {
+                    VStack(alignment: .leading, spacing: 6) {
+                        Text(source.displayTitle)
+                            .font(.title2.weight(.semibold))
+                        Text(source.kind.label)
+                            .font(.subheadline)
+                            .foregroundStyle(.secondary)
+                    }
+
+                    if !source.tags.isEmpty {
+                        ScrollView(.horizontal, showsIndicators: false) {
+                            HStack {
+                                ForEach(source.tags, id: \.self) { tag in
+                                    Text(tag)
+                                        .font(.caption.weight(.medium))
+                                        .padding(.horizontal, 10)
+                                        .padding(.vertical, 5)
+                                        .background(Color.blue.opacity(0.12), in: Capsule())
+                                }
+                            }
+                        }
+                    }
+
+                    if let fileURL {
+                        HStack {
+                            Button {
+                                previewURL = fileURL
+                            } label: {
+                                Label("Open Original", systemImage: "doc.viewfinder")
+                            }
+                            .buttonStyle(.bordered)
+
+                            Button {
+                                onPodcast()
+                            } label: {
+                                Label(podcastTitle, systemImage: "headphones")
+                            }
+                            .buttonStyle(.borderedProminent)
+                            .disabled(source.podcastText.isEmpty || podcastGenerating)
+                        }
+                    } else {
+                        Button {
+                            onPodcast()
+                        } label: {
+                            Label(podcastTitle, systemImage: "headphones")
+                        }
+                        .buttonStyle(.borderedProminent)
+                        .disabled(source.podcastText.isEmpty || podcastGenerating)
+                    }
+
+                    Text(source.bodyText.isEmpty ? "No extractable text." : source.bodyText)
+                        .font(.body)
+                        .textSelection(.enabled)
+                        .frame(maxWidth: .infinity, alignment: .leading)
+                }
+                .padding()
+            }
+            .navigationTitle("Source")
+            .navigationBarTitleDisplayMode(.inline)
+        }
+        .quickLookPreview($previewURL)
+    }
+
+    private var podcastTitle: String {
+        if podcastGenerating { return "Generating" }
+        if podcastCached { return "Play Podcast" }
+        return "Create Podcast"
+    }
+}

MarksTests/AppIntentsTests.swift

@@ -104,4 +104,76 @@ final class AppIntentsTests: XCTestCase {
     func testAppShortcutsAreRegistered() {
         XCTAssertGreaterThanOrEqual(MarksShortcuts.appShortcuts.count, 4)
     }
+
+    // MARK: - Ingest payload parsing
+
+    func testIngestParsesDirectURL() {
+        let payload = IngestPayloadParser.parse(item: URL(string: "https://example.com/article")!)
+        XCTAssertEqual(payload?.url, "https://example.com/article")
+        XCTAssertEqual(payload?.notes, "")
+    }
+
+    func testIngestFindsURLInSharedEmailText() {
+        let text = """
+        Thought you might want to save this:
+
+        https://example.com/story?utm_source=newsletter
+
+        Sent from Spark
+        """
+
+        let payload = IngestPayloadParser.parse(item: text, typeIdentifier: "public.plain-text")
+        XCTAssertEqual(payload?.url, "https://example.com/story?utm_source=newsletter")
+        XCTAssertTrue(payload?.notes.contains("Sent from Spark") == true)
+    }
+
+    func testIngestIgnoresMailLinksAndUsesWebURL() {
+        let text = "mailto:friend@example.com\nRead https://example.com/read-later."
+        let payload = IngestPayloadParser.parse(item: text, typeIdentifier: "public.plain-text")
+        XCTAssertEqual(payload?.url, "https://example.com/read-later")
+    }
+
+    func testIngestDecodesHTMLLinksFromEmailClients() {
+        let html = "<p>Save this: <a href=\"https://example.com/a?x=1&amp;y=2\">article</a></p>"
+        let payload = IngestPayloadParser.parse(item: html, typeIdentifier: "public.html")
+        XCTAssertEqual(payload?.url, "https://example.com/a?x=1&y=2")
+    }
+
+    // MARK: - Local sources
+
+    func testSourceStoreSavesAndLoadsMetadata() throws {
+        let root = FileManager.default.temporaryDirectory.appendingPathComponent(UUID().uuidString, isDirectory: true)
+        defer { try? FileManager.default.removeItem(at: root) }
+
+        let store = IngestedSourceStore(rootURL: root)
+        let source = IngestedSource(kind: .text, title: "Meeting Notes", bodyText: "Follow up on paper receipts.", tags: ["receipts"])
+        try store.save([source])
+
+        let loaded = try store.load()
+        XCTAssertEqual(loaded.count, 1)
+        XCTAssertEqual(loaded.first?.id, source.id)
+        XCTAssertEqual(loaded.first?.kind, .text)
+        XCTAssertEqual(loaded.first?.title, "Meeting Notes")
+        XCTAssertEqual(loaded.first?.bodyText, "Follow up on paper receipts.")
+        XCTAssertEqual(loaded.first?.tags, ["receipts"])
+    }
+
+    func testSourceStoreImportsPlainTextFile() throws {
+        let root = FileManager.default.temporaryDirectory.appendingPathComponent(UUID().uuidString, isDirectory: true)
+        let input = FileManager.default.temporaryDirectory.appendingPathComponent("\(UUID().uuidString).txt")
+        defer {
+            try? FileManager.default.removeItem(at: root)
+            try? FileManager.default.removeItem(at: input)
+        }
+
+        try Data("Offline clipping text".utf8).write(to: input)
+
+        let store = IngestedSourceStore(rootURL: root)
+        let source = try store.importFile(from: input, tags: ["offline"])
+
+        XCTAssertEqual(source.kind, .file)
+        XCTAssertEqual(source.bodyText, "Offline clipping text")
+        XCTAssertEqual(source.tags, ["offline"])
+        XCTAssertNotNil(store.fileURL(for: source))
+    }
 }

ShareExtension/ShareView.swift

@@ -5,6 +5,8 @@ import SwiftUI
 /// read-later flag before saving (new) or updating (existing) — never a duplicate.
 struct ShareView: View {
     let url: String
+    let initialTitle: String?
+    let initialNotes: String
     /// Called when the extension should dismiss. `saved` is true after a successful
     /// write, false on cancel.
     let onClose: (_ saved: Bool) -> Void
@@ -26,10 +28,14 @@ struct ShareView: View {
 
     private let api: LinkdingAPI?
 
-    init(url: String, onClose: @escaping (_ saved: Bool) -> Void) {
+    init(url: String, initialTitle: String? = nil, initialNotes: String = "", onClose: @escaping (_ saved: Bool) -> Void) {
         self.url = url
+        self.initialTitle = initialTitle
+        self.initialNotes = initialNotes
         self.onClose = onClose
         self.api = ServerConfig.loadShared().map(LinkdingAPI.init)
+        _title = State(initialValue: initialTitle ?? "")
+        _notes = State(initialValue: initialNotes)
     }
 
     private enum Phase { case loading, editing, saving, done, failed }
@@ -225,6 +231,14 @@ struct ShareView: View {
     // MARK: - Networking
 
     private func check() async {
+        guard let parsed = URL(string: url),
+              let scheme = parsed.scheme?.lowercased(),
+              scheme == "http" || scheme == "https",
+              parsed.host?.isEmpty == false else {
+            errorMessage = "No bookmarkable link found"
+            phase = .failed
+            return
+        }
         guard let api else {
             errorMessage = "Open Marks first"
             phase = .failed
@@ -239,8 +253,11 @@ struct ShareView: View {
                 notes = bookmark.description
                 readLater = bookmark.unread
             } else {
-                title = result.metadata?.title ?? ""
+                title = initialTitle ?? result.metadata?.title ?? ""
                 suggestedTags = result.autoTags ?? []
+                if notes.isEmpty {
+                    notes = result.metadata?.description ?? initialNotes
+                }
             }
             // Pre-enable the toggle when the current tags match the auto-rule.
             createPodcast = PodcastRequests.matchesAutoTag(parsedTags)
@@ -295,6 +312,7 @@ struct ShareView: View {
                 let create = BookmarkCreate(
                     url: url,
                     title: "",
+                    description: notes,
                     tagNames: parsedTags,
                     isArchived: false,
                     unread: readLater,

ShareExtension/ShareViewController.swift

@@ -4,6 +4,13 @@ import UniformTypeIdentifiers
 
 @objc(ShareViewController)
 class ShareViewController: UIViewController {
+    private let supportedTypeIdentifiers = [
+        UTType.url.identifier,
+        UTType.html.identifier,
+        UTType.rtf.identifier,
+        UTType.plainText.identifier,
+        UTType.text.identifier
+    ]
 
     override func viewDidLoad() {
         super.viewDidLoad()
@@ -11,37 +18,49 @@ class ShareViewController: UIViewController {
         blur.frame = view.bounds
         blur.autoresizingMask = [.flexibleWidth, .flexibleHeight]
         view.addSubview(blur)
-        extractURL()
+        extractPayload()
     }
 
-    private func extractURL() {
+    private func extractPayload() {
         guard let item = extensionContext?.inputItems.first as? NSExtensionItem,
               let attachments = item.attachments else {
-            present(url: nil)
+            present(payload: nil)
             return
         }
 
-        func load(typeId: String) -> Bool {
-            guard let attachment = attachments.first(where: { $0.hasItemConformingToTypeIdentifier(typeId) }) else {
-                return false
-            }
-            attachment.loadItem(forTypeIdentifier: typeId, options: nil) { [weak self] item, _ in
-                let urlString = typeId == UTType.url.identifier
-                    ? ((item as? URL)?.absoluteString ?? (item as? String))
-                    : (item as? String)
-                DispatchQueue.main.async { self?.present(url: urlString) }
-            }
-            return true
+        let candidates = attachments.flatMap { attachment in
+            supportedTypeIdentifiers
+                .filter { attachment.hasItemConformingToTypeIdentifier($0) }
+                .map { (attachment, $0) }
         }
 
-        if !load(typeId: UTType.url.identifier) && !load(typeId: UTType.plainText.identifier) {
-            present(url: nil)
+        loadNext(candidates, index: 0)
+    }
+
+    private func loadNext(_ candidates: [(NSItemProvider, String)], index: Int) {
+        guard index < candidates.count else {
+            present(payload: nil)
+            return
+        }
+
+        let (attachment, typeIdentifier) = candidates[index]
+        attachment.loadItem(forTypeIdentifier: typeIdentifier, options: nil) { [weak self] item, _ in
+            guard let self else { return }
+            if let payload = IngestPayloadParser.parse(item: item, typeIdentifier: typeIdentifier) {
+                DispatchQueue.main.async { self.present(payload: payload) }
+            } else {
+                DispatchQueue.main.async { self.loadNext(candidates, index: index + 1) }
+            }
         }
     }
 
     /// Hosts the SwiftUI save card. A nil URL surfaces an error state in the card.
-    private func present(url: String?) {
-        let root = ShareView(url: url ?? "") { [weak self] _ in
+    private func present(payload: IngestPayload?) {
+        let root = ShareView(
+            url: payload?.url ?? "",
+            initialTitle: payload?.title,
+            initialNotes: payload?.notes ?? ""
+        ) { [weak self] _ in
             self?.close()
         }
         let host = UIHostingController(rootView: root)
@@ -52,7 +71,7 @@ class ShareViewController: UIViewController {
         view.addSubview(host.view)
         host.didMove(toParent: self)
 
-        if url == nil {
+        if payload == nil {
             // No URL to work with — let the card render its failure state briefly.
             DispatchQueue.main.asyncAfter(deadline: .now() + 1.6) { [weak self] in self?.close() }
         }

openwiki/.last-update.json

@@ -0,0 +1,11 @@
+{
+  "updatedAt": "2026-07-02T05:28:44Z",
+  "gitHead": "b496e607fc37e795c765355dd99c191518e6f7f2",
+  "mode": "init",
+  "pages": [
+    "openwiki/quickstart.md",
+    "openwiki/architecture/app-architecture.md",
+    "openwiki/workflows/product-workflows.md",
+    "openwiki/operations/development-and-testing.md"
+  ]
+}

openwiki/architecture/app-architecture.md

@@ -0,0 +1,174 @@
+# App Architecture
+
+This page explains how the major Marks runtime pieces fit together. For product-level flows, see [Product workflows](../workflows/product-workflows.md). For setup and verification, see [Development and testing](../operations/development-and-testing.md).
+
+## Targets and source layout
+
+`/project.yml` is the XcodeGen project definition. It defines four targets:
+
+- `Marks` — the main iOS app. Sources include `/Marks` plus `/MarksWidget/WidgetDataStore.swift` so the app can write widget data.
+- `ShareExtension` — app extension with `/ShareExtension` plus selected shared model/service files from `/Marks` (`Bookmark`, `IngestPayload`, `ServerConfig`, `LinkdingAPI`, `MarksAuth`, `Log`, `PodcastRequests`).
+- `MarksWidget` — WidgetKit extension with `/MarksWidget`.
+- `MarksTests` — unit-test bundle depending on `Marks`.
+
+The app is Swift 6.0 and targets iOS 26.0. The main app, share extension, and widget extension share the app group `group.com.magicive.marks` through entitlements and runtime code.
+
+## App entrypoint and navigation shell
+
+`/Marks/MarksApp.swift` contains the `@main` app and `MainContainer`.
+
+At startup:
+
+1. `MarksApp` loads a saved `ServerConfig` or falls back to a built-in default config.
+2. `MainContainer` constructs `LinkdingAPI(config:)`.
+3. `MainContainer` stores `BookmarksViewModel(api:cacheKey:)` in `@State`, keeping the model stable across SwiftUI re-renders.
+4. `MainContainer` also creates an `IngestedSourceLibrary` for local source storage.
+5. A top-level `TabView` presents Bookmarks, Tags, Sources, Podcasts, and Search.
+
+`MainContainer` also handles:
+
+- custom deep links (`marks://bookmark?...`, `marks://podcast?...`),
+- App Intent handoff through `IntentRouter.shared`,
+- pending podcast requests queued by the share extension,
+- foreground refreshes and background podcast progress persistence.
+
+## Central state: `BookmarksViewModel`
+
+`/Marks/Views/BookmarksViewModel.swift` is `@Observable @MainActor` and is the core app state object. It owns:
+
+- loaded bookmarks, errors, loading flags, pagination URL, search query, and unread filter,
+- generated smart collections and enrichment progress,
+- a `LinkdingAPI` actor for server sync,
+- `ClaudeService` for backend AI/podcast calls,
+- `PodcastPlayerViewModel` and `PodcastGenerationManager`,
+- the disk bookmark cache URL.
+
+Key side effects during bookmark loading and mutations:
+
+- `load()` optionally restores cached bookmarks from Application Support, fetches linkding bookmarks, restores local AI metadata, saves the full unfiltered cache, writes recent bookmarks to `WidgetDataStore`, and indexes bookmarks into Spotlight.
+- `loadMore()` follows linkding's `next` URL and indexes newly appended bookmarks.
+- `delete()` and `archive()` mutate linkding, remove local entries, and remove Spotlight entries.
+- `addBookmark()` saves to linkding, inserts locally, indexes the bookmark, and starts best-effort AI enrichment.
+- `enrichAll()` and background `startEnrichment()` call AI enrichment, persist AI metadata, and reindex enriched bookmarks.
+
+Because one `BookmarksViewModel` instance is shared by all tabs, array mutations and filters have cross-tab effects.
+
+## Linkding integration
+
+`/Marks/Services/LinkdingAPI.swift` is an actor wrapping linkding's REST API. It builds URLs from `ServerConfig` (`/Marks/Models/ServerConfig.swift`) and sends `Authorization: Token ...` headers.
+
+Implemented operations include:
+
+- `fetchBookmarks(search:offset:limit:unread:)` → `GET /api/bookmarks/`,
+- `fetchBookmarksFromUrl(_:)` for pagination `next` URLs,
+- `checkBookmark(url:)` → `GET /api/bookmarks/check/`, used by the share extension,
+- `fetchTags(limit:)` → `GET /api/tags/`,
+- `createBookmark(_:)` → `POST /api/bookmarks/`,
+- `updateBookmark(id:update:)` → `PATCH /api/bookmarks/{id}/`,
+- `deleteBookmark(id:)` → `DELETE /api/bookmarks/{id}/`,
+- `archiveBookmark(id:)` → `POST /api/bookmarks/{id}/archive/`,
+- `verifyConnection()` for configuration checks.
+
+`Bookmark`, `BookmarkResponse`, create/update payloads, `BookmarkCheck`, tag response models, and `SmartCollection` live in `/Marks/Models/Bookmark.swift`.
+
+## Local source ingest
+
+Local source ingest is separate from linkding bookmarks. It is owned by:
+
+- `/Marks/Models/IngestedSource.swift` — source metadata for text, PDF, and generic file imports.
+- `/Marks/Services/IngestedSourceStore.swift` — JSON metadata persistence, security-scoped file copying, PDFKit text extraction, plain-text extraction, and local search.
+- `/Marks/Services/SourceSpotlightIndexer.swift` — Spotlight indexing/removal for source title, body text, tags, kind, and original filename.
+- `/Marks/Views/SourcesView.swift` — Sources tab list/search, text import, file importer, QuickLook preview, delete, and podcast actions.
+
+`IngestedSourceStore` writes `Sources/sources.json` and imported originals under `Sources/files/` in Application Support. Text imports store only metadata/body text. File imports copy the selected file into app storage; PDF imports extract text with `PDFDocument`, while other files attempt UTF-8/ASCII extraction.
+
+Source podcasts use `IngestedSource.podcastURL` (`marks-source://{uuid}`) as the podcast cache/index key and send up to 100,000 characters of `bodyText` to the backend as `text`.
+
+## Configuration and app-group sharing
+
+`ServerConfig` contains linkding host, optional port, path, token, and HTTPS flag. Its extension stores config in two places:
+
+- `UserDefaults.standard` for the main app,
+- `UserDefaults(suiteName: "group.com.magicive.marks")` for extensions.
+
+`ServerConfig.loadShared()` is used by the share extension, which cannot read the main app's standard defaults. Avoid changing config keys or app-group IDs without updating all entitlements, `ServerConfig`, `WidgetDataStore`, and `PodcastRequests` together.
+
+Security note: `/Marks/MarksApp.swift` currently includes a built-in default config with a token-like value. Treat it as sensitive; do not copy it into documentation or generated output.
+
+## Backend AI, analytics, and podcasts
+
+`/Marks/Services/MarksAuth.swift` registers an anonymous device with the Marks backend and caches a JWT in `UserDefaults.standard`. `ClaudeService` uses that token for backend calls:
+
+- bookmark enrichment: `POST /v1/marks/enrich`,
+- semantic search: `POST /v1/marks/search`,
+- smart collections: `POST /v1/marks/collections`,
+- podcast generation: `POST /v1/podcast/generate`,
+- podcast polling: `GET /v1/podcast/status/{jobId}`,
+- podcast audio download: `GET /v1/podcast/audio/{jobId}`.
+
+`/Marks/Services/AnalyticsService.swift` sends events through the backend path used by `ClaudeService`/`MarksAuth`.
+
+Podcast generation accepts either a web URL or a local source pseudo-URL. `ClaudeService.generatePodcast(url:title:sourceText:sourceKind:)` always sends `url` and may also send `title`, `text`, and `source_kind`. Podcast audio is downloaded to Application Support under a `podcasts` directory using a stable hash of the article/source URL. `PodcastIndex` records metadata in `index.json`; `PodcastLibrary` reads that index for the Podcasts tab and widget metadata.
+
+## On-device Ask and Spotlight
+
+The app has two AI paths:
+
+1. **Backend AI** through `ClaudeService` for enrichment, semantic search, smart collections, and podcasts.
+2. **On-device RAG** through `/Marks/Services/BookmarkAssistant.swift` for the Ask UI.
+
+`BookmarkAssistant` uses `FoundationModels.LanguageModelSession` with `BookmarkSearchTool`. Its instructions require answers to be grounded in bookmarks. Retrieval flows through Spotlight:
+
+- `SpotlightIndexer` indexes bookmarks after loads, load-more operations, add, and enrichment.
+- `SpotlightBookmarkSearch`/`BookmarkSearchTool` search the index for relevant bookmarks.
+- `BookmarkEntity` also conforms to indexed App Intents concepts for system-level entity discovery.
+
+If changing bookmark fields, keep `Bookmark`, `BookmarkEntity`, Spotlight indexing, widget payloads, and row UI in sync. If changing source fields, keep `IngestedSource`, `IngestedSourceStore`, `SourceSpotlightIndexer`, Sources UI, and source podcast generation in sync.
+
+## Share extension architecture
+
+The share extension is implemented by `/ShareExtension/ShareViewController.swift` and `/ShareExtension/ShareView.swift`.
+
+It accepts shared URL, HTML, RTF, plain-text, and text payloads, uses `IngestPayloadParser` to find the first bookmarkable `http`/`https` URL and preserve non-URL notes, creates a SwiftUI save card, loads shared `ServerConfig`, checks linkding for an existing bookmark, and lets the user edit tags, notes, read-later state, and a Create Podcast toggle.
+
+For suggestions, it combines:
+
+- linkding `checkBookmark` metadata and `auto_tags`,
+- the user's existing tag vocabulary from `fetchTags()`,
+- backend AI tag suggestions through `/ShareExtension/TagSuggester.swift`.
+
+Existing bookmarks are updated rather than duplicated. New bookmarks are created through `LinkdingAPI`. Podcast generation is not performed inside the extension; it queues a `PodcastRequests` item in the app group for the main app to process later. The same parser is used by in-app Add Bookmark text import.
+
+## Widget architecture and deep links
+
+`/MarksWidget/MarksWidgetBundle.swift` registers three widgets:
+
+- `RecentBookmarksWidget` (`systemMedium`),
+- `RandomBookmarkWidget` (`systemSmall`),
+- `RecentPodcastsWidget` (`systemMedium`).
+
+Widgets read only app-group JSON through `/MarksWidget/WidgetDataStore.swift`:
+
+- `widget_bookmarks.json`,
+- `widget_podcasts.json`.
+
+They do not call network APIs. Main-app writes trigger `WidgetCenter.shared.reloadAllTimelines()` when WidgetKit is available.
+
+Widget links use custom URLs built by `URL.marksBookmark(_:)` and `URL.marksPodcast(_:)`. `MainContainer.handleDeepLink(_:)` opens bookmark URLs in `BrowserView` or starts podcast playback and shows the player.
+
+## App Intents and Shortcuts
+
+`/Marks/Intents/MarksAppIntents.swift` defines:
+
+- `OpenBookmarkIntent` — opens a selected `BookmarkEntity` in app.
+- `SearchMarksIntent` — conforms to the system search schema and routes text to the Search tab.
+- `AddBookmarkIntent` — saves a URL headlessly through linkding and refreshes widget data.
+- `ShowUnreadIntent` — fetches up to 10 unread bookmarks.
+- `SummarizeBookmarkIntent` — calls backend AI enrichment for a selected bookmark.
+- `MarksShortcuts` — registers Add Bookmark, Search, Unread, and Summarize shortcuts.
+
+`IntentRouter` bridges intents that need to open UI back into `MainContainer`. `BookmarkEntity` maps between linkding `Bookmark` values and App Intents entities.
+
+## Recent history context
+
+Recent git history shows major investment in ingest and podcast UX: the latest change added local text/PDF/file sources, richer URL extraction for share/add flows, source Spotlight indexing, and source-backed podcast generation. Earlier podcast and AI changes added played/unplayed queues, background podcast generation, share-sheet audio requests, podcast library/index changes, player improvements, on-device RAG, Spotlight indexing, and unified logging. Use those areas cautiously because they span app state, storage, widgets, share extension, and App Intents rather than a single view.

openwiki/operations/development-and-testing.md

@@ -0,0 +1,170 @@
+# Development and Testing
+
+This page covers local setup, generated project guidance, runtime configuration/storage, and verification strategy for changes.
+
+## Local setup
+
+Requirements from `/README.md` and `/project.yml`:
+
+- macOS with Xcode capable of building the declared iOS 26 / Swift 6 project.
+- [XcodeGen](https://github.com/yonaskolb/XcodeGen).
+- A linkding server with API access for real sync testing.
+- Access to the Marks backend for AI, semantic search, smart collections, analytics, and podcast generation flows.
+
+Setup:
+
+```bash
+brew install xcodegen
+xcodegen generate
+open Marks.xcodeproj
+```
+
+Build and run the `Marks` scheme in Xcode. `/project.yml` declares schemes for `Marks`, `MarksWidget`, and `ShareExtension`; the `Marks` scheme builds the app, share extension, and widget extension and runs `MarksTests` in the test action.
+
+## Project generation rules
+
+Use `/project.yml` as the source of truth for targets, source membership, entitlements, and dependencies. Regenerate the Xcode project after changing target membership:
+
+```bash
+xcodegen generate
+```
+
+Common target-membership traps:
+
+- The main app includes `/MarksWidget/WidgetDataStore.swift` directly so it can write widget JSON.
+- The share extension includes selected shared files from `/Marks/Models` and `/Marks/Services`, including `IngestPayload.swift` for URL extraction; if the extension needs new model/service code, add it in `/project.yml`.
+- The app, widget, and share extension all depend on matching app-group entitlements.
+
+## Testing
+
+Current automated test coverage is concentrated in `/MarksTests/AppIntentsTests.swift`.
+
+Covered today:
+
+- `BookmarkEntity` mapping from `Bookmark`, fallback title behavior, and round-trip fields.
+- `EntityIdentifier` encoding.
+- `IntentRouter` open/search setters.
+- Direct no-network `perform()` tests for Search and Open intents.
+- App Shortcuts registration count.
+- `IngestPayloadParser` URL extraction from direct URLs, plain text, HTML-ish text, and notes.
+- `IngestedSourceStore` save/load behavior plus plain-text file import into a temporary root.
+
+Not currently covered by repository tests:
+
+- `BookmarksViewModel` load/cache/pagination/mutation flows.
+- Linkding networking with mocks.
+- AI enrichment, semantic search, smart collections, or podcast backend calls.
+- Share extension save/update/tag suggestion flows.
+- Widget timeline rendering/deep links.
+- Browser reading progress/reader mode.
+- Podcast generation, playback, queue, played/unplayed, and background audio behavior.
+- Sources tab UI, QuickLook presentation, PDF extraction edge cases, and source-backed podcast backend behavior.
+
+Suggested test command:
+
+```bash
+xcodebuild test -scheme Marks -destination 'platform=iOS Simulator,name=iPhone 16'
+```
+
+Use an installed simulator name if `iPhone 16` is unavailable.
+
+## Manual verification checklist by area
+
+Bookmark sync/list changes:
+
+- Launch with valid linkding config.
+- Confirm cached bookmarks render quickly, then network refresh updates the list.
+- Test pull-to-refresh, pagination, unread filter, add, edit, archive, delete.
+- Confirm widget bookmark JSON updates and Spotlight indexing still happens.
+
+Search/tag changes:
+
+- Test linkding search and semantic search separately.
+- Verify unread filter interactions.
+- Confirm Tags tab counts include expected linkding and AI tags.
+
+AI changes:
+
+- Test enrichment on add, background enrichment, Enrich All, semantic search, Smart Collections, and Summarize intent if affected.
+- Test Ask on a device/simulator environment where Apple on-device model availability can be observed; handle unavailable states.
+- Preserve backend privacy expectations: URLs/titles/tags/summaries may be sent to the Marks backend for backend AI paths.
+
+Share extension changes:
+
+- Share a new URL, an already-saved URL, and text/HTML/RTF content that contains a URL plus notes.
+- Verify duplicate-aware update behavior.
+- Test linkding auto-tags, AI suggestion chips, tag parsing, notes, read-later, and Create Podcast.
+- Confirm the extension works when shared config is missing; current UI shows an "Open Marks first" style failure.
+
+Source ingest changes:
+
+- Import typed text with title/tags and confirm it appears in Sources search.
+- Import a text file and a PDF through the file importer; confirm originals copy into Application Support and QuickLook opens imported files.
+- Confirm PDF text extraction works for text PDFs and handles image-only PDFs gracefully.
+- Delete a source and confirm metadata, copied file, and Spotlight entry are removed.
+- Create a podcast from a source and confirm cached playback uses the same `marks-source://` entry.
+
+Podcast changes:
+
+- Generate from bookmark row and Browser view.
+- Start generation while another podcast is playing; confirm background generation does not interrupt playback.
+- Test queue playback, played/unplayed state, delete, sleep timer, saved speed, background audio, remote controls, now-playing metadata, relaunch restore, and widget recent podcasts.
+- Share a URL with Create Podcast and confirm the main app drains and starts the queued request.
+- Generate from a local text/PDF source and confirm backend support for `text` and `source_kind`.
+
+Widget/deep-link changes:
+
+- Confirm `widget_bookmarks.json` and `widget_podcasts.json` are refreshed by main-app writes.
+- Test Recent Bookmarks, Random Bookmark, and Recent Podcasts widgets.
+- Tap bookmark and podcast widget entries and verify `marks://bookmark` and `marks://podcast` routing in `MainContainer`.
+
+App Intents changes:
+
+- Run `MarksTests`.
+- Test Shortcuts/Siri flows for Add Bookmark, Search, Show Unread, Summarize, and Open Bookmark.
+- Verify entity queries still fetch/resolve bookmarks correctly with a configured linkding server.
+
+## Configuration and persistence map
+
+Do not read or document live secret values.
+
+Main app / standard defaults:
+
+- `serverConfig` — linkding config saved by `ServerConfig.save()`.
+- `marksDeviceId`, `marksJWT`, `marksJWTExpiry` — Marks backend auth state from `MarksAuth`.
+- `aiData` — AI summaries/tags by bookmark ID.
+- `aiSummaryByURL` — summary mirror used outside the main bookmark array.
+- `podcastProgress`, `podcastPlaybackSpeed`, `podcastSession` — podcast playback state.
+- `readingProgress` — in-browser reading progress.
+
+App-group defaults/files (`group.com.magicive.marks`):
+
+- `serverConfig` — shared linkding config for extensions.
+- `pendingPodcastRequests` — share extension to main app podcast queue.
+- `podcastAutoTags` — tags that auto-enable podcast creation in the share extension.
+- `widget_bookmarks.json` — recent bookmark widget cache.
+- `widget_podcasts.json` — recent podcast widget cache.
+
+Application Support files:
+
+- `bookmarks_cache.json` or `bookmarks_{host}.json` — cached bookmarks.
+- `Sources/sources.json` — local source metadata.
+- `Sources/files/{uuid}.{ext}` — copied originals for imported PDFs/files.
+- `podcasts/{hash}.mp3` — generated podcast audio.
+- `podcasts/index.json` — podcast metadata and played state.
+
+## Known caveats and stale-doc risks
+
+- `/Marks/MarksApp.swift` contains a built-in default linkding configuration with a token-like value. Treat it as sensitive and consider replacing it with a safer onboarding/configuration flow before distribution.
+- `OnboardingView` exists but is not the active first-launch path in `MarksApp` as currently written.
+- Disconnect behavior currently resets via the default config callback path instead of clearly deleting config and returning to onboarding.
+- README AI provider text appears older than source: current backend AI/podcast features go through `MarksAuth` + `ClaudeService`, while Ask uses Apple's on-device `FoundationModels`.
+- `MarksAuth` stores backend JWT/device state in `UserDefaults`, not Keychain.
+- App-group ID strings are duplicated in code and entitlements; update all occurrences together if changing it.
+- Share-extension podcast queue draining clears requests before generation success, so crash/retry semantics deserve care.
+- Source-backed podcast generation sends extracted text to the Marks backend; if the backend only accepts URL fetches, local source podcasts will fail even though bookmark podcasts still work.
+- Recent git history shows source ingest, podcast, and on-device AI features were added across many files; avoid narrow changes that ignore cross-target data flow.
+
+## Existing design guidance
+
+`/docs/design-wwdc26.md` is a useful source for UI direction. It emphasizes native iOS 26 UI/Liquid Glass behavior, editorial bookmark rows as the brand canvas, Dynamic Type-safe row layout, bottom/reachable search patterns, WidgetKit app-group data, and standard platform affordances. Link to it rather than duplicating the full design brief.

openwiki/quickstart.md

@@ -0,0 +1,85 @@
+# Marks OpenWiki Quickstart
+
+Marks is a native SwiftUI iOS client for [linkding](https://github.com/sissbruecker/linkding), a self-hosted bookmark manager. The app targets iOS 26 and Swift 6, and includes a main app, share extension, widget extension, App Intents, AI-assisted bookmark features, local source ingest, and podcast generation/playback.
+
+Start here when changing the repository, then follow the page links below for the area you are touching.
+
+## What this repository contains
+
+- **Main iOS app** in `/Marks` with SwiftUI tabs for bookmarks, tags, sources, podcasts, and search. The entrypoint is `/Marks/MarksApp.swift`.
+- **Models** in `/Marks/Models`, centered on `Bookmark`, linkding response/create/update payloads, tags, smart collections, `ServerConfig`, URL ingest payloads, and locally ingested sources.
+- **Services** in `/Marks/Services` for linkding networking, AI/backend calls, auth, on-device bookmark Q&A, Spotlight indexing, source storage, widget/podcast data, analytics, and logging.
+- **Views** in `/Marks/Views` for the primary product surfaces. `BookmarksViewModel` is the central app state object.
+- **App Intents** in `/Marks/Intents` for opening, searching, adding, listing unread, and summarizing bookmarks.
+- **Share extension** in `/ShareExtension` for extracting URLs from shared URLs, text, HTML, and RTF, saving to linkding, and queueing podcast generation.
+- **Widget extension** in `/MarksWidget` for recent bookmarks, random bookmark, and recent podcast widgets.
+- **Tests** in `/MarksTests`, currently focused on App Intents plus ingest parser/source-store coverage.
+- **XcodeGen project spec** in `/project.yml`; `Marks.xcodeproj` is generated/checked in but `project.yml` is the project definition to inspect first.
+- **Design notes** in `/docs/design-wwdc26.md` for iOS 26/Liquid Glass, search, widgets, and row-design guidance.
+
+## Major documentation pages
+
+- [Architecture notes](architecture/app-architecture.md) — target layout, state flow, networking, persistence, AI, Spotlight, extensions, widgets, and App Intents.
+- [Product workflows](workflows/product-workflows.md) — how bookmark browsing, saving, AI enrichment, Ask, smart collections, podcasts, widgets, and intents behave.
+- [Development and testing](operations/development-and-testing.md) — setup/build/test commands, generated project guidance, storage/config map, verification checklist, and caveats.
+
+## Build and run
+
+The README documents the intended local setup:
+
+```bash
+brew install xcodegen
+xcodegen generate
+open Marks.xcodeproj
+```
+
+Then build and run from Xcode using the `Marks` scheme. `/project.yml` defines Swift 6.0, iOS 26.0 deployment target, the `Marks`, `ShareExtension`, `MarksWidget`, and `MarksTests` targets, and the app-group entitlements used by all app surfaces.
+
+Useful checks before shipping a change:
+
+```bash
+xcodegen generate
+xcodebuild test -scheme Marks -destination 'platform=iOS Simulator,name=iPhone 16'
+```
+
+Adjust the simulator name to what is installed locally.
+
+## Runtime architecture in one minute
+
+At launch, `MarksApp` loads a `ServerConfig`, constructs `LinkdingAPI`, and stores a shared `BookmarksViewModel` in `MainContainer` so it survives SwiftUI re-renders (`/Marks/MarksApp.swift`, `/Marks/Views/BookmarksViewModel.swift`). The top-level `TabView` has Bookmarks, Tags, Sources, Podcasts, and Search tabs.
+
+`BookmarksViewModel` fetches paginated bookmarks from linkding through `LinkdingAPI`, restores local AI metadata, caches bookmarks to Application Support, writes recent bookmark metadata for widgets, and indexes bookmarks into Spotlight. It also owns `ClaudeService`, `PodcastPlayerViewModel`, and `PodcastGenerationManager`, so AI, podcast, search, and list state are shared across tabs. `MainContainer` separately owns `IngestedSourceLibrary` for the Sources tab.
+
+Local sources are stored in Application Support under `Sources/`: `sources.json` stores metadata, `Sources/files/` stores imported files, PDF text is extracted with PDFKit, and sources are indexed into Spotlight through `SourceSpotlightIndexer`.
+
+Extensions and widgets use the shared app group `group.com.magicive.marks`. `ServerConfig.save()` writes to standard defaults and the app-group defaults; `WidgetDataStore` writes app-group JSON files for widgets; `PodcastRequests` uses app-group defaults to hand podcast requests from the share extension to the main app.
+
+## External systems and privacy boundaries
+
+- **linkding** is the source of truth for bookmarks and tags. `LinkdingAPI` uses token auth and calls linkding bookmark, check, tag, create, update, delete, archive, and connection-test endpoints.
+- **Marks backend** is used by `MarksAuth`/`ClaudeService` for AI enrichment, semantic search, smart collections, analytics events, and podcast generation/audio download.
+- **Apple on-device intelligence and Spotlight** power the in-app Ask surface via `FoundationModels`, `CoreSpotlight`, and the `BookmarkSearchTool` retrieval path. Spotlight is also used for locally ingested sources.
+- **WidgetKit, App Intents, AVFoundation, and MediaPlayer** support widgets, Siri/Shortcuts integration, podcast playback, background audio, now-playing metadata, and remote controls.
+
+Do not document or expose secret values. `/Marks/MarksApp.swift` currently contains a built-in default server configuration with a token-like value; treat it as sensitive source material and avoid copying it into docs, logs, screenshots, or tests.
+
+## Important caveats for future agents
+
+- The README says optional AI features use OpenRouter/Gemini directly. Current source routes backend AI/podcast calls through `MarksAuth` + `ClaudeService`; the in-app Ask feature is on-device via `FoundationModels`. Prefer source evidence when changing AI behavior.
+- `OnboardingView` exists, but current launch flow uses saved-or-default config directly. Do not assume onboarding is active without changing `/Marks/MarksApp.swift`.
+- Settings' disconnect callback currently resets to the built-in default config path rather than forcing onboarding. Confirm intended product behavior before changing account/config flows.
+- `BookmarksViewModel` is shared across tabs, so changes to bookmark arrays, filters, search, enrichment, and pagination can affect Bookmarks, Tags, Search, Podcasts, widgets, and Spotlight indexing.
+- Share-extension podcast requests are queued in shared defaults and drained by the main app on launch/foreground. Be careful with crash/retry semantics when touching that flow.
+- Local source podcasts use `marks-source://{uuid}` pseudo-URLs plus extracted text sent to `ClaudeService.generatePodcast(...)`. The backend must accept `text` and `source_kind` for non-web podcast generation.
+- Existing automated tests cover App Intents plus focused ingest parser/source-store behavior. For UI, networking, sync, share extension, widgets, and podcasts, add tests where feasible and perform manual verification.
+
+## Where to start for common changes
+
+- Bookmark list, pagination, search, tags, enrichment state: `/Marks/Views/BookmarksViewModel.swift`, `/Marks/Views/BookmarksView.swift`, `/Marks/Services/LinkdingAPI.swift`.
+- Linkding API changes: `/Marks/Services/LinkdingAPI.swift`, `/Marks/Models/Bookmark.swift`, `/ShareExtension/ShareView.swift`, `/Marks/Intents/IntentSupport.swift`.
+- AI/backend changes: `/Marks/Services/ClaudeService.swift`, `/Marks/Services/MarksAuth.swift`, `/Marks/Services/BookmarkAssistant.swift`, `/Marks/Services/BookmarkSearchTool.swift`.
+- Source ingest and local documents: `/Marks/Views/SourcesView.swift`, `/Marks/Models/IngestedSource.swift`, `/Marks/Services/IngestedSourceStore.swift`, `/Marks/Services/SourceSpotlightIndexer.swift`.
+- Podcast generation/playback: `/Marks/Services/PodcastGenerationManager.swift`, `/Marks/Services/PodcastIndex.swift`, `/Marks/Views/PodcastPlayerView.swift`, `/Marks/Views/BookmarksViewModel.swift`, `/Marks/Views/SourcesView.swift`.
+- Share extension and text/link extraction: `/Marks/Models/IngestPayload.swift`, `/ShareExtension/ShareViewController.swift`, `/ShareExtension/ShareView.swift`, `/ShareExtension/TagSuggester.swift`, plus shared files declared in `/project.yml`.
+- Widgets/deep links: `/MarksWidget/WidgetDataStore.swift`, `/MarksWidget/*Widget.swift`, `/Marks/MarksApp.swift`.
+- App Intents/Siri/Shortcuts: `/Marks/Intents/*`, `/MarksTests/AppIntentsTests.swift`.

openwiki/workflows/product-workflows.md

@@ -0,0 +1,172 @@
+# Product Workflows
+
+This page describes the user-facing behavior implemented by the app and the source files that own each flow.
+
+## Browse bookmarks
+
+Primary sources: `/Marks/Views/BookmarksView.swift`, `/Marks/Views/BookmarkListRow.swift`, `/Marks/Views/BookmarksViewModel.swift`, `/Marks/Services/LinkdingAPI.swift`.
+
+The Bookmarks tab loads linkding bookmarks through `BookmarksViewModel.load()`. The view supports loading skeletons, pull-to-refresh, pagination as the user scrolls, an unread filter, and row actions.
+
+A bookmark row displays title/domain/date context, unread state, available excerpt/AI summary, tags/AI tags, reading progress, and podcast-cache state. Tapping opens `BrowserView`. Swipe/context actions support archive, delete, edit, Safari open, and podcast conversion.
+
+Change guidance:
+
+- Keep row actions aligned across `BookmarksView`, `BookmarkListRow`, `BookmarkRow`, and `BrowserView`.
+- `BookmarksViewModel.saveToCache(_:)` intentionally skips saving when the unread filter is active, so filtered results do not replace the full cache.
+- Pagination uses linkding's `next` URL through `fetchBookmarksFromUrl(_:)`; do not rebuild next URLs unless the linkding API contract changes.
+
+## Add and edit bookmarks in app
+
+Primary sources: `/Marks/Views/AddBookmarkView.swift`, `/Marks/Views/EditBookmarkView.swift`, `/Marks/Views/BookmarksViewModel.swift`, `/Marks/Models/Bookmark.swift`.
+
+The Add view collects URL, optional title, description/notes, and comma-separated tags, normalizes/validates the URL, and calls `BookmarksViewModel.addBookmark(url:title:description:tags:)`. It also has a paste/import text path that uses `IngestPayloadParser` to extract the first `http`/`https` URL from plain text and preserve surrounding notes as the bookmark description. Added bookmarks are inserted locally, indexed into Spotlight, and enriched in a background task.
+
+The Edit view updates URL, title, description, tags, unread, and shared state through `BookmarkUpdate`. `BookmarksViewModel.updateBookmark(_:)` preserves locally stored AI summary/tags when replacing the bookmark returned from linkding.
+
+## Search and semantic search
+
+Primary sources: `/Marks/Views/SearchView.swift`, `/Marks/Views/BookmarksViewModel.swift`, `/Marks/Services/ClaudeService.swift`.
+
+The Search tab has two paths:
+
+- normal search through linkding's bookmark API (`q` parameter),
+- semantic search through `ClaudeService.semanticSearch(query:in:)`, which fetches up to 200 bookmarks and sends a compact list to the backend for ranking.
+
+`SearchMarksIntent` routes spoken/system search text into `IntentRouter`, `MainContainer` switches to the Search tab, and `SearchView` consumes the router text into its visible search field.
+
+Change guidance:
+
+- Search state lives on the shared `BookmarksViewModel`; search and unread filters can affect list state outside Search.
+- Backend semantic search sends bookmark titles/domains and optional summaries to the Marks backend. Preserve that privacy boundary in UI copy and docs.
+
+## Tags
+
+Primary sources: `/Marks/Views/TagsView.swift`, `/Marks/Models/Bookmark.swift`.
+
+The Tags tab derives tag counts from both linkding tags (`Bookmark.tagNames`) and local AI tags (`Bookmark.aiTags`), sorted by count/name. Tapping a tag shows matching bookmarks and reuses bookmark row/browser flows.
+
+If changing tag semantics, check in-app Add/Edit, share extension tag parsing, linkding `fetchTags()`, AI suggestions, Tags tab counts, and App Intents bookmark entity fields.
+
+## AI enrichment and smart collections
+
+Primary sources: `/Marks/Services/ClaudeService.swift`, `/Marks/Views/BookmarksViewModel.swift`, `/Marks/Views/CollectionsView.swift`, `/Marks/Services/AISummaryStore.swift`.
+
+AI enrichment generates a short summary and tags for a bookmark. The app stores AI metadata locally in `UserDefaults.standard` under `aiData`, keyed by bookmark ID, and mirrors summaries by URL through `AISummaryStore` for podcast/list display.
+
+Enrichment can happen in three ways:
+
+- after adding a bookmark,
+- as a silent background pass over up to five loaded bookmarks without summaries,
+- manually through Enrich All.
+
+Smart Collections send up to 150 bookmarks to the backend and render the returned collection names, descriptions, and bookmark IDs in `CollectionsView`.
+
+Caveat: README language mentions OpenRouter/Gemini directly, but current source uses the Marks backend proxy for these calls.
+
+## Ask your bookmarks
+
+Primary sources: `/Marks/Views/AskView.swift`, `/Marks/Services/BookmarkAssistant.swift`, `/Marks/Services/BookmarkSearchTool.swift`, `/Marks/Services/SpotlightBookmarkSearch.swift`, `/Marks/Services/SpotlightIndexer.swift`.
+
+Ask is an on-device RAG workflow. `BookmarkAssistant` creates a `FoundationModels` language model session with a bookmark search tool. The model instructions say bookmarks are the only source of truth and require the tool for lookup.
+
+The retrieval corpus comes from Spotlight. `BookmarksViewModel` indexes bookmarks after loading, loading more, adding, and enrichment. Deleted/archived bookmarks are removed from Spotlight.
+
+Change guidance:
+
+- If Ask gives stale answers, inspect Spotlight indexing and removal paths first.
+- If changing indexed fields, update `BookmarkEntity`, `SpotlightIndexer`, search tooling, and tests where relevant.
+- The Ask path is separate from backend semantic search and does not use `ClaudeService`.
+
+## Share extension save flow
+
+Primary sources: `/Marks/Models/IngestPayload.swift`, `/ShareExtension/ShareViewController.swift`, `/ShareExtension/ShareView.swift`, `/ShareExtension/TagSuggester.swift`, `/Marks/Services/PodcastRequests.swift`, `/project.yml`.
+
+The share extension scans URL, HTML, RTF, plain-text, and text attachments, then `IngestPayloadParser` extracts the first bookmarkable web URL. For non-URL text payloads it also preserves cleaned surrounding text as notes. On load it:
+
+1. reads linkding config from app-group defaults,
+2. calls `LinkdingAPI.checkBookmark(url:)`,
+3. pre-fills existing bookmark data or scraped metadata/linkding auto-tags,
+4. fetches existing tag vocabulary and backend AI tag suggestions,
+5. lets the user edit tags, notes, read-later state, and Create Podcast.
+
+On save, existing bookmarks are patched; new bookmarks are created. If Create Podcast is enabled, or if configured auto-tags match, the extension enqueues a `PodcastRequests` item instead of generating audio itself.
+
+Change guidance:
+
+- The extension is short-lived. Keep long-running work in the main app.
+- The extension depends on shared source files listed in `/project.yml`; adding service dependencies may require target membership updates.
+- `IngestPayloadParser` intentionally ignores non-HTTP(S) URLs and caps preserved notes at 1,800 characters.
+- `ShareExtension/Info.plist` currently uses a broad activation rule. Narrowing supported payloads is a product decision.
+
+## Sources
+
+Primary sources: `/Marks/Views/SourcesView.swift`, `/Marks/Models/IngestedSource.swift`, `/Marks/Services/IngestedSourceStore.swift`, `/Marks/Services/SourceSpotlightIndexer.swift`.
+
+The Sources tab stores non-web material in Marks. Users can:
+
+- import typed/pasted text with an optional title and tags,
+- import PDFs, plain text files, generic text/data files through the document picker,
+- search across source title, body text, tags, and original filename,
+- open imported originals through QuickLook,
+- delete sources and copied files,
+- create or play a podcast from extractable source text.
+
+`IngestedSourceLibrary.load()` reads `Sources/sources.json` from Application Support and indexes sources into Spotlight. Text imports write metadata/body text directly. File imports copy the selected security-scoped file into `Sources/files/`; PDFs extract text with PDFKit, while other files attempt UTF-8/ASCII extraction.
+
+Change guidance:
+
+- Empty or image-only PDFs may import with no extractable text; podcast actions are disabled when `podcastText` is empty.
+- Source podcasts use `marks-source://{uuid}` as the cache/index URL and send extracted text plus `source_kind` to the backend.
+- If changing source storage, update deletion, Spotlight removal, QuickLook file lookup, and source podcast cache behavior together.
+
+## Podcasts
+
+Primary sources: `/Marks/Views/PodcastPlayerView.swift`, `/Marks/Services/PodcastGenerationManager.swift`, `/Marks/Services/PodcastIndex.swift`, `/Marks/Services/PodcastLibrary.swift`, `/Marks/Services/ClaudeService.swift`, `/Marks/Services/PodcastRequests.swift`, `/Marks/Info.plist`.
+
+Podcast generation converts an article URL, or a locally ingested source with extracted text, into audio through the Marks backend:
+
+1. create generation job (`/v1/podcast/generate`),
+2. poll status every few seconds,
+3. download audio when done,
+4. save MP3 under Application Support `podcasts/`,
+5. upsert `PodcastIndex`,
+6. reload `PodcastLibrary`,
+7. write recent podcast metadata for widgets.
+
+`BookmarksViewModel.playOrGeneratePodcast(...)` prevents interrupting current bookmark playback. If the player is idle, it starts foreground generation/playback and callers present the player. If busy, it enqueues background generation through `PodcastGenerationManager`. `SourcesView` follows the same foreground/background pattern for local sources, using `marks-source://{uuid}` plus `sourceText`/`sourceKind`.
+
+The player uses AVFoundation/MediaPlayer for playback, background audio, progress, saved playback speed, restored paused session, queue playback, now-playing metadata, remote controls, sleep timer, and played/unplayed state.
+
+Change guidance:
+
+- The main app plist enables background audio and the custom `marks` URL scheme.
+- Widget podcast metadata is in the app group, but audio files and `PodcastIndex` are in the main app's Application Support directory.
+- Share-extension queued podcast requests are drained by `BookmarksViewModel.processPendingPodcastRequests()` on launch/foreground. Consider retry semantics before changing drain behavior.
+- Source-backed podcast generation depends on backend support for the optional `text` and `source_kind` fields in `POST /v1/podcast/generate`.
+
+## Widgets and deep links
+
+Primary sources: `/MarksWidget/WidgetDataStore.swift`, `/MarksWidget/RecentBookmarksWidget.swift`, `/MarksWidget/RandomBookmarkWidget.swift`, `/MarksWidget/RecentPodcastsWidget.swift`, `/Marks/MarksApp.swift`.
+
+Widgets are offline readers of app-group JSON data:
+
+- Recent Bookmarks shows up to three recent bookmarks and links rows to `marks://bookmark`.
+- Random Bookmark chooses a random cached bookmark and links the whole widget to `marks://bookmark`.
+- Recent Podcasts shows up to three podcasts and links rows to `marks://podcast`.
+
+The main app handles bookmark links by presenting `BrowserView`; podcast links start playback and show `PodcastPlayerView`.
+
+## App Intents, Siri, and Shortcuts
+
+Primary sources: `/Marks/Intents/MarksAppIntents.swift`, `/Marks/Intents/BookmarkEntity.swift`, `/Marks/Intents/IntentSupport.swift`, `/Marks/Intents/BookmarkOnscreen.swift`, `/MarksTests/AppIntentsTests.swift`.
+
+Implemented intents:
+
+- Open Bookmark — routes a selected entity URL into the app browser.
+- Search Marks — system search schema; opens Search tab with criteria text.
+- Add Bookmark — headless linkding save and widget refresh.
+- Show Unread Bookmarks — fetches up to ten unread items.
+- Summarize Bookmark — backend AI summary for a selected bookmark.
+
+`BookmarkEntity` maps linkding bookmarks into App Intents entities. Browser presentations annotate current bookmarks for on-screen entity references. Tests currently cover entity mapping, router behavior, direct no-network open/search intent perform calls, and shortcut registration.

project.yml

@@ -86,6 +86,7 @@ targets:
       # Shared with the main app so the extension can talk to linkding + the AI
       # backend (the save card checks for duplicates and suggests tags).
       - path: Marks/Models/Bookmark.swift
+      - path: Marks/Models/IngestPayload.swift
       - path: Marks/Models/ServerConfig.swift
       - path: Marks/Services/LinkdingAPI.swift
       - path: Marks/Services/MarksAuth.swift