polished the app

.gitignore

@@ -47,4 +47,6 @@ i-want-you-to-spicy-dusk.md
 CACHY_OVERVIEW.md
 # Root-level Python prototype agent only — anchored so it does NOT swallow the
 # Flutter feature dir app/lib/ui/features/presenter/.
-/presenter/
+/presenter/
+PRODUCT.md
+.impeccable/critique/2026-07-10T11-11-16Z__app-lib.md

app/lib/data/repositories/card_repository.dart

@@ -159,6 +159,9 @@ class CardRepository extends ChangeNotifier {
     return card;
   }
 
+  /// Clear all locally cached cards. Returns how many were removed.
+  Future<int> clearCardCache() => _store.clearCardCache();
+
   Future<void> delete(String cardId) async {
     await _store.removeCard(cardId);
     try {

app/lib/data/services/api_client.dart

@@ -21,11 +21,29 @@ import '../../domain/models/pipeline_event.dart';
 class ApiException implements Exception {
   ApiException(this.statusCode, this.message);
   final int statusCode;
-  final String message;
+  final String message; // raw body — for logs only, never for UI
+
+  /// What users see. Raw bodies (which may include server details or
+  /// tracebacks) never leave the data layer.
+  String get friendlyMessage => switch (statusCode) {
+        401 || 403 => 'Session expired — please sign in again.',
+        404 => "That card isn't there anymore.",
+        429 => "You've hit today's limit. It resets at midnight UTC.",
+        >= 500 => 'Something went wrong on our side. Try again in a moment.',
+        _ => "That didn't work. Try again.",
+      };
+
   @override
   String toString() => 'ApiException($statusCode): $message';
 }
 
+/// UI-safe message for any thrown object. The only thing view-models should
+/// ever store in a user-visible error field.
+String friendlyError(Object e) => switch (e) {
+      ApiException api => api.friendlyMessage,
+      _ => "Can't reach Cachy. Check your connection.",
+    };
+
 class CreateCardResult {
   const CreateCardResult({
     required this.cardId,

app/lib/data/services/local_store.dart

@@ -90,6 +90,16 @@ class LocalStore {
     await _prefs.setStringList(_indexKey, index.toList());
   }
 
+  /// Remove every cached card and the index. Returns how many were removed.
+  Future<int> clearCardCache() async {
+    final ids = cachedCardIds();
+    for (final id in ids) {
+      await _prefs.remove('$_cardPrefix$id');
+    }
+    await _prefs.remove(_indexKey);
+    return ids.length;
+  }
+
   // --------------------------------------------------------------------- //
   // Offline share queue
   // --------------------------------------------------------------------- //

app/lib/ui/core/home_shell.dart

@@ -16,14 +16,15 @@ import '../features/actions/views/actions_screen.dart';
 import '../features/capture/views/capture_sheet.dart';
 import '../features/collections/views/collections_screen.dart';
 import '../features/feed/views/knowledge_feed_screen.dart';
+import '../features/collections/views/folder_picker_sheet.dart';
 import '../features/library/view_models/library_view_model.dart';
+import '../features/library/views/library_dialogs.dart';
 import '../features/library/views/library_screen.dart';
 import '../features/profile/views/profile_screen.dart';
 import '../features/reader/views/reader_screen.dart';
 import 'brand.dart';
 import 'theme.dart';
 import 'ui_bus.dart';
-import 'widgets/adaptive_modal.dart';
 import 'widgets/glass.dart';
 import 'widgets/selection_action_bar.dart';
 
@@ -167,49 +168,12 @@ class _HomeShellState extends State<HomeShell> {
       bottomNavigationBar: selecting
           ? _SelectionNavSlot(
               vm: vm,
-              onConfirmDelete: () => _confirmBulkDelete(context, vm),
+              onConfirmDelete: () => confirmBulkDelete(context, vm),
             )
           : _GlassNav(index: _index, onSelect: _select),
     );
   }
 
-  Future<void> _confirmBulkDelete(
-      BuildContext context, LibraryViewModel vm) async {
-    final count = vm.selectedCount;
-    final ok = await showAdaptiveModal<bool>(
-      context: context,
-      builder: (ctx, dialog) => AlertDialog(
-        title: Text('Delete $count ${count == 1 ? 'card' : 'cards'}?'),
-        content: const Text(
-            'This removes the cards and their media. This cannot be undone.'),
-        actions: [
-          TextButton(
-            onPressed: () => Navigator.pop(ctx, false),
-            child: const Text('Cancel'),
-          ),
-          FilledButton(
-            onPressed: () => Navigator.pop(ctx, true),
-            style: FilledButton.styleFrom(
-              backgroundColor: Theme.of(ctx).colorScheme.error,
-            ),
-            child: const Text('Delete'),
-          ),
-        ],
-      ),
-    );
-    if (ok == true && context.mounted) {
-      await vm.bulkDelete();
-      if (context.mounted) {
-        final error = context.read<LibraryViewModel>().error;
-        if (error != null) {
-          ScaffoldMessenger.of(context).showSnackBar(
-            SnackBar(content: Text('Delete failed: $error')),
-          );
-        }
-      }
-    }
-  }
-
   Widget _desktopShell(BuildContext context) {
     return Scaffold(
       body: Stack(
@@ -480,9 +444,7 @@ class _SelectionNavSlot extends StatelessWidget {
       child: SelectionActionBar(
         selectedCount: vm.selectedCount,
         onClose: vm.clearSelection,
-        onMoveToFolder: () => ScaffoldMessenger.of(context).showSnackBar(
-          const SnackBar(content: Text('Move to Folder coming soon')),
-        ),
+        onMoveToFolder: () => showFolderPicker(context, vm),
         onDeleteSelected: onConfirmDelete,
       ),
     );

app/lib/ui/core/theme.dart

@@ -148,7 +148,17 @@ class Motion {
   static const slow = Duration(milliseconds: 420);
   static const stagger = Duration(milliseconds: 45);
   static const curve = Curves.easeOutCubic;
-  static const spring = Curves.easeOutBack;
+  // Ease-out with no overshoot: the product register bans bounce/elastic.
+  static const spring = Curves.easeOutCubic;
+}
+
+/// Reduced-motion gate: animations collapse to zero duration when the OS asks
+/// for reduced motion, honouring the accessibility setting everywhere at once.
+extension MotionGate on BuildContext {
+  bool get motionEnabled => !MediaQuery.of(this).disableAnimations;
+
+  /// [d] when motion is allowed, otherwise [Duration.zero] (instant).
+  Duration gated(Duration d) => motionEnabled ? d : Duration.zero;
 }
 
 /// Layout tokens: generous editorial margins.

app/lib/ui/core/widgets/loading_tiles.dart

@@ -14,6 +14,7 @@ class LoadingTiles extends StatelessWidget {
   @override
   Widget build(BuildContext context) {
     final scheme = Theme.of(context).colorScheme;
+    final animate = context.motionEnabled;
     return GridView.count(
       padding: const EdgeInsets.all(Insets.page),
       physics: const NeverScrollableScrollPhysics(),
@@ -23,18 +24,23 @@ class LoadingTiles extends StatelessWidget {
       childAspectRatio: 0.72,
       children: [
         for (var i = 0; i < count; i++)
-          Container(
-            decoration: BoxDecoration(
-              color: scheme.surfaceContainerHigh,
-              borderRadius: BorderRadius.circular(Insets.radius),
-            ),
-          )
-              .animate(onPlay: (c) => c.repeat())
-              .shimmer(
-                duration: const Duration(milliseconds: 1100),
-                delay: Duration(milliseconds: i * 90),
-                color: scheme.surfaceContainerHighest,
+          () {
+            final tile = Container(
+              decoration: BoxDecoration(
+                color: scheme.surfaceContainerHigh,
+                borderRadius: BorderRadius.circular(Insets.radius),
               ),
+            );
+            // Reduced motion: a static placeholder, no looping shimmer.
+            if (!animate) return tile;
+            return tile
+                .animate(onPlay: (c) => c.repeat())
+                .shimmer(
+                  duration: const Duration(milliseconds: 1100),
+                  delay: Duration(milliseconds: i * 90),
+                  color: scheme.surfaceContainerHighest,
+                );
+          }(),
       ],
     );
   }

app/lib/ui/core/widgets/processing_glyph.dart

@@ -73,7 +73,7 @@ class _ProcessingGlyphState extends State<ProcessingGlyph>
         child: TweenAnimationBuilder<double>(
           tween: Tween(begin: 0.0, end: 1.0),
           duration: const Duration(milliseconds: 600),
-          curve: Curves.easeOutBack,
+          curve: Curves.easeOutCubic,
           builder: (context, t, _) {
             final pulse = 1.0 + 0.04 * (1 - (2 * (_c.value) - 1).abs());
             return Transform.scale(

app/lib/ui/features/actions/view_models/actions_view_model.dart

@@ -7,6 +7,7 @@ library;
 import 'package:flutter/foundation.dart';
 
 import '../../../../data/repositories/card_repository.dart';
+import '../../../../data/services/api_client.dart';
 import '../../../../domain/models/card.dart';
 
 enum ActionsStatus { idle, loading, ready, error, empty }
@@ -70,7 +71,7 @@ class ActionsViewModel extends ChangeNotifier {
       _status = groups.isEmpty ? ActionsStatus.empty : ActionsStatus.ready;
       _error = null;
     } catch (e) {
-      _error = e.toString();
+      _error = friendlyError(e);
       _status = ActionsStatus.error;
     }
     notifyListeners();

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

@@ -5,6 +5,7 @@ library;
 import 'package:flutter/foundation.dart';
 
 import '../../../../data/repositories/card_repository.dart';
+import '../../../../data/services/api_client.dart';
 import '../../../../domain/models/artifact.dart';
 
 enum CatalogStatus { idle, loading, ready, error, empty }
@@ -84,7 +85,7 @@ class CatalogViewModel extends ChangeNotifier {
           _entries.isEmpty ? CatalogStatus.empty : CatalogStatus.ready;
       _error = null;
     } catch (e) {
-      _error = '$e';
+      _error = friendlyError(e);
       _status = _entries.isEmpty ? CatalogStatus.error : CatalogStatus.ready;
     }
     notifyListeners();

app/lib/ui/features/collections/view_models/collections_view_model.dart

@@ -3,6 +3,7 @@ library;
 import 'package:flutter/foundation.dart';
 
 import '../../../../data/repositories/card_repository.dart';
+import '../../../../data/services/api_client.dart';
 import '../../../../domain/models/card.dart';
 import '../../../../domain/models/collection.dart';
 import '../../../../domain/models/enums.dart';
@@ -95,7 +96,7 @@ class CollectionsViewModel extends ChangeNotifier {
       _error = null;
       _status = _collections.isEmpty ? CollectionsStatus.empty : CollectionsStatus.ready;
     } catch (e) {
-      _error = '$e';
+      _error = friendlyError(e);
       // Fall back to client-side grouping from cached cards.
       try {
         final cards = await _repository.list();

app/lib/ui/features/collections/views/folder_picker_sheet.dart

@@ -0,0 +1,166 @@
+/// Bulk "Move to Folder" picker — an adaptive sheet listing the user's folders
+/// (plus "New folder…" and "Remove from folders"). Replaces the old
+/// coming-soon stub in the selection action bar.
+library;
+
+import 'package:flutter/material.dart';
+import 'package:phosphor_flutter/phosphor_flutter.dart';
+import 'package:provider/provider.dart';
+
+import '../../../../data/repositories/card_repository.dart';
+import '../../../../domain/models/collection.dart';
+import '../../../core/theme.dart';
+import '../../../core/widgets/adaptive_modal.dart';
+import '../../library/view_models/library_view_model.dart';
+
+/// Present the folder picker for the current selection. Moves every selected
+/// card into the chosen folder and shows a confirmation. No-op if nothing is
+/// selected.
+Future<void> showFolderPicker(BuildContext context, LibraryViewModel vm) async {
+  if (!vm.selectionActive) return;
+  final count = vm.selectedCount;
+  final repo = context.read<CardRepository>();
+  final messenger = ScaffoldMessenger.of(context);
+
+  await showAdaptiveModal<void>(
+    context: context,
+    builder: (ctx, dialog) => _FolderPicker(
+      repo: repo,
+      dialog: dialog,
+      onPick: (collectionId, label) async {
+        Navigator.pop(ctx);
+        await vm.bulkMove(collectionId);
+        messenger.showSnackBar(SnackBar(
+          content: Text(
+            'Moved $count ${count == 1 ? 'card' : 'cards'}'
+            '${label == null ? ' out of folders' : ' to "$label"'}',
+          ),
+        ));
+      },
+    ),
+  );
+}
+
+class _FolderPicker extends StatelessWidget {
+  const _FolderPicker({
+    required this.repo,
+    required this.dialog,
+    required this.onPick,
+  });
+
+  final CardRepository repo;
+  final bool dialog;
+
+  /// (collectionId, label): collectionId null = remove from all folders.
+  final Future<void> Function(String? collectionId, String? label) onPick;
+
+  @override
+  Widget build(BuildContext context) {
+    final theme = Theme.of(context);
+    final scheme = theme.colorScheme;
+    return Container(
+      decoration: BoxDecoration(
+        color: scheme.surface,
+        borderRadius: dialog
+            ? BorderRadius.circular(Insets.radius)
+            : const BorderRadius.vertical(top: Radius.circular(Insets.radius)),
+      ),
+      padding: EdgeInsets.only(
+        top: 12,
+        bottom: MediaQuery.of(context).viewInsets.bottom + 12,
+      ),
+      child: Column(
+        mainAxisSize: MainAxisSize.min,
+        children: [
+          if (!dialog)
+            Container(
+              width: 36,
+              height: 4,
+              margin: const EdgeInsets.only(bottom: 12),
+              decoration: BoxDecoration(
+                color: scheme.onSurfaceVariant.withValues(alpha: 0.3),
+                borderRadius: BorderRadius.circular(2),
+              ),
+            ),
+          Padding(
+            padding: const EdgeInsets.fromLTRB(20, 4, 20, 12),
+            child: Align(
+              alignment: Alignment.centerLeft,
+              child: Text('Move to folder', style: theme.textTheme.titleMedium),
+            ),
+          ),
+          Flexible(
+            child: FutureBuilder<List<CollectionEntry>>(
+              future: repo.listCollections(),
+              builder: (context, snap) {
+                if (snap.connectionState == ConnectionState.waiting) {
+                  return const Padding(
+                    padding: EdgeInsets.all(24),
+                    child: CircularProgressIndicator(),
+                  );
+                }
+                final folders = snap.data ?? const <CollectionEntry>[];
+                return ListView(
+                  shrinkWrap: true,
+                  padding: EdgeInsets.zero,
+                  children: [
+                    for (final f in folders)
+                      ListTile(
+                        leading: const PhosphorIcon(PhosphorIconsRegular.folder),
+                        title: Text(f.name),
+                        onTap: () => onPick(f.id, f.name),
+                      ),
+                    const Divider(height: 1),
+                    ListTile(
+                      leading: PhosphorIcon(PhosphorIconsRegular.folderPlus,
+                          color: scheme.primary),
+                      title: Text('New folder…',
+                          style: TextStyle(color: scheme.primary)),
+                      onTap: () => _createAndMove(context),
+                    ),
+                    if (folders.isNotEmpty)
+                      ListTile(
+                        leading: const PhosphorIcon(PhosphorIconsRegular.folderMinus),
+                        title: const Text('Remove from folders'),
+                        onTap: () => onPick(null, null),
+                      ),
+                  ],
+                );
+              },
+            ),
+          ),
+        ],
+      ),
+    );
+  }
+
+  Future<void> _createAndMove(BuildContext context) async {
+    final controller = TextEditingController();
+    final name = await showDialog<String>(
+      context: context,
+      builder: (ctx) => AlertDialog(
+        title: const Text('New folder'),
+        content: TextField(
+          controller: controller,
+          autofocus: true,
+          textCapitalization: TextCapitalization.words,
+          decoration: const InputDecoration(hintText: 'Folder name'),
+          onSubmitted: (v) => Navigator.pop(ctx, v.trim()),
+        ),
+        actions: [
+          TextButton(
+            onPressed: () => Navigator.pop(ctx),
+            child: const Text('Cancel'),
+          ),
+          FilledButton(
+            onPressed: () => Navigator.pop(ctx, controller.text.trim()),
+            child: const Text('Create'),
+          ),
+        ],
+      ),
+    );
+    if (name == null || name.isEmpty) return;
+    final created = await repo.createCollection(name);
+    await onPick(created.id, created.name);
+  }
+}

app/lib/ui/features/concepts/view_models/concepts_view_model.dart

@@ -5,6 +5,7 @@ library;
 import 'package:flutter/foundation.dart';
 
 import '../../../../data/repositories/card_repository.dart';
+import '../../../../data/services/api_client.dart';
 import '../../../../domain/models/concept.dart';
 import '../../../core/safe_notifier.dart';
 
@@ -61,7 +62,7 @@ class ConceptsViewModel extends ChangeNotifier with SafeNotifier {
       _status = _entries.isEmpty ? ConceptsStatus.empty : ConceptsStatus.ready;
       _error = null;
     } catch (e) {
-      _error = '$e';
+      _error = friendlyError(e);
       _status = _entries.isEmpty ? ConceptsStatus.error : ConceptsStatus.ready;
     }
     notifyListeners();

app/lib/ui/features/feed/views/knowledge_feed_screen.dart

@@ -641,14 +641,16 @@ class _SwipeHint extends StatelessWidget {
   @override
   Widget build(BuildContext context) {
     final scheme = Theme.of(context).colorScheme;
-    return Column(
+    final hint = Column(
       mainAxisSize: MainAxisSize.min,
       children: [
         PhosphorIcon(PhosphorIconsRegular.caretUp, size: 18, color: scheme.onSurfaceVariant),
         Text('SWIPE UP',
             style: Brand.label(size: 9, color: scheme.onSurfaceVariant, weight: FontWeight.w600)),
       ],
-    )
+    );
+    if (!context.motionEnabled) return hint; // reduced motion: static hint
+    return hint
         .animate(onPlay: (c) => c.repeat(reverse: true))
         .moveY(begin: 4, end: -4, duration: 900.ms, curve: Curves.easeInOut);
   }

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

@@ -7,20 +7,53 @@ import 'dart:async';
 import 'package:flutter/foundation.dart';
 
 import '../../../../data/repositories/card_repository.dart';
+import '../../../../data/services/api_client.dart';
 import '../../../../domain/models/card.dart';
 import '../../../../domain/models/enums.dart';
 import '../../../core/safe_notifier.dart';
 
-enum LibraryStatus { idle, loading, ready, error, empty }
+enum LibraryStatus { idle, loading, waking, ready, error, empty }
 
 class LibraryViewModel extends ChangeNotifier with SafeNotifier {
-  LibraryViewModel({required CardRepository repository})
-      : _repository = repository {
+  LibraryViewModel({
+    required CardRepository repository,
+    this.wakeRetryDelay = const Duration(seconds: 10),
+  }) : _repository = repository {
     _repository.addListener(_onRepoChange);
   }
 
   final CardRepository _repository;
 
+  /// Delay between cold-start retries; overridden to zero in tests.
+  final Duration wakeRetryDelay;
+
+  /// Free HF Spaces nap when idle and take ~30s to wake. We retry a handful of
+  /// times, showing the "waking" state, before conceding to an error.
+  static const _maxWakeAttempts = 6;
+  int _wakeAttempt = 0;
+  int get wakeAttempt => _wakeAttempt;
+
+  /// A connection-shaped failure worth retrying: no HTTP response at all
+  /// (socket/timeout, thrown as non-[ApiException]) or a gateway 502/503 from
+  /// a Space that is still booting.
+  bool _isWaking(Object e) =>
+      e is! ApiException || e.statusCode == 502 || e.statusCode == 503;
+
+  /// Fetch the library, retrying through cold start. Rethrows once retries are
+  /// exhausted or the failure isn't cold-start-shaped.
+  Future<List<Card>> _fetchWithWake() async {
+    for (_wakeAttempt = 0; ; _wakeAttempt++) {
+      try {
+        return await _repository.list(state: _filter);
+      } catch (e) {
+        if (!_isWaking(e) || _wakeAttempt >= _maxWakeAttempts) rethrow;
+        _status = LibraryStatus.waking;
+        notifyListeners();
+        await Future<void>.delayed(wakeRetryDelay);
+      }
+    }
+  }
+
   void _onRepoChange() {
     if (_status != LibraryStatus.loading) {
       load(showSpinner: false);
@@ -207,13 +240,13 @@ class LibraryViewModel extends ChangeNotifier with SafeNotifier {
     }
     try {
       await _repository.flushPendingShares();
-      final cards = await _repository.list(state: _filter);
+      final cards = await _fetchWithWake();
       _cards = cards;
       _offline = false;
       _status = cards.isEmpty ? LibraryStatus.empty : LibraryStatus.ready;
       _error = null;
     } catch (e) {
-      _error = '$e';
+      _error = friendlyError(e);
       _offline = true;
       _status = _cards.isEmpty ? LibraryStatus.error : LibraryStatus.ready;
     }
@@ -247,6 +280,24 @@ class LibraryViewModel extends ChangeNotifier with SafeNotifier {
   /// repository. If any deletion fails, the card list and selection are
   /// restored exactly to their pre-operation values and an error is surfaced
   /// (Requirement 8.9).
+  /// Move every currently-selected card into [collectionId] (null removes them
+  /// from all folders). Clears the selection and resyncs on success; surfaces a
+  /// friendly error and keeps the selection on failure.
+  Future<void> bulkMove(String? collectionId) async {
+    final ids = _selectedIds.toList();
+    if (ids.isEmpty) return;
+    try {
+      for (final id in ids) {
+        await _repository.moveCardToCollection(id, collectionId);
+      }
+      clearSelection();
+      await load(showSpinner: false);
+    } catch (e) {
+      _error = friendlyError(e);
+      notifyListeners();
+    }
+  }
+
   Future<void> bulkDelete() async {
     final ids = _selectedIds.toList();
     if (ids.isEmpty) return;
@@ -287,7 +338,7 @@ class LibraryViewModel extends ChangeNotifier with SafeNotifier {
         ..addAll(selectionSnapshot);
       _selectionMode = selectionModeSnapshot;
       _selectionAnchorId = anchorSnapshot;
-      _error = '$e';
+      _error = friendlyError(e);
       notifyListeners();
     }
   }

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

@@ -0,0 +1,44 @@
+/// Shared bulk-selection dialogs for the library. Extracted so the mobile shell
+/// and the desktop overlay invoke the exact same confirmation flow instead of
+/// each carrying its own copy.
+library;
+
+import 'package:flutter/material.dart';
+
+import '../../../core/widgets/adaptive_modal.dart';
+import '../view_models/library_view_model.dart';
+
+/// Confirm and perform a bulk delete of the currently-selected cards. Surfaces
+/// a snackbar if the delete fails.
+Future<void> confirmBulkDelete(BuildContext context, LibraryViewModel vm) async {
+  final count = vm.selectedCount;
+  if (count == 0) return;
+  final messenger = ScaffoldMessenger.of(context);
+  final ok = await showAdaptiveModal<bool>(
+    context: context,
+    builder: (ctx, dialog) => AlertDialog(
+      title: Text('Delete $count ${count == 1 ? 'card' : 'cards'}?'),
+      content: const Text(
+          'This removes the cards and their media. This cannot be undone.'),
+      actions: [
+        TextButton(
+          onPressed: () => Navigator.pop(ctx, false),
+          child: const Text('Cancel'),
+        ),
+        FilledButton(
+          onPressed: () => Navigator.pop(ctx, true),
+          style: FilledButton.styleFrom(
+            backgroundColor: Theme.of(ctx).colorScheme.error,
+          ),
+          child: const Text('Delete'),
+        ),
+      ],
+    ),
+  );
+  if (ok == true) {
+    await vm.bulkDelete();
+    if (vm.error != null) {
+      messenger.showSnackBar(SnackBar(content: Text(vm.error!)));
+    }
+  }
+}

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

@@ -1,9 +1,9 @@
 /// The library: a browsable wall of card faces (docs/06), not a feed of text.
-/// Two segments — Cards (the grid) and To-do (actions followed off reels, folded
-/// in from the old Actions tab). Branded chrome (wordmark, gradient tab
-/// indicator), designed empty/loading/error/offline states, and a staggered
-/// tile entrance. Capture lives in the shell's center button; search opens a
-/// dedicated screen. Tap a tile → reader via a shared-element face transition.
+/// Three segments — Cards (the grid), Concepts, and Catalog. Branded chrome
+/// (wordmark, gradient tab indicator), designed empty/loading/waking/error/
+/// offline states, and a staggered tile entrance. Capture lives in the shell's
+/// center button; search opens a dedicated screen. Tap a tile → reader via a
+/// shared-element face transition.
 library;
 
 import 'dart:io' show Platform;
@@ -21,7 +21,6 @@ import '../../../../domain/models/highlight.dart';
 import '../../../core/app_controller.dart';
 import '../../../core/brand.dart';
 import '../../../core/theme.dart';
-import '../../../core/widgets/adaptive_modal.dart';
 import '../../../core/widgets/empty_state.dart';
 import '../../../core/widgets/error_state.dart';
 import '../../../core/widgets/loading_tiles.dart';
@@ -30,6 +29,7 @@ import '../../../core/widgets/split_pane.dart';
 import '../../../core/widgets/spot_art.dart';
 import '../../capture/views/capture_sheet.dart';
 import '../../catalog/views/catalog_screen.dart';
+import '../../collections/views/folder_picker_sheet.dart';
 import '../../concepts/views/concepts_screen.dart';
 import '../../graph/views/graph_screen.dart';
 import '../../library/views/library_chat_screen.dart';
@@ -38,6 +38,7 @@ import '../../reader/views/reader_screen.dart';
 import '../../search/views/search_screen.dart';
 import '../view_models/library_view_model.dart';
 import 'card_tile.dart';
+import 'library_dialogs.dart';
 import 'grid_navigation.dart';
 
 class LibraryScreen extends StatelessWidget {
@@ -312,60 +313,28 @@ class _CardsTabState extends State<_CardsTab> {
           child: SelectionActionBar(
             selectedCount: vm.selectedCount,
             onClose: () => context.read<LibraryViewModel>().clearSelection(),
-            onMoveToFolder: () {
-              ScaffoldMessenger.of(context).showSnackBar(
-                const SnackBar(content: Text('Move to Folder coming soon')),
-              );
-            },
-            onDeleteSelected: () => _confirmBulkDelete(context),
+            onMoveToFolder: () =>
+                showFolderPicker(context, context.read<LibraryViewModel>()),
+            onDeleteSelected: () => confirmBulkDelete(context, vm),
           ),
         ),
       ],
     );
   }
 
-  Future<void> _confirmBulkDelete(BuildContext context) async {
-    final vm = context.read<LibraryViewModel>();
-    final count = vm.selectedCount;
-    final ok = await showAdaptiveModal<bool>(
-      context: context,
-      builder: (ctx, dialog) => AlertDialog(
-        title: Text('Delete $count ${count == 1 ? 'card' : 'cards'}?'),
-        content: const Text(
-            'This removes the cards and their media. This cannot be undone.'),
-        actions: [
-          TextButton(
-            onPressed: () => Navigator.pop(ctx, false),
-            child: const Text('Cancel'),
-          ),
-          FilledButton(
-            onPressed: () => Navigator.pop(ctx, true),
-            style: FilledButton.styleFrom(
-              backgroundColor: Theme.of(ctx).colorScheme.error,
-            ),
-            child: const Text('Delete'),
-          ),
-        ],
-      ),
-    );
-    if (ok == true && context.mounted) {
-      await context.read<LibraryViewModel>().bulkDelete();
-      // If bulkDelete surfaced an error (vm.error != null), show it.
-      if (context.mounted) {
-        final error = context.read<LibraryViewModel>().error;
-        if (error != null) {
-          ScaffoldMessenger.of(context).showSnackBar(
-            SnackBar(content: Text('Delete failed: $error')),
-          );
-        }
-      }
-    }
-  }
-
   Widget _body(BuildContext context, LibraryViewModel vm, dynamic api) {
     switch (vm.status) {
       case LibraryStatus.loading:
         return const LoadingTiles();
+      case LibraryStatus.waking:
+        return _scrollable(
+          const EmptyState(
+            showGlyph: true,
+            title: 'Waking Cachy up…',
+            message: 'The free server naps when idle. First load takes about '
+                '30 seconds — your library is on its way.',
+          ),
+        );
       case LibraryStatus.error:
         return _scrollable(
           ErrorState(

app/lib/ui/features/onboarding/views/name_screen.dart

@@ -4,7 +4,6 @@
 library;
 
 import 'package:flutter/material.dart';
-import 'package:google_fonts/google_fonts.dart';
 import 'package:phosphor_flutter/phosphor_flutter.dart';
 import 'package:provider/provider.dart';
 
@@ -87,26 +86,13 @@ class _NameScreenState extends State<NameScreen> {
                   const SizedBox(height: 32),
                   RichText(
                     text: TextSpan(
-                      style: GoogleFonts.fraunces(
-                        fontSize: 42,
-                        fontWeight: FontWeight.w800,
-                        letterSpacing: -1.0,
-                        height: 1.1,
-                        color: scheme.onSurface,
-                      ),
+                      style: theme.textTheme.displaySmall
+                          ?.copyWith(color: scheme.onSurface),
                       children: [
                         const TextSpan(text: "What's\nyour "),
                         TextSpan(
                           text: 'name?',
-                          style: TextStyle(
-                            color: scheme.primary,
-                            shadows: [
-                              Shadow(
-                                color: scheme.primary.withValues(alpha: 0.35),
-                                blurRadius: 24,
-                              ),
-                            ],
-                          ),
+                          style: TextStyle(color: scheme.primary),
                         ),
                       ],
                     ),

app/lib/ui/features/onboarding/views/onboarding_screen.dart

@@ -1,10 +1,10 @@
-/// First-run onboarding: detailed 3-phase showcase adapted from Insightr
-/// (demo) featuring Cachy logo headers, Fraunces serif display headlines,
-/// floating capability badges, mock structured feature cards, and library vault previews.
+/// First-run onboarding: a 3-page showcase — capture, structure, library — on
+/// the brand's calm-editorial chrome (CachyGlyph wordmark, Fraunces serif
+/// display via the theme), floating capability badges, mock structured feature
+/// cards, and library vault previews.
 library;
 
 import 'package:flutter/material.dart';
-import 'package:google_fonts/google_fonts.dart';
 import 'package:phosphor_flutter/phosphor_flutter.dart';
 
 import '../../../core/brand.dart';
@@ -160,33 +160,8 @@ class _OnboardingScreenState extends State<OnboardingScreen> {
 class _LogoBadge extends StatelessWidget {
   @override
   Widget build(BuildContext context) {
-    final scheme = Theme.of(context).colorScheme;
-    return Row(
-      children: [
-        Container(
-          width: 34,
-          height: 34,
-          decoration: BoxDecoration(
-            color: scheme.primary,
-            borderRadius: BorderRadius.circular(10),
-            boxShadow: [
-              BoxShadow(
-                color: scheme.primary.withValues(alpha: 0.4),
-                blurRadius: 12,
-                offset: const Offset(0, 3),
-              ),
-            ],
-          ),
-          child: PhosphorIcon(
-            PhosphorIconsRegular.lightning,
-            color: scheme.onPrimary,
-            size: 20,
-          ),
-        ),
-        const SizedBox(width: 10),
-        Text('Cachy', style: Brand.wordmarkStyle(20, color: scheme.onSurface)),
-      ],
-    );
+    // The real brand mark, not a generic lightning-in-a-box.
+    return const CachyWordmark(size: 20);
   }
 }
 
@@ -244,27 +219,10 @@ class _PageHook extends StatelessWidget {
           RichText(
             textAlign: TextAlign.center,
             text: TextSpan(
-              style: GoogleFonts.fraunces(
-                fontSize: 48,
-                fontWeight: FontWeight.w800,
-                letterSpacing: -1.2,
-                height: 1.1,
-                color: scheme.onSurface,
-              ),
+              style: theme.textTheme.displayMedium?.copyWith(color: scheme.onSurface),
               children: [
                 const TextSpan(text: 'Any Link,\n'),
-                TextSpan(
-                  text: 'Captured.',
-                  style: TextStyle(
-                    color: scheme.primary,
-                    shadows: [
-                      Shadow(
-                        color: scheme.primary.withValues(alpha: 0.35),
-                        blurRadius: 24,
-                      ),
-                    ],
-                  ),
-                ),
+                TextSpan(text: 'Captured.', style: TextStyle(color: scheme.primary)),
               ],
             ),
           ),
@@ -308,13 +266,7 @@ class _PageStructure extends StatelessWidget {
           RichText(
             textAlign: TextAlign.center,
             text: TextSpan(
-              style: GoogleFonts.fraunces(
-                fontSize: 40,
-                fontWeight: FontWeight.w800,
-                letterSpacing: -1,
-                height: 1.1,
-                color: scheme.onSurface,
-              ),
+              style: theme.textTheme.displaySmall?.copyWith(color: scheme.onSurface),
               children: [
                 const TextSpan(text: 'Every Source,\n'),
                 TextSpan(
@@ -488,13 +440,7 @@ class _PageLibrary extends StatelessWidget {
           RichText(
             textAlign: TextAlign.center,
             text: TextSpan(
-              style: GoogleFonts.fraunces(
-                fontSize: 40,
-                fontWeight: FontWeight.w800,
-                letterSpacing: -1,
-                height: 1.1,
-                color: scheme.onSurface,
-              ),
+              style: theme.textTheme.displaySmall?.copyWith(color: scheme.onSurface),
               children: [
                 const TextSpan(text: 'Personal Web\n'),
                 TextSpan(

app/lib/ui/features/onboarding/views/splash_screen.dart

@@ -31,7 +31,7 @@ class _SplashScreenState extends State<SplashScreen>
     );
     _drop = CurvedAnimation(
       parent: _c,
-      curve: const Interval(0.0, 0.55, curve: Curves.easeOutBack),
+      curve: const Interval(0.0, 0.55, curve: Curves.easeOutCubic),
     );
     _wordmark = CurvedAnimation(
       parent: _c,

app/lib/ui/features/profile/views/profile_screen.dart

@@ -249,9 +249,16 @@ class _ProfileScreenState extends State<ProfileScreen> {
       ),
     );
     if (ok == true && mounted) {
-      ScaffoldMessenger.of(context).showSnackBar(
-        const SnackBar(content: Text('Offline cache cleared')),
-      );
+      final removed = await context.read<CardRepository>().clearCardCache();
+      if (mounted) {
+        ScaffoldMessenger.of(context).showSnackBar(
+          SnackBar(
+            content: Text(removed == 0
+                ? 'Nothing cached yet'
+                : 'Cleared $removed offline ${removed == 1 ? 'card' : 'cards'}'),
+          ),
+        );
+      }
     }
   }
 

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

@@ -561,7 +561,7 @@ class _QuizCardState extends State<_QuizCard> {
           ),
         ),
       ],
-    ).animate().fadeIn(duration: 300.ms).scaleXY(begin: 0.96, end: 1, curve: Curves.easeOutBack);
+    ).animate().fadeIn(duration: 300.ms).scaleXY(begin: 0.96, end: 1, curve: Curves.easeOutCubic);
   }
 }
 

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

@@ -764,11 +764,13 @@ class _PulsingDot extends StatelessWidget {
 
   @override
   Widget build(BuildContext context) {
-    return Container(
+    final dot = Container(
       width: 8,
       height: 8,
       decoration: BoxDecoration(color: color, shape: BoxShape.circle),
-    )
+    );
+    if (!context.motionEnabled) return dot; // reduced motion: static dot
+    return dot
         .animate(onPlay: (c) => c.repeat(reverse: true))
         .scaleXY(
           begin: 0.5,
@@ -1321,14 +1323,16 @@ class _SkeletonBox extends StatelessWidget {
   @override
   Widget build(BuildContext context) {
     final scheme = Theme.of(context).colorScheme;
-    return Container(
+    final box = Container(
       width: width,
       height: height,
       decoration: BoxDecoration(
         color: scheme.surfaceContainerHigh,
         borderRadius: BorderRadius.circular(radius),
       ),
-    )
+    );
+    if (!context.motionEnabled) return box; // reduced motion: static block
+    return box
         .animate(onPlay: (c) => c.repeat())
         .shimmer(
           duration: const Duration(milliseconds: 1200),

app/lib/ui/features/share/view_models/share_view_model.dart

@@ -64,11 +64,11 @@ class ShareViewModel extends ChangeNotifier {
     } catch (e) {
       if (e is ApiException) {
         _status = ShareStatus.failed;
-        _failureReason = e.message;
+        _failureReason = e.friendlyMessage;
       } else {
         // Network down: repository has queued the share for later.
         _status = ShareStatus.queuedOffline;
-        _error = '$e';
+        _error = friendlyError(e);
       }
       notifyListeners();
       return null;
@@ -92,7 +92,7 @@ class ShareViewModel extends ChangeNotifier {
         _safeNotify();
       },
       onError: (e) {
-        _error = '$e';
+        _error = friendlyError(e);
         _safeNotify();
       },
       cancelOnError: false,

app/lib/ui/features/share/views/share_screen.dart

@@ -133,10 +133,11 @@ class _ShareViewState extends State<_ShareView> {
             children: [
               const PhosphorIcon(PhosphorIconsRegular.cloudSlash, size: 48),
               const SizedBox(height: 14),
-              Text('Saved offline', style: theme.textTheme.titleLarge),
+              Text('Saved — will process shortly', style: theme.textTheme.titleLarge),
               const SizedBox(height: 8),
               const Text(
-                "We'll process this reel as soon as you're back online.",
+                "We'll process this as soon as Cachy is reachable — the free "
+                'server can take ~30s to wake up.',
                 textAlign: TextAlign.center,
               ),
               const SizedBox(height: 20),

app/test/api_exception_test.dart

@@ -0,0 +1,25 @@
+import 'package:flutter_test/flutter_test.dart';
+import 'package:cachy/data/services/api_client.dart';
+
+void main() {
+  test('friendly messages never leak bodies or tracebacks', () {
+    expect(ApiException(500, '{"detail":"X","traceback":"Trace..."}').friendlyMessage,
+        'Something went wrong on our side. Try again in a moment.');
+    expect(ApiException(429, '{"error":"quota"}').friendlyMessage,
+        "You've hit today's limit. It resets at midnight UTC.");
+    expect(ApiException(401, 'x').friendlyMessage,
+        'Session expired — please sign in again.');
+    expect(ApiException(404, 'x').friendlyMessage,
+        "That card isn't there anymore.");
+    for (final code in [400, 401, 404, 429, 500, 503]) {
+      final msg = ApiException(code, 'traceback secret').friendlyMessage;
+      expect(msg.contains('traceback'), isFalse);
+      expect(msg.contains('secret'), isFalse);
+    }
+  });
+
+  test('friendlyError handles non-Api exceptions', () {
+    expect(friendlyError(Exception('SocketException: conn refused')),
+        "Can't reach Cachy. Check your connection.");
+  });
+}

app/test/bulk_move_test.dart

@@ -0,0 +1,53 @@
+import 'dart:convert';
+
+import 'package:flutter_test/flutter_test.dart';
+import 'package:http/http.dart' as http;
+import 'package:http/testing.dart';
+import 'package:shared_preferences/shared_preferences.dart';
+import 'package:cachy/data/repositories/card_repository.dart';
+import 'package:cachy/data/services/api_client.dart';
+import 'package:cachy/data/services/local_store.dart';
+import 'package:cachy/ui/features/library/view_models/library_view_model.dart';
+
+/// Builds a VM over a real repo whose MockClient serves the given cards and
+/// records every move POST as cardId -> collection_id.
+Future<(LibraryViewModel, Map<String, String?>)> _vm(List<String> ids) async {
+  SharedPreferences.setMockInitialValues({});
+  final store = await LocalStore.open();
+  final moves = <String, String?>{};
+  final mock = MockClient((req) async {
+    final path = req.url.path;
+    if (path == '/cards') {
+      return http.Response(
+        jsonEncode([for (final id in ids) {'card_id': id, 'state': 'ready'}]),
+        200,
+      );
+    }
+    final move = RegExp(r'^/collections/cards/(.+)/move$').firstMatch(path);
+    if (move != null) {
+      moves[move.group(1)!] = jsonDecode(req.body)['collection_id'] as String?;
+      return http.Response('{}', 200);
+    }
+    return http.Response('[]', 200);
+  });
+  final api = ApiClient(baseUrl: 'http://x', client: mock);
+  final repo = CardRepository(api: api, store: store);
+  return (LibraryViewModel(repository: repo), moves);
+}
+
+void main() {
+  TestWidgetsFlutterBinding.ensureInitialized();
+
+  test('bulkMove moves every selected card and clears selection', () async {
+    final (vm, moves) = await _vm(['a', 'b', 'c']);
+    await vm.load();
+    vm.toggleSelection('a');
+    vm.toggleSelection('c');
+    expect(vm.selectionActive, isTrue);
+
+    await vm.bulkMove('folder-1');
+
+    expect(moves, {'a': 'folder-1', 'c': 'folder-1'});
+    expect(vm.selectionActive, isFalse);
+  });
+}

app/test/library_wakeup_test.dart

@@ -0,0 +1,52 @@
+import 'package:flutter_test/flutter_test.dart';
+import 'package:http/http.dart' as http;
+import 'package:http/testing.dart';
+import 'package:shared_preferences/shared_preferences.dart';
+import 'package:cachy/data/repositories/card_repository.dart';
+import 'package:cachy/data/services/api_client.dart';
+import 'package:cachy/data/services/local_store.dart';
+import 'package:cachy/ui/features/library/view_models/library_view_model.dart';
+
+/// Real repository driven by a MockClient that "naps" (throws) a fixed number
+/// of times before answering — exactly the sleeping-HF-Space cold start.
+Future<LibraryViewModel> _vm(int naps, {int status = 200}) async {
+  SharedPreferences.setMockInitialValues({}); // empty cache => list() rethrows
+  final store = await LocalStore.open();
+  var calls = 0;
+  final mock = MockClient((req) async {
+    calls++;
+    if (calls <= naps) {
+      if (status == 200) throw http.ClientException('nap');
+      return http.Response('waking', status);
+    }
+    return http.Response('[]', 200);
+  });
+  final api = ApiClient(baseUrl: 'http://x', client: mock);
+  final repo = CardRepository(api: api, store: store);
+  return LibraryViewModel(repository: repo, wakeRetryDelay: Duration.zero);
+}
+
+void main() {
+  TestWidgetsFlutterBinding.ensureInitialized();
+
+  test('connection nap enters waking state, then recovers', () async {
+    final vm = await _vm(2);
+    final seen = <LibraryStatus>[];
+    vm.addListener(() => seen.add(vm.status));
+    await vm.load();
+    expect(seen, contains(LibraryStatus.waking));
+    expect(vm.status, LibraryStatus.empty);
+  });
+
+  test('503 while waking is retried too', () async {
+    final vm = await _vm(2, status: 503);
+    await vm.load();
+    expect(vm.status, LibraryStatus.empty);
+  });
+
+  test('persistent failure lands on error after max attempts', () async {
+    final vm = await _vm(99);
+    await vm.load();
+    expect(vm.status, LibraryStatus.error);
+  });
+}

app/test/local_store_test.dart

@@ -0,0 +1,20 @@
+import 'package:flutter_test/flutter_test.dart';
+import 'package:shared_preferences/shared_preferences.dart';
+import 'package:cachy/data/services/local_store.dart';
+
+void main() {
+  TestWidgetsFlutterBinding.ensureInitialized();
+
+  test('clearCardCache removes all cached cards and the index', () async {
+    SharedPreferences.setMockInitialValues({});
+    final store = await LocalStore.open();
+    await store.cacheCard('c1', {'id': 'c1'});
+    await store.cacheCard('c2', {'id': 'c2'});
+    expect(store.cachedCardIds(), hasLength(2));
+
+    final removed = await store.clearCardCache();
+    expect(removed, 2);
+    expect(store.cachedCardIds(), isEmpty);
+    expect(store.readCard('c1'), isNull);
+  });
+}

app/test/reduced_motion_test.dart

@@ -0,0 +1,35 @@
+import 'package:flutter/material.dart';
+import 'package:flutter_test/flutter_test.dart';
+import 'package:cachy/ui/core/theme.dart';
+
+void main() {
+  testWidgets('motionEnabled follows MediaQuery.disableAnimations', (tester) async {
+    late bool enabled;
+    late Duration gated;
+    await tester.pumpWidget(MediaQuery(
+      data: const MediaQueryData(disableAnimations: true),
+      child: Builder(builder: (context) {
+        enabled = context.motionEnabled;
+        gated = context.gated(Motion.medium);
+        return const SizedBox();
+      }),
+    ));
+    expect(enabled, isFalse);
+    expect(gated, Duration.zero);
+  });
+
+  testWidgets('motion on by default', (tester) async {
+    late bool enabled;
+    late Duration gated;
+    await tester.pumpWidget(MediaQuery(
+      data: const MediaQueryData(),
+      child: Builder(builder: (context) {
+        enabled = context.motionEnabled;
+        gated = context.gated(Motion.medium);
+        return const SizedBox();
+      }),
+    ));
+    expect(enabled, isTrue);
+    expect(gated, Motion.medium);
+  });
+}

app/web/index.html

@@ -69,7 +69,7 @@
       stroke: #1C1917;
     }
     .glyph-reel-group {
-      animation: reelDrop 0.72s cubic-bezier(0.34, 1.56, 0.64, 1) forwards;
+      animation: reelDrop 0.72s cubic-bezier(0.22, 1, 0.36, 1) forwards;
     }
     @keyframes reelDrop {
       0% { transform: translateY(-44px); }

docs/planning/plans/2026-07-10-backend-auth-quotas.md

@@ -0,0 +1,790 @@
+# Backend Auth + Quotas + Hardening Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Replace the spoofable `x-owner-id` header with verified Firebase ID tokens, add per-user/per-IP daily quotas with degrade-to-fallback, and lock down admin/debug/error surfaces.
+
+**Architecture:** A FastAPI dependency `get_owner` verifies the bearer token via `firebase_admin.auth.verify_id_token` and yields the uid; every route swaps its header param for this dependency. Quotas live in a new `usage` table keyed `(owner_id, day, kind)`; past-quota card creation flags the job `degraded` so the worker takes the existing paragraph-fallback path instead of failing. A temporary `/auth/claim` migrates legacy name-keyed rows.
+
+**Tech Stack:** FastAPI, SQLAlchemy async + aiosqlite, firebase-admin, pytest + pytest-asyncio + httpx.
+
+## Global Constraints
+
+- Spec: `docs/superpowers/specs/2026-07-10-public-distribution-auth-quotas-design.md`.
+- Python style: type hints + docstrings on every function; explicit error handling (no `except: pass`); `pathlib.Path`; config only via `app.config.Settings` (pydantic-settings, `.env`).
+- Quota defaults (env-overridable): cards 10/day, chat 30/day, connections-refresh 3/day, per-IP cards 30/day.
+- `x-owner-id` header support is removed entirely; legacy name survives only as `/auth/claim`'s body parameter.
+- Every external dependency optional / graceful degradation preserved: if `FIREBASE_PROJECT_ID` is unset, `get_owner` must raise 503 with "auth not configured" (never crash at import).
+- Run tests with `cd backend && .venv/bin/pytest` after every task.
+- Do not commit unless the user asked; each task's Commit step is conditional on that standing permission being granted at execution time.
+
+---
+
+### Task 1: Restore the pytest harness
+
+**Files:**
+- Create: `backend/tests/__init__.py` (empty)
+- Create: `backend/tests/conftest.py`
+- Create: `backend/tests/test_health.py`
+
+**Interfaces:**
+- Produces: `client` async fixture (httpx.AsyncClient against the app, fresh in-memory-style temp SQLite per test) used by every later test.
+
+- [ ] **Step 1: Write conftest**
+
+```python
+"""Shared fixtures: temp-file SQLite DB + httpx client bound to the app.
+
+The worker loop is not started (tests drive functions directly); lifespan is
+bypassed by calling db.init_db() ourselves against a temp database file.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import AsyncIterator
+from pathlib import Path
+
+import pytest
+import pytest_asyncio
+from httpx import ASGITransport, AsyncClient
+
+
+@pytest_asyncio.fixture
+async def client(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> AsyncIterator[AsyncClient]:
+    """App-bound HTTP client with an isolated database per test."""
+    db_path = tmp_path / "test.db"
+    monkeypatch.setenv("DATABASE_URL", f"sqlite+aiosqlite:///{db_path}")
+    # Settings and the engine are cached at import; reset both.
+    from app import config
+    config.get_settings.cache_clear()
+    from app.store import db as store_db
+    await store_db.dispose_db()
+    store_db.reset_engine()  # added in Step 2 if absent
+    await store_db.init_db()
+
+    from app.main import app
+    transport = ASGITransport(app=app)
+    async with AsyncClient(transport=transport, base_url="http://test") as c:
+        yield c
+    await store_db.dispose_db()
+```
+
+- [ ] **Step 2: Ensure `reset_engine` exists in `backend/app/store/db.py`**
+
+Read `db.py`'s engine setup. If the engine/sessionmaker are module-level singletons built from `get_settings().database_url` at import, add:
+
+```python
+def reset_engine() -> None:
+    """Rebuild the engine/sessionmaker from current settings (tests swap DATABASE_URL)."""
+    global _engine, _session_factory
+    _engine = create_async_engine(get_settings().database_url, future=True)
+    _session_factory = async_sessionmaker(_engine, expire_on_commit=False)
+```
+
+Match the actual variable names used in `db.py` (`_engine` / `_session_factory` may differ — mirror what `dispose_db()` touches).
+
+- [ ] **Step 3: Write the smoke test**
+
+```python
+"""Harness smoke test: the app answers /health on an isolated DB."""
+
+import pytest
+
+
+@pytest.mark.asyncio
+async def test_health(client) -> None:
+    resp = await client.get("/health")
+    assert resp.status_code == 200
+    assert resp.json()["status"] == "ok"
+```
+
+- [ ] **Step 4: Run**
+
+Run: `cd backend && .venv/bin/pytest tests/test_health.py -v` — Expected: PASS. If `pytest-asyncio` mode errors appear, add to `backend/pyproject.toml` under `[tool.pytest.ini_options]`: `asyncio_mode = "auto"` (then the `@pytest.mark.asyncio` markers are optional but harmless).
+
+- [ ] **Step 5: Commit** — `test: restore pytest harness with isolated per-test DB`
+
+---
+
+### Task 2: `get_owner` — Firebase token verification dependency
+
+**Files:**
+- Modify: `backend/pyproject.toml` (add `"firebase-admin>=6.5"` to dependencies)
+- Modify: `backend/app/config.py` (add `firebase_project_id: str = ""`)
+- Create: `backend/app/auth.py`
+- Create: `backend/tests/test_auth.py`
+
+**Interfaces:**
+- Produces: `async def get_owner(authorization: str | None = Header(None)) -> str` — FastAPI dependency returning the verified uid; raises HTTPException 401 (missing/invalid token) or 503 (auth unconfigured). Also `OwnerDep = Annotated[str, Depends(get_owner)]` for route signatures.
+
+- [ ] **Step 1: Write failing tests**
+
+```python
+"""get_owner: valid token -> uid; garbage/missing -> 401; unconfigured -> 503."""
+
+from unittest.mock import patch
+
+import pytest
+from fastapi import HTTPException
+
+from app.auth import get_owner
+
+
+@pytest.mark.asyncio
+async def test_missing_header_401() -> None:
+    with pytest.raises(HTTPException) as exc:
+        await get_owner(authorization=None)
+    assert exc.value.status_code == 401
+
+
+@pytest.mark.asyncio
+async def test_valid_token_returns_uid(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("FIREBASE_PROJECT_ID", "demo-project")
+    from app import config
+    config.get_settings.cache_clear()
+    with patch("app.auth._verify", return_value={"uid": "user-123"}):
+        uid = await get_owner(authorization="Bearer sometoken")
+    assert uid == "user-123"
+
+
+@pytest.mark.asyncio
+async def test_invalid_token_401(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("FIREBASE_PROJECT_ID", "demo-project")
+    from app import config
+    config.get_settings.cache_clear()
+    with patch("app.auth._verify", side_effect=ValueError("bad token")):
+        with pytest.raises(HTTPException) as exc:
+            await get_owner(authorization="Bearer garbage")
+    assert exc.value.status_code == 401
+
+
+@pytest.mark.asyncio
+async def test_unconfigured_503(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.delenv("FIREBASE_PROJECT_ID", raising=False)
+    from app import config
+    config.get_settings.cache_clear()
+    with pytest.raises(HTTPException) as exc:
+        await get_owner(authorization="Bearer sometoken")
+    assert exc.value.status_code == 503
+```
+
+- [ ] **Step 2: Run to verify failure** — `cd backend && .venv/bin/pytest tests/test_auth.py -v` — Expected: FAIL, `ModuleNotFoundError: app.auth`.
+
+- [ ] **Step 3: Implement `backend/app/auth.py`**
+
+```python
+"""Verified identity: Firebase ID token -> uid.
+
+The client sends `Authorization: Bearer <ID token>`; we verify the signature
+against Google's public certs (firebase-admin handles fetching/rotation).
+No service-account secret is needed for verification — only the project id.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Annotated
+
+from fastapi import Depends, Header, HTTPException
+
+from app.config import get_settings
+
+log = logging.getLogger("app.auth")
+
+_initialized = False
+
+
+def _verify(token: str) -> dict:
+    """Verify a Firebase ID token, initializing the SDK lazily (once)."""
+    global _initialized
+    import firebase_admin
+    from firebase_admin import auth as fb_auth
+
+    if not _initialized:
+        firebase_admin.initialize_app(
+            options={"projectId": get_settings().firebase_project_id}
+        )
+        _initialized = True
+    return fb_auth.verify_id_token(token)
+
+
+async def get_owner(authorization: str | None = Header(None)) -> str:
+    """FastAPI dependency: the verified Firebase uid of the caller."""
+    if not get_settings().firebase_project_id:
+        raise HTTPException(status_code=503, detail="auth not configured")
+    if not authorization or not authorization.startswith("Bearer "):
+        raise HTTPException(status_code=401, detail="missing bearer token")
+    token = authorization.removeprefix("Bearer ").strip()
+    try:
+        decoded = _verify(token)
+    except Exception as exc:  # firebase raises several exc types; all mean 401
+        log.info("token verification failed: %s: %s", type(exc).__name__, exc)
+        raise HTTPException(status_code=401, detail="invalid or expired token")
+    return str(decoded["uid"])
+
+
+OwnerDep = Annotated[str, Depends(get_owner)]
+```
+
+Add to `backend/app/config.py` inside `Settings` (near the storage block):
+
+```python
+    # auth — Firebase project id; token verification needs no secret.
+    firebase_project_id: str = ""
+```
+
+Add `"firebase-admin>=6.5",` to `dependencies` in `backend/pyproject.toml`, then `cd backend && .venv/bin/pip install -e .`.
+
+- [ ] **Step 4: Run** — `cd backend && .venv/bin/pytest tests/test_auth.py -v` — Expected: 4 PASS.
+
+- [ ] **Step 5: Commit** — `feat: verified Firebase identity dependency (get_owner)`
+
+---
+
+### Task 3: Swap every `x_owner_id` header for `OwnerDep`
+
+**Files:**
+- Modify: `backend/app/api/cards.py`, `catalog.py`, `collections.py`, `concepts.py`, `connections.py`, `feed.py`, `graph.py`, `library_chat.py`, `search.py` (≈56 sites)
+- Create: `backend/tests/test_auth_routes.py`
+
+**Interfaces:**
+- Consumes: `OwnerDep` from Task 2.
+- Produces: every data route requires auth; tests override `get_owner` via `app.dependency_overrides` (this is also the pattern all later route tests use).
+
+- [ ] **Step 1: Write failing tests**
+
+```python
+"""Routes reject anonymous callers and scope rows to the verified uid."""
+
+import pytest
+
+from app.auth import get_owner
+from app.main import app
+
+
+@pytest.mark.asyncio
+async def test_cards_requires_auth(client) -> None:
+    resp = await client.get("/cards")
+    # 401 (bad token) or 503 (auth unconfigured in test env) — never 200.
+    assert resp.status_code in (401, 503)
+
+
+@pytest.mark.asyncio
+async def test_owner_scoping(client) -> None:
+    app.dependency_overrides[get_owner] = lambda: "uid-a"
+    try:
+        created = await client.post("/cards", json={"url": "https://example.com/a"})
+        assert created.status_code in (200, 201)
+        mine = await client.get("/cards")
+        assert mine.status_code == 200
+
+        app.dependency_overrides[get_owner] = lambda: "uid-b"
+        theirs = await client.get("/cards")
+        assert theirs.status_code == 200
+        assert theirs.json() == []  # uid-b sees nothing of uid-a's
+    finally:
+        app.dependency_overrides.clear()
+```
+
+- [ ] **Step 2: Run to verify failure** — `cd backend && .venv/bin/pytest tests/test_auth_routes.py -v` — Expected: `test_cards_requires_auth` FAILS (anonymous GET /cards currently returns 200).
+
+- [ ] **Step 3: Mechanical swap in all 9 API modules**
+
+In each file: add `from app.auth import OwnerDep`; replace every parameter
+`x_owner_id: Annotated[str | None, Header()] = None` with `owner_id: OwnerDep`
+and every body use of `x_owner_id` with `owner_id`. Delete now-unused `Header` imports. Where routes special-cased `owner_id is None` (e.g. `cards.py:241`), the branch is dead — owner is always set now; remove the conditional and always filter by owner. Grep afterwards: `grep -rn "x_owner_id" backend/app` must return nothing.
+
+The SSE stream route (`/cards/{id}/stream`) gets the same `OwnerDep`.
+
+- [ ] **Step 4: Run full suite** — `cd backend && .venv/bin/pytest -v` — Expected: all PASS.
+
+- [ ] **Step 5: Commit** — `feat: all data routes require verified owner identity`
+
+---
+
+### Task 4: Usage table + quota dependency
+
+**Files:**
+- Modify: `backend/app/store/db.py` (UsageRow + helpers; add `degraded` to JobRow; add both columns to the lightweight migration map near line 383)
+- Modify: `backend/app/config.py` (quota settings)
+- Create: `backend/app/quota.py`
+- Create: `backend/tests/test_quota.py`
+
+**Interfaces:**
+- Produces:
+  - `db.UsageRow` (`owner_id: str, day: str, kind: str, count: int`, PK = first three)
+  - `async def db.spend_usage(session, *, owner_id: str, kind: str, limit: int) -> tuple[bool, int]` — atomically increments and returns `(allowed, used_after)`; increments even when over limit is NOT performed (count stays at limit).
+  - `quota.spend(kind: str, limit_attr: str)` — dependency factory raising 429 `{"error": "quota", "kind": ..., "used": ..., "limit": ..., "resets_at": ...}`.
+  - `quota.card_budget(owner_id, request, session) -> bool` — non-raising check for card creation (True = within quota, False = degrade), which also enforces the per-IP cap (raising 429 only for the IP cap).
+  - `JobRow.degraded: bool` column.
+
+- [ ] **Step 1: Write failing tests**
+
+```python
+"""Quota accounting: daily counters, limits, per-IP cap, UTC rollover."""
+
+import pytest
+
+from app.store import db
+
+
+@pytest.mark.asyncio
+async def test_spend_usage_counts_and_caps(client) -> None:  # client fixture builds the DB
+    async with db.session() as s:
+        for i in range(3):
+            allowed, used = await db.spend_usage(s, owner_id="u1", kind="chat", limit=3)
+            assert allowed and used == i + 1
+        allowed, used = await db.spend_usage(s, owner_id="u1", kind="chat", limit=3)
+        assert not allowed and used == 3
+
+
+@pytest.mark.asyncio
+async def test_usage_is_per_owner_and_per_kind(client) -> None:
+    async with db.session() as s:
+        await db.spend_usage(s, owner_id="u1", kind="chat", limit=3)
+        allowed, used = await db.spend_usage(s, owner_id="u2", kind="chat", limit=3)
+        assert allowed and used == 1
+        allowed, used = await db.spend_usage(s, owner_id="u1", kind="cards", limit=3)
+        assert allowed and used == 1
+```
+
+- [ ] **Step 2: Run to verify failure** — Expected: FAIL, `spend_usage` not defined.
+
+- [ ] **Step 3: Implement**
+
+`db.py` additions:
+
+```python
+class UsageRow(Base):
+    """Daily metered usage. One row per (owner, UTC day, kind); owner_id also
+    stores "ip:<addr>" rows for the anonymous-farming IP cap."""
+
+    __tablename__ = "usage"
+
+    owner_id: Mapped[str] = mapped_column(String, primary_key=True)
+    day: Mapped[str] = mapped_column(String, primary_key=True)  # "YYYY-MM-DD" UTC
+    kind: Mapped[str] = mapped_column(String, primary_key=True)
+    count: Mapped[int] = mapped_column(Integer, default=0)
+
+
+def _today() -> str:
+    """Current UTC day key."""
+    return datetime.now(timezone.utc).strftime("%Y-%m-%d")
+
+
+async def spend_usage(
+    db_session: AsyncSession, *, owner_id: str, kind: str, limit: int
+) -> tuple[bool, int]:
+    """Increment today's counter unless at limit. Returns (allowed, used_after)."""
+    day = _today()
+    row = await db_session.get(UsageRow, (owner_id, day, kind))
+    if row is None:
+        row = UsageRow(owner_id=owner_id, day=day, kind=kind, count=0)
+        db_session.add(row)
+    if row.count >= limit:
+        return False, row.count
+    row.count += 1
+    await db_session.commit()
+    return True, row.count
+```
+
+`JobRow` gains `degraded: Mapped[bool] = mapped_column(Boolean, default=False)`; add `"degraded": "BOOLEAN DEFAULT 0"` to the jobs entry of the additive-migration map (the dict near db.py:383 that backfills missing columns).
+
+`config.py` additions:
+
+```python
+    # quotas (per UTC day)
+    quota_cards_per_day: int = 10
+    quota_chat_per_day: int = 30
+    quota_connections_refresh_per_day: int = 3
+    quota_ip_cards_per_day: int = 30
+```
+
+`backend/app/quota.py`:
+
+```python
+"""Per-user daily quotas. Chat-style routes raise 429; card creation degrades
+instead (see cards.py) so a save never hard-fails."""
+
+from __future__ import annotations
+
+from datetime import datetime, time, timezone
+
+from fastapi import Depends, HTTPException, Request
+
+from app.auth import get_owner
+from app.config import get_settings
+from app.store import db
+
+
+def _resets_at() -> str:
+    """ISO timestamp of the next UTC midnight (quota reset)."""
+    now = datetime.now(timezone.utc)
+    tomorrow = datetime.combine(now.date(), time.min, tzinfo=timezone.utc)
+    return tomorrow.replace(day=now.day).isoformat()  # replaced in Step 3b
+
+
+def spend(kind: str, limit_attr: str):
+    """Dependency factory: spend one unit of `kind` or raise 429."""
+
+    async def _dep(owner_id: str = Depends(get_owner)) -> str:
+        limit = getattr(get_settings(), limit_attr)
+        async with db.session() as s:
+            allowed, used = await db.spend_usage(
+                s, owner_id=owner_id, kind=kind, limit=limit
+            )
+        if not allowed:
+            raise HTTPException(
+                status_code=429,
+                detail={
+                    "error": "quota", "kind": kind,
+                    "used": used, "limit": limit, "resets_at": _resets_at(),
+                },
+            )
+        return owner_id
+
+    return _dep
+
+
+async def card_budget(owner_id: str, request: Request) -> bool:
+    """Card-creation budget. Enforces the per-IP cap (429) and returns whether
+    the owner still has AI budget today (False -> degrade, never fail)."""
+    settings = get_settings()
+    ip = request.client.host if request.client else "unknown"
+    async with db.session() as s:
+        ip_ok, _ = await db.spend_usage(
+            s, owner_id=f"ip:{ip}", kind="cards", limit=settings.quota_ip_cards_per_day
+        )
+        if not ip_ok:
+            raise HTTPException(status_code=429, detail={
+                "error": "quota", "kind": "ip", "limit": settings.quota_ip_cards_per_day,
+                "used": settings.quota_ip_cards_per_day, "resets_at": _resets_at(),
+            })
+        allowed, _ = await db.spend_usage(
+            s, owner_id=owner_id, kind="cards", limit=settings.quota_cards_per_day
+        )
+    return allowed
+```
+
+- [ ] **Step 3b: Fix `_resets_at`** — the naive `.replace(day=...)` is wrong at month end. Use:
+
+```python
+from datetime import timedelta
+
+def _resets_at() -> str:
+    now = datetime.now(timezone.utc)
+    tomorrow = datetime.combine(now.date() + timedelta(days=1), time.min, tzinfo=timezone.utc)
+    return tomorrow.isoformat()
+```
+
+- [ ] **Step 4: Run** — `cd backend && .venv/bin/pytest tests/test_quota.py -v` — Expected: PASS.
+
+- [ ] **Step 5: Commit** — `feat: usage table + daily quota accounting`
+
+---
+
+### Task 5: Wire quotas into routes; degrade card creation
+
+**Files:**
+- Modify: `backend/app/api/cards.py` (create route + chat + rabbithole), `backend/app/api/library_chat.py`, `backend/app/api/connections.py`
+- Modify: `backend/app/pipeline/worker.py` + `backend/app/pipeline/structuring.py` (degraded path)
+- Create: `backend/app/api/me.py` (`GET /me/quota`), register in `main.py`
+- Create: `backend/tests/test_quota_routes.py`
+
+**Interfaces:**
+- Consumes: `quota.spend`, `quota.card_budget`, `JobRow.degraded` from Task 4.
+- Produces: `structure(bundle, transcript, caption, force_fallback: bool = False)` — when True returns `_paragraph_fallback(...)` immediately, with `degraded=True, degraded_reason="quota"`. `GET /me/quota` → `{"cards": {"used": n, "limit": n}, "chat": {...}, "resets_at": iso}`.
+
+- [ ] **Step 1: Write failing tests**
+
+```python
+"""Quota wiring: chat 429s past limit; card creation degrades; /me/quota reports."""
+
+import pytest
+
+from app.auth import get_owner
+from app.main import app
+from app.store import db
+
+
+@pytest.fixture(autouse=True)
+def _small_limits(monkeypatch):
+    monkeypatch.setenv("QUOTA_CARDS_PER_DAY", "1")
+    monkeypatch.setenv("QUOTA_CHAT_PER_DAY", "1")
+    from app import config
+    config.get_settings.cache_clear()
+    yield
+    config.get_settings.cache_clear()
+
+
+@pytest.fixture
+def as_user():
+    app.dependency_overrides[get_owner] = lambda: "uid-q"
+    yield
+    app.dependency_overrides.clear()
+
+
+@pytest.mark.asyncio
+async def test_card_creation_degrades_past_quota(client, as_user) -> None:
+    r1 = await client.post("/cards", json={"url": "https://example.com/1"})
+    assert r1.status_code in (200, 201)
+    r2 = await client.post("/cards", json={"url": "https://example.com/2"})
+    assert r2.status_code in (200, 201)  # degrade, never fail
+    async with db.session() as s:
+        jobs = (await s.execute(db.select(db.JobRow).order_by(db.JobRow.created_at))).scalars().all()
+    assert [j.degraded for j in jobs] == [False, True]
+
+
+@pytest.mark.asyncio
+async def test_me_quota(client, as_user) -> None:
+    resp = await client.get("/me/quota")
+    assert resp.status_code == 200
+    body = resp.json()
+    assert body["cards"]["limit"] == 1 and "resets_at" in body
+```
+
+(If `db.select` isn't re-exported, import `select` from sqlalchemy in the test.)
+
+- [ ] **Step 2: Run to verify failure** — Expected: FAIL (`degraded` never True; /me/quota 404).
+
+- [ ] **Step 3: Implement**
+
+`cards.py` create route: add `request: Request` param; after resolving the cache-miss path and before creating the JobRow, call `within = await quota.card_budget(owner_id, request)`; create the job with `degraded=not within`; include `"quota_degraded": not within` in the response body.
+
+Chat routes: append `dependencies=[Depends(quota.spend("chat", "quota_chat_per_day"))]` to the route decorators of card chat, rabbithole (in `cards.py`) and library chat (`library_chat.py`). Connections refresh: inside the handler, only when `refresh=True`, call the spend dependency logic directly:
+
+```python
+if refresh:
+    await quota.spend("connections_refresh", "quota_connections_refresh_per_day")(owner_id)
+```
+
+`structuring.py`: change signature to `def structure(bundle: str, transcript: str = "", caption: str = "", force_fallback: bool = False) -> "StructuredCard":` and as the first statement:
+
+```python
+    if force_fallback:
+        log.info("structuring: quota-degraded card -> paragraph fallback")
+        return _paragraph_fallback(bundle, transcript, caption, reason="quota")
+```
+
+Match `_paragraph_fallback`'s real signature (read it first; pass whatever it actually takes, setting `degraded_reason="quota"` however the non-forced fallback path does).
+
+`worker.py` `_run_job`: where `structure(...)` is called, pass `force_fallback=job.degraded`.
+
+`me.py`:
+
+```python
+"""The caller's own quota status — powers the profile meter."""
+
+from __future__ import annotations
+
+from fastapi import APIRouter
+
+from app.auth import OwnerDep
+from app.config import get_settings
+from app.quota import _resets_at
+from app.store import db
+
+router = APIRouter(prefix="/me", tags=["me"])
+
+
+@router.get("/quota")
+async def my_quota(owner_id: OwnerDep) -> dict:
+    """Today's used/limit per metered kind."""
+    settings = get_settings()
+    day = db._today()
+    out: dict = {"resets_at": _resets_at()}
+    async with db.session() as s:
+        for kind, limit in (
+            ("cards", settings.quota_cards_per_day),
+            ("chat", settings.quota_chat_per_day),
+        ):
+            row = await s.get(db.UsageRow, (owner_id, day, kind))
+            out[kind] = {"used": row.count if row else 0, "limit": limit}
+    return out
+```
+
+Register in `main.py`: `from app.api import me` + `app.include_router(me.router)`.
+
+- [ ] **Step 4: Run full suite** — `cd backend && .venv/bin/pytest -v` — Expected: all PASS.
+
+- [ ] **Step 5: Commit** — `feat: quotas wired — chat 429s, cards degrade, /me/quota`
+
+---
+
+### Task 6: `/auth/claim` — legacy name migration
+
+**Files:**
+- Modify: `backend/app/store/db.py` (ClaimRow + `claim_owner` helper)
+- Create: `backend/app/api/auth_routes.py`, register in `main.py`
+- Create: `backend/tests/test_claim.py`
+
+**Interfaces:**
+- Produces: `POST /auth/claim {"name": str}` → 200 `{"claimed": <row count>}` or 409 if the name was already claimed. `db.claim_owner(session, *, name: str, uid: str) -> int | None` (None = already claimed by someone else).
+
+- [ ] **Step 1: Write failing tests**
+
+```python
+"""First-claim-wins migration of legacy name-keyed rows."""
+
+import pytest
+
+from app.auth import get_owner
+from app.main import app
+from app.store import db
+
+
+async def _seed_legacy_card(name: str) -> None:
+    async with db.session() as s:
+        s.add(db.CardRow(owner_id=name, url=f"https://example.com/{name}", state="ready"))
+        await s.commit()
+
+
+@pytest.mark.asyncio
+async def test_claim_repoints_rows(client) -> None:
+    await _seed_legacy_card("Vatsal")
+    app.dependency_overrides[get_owner] = lambda: "uid-new"
+    try:
+        resp = await client.post("/auth/claim", json={"name": "Vatsal"})
+        assert resp.status_code == 200 and resp.json()["claimed"] >= 1
+        again = await client.post("/auth/claim", json={"name": "Vatsal"})
+        assert again.status_code == 200  # same uid re-claiming is a no-op success
+        app.dependency_overrides[get_owner] = lambda: "uid-thief"
+        stolen = await client.post("/auth/claim", json={"name": "Vatsal"})
+        assert stolen.status_code == 409
+    finally:
+        app.dependency_overrides.clear()
+```
+
+Adjust `_seed_legacy_card` to CardRow's actual required columns (read the model; fill mandatory fields minimally).
+
+- [ ] **Step 2: Run to verify failure** — Expected: 404 on /auth/claim.
+
+- [ ] **Step 3: Implement**
+
+`db.py`:
+
+```python
+class ClaimRow(Base):
+    """Legacy display-name -> uid claims; first claim wins."""
+
+    __tablename__ = "claims"
+
+    name: Mapped[str] = mapped_column(String, primary_key=True)
+    uid: Mapped[str] = mapped_column(String, nullable=False)
+
+
+async def claim_owner(db_session: AsyncSession, *, name: str, uid: str) -> int | None:
+    """Re-point every legacy row owned by `name` to `uid`. None = taken."""
+    existing = await db_session.get(ClaimRow, name)
+    if existing is not None:
+        return 0 if existing.uid == uid else None
+    db_session.add(ClaimRow(name=name, uid=uid))
+    total = 0
+    for model in (CardRow, CollectionRow, ConversationRow, ConnectionRow):
+        res = await db_session.execute(
+            update(model).where(model.owner_id == name).values(owner_id=uid)
+        )
+        total += res.rowcount or 0
+    await db_session.commit()
+    return total
+```
+
+`auth_routes.py`:
+
+```python
+"""Temporary migration endpoint (delete ~1 month after auth ships)."""
+
+from __future__ import annotations
+
+from fastapi import APIRouter, HTTPException
+from pydantic import BaseModel
+
+from app.auth import OwnerDep
+from app.store import db
+
+router = APIRouter(prefix="/auth", tags=["auth"])
+
+
+class ClaimRequest(BaseModel):
+    name: str
+
+
+@router.post("/claim")
+async def claim(req: ClaimRequest, owner_id: OwnerDep) -> dict:
+    """Adopt legacy rows keyed by the pre-auth display name. First claim wins."""
+    name = req.name.strip()
+    if not name:
+        raise HTTPException(status_code=422, detail="name required")
+    async with db.session() as s:
+        claimed = await db.claim_owner(s, name=name, uid=owner_id)
+    if claimed is None:
+        raise HTTPException(status_code=409, detail="name already claimed")
+    return {"claimed": claimed}
+```
+
+- [ ] **Step 4: Run** — `cd backend && .venv/bin/pytest tests/test_claim.py -v` — Expected: PASS.
+
+- [ ] **Step 5: Commit** — `feat: /auth/claim legacy library migration (first-claim-wins)`
+
+---
+
+### Task 7: Hardening — admin token, clean 500s, CORS
+
+**Files:**
+- Modify: `backend/app/main.py`, `backend/app/config.py`
+- Create: `backend/tests/test_hardening.py`
+
+**Interfaces:**
+- Consumes: nothing new. Produces: `Settings.admin_token: str = ""`, `Settings.cors_origins: str = ""` (comma-separated).
+
+- [ ] **Step 1: Write failing tests**
+
+```python
+"""Admin/debug gated; 500s never leak tracebacks."""
+
+import pytest
+
+
+@pytest.mark.asyncio
+async def test_admin_requires_token(client, monkeypatch) -> None:
+    monkeypatch.setenv("ADMIN_TOKEN", "s3cret")
+    from app import config
+    config.get_settings.cache_clear()
+    assert (await client.get("/admin/stats")).status_code == 401
+    assert (await client.get("/debug/jobs")).status_code == 401
+    ok = await client.get("/admin/stats", headers={"x-admin-token": "s3cret"})
+    assert ok.status_code == 200
+
+
+@pytest.mark.asyncio
+async def test_admin_disabled_when_unset(client, monkeypatch) -> None:
+    monkeypatch.delenv("ADMIN_TOKEN", raising=False)
+    from app import config
+    config.get_settings.cache_clear()
+    assert (await client.get("/debug/jobs")).status_code == 401
+```
+
+- [ ] **Step 2: Run to verify failure** — Expected: FAIL (currently 200 without token).
+
+- [ ] **Step 3: Implement**
+
+`config.py`: add `admin_token: str = ""` and `cors_origins: str = ""`.
+
+`main.py`:
+
+```python
+from fastapi import Depends, Header, HTTPException
+
+async def require_admin(x_admin_token: str | None = Header(None)) -> None:
+    """Gate for owner-only endpoints; unset ADMIN_TOKEN disables them entirely."""
+    expected = get_settings().admin_token
+    if not expected or x_admin_token != expected:
+        raise HTTPException(status_code=401, detail="admin token required")
+```
+
+Add `dependencies=[Depends(require_admin)]` to the `/admin/stats`, `/debug/jobs`, `/debug/kill_stuck` decorators. Replace the 500 handler body: keep the full-traceback `log.error`, return only `{"detail": "internal error"}` (no exception text, no traceback). CORS: `allow_origins=[o.strip() for o in get_settings().cors_origins.split(",") if o.strip()] or ["http://localhost:8000"]` — set the real Space origin via env in deployment. Import `get_settings` from `app.config` at top of main.py.
+
+- [ ] **Step 4: Run full suite** — `cd backend && .venv/bin/pytest -v` — Expected: all PASS. Also verify: `grep -rn "traceback" backend/app/main.py` shows logging only, not response content.
+
+- [ ] **Step 5: Commit** — `feat: admin token gate, clean 500s, restricted CORS`

docs/planning/plans/2026-07-10-flutter-auth.md

@@ -0,0 +1,625 @@
+# Flutter Auth Integration Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Firebase identity in the app — anonymous sign-in after onboarding+name, optional Google login screen ("Or use without login…"), bearer-token transport, real sign-out, quota meter, and legacy-library claim.
+
+**Architecture:** An `AuthService` wraps FirebaseAuth (anonymous start, Google link/sign-in, token access). `ApiClient` gains a token provider injected at construction and attaches `Authorization: Bearer` to every request with one 401-retry-after-refresh. `RootGate` gains a login step between onboarding/name and the shell. Profile gets an account section + quota meter.
+
+**Tech Stack:** Flutter, firebase_core, firebase_auth, google_sign_in, provider, flutter_test with mocked services (no Firebase in unit tests).
+
+## Global Constraints
+
+- Spec: `docs/superpowers/specs/2026-07-10-public-distribution-auth-quotas-design.md`. Backend plan (`2026-07-10-backend-auth-quotas.md`) must be deployed for end-to-end flows; unit tests here never hit the network.
+- Login screen comes AFTER onboarding + name screen. Primary: "Continue with Google". Below, small quiet text: "Or use without login…". The typed name stays the greeting; uid is identity.
+- Anonymous users see a persistent profile banner: "Your library isn't backed up — sign in with Google", plus warning copy that data may be lost.
+- Dart style: provider/ChangeNotifier, business logic outside widgets, strict null safety, brand tokens from `brand.dart`/`theme.dart`.
+- Run `cd app && flutter test` after every task; `flutter analyze` must stay clean.
+- The user's standing rule: no commits unless asked in-session; Commit steps are conditional on that permission.
+
+**One-time owner setup (NOT part of this plan; do first, manually):** create Firebase project → enable Anonymous + Google providers → `flutterfire configure` (writes `app/lib/firebase_options.dart` + `app/android/app/google-services.json`) → register release SHA-1 → set `FIREBASE_PROJECT_ID` on the HF Space. Tasks below assume `firebase_options.dart` exists.
+
+---
+
+### Task 1: AuthService — testable Firebase wrapper
+
+**Files:**
+- Modify: `app/pubspec.yaml` (add `firebase_core: ^3.6.0`, `firebase_auth: ^5.3.1`, `google_sign_in: ^6.2.1`)
+- Create: `app/lib/data/services/auth_service.dart`
+- Create: `app/test/auth_service_test.dart`
+- Modify: `app/lib/main.dart` (Firebase.initializeApp before runApp)
+
+**Interfaces:**
+- Produces:
+
+```dart
+/// Wraps FirebaseAuth so the rest of the app never imports firebase directly
+/// (and tests can fake it).
+abstract class AuthService {
+  Stream<AuthUser?> get userChanges;
+  AuthUser? get currentUser;
+  Future<AuthUser> signInAnonymously();
+  Future<AuthUser> signInWithGoogle();   // links when currently anonymous
+  Future<String?> idToken({bool forceRefresh = false});
+  Future<void> signOut();
+}
+
+class AuthUser {
+  const AuthUser({required this.uid, required this.isAnonymous, this.email, this.displayName, this.photoUrl});
+  final String uid;
+  final bool isAnonymous;
+  final String? email;
+  final String? displayName;
+  final String? photoUrl;
+}
+```
+
+- [ ] **Step 1: Write the failing test** (against a `FakeAuthService` used by all later tests, plus the linking contract)
+
+```dart
+import 'dart:async';
+
+import 'package:flutter_test/flutter_test.dart';
+import 'package:cachy/data/services/auth_service.dart';
+
+/// Deterministic in-memory AuthService for widget/unit tests.
+class FakeAuthService implements AuthService {
+  AuthUser? _user;
+  final _controller = StreamController<AuthUser?>.broadcast();
+  String tokenValue = 'fake-token';
+
+  @override
+  Stream<AuthUser?> get userChanges => _controller.stream;
+  @override
+  AuthUser? get currentUser => _user;
+
+  @override
+  Future<AuthUser> signInAnonymously() async {
+    _user = const AuthUser(uid: 'anon-1', isAnonymous: true);
+    _controller.add(_user);
+    return _user!;
+  }
+
+  @override
+  Future<AuthUser> signInWithGoogle() async {
+    // Linking keeps the uid when the current user is anonymous.
+    final uid = _user?.isAnonymous == true ? _user!.uid : 'google-1';
+    _user = AuthUser(uid: uid, isAnonymous: false, email: 'a@b.c', displayName: 'A');
+    _controller.add(_user);
+    return _user!;
+  }
+
+  @override
+  Future<String?> idToken({bool forceRefresh = false}) async =>
+      _user == null ? null : tokenValue;
+
+  @override
+  Future<void> signOut() async {
+    _user = null;
+    _controller.add(null);
+  }
+}
+
+void main() {
+  test('google sign-in after anonymous keeps the uid (link semantics)', () async {
+    final auth = FakeAuthService();
+    final anon = await auth.signInAnonymously();
+    final linked = await auth.signInWithGoogle();
+    expect(linked.uid, anon.uid);
+    expect(linked.isAnonymous, isFalse);
+  });
+
+  test('no token when signed out', () async {
+    final auth = FakeAuthService();
+    expect(await auth.idToken(), isNull);
+    await auth.signInAnonymously();
+    expect(await auth.idToken(), 'fake-token');
+  });
+}
+```
+
+Save `FakeAuthService` in the test file now; Task 3 moves it to `app/test/fakes.dart` for reuse.
+
+- [ ] **Step 2: Run to verify failure** — `cd app && flutter test test/auth_service_test.dart` — Expected: FAIL, `auth_service.dart` missing.
+
+- [ ] **Step 3: Implement `auth_service.dart`**
+
+```dart
+/// Identity layer: Firebase anonymous-first with optional Google upgrade.
+/// The uid is the backend `owner_id`; linking preserves it so no data moves.
+library;
+
+import 'package:firebase_auth/firebase_auth.dart' as fb;
+import 'package:google_sign_in/google_sign_in.dart';
+
+class AuthUser {
+  const AuthUser({
+    required this.uid,
+    required this.isAnonymous,
+    this.email,
+    this.displayName,
+    this.photoUrl,
+  });
+  final String uid;
+  final bool isAnonymous;
+  final String? email;
+  final String? displayName;
+  final String? photoUrl;
+}
+
+abstract class AuthService {
+  Stream<AuthUser?> get userChanges;
+  AuthUser? get currentUser;
+  Future<AuthUser> signInAnonymously();
+  Future<AuthUser> signInWithGoogle();
+  Future<String?> idToken({bool forceRefresh = false});
+  Future<void> signOut();
+}
+
+class FirebaseAuthService implements AuthService {
+  FirebaseAuthService({fb.FirebaseAuth? auth, GoogleSignIn? google})
+      : _auth = auth ?? fb.FirebaseAuth.instance,
+        _google = google ?? GoogleSignIn();
+
+  final fb.FirebaseAuth _auth;
+  final GoogleSignIn _google;
+
+  AuthUser? _map(fb.User? u) => u == null
+      ? null
+      : AuthUser(
+          uid: u.uid,
+          isAnonymous: u.isAnonymous,
+          email: u.email,
+          displayName: u.displayName,
+          photoUrl: u.photoURL,
+        );
+
+  @override
+  Stream<AuthUser?> get userChanges => _auth.userChanges().map(_map);
+
+  @override
+  AuthUser? get currentUser => _map(_auth.currentUser);
+
+  @override
+  Future<AuthUser> signInAnonymously() async {
+    final cred = await _auth.signInAnonymously();
+    return _map(cred.user)!;
+  }
+
+  @override
+  Future<AuthUser> signInWithGoogle() async {
+    final account = await _google.signIn();
+    if (account == null) throw fb.FirebaseAuthException(code: 'canceled');
+    final gAuth = await account.authentication;
+    final credential = fb.GoogleAuthProvider.credential(
+      idToken: gAuth.idToken,
+      accessToken: gAuth.accessToken,
+    );
+    final current = _auth.currentUser;
+    fb.UserCredential cred;
+    if (current != null && current.isAnonymous) {
+      try {
+        cred = await current.linkWithCredential(credential); // uid preserved
+      } on fb.FirebaseAuthException catch (e) {
+        if (e.code != 'credential-already-in-use') rethrow;
+        // Google account already has a Cachy identity — switch to it.
+        cred = await _auth.signInWithCredential(credential);
+      }
+    } else {
+      cred = await _auth.signInWithCredential(credential);
+    }
+    return _map(cred.user)!;
+  }
+
+  @override
+  Future<String?> idToken({bool forceRefresh = false}) =>
+      _auth.currentUser?.getIdToken(forceRefresh) ?? Future.value(null);
+
+  @override
+  Future<void> signOut() async {
+    await _google.signOut();
+    await _auth.signOut();
+  }
+}
+```
+
+`main.dart`: before `runApp`, add
+
+```dart
+await Firebase.initializeApp(options: DefaultFirebaseOptions.currentPlatform);
+```
+
+with imports `package:firebase_core/firebase_core.dart` and `firebase_options.dart`; provide `AuthService` alongside the existing providers: `Provider<AuthService>(create: (_) => FirebaseAuthService())`.
+
+- [ ] **Step 4: Run** — `cd app && flutter test test/auth_service_test.dart && flutter analyze` — Expected: PASS, no new analyzer issues.
+
+- [ ] **Step 5: Commit** — `feat: AuthService — anonymous-first Firebase identity with Google linking`
+
+---
+
+### Task 2: Bearer token transport in ApiClient (with one 401 retry)
+
+**Files:**
+- Modify: `app/lib/data/services/api_client.dart`
+- Create: `app/test/api_client_auth_test.dart`
+
+**Interfaces:**
+- Consumes: `AuthService.idToken` (Task 1).
+- Produces: `ApiClient({..., Future<String?> Function({bool forceRefresh})? tokenProvider})`; private `Future<http.Response> _send(...)` used by all verbs; `_ownerHeader` and every `x-owner-id` reference deleted.
+
+- [ ] **Step 1: Write the failing test** (MockClient counts auth headers + retry behavior)
+
+```dart
+import 'dart:convert';
+
+import 'package:flutter_test/flutter_test.dart';
+import 'package:http/http.dart' as http;
+import 'package:http/testing.dart';
+import 'package:cachy/data/services/api_client.dart';
+
+void main() {
+  test('attaches bearer token to requests', () async {
+    String? seenAuth;
+    final mock = MockClient((req) async {
+      seenAuth = req.headers['authorization'];
+      return http.Response(jsonEncode([]), 200);
+    });
+    final api = ApiClient(
+      baseUrl: 'http://x',
+      client: mock,
+      tokenProvider: ({bool forceRefresh = false}) async => 'tok-1',
+    );
+    await api.listCards();
+    expect(seenAuth, 'Bearer tok-1');
+  });
+
+  test('one forced-refresh retry on 401', () async {
+    var calls = 0;
+    final mock = MockClient((req) async {
+      calls++;
+      if (req.headers['authorization'] == 'Bearer stale') {
+        return http.Response('unauthorized', 401);
+      }
+      return http.Response(jsonEncode([]), 200);
+    });
+    var fresh = false;
+    final api = ApiClient(
+      baseUrl: 'http://x',
+      client: mock,
+      tokenProvider: ({bool forceRefresh = false}) async {
+        if (forceRefresh) fresh = true;
+        return fresh ? 'fresh' : 'stale';
+      },
+    );
+    final cards = await api.listCards();
+    expect(cards, isEmpty);
+    expect(calls, 2); // 401 then success — exactly one retry
+  });
+}
+```
+
+- [ ] **Step 2: Run to verify failure** — `cd app && flutter test test/api_client_auth_test.dart` — Expected: FAIL, no `tokenProvider` parameter.
+
+- [ ] **Step 3: Implement in `api_client.dart`**
+
+Constructor gains `this.tokenProvider`; field `final Future<String?> Function({bool forceRefresh})? tokenProvider;`. Replace `_ownerHeader` with:
+
+```dart
+  Future<Map<String, String>> _authHeader({bool forceRefresh = false}) async {
+    final token = await tokenProvider?.call(forceRefresh: forceRefresh);
+    if (token == null || token.isEmpty) return const {};
+    return {'authorization': 'Bearer $token'};
+  }
+
+  /// All verbs funnel through here: auth header + one refresh-retry on 401.
+  Future<http.Response> _send(
+    Future<http.Response> Function(Map<String, String> headers) go, {
+    Map<String, String> extra = const {},
+  }) async {
+    var resp = await go({...extra, ...await _authHeader()});
+    if (resp.statusCode == 401 && tokenProvider != null) {
+      resp = await go({...extra, ...await _authHeader(forceRefresh: true)});
+    }
+    return resp;
+  }
+```
+
+Then mechanically rewrite each call site, e.g.:
+
+```dart
+  Future<List<Card>> listCards({...}) async {
+    final resp = await _send((h) => _client.get(_uri('/cards', {...}), headers: h));
+    return _decodeList(resp).map(Card.fromJson).toList();
+  }
+
+  Future<CreateCardResult> createCard(String url) async {
+    final resp = await _send(
+      (h) => _client.post(_uri('/cards'), headers: h, body: jsonEncode({'url': url})),
+      extra: const {'content-type': 'application/json'},
+    );
+    ...
+  }
+```
+
+Apply to every method that used `_ownerHeader` (grep: `_ownerHeader` must return zero hits afterwards). `streamCard` (SSE): add the awaited auth header to `request.headers` before `_client.send(request)` (no retry loop needed — the reader screen re-subscribes on error). In `main.dart`/composition root, construct `ApiClient(..., tokenProvider: ({bool forceRefresh = false}) => context.read<AuthService>().idToken(forceRefresh: forceRefresh))` — wire via the existing repository setup (pass AuthService into wherever ApiClient is built today).
+
+- [ ] **Step 4: Run** — `cd app && flutter test && flutter analyze` — Expected: PASS.
+
+- [ ] **Step 5: Commit** — `feat: bearer-token transport with single 401 refresh-retry`
+
+---
+
+### Task 3: Login screen after onboarding + RootGate wiring
+
+**Files:**
+- Create: `app/lib/ui/features/onboarding/views/login_screen.dart`
+- Modify: `app/lib/ui/core/root_gate.dart` (insert login step after name; read its current step logic first and mirror its pattern)
+- Modify: `app/lib/ui/core/app_controller.dart` (expose `authUser`, `signInWithGoogle()`, `continueAnonymously()`, listening to `AuthService.userChanges`)
+- Create: `app/test/fakes.dart` (move `FakeAuthService` here)
+- Create: `app/test/login_screen_test.dart`
+
+**Interfaces:**
+- Consumes: `AuthService` (Task 1).
+- Produces: `LoginScreen({required VoidCallback onDone})`; AppController: `AuthUser? get authUser`, `bool get needsLogin` (seen onboarding + has name + no firebase user), `Future<void> signInWithGoogle()`, `Future<void> continueAnonymously()`.
+
+- [ ] **Step 1: Write the failing widget test**
+
+```dart
+import 'package:flutter/material.dart';
+import 'package:flutter_test/flutter_test.dart';
+import 'package:provider/provider.dart';
+import 'package:cachy/data/services/auth_service.dart';
+import 'package:cachy/ui/features/onboarding/views/login_screen.dart';
+
+import 'fakes.dart';
+
+void main() {
+  testWidgets('login screen: Google primary, quiet anonymous path', (tester) async {
+    final auth = FakeAuthService();
+    var done = 0;
+    await tester.pumpWidget(
+      Provider<AuthService>.value(
+        value: auth,
+        child: MaterialApp(home: LoginScreen(onDone: () => done++)),
+      ),
+    );
+    expect(find.text('Continue with Google'), findsOneWidget);
+    expect(find.text('Or use without login…'), findsOneWidget);
+
+    await tester.tap(find.text('Or use without login…'));
+    await tester.pumpAndSettle();
+    expect(auth.currentUser?.isAnonymous, isTrue);
+    expect(done, 1);
+  });
+}
+```
+
+- [ ] **Step 2: Run to verify failure** — Expected: FAIL, `login_screen.dart` missing.
+
+- [ ] **Step 3: Implement `login_screen.dart`**
+
+Visual language mirrors `name_screen.dart` (same radial gradient scaffold, Fraunces headline via theme, `Brand` tokens — no direct GoogleFonts). Core structure:
+
+```dart
+/// Login gate, shown after onboarding + name. Google is primary; anonymous is
+/// a quiet escape hatch with an honest data-loss caveat.
+library;
+
+import 'package:flutter/material.dart';
+import 'package:phosphor_flutter/phosphor_flutter.dart';
+import 'package:provider/provider.dart';
+
+import '../../../../data/services/auth_service.dart';
+import '../../../core/brand.dart';
+import '../../../core/widgets/responsive_center.dart';
+
+class LoginScreen extends StatefulWidget {
+  const LoginScreen({super.key, required this.onDone});
+  final VoidCallback onDone;
+
+  @override
+  State<LoginScreen> createState() => _LoginScreenState();
+}
+
+class _LoginScreenState extends State<LoginScreen> {
+  bool _busy = false;
+  String? _error;
+
+  Future<void> _run(Future<void> Function() action) async {
+    setState(() { _busy = true; _error = null; });
+    try {
+      await action();
+      if (mounted) widget.onDone();
+    } catch (_) {
+      if (mounted) {
+        setState(() => _error = "Couldn't sign in. Check your connection and try again.");
+      }
+    } finally {
+      if (mounted) setState(() => _busy = false);
+    }
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    final theme = Theme.of(context);
+    final scheme = theme.colorScheme;
+    final auth = context.read<AuthService>();
+    return Scaffold(
+      backgroundColor: scheme.surface,
+      body: SafeArea(
+        child: ResponsiveCenter(
+          child: Padding(
+            padding: const EdgeInsets.symmetric(horizontal: 28),
+            child: Column(
+              crossAxisAlignment: CrossAxisAlignment.start,
+              children: [
+                const SizedBox(height: 48),
+                const CachyGlyph(size: 56),
+                const SizedBox(height: 32),
+                Text('Keep your\nlibrary safe.',
+                    style: theme.textTheme.displaySmall),
+                const SizedBox(height: 16),
+                Text(
+                  'Sign in so your cards follow you to any device — and survive a reinstall.',
+                  style: theme.textTheme.bodyLarge?.copyWith(
+                      color: scheme.onSurfaceVariant, height: 1.5),
+                ),
+                if (_error != null) ...[
+                  const SizedBox(height: 16),
+                  Text(_error!, style: TextStyle(color: scheme.error)),
+                ],
+                const Spacer(),
+                FilledButton.icon(
+                  onPressed: _busy ? null : () => _run(() async { await auth.signInWithGoogle(); }),
+                  icon: const PhosphorIcon(PhosphorIconsRegular.googleLogo, size: 20),
+                  label: const Text('Continue with Google'),
+                  style: FilledButton.styleFrom(
+                    minimumSize: const Size.fromHeight(56),
+                    shape: RoundedRectangleBorder(borderRadius: BorderRadius.circular(16)),
+                  ),
+                ),
+                const SizedBox(height: 14),
+                Center(
+                  child: TextButton(
+                    onPressed: _busy ? null : () => _run(() async { await auth.signInAnonymously(); }),
+                    child: Text(
+                      'Or use without login…',
+                      style: theme.textTheme.bodySmall?.copyWith(
+                        color: scheme.onSurfaceVariant,
+                        decoration: TextDecoration.underline,
+                      ),
+                    ),
+                  ),
+                ),
+                const SizedBox(height: 6),
+                Center(
+                  child: Text(
+                    'Without an account, your library lives only on this device.',
+                    textAlign: TextAlign.center,
+                    style: theme.textTheme.bodySmall?.copyWith(color: scheme.onSurfaceVariant),
+                  ),
+                ),
+                const SizedBox(height: 24),
+              ],
+            ),
+          ),
+        ),
+      ),
+    );
+  }
+}
+```
+
+`app_controller.dart`: inject `AuthService`, subscribe to `userChanges` (notifyListeners), add the three members from Interfaces. `root_gate.dart`: current gate is onboarding → name → shell; make it onboarding → name → login → shell, keyed on `needsLogin` (a returning signed-in user skips the login screen because `currentUser != null`).
+
+- [ ] **Step 4: Run** — `cd app && flutter test && flutter analyze` — Expected: PASS.
+
+- [ ] **Step 5: Commit** — `feat: post-onboarding login screen (Google primary, anonymous quiet path)`
+
+---
+
+### Task 4: Profile account section — banner, real sign-out, quota meter, claim
+
+**Files:**
+- Modify: `app/lib/ui/features/profile/views/profile_screen.dart`
+- Modify: `app/lib/data/services/api_client.dart` (+`me()` quota fetch, +`claim(name)`)
+- Modify: `app/lib/ui/core/app_controller.dart` (`logout()` also calls `AuthService.signOut()`)
+- Create: `app/test/profile_account_test.dart`
+
+**Interfaces:**
+- Consumes: `AuthService`, `AppController.authUser` (Task 3), backend `GET /me/quota` + `POST /auth/claim`.
+- Produces: `ApiClient.quota() -> Future<QuotaStatus>` where
+
+```dart
+class QuotaStatus {
+  const QuotaStatus({required this.cardsUsed, required this.cardsLimit, required this.chatUsed, required this.chatLimit});
+  final int cardsUsed, cardsLimit, chatUsed, chatLimit;
+}
+```
+
+and `ApiClient.claimLegacyLibrary(String name) -> Future<int>` (claimed row count; throws ApiException 409 when taken).
+
+- [ ] **Step 1: Write the failing test**
+
+```dart
+import 'dart:convert';
+
+import 'package:flutter_test/flutter_test.dart';
+import 'package:http/http.dart' as http;
+import 'package:http/testing.dart';
+import 'package:cachy/data/services/api_client.dart';
+
+void main() {
+  test('quota() parses /me/quota', () async {
+    final mock = MockClient((req) async {
+      expect(req.url.path, '/me/quota');
+      return http.Response(jsonEncode({
+        'cards': {'used': 3, 'limit': 10},
+        'chat': {'used': 1, 'limit': 30},
+        'resets_at': '2026-07-11T00:00:00+00:00',
+      }), 200);
+    });
+    final api = ApiClient(baseUrl: 'http://x', client: mock);
+    final q = await api.quota();
+    expect(q.cardsUsed, 3);
+    expect(q.cardsLimit, 10);
+  });
+
+  test('claimLegacyLibrary returns claimed count', () async {
+    final mock = MockClient((req) async => http.Response(jsonEncode({'claimed': 7}), 200));
+    final api = ApiClient(baseUrl: 'http://x', client: mock);
+    expect(await api.claimLegacyLibrary('Vatsal'), 7);
+  });
+}
+```
+
+- [ ] **Step 2: Run to verify failure** — Expected: FAIL, `quota`/`claimLegacyLibrary` undefined.
+
+- [ ] **Step 3: Implement**
+
+`api_client.dart` additions (using `_send` from Task 2):
+
+```dart
+class QuotaStatus {
+  const QuotaStatus({required this.cardsUsed, required this.cardsLimit, required this.chatUsed, required this.chatLimit});
+  final int cardsUsed;
+  final int cardsLimit;
+  final int chatUsed;
+  final int chatLimit;
+}
+
+  Future<QuotaStatus> quota() async {
+    final resp = await _send((h) => _client.get(_uri('/me/quota'), headers: h));
+    final json = _decodeMap(resp);
+    int pick(String kind, String field) =>
+        ((json[kind] as Map<String, dynamic>?)?[field] as num?)?.toInt() ?? 0;
+    return QuotaStatus(
+      cardsUsed: pick('cards', 'used'),
+      cardsLimit: pick('cards', 'limit'),
+      chatUsed: pick('chat', 'used'),
+      chatLimit: pick('chat', 'limit'),
+    );
+  }
+
+  Future<int> claimLegacyLibrary(String name) async {
+    final resp = await _send(
+      (h) => _client.post(_uri('/auth/claim'), headers: h, body: jsonEncode({'name': name})),
+      extra: const {'content-type': 'application/json'},
+    );
+    return (_decodeMap(resp)['claimed'] as num?)?.toInt() ?? 0;
+  }
+```
+
+`profile_screen.dart` Account section replaces the current sign-out-only block:
+- Signed-in (Google): row with photo/initial avatar, displayName, email; "Sign out" tile below (existing confirm dialog; copy updated to "Your cards stay safe in your account.").
+- Anonymous: banner tile (primary-tinted container, not a snackbar): title "Your library isn't backed up", subtitle "Sign in with Google — if you uninstall or clear data, your cards are gone.", trailing FilledButton "Sign in" → `context.read<AppController>().signInWithGoogle()`; on success and when `LocalStore.userName` is set, offer the claim dialog: "Restore my old library" → `api.claimLegacyLibrary(name)`; on 409 show "That name was already claimed."
+- Quota meter: under Library section, a `_Tile`-style row "AI usage today" with subtitle `"${q.cardsUsed}/${q.cardsLimit} cards · ${q.chatUsed}/${q.chatLimit} chats"`, loaded via `FutureBuilder(api.quota())`, hidden on error (quota is a nicety, never a blocker).
+- `AppController.logout()`: call `await _auth.signOut()` in addition to the existing `LocalStore.clearUser()`.
+
+- [ ] **Step 4: Run** — `cd app && flutter test && flutter analyze` — Expected: PASS.
+
+- [ ] **Step 5: Manual end-to-end check (requires deployed backend + Firebase setup)**
+
+Run `cd app && flutter run -d chrome --dart-define=CACHY_API_BASE=http://localhost:8000` with the backend running and `FIREBASE_PROJECT_ID` set. Verify: onboarding → name → login screen appears once → "Or use without login…" enters the shell → profile shows the not-backed-up banner → Google sign-in links (library unchanged) → banner replaced by account row → sign out returns to onboarding gate.
+
+- [ ] **Step 6: Commit** — `feat: profile account section — banner, quota meter, legacy claim, real sign-out`

docs/planning/plans/2026-07-10-ui-trust-polish.md

@@ -0,0 +1,435 @@
+# UI Trust & Polish Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Close the four P1 trust leaks from the 2026-07-10 critique (fake cache-clear, dead Move-to-Folder, raw errors, cold-start cliff) plus the P2 polish items (reduced motion, onboarding brand pass, bounce easing).
+
+**Architecture:** Pure Flutter changes, independent of the auth plans. Error mapping happens once in `ApiException`; move-to-folder reuses the existing `/collections/cards/{id}/move` endpoint and `ApiClient.moveCardToCollection`; cold-start becomes a distinct library/share status driven by retry-with-backoff in the repository layer.
+
+**Tech Stack:** Flutter, provider, flutter_animate, flutter_test.
+
+## Global Constraints
+
+- Spec: "UI trust & polish fixes" section of `docs/superpowers/specs/2026-07-10-public-distribution-auth-quotas-design.md`; critique snapshot `.impeccable/critique/2026-07-10T11-11-16Z__app-lib.md`.
+- Brand rules: all type through `brand.dart` tokens (no direct GoogleFonts outside it), motion 150–260ms ease-out, no bounce/overshoot, glass tokens shared.
+- Never surface `e.toString()`, `ApiException(...)` bodies, or server tracebacks in UI copy.
+- `cd app && flutter test && flutter analyze` after every task.
+- No commits unless the user has granted it in-session; Commit steps are conditional on that.
+
+---
+
+### Task 1: Real "Clear offline cache"
+
+**Files:**
+- Modify: `app/lib/data/services/local_store.dart`
+- Modify: `app/lib/ui/features/profile/views/profile_screen.dart:251-256`
+- Create: `app/test/local_store_test.dart`
+
+**Interfaces:**
+- Produces: `Future<int> LocalStore.clearCardCache()` — removes every cached card + index, returns removed count.
+
+- [ ] **Step 1: Write the failing test**
+
+```dart
+import 'package:flutter_test/flutter_test.dart';
+import 'package:shared_preferences/shared_preferences.dart';
+import 'package:cachy/data/services/local_store.dart';
+
+void main() {
+  TestWidgetsFlutterBinding.ensureInitialized();
+
+  test('clearCardCache removes all cached cards and the index', () async {
+    SharedPreferences.setMockInitialValues({});
+    final store = await LocalStore.open();
+    await store.cacheCard('c1', {'id': 'c1'});
+    await store.cacheCard('c2', {'id': 'c2'});
+    expect(store.cachedCardIds(), hasLength(2));
+
+    final removed = await store.clearCardCache();
+    expect(removed, 2);
+    expect(store.cachedCardIds(), isEmpty);
+    expect(store.readCard('c1'), isNull);
+  });
+}
+```
+
+- [ ] **Step 2: Run to verify failure** — `cd app && flutter test test/local_store_test.dart` — Expected: FAIL, `clearCardCache` undefined.
+
+- [ ] **Step 3: Implement**
+
+`local_store.dart`, in the Card cache section:
+
+```dart
+  /// Remove every cached card and the index. Returns how many were removed.
+  Future<int> clearCardCache() async {
+    final ids = cachedCardIds();
+    for (final id in ids) {
+      await _prefs.remove('$_cardPrefix$id');
+    }
+    await _prefs.remove(_indexKey);
+    return ids.length;
+  }
+```
+
+`profile_screen.dart` `_confirmClear`, replace the lying success block:
+
+```dart
+    if (ok == true && mounted) {
+      final removed = await context.read<LocalStore>().clearCardCache();
+      if (mounted) {
+        ScaffoldMessenger.of(context).showSnackBar(SnackBar(
+          content: Text(removed == 0
+              ? 'Nothing cached yet'
+              : 'Cleared $removed offline ${removed == 1 ? 'card' : 'cards'}'),
+        ));
+      }
+    }
+```
+
+If `LocalStore` isn't in the provider graph, expose it via `CardRepository` (e.g. `context.read<CardRepository>().store.clearCardCache()`) — check how the repository holds it and use the existing path; do not add a new provider if one route already exists.
+
+- [ ] **Step 4: Run** — `cd app && flutter test && flutter analyze` — Expected: PASS.
+
+- [ ] **Step 5: Commit** — `fix: Clear offline cache actually clears (and reports the count)`
+
+---
+
+### Task 2: Friendly error mapping at the ApiException boundary
+
+**Files:**
+- Modify: `app/lib/data/services/api_client.dart` (ApiException gains `friendlyMessage`)
+- Modify: `app/lib/ui/features/actions/view_models/actions_view_model.dart:73` and every VM assigning `e.toString()` to a user-visible error field (grep `toString()` under `app/lib/ui/**/view_models/` and `app/lib/ui/**/views/` for snackbar/error uses)
+- Create: `app/test/api_exception_test.dart`
+
+**Interfaces:**
+- Produces: `String ApiException.friendlyMessage` and `String friendlyError(Object e)` helper (top-level in api_client.dart) — the ONLY strings VMs may store in user-visible error fields.
+
+- [ ] **Step 1: Write the failing test**
+
+```dart
+import 'package:flutter_test/flutter_test.dart';
+import 'package:cachy/data/services/api_client.dart';
+
+void main() {
+  test('friendly messages never leak bodies or tracebacks', () {
+    expect(ApiException(500, '{"detail":"X","traceback":"Trace..."}').friendlyMessage,
+        'Something went wrong on our side. Try again in a moment.');
+    expect(ApiException(429, '{"error":"quota"}').friendlyMessage,
+        "You've hit today's limit. It resets at midnight UTC.");
+    expect(ApiException(401, 'x').friendlyMessage,
+        'Session expired — please sign in again.');
+    expect(ApiException(404, 'x').friendlyMessage,
+        "That card isn't there anymore.");
+    for (final code in [400, 401, 404, 429, 500, 503]) {
+      final msg = ApiException(code, 'traceback secret').friendlyMessage;
+      expect(msg.contains('traceback'), isFalse);
+      expect(msg.contains('secret'), isFalse);
+    }
+  });
+
+  test('friendlyError handles non-Api exceptions', () {
+    expect(friendlyError(Exception('SocketException: conn refused')),
+        "Can't reach Cachy. Check your connection.");
+  });
+}
+```
+
+- [ ] **Step 2: Run to verify failure** — Expected: FAIL, `friendlyMessage` undefined.
+
+- [ ] **Step 3: Implement**
+
+In `api_client.dart`:
+
+```dart
+class ApiException implements Exception {
+  ApiException(this.statusCode, this.message);
+  final int statusCode;
+  final String message; // raw body — for logs only, never for UI
+
+  /// What users see. Raw bodies (which may include server details) never
+  /// leave the data layer.
+  String get friendlyMessage => switch (statusCode) {
+        401 || 403 => 'Session expired — please sign in again.',
+        404 => "That card isn't there anymore.",
+        429 => "You've hit today's limit. It resets at midnight UTC.",
+        >= 500 => 'Something went wrong on our side. Try again in a moment.',
+        _ => "That didn't work. Try again.",
+      };
+
+  @override
+  String toString() => 'ApiException($statusCode): $message';
+}
+
+/// UI-safe message for any thrown object.
+String friendlyError(Object e) => switch (e) {
+      ApiException api => api.friendlyMessage,
+      _ => "Can't reach Cachy. Check your connection.",
+    };
+```
+
+Swap every user-visible assignment, e.g. `actions_view_model.dart:73`: `_error = e.toString();` → `_error = friendlyError(e);` (keep a `debugPrint('$e')` or logger call if the original context logged). Do the same wherever `SnackBar(content: Text('...$error'))` shows a VM error built from `toString()` (library bulk delete already shows `vm.error` — that's now friendly automatically).
+
+- [ ] **Step 4: Run** — `cd app && flutter test && flutter analyze`; then `grep -rn "toString()" app/lib/ui | grep -i "error\|snack"` — Expected: tests PASS; grep only shows non-UI/logging uses.
+
+- [ ] **Step 5: Commit** — `fix: friendly error copy everywhere — raw exceptions never reach UI`
+
+---
+
+### Task 3: Cold-start "Waking Cachy up" state
+
+**Files:**
+- Modify: `app/lib/ui/features/library/view_models/library_view_model.dart` (new status + retry loop)
+- Modify: `app/lib/ui/features/library/views/library_screen.dart` (`_body` renders the waking state)
+- Create: `app/test/library_wakeup_test.dart`
+
+**Interfaces:**
+- Consumes: `friendlyError` (Task 2).
+- Produces: `LibraryStatus.waking` enum value; `LibraryViewModel.load()` retries up to 6 times / 10s apart on connection-shaped failures before settling on `error`; `int get wakeAttempt`.
+
+- [ ] **Step 1: Write the failing test**
+
+Read `library_view_model.dart` first for its repository interface, then adapt this shape (fake repo that fails N times then succeeds):
+
+```dart
+import 'package:flutter_test/flutter_test.dart';
+import 'package:cachy/ui/features/library/view_models/library_view_model.dart';
+
+import 'fakes.dart'; // FakeCardRepository: fails with SocketException-ish twice, then returns []
+
+void main() {
+  test('connection failure enters waking state, then recovers', () async {
+    final repo = FakeCardRepository(failuresBeforeSuccess: 2);
+    final vm = LibraryViewModel(repository: repo, wakeRetryDelay: Duration.zero);
+    final seen = <LibraryStatus>[];
+    vm.addListener(() => seen.add(vm.status));
+    await vm.load();
+    expect(seen, contains(LibraryStatus.waking));
+    expect(vm.status, anyOf(LibraryStatus.empty, LibraryStatus.ready));
+  });
+
+  test('persistent failure lands on error after max attempts', () async {
+    final repo = FakeCardRepository(failuresBeforeSuccess: 99);
+    final vm = LibraryViewModel(repository: repo, wakeRetryDelay: Duration.zero);
+    await vm.load();
+    expect(vm.status, LibraryStatus.error);
+  });
+}
+```
+
+Write `FakeCardRepository` in `app/test/fakes.dart` implementing only the members `LibraryViewModel` actually calls (check the VM; typically `list()` and the offline flag).
+
+- [ ] **Step 2: Run to verify failure** — Expected: FAIL, `LibraryStatus.waking` undefined.
+
+- [ ] **Step 3: Implement**
+
+In `library_view_model.dart`: add `waking` to `LibraryStatus`; constructor param `this.wakeRetryDelay = const Duration(seconds: 10)`; wrap the load's fetch:
+
+```dart
+  static const _maxWakeAttempts = 6;
+  int _wakeAttempt = 0;
+  int get wakeAttempt => _wakeAttempt;
+
+  Future<List<model.Card>> _fetchWithWake() async {
+    for (_wakeAttempt = 0; ; _wakeAttempt++) {
+      try {
+        return await repository.list();
+      } catch (e) {
+        final connectionShaped = e is! ApiException; // socket/timeouts, not HTTP
+        if (!connectionShaped || _wakeAttempt >= _maxWakeAttempts) rethrow;
+        _status = LibraryStatus.waking;
+        notifyListeners();
+        await Future<void>.delayed(wakeRetryDelay);
+      }
+    }
+  }
+```
+
+and call `_fetchWithWake()` where `load()` currently calls the repository (keep the existing offline-cache fallback: if the cache has cards while waking fails, show cached cards with the offline chip instead — reuse the current offline path).
+
+`library_screen.dart` `_body`, add before the error case:
+
+```dart
+      case LibraryStatus.waking:
+        return _scrollable(
+          EmptyState(
+            showGlyph: true,
+            title: 'Waking Cachy up…',
+            message: 'The free server naps when idle. First load takes about '
+                '30 seconds — your library is on its way.',
+          ),
+        );
+```
+
+- [ ] **Step 4: Share flow cold-start copy**
+
+The share pipeline already degrades to `ShareStatus.queuedOffline` on connection failure (`share_screen.dart:129-149`) — that state doubles as the cold-start path for captures. Update its copy so a sleeping server doesn't read as "you're offline":
+
+- Title: `'Saved offline'` → `'Saved — will process shortly'`
+- Body: `"We'll process this reel as soon as you're back online."` → `"We'll process this as soon as Cachy is reachable — the free server can take ~30s to wake up."`
+
+- [ ] **Step 5: Run** — `cd app && flutter test && flutter analyze` — Expected: PASS.
+
+- [ ] **Step 6: Commit** — `feat: cold-start waking state with auto-retry instead of instant failure`
+
+---
+
+### Task 4: Move to Folder — replace both stubs
+
+**Files:**
+- Modify: `app/lib/ui/features/library/view_models/library_view_model.dart` (`bulkMove`)
+- Create: `app/lib/ui/features/collections/views/folder_picker_sheet.dart`
+- Modify: `app/lib/ui/core/home_shell.dart:483-485` and `app/lib/ui/features/library/views/library_screen.dart:315-319` (call the picker; also dedupe `_confirmBulkDelete` into one shared helper `confirmBulkDelete(BuildContext, LibraryViewModel)` living in `library_view_model.dart`'s file or a small `library_dialogs.dart`)
+- Create: `app/test/bulk_move_test.dart`
+
+**Interfaces:**
+- Consumes: `ApiClient.moveCardToCollection` + `listCollections`/`createCollection` (already exist).
+- Produces: `Future<void> LibraryViewModel.bulkMove(String? collectionId)` — moves all selected cards, clears selection, refreshes; `Future<void> showFolderPicker(BuildContext context, LibraryViewModel vm)` — adaptive sheet listing folders + "New folder…" row.
+
+- [ ] **Step 1: Write the failing test**
+
+```dart
+import 'package:flutter_test/flutter_test.dart';
+import 'package:cachy/ui/features/library/view_models/library_view_model.dart';
+
+import 'fakes.dart'; // FakeCardRepository records moveCardToCollection calls
+
+void main() {
+  test('bulkMove moves every selected card and clears selection', () async {
+    final repo = FakeCardRepository(cards: ['a', 'b', 'c']);
+    final vm = LibraryViewModel(repository: repo);
+    await vm.load();
+    vm.toggleSelected('a');
+    vm.toggleSelected('c');
+
+    await vm.bulkMove('folder-1');
+
+    expect(repo.moves, {'a': 'folder-1', 'c': 'folder-1'});
+    expect(vm.selectionActive, isFalse);
+  });
+}
+```
+
+Match the VM's real selection API names (`toggleSelected`/`selectionActive` — read the VM first and mirror; extend `FakeCardRepository` with a `moves` map).
+
+- [ ] **Step 2: Run to verify failure** — Expected: FAIL, `bulkMove` undefined.
+
+- [ ] **Step 3: Implement**
+
+`library_view_model.dart`:
+
+```dart
+  /// Move every selected card into [collectionId] (null = remove from folders).
+  Future<void> bulkMove(String? collectionId) async {
+    final ids = List<String>.from(selectedIds);
+    try {
+      for (final id in ids) {
+        await repository.moveCardToCollection(id, collectionId);
+      }
+      clearSelection();
+      await refresh();
+    } catch (e) {
+      _error = friendlyError(e);
+      notifyListeners();
+    }
+  }
+```
+
+(If the repository lacks `moveCardToCollection`, add a one-line passthrough to `api.moveCardToCollection`.)
+
+`folder_picker_sheet.dart` — adaptive modal (reuse `showAdaptiveModal`) listing collections from `ApiClient.listCollections()`, one `ListTile` per folder (folder icon, name), a divider, then "New folder…" which prompts a name via `AlertDialog` + `createCollection`, then moves. Selecting any row: `await vm.bulkMove(entry.id); Navigator.pop(ctx);` with a confirmation snackbar `Moved N cards to "<name>"`.
+
+Replace both stubs: `onMoveToFolder: () => showFolderPicker(context, vm)`. Delete the duplicated `_confirmBulkDelete` from `home_shell.dart` and `library_screen.dart`; both call the new shared `confirmBulkDelete`.
+
+- [ ] **Step 4: Run** — `cd app && flutter test && flutter analyze`; then `grep -rn "coming soon" app/lib` — Expected: tests PASS, grep empty.
+
+- [ ] **Step 5: Commit** — `feat: bulk Move to Folder (replaces coming-soon stubs); dedupe bulk-delete dialog`
+
+---
+
+### Task 5: Reduced motion honored everywhere
+
+**Files:**
+- Modify: `app/lib/ui/core/theme.dart` (motion gate helper)
+- Modify: all 16 `.animate()` call sites + `AnimatedScale` durations (grep `\.animate(` and `Motion.fast`/`Motion.spring` under `app/lib`)
+- Create: `app/test/reduced_motion_test.dart`
+
+**Interfaces:**
+- Produces: `extension MotionGate on BuildContext { bool get motionEnabled; Duration gated(Duration d); }` in theme.dart.
+
+- [ ] **Step 1: Write the failing test**
+
+```dart
+import 'package:flutter/material.dart';
+import 'package:flutter_test/flutter_test.dart';
+import 'package:cachy/ui/core/theme.dart';
+
+void main() {
+  testWidgets('motionEnabled follows MediaQuery.disableAnimations', (tester) async {
+    late bool enabled;
+    late Duration gated;
+    await tester.pumpWidget(MediaQuery(
+      data: const MediaQueryData(disableAnimations: true),
+      child: Builder(builder: (context) {
+        enabled = context.motionEnabled;
+        gated = context.gated(Motion.medium);
+        return const SizedBox();
+      }),
+    ));
+    expect(enabled, isFalse);
+    expect(gated, Duration.zero);
+  });
+}
+```
+
+- [ ] **Step 2: Run to verify failure** — Expected: FAIL, extension undefined.
+
+- [ ] **Step 3: Implement**
+
+`theme.dart`:
+
+```dart
+/// Reduced-motion gate: animations collapse to zero duration when the OS asks.
+extension MotionGate on BuildContext {
+  bool get motionEnabled => !MediaQuery.of(this).disableAnimations;
+  Duration gated(Duration d) => motionEnabled ? d : Duration.zero;
+}
+```
+
+Then sweep call sites:
+- flutter_animate chains: `.animate()` → wrap the whole chain: `motionEnabled ? child.animate()...fadeIn(...) : child` OR simpler global switch in `main.dart` root build: `Animate.restartOnHotReload = true;` is unrelated — instead set `child.animate(autoPlay: context.motionEnabled)` where supported, else the conditional wrap. Use the conditional wrap; it's explicit and testable.
+- `AnimatedScale`/`AnimatedContainer` durations: `duration: Motion.fast` → `duration: context.gated(Motion.fast)`.
+- Also change `Motion.spring = Curves.easeOutBack` → `Curves.easeOutCubic` (bounce ban) and in `app/web/index.html` replace `cubic-bezier(0.34, 1.56, 0.64, 1)` with `cubic-bezier(0.22, 1, 0.36, 1)`.
+
+- [ ] **Step 4: Run** — `cd app && flutter test && flutter analyze`; then `grep -rn "easeOutBack" app/` — Expected: PASS, grep empty.
+
+- [ ] **Step 5: Commit** — `fix: honor reduced-motion everywhere; retire bounce easing`
+
+---
+
+### Task 6: Onboarding brand pass + stale comments
+
+**Files:**
+- Modify: `app/lib/ui/features/onboarding/views/onboarding_screen.dart`
+- Modify: `app/lib/ui/features/onboarding/views/name_screen.dart`
+- Modify: `app/lib/ui/features/library/views/library_screen.dart:1-7` (doc comment)
+
+**Interfaces:** none new — visual conformance only.
+
+- [ ] **Step 1: Apply the brand pass**
+
+`onboarding_screen.dart`:
+- `_LogoBadge`: replace the lightning-in-a-box with the real mark: `Row(children: [const CachyGlyph(size: 30), const SizedBox(width: 10), Text('cachy', style: Brand.wordmarkStyle(20, color: scheme.onSurface))])` — delete the Container/lightning entirely.
+- Every `GoogleFonts.fraunces(... fontWeight: FontWeight.w800 ...)` headline → `theme.textTheme.displaySmall` / `displayMedium` (Brand's w600 serif), keeping the accent-colored `TextSpan`s; drop the glow `Shadow` on "Captured." (calm over clever). Remove the `google_fonts` import.
+- File doc comment: delete "adapted from Insightr (demo)" wording — describe what it is now.
+
+`name_screen.dart`: headline `GoogleFonts.fraunces(...)` → `theme.textTheme.displaySmall`; remove the glow shadow and the `google_fonts` import.
+
+`library_screen.dart` header comment: "Two segments — Cards and To-do" → "Three segments — Cards, Concepts, Catalog".
+
+- [ ] **Step 2: Verify**
+
+Run: `cd app && flutter analyze && flutter test` — Expected: clean, all PASS. Then `grep -rn "GoogleFonts" app/lib | grep -v core/brand.dart` — Expected: empty.
+
+- [ ] **Step 3: Visual check** — `cd app && flutter run -d chrome` , clear browser storage to re-trigger onboarding; confirm the glyph mark, w600 headlines, no glow.
+
+- [ ] **Step 4: Commit** — `polish: onboarding on-brand (glyph mark, w600 serif, no glow); fix stale comments`

docs/planning/plans/2026-07-10-v2-on-device-ai.md

@@ -0,0 +1,76 @@
+# V2 On-Device AI + Distribution Implementation Plan (Roadmap)
+
+> **For agentic workers:** This is a V2 roadmap plan. Prerequisites: V1 plans (`2026-07-10-backend-auth-quotas.md`, `2026-07-10-flutter-auth.md`) executed and deployed. Before executing any task here, RE-VALIDATE the runtime choice (MediaPipe LLM Inference / `flutter_gemma` / model availability) — the on-device LLM ecosystem changes monthly. Then expand each task into full TDD steps via superpowers:writing-plans.
+
+**Goal:** Quota-exhausted users with an installed local model get structured cards generated on their own phone — zero server AI spend. Plus Play Store readiness and sustainability hooks.
+
+**Spec:** `docs/superpowers/specs/2026-07-10-v2-on-device-ai-design.md`
+
+## Phase A — Backend bundle round-trip (independent, testable now-ish)
+
+### Task A1: Persist raw bundle on degraded jobs
+- `cards.raw_bundle: TEXT NULL` column + additive migration entry.
+- Worker: when `job.degraded`, store the extraction bundle text on the card before paragraph fallback.
+- Test: degraded job → `raw_bundle` set; normal job → NULL.
+
+### Task A2: `GET /cards/{id}/bundle`
+- Owner-scoped (OwnerDep). 200 `{bundle, transcript, caption}` when stored; 404 otherwise.
+- Test: owner gets bundle; other uid 404; non-degraded card 404.
+
+### Task A3: `POST /cards/{id}/structure`
+- Owner-scoped. Body = client-generated structured card JSON.
+- Validate with the SAME Pydantic models the LLM path uses (`structuring` validation) — reject invalid with 422.
+- On accept: replace paragraph content, clear `raw_bundle`, re-run `_embed_card`, bump card state.
+- Test: valid payload upgrades card + clears bundle; schema-garbage 422; foreign owner 404.
+
+## Phase B — Flutter local AI
+
+### Task B1: `LocalAiService` interface + fake
+- Mirror the `AuthService` pattern: abstract interface, `FakeLocalAiService` for tests.
+- API: `status` (notInstalled|downloading(progress)|ready|error), `download()`, `delete()`, `Future<Map<String,dynamic>?> structureBundle(String bundle, {String transcript, String caption})` (null = generation failed/invalid JSON).
+
+### Task B2: Model download manager
+- Resumable download of Gemma 3 1B int4 (~550 MB) to app storage, sha256 check, Wi-Fi-recommended warning dialog.
+- State machine unit-tested against the fake HTTP layer.
+
+### Task B3: Inference integration
+- MediaPipe LLM Inference via platform channel (or `flutter_gemma` if healthy at build time). Android only; feature-gate everywhere else.
+- Prompt: short instruction + one few-shot example + strict "JSON only" suffix; client-side JSON parse + block-schema validation; invalid → return null.
+
+### Task B4: Wire the degrade path
+- Card returns `quota_degraded` → if `LocalAiService.status == ready`: fetch `/bundle`, run `structureBundle`, POST `/structure`, refresh card. Progress UI in reader ("Generating on your phone…"), cancellable.
+- Any failure → paragraph card remains, no error dialog (silent grace, log only).
+- Widget test with fakes: degraded card + ready model → upgraded card; model returns null → paragraph kept.
+
+### Task B5: Profile "Offline AI" section
+- Download/enable/disable/delete UI, size on disk, honest copy ("~550 MB, runs on your phone, slower than cloud").
+- Quota chip second state: "Generating on your phone".
+
+## Phase C — Distribution & sustainability
+
+### Task C1: Privacy policy page at `/privacy` on the Space; link from Profile → About.
+### Task C2: Play Store submission — Data Safety form, target API check, store listing (screenshots from web build), $25 account.
+### Task C3: Sponsors/Ko-fi link in Profile → About ("Keep Cachy free"); apply GitHub Student Pack + Cerebras/Groq edu credits.
+### Task C4 (calendar ~1 month post-V1): delete `/auth/claim` + `claims` table + client claim flow.
+
+## Phase D — Private media (thumbnails/keyframes off the public HF dataset)
+
+Closes a real privacy gap: onboarding promises "Only you see your cards" but thumbnails currently sit in a **public** HF dataset repo. Spec: `docs/superpowers/specs/2026-07-10-v2-on-device-ai-design.md` Part 3.
+
+### Task D1: Flip the HF dataset repo to private
+- Manual, one-time: HF dataset settings → private. No code change. Verify with an unauthenticated raw-URL fetch attempt (must fail after the flip).
+
+### Task D2: Owner-checked media proxy endpoint
+- `GET /media/{card_id}/{filename}` — `OwnerDep`-gated (card's `owner_id` must match caller), streams bytes from the private HF dataset via `hf_api_key` (`hf_hub_download` or HF HTTP API), correct `content-type` by extension, `Cache-Control: private, max-age=3600`.
+- Test: 404 for non-owned cards, 200 + correct bytes for owned cards, 401 unauthenticated.
+
+### Task D3: Emit proxy paths instead of raw HF URLs
+- Update wherever media refs are written into card JSON (`store/media.py` / `worker.py`) to emit `/media/{card_id}/{filename}` instead of the absolute HF dataset URL.
+- Confirm `ApiClient.resolveMedia` needs no change (it already joins bare paths onto `baseUrl`; only absolute-URL passthrough becomes dead code for new cards).
+- Regression: existing cards written before this change carry old absolute HF URLs — keep a fallback branch (client or backend) so pre-migration cards still resolve, or run a one-time backfill rewriting stored refs to the new scheme.
+
+## Order & gates
+
+- A before B (B needs the endpoints). C anytime after V1. D anytime after V1 (independent of A/B/C) — recommended right after V2's on-device work, per user sequencing preference; could move earlier since it's a live privacy gap, revisit if that becomes urgent.
+- Gate before B3: benchmark chosen model on one real mid-range Android phone — if structuring takes >2 min or JSON validity <~70%, drop to paragraph-only and re-evaluate model choice.
+- Gate before D1: confirm no other consumer (embed codes shared externally, cached CDN links, etc.) depends on the media repo being public before flipping it private.

docs/planning/specs/2026-07-10-public-distribution-auth-quotas-design.md

@@ -0,0 +1,133 @@
+# Cachy Public Distribution: Auth, Quotas, Backend Hardening
+
+**Date:** 2026-07-10
+**Status:** Approved
+**Scope:** V1 for distributing Cachy to non-technical users (GitHub APK + hosted web) while shared free-tier AI keys survive. On-device model, Play Store, payments, email auth are explicitly out of scope (V2+).
+
+## Problem
+
+Cachy today identifies users by a self-declared name sent as the `x-owner-id` header. The backend trusts it blindly:
+
+- Anyone can read any user's library by guessing a name (`curl -H "x-owner-id: Vatsal"`).
+- Name collisions silently merge libraries.
+- Per-user quotas are unenforceable (attacker rotates header values), so shared free-tier API keys (Cerebras, Groq, Gemini pool) cannot be protected.
+- `/admin/stats`, `/debug/jobs`, `/debug/kill_stuck` are unauthenticated; 500 responses leak tracebacks; CORS is `*`.
+
+## Decision Summary
+
+| Decision | Choice |
+|---|---|
+| Identity | Firebase Auth: anonymous sign-in on first launch, optional upgrade to Google Sign-In via `linkWithCredential` (same uid, data preserved) |
+| Token transport | `Authorization: Bearer <Firebase ID token>` on every API request |
+| Backend verification | `firebase-admin` `verify_id_token`; `owner_id` = verified `uid` |
+| Quota policy | Per-user daily quotas; past card quota → degrade to existing paragraph-fallback path (card still saves), never hard-fail |
+| Quota storage | `usage(owner_id, day, kind, count)` table in existing DB (SQLite / Neon) |
+| Abuse defense | Per-IP daily cap on card creation (same usage table, keyed by IP) |
+| Admin/debug routes | Gated by `X-Admin-Token` matching env secret |
+| Migration | Temporary `/auth/claim` endpoint: authed user claims rows whose `owner_id` equals their old display name, first-claim-wins; removed after ~1 month |
+
+### Why Firebase Auth (alternatives considered)
+
+- **Firebase Auth (chosen):** anonymous→Google linking is a native feature; free unlimited for anonymous + Google providers; backend verification is one call. Google lock-in acceptable — stack is already Google-centric (Gemini keys, Android target).
+- **Supabase Auth:** comparable free tier but anonymous→permanent linking is manual, and it adds a new vendor.
+- **Hand-rolled JWT (Google Identity Services direct):** no new dependency but we own token issuance, refresh, revocation — auth bugs become breaches. Rejected.
+
+## Architecture
+
+### 1. Client auth flow (Flutter)
+
+- Packages: `firebase_auth`, `google_sign_in` (+ `firebase_core`).
+- **First launch:** onboarding (including the existing name screen) runs first; the login screen comes after it:
+  - Primary button: "Continue with Google" (`signInWithCredential`).
+  - Below, small quiet text link: "Or use without login…" → `signInAnonymously()`.
+  - Either path yields a stable Firebase `uid`.
+  - The name entered during onboarding is kept for both paths — it stays the display/greeting name (local + stored server-side as profile field), but is no longer the identity; `uid` is.
+- **Anonymous upgrade:** Profile screen shows a persistent banner while anonymous: "Your library isn't backed up — sign in with Google." Tapping runs `linkWithCredential(GoogleAuthProvider credential)` — uid unchanged, no data migration.
+- **Warning copy:** anonymous users are told data may be lost if the app is uninstalled / data cleared.
+- Display name: everyone types a name during onboarding (kept as greeting/profile name); Google linking may additionally surface the Google profile name/avatar. Name is never identity.
+
+### 2. Token transport (ApiClient)
+
+- `_ownerHeader` in `app/lib/data/services/api_client.dart` is replaced by an auth header provider: every request attaches `Authorization: Bearer <ID token>` from `FirebaseAuth.instance.currentUser.getIdToken()` (SDK caches + auto-refreshes; cheap to call per request).
+- SSE stream request (`streamCard`) attaches the same header.
+
+### 3. Backend verification (FastAPI)
+
+- New dependency `get_owner(request) -> str`:
+  - Extracts bearer token, verifies via `firebase_admin.auth.verify_id_token` (public JWKS; needs only the Firebase project ID configured via env).
+  - Returns `uid`; raises 401 on missing/invalid/expired token.
+- Every route currently reading `x-owner-id` swaps to `Depends(get_owner)`. The `owner_id` column semantics are unchanged — only its source becomes trustworthy.
+- `x-owner-id` header support is removed entirely (no fallback); the legacy name only survives as the body parameter of the temporary `/auth/claim` endpoint below.
+
+### 4. Migration of existing name-based data
+
+- `POST /auth/claim {name: str}` (authenticated): re-points all rows with `owner_id == name` to the caller's `uid`, if that name has not already been claimed. First-claim-wins; a `claims` table records name→uid to prevent double claims.
+- Client: after first sign-in, if a legacy local `userName` exists, offer "Restore my old library" which calls this endpoint.
+- Endpoint is temporary; delete after ~1 month.
+
+### 5. Quotas
+
+- Table: `usage(owner_id TEXT, day TEXT, kind TEXT, count INT, PRIMARY KEY(owner_id, day, kind))`. Day = UTC date string.
+- FastAPI dependency factory `spend_quota(kind, daily_limit)` applied to expensive routes:
+  - `POST /cards` (AI card creation): **10/day**
+  - Card chat + library chat + rabbithole: **30/day** combined
+  - `GET /connections?refresh=true`: **3/day**
+  - Limits are env-configurable (`QUOTA_CARDS_PER_DAY`, etc.).
+- **Degrade, don't fail (cards):** past quota, `POST /cards` still succeeds but the job row is flagged `degraded=1`; the worker skips LLM structuring and uses the existing paragraph-fallback path. This flag is also the V2 hook — a device with an installed local model can fetch the raw bundle and structure it client-side.
+- **Chat past quota:** 429 with structured body `{error: "quota", kind, used, limit, resets_at}`; UI renders "recharges tomorrow" state.
+- Quota status: expensive-route responses include `quota: {used, limit}`; plus `GET /me/quota` for the profile meter.
+- **Anon-farming defense:** card creation also increments a per-IP counter (same table, `owner_id = "ip:<addr>"`), capped at e.g. 30/day/IP (env-configurable). Prevents scripted fresh anonymous uids from draining keys.
+
+### 6. Backend hardening
+
+- `/admin/stats`, `/debug/jobs`, `/debug/kill_stuck`: require `X-Admin-Token` header equal to `ADMIN_TOKEN` env secret (404/401 otherwise).
+- Global 500 handler: full traceback to server logs only; client gets `{"detail": "internal error"}`.
+- CORS: `allow_origins` restricted to the hosted Space origin + `http://localhost:*` dev origins (native APK traffic is unaffected by CORS).
+
+### 7. UI changes (Flutter)
+
+- **Login screen** (new, shown after onboarding/name screen): Google button + small "Or use without login…" link; brand styling consistent with `brand.dart` tokens.
+- **Profile screen:** account section — avatar/name/email when linked; "Sign in with Google" banner when anonymous; quota meter ("7/10 AI cards today"); sign out.
+- **Share/pipeline UI:** quota chip; degraded card shows "AI recharges tomorrow".
+
+### 8. Error handling
+
+- 401 from API → client forces token refresh once, retries; still 401 → return to login screen.
+- Firebase unreachable at launch → app opens read-only from repository cache with "reconnecting" banner.
+- Quota 429 → friendly states everywhere; raw errors never shown.
+- `verify_id_token` failures log the reason server-side (expired vs malformed vs wrong project).
+
+### 9. Testing
+
+- `backend/tests/` is deleted on the current branch — restore the pytest harness first.
+- Backend: `get_owner` (valid/expired/forged/missing token, mocked verifier); quota spend/rollover/degrade flag; per-IP cap; admin-token gate; `/auth/claim` first-claim-wins.
+- Flutter: auth controller transitions (anonymous → linked); quota meter widget; 401-retry logic in ApiClient.
+
+## UI trust & polish fixes (from 2026-07-10 whole-app critique, score 26/40)
+
+Ship with this release; full report in `.impeccable/critique/2026-07-10T11-11-16Z__app-lib.md`.
+
+**P1 — trust (all four required):**
+1. **Real cache clear**: `_confirmClear` (profile_screen.dart) currently shows "Offline cache cleared" without clearing anything. Wire to the local store's actual clear, or remove the tile.
+2. **Move to Folder**: implement the bulk-selection "Move to Folder" action (collections + move endpoint already exist); replace both "coming soon" stubs (home_shell.dart, library_screen.dart). Dedupe the duplicated bulk-delete dialog while there.
+3. **Friendly errors**: map `ApiException` → human strings at the repository boundary; never surface `e.toString()` in snackbars/error states (pairs with server-side traceback removal above).
+4. **Cold-start state**: HF Space sleeps; first connect must show "Waking Cachy up — first load takes ~30s" with auto-retry (library + share view models) instead of "Can't reach Cachy".
+
+**P2 — polish:**
+5. **Reduced motion**: honor `MediaQuery.disableAnimations` via one shared gate covering all flutter_animate/AnimatedScale usages.
+6. **Onboarding brand pass**: replace lightning `_LogoBadge` with CachyGlyph, Fraunces w800 → w600, route type through `Brand` instead of direct GoogleFonts (onboarding_screen.dart, name_screen.dart). This screen precedes the new login screen, so it's touched anyway.
+7. **Motion curve**: `Motion.spring` easeOutBack → easeOutCubic (and the matching bounce cubic-bezier in app/web/index.html splash).
+
+**Minors (fold in where files are already open):** stale doc comments (library_screen.dart header), audit stray hex literals outside tokens, dev password constant gets a `ponytail:` note or moves behind the admin token.
+
+## One-time owner setup (~30 min)
+
+1. Create Firebase project; enable Anonymous + Google sign-in providers.
+2. Android: add `google-services.json`, register release-keystore SHA-1.
+3. Web: Firebase JS config in Flutter web init.
+4. HF Space env: `FIREBASE_PROJECT_ID` (token verification needs no service-account secret for `verify_id_token` with JWKS), `ADMIN_TOKEN`, quota env vars.
+
+## Out of scope (V2+)
+
+- On-device quantized model (opt-in "offline AI" past quota) — the `degraded` job flag + raw-bundle fetch is the designed extension point.
+- Play Store / App Store distribution, payments, email/password auth, multi-device conflict resolution beyond what Firebase uid sync gives for free.

docs/planning/specs/2026-07-10-v2-on-device-ai-design.md

@@ -0,0 +1,89 @@
+# Cachy V2: On-Device AI + Distribution Growth
+
+**Date:** 2026-07-10
+**Status:** Draft (V2 — build after the V1 auth/quota release ships and stabilizes)
+**Depends on:** `2026-07-10-public-distribution-auth-quotas-design.md` (V1) — specifically the `degraded` job flag, quota system, and Firebase identity.
+
+## Problem
+
+V1 caps each user at N AI cards/day so shared free-tier keys survive. Past quota, cards degrade to paragraph fallback. Power users want more without the developer paying for it. V1's answer was "wait until tomorrow"; V2's answer is: **bring your own compute** — an optional quantized model running on the user's phone.
+
+Also collected here: the rest of the deferred V2 items (store distribution, sustainability, claim-endpoint removal) so V2 has one source of truth.
+
+## Part 1 — On-device AI (headline)
+
+### Decision summary
+
+| Decision | Choice | Why |
+|---|---|---|
+| Split point | Server extracts (download, whisper, OCR → text bundle); device structures (bundle → card JSON) | Extraction needs yt-dlp/ffmpeg — impossible on phone. Structuring is pure text→JSON — exactly what a small LLM can do |
+| Trigger | Quota-degraded cards, when local model installed & enabled | Reuses V1's `degraded` flag; zero new quota logic |
+| Runtime | MediaPipe LLM Inference API (Android), via `flutter_gemma` or direct platform channel | Google-maintained, handles quantized Gemma models on-device, no NDK build of llama.cpp needed. Re-validate at build time — this space moves fast |
+| Model | Gemma 3 1B, int4 quantized (~550 MB) | Best small-model JSON-following per size; MediaPipe-native. Fallback candidate: Qwen2.5-1.5B-Instruct q4 |
+| Platforms | Android APK only | Web can't (practically); iOS not distributed yet |
+| Opt-in UX | Profile → "Offline AI" section: explicit download (~550 MB warning, Wi-Fi recommended), enable/disable toggle, delete model | Never surprise-download half a gigabyte |
+| Output guard | Client validates generated JSON against the card block schema; invalid → paragraph fallback (same as server) | Small models fail JSON sometimes; the card must always render |
+
+### Architecture
+
+1. **Server persists the bundle for degraded jobs.** Worker, on a `degraded` job, stores the extraction bundle (transcript + OCR text + caption — text only, a few KB) on the card row (`cards.raw_bundle` TEXT, nullable) instead of discarding it after paragraph fallback.
+2. **New endpoint** `GET /cards/{id}/bundle` (auth: owner only) → `{"bundle": str, "transcript": str, "caption": str}`; 404 when no stored bundle.
+3. **New endpoint** `POST /cards/{id}/structure` (auth: owner only) → accepts client-generated `{blocks: [...], one_liner, tags, ...}`, validated server-side with the **same** Pydantic validation the LLM path uses (never trust device output), replaces the paragraph card's content, clears `raw_bundle`, re-embeds.
+4. **Flutter `LocalAiService`:** model download manager (resumable, checksum), inference wrapper (`structureBundle(bundle) -> Map?`), prompt tuned for 1B models (short system prompt, few-shot single example, strict JSON instruction).
+5. **Flow:** card comes back `quota_degraded` → app checks Local AI enabled → fetches bundle → structures on-device (progress UI: "Generating on your phone…") → POSTs result → card upgrades in place. Failure at any step → paragraph card stays (user never worse off).
+
+### UX rules
+
+- Quota chip gains a second state: past quota + model installed → "Generating on your phone" instead of "AI recharges tomorrow".
+- Generation runs foreground-visible (reader shows progress), cancellable. No silent battery drain.
+- Settings shows model size on disk, last-used, delete button.
+
+### Explicitly rejected
+
+- Shipping the whole pipeline on-device (yt-dlp on Android: no).
+- Auto-downloading the model for everyone.
+- Trusting device JSON without server-side validation (auth'd users could inject arbitrary blocks otherwise).
+
+## Part 2 — Distribution & sustainability (V2 grab-bag)
+
+1. **Play Store**: $25 one-time, release signing already exists; needs privacy policy page (host on the HF Space at `/privacy`), Data Safety form (declares: account IDs, user content stored server-side), target API compliance. Do after auth ships — store review with anonymous+Google auth is straightforward.
+2. **Sustainability hooks**: GitHub Sponsors / Ko-fi link in Profile → About ("Keep Cachy free"); apply for GitHub Student Pack + Cerebras/Groq startup/edu credits to raise free ceilings.
+3. **Cleanup task**: delete `/auth/claim` endpoint + `claims` table ~1 month after V1 auth ships (calendar it).
+4. **Deferred still**: email/password auth, payments, iOS, multi-device conflict resolution. Not in V2 either unless users demand.
+
+## Part 3 — Private media (thumbnails/keyframes off the public HF dataset)
+
+### Problem
+
+Thumbnails and keyframes for every user's saved content currently live in a **public** HF dataset repo (`hf_media_repo` in `config.py`). The onboarding name screen promises "Your library stays private. Only you see your cards" — false for images today. Backend currently returns HF dataset URLs directly to the client (`resolveMedia` in `api_client.dart` joins bare paths, or passes through absolute URLs).
+
+### Decision
+
+Flip the HF dataset repo to **private**, add an owner-checked proxy endpoint, keep everything else (HF storage, `hf_api_key`) as-is. No new vendor — R2/S3 migration stays a "later, if bandwidth ever hurts" option, not part of this task (ponytail: don't add infrastructure for a problem that doesn't exist yet at this scale).
+
+### Architecture
+
+1. **Flip `hf_media_repo` to private** in the HF dataset settings (one-time manual step, no code).
+2. **New endpoint** `GET /media/{card_id}/{filename}` — `OwnerDep`-gated (must own the card, verified via `CardRow.owner_id`), streams bytes from the private HF dataset using the existing `hf_api_key` (server-side `hf_hub_download` or the HF `hfh` HTTP API), sets correct `content-type` from the file extension.
+3. **Backend media writer** (wherever thumbnails/keyframes are currently persisted, likely `store/media.py`) stores media under a `{card_id}/...` path scheme if not already, so the proxy route can validate ownership before any HF fetch.
+4. **Client**: `ApiClient.resolveMedia` continues to just join bare paths onto `baseUrl` — no change needed if the backend now returns `/media/{card_id}/{filename}` instead of absolute HF URLs (check `structuring.py`/`worker.py` for where media refs are written into card JSON; update to emit the proxy path instead of the raw HF URL).
+5. **Caching**: proxy response gets `Cache-Control: private, max-age=3600` (browser/client caches per-session; still requires re-auth on a fresh session, avoiding stale public exposure).
+
+### Testing
+
+- Backend: proxy route 404s for non-owned cards; 200 + correct bytes for owned cards; unauthenticated request 401.
+- Manual: confirm the HF dataset repo is actually private (attempt an unauthenticated raw HF URL fetch — must fail) after the flip.
+- Regression: existing cards' media still resolves after the path-scheme change (migrate old absolute-URL refs or keep a fallback branch in `resolveMedia`/backend for pre-migration cards).
+
+## Success criteria
+
+- A quota-exhausted user with the model installed gets a structured (not paragraph) card, fully offline of AI providers, in <2 min on a mid-range phone.
+- Server AI spend for that card: zero.
+- Users without the model see zero change.
+- No thumbnail or keyframe is fetchable without a valid owner session (public dataset browsing no longer exposes any user's media).
+
+## Testing
+
+- Backend: bundle persisted only for degraded jobs; `/bundle` owner-scoped 404/200; `/structure` rejects schema-invalid payloads, upgrades card, clears bundle.
+- Flutter: `LocalAiService` faked in tests (interface like `AuthService`); download-manager state machine (idle→downloading→ready→error) unit-tested; JSON-invalid model output → paragraph kept.
+- Manual: one real mid-range Android device before release (emulators lie about inference speed).