Phase 1 done

app/android/app/src/main/AndroidManifest.xml

@@ -48,5 +48,15 @@
             <action android:name="android.intent.action.PROCESS_TEXT"/>
             <data android:mimeType="text/plain"/>
         </intent>
+        <!-- url_launcher: open Maps (save-place action) via an https link. -->
+        <intent>
+            <action android:name="android.intent.action.VIEW"/>
+            <data android:scheme="https"/>
+        </intent>
+        <!-- add_2_calendar: insert a reminder/session into a calendar app. -->
+        <intent>
+            <action android:name="android.intent.action.INSERT"/>
+            <data android:mimeType="vnd.android.cursor.dir/event"/>
+        </intent>
     </queries>
 </manifest>

app/ios/Runner/Info.plist

@@ -2,6 +2,8 @@
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 <plist version="1.0">
 <dict>
+	<key>NSCalendarsUsageDescription</key>
+	<string>Cachy adds reminders and sessions from your cards to your calendar.</string>
 	<key>CADisableMinimumFrameDurationOnPhone</key>
 	<true/>
 	<key>CFBundleDevelopmentRegion</key>

app/lib/data/repositories/card_repository.dart

@@ -5,6 +5,7 @@ library;
 
 import 'dart:convert';
 
+import '../../domain/models/artifact.dart';
 import '../../domain/models/card.dart';
 import '../../domain/models/enums.dart';
 import '../../domain/models/pipeline_event.dart';
@@ -101,6 +102,19 @@ class CardRepository {
 
   Future<List<Card>> search(String query) => _api.search(query);
 
+  /// Grounded chat over one card (docs/13). Network-only; the conversation is
+  /// held in the view model and replayed each turn.
+  Future<String> chat(String cardId, List<Map<String, String>> messages) =>
+      _api.chat(cardId, messages);
+
+  /// The aggregated artifact catalog (docs/12). Network-only for now — these
+  /// are remote-thumbnail entries with no offline-render requirement.
+  Future<List<CatalogEntry>> catalog({ArtifactType? type}) =>
+      _api.listCatalog(type: type);
+
+  Future<void> deleteCatalogEntry(String artifactId) =>
+      _api.deleteCatalogEntry(artifactId);
+
   /// Reconstruct the raw JSON for caching. Uses preserved `rawBlocks` so block
   /// state round-trips losslessly.
   Map<String, dynamic> _rawOf(Card card) => {

app/lib/data/services/api_client.dart

@@ -7,6 +7,7 @@ import 'dart:convert';
 
 import 'package:http/http.dart' as http;
 
+import '../../domain/models/artifact.dart';
 import '../../domain/models/card.dart';
 import '../../domain/models/enums.dart';
 import '../../domain/models/pipeline_event.dart';
@@ -121,6 +122,41 @@ class ApiClient {
     return _decodeList(resp).map(Card.fromJson).toList();
   }
 
+  /// Grounded Q&A over one card (docs/13). Stateless: send the full history each
+  /// turn as [{'role','content'}]; returns the assistant's reply text.
+  Future<String> chat(String cardId, List<Map<String, String>> messages) async {
+    final resp = await _client.post(
+      _uri('/cards/$cardId/chat'),
+      headers: const {'content-type': 'application/json'},
+      body: jsonEncode({'messages': messages}),
+    );
+    return (_decodeMap(resp)['reply'] as String?) ?? '';
+  }
+
+  // ------------------------------------------------------------------------- //
+  // Catalog — referenced artifacts aggregated across cards (docs/12)
+  // ------------------------------------------------------------------------- //
+
+  Future<List<CatalogEntry>> listCatalog({
+    ArtifactType? type,
+    int limit = 200,
+    int offset = 0,
+  }) async {
+    final resp = await _client.get(_uri('/catalog', {
+      'type': ?type?.wire,
+      'limit': limit,
+      'offset': offset,
+    }));
+    return _decodeList(resp).map(CatalogEntry.fromJson).toList();
+  }
+
+  Future<void> deleteCatalogEntry(String artifactId) async {
+    final resp = await _client.delete(_uri('/catalog/$artifactId'));
+    if (resp.statusCode >= 400) {
+      throw ApiException(resp.statusCode, resp.body);
+    }
+  }
+
   // ------------------------------------------------------------------------- //
   // SSE pipeline stream — GET /cards/{id}/stream
   // ------------------------------------------------------------------------- //

app/lib/domain/models/artifact.dart

@@ -0,0 +1,115 @@
+/// Catalog artifact: a real-world thing a video references — book, movie,
+/// podcast, product, place, etc. Mirrors the backend catalog contract
+/// (docs/12, backend models/artifact.py). Parsing is tolerant: unknown type
+/// degrades to [ArtifactType.other] rather than throwing.
+library;
+
+enum ArtifactType {
+  book,
+  movie,
+  tvShow,
+  podcast,
+  music,
+  product,
+  place,
+  app,
+  other;
+
+  static ArtifactType fromWire(String? value) {
+    switch (value) {
+      case 'book':
+        return ArtifactType.book;
+      case 'movie':
+        return ArtifactType.movie;
+      case 'tv_show':
+        return ArtifactType.tvShow;
+      case 'podcast':
+        return ArtifactType.podcast;
+      case 'music':
+        return ArtifactType.music;
+      case 'product':
+        return ArtifactType.product;
+      case 'place':
+        return ArtifactType.place;
+      case 'app':
+        return ArtifactType.app;
+      default:
+        return ArtifactType.other;
+    }
+  }
+
+  String get wire {
+    switch (this) {
+      case ArtifactType.tvShow:
+        return 'tv_show';
+      default:
+        return name;
+    }
+  }
+
+  /// Plural label used as a catalog section header.
+  String get sectionLabel {
+    switch (this) {
+      case ArtifactType.book:
+        return 'Books';
+      case ArtifactType.movie:
+        return 'Movies';
+      case ArtifactType.tvShow:
+        return 'TV Shows';
+      case ArtifactType.podcast:
+        return 'Podcasts';
+      case ArtifactType.music:
+        return 'Music';
+      case ArtifactType.product:
+        return 'Products';
+      case ArtifactType.place:
+        return 'Places';
+      case ArtifactType.app:
+        return 'Apps';
+      case ArtifactType.other:
+        return 'Other';
+    }
+  }
+}
+
+class CatalogEntry {
+  const CatalogEntry({
+    required this.id,
+    this.type = ArtifactType.other,
+    required this.title,
+    this.creator,
+    this.year,
+    this.thumbnail,
+    this.sourceCardIds = const [],
+  });
+
+  final String id;
+  final ArtifactType type;
+  final String title;
+  final String? creator;
+  final int? year;
+  final String? thumbnail;
+  final List<String> sourceCardIds;
+
+  /// "James Clear · 2018", "2018", or "" — the dimmed subtitle line.
+  String get subtitle {
+    final parts = <String>[
+      if (creator != null && creator!.isNotEmpty) creator!,
+      if (year != null) '$year',
+    ];
+    return parts.join(' · ');
+  }
+
+  factory CatalogEntry.fromJson(Map<String, dynamic> json) => CatalogEntry(
+        id: (json['id'] as String?) ?? '',
+        type: ArtifactType.fromWire(json['type'] as String?),
+        title: (json['title'] as String?) ?? '',
+        creator: json['creator'] as String?,
+        year: (json['year'] as num?)?.toInt(),
+        thumbnail: json['thumbnail'] as String?,
+        sourceCardIds: (json['source_card_ids'] as List?)
+                ?.map((e) => e.toString())
+                .toList() ??
+            const [],
+      );
+}

app/lib/main.dart

@@ -12,8 +12,8 @@ import 'package:receive_sharing_intent/receive_sharing_intent.dart';
 import 'data/repositories/card_repository.dart';
 import 'data/services/api_client.dart';
 import 'data/services/local_store.dart';
+import 'ui/core/home_shell.dart';
 import 'ui/core/theme.dart';
-import 'ui/features/library/views/library_screen.dart';
 import 'ui/features/share/views/share_screen.dart';
 
 Future<void> main() async {
@@ -100,7 +100,7 @@ class _CachyAppState extends State<CachyApp> {
         theme: AppTheme.light(),
         darkTheme: AppTheme.dark(),
         themeMode: ThemeMode.system,
-        home: const LibraryScreen(),
+        home: const HomeShell(),
       ),
     );
   }

app/lib/ui/core/home_shell.dart

@@ -0,0 +1,46 @@
+/// Root navigation shell: the two top-level spaces — Library (your cards) and
+/// Catalog (artifacts referenced across them, docs/12). An IndexedStack keeps
+/// each tab's state alive across switches.
+library;
+
+import 'package:flutter/material.dart';
+
+import '../features/catalog/views/catalog_screen.dart';
+import '../features/library/views/library_screen.dart';
+
+class HomeShell extends StatefulWidget {
+  const HomeShell({super.key});
+
+  @override
+  State<HomeShell> createState() => _HomeShellState();
+}
+
+class _HomeShellState extends State<HomeShell> {
+  int _index = 0;
+
+  @override
+  Widget build(BuildContext context) {
+    return Scaffold(
+      body: IndexedStack(
+        index: _index,
+        children: const [LibraryScreen(), CatalogScreen()],
+      ),
+      bottomNavigationBar: NavigationBar(
+        selectedIndex: _index,
+        onDestinationSelected: (i) => setState(() => _index = i),
+        destinations: const [
+          NavigationDestination(
+            icon: Icon(Icons.video_library_outlined),
+            selectedIcon: Icon(Icons.video_library_rounded),
+            label: 'Library',
+          ),
+          NavigationDestination(
+            icon: Icon(Icons.auto_stories_outlined),
+            selectedIcon: Icon(Icons.auto_stories_rounded),
+            label: 'Catalog',
+          ),
+        ],
+      ),
+    );
+  }
+}

app/lib/ui/features/catalog/view_models/catalog_view_model.dart

@@ -0,0 +1,91 @@
+/// Catalog state (MVVM). Loads aggregated artifacts from the repository, groups
+/// them by type for sectioned display, and supports a type filter + delete.
+library;
+
+import 'package:flutter/foundation.dart';
+
+import '../../../../data/repositories/card_repository.dart';
+import '../../../../domain/models/artifact.dart';
+
+enum CatalogStatus { idle, loading, ready, error, empty }
+
+/// One display section: a type and its entries.
+class CatalogSection {
+  const CatalogSection(this.type, this.entries);
+  final ArtifactType type;
+  final List<CatalogEntry> entries;
+}
+
+class CatalogViewModel extends ChangeNotifier {
+  CatalogViewModel({required CardRepository repository})
+      : _repository = repository;
+
+  final CardRepository _repository;
+
+  CatalogStatus _status = CatalogStatus.idle;
+  CatalogStatus get status => _status;
+
+  List<CatalogEntry> _entries = const [];
+
+  ArtifactType? _filter;
+  ArtifactType? get filter => _filter;
+
+  String? _error;
+  String? get error => _error;
+
+  /// The type filters that actually have entries, in catalog order — so the
+  /// filter bar never offers an empty category.
+  List<ArtifactType> get availableTypes {
+    final seen = <ArtifactType>{for (final e in _entries) e.type};
+    return ArtifactType.values.where(seen.contains).toList();
+  }
+
+  /// Entries grouped into sections (respecting the active filter).
+  List<CatalogSection> get sections {
+    final visible = _filter == null
+        ? _entries
+        : _entries.where((e) => e.type == _filter).toList();
+    final out = <CatalogSection>[];
+    for (final type in ArtifactType.values) {
+      final group = visible.where((e) => e.type == type).toList();
+      if (group.isNotEmpty) out.add(CatalogSection(type, group));
+    }
+    return out;
+  }
+
+  Future<void> load({bool showSpinner = true}) async {
+    if (showSpinner) {
+      _status = CatalogStatus.loading;
+      notifyListeners();
+    }
+    try {
+      _entries = await _repository.catalog();
+      _status =
+          _entries.isEmpty ? CatalogStatus.empty : CatalogStatus.ready;
+      _error = null;
+    } catch (e) {
+      _error = '$e';
+      _status = _entries.isEmpty ? CatalogStatus.error : CatalogStatus.ready;
+    }
+    notifyListeners();
+  }
+
+  Future<void> refresh() => load(showSpinner: false);
+
+  void setFilter(ArtifactType? type) {
+    if (_filter == type) return;
+    _filter = type;
+    notifyListeners();
+  }
+
+  Future<void> delete(String artifactId) async {
+    _entries = _entries.where((e) => e.id != artifactId).toList();
+    if (_entries.isEmpty) _status = CatalogStatus.empty;
+    notifyListeners();
+    try {
+      await _repository.deleteCatalogEntry(artifactId);
+    } catch (_) {
+      await load(showSpinner: false); // resync on failure
+    }
+  }
+}

app/lib/ui/features/catalog/views/catalog_screen.dart

@@ -0,0 +1,320 @@
+/// The catalog: a browsable wall of artifact covers (docs/12) — every book,
+/// movie, podcast, product, and place referenced across the user's cards,
+/// deduplicated and grouped by type. Thumbnails are remote (free image APIs)
+/// and degrade to a typed placeholder when absent or unreachable.
+library;
+
+import 'package:flutter/material.dart';
+import 'package:provider/provider.dart';
+
+import '../../../../data/repositories/card_repository.dart';
+import '../../../../domain/models/artifact.dart';
+import '../../../core/theme.dart';
+import '../view_models/catalog_view_model.dart';
+
+class CatalogScreen extends StatelessWidget {
+  const CatalogScreen({super.key});
+
+  @override
+  Widget build(BuildContext context) {
+    return ChangeNotifierProvider(
+      create: (ctx) =>
+          CatalogViewModel(repository: ctx.read<CardRepository>())..load(),
+      child: const _CatalogView(),
+    );
+  }
+}
+
+class _CatalogView extends StatelessWidget {
+  const _CatalogView();
+
+  @override
+  Widget build(BuildContext context) {
+    final vm = context.watch<CatalogViewModel>();
+    return Scaffold(
+      appBar: AppBar(
+        title: const Text('Catalog'),
+        bottom: vm.availableTypes.isEmpty
+            ? null
+            : PreferredSize(
+                preferredSize: const Size.fromHeight(50),
+                child: _FilterBar(
+                  types: vm.availableTypes,
+                  selected: vm.filter,
+                  onSelect: vm.setFilter,
+                ),
+              ),
+      ),
+      body: RefreshIndicator(
+        onRefresh: vm.refresh,
+        child: _body(context, vm),
+      ),
+    );
+  }
+
+  Widget _body(BuildContext context, CatalogViewModel vm) {
+    switch (vm.status) {
+      case CatalogStatus.loading:
+        return const Center(child: CircularProgressIndicator());
+      case CatalogStatus.error:
+        return _Message(
+          icon: Icons.wifi_off_rounded,
+          title: "Can't reach the backend",
+          subtitle: vm.error ?? '',
+          action: FilledButton(onPressed: vm.load, child: const Text('Retry')),
+        );
+      case CatalogStatus.empty:
+        return const _Message(
+          icon: Icons.auto_stories_outlined,
+          title: 'Nothing catalogued yet',
+          subtitle:
+              'Books, movies, podcasts and places mentioned in your cards '
+              'show up here automatically.',
+        );
+      case CatalogStatus.idle:
+      case CatalogStatus.ready:
+        final sections = vm.sections;
+        return ListView.builder(
+          padding: const EdgeInsets.fromLTRB(Insets.page, 8, Insets.page, 96),
+          physics: const AlwaysScrollableScrollPhysics(),
+          itemCount: sections.length,
+          itemBuilder: (ctx, i) => _Section(section: sections[i], vm: vm),
+        );
+    }
+  }
+}
+
+class _Section extends StatelessWidget {
+  const _Section({required this.section, required this.vm});
+  final CatalogSection section;
+  final CatalogViewModel vm;
+
+  @override
+  Widget build(BuildContext context) {
+    final theme = Theme.of(context);
+    return Column(
+      crossAxisAlignment: CrossAxisAlignment.start,
+      children: [
+        Padding(
+          padding: const EdgeInsets.only(top: 16, bottom: 10),
+          child: Text(
+            section.type.sectionLabel,
+            style: theme.textTheme.titleMedium
+                ?.copyWith(fontWeight: FontWeight.w700),
+          ),
+        ),
+        GridView.builder(
+          shrinkWrap: true,
+          physics: const NeverScrollableScrollPhysics(),
+          gridDelegate: const SliverGridDelegateWithFixedCrossAxisCount(
+            crossAxisCount: 3,
+            mainAxisSpacing: 14,
+            crossAxisSpacing: 14,
+            childAspectRatio: 0.58,
+          ),
+          itemCount: section.entries.length,
+          itemBuilder: (ctx, i) => _ArtifactTile(
+            entry: section.entries[i],
+            onDelete: () => vm.delete(section.entries[i].id),
+          ),
+        ),
+      ],
+    );
+  }
+}
+
+class _ArtifactTile extends StatelessWidget {
+  const _ArtifactTile({required this.entry, required this.onDelete});
+  final CatalogEntry entry;
+  final VoidCallback onDelete;
+
+  @override
+  Widget build(BuildContext context) {
+    final theme = Theme.of(context);
+    return GestureDetector(
+      onLongPress: () => _confirmDelete(context),
+      child: Column(
+        crossAxisAlignment: CrossAxisAlignment.start,
+        children: [
+          AspectRatio(
+            aspectRatio: 0.72,
+            child: ClipRRect(
+              borderRadius: BorderRadius.circular(12),
+              child: _Cover(entry: entry),
+            ),
+          ),
+          const SizedBox(height: 6),
+          Text(
+            entry.title,
+            maxLines: 2,
+            overflow: TextOverflow.ellipsis,
+            style: theme.textTheme.bodySmall
+                ?.copyWith(fontWeight: FontWeight.w600, height: 1.2),
+          ),
+          if (entry.subtitle.isNotEmpty)
+            Text(
+              entry.subtitle,
+              maxLines: 1,
+              overflow: TextOverflow.ellipsis,
+              style: theme.textTheme.labelSmall
+                  ?.copyWith(color: theme.colorScheme.onSurfaceVariant),
+            ),
+        ],
+      ),
+    );
+  }
+
+  Future<void> _confirmDelete(BuildContext context) async {
+    final ok = await showDialog<bool>(
+      context: context,
+      builder: (ctx) => AlertDialog(
+        title: const Text('Remove from catalog?'),
+        content: Text('“${entry.title}” will be removed from the catalog.'),
+        actions: [
+          TextButton(
+            onPressed: () => Navigator.pop(ctx, false),
+            child: const Text('Cancel'),
+          ),
+          FilledButton(
+            onPressed: () => Navigator.pop(ctx, true),
+            child: const Text('Remove'),
+          ),
+        ],
+      ),
+    );
+    if (ok == true) onDelete();
+  }
+}
+
+/// The cover image with a typed placeholder fallback. `Image.network` errors
+/// (offline, dead hotlink, 404) degrade to the placeholder, never crash.
+class _Cover extends StatelessWidget {
+  const _Cover({required this.entry});
+  final CatalogEntry entry;
+
+  @override
+  Widget build(BuildContext context) {
+    final thumb = entry.thumbnail;
+    if (thumb == null || thumb.isEmpty) return _Placeholder(type: entry.type);
+    return Image.network(
+      thumb,
+      fit: BoxFit.cover,
+      errorBuilder: (context, error, stack) => _Placeholder(type: entry.type),
+      loadingBuilder: (ctx, child, progress) =>
+          progress == null ? child : _Placeholder(type: entry.type),
+    );
+  }
+}
+
+class _Placeholder extends StatelessWidget {
+  const _Placeholder({required this.type});
+  final ArtifactType type;
+
+  static const _icons = {
+    ArtifactType.book: Icons.menu_book_rounded,
+    ArtifactType.movie: Icons.movie_rounded,
+    ArtifactType.tvShow: Icons.tv_rounded,
+    ArtifactType.podcast: Icons.podcasts_rounded,
+    ArtifactType.music: Icons.music_note_rounded,
+    ArtifactType.product: Icons.shopping_bag_rounded,
+    ArtifactType.place: Icons.place_rounded,
+    ArtifactType.app: Icons.apps_rounded,
+    ArtifactType.other: Icons.category_rounded,
+  };
+
+  @override
+  Widget build(BuildContext context) {
+    final theme = Theme.of(context);
+    return ColoredBox(
+      color: theme.colorScheme.surfaceContainerHighest,
+      child: Center(
+        child: Icon(
+          _icons[type] ?? Icons.category_rounded,
+          size: 32,
+          color: theme.colorScheme.onSurfaceVariant,
+        ),
+      ),
+    );
+  }
+}
+
+class _FilterBar extends StatelessWidget {
+  const _FilterBar({
+    required this.types,
+    required this.selected,
+    required this.onSelect,
+  });
+  final List<ArtifactType> types;
+  final ArtifactType? selected;
+  final ValueChanged<ArtifactType?> onSelect;
+
+  @override
+  Widget build(BuildContext context) {
+    return SizedBox(
+      height: 50,
+      child: ListView(
+        scrollDirection: Axis.horizontal,
+        padding: const EdgeInsets.symmetric(horizontal: Insets.page),
+        children: [
+          Padding(
+            padding: const EdgeInsets.only(right: 8),
+            child: ChoiceChip(
+              label: const Text('All'),
+              selected: selected == null,
+              onSelected: (_) => onSelect(null),
+            ),
+          ),
+          for (final type in types)
+            Padding(
+              padding: const EdgeInsets.only(right: 8),
+              child: ChoiceChip(
+                label: Text(type.sectionLabel),
+                selected: selected == type,
+                onSelected: (_) => onSelect(type),
+              ),
+            ),
+        ],
+      ),
+    );
+  }
+}
+
+class _Message extends StatelessWidget {
+  const _Message({
+    required this.icon,
+    required this.title,
+    required this.subtitle,
+    this.action,
+  });
+  final IconData icon;
+  final String title;
+  final String subtitle;
+  final Widget? action;
+
+  @override
+  Widget build(BuildContext context) {
+    final theme = Theme.of(context);
+    return ListView(
+      physics: const AlwaysScrollableScrollPhysics(),
+      children: [
+        SizedBox(height: MediaQuery.of(context).size.height * 0.22),
+        Icon(icon, size: 52, color: theme.colorScheme.outline),
+        const SizedBox(height: 16),
+        Text(title,
+            textAlign: TextAlign.center, style: theme.textTheme.titleLarge),
+        const SizedBox(height: 8),
+        Padding(
+          padding: const EdgeInsets.symmetric(horizontal: 48),
+          child: Text(subtitle,
+              textAlign: TextAlign.center,
+              style: theme.textTheme.bodyMedium
+                  ?.copyWith(color: theme.colorScheme.onSurfaceVariant)),
+        ),
+        if (action != null) ...[
+          const SizedBox(height: 20),
+          Center(child: action!),
+        ],
+      ],
+    );
+  }
+}

app/lib/ui/features/library/view_models/library_view_model.dart

@@ -2,6 +2,8 @@
 /// pull-to-refresh, filtering by state, and delete. Falls back to cache offline.
 library;
 
+import 'dart:async';
+
 import 'package:flutter/foundation.dart';
 
 import '../../../../data/repositories/card_repository.dart';
@@ -31,6 +33,63 @@ class LibraryViewModel extends ChangeNotifier {
   bool _offline = false;
   bool get offline => _offline;
 
+  // --- search (full-text, /search endpoint) ------------------------------ //
+  String _query = '';
+  String get query => _query;
+  bool get searching => _query.trim().isNotEmpty;
+
+  List<Card> _results = const [];
+  List<Card> get results => List.unmodifiable(_results);
+
+  bool _searchBusy = false;
+  bool get searchBusy => _searchBusy;
+
+  Timer? _debounce;
+
+  /// Cards to render: search hits when a query is active, else the library.
+  List<Card> get visibleCards => searching ? _results : cards;
+
+  void setQuery(String value) {
+    _query = value;
+    notifyListeners();
+    _debounce?.cancel();
+    if (value.trim().isEmpty) {
+      _results = const [];
+      _searchBusy = false;
+      notifyListeners();
+      return;
+    }
+    _searchBusy = true;
+    notifyListeners();
+    _debounce = Timer(const Duration(milliseconds: 300), () => _runSearch(value));
+  }
+
+  void clearSearch() {
+    _debounce?.cancel();
+    _query = '';
+    _results = const [];
+    _searchBusy = false;
+    notifyListeners();
+  }
+
+  Future<void> _runSearch(String value) async {
+    try {
+      final hits = await _repository.search(value.trim());
+      if (value != _query) return; // a newer keystroke superseded this one
+      _results = hits;
+    } catch (_) {
+      _results = const [];
+    }
+    _searchBusy = false;
+    notifyListeners();
+  }
+
+  @override
+  void dispose() {
+    _debounce?.cancel();
+    super.dispose();
+  }
+
   Future<void> load({bool showSpinner = true}) async {
     if (showSpinner) {
       _status = LibraryStatus.loading;

app/lib/ui/features/library/views/library_screen.dart

@@ -49,17 +49,27 @@ class _LibraryView extends StatelessWidget {
             ),
         ],
         bottom: PreferredSize(
-          preferredSize: const Size.fromHeight(50),
-          child: _FilterBar(
-            selected: vm.filter,
-            onSelect: vm.setFilter,
+          preferredSize: const Size.fromHeight(108),
+          child: Column(
+            children: [
+              _SearchField(
+                query: vm.query,
+                busy: vm.searchBusy,
+                onChanged: vm.setQuery,
+                onClear: vm.clearSearch,
+              ),
+              _FilterBar(
+                selected: vm.filter,
+                onSelect: vm.setFilter,
+              ),
+            ],
           ),
         ),
       ),
       floatingActionButton: FloatingActionButton.extended(
         onPressed: () => _openPaste(context),
         icon: const Icon(Icons.add_link_rounded),
-        label: const Text('Add reel'),
+        label: const Text('Add link'),
       ),
       body: RefreshIndicator(
         onRefresh: vm.refresh,
@@ -69,6 +79,21 @@ class _LibraryView extends StatelessWidget {
   }
 
   Widget _body(BuildContext context, LibraryViewModel vm, api) {
+    // An active search overrides the normal library/status views.
+    if (vm.searching) {
+      if (vm.searchBusy && vm.results.isEmpty) {
+        return const Center(child: CircularProgressIndicator());
+      }
+      if (vm.results.isEmpty) {
+        return _Message(
+          icon: Icons.search_off_rounded,
+          title: 'No matches',
+          subtitle: 'Nothing in your library matches “${vm.query.trim()}”.',
+        );
+      }
+      return _grid(context, vm.results, vm, api);
+    }
+
     switch (vm.status) {
       case LibraryStatus.loading:
         return const Center(child: CircularProgressIndicator());
@@ -83,36 +108,40 @@ class _LibraryView extends StatelessWidget {
         return const _Message(
           icon: Icons.video_library_outlined,
           title: 'No cards yet',
-          subtitle: 'Share a reel or paste a link to make your first card.',
+          subtitle: 'Share or paste any link — a reel, article, or post.',
         );
       case LibraryStatus.idle:
       case LibraryStatus.ready:
-        return GridView.builder(
-          padding: const EdgeInsets.fromLTRB(
-              Insets.page, 12, Insets.page, 96),
-          physics: const AlwaysScrollableScrollPhysics(),
-          gridDelegate: const SliverGridDelegateWithFixedCrossAxisCount(
-            crossAxisCount: 2,
-            mainAxisSpacing: 14,
-            crossAxisSpacing: 14,
-            childAspectRatio: 0.72,
+        return _grid(context, vm.cards, vm, api);
+    }
+  }
+
+  Widget _grid(
+      BuildContext context, List cards, LibraryViewModel vm, api) {
+    return GridView.builder(
+      padding: const EdgeInsets.fromLTRB(Insets.page, 12, Insets.page, 96),
+      physics: const AlwaysScrollableScrollPhysics(),
+      gridDelegate: const SliverGridDelegateWithFixedCrossAxisCount(
+        crossAxisCount: 2,
+        mainAxisSpacing: 14,
+        crossAxisSpacing: 14,
+        childAspectRatio: 0.72,
+      ),
+      itemCount: cards.length,
+      itemBuilder: (ctx, i) {
+        final card = cards[i];
+        return CardTile(
+          card: card,
+          api: api,
+          onTap: () => Navigator.of(ctx).push(
+            MaterialPageRoute(
+              builder: (_) => ReaderScreen(cardId: card.cardId),
+            ),
           ),
-          itemCount: vm.cards.length,
-          itemBuilder: (ctx, i) {
-            final card = vm.cards[i];
-            return CardTile(
-              card: card,
-              api: api,
-              onTap: () => Navigator.of(ctx).push(
-                MaterialPageRoute(
-                  builder: (_) => ReaderScreen(cardId: card.cardId),
-                ),
-              ),
-              onDelete: () => vm.delete(card.cardId),
-            );
-          },
+          onDelete: () => vm.delete(card.cardId),
         );
-    }
+      },
+    );
   }
 
   Future<void> _openPaste(BuildContext context) async {
@@ -131,15 +160,19 @@ class _LibraryView extends StatelessWidget {
           mainAxisSize: MainAxisSize.min,
           crossAxisAlignment: CrossAxisAlignment.start,
           children: [
-            Text('Paste a reel link',
+            Text('Paste a link',
                 style: Theme.of(ctx).textTheme.titleLarge),
+            const SizedBox(height: 6),
+            Text('Reel, article, post, or page — any source.',
+                style: Theme.of(ctx).textTheme.bodyMedium?.copyWith(
+                    color: Theme.of(ctx).colorScheme.onSurfaceVariant)),
             const SizedBox(height: 14),
             TextField(
               controller: controller,
               autofocus: true,
               keyboardType: TextInputType.url,
               decoration: const InputDecoration(
-                hintText: 'https://instagram.com/reel/…',
+                hintText: 'https://…',
                 border: OutlineInputBorder(),
               ),
               onSubmitted: (v) => Navigator.pop(ctx, v),
@@ -162,6 +195,72 @@ class _LibraryView extends StatelessWidget {
   }
 }
 
+class _SearchField extends StatefulWidget {
+  const _SearchField({
+    required this.query,
+    required this.busy,
+    required this.onChanged,
+    required this.onClear,
+  });
+  final String query;
+  final bool busy;
+  final ValueChanged<String> onChanged;
+  final VoidCallback onClear;
+
+  @override
+  State<_SearchField> createState() => _SearchFieldState();
+}
+
+class _SearchFieldState extends State<_SearchField> {
+  late final TextEditingController _controller =
+      TextEditingController(text: widget.query);
+
+  @override
+  void dispose() {
+    _controller.dispose();
+    super.dispose();
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    return Padding(
+      padding: const EdgeInsets.fromLTRB(Insets.page, 4, Insets.page, 4),
+      child: TextField(
+        controller: _controller,
+        textInputAction: TextInputAction.search,
+        onChanged: (v) {
+          setState(() {}); // refresh the clear-button affordance
+          widget.onChanged(v);
+        },
+        decoration: InputDecoration(
+          isDense: true,
+          hintText: 'Search your cards',
+          prefixIcon: widget.busy
+              ? const Padding(
+                  padding: EdgeInsets.all(12),
+                  child: SizedBox(
+                    width: 18,
+                    height: 18,
+                    child: CircularProgressIndicator(strokeWidth: 2),
+                  ),
+                )
+              : const Icon(Icons.search_rounded),
+          suffixIcon: _controller.text.isEmpty
+              ? null
+              : IconButton(
+                  icon: const Icon(Icons.close_rounded),
+                  onPressed: () {
+                    _controller.clear();
+                    widget.onClear();
+                  },
+                ),
+          border: const OutlineInputBorder(),
+        ),
+      ),
+    );
+  }
+}
+
 class _FilterBar extends StatelessWidget {
   const _FilterBar({required this.selected, required this.onSelect});
   final CardState? selected;

app/lib/ui/features/reader/services/card_actions.dart

@@ -0,0 +1,263 @@
+/// The action layer (docs/13): turns a card into things the device can do.
+/// Actions are **content-aware** — derived from the blocks a card actually has,
+/// not just its content_type — plus a common set offered on every card. Every
+/// payload is built client-side from existing blocks, so nothing here needs a
+/// schema change. All handlers are best-effort and never crash the reader.
+library;
+
+import 'package:add_2_calendar/add_2_calendar.dart';
+import 'package:flutter/material.dart' hide Card;
+import 'package:flutter/services.dart';
+import 'package:share_plus/share_plus.dart';
+import 'package:url_launcher/url_launcher.dart';
+
+import '../../../../domain/models/block.dart';
+import '../../../../domain/models/card.dart';
+
+/// Outcome of an action so the UI can show the right message.
+enum ActionResult { done, copied, empty, failed }
+
+/// Every side-effect action the action layer can perform. (Chat/"Ask" is a
+/// navigation concern handled by the reader, not a side-effect, so it's not here.)
+enum CardActionType {
+  copy,
+  share,
+  openOriginal,
+  addToCalendar,
+  shoppingList,
+  openMaps,
+  openLinks,
+}
+
+/// A presentable action: what to label it and which icon to show.
+class CardActionSpec {
+  const CardActionSpec(this.type, this.label, this.icon);
+  final CardActionType type;
+  final String label;
+  final IconData icon;
+}
+
+class CardActions {
+  const CardActions();
+
+  /// The ordered, content-aware action set for a card. Common actions first,
+  /// then ones unlocked by the blocks this card actually contains.
+  List<CardActionSpec> available(Card card) {
+    final out = <CardActionSpec>[
+      const CardActionSpec(CardActionType.copy, 'Copy', Icons.copy_rounded),
+      const CardActionSpec(CardActionType.share, 'Share', Icons.ios_share_rounded),
+      const CardActionSpec(
+          CardActionType.addToCalendar, 'Add to calendar', Icons.event_rounded),
+    ];
+    if (_hasPlace(card)) {
+      out.add(const CardActionSpec(
+          CardActionType.openMaps, 'Open in Maps', Icons.map_rounded));
+    }
+    if (_hasListItems(card)) {
+      out.add(const CardActionSpec(CardActionType.shoppingList, 'Shopping list',
+          Icons.add_shopping_cart_rounded));
+    }
+    if (_hasLinks(card)) {
+      out.add(const CardActionSpec(
+          CardActionType.openLinks, 'Open links', Icons.link_rounded));
+    }
+    if (card.source.url.isNotEmpty) {
+      out.add(const CardActionSpec(CardActionType.openOriginal, 'Open original',
+          Icons.play_circle_outline_rounded));
+    }
+    return out;
+  }
+
+  /// Map the server-derived primary action to a concrete handler so the big
+  /// primary button runs through the same dispatch as the secondary set.
+  CardActionType? primaryType(Card card) {
+    switch (card.primaryAction.kind.name) {
+      case 'export':
+        return CardActionType.share;
+      case 'shoppingList':
+        return CardActionType.shoppingList;
+      case 'savePlace':
+        return CardActionType.openMaps;
+      case 'reminder':
+      case 'schedule':
+        return CardActionType.addToCalendar;
+      default:
+        return null;
+    }
+  }
+
+  Future<ActionResult> perform(Card card, CardActionType type) async {
+    try {
+      switch (type) {
+        case CardActionType.copy:
+          return _copy(card);
+        case CardActionType.share:
+          return _share(_cardToMarkdown(card), card.base.oneLiner);
+        case CardActionType.openOriginal:
+          return _launch(card.source.url);
+        case CardActionType.addToCalendar:
+          return _addToCalendar(card);
+        case CardActionType.shoppingList:
+          return _shareShoppingList(card);
+        case CardActionType.openMaps:
+          return _openInMaps(card);
+        case CardActionType.openLinks:
+          return _openLinks(card);
+      }
+    } catch (_) {
+      return ActionResult.failed;
+    }
+  }
+
+  // --- block predicates -------------------------------------------------- //
+
+  bool _hasPlace(Card card) =>
+      card.blocks.any((b) => b is MapBlock && b.places.isNotEmpty);
+
+  bool _hasListItems(Card card) => card.blocks.any(
+      (b) => b is ChecklistBlock || b is BulletListBlock);
+
+  bool _hasLinks(Card card) => card.blocks.any((b) => b is LinkBlock);
+
+  // --- handlers ---------------------------------------------------------- //
+
+  Future<ActionResult> _copy(Card card) async {
+    final text = _cardToMarkdown(card);
+    if (text.trim().isEmpty) return ActionResult.empty;
+    await Clipboard.setData(ClipboardData(text: text));
+    return ActionResult.copied;
+  }
+
+  Future<ActionResult> _share(String text, String subject) async {
+    if (text.trim().isEmpty) return ActionResult.empty;
+    await Share.share(text, subject: subject.isEmpty ? 'Cachy card' : subject);
+    return ActionResult.done;
+  }
+
+  Future<ActionResult> _launch(String url) async {
+    if (url.trim().isEmpty) return ActionResult.empty;
+    final ok = await launchUrl(Uri.parse(url),
+        mode: LaunchMode.externalApplication);
+    return ok ? ActionResult.done : ActionResult.failed;
+  }
+
+  Future<ActionResult> _shareShoppingList(Card card) async {
+    final items = <String>[];
+    for (final b in card.blocks) {
+      if (b is ChecklistBlock) {
+        items.addAll(b.items.map((i) => i.text));
+      } else if (b is BulletListBlock) {
+        items.addAll(b.items);
+      }
+    }
+    final clean = items.where((i) => i.trim().isNotEmpty).toList();
+    if (clean.isEmpty) return ActionResult.empty;
+    final title = card.base.oneLiner.isEmpty ? 'Shopping list' : card.base.oneLiner;
+    final body = '$title\n\n${clean.map((i) => '- [ ] $i').join('\n')}';
+    return _share(body, title);
+  }
+
+  Future<ActionResult> _openInMaps(Card card) async {
+    Place? place;
+    for (final b in card.blocks) {
+      if (b is MapBlock && b.places.isNotEmpty) {
+        place = b.places.first;
+        break;
+      }
+    }
+    final query = place?.name ?? card.base.oneLiner;
+    if (query.trim().isEmpty) return ActionResult.empty;
+    final Uri uri;
+    if (place?.lat != null && place?.lng != null) {
+      uri = Uri.parse(
+        'https://www.google.com/maps/search/?api=1&query=${place!.lat},${place.lng}',
+      );
+    } else {
+      uri = Uri.parse(
+        'https://www.google.com/maps/search/?api=1&query=${Uri.encodeComponent(query)}',
+      );
+    }
+    final ok = await launchUrl(uri, mode: LaunchMode.externalApplication);
+    return ok ? ActionResult.done : ActionResult.failed;
+  }
+
+  Future<ActionResult> _openLinks(Card card) async {
+    final urls = card.blocks
+        .whereType<LinkBlock>()
+        .map((b) => b.url)
+        .where((u) => u.trim().isNotEmpty)
+        .toList();
+    if (urls.isEmpty) return ActionResult.empty;
+    // Open the first link; the rest stay visible as tappable link blocks.
+    return _launch(urls.first);
+  }
+
+  Future<ActionResult> _addToCalendar(Card card) async {
+    final title = card.base.oneLiner.isEmpty ? 'Cachy reminder' : card.base.oneLiner;
+    final start = DateTime.now().add(const Duration(days: 1));
+    final desc = [card.base.tldr, card.source.url]
+        .where((s) => s.trim().isNotEmpty)
+        .join('\n\n');
+    final event = Event(
+      title: title,
+      description: desc,
+      startDate: start,
+      endDate: start.add(const Duration(hours: 1)),
+    );
+    final ok = await Add2Calendar.addEvent2Cal(event);
+    return ok ? ActionResult.done : ActionResult.failed;
+  }
+
+  // --- markdown serialization (copy / share) ----------------------------- //
+
+  String _cardToMarkdown(Card card) {
+    final out = <String>[];
+    if (card.base.oneLiner.isNotEmpty) out.add('# ${card.base.oneLiner}');
+    if (card.base.tldr.isNotEmpty) out.add('> ${card.base.tldr}');
+    for (final b in card.blocks) {
+      out.add(_blockToMarkdown(b));
+    }
+    if (card.source.url.isNotEmpty) {
+      out.add('---\nSource: ${card.source.url}');
+    }
+    return out.where((s) => s.trim().isNotEmpty).join('\n\n');
+  }
+
+  String _blockToMarkdown(Block b) {
+    switch (b) {
+      case HeadingBlock(:final text, :final level):
+        return '${'#' * level.clamp(1, 6)} $text';
+      case ParagraphBlock(:final text):
+        return text;
+      case BulletListBlock(:final items):
+        return items.map((i) => '- $i').join('\n');
+      case StepListBlock(:final steps):
+        return steps
+            .asMap()
+            .entries
+            .map((e) => '${e.key + 1}. ${e.value.text}')
+            .join('\n');
+      case KeyValueBlock(:final pairs):
+        return pairs.map((p) => '**${p.key}:** ${p.value}').join('\n');
+      case ChecklistBlock(:final items):
+        return items
+            .map((i) => '- [${i.checked ? 'x' : ' '}] ${i.text}')
+            .join('\n');
+      case CalloutBlock(:final text):
+        return '> $text';
+      case LinkBlock(:final url, :final label):
+        return '[${label ?? url}]($url)';
+      case MapBlock(:final places):
+        return places
+            .map((p) => '- ${p.name}${p.note.isEmpty ? '' : ' — ${p.note}'}')
+            .join('\n');
+      case TableBlock(:final headers, :final rows):
+        final head = '| ${headers.join(' | ')} |';
+        final sep = '| ${headers.map((_) => '---').join(' | ')} |';
+        final body = rows.map((r) => '| ${r.join(' | ')} |').join('\n');
+        return '$head\n$sep\n$body';
+      case UnknownBlock(:final text):
+        return text ?? '';
+    }
+  }
+}

app/lib/ui/features/reader/view_models/chat_view_model.dart

@@ -0,0 +1,62 @@
+/// Chat Q&A over a single card (docs/13). Stateless on the server: this view
+/// model holds the conversation and replays the whole history on every turn.
+library;
+
+import 'package:flutter/foundation.dart';
+
+import '../../../../data/repositories/card_repository.dart';
+import '../../../../data/services/api_client.dart';
+
+class ChatMessage {
+  const ChatMessage({required this.role, required this.content});
+  final String role; // "user" | "assistant"
+  final String content;
+
+  bool get isUser => role == 'user';
+  Map<String, String> toWire() => {'role': role, 'content': content};
+}
+
+class ChatViewModel extends ChangeNotifier {
+  ChatViewModel({required CardRepository repository, required this.cardId})
+      : _repository = repository;
+
+  final CardRepository _repository;
+  final String cardId;
+
+  final List<ChatMessage> _messages = [];
+  List<ChatMessage> get messages => List.unmodifiable(_messages);
+
+  bool _busy = false;
+  bool get busy => _busy;
+
+  String? _error;
+  String? get error => _error;
+
+  bool get isEmpty => _messages.isEmpty;
+
+  Future<void> send(String text) async {
+    final trimmed = text.trim();
+    if (trimmed.isEmpty || _busy) return;
+
+    _messages.add(ChatMessage(role: 'user', content: trimmed));
+    _busy = true;
+    _error = null;
+    notifyListeners();
+
+    try {
+      final reply = await _repository.chat(
+        cardId,
+        _messages.map((m) => m.toWire()).toList(),
+      );
+      _messages.add(ChatMessage(role: 'assistant', content: reply));
+    } on ApiException catch (e) {
+      _error = e.statusCode == 503
+          ? 'Chat is unavailable — no AI backend is configured.'
+          : "Couldn't get an answer. Try again.";
+    } catch (_) {
+      _error = "Couldn't reach the backend.";
+    }
+    _busy = false;
+    notifyListeners();
+  }
+}

app/lib/ui/features/reader/views/chat_screen.dart

@@ -0,0 +1,213 @@
+/// Ask-the-card screen (docs/13): a grounded chat over one card's content.
+/// Answers come from the backend LLM using only the card as context, so the
+/// header carries the standard "AI-generated, may contain errors" note.
+library;
+
+import 'package:flutter/material.dart';
+import 'package:provider/provider.dart';
+
+import '../../../../data/repositories/card_repository.dart';
+import '../view_models/chat_view_model.dart';
+
+class ChatScreen extends StatelessWidget {
+  const ChatScreen({super.key, required this.cardId, required this.title});
+  final String cardId;
+  final String title;
+
+  @override
+  Widget build(BuildContext context) {
+    return ChangeNotifierProvider(
+      create: (ctx) => ChatViewModel(
+        repository: ctx.read<CardRepository>(),
+        cardId: cardId,
+      ),
+      child: _ChatView(title: title),
+    );
+  }
+}
+
+class _ChatView extends StatefulWidget {
+  const _ChatView({required this.title});
+  final String title;
+
+  @override
+  State<_ChatView> createState() => _ChatViewState();
+}
+
+class _ChatViewState extends State<_ChatView> {
+  final _controller = TextEditingController();
+  final _scroll = ScrollController();
+
+  @override
+  void dispose() {
+    _controller.dispose();
+    _scroll.dispose();
+    super.dispose();
+  }
+
+  void _send(ChatViewModel vm) {
+    final text = _controller.text;
+    _controller.clear();
+    vm.send(text).then((_) => _scrollToEnd());
+    _scrollToEnd();
+  }
+
+  void _scrollToEnd() {
+    WidgetsBinding.instance.addPostFrameCallback((_) {
+      if (_scroll.hasClients) {
+        _scroll.animateTo(
+          _scroll.position.maxScrollExtent,
+          duration: const Duration(milliseconds: 200),
+          curve: Curves.easeOut,
+        );
+      }
+    });
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    final vm = context.watch<ChatViewModel>();
+    final theme = Theme.of(context);
+
+    return Scaffold(
+      appBar: AppBar(
+        title: Column(
+          crossAxisAlignment: CrossAxisAlignment.start,
+          children: [
+            Text(widget.title.isEmpty ? 'Ask this card' : widget.title,
+                maxLines: 1, overflow: TextOverflow.ellipsis),
+            Text(
+              'AI-generated · may contain errors',
+              style: theme.textTheme.labelSmall
+                  ?.copyWith(color: theme.colorScheme.onSurfaceVariant),
+            ),
+          ],
+        ),
+      ),
+      body: Column(
+        children: [
+          Expanded(child: _messages(context, vm)),
+          if (vm.error != null)
+            Padding(
+              padding: const EdgeInsets.symmetric(horizontal: 16, vertical: 4),
+              child: Text(vm.error!,
+                  style: TextStyle(color: theme.colorScheme.error)),
+            ),
+          _composer(context, vm),
+        ],
+      ),
+    );
+  }
+
+  Widget _messages(BuildContext context, ChatViewModel vm) {
+    if (vm.isEmpty) {
+      return Center(
+        child: Padding(
+          padding: const EdgeInsets.all(32),
+          child: Text(
+            'Ask anything about this card — ingredients, steps, the gist…',
+            textAlign: TextAlign.center,
+            style: Theme.of(context).textTheme.bodyMedium?.copyWith(
+                color: Theme.of(context).colorScheme.onSurfaceVariant),
+          ),
+        ),
+      );
+    }
+    return ListView.builder(
+      controller: _scroll,
+      padding: const EdgeInsets.all(16),
+      itemCount: vm.messages.length + (vm.busy ? 1 : 0),
+      itemBuilder: (ctx, i) {
+        if (i >= vm.messages.length) return const _TypingBubble();
+        return _Bubble(message: vm.messages[i]);
+      },
+    );
+  }
+
+  Widget _composer(BuildContext context, ChatViewModel vm) {
+    return SafeArea(
+      top: false,
+      child: Padding(
+        padding: const EdgeInsets.fromLTRB(12, 4, 12, 8),
+        child: Row(
+          children: [
+            Expanded(
+              child: TextField(
+                controller: _controller,
+                minLines: 1,
+                maxLines: 4,
+                textInputAction: TextInputAction.send,
+                onSubmitted: (_) => _send(vm),
+                decoration: const InputDecoration(
+                  hintText: 'Ask about this card',
+                  border: OutlineInputBorder(),
+                  isDense: true,
+                ),
+              ),
+            ),
+            const SizedBox(width: 8),
+            IconButton.filled(
+              onPressed: vm.busy ? null : () => _send(vm),
+              icon: const Icon(Icons.send_rounded),
+            ),
+          ],
+        ),
+      ),
+    );
+  }
+}
+
+class _Bubble extends StatelessWidget {
+  const _Bubble({required this.message});
+  final ChatMessage message;
+
+  @override
+  Widget build(BuildContext context) {
+    final scheme = Theme.of(context).colorScheme;
+    final isUser = message.isUser;
+    return Align(
+      alignment: isUser ? Alignment.centerRight : Alignment.centerLeft,
+      child: Container(
+        margin: const EdgeInsets.symmetric(vertical: 4),
+        padding: const EdgeInsets.symmetric(horizontal: 14, vertical: 10),
+        constraints: BoxConstraints(
+          maxWidth: MediaQuery.of(context).size.width * 0.78,
+        ),
+        decoration: BoxDecoration(
+          color: isUser ? scheme.primaryContainer : scheme.surfaceContainerHighest,
+          borderRadius: BorderRadius.circular(14),
+        ),
+        child: Text(
+          message.content,
+          style: TextStyle(
+            color: isUser ? scheme.onPrimaryContainer : scheme.onSurface,
+          ),
+        ),
+      ),
+    );
+  }
+}
+
+class _TypingBubble extends StatelessWidget {
+  const _TypingBubble();
+
+  @override
+  Widget build(BuildContext context) {
+    return Align(
+      alignment: Alignment.centerLeft,
+      child: Container(
+        margin: const EdgeInsets.symmetric(vertical: 4),
+        padding: const EdgeInsets.all(14),
+        decoration: BoxDecoration(
+          color: Theme.of(context).colorScheme.surfaceContainerHighest,
+          borderRadius: BorderRadius.circular(14),
+        ),
+        child: const SizedBox(
+          width: 18,
+          height: 18,
+          child: CircularProgressIndicator(strokeWidth: 2),
+        ),
+      ),
+    );
+  }
+}

app/lib/ui/features/reader/views/primary_action_bar.dart

@@ -1,22 +1,38 @@
-/// The one dominant action per card (docs/04 primary_action, docs/06). The kind
-/// is derived server-side from content type. Phase-1 handlers acknowledge the
-/// action locally; deep integrations (calendar, Notion export) are P2.
+/// The card's action area (docs/13). Always offers **Ask** (grounded chat) and
+/// a content-aware "more" menu; when the server derived a dominant action it
+/// also shows it as the primary button. Handlers run on-device against the
+/// card's own blocks (see [CardActions]) — share/copy/Maps/calendar, all free.
 library;
 
-import 'package:flutter/material.dart';
+import 'package:flutter/material.dart' hide Card;
 
 import '../../../../domain/models/card.dart';
-import '../../../../domain/models/enums.dart';
+import '../services/card_actions.dart';
+import 'chat_screen.dart';
 
-class PrimaryActionBar extends StatelessWidget {
-  const PrimaryActionBar({super.key, required this.action});
-  final PrimaryAction action;
+class PrimaryActionBar extends StatefulWidget {
+  const PrimaryActionBar({super.key, required this.card});
+  final Card card;
+
+  @override
+  State<PrimaryActionBar> createState() => _PrimaryActionBarState();
+}
+
+class _PrimaryActionBarState extends State<PrimaryActionBar> {
+  static const _actions = CardActions();
+  bool _busy = false;
+
+  Card get card => widget.card;
 
   @override
   Widget build(BuildContext context) {
     final scheme = Theme.of(context).colorScheme;
+    final primaryType = _actions.primaryType(card);
+    final hasPrimary =
+        card.primaryAction.isPresent && primaryType != null;
+
     return SafeArea(
-      minimum: const EdgeInsets.fromLTRB(20, 0, 20, 16),
+      minimum: const EdgeInsets.fromLTRB(16, 0, 16, 16),
       child: Material(
         color: Colors.transparent,
         child: DecoratedBox(
@@ -29,37 +45,120 @@ class PrimaryActionBar extends StatelessWidget {
               ),
             ],
           ),
-          child: FilledButton.icon(
-            onPressed: () => _run(context),
-            icon: Icon(_icon),
-            label: Text(action.label),
+          child: Row(
+            children: [
+              if (hasPrimary)
+                OutlinedButton.icon(
+                  onPressed: _openChat,
+                  icon: const Icon(Icons.chat_bubble_outline_rounded),
+                  label: const Text('Ask'),
+                )
+              else
+                Expanded(
+                  child: FilledButton.icon(
+                    onPressed: _openChat,
+                    icon: const Icon(Icons.chat_bubble_outline_rounded),
+                    label: const Text('Ask this card'),
+                  ),
+                ),
+              if (hasPrimary) ...[
+                const SizedBox(width: 10),
+                Expanded(
+                  child: FilledButton.icon(
+                    onPressed: _busy ? null : () => _run(primaryType),
+                    icon: _busy
+                        ? const SizedBox(
+                            width: 18,
+                            height: 18,
+                            child: CircularProgressIndicator(strokeWidth: 2),
+                          )
+                        : Icon(_iconFor(primaryType)),
+                    label: Text(card.primaryAction.label),
+                  ),
+                ),
+              ],
+              const SizedBox(width: 6),
+              IconButton.filledTonal(
+                onPressed: _busy ? null : () => _openMore(primaryType),
+                icon: const Icon(Icons.more_horiz_rounded),
+                tooltip: 'More actions',
+              ),
+            ],
           ),
         ),
       ),
     );
   }
 
-  IconData get _icon {
-    switch (action.kind) {
-      case PrimaryActionKind.shoppingList:
-        return Icons.add_shopping_cart_rounded;
-      case PrimaryActionKind.schedule:
-        return Icons.event_available_rounded;
-      case PrimaryActionKind.savePlace:
-        return Icons.bookmark_add_rounded;
-      case PrimaryActionKind.reminder:
-        return Icons.notifications_active_rounded;
-      case PrimaryActionKind.export:
-        return Icons.ios_share_rounded;
-      case PrimaryActionKind.none:
-        return Icons.bolt_rounded;
-    }
+  void _openChat() {
+    Navigator.of(context).push(
+      MaterialPageRoute(
+        builder: (_) =>
+            ChatScreen(cardId: card.cardId, title: card.base.oneLiner),
+      ),
+    );
   }
 
-  void _run(BuildContext context) {
-    // Phase-1: acknowledge. P2 wires real shopping-list/calendar/export targets.
-    ScaffoldMessenger.of(context).showSnackBar(
-      SnackBar(content: Text('${action.label} — coming soon')),
+  Future<void> _openMore(CardActionType? primaryType) async {
+    // The "more" sheet lists every available action except the one already
+    // shown as the primary button.
+    final specs = _actions
+        .available(card)
+        .where((s) => s.type != primaryType)
+        .toList();
+    final chosen = await showModalBottomSheet<CardActionType>(
+      context: context,
+      builder: (ctx) => SafeArea(
+        child: Column(
+          mainAxisSize: MainAxisSize.min,
+          children: [
+            for (final s in specs)
+              ListTile(
+                leading: Icon(s.icon),
+                title: Text(s.label),
+                onTap: () => Navigator.pop(ctx, s.type),
+              ),
+          ],
+        ),
+      ),
     );
+    if (chosen != null) await _run(chosen);
+  }
+
+  Future<void> _run(CardActionType type) async {
+    setState(() => _busy = true);
+    final result = await _actions.perform(card, type);
+    if (!mounted) return;
+    setState(() => _busy = false);
+
+    final message = switch (result) {
+      ActionResult.done => null, // the OS sheet/app is the feedback
+      ActionResult.copied => 'Copied to clipboard',
+      ActionResult.empty => 'Nothing in this card for that',
+      ActionResult.failed => "Couldn't complete that action",
+    };
+    if (message != null) {
+      ScaffoldMessenger.of(context)
+          .showSnackBar(SnackBar(content: Text(message)));
+    }
+  }
+
+  IconData _iconFor(CardActionType type) {
+    switch (type) {
+      case CardActionType.share:
+        return Icons.ios_share_rounded;
+      case CardActionType.shoppingList:
+        return Icons.add_shopping_cart_rounded;
+      case CardActionType.openMaps:
+        return Icons.map_rounded;
+      case CardActionType.addToCalendar:
+        return Icons.event_available_rounded;
+      case CardActionType.copy:
+        return Icons.copy_rounded;
+      case CardActionType.openOriginal:
+        return Icons.play_circle_outline_rounded;
+      case CardActionType.openLinks:
+        return Icons.link_rounded;
+    }
   }
 }

app/lib/ui/features/reader/views/reader_screen.dart

@@ -117,9 +117,7 @@ class _ReaderView extends StatelessWidget {
           ),
         ],
       ),
-      bottomSheet: card.primaryAction.isPresent && card.isReady
-          ? PrimaryActionBar(action: card.primaryAction)
-          : null,
+      bottomSheet: card.isReady ? PrimaryActionBar(card: card) : null,
     );
   }
 

app/pubspec.lock

@@ -1,6 +1,14 @@
 # Generated by pub
 # See https://dart.dev/tools/pub/glossary#lockfile
 packages:
+  add_2_calendar:
+    dependency: "direct main"
+    description:
+      name: add_2_calendar
+      sha256: "8274d1c7a776fdb46b7b7b9a4ed6b1b80ec8f2a9325fe46e2336687bcbc18ce5"
+      url: "https://pub.dev"
+    source: hosted
+    version: "3.1.1"
   args:
     dependency: transitive
     description:
@@ -81,6 +89,14 @@ packages:
       url: "https://pub.dev"
     source: hosted
     version: "1.19.1"
+  cross_file:
+    dependency: transitive
+    description:
+      name: cross_file
+      sha256: "28bb3ae56f117b5aec029d702a90f57d285cd975c3c5c281eaca38dbc47c5937"
+      url: "https://pub.dev"
+    source: hosted
+    version: "0.3.5+2"
   crypto:
     dependency: transitive
     description:
@@ -264,6 +280,14 @@ packages:
       url: "https://pub.dev"
     source: hosted
     version: "1.17.0"
+  mime:
+    dependency: transitive
+    description:
+      name: mime
+      sha256: "41a20518f0cb1256669420fdba0cd90d21561e560ac240f26ef8322e45bb7ed6"
+      url: "https://pub.dev"
+    source: hosted
+    version: "2.0.0"
   nested:
     dependency: transitive
     description:
@@ -408,6 +432,22 @@ packages:
       url: "https://pub.dev"
     source: hosted
     version: "0.28.0"
+  share_plus:
+    dependency: "direct main"
+    description:
+      name: share_plus
+      sha256: fce43200aa03ea87b91ce4c3ac79f0cecd52e2a7a56c7a4185023c271fbfa6da
+      url: "https://pub.dev"
+    source: hosted
+    version: "10.1.4"
+  share_plus_platform_interface:
+    dependency: transitive
+    description:
+      name: share_plus_platform_interface
+      sha256: cc012a23fc2d479854e6c80150696c4a5f5bb62cb89af4de1c505cf78d0a5d0b
+      url: "https://pub.dev"
+    source: hosted
+    version: "5.0.2"
   shared_preferences:
     dependency: "direct main"
     description:
@@ -573,6 +613,70 @@ packages:
       url: "https://pub.dev"
     source: hosted
     version: "1.4.0"
+  url_launcher:
+    dependency: "direct main"
+    description:
+      name: url_launcher
+      sha256: f6a7e5c4835bb4e3026a04793a4199ca2d14c739ec378fdfe23fc8075d0439f8
+      url: "https://pub.dev"
+    source: hosted
+    version: "6.3.2"
+  url_launcher_android:
+    dependency: transitive
+    description:
+      name: url_launcher_android
+      sha256: "17bc677f0b301615530dd1d67e0a9828cafa2d0b6b6eae4cd3679b7eac4a273c"
+      url: "https://pub.dev"
+    source: hosted
+    version: "6.3.30"
+  url_launcher_ios:
+    dependency: transitive
+    description:
+      name: url_launcher_ios
+      sha256: "580fe5dfb51671ae38191d316e027f6b76272b026370708c2d898799750a02b0"
+      url: "https://pub.dev"
+    source: hosted
+    version: "6.4.1"
+  url_launcher_linux:
+    dependency: transitive
+    description:
+      name: url_launcher_linux
+      sha256: d5e14138b3bc193a0f63c10a53c94b91d399df0512b1f29b94a043db7482384a
+      url: "https://pub.dev"
+    source: hosted
+    version: "3.2.2"
+  url_launcher_macos:
+    dependency: transitive
+    description:
+      name: url_launcher_macos
+      sha256: "368adf46f71ad3c21b8f06614adb38346f193f3a59ba8fe9a2fd74133070ba18"
+      url: "https://pub.dev"
+    source: hosted
+    version: "3.2.5"
+  url_launcher_platform_interface:
+    dependency: transitive
+    description:
+      name: url_launcher_platform_interface
+      sha256: "552f8a1e663569be95a8190206a38187b531910283c3e982193e4f2733f01029"
+      url: "https://pub.dev"
+    source: hosted
+    version: "2.3.2"
+  url_launcher_web:
+    dependency: transitive
+    description:
+      name: url_launcher_web
+      sha256: "85c81589622fbc87c1c683aaea164d3604a7777495a79d91e39ffcdec39ddb34"
+      url: "https://pub.dev"
+    source: hosted
+    version: "2.4.3"
+  url_launcher_windows:
+    dependency: transitive
+    description:
+      name: url_launcher_windows
+      sha256: "712c70ab1b99744ff066053cbe3e80c73332b38d46e5e945c98689b2e66fc15f"
+      url: "https://pub.dev"
+    source: hosted
+    version: "3.1.5"
   uuid:
     dependency: transitive
     description:
@@ -605,6 +709,14 @@ packages:
       url: "https://pub.dev"
     source: hosted
     version: "1.1.1"
+  win32:
+    dependency: transitive
+    description:
+      name: win32
+      sha256: d7cb55e04cd34096cd3a79b3330245f54cb96a370a1c27adb3c84b917de8b08e
+      url: "https://pub.dev"
+    source: hosted
+    version: "5.15.0"
   xdg_directories:
     dependency: transitive
     description:
@@ -623,4 +735,4 @@ packages:
     version: "3.1.3"
 sdks:
   dart: ">=3.11.3 <4.0.0"
-  flutter: ">=3.38.4"
+  flutter: ">=3.41.0"

app/pubspec.yaml

@@ -46,6 +46,12 @@ dependencies:
   # Cached, progressive thumbnail/keyframe loading in the library grid.
   cached_network_image: ^3.4.1
 
+  # Action layer (docs/09): export/shopping-list -> OS share sheet,
+  # save-place -> Maps, reminder/schedule -> native calendar event.
+  share_plus: ^10.1.4
+  url_launcher: ^6.3.1
+  add_2_calendar: ^3.0.1
+
 dev_dependencies:
   flutter_test:
     sdk: flutter

app/test/artifact_test.dart

@@ -0,0 +1,45 @@
+// Contract tests for the catalog artifact mirror (docs/12). Parsing must be
+// tolerant: unknown type degrades to `other`, missing fields don't throw.
+
+import 'package:flutter_test/flutter_test.dart';
+
+import 'package:cachy/domain/models/artifact.dart';
+
+void main() {
+  group('CatalogEntry.fromJson', () {
+    test('parses a full entry', () {
+      final e = CatalogEntry.fromJson({
+        'id': 'a_1',
+        'type': 'book',
+        'title': 'Atomic Habits',
+        'creator': 'James Clear',
+        'year': 2018,
+        'thumbnail': 'https://covers/x.jpg',
+        'source_card_ids': ['c1', 'c2'],
+      });
+      expect(e.type, ArtifactType.book);
+      expect(e.title, 'Atomic Habits');
+      expect(e.subtitle, 'James Clear · 2018');
+      expect(e.sourceCardIds, ['c1', 'c2']);
+    });
+
+    test('tv_show wire maps to tvShow and back', () {
+      expect(ArtifactType.fromWire('tv_show'), ArtifactType.tvShow);
+      expect(ArtifactType.tvShow.wire, 'tv_show');
+    });
+
+    test('unknown type degrades to other', () {
+      final e = CatalogEntry.fromJson({'id': 'a', 'title': 'X', 'type': 'zzz'});
+      expect(e.type, ArtifactType.other);
+    });
+
+    test('missing optional fields do not throw', () {
+      final e = CatalogEntry.fromJson({'id': 'a', 'title': 'Solo'});
+      expect(e.creator, isNull);
+      expect(e.year, isNull);
+      expect(e.thumbnail, isNull);
+      expect(e.subtitle, '');
+      expect(e.sourceCardIds, isEmpty);
+    });
+  });
+}

backend/app/api/cards.py

@@ -14,7 +14,8 @@ from sqlalchemy import delete, select
 
 from app.models.card import Card, CardState
 from app.models.job import JobState
-from app.services import cache, events
+from app.pipeline.ingestion.source import platform_for_url
+from app.services import cache, events, llm_chat
 from app.store import db, media
 
 log = logging.getLogger("api.cards")
@@ -41,15 +42,21 @@ class PatchCardRequest(BaseModel):
     state: None = None  # state is server-controlled; ignored if sent
 
 
+class ChatMessage(BaseModel):
+    role: str  # "user" | "assistant"
+    content: str
+
+
+class ChatRequest(BaseModel):
+    messages: list[ChatMessage]
+
+
+class ChatResponse(BaseModel):
+    reply: str
+
+
 def _platform_for(url: str) -> str | None:
-    u = url.lower()
-    if "instagram.com" in u:
-        return "instagram"
-    if "tiktok.com" in u:
-        return "tiktok"
-    if "youtube.com" in u or "youtu.be" in u:
-        return "youtube"
-    return None
+    return platform_for_url(url)
 
 
 # --------------------------------------------------------------------------- #
@@ -156,6 +163,31 @@ async def patch_card(card_id: str, req: PatchCardRequest) -> Card:
         return row.to_card()
 
 
+@router.post("/{card_id}/chat", response_model=ChatResponse)
+async def chat_card(card_id: str, req: ChatRequest) -> ChatResponse:
+    """Grounded Q&A over one card (docs/13). Stateless: the client replays the
+    conversation each turn; nothing is stored. The model answers from the card's
+    structured content only."""
+    if not req.messages or req.messages[-1].role != "user":
+        raise HTTPException(status_code=422, detail="last message must be from user")
+
+    async with db.session() as session:
+        row = await db.get_card_row(session, card_id)
+        if row is None:
+            raise HTTPException(status_code=404, detail="card not found")
+        if row.state != CardState.READY.value:
+            raise HTTPException(status_code=409, detail="card is not ready")
+        card = row.to_card()
+
+    history = [m.model_dump() for m in req.messages]
+    reply = await asyncio.to_thread(llm_chat.answer, card, history)
+    if reply is None:
+        raise HTTPException(
+            status_code=503, detail="chat is unavailable (no LLM backend configured)"
+        )
+    return ChatResponse(reply=reply)
+
+
 @router.delete("/{card_id}")
 async def delete_card(card_id: str) -> dict:
     async with db.session() as session:

backend/app/api/catalog.py

@@ -0,0 +1,57 @@
+"""Catalog endpoints (docs/12): the aggregated, deduplicated view of every
+artifact referenced across all cards. Read-mostly; entries are created by the
+worker, not by clients."""
+
+from __future__ import annotations
+
+from fastapi import APIRouter, HTTPException, Query
+from pydantic import BaseModel
+from sqlalchemy import delete, select
+
+from app.models.artifact import ArtifactType, CatalogEntry
+from app.store import db
+
+router = APIRouter(prefix="/catalog", tags=["catalog"])
+
+
+class CatalogDetail(BaseModel):
+    entry: CatalogEntry
+    source_card_ids: list[str]
+
+
+@router.get("", response_model=list[CatalogEntry])
+async def list_catalog(
+    type: ArtifactType | None = None,
+    limit: int = Query(200, ge=1, le=500),
+    offset: int = Query(0, ge=0),
+) -> list[CatalogEntry]:
+    async with db.session() as session:
+        stmt = select(db.ArtifactRow).order_by(db.ArtifactRow.created_at.desc())
+        if type is not None:
+            stmt = stmt.where(db.ArtifactRow.type == type.value)
+        stmt = stmt.limit(limit).offset(offset)
+        rows = (await session.execute(stmt)).scalars().all()
+        return [r.to_entry() for r in rows]
+
+
+@router.get("/{artifact_id}", response_model=CatalogDetail)
+async def get_catalog_entry(artifact_id: str) -> CatalogDetail:
+    async with db.session() as session:
+        row = await session.get(db.ArtifactRow, artifact_id)
+        if row is None:
+            raise HTTPException(status_code=404, detail="artifact not found")
+        entry = row.to_entry()
+        return CatalogDetail(entry=entry, source_card_ids=entry.source_card_ids)
+
+
+@router.delete("/{artifact_id}")
+async def delete_catalog_entry(artifact_id: str) -> dict:
+    async with db.session() as session:
+        row = await session.get(db.ArtifactRow, artifact_id)
+        if row is None:
+            raise HTTPException(status_code=404, detail="artifact not found")
+        await session.execute(
+            delete(db.ArtifactRow).where(db.ArtifactRow.id == artifact_id)
+        )
+        await session.commit()
+    return {"deleted": artifact_id}

backend/app/main.py

@@ -13,7 +13,7 @@ from fastapi import FastAPI
 from fastapi.middleware.cors import CORSMiddleware
 from fastapi.staticfiles import StaticFiles
 
-from app.api import cards, search
+from app.api import cards, catalog, search
 from app.models.card import SCHEMA_VERSION
 from app.pipeline import worker
 from app.store import db, media
@@ -57,6 +57,7 @@ app.add_middleware(
 )
 
 app.include_router(cards.router)
+app.include_router(catalog.router)
 app.include_router(search.router)
 
 # Serve extracted keyframes/thumbnails so the frontend faces load (docs/05).

backend/app/models/artifact.py

@@ -0,0 +1,60 @@
+"""Artifact catalog models (docs/12).
+
+An *artifact* is a real-world thing a video references — a book, movie, podcast,
+product, place, etc. — as opposed to the structured how-to content of the card
+itself. Artifacts are extracted by the same single structuring LLM call (docs/04),
+then aggregated across all cards into a global, deduplicated catalog.
+
+This is a parallel surface to the block schema, NOT a new block type. The block
+vocabulary is unchanged; the structuring output simply grows an `artifacts` list.
+"""
+
+from __future__ import annotations
+
+import uuid
+from datetime import datetime, timezone
+from enum import Enum
+from typing import Optional
+
+from pydantic import BaseModel, Field
+
+
+class ArtifactType(str, Enum):
+    BOOK = "book"
+    MOVIE = "movie"
+    TV_SHOW = "tv_show"
+    PODCAST = "podcast"
+    MUSIC = "music"
+    PRODUCT = "product"
+    PLACE = "place"
+    APP = "app"
+    OTHER = "other"
+
+
+def _new_id() -> str:
+    return "a_" + uuid.uuid4().hex[:8]
+
+
+class Artifact(BaseModel):
+    """One referenced thing, as emitted by structuring (pre-aggregation)."""
+
+    type: ArtifactType = ArtifactType.OTHER
+    title: str
+    creator: Optional[str] = None  # author / director / artist / host
+    year: Optional[int] = None
+    thumbnail: Optional[str] = None  # resolved from a free image API (docs/12)
+
+
+class CatalogEntry(BaseModel):
+    """An aggregated, deduplicated catalog item: one artifact, many source cards."""
+
+    id: str = Field(default_factory=_new_id)
+    type: ArtifactType = ArtifactType.OTHER
+    title: str
+    creator: Optional[str] = None
+    year: Optional[int] = None
+    thumbnail: Optional[str] = None
+    source_card_ids: list[str] = Field(default_factory=list)
+    created_at: str = Field(
+        default_factory=lambda: datetime.now(timezone.utc).isoformat()
+    )

backend/app/models/card.py

@@ -13,7 +13,7 @@ from typing import Annotated, Literal, Optional, Union
 
 from pydantic import BaseModel, Field
 
-SCHEMA_VERSION = "1.0"
+SCHEMA_VERSION = "1.1"  # 1.1: structuring output grows an `artifacts` list (docs/12)
 
 
 # --------------------------------------------------------------------------- #

backend/app/pipeline/extraction.py

@@ -202,6 +202,38 @@ def _aggregate(caption: str, transcript: str, ocr_text: str, source_line: str) -
     return "\n".join(parts)
 
 
+def _aggregate_article(
+    title: str, text: str, author: str | None, source_line: str
+) -> str:
+    """Text-source bundle (docs/02 article path): no audio/frames, the body is the
+    content. Same labeled shape the structuring prompt already consumes."""
+    parts = [
+        f"TITLE: {title.strip()}" if title.strip() else "TITLE:",
+        f"AUTHOR: {author.strip()}" if author and author.strip() else "AUTHOR:",
+        f"ARTICLE TEXT: {text.strip()}" if text.strip() else "ARTICLE TEXT:",
+        f"SOURCE: {source_line}",
+    ]
+    return "\n".join(parts)
+
+
+def _extract_article(download: DownloadResult, source_line: str) -> ExtractionResult:
+    """Article path: skip ffmpeg/Whisper/OCR entirely. The lead image (if any) is
+    a remote URL used directly as the thumbnail — nothing is downloaded."""
+    aggregated = _aggregate_article(
+        download.title, download.text, download.author, source_line
+    )
+    return ExtractionResult(
+        aggregated_text=aggregated,
+        transcript=download.text,  # gives base-synth / paragraph-fallback real text
+        ocr_text="",
+        thumbnail=download.image_url,
+        keyframes=[],
+        had_transcript=False,
+        had_ocr=False,
+        had_visual=False,
+    )
+
+
 # --------------------------------------------------------------------------- #
 # Entry point
 # --------------------------------------------------------------------------- #
@@ -211,6 +243,9 @@ def extract(
 ) -> ExtractionResult:
     """Run the extraction pipeline against a DownloadResult. `work_dir` is the
     per-card directory where audio/frames live."""
+    if download.media_type == "article":
+        return _extract_article(download, source_line)
+
     os.makedirs(work_dir, exist_ok=True)
     transcript = ""
     frames: list[str] = []

backend/app/pipeline/ingestion/article.py

@@ -0,0 +1,85 @@
+"""article.py — readable-text ingestion for non-video sources (docs/02).
+
+A parallel path to the resolver cascade: for URLs that are articles/posts rather
+than short-form video (Reddit, Wikipedia, Substack, blogs, news, …), there is no
+media to download — the content *is* text. This module fetches the page and
+extracts the main readable body, title, author, and a lead image.
+
+Free-first: trafilatura is a keyless, local extractor — no API, no
+quota. Best-effort by design: any miss/timeout/too-thin result returns None and
+the caller treats it as a normal ingestion failure (the cascade/graceful-fail
+model of docs/02), never a crash.
+
+Distinct from resolvers.py: that file is the fragile, untouched video-scraper
+layer. This is new orchestration the app owns.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from dataclasses import dataclass
+from typing import Optional
+
+log = logging.getLogger("ingestion.article")
+
+# A body shorter than this is almost certainly a paywall/login wall or a failed
+# extraction, not a real article — reject so the caller can fall through.
+_MIN_CHARS = 200
+
+
+@dataclass
+class ArticleResult:
+    title: str
+    text: str
+    author: Optional[str] = None
+    image_url: Optional[str] = None
+    site: Optional[str] = None
+
+
+def fetch_article(url: str) -> ArticleResult | None:
+    """Fetch + extract a readable article from `url`. Returns None on any failure
+    or if the extracted body is too thin to be a real article."""
+    try:
+        import trafilatura
+    except Exception as e:  # noqa: BLE001 — dep missing -> article path simply unavailable
+        log.warning("trafilatura unavailable; article path disabled: %s", e)
+        return None
+
+    try:
+        downloaded = trafilatura.fetch_url(url)
+        if not downloaded:
+            log.info("article fetch returned nothing for %s", url)
+            return None
+        raw = trafilatura.extract(
+            downloaded,
+            output_format="json",
+            with_metadata=True,
+            favor_recall=True,
+            include_comments=False,
+            include_tables=True,
+        )
+        if not raw:
+            return None
+        data = json.loads(raw)
+    except Exception as e:  # noqa: BLE001 — any extraction error is a normal miss
+        log.info("article extraction failed for %s: %s", url, e)
+        return None
+
+    text = (data.get("text") or "").strip()
+    if len(text) < _MIN_CHARS:
+        log.info("article body too thin (%d chars) for %s", len(text), url)
+        return None
+
+    title = (data.get("title") or "").strip()
+    author = (data.get("author") or "").strip() or None
+    image_url = (data.get("image") or "").strip() or None
+    site = (data.get("sitename") or data.get("hostname") or "").strip() or None
+
+    return ArticleResult(
+        title=title,
+        text=text,
+        author=author,
+        image_url=image_url,
+        site=site,
+    )

backend/app/pipeline/ingestion/downloader.py

@@ -27,11 +27,15 @@ import uuid
 from dataclasses import dataclass, field
 from typing import Callable, Literal, Optional, Union
 
-from . import resolvers  # the resolver functions, unchanged
+from . import article, resolvers  # resolvers unchanged; article is the text path
 
 log = logging.getLogger("ingestion.downloader")
 
-MediaType = Literal["video", "images"]
+MediaType = Literal["video", "images", "article"]
+
+# URLs on these hosts go to the fragile video resolver cascade; everything else
+# is treated as a readable article/post (docs/02 article path).
+_VIDEO_HOSTS = ("instagram.com", "tiktok.com", "youtube.com", "youtu.be")
 
 # Optional keyless resolvers, in cascade order. Probed by name; missing ones skip.
 _KEYLESS_NAMES = [
@@ -61,11 +65,17 @@ class DownloaderConfig:
 @dataclass
 class DownloadResult:
     """What the pipeline's extraction stage consumes next."""
-    media_type: MediaType            # "video" or "images"
-    data: Union[str, list[str]]      # path to .mp4, OR list of image paths
+    media_type: MediaType            # "video" | "images" | "article"
+    data: Union[str, list[str]]      # path to .mp4, list of image paths, or "" for article
     caption: str                     # may be empty; OCR/transcript compensates
     resolver: str                    # which strategy succeeded (for observability)
 
+    # Article path only (media_type == "article"): the content is text, not media.
+    text: str = ""                   # extracted readable body
+    title: str = ""                  # article/post title
+    author: str | None = None        # byline, if any
+    image_url: str | None = None     # remote lead-image URL (hotlinked, not downloaded)
+
 
 class DownloadError(RuntimeError):
     """Raised when every resolver in the cascade fails — an expected outcome."""
@@ -97,6 +107,44 @@ def _safe_call(name: str, fn: Callable):
         return None
 
 
+def _is_video_url(url: str) -> bool:
+    """True for the short-form video platforms handled by the resolver cascade."""
+    u = url.lower()
+    return any(host in u for host in _VIDEO_HOSTS)
+
+
+def _article_result(url: str) -> DownloadResult | None:
+    """The text path: extract a readable article. None if nothing usable."""
+    art = article.fetch_article(url)
+    if art is None:
+        return None
+    log.info("download ok via article extractor (%d chars)", len(art.text))
+    return DownloadResult(
+        media_type="article",
+        data="",
+        caption=art.title,
+        resolver="article",
+        text=art.text,
+        title=art.title,
+        author=art.author,
+        image_url=art.image_url,
+    )
+
+
+def _yt_dlp_result(url: str, output_path: str, cookies_path: str | None) -> DownloadResult | None:
+    """yt-dlp as a video safety net — it supports far more sites than the keyless
+    scrapers, so it can rescue a non-video host that is actually a video page."""
+    yt = getattr(resolvers, "_download_yt_dlp", None)
+    if not callable(yt):
+        return None
+    res = _safe_call("yt-dlp", lambda: yt(url, output_path, cookies_path))
+    if res:
+        path, caption = res
+        log.info("download ok via yt-dlp")
+        return DownloadResult("video", path, caption, "yt-dlp")
+    return None
+
+
 # --------------------------------------------------------------------------- #
 # Orchestration (sync core)
 # --------------------------------------------------------------------------- #
@@ -111,6 +159,22 @@ def download_content(
     """
     config = config or DownloaderConfig()
 
+    # Article path: non-video hosts carry readable text, not media. Try text
+    # extraction first; if it yields nothing, fall through to yt-dlp in case the
+    # page is actually a video the cascade can handle (docs/02 article path).
+    if not _is_video_url(url):
+        art = _article_result(url)
+        if art is not None:
+            return art
+        job_dir = os.path.join(config.output_dir, uuid.uuid4().hex)
+        os.makedirs(job_dir, exist_ok=True)
+        yt = _yt_dlp_result(
+            url, os.path.join(job_dir, "video.mp4"), config.cookies_path
+        )
+        if yt is not None:
+            return yt
+        raise DownloadError(f"no article or video extracted for {url}")
+
     # Per-job isolation: unique dir per call so concurrent downloads never collide.
     job_dir = os.path.join(config.output_dir, uuid.uuid4().hex)
     os.makedirs(job_dir, exist_ok=True)
@@ -122,9 +186,13 @@ def download_content(
         log.debug("trying keyless resolver: %s", name)
         res = _safe_call(name, lambda fn=fn: fn(url, output_path))
         if res:
-            path, caption = res
+            if len(res) == 3:
+                m_type, path_or_list, caption = res
+            else:
+                path_or_list, caption = res
+                m_type = "video"
             log.info("download ok via %s", name)
-            return DownloadResult("video", path, caption, name)
+            return DownloadResult(m_type, path_or_list, caption, name)
 
     # 2) RapidAPI — optional, only if a key is configured and resolvers exposes it.
     rapid = getattr(resolvers, "_download_rapidapi", None)
@@ -135,9 +203,13 @@ def download_content(
             lambda: rapid(url, output_path, config.rapidapi_key),
         )
         if res:
-            path, caption = res
+            if len(res) == 3:
+                m_type, path_or_list, caption = res
+            else:
+                path_or_list, caption = res
+                m_type = "video"
             log.info("download ok via rapidapi")
-            return DownloadResult("video", path, caption, "rapidapi")
+            return DownloadResult(m_type, path_or_list, caption, "rapidapi")
 
     # 3) yt-dlp — local fallback for videos/reels.
     yt = getattr(resolvers, "_download_yt_dlp", None)

backend/app/pipeline/ingestion/resolvers.py

@@ -1,27 +1,74 @@
-import os
-import yt_dlp
+import json
+import logging
+import re
+import shutil
+import ssl
+import time
+import urllib.parse
+import urllib.request
+from pathlib import Path
+from typing import List, Optional, Tuple, Union
+
 import instaloader
-from typing import List, Union, Tuple
+import requests
+import yt_dlp
 
-def download_content(url: str, output_path: str, cookies_path: str = None) -> Tuple[str, Union[str, List[str]], str]:
-    """
-    Downloads content from the given URL.
-    First tries yt-dlp (for video).
+ssl._create_default_https_context = ssl._create_unverified_context
+log = logging.getLogger("ingestion.resolvers")
+
+
+def _is_valid_video_link(link: Optional[str]) -> bool:
+    """Checks if the extracted media link points to a video stream rather than an image."""
+    if not link:
+        return False
+    low = link.lower()
+    image_indicators = [".jpg", ".jpeg", ".png", ".webp", "dst-jpg", "image_urlgen", "format=jpg"]
+    if any(ind in low for ind in image_indicators):
+        return False
+    return True
+
+
+def download_content(
+    url: str, output_path: Union[str, Path], cookies_path: Optional[Union[str, Path]] = None
+) -> Tuple[str, Union[str, List[str]], str]:
+    """Downloads content from the given URL.
+    First tries keyless scrapers (vidssave, savethevideo, saveig, downloadgram, anyvidsave, igreelsdl).
+    If they fail, tries yt-dlp (for video).
     If it fails or finds no video, tries instaloader (for images/carousels).
 
+    Args:
+        url: Source URL to ingest.
+        output_path: Target filesystem path for downloaded video.
+        cookies_path: Optional path to netscape cookie file.
+
     Returns:
-        (type, data, caption)
-        type: "video" or "images"
-        data: path to .mp4 OR list of paths to images
-        caption: text caption of the post
+        Tuple of (media_type, data_path_or_list, caption).
     """
-    # 1. Try yt-dlp first (for videos/reels)
+    # 1. Try keyless scrapers first (in cascade order)
+    keyless_funcs = [
+        ("vidssave", _download_vidssave),
+        ("savethevideo", _download_savethevideo),
+        ("saveig", _download_saveig),
+        ("downloadgram", _download_downloadgram),
+        ("anyvidsave", _download_anyvidsave),
+        ("igreelsdl", _download_igreelsdl),
+    ]
+    for name, scraper_fn in keyless_funcs:
+        try:
+            res = scraper_fn(url, output_path)
+            if res:
+                media_type, data, caption = res
+                return media_type, data, caption
+        except Exception as e:
+            log.warning(f"Keyless resolver {name} failed in download_content for {url}: {e}")
+
+    # 2. Try yt-dlp (for videos/reels)
     video_res = _download_yt_dlp(url, output_path, cookies_path)
     if video_res:
         video_path, caption = video_res
         return "video", video_path, caption
 
-    # 2. Try Instaloader (for carousels/images)
+    # 3. Try Instaloader (for carousels/images)
     if "instagram.com" in url:
         image_res = _download_instaloader(url)
         if image_res:
@@ -30,78 +77,632 @@ def download_content(url: str, output_path: str, cookies_path: str = None) -> Tu
 
     raise RuntimeError(f"Could not download content from {url} using any available method.")
 
-def _download_yt_dlp(url: str, output_path: str, cookies_path: str = None) -> Union[Tuple[str, str], None]:
+
+def _download_vidssave(
+    url: str, output_path: Union[str, Path]
+) -> Optional[Tuple[str, Union[str, List[str]], str]]:
+    """Resolves URL using the public vidssave.com API.
+
+    Args:
+        url: Source URL of the video/reel.
+        output_path: Target filesystem path where the video should be saved.
+
+    Returns:
+        Tuple of (media_type, saved_path_or_list, caption) if successful, otherwise None.
+    """
+    target_path = Path(output_path)
+    api_url = "https://api.vidssave.com/api/contentsite_api/media/parse"
+    headers = {
+        "accept": "*/*",
+        "accept-language": "en-US,en;q=0.9",
+        "content-type": "application/x-www-form-urlencoded",
+        "origin": "https://vidssave.com",
+        "referer": "https://vidssave.com/",
+        "user-agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36",
+    }
+    data = {
+        "auth": "20250901majwlqo",
+        "domain": "api-ak.vidssave.com",
+        "origin": "source",
+        "link": url,
+    }
+    try:
+        response = requests.post(api_url, headers=headers, data=data, timeout=20)
+        if response.status_code == 200:
+            res_json = response.json()
+            media_data = res_json.get("data", {})
+            caption = media_data.get("title", "")
+            resources = media_data.get("resources", [])
+            if resources:
+                first_url = resources[0].get("download_url")
+                if _is_valid_video_link(first_url):
+                    log.debug(f"[vidssave] Got direct link: {first_url[:60] if first_url else ''}...")
+                    video_response = requests.get(
+                        first_url, stream=True, headers={"user-agent": headers["user-agent"]}, timeout=60
+                    )
+                    if video_response.status_code == 200:
+                        target_path.parent.mkdir(parents=True, exist_ok=True)
+                        with target_path.open("wb") as f:
+                            for chunk in video_response.iter_content(chunk_size=8192):
+                                if chunk:
+                                    f.write(chunk)
+                        if target_path.exists() and target_path.stat().st_size > 0:
+                            return "video", str(target_path), caption
+                    else:
+                        log.warning(f"[vidssave] Download failed with stream status: {video_response.status_code}")
+                else:
+                    log.debug("[vidssave] Link points to images, saving as image carousel.")
+                    saved_paths = []
+                    target_path.parent.mkdir(parents=True, exist_ok=True)
+                    base_stem = target_path.stem
+                    for idx, res_dict in enumerate(resources, 1):
+                        img_url = res_dict.get("download_url")
+                        if not img_url:
+                            continue
+                        img_path = target_path.parent / f"{base_stem}_{idx}.jpg"
+                        try:
+                            img_resp = requests.get(
+                                img_url, stream=True, headers={"user-agent": headers["user-agent"]}, timeout=30
+                            )
+                            if img_resp.status_code == 200:
+                                with img_path.open("wb") as f:
+                                    for chunk in img_resp.iter_content(chunk_size=8192):
+                                        if chunk:
+                                            f.write(chunk)
+                                if img_path.exists() and img_path.stat().st_size > 0:
+                                    saved_paths.append(str(img_path))
+                        except Exception as img_err:
+                            log.warning(f"[vidssave] Failed to download carousel image {idx}: {img_err}")
+                    if saved_paths:
+                        return "images", saved_paths, caption
+            else:
+                log.debug(f"[vidssave] API did not return resources: {res_json}")
+        else:
+            log.warning(f"[vidssave] API POST failed with status: {response.status_code}")
+    except Exception as e:
+        log.warning(f"[vidssave] Helper failed for {url}: {e}")
+    return None
+
+
+def _download_savethevideo(
+    url: str, output_path: Union[str, Path]
+) -> Optional[Tuple[str, Union[str, List[str]], str]]:
+    """Resolves URL using the public savethevideo.com API by polling task status.
+
+    Args:
+        url: Source URL of the video/reel.
+        output_path: Target filesystem path where the video should be saved.
+
+    Returns:
+        Tuple of (media_type, saved_path_or_list, caption) if successful, otherwise None.
+    """
+    target_path = Path(output_path)
+    api_url = "https://api.v02.savethevideo.com/tasks"
+    headers = {
+        "accept": "application/json",
+        "content-type": "application/json",
+        "origin": "https://www.savethevideo.com",
+        "referer": "https://www.savethevideo.com/",
+        "user-agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/149.0.0.0 Safari/537.36",
+    }
+    payload = {"type": "info", "url": url}
+
+    def download_from_result(result_list: list) -> Optional[Tuple[str, Union[str, List[str]], str]]:
+        if not result_list:
+            log.debug("[savethevideo] Task result is empty.")
+            return None
+        video_url = result_list[0].get("url")
+        caption = result_list[0].get("description") or result_list[0].get("title", "")
+        if _is_valid_video_link(video_url):
+            log.debug(f"[savethevideo] Got direct link: {video_url[:60] if video_url else ''}...")
+            try:
+                video_response = requests.get(video_url, stream=True, timeout=60)
+                if video_response.status_code == 200:
+                    target_path.parent.mkdir(parents=True, exist_ok=True)
+                    with target_path.open("wb") as f:
+                        for chunk in video_response.iter_content(chunk_size=8192):
+                            if chunk:
+                                f.write(chunk)
+                    if target_path.exists() and target_path.stat().st_size > 0:
+                        return "video", str(target_path), caption
+                else:
+                    log.warning(f"[savethevideo] Download failed with status: {video_response.status_code}")
+            except Exception as e:
+                log.warning(f"[savethevideo] Stream download failed: {e}")
+        else:
+            log.debug("[savethevideo] Link points to images, saving as image carousel.")
+            saved_paths = []
+            target_path.parent.mkdir(parents=True, exist_ok=True)
+            base_stem = target_path.stem
+            for idx, res_item in enumerate(result_list, 1):
+                img_url = res_item.get("url")
+                if not img_url:
+                    continue
+                img_path = target_path.parent / f"{base_stem}_{idx}.jpg"
+                try:
+                    img_resp = requests.get(img_url, stream=True, timeout=30)
+                    if img_resp.status_code == 200:
+                        with img_path.open("wb") as f:
+                            for chunk in img_resp.iter_content(chunk_size=8192):
+                                if chunk:
+                                    f.write(chunk)
+                        if img_path.exists() and img_path.stat().st_size > 0:
+                            saved_paths.append(str(img_path))
+                except Exception as img_err:
+                    log.warning(f"[savethevideo] Failed to download image {idx}: {img_err}")
+            if saved_paths:
+                return "images", saved_paths, caption
+        return None
+
+    try:
+        response = requests.post(api_url, headers=headers, json=payload, timeout=20)
+        if response.status_code == 200:
+            res_json = response.json()
+            if res_json.get("state") == "completed":
+                return download_from_result(res_json.get("result", []))
+            log.debug(f"[savethevideo] State is {res_json.get('state')}")
+        elif response.status_code == 202:
+            res_json = response.json()
+            task_id = res_json.get("id")
+            if not task_id:
+                log.warning("[savethevideo] Task created but no task ID returned.")
+                return None
+            poll_url = f"https://api.v02.savethevideo.com/tasks/{task_id}"
+            log.debug(f"[savethevideo] Polling task: {poll_url}")
+            for _ in range(15):
+                poll_resp = requests.get(
+                    poll_url,
+                    headers={"accept": "application/json", "referer": "https://www.savethevideo.com/"},
+                    timeout=15,
+                )
+                if poll_resp.status_code == 200:
+                    poll_json = poll_resp.json()
+                    state = poll_json.get("state")
+                    if state == "completed":
+                        return download_from_result(poll_json.get("result", []))
+                    if state == "failed":
+                        log.warning("[savethevideo] Task failed on remote server.")
+                        return None
+                time.sleep(2)
+        else:
+            log.warning(f"[savethevideo] Task creation failed with status: {response.status_code}")
+    except Exception as e:
+        log.warning(f"[savethevideo] Helper failed for {url}: {e}")
+    return None
+
+
+def _download_saveig(
+    url: str, output_path: Union[str, Path]
+) -> Optional[Tuple[str, Union[str, List[str]], str]]:
+    """Resolves URL using the public saveig.in API.
+
+    Args:
+        url: Source URL of the video/reel.
+        output_path: Target filesystem path where the video should be saved.
+
+    Returns:
+        Tuple of (media_type, saved_path_or_list, caption) if successful, otherwise None.
+    """
+    target_path = Path(output_path)
+    api_url = "https://saveig.in/wp-json/visolix/api/download"
+    headers = {
+        "accept": "application/json, text/plain, */*",
+        "content-type": "application/json",
+        "origin": "https://saveig.in",
+        "referer": "https://saveig.in/fastdl/",
+        "user-agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/149.0.0.0 Safari/537.36",
+    }
+    payload = {"url": url, "format": "", "captcha_response": None}
+    try:
+        response = requests.post(api_url, headers=headers, json=payload, timeout=20)
+        if response.status_code != 200:
+            log.warning(f"[saveig] POST returned status code {response.status_code}")
+            return None
+        res_json = response.json()
+        if not res_json.get("status"):
+            log.debug(f"[saveig] API returned failure status: {res_json}")
+            return None
+        html_content = res_json.get("data", "")
+        match = re.search(r'href=["\']([^"\']*dl\.php\?id=[a-zA-Z0-9]+)["\']', html_content)
+        if not match:
+            log.debug("[saveig] Could not find download link in HTML response data.")
+            return None
+        dl_url = match.group(1)
+        if dl_url.startswith("/"):
+            dl_url = "https://saveig.in" + dl_url
+        elif dl_url.startswith("../"):
+            dl_url = "https://saveig.in/wp-content/plugins/visolix-video-downloader/" + dl_url
+        elif not dl_url.startswith("http"):
+            dl_url = "https://saveig.in/wp-content/plugins/visolix-video-downloader/includes/" + dl_url
+        dl_url = dl_url.replace("/includes/../", "/")
+        if _is_valid_video_link(dl_url):
+            log.debug(f"[saveig] Got proxy link: {dl_url[:60]}...")
+            video_resp = requests.get(dl_url, stream=True, headers={"user-agent": headers["user-agent"]}, timeout=60)
+            if video_resp.status_code != 200:
+                log.warning(f"[saveig] Proxy stream returned status code {video_resp.status_code}")
+                return None
+            target_path.parent.mkdir(parents=True, exist_ok=True)
+            with target_path.open("wb") as f:
+                for chunk in video_resp.iter_content(chunk_size=8192):
+                    if chunk:
+                        f.write(chunk)
+            if target_path.exists() and target_path.stat().st_size > 0:
+                return "video", str(target_path), ""
+        else:
+            log.debug("[saveig] Link points to image, saving as jpg.")
+            target_path.parent.mkdir(parents=True, exist_ok=True)
+            img_path = target_path.parent / f"{target_path.stem}_1.jpg"
+            img_resp = requests.get(dl_url, stream=True, headers={"user-agent": headers["user-agent"]}, timeout=60)
+            if img_resp.status_code == 200:
+                with img_path.open("wb") as f:
+                    for chunk in img_resp.iter_content(chunk_size=8192):
+                        if chunk:
+                            f.write(chunk)
+                if img_path.exists() and img_path.stat().st_size > 0:
+                    return "images", [str(img_path)], ""
+    except Exception as e:
+        log.warning(f"[saveig] Helper failed for {url}: {e}")
+    return None
+
+
+
+def _download_downloadgram(
+    url: str, output_path: Union[str, Path]
+) -> Optional[Tuple[str, Union[str, List[str]], str]]:
+    """Resolves URL using the public downloadgram.org API.
+
+    Args:
+        url: Source URL of the video/reel.
+        output_path: Target filesystem path where the video should be saved.
+
+    Returns:
+        Tuple of (media_type, saved_path_or_list, caption) if successful, otherwise None.
+    """
+    target_path = Path(output_path)
+    api_url = "https://api.downloadgram.org/media"
+    headers = {
+        "accept": "*/*",
+        "content-type": "application/x-www-form-urlencoded",
+        "origin": "https://downloadgram.org",
+        "referer": "https://downloadgram.org/",
+        "user-agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/149.0.0.0 Safari/537.36",
+    }
+    payload = {"url": url, "v": "3", "lang": "en"}
+    try:
+        response = requests.post(api_url, headers=headers, data=payload, timeout=20)
+        if response.status_code != 200:
+            log.warning(f"[downloadgram] POST returned status code {response.status_code}")
+            return None
+        matches = re.findall(r"https://cdn\.downloadgram\.org/\?token=[a-zA-Z0-9_\-\.]+", response.text)
+        if not matches:
+            log.debug("[downloadgram] Could not find CDN link in response.")
+            return None
+        dl_url = matches[-1]
+        if _is_valid_video_link(dl_url):
+            log.debug(f"[downloadgram] Got direct link: {dl_url[:60]}...")
+            video_resp = requests.get(dl_url, headers={"user-agent": headers["user-agent"]}, stream=True, timeout=60)
+            if video_resp.status_code != 200:
+                log.warning(f"[downloadgram] Stream returned status code {video_resp.status_code}")
+                return None
+            target_path.parent.mkdir(parents=True, exist_ok=True)
+            with target_path.open("wb") as f:
+                for chunk in video_resp.iter_content(chunk_size=8192):
+                    if chunk:
+                        f.write(chunk)
+            if target_path.exists() and target_path.stat().st_size > 0:
+                return "video", str(target_path), ""
+        else:
+            log.debug("[downloadgram] Link points to image, saving as jpg.")
+            target_path.parent.mkdir(parents=True, exist_ok=True)
+            img_path = target_path.parent / f"{target_path.stem}_1.jpg"
+            img_resp = requests.get(dl_url, headers={"user-agent": headers["user-agent"]}, stream=True, timeout=60)
+            if img_resp.status_code == 200:
+                with img_path.open("wb") as f:
+                    for chunk in img_resp.iter_content(chunk_size=8192):
+                        if chunk:
+                            f.write(chunk)
+                if img_path.exists() and img_path.stat().st_size > 0:
+                    return "images", [str(img_path)], ""
+    except Exception as e:
+        log.warning(f"[downloadgram] Helper failed for {url}: {e}")
+    return None
+
+
+def _download_anyvidsave(
+    url: str, output_path: Union[str, Path]
+) -> Optional[Tuple[str, Union[str, List[str]], str]]:
+    """Resolves URL using the public anyvidsave.in API.
+
+    Args:
+        url: Source URL of the video/reel.
+        output_path: Target filesystem path where the video should be saved.
+
+    Returns:
+        Tuple of (media_type, saved_path_or_list, caption) if successful, otherwise None.
+    """
+    target_path = Path(output_path)
+    api_url = "https://anyvidsave.in/download.php"
+    headers = {
+        "Content-Type": "application/json",
+        "Origin": "https://anyvidsave.in",
+        "Referer": "https://anyvidsave.in/",
+        "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/120.0.0.0",
+    }
+    data = {"url": url}
+    try:
+        response = requests.post(api_url, headers=headers, json=data, timeout=15)
+        if response.status_code == 200:
+            res_json = response.json()
+            if res_json.get("success") and not res_json.get("limit_reached"):
+                media_data = res_json.get("data", {})
+                caption = media_data.get("title", "")
+                links = media_data.get("links", [])
+                cdn_url = None
+                for link in links:
+                    if link.get("type") == "mp4" or "video" in link.get("type", ""):
+                        cdn_url = link.get("url")
+                        break
+                if cdn_url and _is_valid_video_link(cdn_url):
+                    log.debug(f"[anyvidsave] Got CDN link: {cdn_url[:60]}...")
+                    video_response = requests.get(cdn_url, stream=True, timeout=30)
+                    if video_response.status_code == 200:
+                        target_path.parent.mkdir(parents=True, exist_ok=True)
+                        with target_path.open("wb") as f:
+                            for chunk in video_response.iter_content(chunk_size=8192):
+                                if chunk:
+                                    f.write(chunk)
+                        if target_path.exists() and target_path.stat().st_size > 0:
+                            return "video", str(target_path), caption
+                else:
+                    log.debug("[anyvidsave] Link points to images, collecting image links.")
+                    saved_paths = []
+                    target_path.parent.mkdir(parents=True, exist_ok=True)
+                    base_stem = target_path.stem
+                    for idx, l_item in enumerate(links, 1):
+                        img_url = l_item.get("url")
+                        if not img_url or _is_valid_video_link(img_url):
+                            continue
+                        img_path = target_path.parent / f"{base_stem}_{idx}.jpg"
+                        try:
+                            img_resp = requests.get(img_url, stream=True, timeout=30)
+                            if img_resp.status_code == 200:
+                                with img_path.open("wb") as f:
+                                    for chunk in img_resp.iter_content(chunk_size=8192):
+                                        if chunk:
+                                            f.write(chunk)
+                                if img_path.exists() and img_path.stat().st_size > 0:
+                                    saved_paths.append(str(img_path))
+                        except Exception as img_err:
+                            log.warning(f"[anyvidsave] Failed to download image {idx}: {img_err}")
+                    if saved_paths:
+                        return "images", saved_paths, caption
+    except Exception as e:
+        log.warning(f"[anyvidsave] Helper failed for {url}: {e}")
+    return None
+
+
+def _download_igreelsdl(
+    url: str, output_path: Union[str, Path]
+) -> Optional[Tuple[str, Union[str, List[str]], str]]:
+    """Resolves URL using the public igreelsdl.com API.
+
+    Args:
+        url: Source URL of the video/reel.
+        output_path: Target filesystem path where the video should be saved.
+
+    Returns:
+        Tuple of (media_type, saved_path_or_list, caption) if successful, otherwise None.
+    """
+    target_path = Path(output_path)
+    resolve_url = f"https://igreelsdl.com/api/resolve?url={requests.utils.quote(url)}"
+    headers = {
+        "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/120.0.0.0",
+        "Referer": "https://igreelsdl.com/",
+    }
+    try:
+        response = requests.get(resolve_url, headers=headers, timeout=15)
+        if response.status_code == 200:
+            res_json = response.json()
+            if res_json.get("success"):
+                caption = res_json.get("title", "")
+                source_url = res_json.get("sourceUrl", url)
+                formats = res_json.get("formats", [])
+                format_id = formats[0].get("formatId", "best") if formats else "best"
+                download_url = (
+                    f"https://igreelsdl.com/api/download?"
+                    f"url={requests.utils.quote(source_url)}&"
+                    f"format_id={requests.utils.quote(format_id)}&"
+                    f"filename=instagram-download.mp4&"
+                    f"type=video"
+                )
+                if _is_valid_video_link(download_url):
+                    log.debug(f"[igreelsdl] Got proxy link: {download_url[:60]}...")
+                    video_response = requests.get(download_url, headers=headers, stream=True, timeout=30)
+                    if video_response.status_code == 200:
+                        target_path.parent.mkdir(parents=True, exist_ok=True)
+                        with target_path.open("wb") as f:
+                            for chunk in video_response.iter_content(chunk_size=8192):
+                                if chunk:
+                                    f.write(chunk)
+                        if target_path.exists() and target_path.stat().st_size > 0:
+                            return "video", str(target_path), caption
+                else:
+                    log.debug("[igreelsdl] Link points to image, saving as jpg.")
+                    target_path.parent.mkdir(parents=True, exist_ok=True)
+                    img_path = target_path.parent / f"{target_path.stem}_1.jpg"
+                    img_resp = requests.get(download_url, headers=headers, stream=True, timeout=30)
+                    if img_resp.status_code == 200:
+                        with img_path.open("wb") as f:
+                            for chunk in img_resp.iter_content(chunk_size=8192):
+                                if chunk:
+                                    f.write(chunk)
+                        if img_path.exists() and img_path.stat().st_size > 0:
+                            return "images", [str(img_path)], caption
+    except Exception as e:
+        log.warning(f"[igreelsdl] Helper failed for {url}: {e}")
+    return None
+
+
+def _download_rapidapi(
+    url: str, output_path: Union[str, Path], api_key: str
+) -> Optional[Tuple[str, Union[str, List[str]], str]]:
+    """Uses a RapidAPI social media downloader to get the direct unblocked CDN link.
+
+    Args:
+        url: Source URL of the video/reel.
+        output_path: Target filesystem path where the video should be saved.
+        api_key: RapidAPI subscription key.
+
+    Returns:
+        Tuple of (media_type, saved_path_or_list, caption) if successful, otherwise None.
+    """
+    target_path = Path(output_path)
+    endpoint = "https://instagram-downloader-download-instagram-videos-stories.p.rapidapi.com/index"
+    headers = {
+        "x-rapidapi-key": api_key,
+        "x-rapidapi-host": "instagram-downloader-download-instagram-videos-stories.p.rapidapi.com",
+    }
+    params = {"url": url}
+    try:
+        response = requests.get(endpoint, headers=headers, params=params, timeout=15)
+        if response.status_code == 200:
+            data = response.json()
+            cdn_url = data.get("media") or data.get("url") or data.get("download_url")
+            caption = data.get("caption") or data.get("title") or ""
+            if cdn_url and _is_valid_video_link(cdn_url):
+                log.debug(f"[rapidapi] Got CDN link: {cdn_url[:60]}...")
+                video_response = requests.get(cdn_url, stream=True, timeout=30)
+                if video_response.status_code == 200:
+                    target_path.parent.mkdir(parents=True, exist_ok=True)
+                    with target_path.open("wb") as f:
+                        for chunk in video_response.iter_content(chunk_size=8192):
+                            if chunk:
+                                f.write(chunk)
+                    if target_path.exists() and target_path.stat().st_size > 0:
+                        return "video", str(target_path), caption
+            elif cdn_url:
+                log.debug("[rapidapi] Link points to image, saving as jpg.")
+                target_path.parent.mkdir(parents=True, exist_ok=True)
+                img_path = target_path.parent / f"{target_path.stem}_1.jpg"
+                img_resp = requests.get(cdn_url, stream=True, timeout=30)
+                if img_resp.status_code == 200:
+                    with img_path.open("wb") as f:
+                        for chunk in img_resp.iter_content(chunk_size=8192):
+                            if chunk:
+                                f.write(chunk)
+                    if img_path.exists() and img_path.stat().st_size > 0:
+                        return "images", [str(img_path)], caption
+    except Exception as e:
+        log.warning(f"[rapidapi] Helper failed for {url}: {e}")
+    return None
+
+
+def _download_yt_dlp(
+    url: str, output_path: Union[str, Path], cookies_path: Optional[Union[str, Path]] = None
+) -> Optional[Tuple[str, str]]:
+    """Downloads video using local yt-dlp library.
+
+    Args:
+        url: Source URL to ingest.
+        output_path: Target filesystem path for downloaded video.
+        cookies_path: Optional path to netscape cookie file.
+
+    Returns:
+        Tuple of (output_path_str, caption) if successful, otherwise None.
+    """
+    out_path = Path(output_path)
     opts = {
         "format": "bestvideo[ext=mp4]+bestaudio/best",
-        "outtmpl": output_path,
+        "outtmpl": str(out_path),
         "merge_output_format": "mp4",
         "quiet": True,
         "no_warnings": True,
     }
 
-    if cookies_path and os.path.exists(cookies_path):
-        opts["cookiefile"] = cookies_path
+    if cookies_path:
+        cookie_p = Path(cookies_path)
+        if cookie_p.exists():
+            opts["cookiefile"] = str(cookie_p)
 
     try:
         with yt_dlp.YoutubeDL(opts) as ydl:
-            # Check if video formats exist before downloading
             info = ydl.extract_info(url, download=False)
-            caption = info.get('description', '') or info.get('title', '')
+            caption = info.get("description", "") or info.get("title", "")
 
-            if not info.get('formats'):
+            if not info.get("formats"):
                 return None
             ydl.download([url])
-            if os.path.exists(output_path):
-                return output_path, caption
-    except Exception:
+            if out_path.exists():
+                return str(out_path), caption
+    except Exception as e:
+        log.warning(f"yt-dlp download failed for {url}: {e}")
         return None
     return None
 
-def _download_instaloader(url: str) -> Union[Tuple[List[str], str], None]:
-    import re
-    # Extract shortcode
+
+def _download_instaloader(url: str) -> Optional[Tuple[List[str], str]]:
+    """Downloads Instagram carousels/images using Instaloader.
+
+    Args:
+        url: Source Instagram post URL.
+
+    Returns:
+        Tuple of (sorted_image_path_list, caption) if successful, otherwise None.
+    """
     match = re.search(r"/(?:p|reels|reel)/([^/?#&]+)", url)
     if not match:
         return None
 
     shortcode = match.group(1)
+    temp_dir = Path("temp_images")
     loader = instaloader.Instaloader(
         download_pictures=True,
-        download_videos=False, # We use yt-dlp for videos
+        download_videos=False,  # We use yt-dlp for videos
         download_video_thumbnails=False,
         download_geotags=False,
         download_comments=False,
         save_metadata=False,
         compress_json=False,
-        dirname_pattern="temp_images"
+        dirname_pattern=str(temp_dir),
     )
 
     try:
-        # Cleanup previous temp folder
-        import shutil
-        if os.path.exists("temp_images"):
-            shutil.rmtree("temp_images")
+        if temp_dir.exists():
+            shutil.rmtree(temp_dir)
 
         post = instaloader.Post.from_shortcode(loader.context, shortcode)
         caption = post.caption or ""
-        loader.download_post(post, target="temp_images")
+        loader.download_post(post, target=str(temp_dir))
 
-        # Collect image paths
         images = [
-            os.path.join("temp_images", f)
-            for f in os.listdir("temp_images")
-            if f.endswith((".jpg", ".png", ".webp"))
+            str(p)
+            for p in temp_dir.iterdir()
+            if p.suffix.lower() in {".jpg", ".png", ".webp"}
         ]
         if images:
             return sorted(images), caption
         return None
     except Exception as e:
-        print(f"[Downloader] Instaloader failed: {e}")
+        log.warning(f"Instaloader failed for {url}: {e}")
         return None
 
-# Keep compatibility for existing calls if any
-def download_video(url: str, output_path: str, cookies_path: str = None) -> str:
+
+def download_video(
+    url: str, output_path: Union[str, Path], cookies_path: Optional[Union[str, Path]] = None
+) -> str:
+    """Downloads video content specifically, raising an error if images are returned.
+
+    Args:
+        url: Source URL to ingest.
+        output_path: Target filesystem path for downloaded video.
+        cookies_path: Optional path to netscape cookie file.
+
+    Returns:
+        Path string to the downloaded video file.
+    """
     res_type, res_data, _ = download_content(url, output_path, cookies_path)
     if res_type == "video":
-        return res_data
-    raise RuntimeError("Download found images instead of video.")
+        return str(res_data)
+    raise RuntimeError(f"Download found images instead of video for {url}.")
+
+

backend/app/pipeline/ingestion/source.py

@@ -0,0 +1,34 @@
+"""Source-platform labelling (docs/02). One place that maps a URL to a human
+platform label, shared by the API (at card creation) and the worker (for the
+observability source line). Covers the video platforms and the common article
+sources, with a generic host fallback so any URL gets a sensible label."""
+
+from __future__ import annotations
+
+from urllib.parse import urlparse
+
+# host substring -> platform label
+_KNOWN: tuple[tuple[str, str], ...] = (
+    ("instagram.com", "instagram"),
+    ("tiktok.com", "tiktok"),
+    ("youtube.com", "youtube"),
+    ("youtu.be", "youtube"),
+    ("reddit.com", "reddit"),
+    ("wikipedia.org", "wikipedia"),
+    ("linkedin.com", "linkedin"),
+    ("substack.com", "substack"),
+    ("medium.com", "medium"),
+)
+
+
+def platform_for_url(url: str) -> str | None:
+    """A platform label for `url`: a known platform, else the bare host (no
+    `www.`), else None for an unparseable URL."""
+    u = url.lower()
+    for needle, label in _KNOWN:
+        if needle in u:
+            return label
+    host = urlparse(url).netloc.lower()
+    if host.startswith("www."):
+        host = host[4:]
+    return host or None

backend/app/pipeline/structuring.py

@@ -14,6 +14,7 @@ import logging
 import re
 
 from app.config import get_settings
+from app.models.artifact import Artifact, ArtifactType
 from app.models.card import (
     Base,
     Block,
@@ -57,12 +58,19 @@ _ACTION_FOR_TYPE: dict[ContentType, tuple[PrimaryActionKind, str]] = {
 
 
 class StructuredCard:
-    """Validated structuring output: base + blocks + primary_action."""
-
-    def __init__(self, base: Base, blocks: list[dict], primary_action: PrimaryAction):
+    """Validated structuring output: base + blocks + primary_action + artifacts."""
+
+    def __init__(
+        self,
+        base: Base,
+        blocks: list[dict],
+        primary_action: PrimaryAction,
+        artifacts: list[Artifact] | None = None,
+    ):
         self.base = base
         self.blocks = blocks  # list of plain dicts (validated), ready for JSON column
         self.primary_action = primary_action
+        self.artifacts = artifacts or []  # referenced things for the catalog (docs/12)
 
 
 # --------------------------------------------------------------------------- #
@@ -92,7 +100,13 @@ Return ONLY a JSON object (no prose, no markdown fences) with this exact shape:
     "content_type": "recipe|workout|tutorial|tip|product_list|travel|news_explainer|other",
     "type_confidence": 0.0-1.0
   }},
-  "blocks": [ ... ]          // ordered list using ONLY the allowed block types
+  "blocks": [ ... ],         // ordered list using ONLY the allowed block types
+  "artifacts": [             // real, named things the video REFERENCES (may be empty)
+    {{ "type": "book|movie|tv_show|podcast|music|product|place|app|other",
+       "title": str,         // the proper name of the thing
+       "creator": str|null,  // author / director / artist / host / brand
+       "year": int|null }}
+  ]
 }}
 
 Rules:
@@ -100,6 +114,9 @@ Rules:
 - Choose content_type, then arrange blocks to fit it (e.g. recipe -> heading,
   key_value(time/serves), checklist(ingredients), step_list(steps)).
 - Use ONLY the allowed block types below. Output strict JSON.
+- artifacts: include ONLY concrete, named, real-world things the video names
+  (e.g. a specific book, movie, podcast, product, or place). Do NOT invent any;
+  if the video names none, return an empty list. Use the most specific type.
 
 {vocab}
 
@@ -202,6 +219,36 @@ def _coerce_blocks(raw_blocks: list) -> list[dict]:
     return out
 
 
+def _coerce_artifacts(raw_artifacts: list) -> list[Artifact]:
+    """Validate referenced things; drop anything without a usable title or with a
+    bad shape. Never trust the model — a malformed entry is silently skipped."""
+    out: list[Artifact] = []
+    if not isinstance(raw_artifacts, list):
+        return out
+    seen: set[tuple[str, str]] = set()
+    for raw in raw_artifacts:
+        if not isinstance(raw, dict):
+            continue
+        title = (raw.get("title") or "").strip()
+        if not title:
+            continue
+        try:
+            atype = ArtifactType(raw.get("type", "other"))
+        except ValueError:
+            atype = ArtifactType.OTHER
+        key = (atype.value, title.lower())
+        if key in seen:
+            continue
+        seen.add(key)
+        creator = (raw.get("creator") or None)
+        if isinstance(creator, str):
+            creator = creator.strip() or None
+        year = raw.get("year")
+        year = int(year) if isinstance(year, (int, float)) else None
+        out.append(Artifact(type=atype, title=title, creator=creator, year=year))
+    return out
+
+
 def _synthesize_base(bundle: str, transcript: str, caption: str) -> Base:
     """When the model omits one_liner/tldr, build something usable from raw text."""
     source = (transcript or caption or "").strip()
@@ -262,12 +309,19 @@ def _validate(raw_text: str, bundle: str, transcript: str, caption: str) -> "Str
         base.one_liner = base.one_liner or synth.one_liner
         base.tldr = base.tldr or synth.tldr
 
+    artifacts = _coerce_artifacts(data.get("artifacts") or [])
+
     blocks = _coerce_blocks(data.get("blocks") or [])
     if not blocks:
-        # an empty/garbage block list still gets a usable body
-        return _paragraph_fallback(bundle, transcript, caption)
-
-    return StructuredCard(base, blocks, _primary_action_for(base.content_type))
+        # an empty/garbage block list still gets a usable body, but keep any
+        # artifacts the model did surface (the catalog doesn't need blocks).
+        fallback = _paragraph_fallback(bundle, transcript, caption)
+        fallback.artifacts = artifacts
+        return fallback
+
+    return StructuredCard(
+        base, blocks, _primary_action_for(base.content_type), artifacts
+    )
 
 
 # --------------------------------------------------------------------------- #

backend/app/pipeline/worker.py

@@ -26,7 +26,7 @@ from app.pipeline.ingestion.downloader import (
     download_content_async,
 )
 from app.pipeline.structuring import structure_async
-from app.services import events, notify
+from app.services import artifact_images, events, notify
 from app.store import db, media
 
 log = logging.getLogger("pipeline.worker")
@@ -38,17 +38,6 @@ def _utcnow() -> datetime:
     return datetime.now(timezone.utc)
 
 
-def _platform_for(url: str) -> str | None:
-    u = url.lower()
-    if "instagram.com" in u:
-        return "instagram"
-    if "tiktok.com" in u:
-        return "tiktok"
-    if "youtube.com" in u or "youtu.be" in u:
-        return "youtube"
-    return None
-
-
 # --------------------------------------------------------------------------- #
 # Queue claim
 # --------------------------------------------------------------------------- #
@@ -115,26 +104,49 @@ async def _write_blocks(session, card_id: str, blocks: list[dict]) -> None:
 
 
 async def _write_media_and_meta(
-    session, card_id: str, extraction, caption: str, resolver: str
+    session, card_id: str, extraction, caption: str, resolver: str,
+    creator: str | None = None,
 ) -> None:
+    values = dict(
+        thumbnail=extraction.thumbnail,
+        keyframes=extraction.keyframes,
+        caption=caption,
+        resolver=resolver,
+        extraction={
+            "transcript": extraction.had_transcript,
+            "ocr": extraction.had_ocr,
+            "visual": extraction.had_visual,
+        },
+    )
+    if creator:  # article byline -> shown in the source line
+        values["creator"] = creator
     await session.execute(
-        update(db.CardRow)
-        .where(db.CardRow.id == card_id)
-        .values(
-            thumbnail=extraction.thumbnail,
-            keyframes=extraction.keyframes,
-            caption=caption,
-            resolver=resolver,
-            extraction={
-                "transcript": extraction.had_transcript,
-                "ocr": extraction.had_ocr,
-                "visual": extraction.had_visual,
-            },
-        )
+        update(db.CardRow).where(db.CardRow.id == card_id).values(**values)
     )
     await session.commit()
 
 
+async def _persist_artifacts(session, card_id: str, artifacts) -> None:
+    """Aggregate referenced things into the global catalog (docs/12). Each lookup
+    is best-effort and isolated — a failure here never affects the card itself."""
+    for art in artifacts:
+        try:
+            thumbnail = await asyncio.to_thread(
+                artifact_images.resolve_thumbnail, art
+            )
+            await db.upsert_artifact(
+                session,
+                card_id=card_id,
+                type_=art.type.value,
+                title=art.title,
+                creator=art.creator,
+                year=art.year,
+                thumbnail=thumbnail,
+            )
+        except Exception:  # noqa: BLE001 — catalog is non-critical to the card
+            log.warning("catalog upsert failed for %r", art.title, exc_info=True)
+
+
 async def _finish_ready(session, card_id: str, job: db.JobRow) -> None:
     await session.execute(
         update(db.CardRow)
@@ -220,9 +232,15 @@ async def _run_job(session, job: db.JobRow) -> None:
     await _write_base(session, card_id, structured)
     await _write_blocks(session, card_id, structured.blocks)
     await _write_media_and_meta(
-        session, card_id, extraction, download.caption or "", download.resolver
+        session, card_id, extraction, download.caption or "", download.resolver,
+        creator=download.author,
     )
 
+    # 5) Catalog: aggregate any referenced artifacts + fetch their thumbnails.
+    if structured.artifacts:
+        events.publish(card_id, "cataloging", "processing", "Cataloging references")
+        await _persist_artifacts(session, card_id, structured.artifacts)
+
     # Optionally discard the source video, keep keyframes+thumbnail (docs/11)
     if get_settings().discard_source_video and download.media_type == "video":
         media.remove_path(str(download.data))

backend/app/services/artifact_images.py

@@ -0,0 +1,103 @@
+"""Free, keyless thumbnail lookup for catalog artifacts (docs/12).
+
+Free-first: every source here is a public API with no key and no
+quota worth budgeting — iTunes Search (movies/podcasts/music/tv), Open Library
+(books), Wikipedia REST (everything else). Best-effort by design: any miss,
+timeout, or error returns None and the catalog simply shows a placeholder.
+
+The returned value is a remote https URL (hotlinked) — nothing is downloaded or
+stored, which fits the ephemeral free-tier filesystem.
+"""
+
+from __future__ import annotations
+
+import logging
+from urllib.parse import quote
+
+import httpx
+
+from app.models.artifact import Artifact, ArtifactType
+
+log = logging.getLogger("services.artifact_images")
+
+_TIMEOUT = httpx.Timeout(6.0)
+_HEADERS = {"User-Agent": "Cachy/0.1 (catalog thumbnail lookup)"}
+
+# iTunes Search `entity` per artifact type (covers most media).
+_ITUNES_ENTITY: dict[ArtifactType, str] = {
+    ArtifactType.MOVIE: "movie",
+    ArtifactType.TV_SHOW: "tvShow",
+    ArtifactType.PODCAST: "podcast",
+    ArtifactType.MUSIC: "album",
+    ArtifactType.APP: "software",
+}
+
+
+def resolve_thumbnail(artifact: Artifact) -> str | None:
+    """Route by type to a free image source. Returns a remote URL or None."""
+    try:
+        if artifact.type == ArtifactType.BOOK:
+            return _from_open_library(artifact) or _from_wikipedia(artifact)
+        if artifact.type in _ITUNES_ENTITY:
+            return _from_itunes(artifact) or _from_wikipedia(artifact)
+        # product / place / other -> Wikipedia is the best free generic source.
+        return _from_wikipedia(artifact)
+    except Exception as e:  # noqa: BLE001 — thumbnail lookup must never break a card
+        log.info("thumbnail lookup failed for %r: %s", artifact.title, e)
+        return None
+
+
+def _query(artifact: Artifact) -> str:
+    parts = [artifact.title]
+    if artifact.creator:
+        parts.append(artifact.creator)
+    return " ".join(parts)
+
+
+def _from_itunes(artifact: Artifact) -> str | None:
+    entity = _ITUNES_ENTITY[artifact.type]
+    params = {"term": _query(artifact), "entity": entity, "limit": 1}
+    with httpx.Client(timeout=_TIMEOUT, headers=_HEADERS) as client:
+        resp = client.get("https://itunes.apple.com/search", params=params)
+        resp.raise_for_status()
+        results = resp.json().get("results") or []
+    if not results:
+        return None
+    art = results[0].get("artworkUrl100")
+    if not art:
+        return None
+    # Upscale the 100px thumbnail iTunes returns to a crisper catalog cover.
+    return art.replace("100x100bb", "400x400bb")
+
+
+def _from_open_library(artifact: Artifact) -> str | None:
+    params = {"title": artifact.title, "limit": 1}
+    if artifact.creator:
+        params["author"] = artifact.creator
+    with httpx.Client(timeout=_TIMEOUT, headers=_HEADERS) as client:
+        resp = client.get("https://openlibrary.org/search.json", params=params)
+        resp.raise_for_status()
+        docs = resp.json().get("docs") or []
+    if not docs:
+        return None
+    cover_id = docs[0].get("cover_i")
+    if cover_id:
+        return f"https://covers.openlibrary.org/b/id/{cover_id}-L.jpg"
+    isbns = docs[0].get("isbn") or []
+    if isbns:
+        return f"https://covers.openlibrary.org/b/isbn/{isbns[0]}-L.jpg"
+    return None
+
+
+def _from_wikipedia(artifact: Artifact) -> str | None:
+    title = quote(artifact.title.replace(" ", "_"))
+    url = f"https://en.wikipedia.org/api/rest_v1/page/summary/{title}"
+    with httpx.Client(
+        timeout=_TIMEOUT, headers=_HEADERS, follow_redirects=True
+    ) as client:
+        resp = client.get(url)
+        if resp.status_code != 200:
+            return None
+        data = resp.json()
+    thumb = data.get("thumbnail") or {}
+    return thumb.get("source")

backend/app/services/llm_chat.py

@@ -0,0 +1,139 @@
+"""Chat Q&A over a single card (docs/13).
+
+A grounded question-answering helper: the user asks about a card, the model
+answers using ONLY that card's structured content as context. Reuses the same
+
+Stateless by design — the client holds the conversation and replays it on each
+turn; nothing is persisted server-side.
+"""
+
+from __future__ import annotations
+
+import logging
+
+from app.config import get_settings
+from app.models.card import Card
+
+log = logging.getLogger("services.llm_chat")
+
+_MAX_TURNS = 12  # cap replayed history so context stays small + cheap
+_MAX_TOKENS = 600
+
+_SYSTEM = """You are Cachy, answering questions about ONE saved knowledge card.
+Use ONLY the card content below as your source of truth. If the answer is not in
+the card, say so plainly — do not invent facts. Be concise and direct.
+
+--- CARD ---
+{context}
+--- END CARD ---"""
+
+
+def card_context(card: Card) -> str:
+    """Flatten a card's base + blocks into plain text the model can reason over."""
+    lines: list[str] = []
+    if card.base.one_liner:
+        lines.append(card.base.one_liner)
+    if card.base.tldr:
+        lines.append(card.base.tldr)
+    for block in card.blocks:
+        # blocks are pydantic Block objects; normalise to a plain dict view.
+        raw = block.model_dump() if hasattr(block, "model_dump") else block
+        lines.append(_block_text(raw))
+    return "\n".join(l for l in lines if l and l.strip())
+
+
+def _block_text(block: dict) -> str:
+    """Best-effort text view of any block dict (tolerant of unknown shapes)."""
+    if not isinstance(block, dict):
+        return ""
+    btype = block.get("type")
+    if btype == "heading":
+        return f"# {block.get('text', '')}"
+    if btype in ("paragraph", "callout"):
+        return block.get("text", "")
+    if btype == "bullet_list":
+        return "\n".join(f"- {i}" for i in block.get("items", []))
+    if btype == "step_list":
+        steps = block.get("steps", [])
+        return "\n".join(
+            f"{n}. {s.get('text', '')}" for n, s in enumerate(steps, 1)
+            if isinstance(s, dict)
+        )
+    if btype == "key_value":
+        pairs = block.get("pairs", [])
+        return "\n".join(
+            f"{p.get('key', '')}: {p.get('value', '')}" for p in pairs
+            if isinstance(p, dict)
+        )
+    if btype == "checklist":
+        items = block.get("items", [])
+        return "\n".join(
+            f"- {i.get('text', '')}" for i in items if isinstance(i, dict)
+        )
+    if btype == "link":
+        return block.get("label") or block.get("url", "")
+    if btype == "map":
+        places = block.get("places", [])
+        return "\n".join(p.get("name", "") for p in places if isinstance(p, dict))
+    if btype == "table":
+        rows = block.get("rows", [])
+        return "\n".join(
+            " | ".join(str(c) for c in r) for r in rows if isinstance(r, list)
+        )
+    # unknown / forward-compat
+    return block.get("text", "") if isinstance(block.get("text"), str) else ""
+
+
+def _messages(context: str, history: list[dict]) -> list[dict]:
+    recent = [m for m in history if m.get("role") in ("user", "assistant")][-_MAX_TURNS:]
+    return [{"role": "system", "content": _SYSTEM.format(context=context)}, *recent]
+
+
+def answer(card: Card, history: list[dict]) -> str | None:
+    """Return the assistant's reply, or None if no backend is configured / it fails."""
+    context = card_context(card)
+    messages = _messages(context, history)
+    settings = get_settings()
+    if settings.hf_enabled:
+        return _call_hf(messages)
+    if settings.groq_llm_enabled:
+        return _call_groq(messages)
+    return None
+
+
+def _call_hf(messages: list[dict]) -> str | None:
+    settings = get_settings()
+    try:
+        from huggingface_hub import InferenceClient
+
+        client = InferenceClient(api_key=settings.hf_api_key)
+        resp = client.chat_completion(
+            model=settings.hf_model,
+            messages=messages,
+            temperature=0.3,
+            max_tokens=_MAX_TOKENS,
+        )
+        text = resp.choices[0].message.content if resp.choices else ""
+        return (text or "").strip() or None
+    except Exception as e:  # noqa: BLE001
+        log.warning("chat call (huggingface) failed: %s", e)
+        return None
+
+
+def _call_groq(messages: list[dict]) -> str | None:
+    settings = get_settings()
+    try:
+        from groq import Groq
+
+        client = Groq(api_key=settings.groq_api_key)
+        resp = client.chat.completions.create(
+            model="llama-3.1-70b-versatile",  # free tier, matches structuring
+            messages=messages,
+            temperature=0.3,
+            max_tokens=_MAX_TOKENS,
+        )
+        text = resp.choices[0].message.content if resp.choices else ""
+        return (text or "").strip() or None
+    except Exception as e:  # noqa: BLE001
+        log.warning("chat call (groq) failed: %s", e)
+        return None

backend/app/store/db.py

@@ -26,6 +26,7 @@ from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
 
 from app.config import get_settings
 from app.store import media as media_store
+from app.models.artifact import ArtifactType, CatalogEntry
 from app.models.card import (
     Base as CardBase,
     Card,
@@ -124,6 +125,38 @@ class CardRow(Base):
         )
 
 
+class ArtifactRow(Base):
+    """A deduplicated catalog item (docs/12): one referenced thing, many source
+    cards. Dedupe key is (type, title_norm). Thumbnails are remote URLs."""
+
+    __tablename__ = "artifacts"
+
+    id: Mapped[str] = mapped_column(String, primary_key=True, default=_new_uuid)
+    type: Mapped[str] = mapped_column(String, default="other", index=True)
+    title: Mapped[str] = mapped_column(Text)
+    title_norm: Mapped[str] = mapped_column(String, index=True)
+    creator: Mapped[str | None] = mapped_column(String, nullable=True)
+    year: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    thumbnail: Mapped[str | None] = mapped_column(Text, nullable=True)
+    source_card_ids: Mapped[list] = mapped_column(JSON, default=list)
+    created_at: Mapped[datetime] = mapped_column(DateTime, default=_utcnow)
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime, default=_utcnow, onupdate=_utcnow
+    )
+
+    def to_entry(self) -> CatalogEntry:
+        return CatalogEntry(
+            id=self.id,
+            type=ArtifactType(self.type) if self.type else ArtifactType.OTHER,
+            title=self.title,
+            creator=self.creator,
+            year=self.year,
+            thumbnail=self.thumbnail,
+            source_card_ids=list(self.source_card_ids or []),
+            created_at=(self.created_at or _utcnow()).isoformat(),
+        )
+
+
 class JobRow(Base):
     __tablename__ = "jobs"
 
@@ -184,3 +217,50 @@ async def get_card_row(db: AsyncSession, card_id: str) -> CardRow | None:
 async def find_card_by_url(db: AsyncSession, url: str) -> CardRow | None:
     res = await db.execute(select(CardRow).where(CardRow.source_url == url))
     return res.scalar_one_or_none()
+
+
+def _norm_title(title: str) -> str:
+    return " ".join(title.lower().split())
+
+
+async def upsert_artifact(
+    db: AsyncSession,
+    *,
+    card_id: str,
+    type_: str,
+    title: str,
+    creator: str | None,
+    year: int | None,
+    thumbnail: str | None,
+) -> ArtifactRow:
+    """Insert a catalog item or merge into the existing one (dedupe by type+title).
+    Appends card_id to source_card_ids and backfills a missing thumbnail."""
+    norm = _norm_title(title)
+    res = await db.execute(
+        select(ArtifactRow).where(
+            ArtifactRow.type == type_, ArtifactRow.title_norm == norm
+        )
+    )
+    row = res.scalar_one_or_none()
+    if row is None:
+        row = ArtifactRow(
+            type=type_,
+            title=title,
+            title_norm=norm,
+            creator=creator,
+            year=year,
+            thumbnail=thumbnail,
+            source_card_ids=[card_id],
+        )
+        db.add(row)
+    else:
+        if card_id not in (row.source_card_ids or []):
+            row.source_card_ids = [*(row.source_card_ids or []), card_id]
+        if not row.thumbnail and thumbnail:
+            row.thumbnail = thumbnail
+        if not row.creator and creator:
+            row.creator = creator
+        if not row.year and year:
+            row.year = year
+    await db.commit()
+    return row

backend/pyproject.toml

@@ -13,8 +13,10 @@ dependencies = [
     "aiosqlite>=0.20",
     "python-multipart>=0.0.9",
     # ingestion
+    "requests>=2.31",
     "yt-dlp>=2024.4.9",
     "instaloader>=4.11",
+    "trafilatura>=1.8",  # keyless readable-article extraction (docs/02 article path)
     # extraction
     "Pillow>=10.0",
     "imagehash>=4.3",

backend/tests/test_api.py

@@ -18,7 +18,7 @@ async def client(database):
 async def test_health(client):
     r = await client.get("/health")
     assert r.status_code == 200
-    assert r.json()["schema_version"] == "1.0"
+    assert r.json()["schema_version"] == "1.1"
 
 
 async def test_create_returns_id_and_queued(client):
@@ -63,3 +63,121 @@ async def test_get_list_patch_delete(client):
 async def test_get_missing_card_404(client):
     r = await client.get("/cards/does-not-exist")
     assert r.status_code == 404
+
+
+async def test_catalog_empty_initially(client):
+    r = await client.get("/catalog")
+    assert r.status_code == 200
+    assert r.json() == []
+
+
+async def test_catalog_upsert_dedupes_and_lists(client, database):
+    async with database.session() as s:
+        await database.upsert_artifact(
+            s, card_id="c1", type_="book", title="Atomic Habits",
+            creator="James Clear", year=2018, thumbnail="http://x/a.jpg",
+        )
+        await database.upsert_artifact(
+            s, card_id="c2", type_="book", title="atomic   habits",
+            creator=None, year=None, thumbnail=None,
+        )
+        await database.upsert_artifact(
+            s, card_id="c3", type_="movie", title="Inception",
+            creator="Nolan", year=2010, thumbnail=None,
+        )
+
+    r = await client.get("/catalog")
+    entries = r.json()
+    assert len(entries) == 2  # the two books deduped into one
+    book = next(e for e in entries if e["type"] == "book")
+    assert sorted(book["source_card_ids"]) == ["c1", "c2"]
+    assert book["thumbnail"] == "http://x/a.jpg"  # backfilled-keep
+
+    # type filter
+    r2 = await client.get("/catalog", params={"type": "movie"})
+    assert [e["title"] for e in r2.json()] == ["Inception"]
+
+
+async def _make_ready_card(database) -> str:
+    async with database.session() as s:
+        row = database.CardRow(
+            source_url="https://instagram.com/reel/chat",
+            state="ready",
+            content_type="recipe",
+            one_liner="Easy pancakes",
+            tldr="Mix, pour, flip.",
+            blocks=[
+                {"type": "checklist", "id": "b1",
+                 "items": [{"text": "flour", "checked": False}]},
+            ],
+        )
+        s.add(row)
+        await s.commit()
+        return row.id
+
+
+async def test_chat_rejects_non_user_last_message(client):
+    r = await client.post(
+        "/cards/whatever/chat",
+        json={"messages": [{"role": "assistant", "content": "hi"}]},
+    )
+    assert r.status_code == 422
+
+
+async def test_chat_409_when_card_not_ready(client):
+    created = await client.post("/cards", json={"url": "https://instagram.com/reel/q"})
+    card_id = created.json()["card_id"]  # stays QUEUED (no worker in tests)
+    r = await client.post(
+        f"/cards/{card_id}/chat",
+        json={"messages": [{"role": "user", "content": "what is this?"}]},
+    )
+    assert r.status_code == 409
+
+
+async def test_chat_503_without_llm_backend(client, database):
+    card_id = await _make_ready_card(database)
+    r = await client.post(
+        f"/cards/{card_id}/chat",
+        json={"messages": [{"role": "user", "content": "how much flour?"}]},
+    )
+    assert r.status_code == 503  # LLM_BACKEND=none in the test env
+
+
+async def test_chat_returns_reply_when_backend_answers(client, database, monkeypatch):
+    card_id = await _make_ready_card(database)
+
+    captured = {}
+
+    def fake_answer(card, history):
+        captured["title"] = card.base.one_liner
+        captured["history"] = history
+        return "You need flour."
+
+    monkeypatch.setattr("app.api.cards.llm_chat.answer", fake_answer)
+
+    r = await client.post(
+        f"/cards/{card_id}/chat",
+        json={"messages": [{"role": "user", "content": "ingredients?"}]},
+    )
+    assert r.status_code == 200
+    assert r.json()["reply"] == "You need flour."
+    assert captured["title"] == "Easy pancakes"
+    assert captured["history"][-1]["content"] == "ingredients?"
+
+
+async def test_catalog_detail_and_delete(client, database):
+    async with database.session() as s:
+        row = await database.upsert_artifact(
+            s, card_id="c1", type_="podcast", title="Lex Fridman",
+            creator=None, year=None, thumbnail=None,
+        )
+        artifact_id = row.id
+
+    g = await client.get(f"/catalog/{artifact_id}")
+    assert g.status_code == 200
+    assert g.json()["entry"]["title"] == "Lex Fridman"
+    assert g.json()["source_card_ids"] == ["c1"]
+
+    d = await client.delete(f"/catalog/{artifact_id}")
+    assert d.status_code == 200
+    assert (await client.get(f"/catalog/{artifact_id}")).status_code == 404

backend/tests/test_article.py

@@ -0,0 +1,111 @@
+"""Article ingestion path (docs/02): readable-text extraction for non-video
+sources, routing, and the extraction-stage branch. No network — trafilatura is
+stubbed."""
+
+import json
+
+import pytest
+
+from app.pipeline.extraction import extract
+from app.pipeline.ingestion import article, downloader
+from app.pipeline.ingestion.downloader import DownloadResult
+from app.pipeline.ingestion.source import platform_for_url
+
+
+# --------------------------------------------------------------------------- #
+# article.fetch_article
+# --------------------------------------------------------------------------- #
+
+def _stub_trafilatura(monkeypatch, *, html="<html></html>", payload=None):
+    import trafilatura
+    monkeypatch.setattr(trafilatura, "fetch_url", lambda url: html)
+    monkeypatch.setattr(
+        trafilatura, "extract",
+        lambda *a, **k: (json.dumps(payload) if payload is not None else None),
+    )
+
+
+def test_fetch_article_extracts_fields(monkeypatch):
+    _stub_trafilatura(monkeypatch, payload={
+        "title": "Why Sleep Matters",
+        "text": "Sleep is essential. " * 30,
+        "author": "Jane Doe",
+        "image": "https://img/cover.jpg",
+        "sitename": "Substack",
+    })
+    art = article.fetch_article("https://x.substack.com/p/sleep")
+    assert art is not None
+    assert art.title == "Why Sleep Matters"
+    assert art.author == "Jane Doe"
+    assert art.image_url == "https://img/cover.jpg"
+    assert art.site == "Substack"
+
+
+def test_fetch_article_too_thin_returns_none(monkeypatch):
+    _stub_trafilatura(monkeypatch, payload={"title": "x", "text": "too short"})
+    assert article.fetch_article("https://x.com/p") is None
+
+
+def test_fetch_article_handles_empty_fetch(monkeypatch):
+    _stub_trafilatura(monkeypatch, html="")
+    assert article.fetch_article("https://x.com/p") is None
+
+
+def test_fetch_article_handles_no_extract(monkeypatch):
+    _stub_trafilatura(monkeypatch, payload=None)  # extract returns None
+    assert article.fetch_article("https://x.com/p") is None
+
+
+# --------------------------------------------------------------------------- #
+# routing
+# --------------------------------------------------------------------------- #
+
+@pytest.mark.parametrize("url,is_video", [
+    ("https://www.instagram.com/reel/abc", True),
+    ("https://youtu.be/abc", True),
+    ("https://www.tiktok.com/@x/video/1", True),
+    ("https://www.reddit.com/r/x/comments/1/title", False),
+    ("https://en.wikipedia.org/wiki/Sleep", False),
+    ("https://someblog.com/post", False),
+])
+def test_is_video_url(url, is_video):
+    assert downloader._is_video_url(url) is is_video
+
+
+def test_download_content_routes_article(monkeypatch):
+    monkeypatch.setattr(article, "fetch_article", lambda url: article.ArticleResult(
+        title="T", text="body " * 50, author="A", image_url="https://i/x.jpg",
+        site="reddit",
+    ))
+    res = downloader.download_content("https://www.reddit.com/r/x/comments/1/t")
+    assert res.media_type == "article"
+    assert res.resolver == "article"
+    assert res.title == "T"
+    assert res.author == "A"
+    assert res.image_url == "https://i/x.jpg"
+
+
+def test_platform_for_url():
+    assert platform_for_url("https://www.reddit.com/r/x") == "reddit"
+    assert platform_for_url("https://en.wikipedia.org/wiki/X") == "wikipedia"
+    assert platform_for_url("https://x.substack.com/p/y") == "substack"
+    assert platform_for_url("https://www.someblog.com/post") == "someblog.com"
+    assert platform_for_url("https://youtu.be/abc") == "youtube"
+
+
+# --------------------------------------------------------------------------- #
+# extraction branch
+# --------------------------------------------------------------------------- #
+
+def test_extract_article_branch_skips_media(tmp_path):
+    download = DownloadResult(
+        media_type="article", data="", caption="My Title", resolver="article",
+        text="The body of the article goes here.", title="My Title",
+        author="Author", image_url="https://img/lead.jpg",
+    )
+    result = extract(download, str(tmp_path), "reddit / article")
+    assert "TITLE: My Title" in result.aggregated_text
+    assert "ARTICLE TEXT: The body of the article" in result.aggregated_text
+    assert result.thumbnail == "https://img/lead.jpg"  # remote, not downloaded
+    assert result.keyframes == []
+    assert result.had_transcript is False

backend/tests/test_pipeline.py

@@ -69,6 +69,37 @@ async def test_job_reaches_ready_with_sane_card(database, stub_pipeline):
     assert card.meta.extraction.transcript is True
 
 
+async def test_article_job_reaches_ready(database, monkeypatch):
+    """A non-video source runs through the article path: no media, real
+    extraction branch + structuring (offline -> paragraph fallback), READY."""
+    async def fake_download(url, config=None):
+        return DownloadResult(
+            media_type="article", data="", caption="Sleep Guide",
+            resolver="article", text="Sleep early. Avoid screens. " * 20,
+            title="Sleep Guide", author="Jane Doe",
+            image_url="https://img/cover.jpg",
+        )
+
+    monkeypatch.setattr(worker, "download_content_async", fake_download)
+    card_id, _ = await _make_card_and_job("https://en.wikipedia.org/wiki/Sleep")
+
+    async with db.session() as s:
+        jid = await _first_job_id(s, card_id)
+        job = await s.get(db.JobRow, jid)
+        await worker._run_job(s, job)
+
+    async with db.session() as s:
+        row = await db.get_card_row(s, card_id)
+        card = row.to_card()
+
+    assert card.state == CardState.READY
+    assert card.base.one_liner and card.base.tldr
+    assert card.blocks  # paragraph fallback at minimum
+    assert card.media.thumbnail == "https://img/cover.jpg"  # remote passthrough
+    assert card.source.resolver == "article"
+    assert card.source.creator == "Jane Doe"  # byline persisted
+
+
 async def test_ingestion_failure_dead_letters_after_retries(database, monkeypatch):
     async def boom(url, config=None):
         raise DownloadError("all resolvers failed")

backend/tests/test_structuring.py

@@ -67,3 +67,34 @@ def test_primary_action_mapping():
     raw_recipe = '{"base":{"one_liner":"a","tldr":"b","content_type":"recipe"},"blocks":[{"type":"paragraph","text":"x"}]}'
     sc = structuring._validate(raw_recipe, bundle="", transcript="", caption="")
     assert sc.primary_action.kind == PrimaryActionKind.SHOPPING_LIST
+
+
+def test_artifacts_extracted_and_validated():
+    raw = (
+        '{"base":{"one_liner":"5 books","tldr":"reading list","content_type":"tip"},'
+        '"blocks":[{"type":"bullet_list","items":["a"]}],'
+        '"artifacts":['
+        '{"type":"book","title":"Atomic Habits","creator":"James Clear","year":2018},'
+        '{"type":"bogus","title":"Dune"},'
+        '{"title":""},'
+        '"not a dict",'
+        '{"type":"book","title":"atomic habits"}]}'  # dup of first (case-insensitive)
+    )
+    sc = structuring._validate(raw, bundle="", transcript="", caption="")
+    titles = [(a.type.value, a.title) for a in sc.artifacts]
+    assert ("book", "Atomic Habits") in titles
+    assert ("other", "Dune") in titles  # bad type coerced to other
+    assert len(sc.artifacts) == 2  # empty-title, non-dict, and dup dropped
+
+
+def test_artifacts_kept_even_when_blocks_empty():
+    raw = '{"base":{"one_liner":"x","tldr":"y"},"blocks":[],"artifacts":[{"type":"movie","title":"Inception"}]}'
+    sc = structuring._validate(raw, bundle="", transcript="body text", caption="")
+    assert any(b["type"] == "paragraph" for b in sc.blocks)  # fallback body
+    assert [a.title for a in sc.artifacts] == ["Inception"]
+
+
+def test_no_artifacts_is_normal():
+    raw = '{"base":{"one_liner":"x","tldr":"y","content_type":"tip"},"blocks":[{"type":"paragraph","text":"z"}]}'
+    sc = structuring._validate(raw, bundle="", transcript="", caption="")
+    assert sc.artifacts == []

docs/02-ingestion.md

@@ -75,6 +75,41 @@ async def ingest(job):
 - **Resolver rot.** Expect individual resolvers to break over time. Monitor
   per-resolver success rate (it's recorded on every card) and prune/replace dead ones.
 
+## Article path (non-video sources)
+
+Not every shared link is short-form video. Reddit, Wikipedia, LinkedIn,
+Substack, news, and blogs are **text** — there is no media to download, the
+content *is* the article. These take a parallel path instead of the resolver
+cascade.
+
+**Routing (domain classify).** `downloader._is_video_url` checks the host:
+Instagram / TikTok / YouTube go to the fragile resolver cascade (unchanged);
+**everything else is treated as an article**. yt-dlp stays a safety net — if
+article extraction yields nothing usable, a non-video host is retried through
+yt-dlp in case the page is actually a video it supports.
+
+**Extraction.** `ingestion/article.py` (new orchestration the app owns — *not*
+title, readable body, author, and a remote lead-image URL. Best-effort: a thin
+body (paywall/login wall) or any error → `None` → normal ingestion failure (a
+LinkedIn post behind auth simply fails gracefully, same model as a dead
+resolver).
+
+```
+DownloadResult(media_type="article", data="", caption=title, resolver="article",
+               text=…, title=…, author=…, image_url=…)
+```
+
+**Pipeline fit.** The extraction stage branches on `media_type == "article"`:
+it skips ffmpeg / Whisper / OCR entirely, builds the labeled text bundle from
+title + body, and uses the remote `image_url` directly as the thumbnail
+(nothing is downloaded — fits the ephemeral free tier). Structuring (docs/04) is
+**unchanged**: article text flows in as the bundle exactly like a transcript
+does. No block-schema change.
+
+**Platform label.** `ingestion/source.py::platform_for_url` maps a URL to a
+label (reddit / wikipedia / linkedin / substack / medium / known video
+platforms), falling back to the bare host — shown in the card's source line.
+
 ## Caching
 
 Cache by source URL. Re-sharing the same reel returns the existing card instead

docs/04-structuring-and-schema.md

@@ -17,7 +17,7 @@ not new UI code.
 
 ```json
 {
-  "schema_version": "1.0",
+  "schema_version": "1.1",
   "card_id": "uuid",
   "state": "queued | processing | ready | failed",
   "failure_reason": null,
@@ -170,8 +170,18 @@ The guarantee: **a card always renders something sane**, even on a degraded
 model response. This validation step is the difference between "occasionally
 renders garbage" and "always usable."
 
+## Artifacts (catalog) — separate from blocks
+
+The same single structuring call also emits an `artifacts` list — concrete,
+named things the video *references* (books, movies, podcasts, products, places).
+These are **not blocks** and never render inside the card; they feed the global
+catalog. Validated separately (title required, dedupe, drop malformed). See
+`@docs/12-catalog-and-artifacts.md`. Their addition to the structuring output is
+what took `schema_version` to `1.1`.
+
 ## Versioning
 
 `schema_version` is on every card. When the vocabulary changes, bump it; the
 client renders known versions and degrades gracefully on unknown future blocks
-(render their `text`/`items` if present, else skip).
+(render their `text`/`items` if present, else skip). **1.1** added the
+`artifacts` list to the structuring output (block vocabulary unchanged).

docs/09-features.md

@@ -5,6 +5,8 @@ Full feature list by area. Phase tags: **[P1]** MVP, **[P2]**, **[P3]**.
 ## Ingestion
 - Share-sheet integration (Instagram first) **[P1]**, TikTok + YouTube Shorts **[P2]**
 - Link paste fallback **[P1]**
+- Article/text sources — Reddit, Wikipedia, LinkedIn, Substack, blogs, news (docs/02) **[done]**
+- Domain-classified routing (video cascade vs. keyless article extraction) **[done]**
 - Batch share — multiple reels queue independently without blocking **[P1]**
 - Duplicate detection — re-share returns existing card **[P1]**
 - Graceful late-surfaced failure for unsupported/private/unavailable **[P1]**
@@ -31,17 +33,27 @@ Full feature list by area. Phase tags: **[P1]** MVP, **[P2]**, **[P3]**.
 - Lookup-able products **[P2]**
 - Mappable places **[P2]**
 
-## Action layer
+## Action layer (docs/13)
 - One primary action per card **[P1]** (kind derived from content type)
-- Shopping/checklist generation **[P2]**
-- Reminders / calendar events **[P2]**
-- Export to Notion / Obsidian / Apple Notes / markdown **[P2]**
+- Content-aware action set — actions unlocked by the blocks a card contains **[done]**
+- Common actions on every card: Copy, Share, Open original **[done]**
+- Shopping/checklist generation (share as checkable list) **[done]**
+- Reminders / calendar events (native add-event) **[done]**
+- Export to Notion / Obsidian / Apple Notes / markdown (share markdown) **[done]**
+- Open place in Maps; open card links **[done]**
+- Grounded chat — Ask questions about a single card **[done]**
 
 ## Visual
 - Keyframe thumbnails + visual library grid **[P1]**
 - Color/motion/depth system, progressive-render animation **[P1]**
 - Maps with pins, charts, product thumbnails, visual step strips **[P2]**
 
+## Catalog (artifacts)
+- Artifact extraction from referenced things (book/movie/podcast/product/place…) **[P1]**
+- Global deduplicated catalog space, grouped by type **[P1]**
+- Free keyless thumbnail retrieval (iTunes / Open Library / Wikipedia) **[P1]**
+- Source-card backreferences per artifact **[P1]**
+
 ## Library & retrieval
 - Card states surfaced (queued/processing/ready/failed) **[P1]**
 - Basic search (full-text) **[P1]**

docs/12-catalog-and-artifacts.md

@@ -0,0 +1,90 @@
+# 12 — Catalog & Artifacts
+
+A second top-level space alongside the card Library: a **catalog** of the
+real-world things videos *reference* — books, movies, podcasts, music, products,
+places — deduplicated across every card and shown as a wall of covers.
+
+This is a **parallel surface to the block schema, not a new block type**. The
+block vocabulary (docs/04) is unchanged. Structuring's output simply grows an
+`artifacts` list, which the worker aggregates into a global catalog.
+
+## What an artifact is
+
+A concrete, named thing the video mentions, distinct from the how-to content of
+the card itself. A booktuber's video *is* a `tip`/`product_list` card **and**
+contributes its named books to the catalog.
+
+```json
+// artifact (as emitted by structuring, per card)
+{ "type": "book|movie|tv_show|podcast|music|product|place|app|other",
+  "title": "Atomic Habits",
+  "creator": "James Clear",   // author / director / artist / host / brand (nullable)
+  "year": 2018 }              // nullable
+```
+
+## Pipeline fit (one LLM call, still)
+
+Artifact extraction piggybacks on the **existing single text-only structuring
+call** (docs/04) — the prompt gains an `artifacts` field in its JSON output. No
+
+```
+structuring LLM → { base, blocks, artifacts }
+  → validate blocks      (docs/04, unchanged)
+  → validate artifacts   (drop title-less / malformed; dedupe within the card)
+  → worker: for each artifact
+       → resolve thumbnail (free image API, best-effort)
+       → upsert into the global catalog (dedupe by type + normalized title)
+```
+
+Artifacts are validated like blocks: never trusted raw. A malformed entry is
+dropped; an empty list is normal. Artifact failure never affects the card —
+the card still reaches READY.
+
+## Thumbnails (free, keyless, hotlinked)
+
+`services/artifact_images.py` routes by type to a public, no-key API and returns
+a remote `https` URL (nothing is downloaded or stored — fits the ephemeral
+free tier). Best-effort: any miss/timeout/error → `None` → typed placeholder.
+
+| Artifact type | Source | Key? |
+|---|---|---|
+| book | Open Library (cover by id/isbn), Wikipedia fallback | no |
+| movie / tv_show / podcast / music / app | iTunes Search API (`artworkUrl`) | no |
+| product / place / other | Wikipedia REST summary thumbnail | no |
+
+## Aggregation & dedupe
+
+A global `artifacts` table (docs/08 style: one row per catalog item). Dedupe key
+is `(type, normalized_title)`. Re-seeing the same artifact in another card appends
+that `card_id` to `source_card_ids` and backfills any missing thumbnail/creator/
+year rather than creating a duplicate.
+
+## API
+
+```
+GET    /catalog            list entries (optional ?type=, paginated)
+GET    /catalog/{id}       one entry + its source_card_ids
+DELETE /catalog/{id}       remove an entry (data ownership)
+```
+
+`CatalogEntry`:
+
+```json
+{ "id": "a_xxxxxxxx", "type": "book", "title": "Atomic Habits",
+  "creator": "James Clear", "year": 2018,
+  "thumbnail": "https://covers.openlibrary.org/...",
+  "source_card_ids": ["uuid", "uuid"], "created_at": "ISO-8601" }
+```
+
+## Frontend
+
+A second tab in the root `NavigationBar` (Library | Catalog). The Catalog screen
+shows entries grouped by type, each a cover tile with title + creator·year. Covers
+load via `Image.network` and degrade to a typed icon placeholder on error — never
+
+## Schema version
+
+Adding `artifacts` to the structuring/card contract bumps `SCHEMA_VERSION`
+**1.0 → 1.1**. The block vocabulary is unchanged, so existing cards and the
+renderer are unaffected; the client tolerates the new version (it never hard-fails
+on a version it doesn't recognize).

docs/13-actions-and-chat.md

@@ -0,0 +1,67 @@
+# 13 — Actions & Chat
+
+How a card becomes *useful*, not just readable. Two surfaces: a **content-aware
+action layer** and **grounded chat (Ask)**. Both are additive — no block-schema
+change (docs/04 is unchanged); everything is derived from a card's existing
+content.
+
+## Action layer
+
+The backend still derives one dominant `primary_action` per card (docs/04). The
+client now goes further: it inspects the card's **blocks** and offers every
+action that fits, plus a common set on every card. All payloads are built
+client-side from blocks, so the wire `payload` stays empty.
+
+| Action | Shown when | Handler (free, on-device) |
+|---|---|---|
+| Ask | always | opens grounded chat (below) |
+| Copy | always | card → markdown → clipboard |
+| Share | always | card → markdown → OS share sheet (`share_plus`) |
+| Add to calendar | always | native add-event sheet (`add_2_calendar`) |
+| Open original | has source url | launches the reel (`url_launcher`) |
+| Open in Maps | has a `map`/place block | Maps search/coords (`url_launcher`) |
+| Shopping list | has `checklist`/`bullet_list` | items → checkable list → share |
+| Open links | has a `link` block | launches the first link |
+
+The dominant `primary_action` is rendered as the big button; the rest live
+behind a "more" menu. The reader shows the bar whenever the card is READY (Ask
+is available even when there is no primary action).
+
+Frontend: `ui/features/reader/services/card_actions.dart` (`available()`,
+`primaryType()`, `perform()`), surfaced by `views/primary_action_bar.dart`.
+
+### Android config
+
+- `url_launcher` https + `add_2_calendar` insert intents are declared in
+  `android/app/src/main/AndroidManifest.xml` `<queries>` (Android 11+ package
+  visibility).
+
+## Chat (Ask)
+
+Grounded Q&A over a single card. The model answers using **only that card's
+structured content** as context; if the answer isn't there, it says so.
+
+```
+POST /cards/{card_id}/chat
+  body: { "messages": [ { "role": "user|assistant", "content": str }, ... ] }
+  → 200 { "reply": str }
+  → 409 card is not READY
+  → 422 last message is not from the user
+  → 503 no LLM backend configured
+```
+
+**Stateless.** Nothing is persisted server-side: the client holds the
+conversation and replays the full history each turn (capped to the last
+`_MAX_TURNS` for cost). Grounding context is the card's `base` (one_liner, tldr)
+plus a flattened plain-text view of its blocks.
+
+**Free-first.** Reuses the same selectable backend as structuring
+(`llm_backend = huggingface | groq | none`) via `services/llm_chat.py`. With no
+key, the endpoint returns 503 and the UI shows an "unavailable" message — the
+card still reads and every other action still works.
+
+**Trust.** The chat header carries the standard "AI-generated · may contain
+errors" note (docs/09 trust & safety).
+
+Frontend: `ui/features/reader/view_models/chat_view_model.dart` +
+`views/chat_screen.dart`, opened from the **Ask** action.