Natural click-driven presenter tour

Rework Present mode so every screen change is preceded by a visible cursor
landing and tap on the real widget, and follow the guided narrative
(home → card → concepts → catalog → nav bar → graph/chat → add).

- PresenterController: point→tap→act gesture choreography; navigation routed
through a visible tap on the nav control; rewritten kTour script; speech
watchdog so a missing web 'end' event can no longer hang the tour.
- PresenterSpotlight: hold the target through the 150ms geometry-poll jitter
(fixes the snapping glide); always render the cursor; add a tap ripple.
- AgentBus: onLibraryTab / onOpenCatalogItem hooks.
- Screens register real tap targets (nav tabs, top icons, plus, first card,
reader blocks/insight/references/action-bar); Concepts & Catalog now flip
the real library tab instead of a full-screen swap.
- .gitignore: scope the bare 'presenter' rule to /presenter/ so the Flutter
feature dir is tracked (it never was) while the root prototype stays ignored.

.gitignore

@@ -45,4 +45,6 @@ graph/
 context.md 
 i-want-you-to-spicy-dusk.md
 CACHY_OVERVIEW.md
-presenter
+# Root-level Python prototype agent only — anchored so it does NOT swallow the
+# Flutter feature dir app/lib/ui/features/presenter/.
+/presenter/

app/lib/data/services/api_client.dart

@@ -144,6 +144,27 @@ class ApiClient {
     return steps.whereType<Map<String, dynamic>>().toList();
   }
 
+  /// Relay a Present-mode event to the backend so it lands in the same
+  /// colour-coded pipeline log `start.py` shows — `debugPrint` alone only
+  /// reaches the terminal via the browser's DWDS log forwarding, which is
+  /// flaky, so this is the reliable path. Fire-and-forget: a failed relay
+  /// must never interrupt a live presentation, so errors are swallowed here.
+  void presenterLog(String message, {String level = 'info'}) {
+    unawaited(_postPresenterLog(message, level));
+  }
+
+  Future<void> _postPresenterLog(String message, String level) async {
+    try {
+      await _client.post(
+        _uri('/presenter/log'),
+        headers: {'content-type': 'application/json', ..._ownerHeader},
+        body: jsonEncode({'level': level, 'message': message}),
+      );
+    } catch (_) {
+      // Relay is best-effort; debugPrint is the fallback trail.
+    }
+  }
+
   // ------------------------------------------------------------------------- //
   // Cards
   // ------------------------------------------------------------------------- //

app/lib/ui/core/home_shell.dart

@@ -13,10 +13,8 @@ import 'package:provider/provider.dart';
 
 import '../features/actions/views/actions_screen.dart';
 import '../features/capture/views/capture_sheet.dart';
-import '../features/catalog/views/catalog_screen.dart';
 import '../features/collections/views/collections_screen.dart';
 import '../features/concepts/views/concept_detail_screen.dart';
-import '../features/concepts/views/concepts_screen.dart';
 import '../features/feed/views/connections_screen.dart';
 import '../features/feed/views/knowledge_feed_screen.dart';
 import '../features/graph/views/graph_screen.dart';
@@ -89,9 +87,21 @@ class _HomeShellState extends State<HomeShell> {
   PresenterController? _presenter;
   Widget? _presenterScreen; // GraphScreen/SearchScreen shown during the tour
 
+  // Spotlight anchor for the nav (bottom pill / side rail — only one mounted).
+  final GlobalKey _navKey = GlobalKey();
+
+  // Per-tab anchors so the presenter's cursor lands on the exact tab it taps,
+  // and the plus button so "add something" reads as a real click.
+  static const _navSpotlightIds = ['nav.home', 'nav.folders', 'nav.todo', 'nav.feed', 'nav.you'];
+  final List<GlobalKey> _navItemKeys =
+      List.generate(_navSpotlightIds.length, (_) => GlobalKey());
+  final GlobalKey _plusKey = GlobalKey();
+
   void _startPresenting() {
     final repo = context.read<CardRepository>();
     final bus = context.read<AgentBus>()
+      ..registerSpotlight('nav', _navKey)
+      ..registerSpotlight('home.plus', _plusKey)
       ..onNavigate = _goToView
       ..onOpenCard = _openCardInPresenter
       ..onCreateCard = _createCardInPresenter
@@ -99,6 +109,9 @@ class _HomeShellState extends State<HomeShell> {
       ..onOpenRabbitHole = _openRabbitHoleInPresenter
       ..onOpenCardChat = _openCardChatInPresenter
       ..onOpenLibraryChat = _openLibraryChatInPresenter;
+    for (var i = 0; i < _navSpotlightIds.length; i++) {
+      bus.registerSpotlight(_navSpotlightIds[i], _navItemKeys[i]);
+    }
     final controller = PresenterController(repository: repo, bus: bus);
     setState(() => _presenter = controller);
     controller.addListener(_onPresenterChanged);
@@ -156,8 +169,12 @@ class _HomeShellState extends State<HomeShell> {
         setState(() => _presenterScreen = ReaderScreen(cardId: result.cardId));
       }
       return result.cardId;
-    } catch (_) {
-      return null; // live demo: don't crash the tour if the pipeline is down
+    } catch (e, st) {
+      // Live demo: don't crash the tour if the pipeline is down, but the
+      // failure shouldn't vanish silently either.
+      debugPrint('[Presenter] create_card($url) failed: $e');
+      debugPrintStack(stackTrace: st, label: '[Presenter] create_card');
+      return null;
     }
   }
 
@@ -165,6 +182,12 @@ class _HomeShellState extends State<HomeShell> {
     if (_presenter?.phase == PresenterPhase.done) {
       final c = _presenter;
       c?.removeListener(_onPresenterChanged);
+      final bus = context.read<AgentBus>()
+        ..unregisterSpotlight('nav', _navKey)
+        ..unregisterSpotlight('home.plus', _plusKey);
+      for (var i = 0; i < _navSpotlightIds.length; i++) {
+        bus.unregisterSpotlight(_navSpotlightIds[i], _navItemKeys[i]);
+      }
       setState(() {
         _presenter = null;
         _presenterScreen = null;
@@ -195,15 +218,23 @@ class _HomeShellState extends State<HomeShell> {
         case 'search':
           _presenterScreen = const SearchScreen();
         case 'catalog':
-          _presenterScreen = const CatalogScreen();
+          // Concepts and Catalog are the library's own top tabs — flip the real
+          // tab (via the hook the library registers) instead of overlaying a
+          // separate screen, so it reads as a tap on the segment.
+          _presenterScreen = null;
+          _index = 0;
+          context.read<AgentBus>().onLibraryTab?.call(2);
         case 'concepts':
-          _presenterScreen = const ConceptsScreen();
+          _presenterScreen = null;
+          _index = 0;
+          context.read<AgentBus>().onLibraryTab?.call(1);
         case 'connections':
           _presenterScreen = const ConnectionsScreen();
         case 'library':
         default:
           _presenterScreen = null;
           _index = 0;
+          context.read<AgentBus>().onLibraryTab?.call(0);
       }
     });
   }
@@ -274,13 +305,23 @@ class _HomeShellState extends State<HomeShell> {
       floatingActionButtonLocation: FloatingActionButtonLocation.endFloat,
       floatingActionButton: selecting
           ? null
-          : _CaptureButton(onTap: () => showCaptureSheet(context)),
+          : KeyedSubtree(
+              key: _plusKey,
+              child: _CaptureButton(onTap: () => showCaptureSheet(context)),
+            ),
       bottomNavigationBar: selecting
           ? _SelectionNavSlot(
               vm: vm,
               onConfirmDelete: () => _confirmBulkDelete(context, vm),
             )
-          : _GlassNav(index: _index, onSelect: _select),
+          : KeyedSubtree(
+              key: _navKey,
+              child: _GlassNav(
+                index: _index,
+                onSelect: _select,
+                itemKeys: _navItemKeys,
+              ),
+            ),
     );
   }
 
@@ -329,10 +370,13 @@ class _HomeShellState extends State<HomeShell> {
           Positioned.fill(
             child: Row(
               children: [
-                _GlassRail(
-                  index: _index,
-                  onSelect: _select,
-                  onCapture: () => showCaptureSheet(context),
+                KeyedSubtree(
+                  key: _navKey,
+                  child: _GlassRail(
+                    index: _index,
+                    onSelect: _select,
+                    onCapture: () => showCaptureSheet(context),
+                  ),
                 ),
                 Expanded(
                   child: Stack(
@@ -357,7 +401,10 @@ class _HomeShellState extends State<HomeShell> {
   List<Widget> _presenterLayers(BuildContext context) {
     if (_presenter != null) {
       return [
-        PresenterSpotlight(controller: _presenter!),
+        PresenterSpotlight(
+          controller: _presenter!,
+          bus: context.read<AgentBus>(),
+        ),
         PresenterOverlay(controller: _presenter!),
       ];
     }
@@ -517,10 +564,18 @@ class _GlassRail extends StatelessWidget {
 // ── Mobile floating pill nav ───────────────────────────────────────────────── //
 
 class _GlassNav extends StatelessWidget {
-  const _GlassNav({required this.index, required this.onSelect});
+  const _GlassNav({
+    required this.index,
+    required this.onSelect,
+    this.itemKeys = const [],
+  });
   final int index;
   final ValueChanged<int> onSelect;
 
+  /// Per-tab spotlight anchors so the presenter's cursor lands on the exact
+  /// tab it taps. Empty when not presenting.
+  final List<GlobalKey> itemKeys;
+
   @override
   Widget build(BuildContext context) {
     final b = Theme.of(context).brightness;
@@ -562,10 +617,13 @@ class _GlassNav extends StatelessWidget {
                   children: [
                     for (var i = 0; i < _navItems.length; i++)
                       Expanded(
-                        child: _NavBtn(
-                          def: _navItems[i],
-                          selected: index == i,
-                          onTap: () => onSelect(i),
+                        child: KeyedSubtree(
+                          key: i < itemKeys.length ? itemKeys[i] : null,
+                          child: _NavBtn(
+                            def: _navItems[i],
+                            selected: index == i,
+                            onTap: () => onSelect(i),
+                          ),
                         ),
                       ),
                   ],

app/lib/ui/core/safe_notifier.dart

@@ -0,0 +1,31 @@
+/// A [ChangeNotifier] that silently ignores `notifyListeners()` once disposed.
+///
+/// View models kick off async work (a network turn, a bootstrap) and then
+/// `notifyListeners()` when it resolves. If the screen is torn down first —
+/// the user pops it, or Present mode navigates on before the request
+/// finishes — that late notify hits a disposed notifier and throws
+/// "used after being disposed". Guarding every call site is error-prone;
+/// guarding the notifier once is not.
+library;
+
+import 'package:flutter/foundation.dart';
+
+mixin SafeNotifier on ChangeNotifier {
+  bool _disposed = false;
+
+  /// Whether [dispose] has run — useful for bailing out of in-flight async
+  /// work before it touches other disposed state.
+  bool get disposed => _disposed;
+
+  @override
+  void dispose() {
+    _disposed = true;
+    super.dispose();
+  }
+
+  @override
+  void notifyListeners() {
+    if (_disposed) return;
+    super.notifyListeners();
+  }
+}

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

@@ -6,10 +6,11 @@ import 'package:flutter/foundation.dart';
 
 import '../../../../data/repositories/card_repository.dart';
 import '../../../../domain/models/concept.dart';
+import '../../../core/safe_notifier.dart';
 
 enum ConceptsStatus { idle, loading, ready, error, empty }
 
-class ConceptsViewModel extends ChangeNotifier {
+class ConceptsViewModel extends ChangeNotifier with SafeNotifier {
   ConceptsViewModel({required CardRepository repository})
       : _repository = repository {
     _repository.addListener(_onRepoChange);

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

@@ -59,8 +59,10 @@ class _FeedViewState extends State<_FeedView> {
   int _page = 0;
 
   // Agent driving: expose feed paging to the presenter agent while mounted.
+  // The page key gives its spotlight the pager's real bounds.
   AgentBus? _bus;
   FeedAgentHooks? _hooks;
+  final _pageKey = GlobalKey();
 
   int get _total {
     if (!mounted) return 0;
@@ -82,12 +84,14 @@ class _FeedViewState extends State<_FeedView> {
     );
     _hooks = hooks;
     _bus!.attachFeed(hooks);
+    _bus!.registerSpotlight('feed.page', _pageKey);
   }
 
   @override
   void dispose() {
     final h = _hooks;
     if (h != null) _bus?.detachFeed(h);
+    _bus?.unregisterSpotlight('feed.page', _pageKey);
     _controller.dispose();
     _focusNode.dispose();
     super.dispose();
@@ -191,6 +195,7 @@ class _FeedViewState extends State<_FeedView> {
     return ScrollConfiguration(
       behavior: const _FeedScrollBehavior(),
       child: PageView.builder(
+        key: _pageKey,
         controller: _controller,
         scrollDirection: Axis.vertical,
         itemCount: vm.items.length,

app/lib/ui/features/graph/views/graph_screen.dart

@@ -166,9 +166,11 @@ class _GraphScreenState extends State<GraphScreen>
   bool _showConcepts = true;
 
   // Agent driving: the presenter agent operates the graph through these hooks
-  // while this screen is mounted (see AgentBus).
+  // while this screen is mounted (see AgentBus). The canvas key gives its
+  // spotlight the real canvas bounds.
   AgentBus? _bus;
   GraphAgentHooks? _hooks;
+  final _canvasKey = GlobalKey();
 
   @override
   void initState() {
@@ -193,12 +195,14 @@ class _GraphScreenState extends State<GraphScreen>
     );
     _hooks = hooks;
     _bus!.attachGraph(hooks);
+    _bus!.registerSpotlight('graph.canvas', _canvasKey);
   }
 
   @override
   void dispose() {
     final h = _hooks;
     if (h != null) _bus?.detachGraph(h);
+    _bus?.unregisterSpotlight('graph.canvas', _canvasKey);
     _ticker.dispose();
     super.dispose();
   }
@@ -968,6 +972,7 @@ class _GraphScreenState extends State<GraphScreen>
               final size =
                   Size(constraints.maxWidth, constraints.maxHeight);
               return ClipRect(
+                key: _canvasKey,
                 child: GestureDetector(
                   onScaleStart: (d) => _onScaleStart(d, size),
                   onScaleUpdate: (d) => _onScaleUpdate(d, size),

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

@@ -7,6 +7,7 @@ import 'package:flutter/foundation.dart';
 
 import '../../../../data/repositories/card_repository.dart';
 import '../../../../data/services/api_client.dart';
+import '../../../core/safe_notifier.dart';
 
 class LibraryChatMessage {
   const LibraryChatMessage({required this.role, required this.content});
@@ -17,7 +18,7 @@ class LibraryChatMessage {
   Map<String, String> toWire() => {'role': role, 'content': content};
 }
 
-class LibraryChatViewModel extends ChangeNotifier {
+class LibraryChatViewModel extends ChangeNotifier with SafeNotifier {
   LibraryChatViewModel({required CardRepository repository})
       : _repository = repository;
 

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

@@ -9,10 +9,11 @@ import 'package:flutter/foundation.dart';
 import '../../../../data/repositories/card_repository.dart';
 import '../../../../domain/models/card.dart';
 import '../../../../domain/models/enums.dart';
+import '../../../core/safe_notifier.dart';
 
 enum LibraryStatus { idle, loading, ready, error, empty }
 
-class LibraryViewModel extends ChangeNotifier {
+class LibraryViewModel extends ChangeNotifier with SafeNotifier {
   LibraryViewModel({required CardRepository repository})
       : _repository = repository {
     _repository.addListener(_onRepoChange);

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

@@ -33,6 +33,7 @@ import '../../catalog/views/catalog_screen.dart';
 import '../../concepts/views/concepts_screen.dart';
 import '../../graph/views/graph_screen.dart';
 import '../../library/views/library_chat_screen.dart';
+import '../../presenter/agent_bus.dart';
 import '../../reader/views/reader_screen.dart';
 import '../../search/views/search_screen.dart';
 import '../view_models/library_view_model.dart';
@@ -50,18 +51,62 @@ class LibraryScreen extends StatelessWidget {
   }
 }
 
-class _LibraryView extends StatelessWidget {
+class _LibraryView extends StatefulWidget {
   const _LibraryView();
 
+  @override
+  State<_LibraryView> createState() => _LibraryViewState();
+}
+
+class _LibraryViewState extends State<_LibraryView>
+    with SingleTickerProviderStateMixin {
+  late final TabController _tabs = TabController(length: 3, vsync: this);
+
+  // Presenter spotlight anchors: the top segments and top-bar icons the agent
+  // taps live here. Registered while mounted; the presenter's cursor resolves
+  // them to real geometry.
+  final _conceptsTabKey = GlobalKey();
+  final _catalogTabKey = GlobalKey();
+  final _graphKey = GlobalKey();
+  final _chatKey = GlobalKey();
+  final _searchKey = GlobalKey();
+  AgentBus? _bus;
+
+  @override
+  void didChangeDependencies() {
+    super.didChangeDependencies();
+    if (_bus != null) return;
+    _bus = context.read<AgentBus>()
+      ..onLibraryTab = (i) {
+        if (i >= 0 && i < _tabs.length) _tabs.animateTo(i);
+      }
+      ..registerSpotlight('library.tab.concepts', _conceptsTabKey)
+      ..registerSpotlight('library.tab.catalog', _catalogTabKey)
+      ..registerSpotlight('top.graph', _graphKey)
+      ..registerSpotlight('top.chat', _chatKey)
+      ..registerSpotlight('top.search', _searchKey);
+  }
+
+  @override
+  void dispose() {
+    _bus
+      ?..onLibraryTab = null
+      ..unregisterSpotlight('library.tab.concepts', _conceptsTabKey)
+      ..unregisterSpotlight('library.tab.catalog', _catalogTabKey)
+      ..unregisterSpotlight('top.graph', _graphKey)
+      ..unregisterSpotlight('top.chat', _chatKey)
+      ..unregisterSpotlight('top.search', _searchKey);
+    _tabs.dispose();
+    super.dispose();
+  }
+
   @override
   Widget build(BuildContext context) {
     final vm = context.watch<LibraryViewModel>();
     final scheme = Theme.of(context).colorScheme;
     final isDesktop = MediaQuery.sizeOf(context).width >= Insets.desktop;
 
-    return DefaultTabController(
-      length: 3,
-      child: Scaffold(
+    return Scaffold(
         backgroundColor: Colors.transparent,
         appBar: AppBar(
           titleSpacing: Insets.page,
@@ -76,6 +121,7 @@ class _LibraryView extends StatelessWidget {
                 ),
               ),
             IconButton(
+              key: _graphKey,
               tooltip: 'Graph',
               icon: const PhosphorIcon(PhosphorIconsRegular.graph),
               onPressed: () => Navigator.of(context).push(
@@ -83,6 +129,7 @@ class _LibraryView extends StatelessWidget {
               ),
             ),
             IconButton(
+              key: _chatKey,
               tooltip: 'Chat',
               icon: const PhosphorIcon(PhosphorIconsRegular.chats),
               onPressed: () => Navigator.of(context).push(
@@ -90,6 +137,7 @@ class _LibraryView extends StatelessWidget {
               ),
             ),
             IconButton(
+              key: _searchKey,
               tooltip: 'Search',
               icon: const PhosphorIcon(PhosphorIconsRegular.magnifyingGlass),
               onPressed: () => Navigator.of(context).push(
@@ -113,6 +161,7 @@ class _LibraryView extends StatelessWidget {
                       borderRadius: BorderRadius.circular(12),
                     ),
                     child: TabBar(
+                      controller: _tabs,
                       dividerColor: Colors.transparent,
                       indicator: BoxDecoration(
                         color: scheme.surface,
@@ -127,10 +176,10 @@ class _LibraryView extends StatelessWidget {
                       unselectedLabelColor: scheme.onSurfaceVariant,
                       labelStyle: Brand.label(size: 12, weight: FontWeight.w700),
                       unselectedLabelStyle: Brand.label(size: 12, weight: FontWeight.w500),
-                      tabs: const [
-                        Tab(text: 'CARDS'),
-                        Tab(text: 'CONCEPTS'),
-                        Tab(text: 'CATALOG'),
+                      tabs: [
+                        const Tab(text: 'CARDS'),
+                        Tab(key: _conceptsTabKey, text: 'CONCEPTS'),
+                        Tab(key: _catalogTabKey, text: 'CATALOG'),
                       ],
                     ),
                   ),
@@ -139,15 +188,15 @@ class _LibraryView extends StatelessWidget {
             ),
           ),
         ),
-        body: const TabBarView(
-          children: [
+        body: TabBarView(
+          controller: _tabs,
+          children: const [
             _CardsTab(),
             ConceptsScreen(),
             CatalogScreen(),
           ],
         ),
-      ),
-    );
+      );
   }
 }
 
@@ -167,12 +216,27 @@ class _CardsTabState extends State<_CardsTab> {
   /// The grid index that most recently received keyboard focus.
   int _lastFocusedIndex = 0;
 
+  // Presenter agent: expose the grid's scroll so the agent can browse the
+  // library while narrating.
+  final _gridScroll = ScrollController();
+  final _firstCardKey = GlobalKey();
+  AgentBus? _bus;
+
   @override
   void initState() {
     super.initState();
     _fraction = context.read<AppController>().splitPaneFraction;
   }
 
+  @override
+  void didChangeDependencies() {
+    super.didChangeDependencies();
+    if (_bus != null) return;
+    _bus = context.read<AgentBus>()
+      ..registerScrollable('library', _gridScroll)
+      ..registerSpotlight('card.first', _firstCardKey);
+  }
+
   /// Grows or shrinks [_focusNodes] to exactly [count] nodes.
   /// New nodes are equipped with a listener that updates [_lastFocusedIndex].
   void _ensureFocusNodes(int count) {
@@ -192,6 +256,10 @@ class _CardsTabState extends State<_CardsTab> {
 
   @override
   void dispose() {
+    _bus
+      ?..unregisterScrollable('library', _gridScroll)
+      ..unregisterSpotlight('card.first', _firstCardKey);
+    _gridScroll.dispose();
     for (final node in _focusNodes) {
       node.dispose();
     }
@@ -426,6 +494,7 @@ class _CardsTabState extends State<_CardsTab> {
             child: FocusTraversalGroup(
               policy: OrderedTraversalPolicy(),
               child: GridView.builder(
+                controller: _gridScroll,
                 padding: const EdgeInsets.fromLTRB(Insets.page, 8, Insets.page, 96),
                 physics: const AlwaysScrollableScrollPhysics(),
                 gridDelegate: SliverGridDelegateWithFixedCrossAxisCount(
@@ -444,7 +513,7 @@ class _CardsTabState extends State<_CardsTab> {
                       (Platform.isMacOS ||
                           Platform.isWindows ||
                           Platform.isLinux);
-                  return CardTile(
+                  final tile = CardTile(
                     focusNode: _focusNodes[i],
                     card: card,
                     api: api,
@@ -493,6 +562,11 @@ class _CardsTabState extends State<_CardsTab> {
                     },
                     onDelete: () => vm.delete(card.cardId),
                   );
+                  // Anchor the first tile so the presenter's cursor lands on a
+                  // real card before opening it.
+                  return i == 0
+                      ? KeyedSubtree(key: _firstCardKey, child: tile)
+                      : tile;
                 },
               ),
             ),

app/lib/ui/features/presenter/agent_bus.dart

@@ -0,0 +1,289 @@
+/// The bridge that lets the presenting agent actually *operate* the app.
+///
+/// Cachy has no central controller registry — each feature keeps its live UI
+/// state private inside its own `State`. Rather than rewire every screen into a
+/// global controller, the agent talks to screens through this bus:
+///
+///  * the host shell registers [onNavigate] / [onOpenCard] / [onCreateCard] so
+///    the agent can move between views and open cards, and
+///  * interactive screens (graph, feed, search) register a small set of
+///    imperative *hooks* while they're mounted, which the agent invokes to
+///    drive them live (focus a graph node, advance the feed, run a search).
+///
+/// A screen attaches its hooks in `initState`/`didChangeDependencies` and
+/// detaches them in `dispose`, so the agent only ever drives what's on screen.
+library;
+
+import 'package:flutter/widgets.dart';
+
+import '../../../domain/models/graph.dart';
+
+/// A single thing the agent can do: a verb ([type]) plus its arguments.
+///
+/// The vocabulary is shared with the backend `/presenter/ask` endpoint, which
+/// returns these to answer audience questions by *performing* them.
+@immutable
+class AgentAction {
+  const AgentAction(this.type, [this.args = const {}]);
+
+  /// One of: navigate, create_card, search, open_card, graph_focus,
+  /// graph_open, graph_wander, graph_reset, feed_next, feed_prev, wait.
+  final String type;
+  final Map<String, dynamic> args;
+
+  String? get view => args['view'] as String?;
+  String? get query => args['query'] as String?;
+  String? get url => args['url'] as String?;
+
+  factory AgentAction.fromJson(Map<String, dynamic> json) => AgentAction(
+        (json['do'] as String?)?.trim() ?? 'none',
+        Map<String, dynamic>.from(json)..remove('do'),
+      );
+}
+
+/// One beat of narration: optionally [say] something, optionally do [action].
+/// Beats run in order; within a beat speech starts first and the action fires a
+/// moment later *while* the agent is still talking — the way a human presenter
+/// narrates over their own clicks.
+@immutable
+class AgentBeat {
+  const AgentBeat({this.say, this.action, this.view, this.focus});
+
+  final String? say;
+  final AgentAction? action;
+
+  /// Convenience for tour beats that just switch view before speaking.
+  final String? view;
+
+  /// Optional spotlight target id (see [AgentBus.spotlightRect]); when absent
+  /// the target is derived from the action type.
+  final String? focus;
+
+  factory AgentBeat.fromJson(Map<String, dynamic> json) {
+    final rawAction = json['action'];
+    return AgentBeat(
+      say: (json['say'] as String?)?.trim(),
+      action: rawAction is Map<String, dynamic>
+          ? AgentAction.fromJson(rawAction)
+          : null,
+    );
+  }
+}
+
+/// Imperative controls a mounted [graph screen] exposes to the agent.
+class GraphAgentHooks {
+  GraphAgentHooks({
+    required this.nodes,
+    required this.isReady,
+    required this.focus,
+    required this.open,
+    required this.wander,
+    required this.reset,
+    required this.filterCluster,
+    required this.toggleConcepts,
+  });
+
+  /// Snapshot of the currently loaded graph nodes (empty until loaded).
+  final List<GraphNode> Function() nodes;
+
+  /// True once graph data is loaded and the screen can be driven.
+  final bool Function() isReady;
+
+  /// Center + select a node and dive into its neighborhood (ego view).
+  final Future<void> Function(String nodeId) focus;
+
+  /// Open a node's underlying card/concept.
+  final Future<void> Function(String nodeId) open;
+
+  /// Reheat the physics + drift the view so the layout visibly comes alive.
+  final Future<void> Function() wander;
+
+  /// Exit ego/local mode and recenter.
+  final void Function() reset;
+
+  /// Apply a cluster filter so only one community stays visible.
+  final Future<void> Function() filterCluster;
+
+  /// Toggle the concept hub nodes on/off.
+  final Future<void> Function() toggleConcepts;
+}
+
+/// Imperative controls a mounted feed exposes to the agent.
+class FeedAgentHooks {
+  FeedAgentHooks({
+    required this.next,
+    required this.prev,
+    required this.count,
+    required this.shuffle,
+  });
+
+  final void Function() next;
+  final void Function() prev;
+  final int Function() count;
+
+  /// Reshuffle the feed into a fresh set of moments.
+  final void Function() shuffle;
+}
+
+/// Imperative controls a mounted search screen exposes to the agent.
+class SearchAgentHooks {
+  SearchAgentHooks({required this.run, required this.filter});
+
+  /// Type a query into the search box and run it.
+  final void Function(String query) run;
+
+  /// Apply the first available content-type filter to the current results.
+  final void Function() filter;
+}
+
+/// Imperative controls a mounted reader exposes to the agent, so it can show
+/// that cards are interactive (checkable steps and checklists) live.
+class ReaderAgentHooks {
+  ReaderAgentHooks({
+    required this.isReady,
+    required this.toggleCheck,
+    required this.toggleStep,
+  });
+
+  /// True once the card is loaded.
+  final bool Function() isReady;
+
+  /// Toggle the first checklist item; returns true if there was one.
+  final Future<bool> Function() toggleCheck;
+
+  /// Mark the first step complete; returns true if there was one.
+  final Future<bool> Function() toggleStep;
+}
+
+/// Shared channel between the [PresenterController] agent and the app.
+///
+/// Provided app-wide (see `main.dart`). The shell sets the navigation callbacks;
+/// feature screens attach/detach their hooks as they mount/unmount.
+class AgentBus extends ChangeNotifier {
+  // ── Shell-provided navigation ─────────────────────────────────────────── //
+
+  /// Switch the visible view. Recognized: library, feed, graph, search,
+  /// collections, actions, profile, catalog, concepts, connections.
+  void Function(String view)? onNavigate;
+
+  /// Open a card in the reader (kept under the agent glyph, not pushed).
+  Future<void> Function(String cardId)? onOpenCard;
+
+  /// Submit a URL to the live pipeline and open the resulting card.
+  Future<String?> Function(String url)? onCreateCard;
+
+  /// Open a concept's detail (auto-defines if it has no definition yet).
+  Future<void> Function(String conceptId, String name)? onOpenConcept;
+
+  /// Open the rabbit-hole explorer for a card, seeded with a topic.
+  Future<void> Function(String cardId, String seed)? onOpenRabbitHole;
+
+  /// Open the grounded per-card chat, seeded with a question it auto-asks.
+  Future<void> Function(String cardId, String title, String seed)?
+      onOpenCardChat;
+
+  /// Open the whole-library chat, seeded with a question it auto-asks.
+  Future<void> Function(String seed)? onOpenLibraryChat;
+
+  /// Switch the library's top segment (0 = Cards, 1 = Concepts, 2 = Catalog).
+  /// Concepts and Catalog are tabs inside the library, not separate screens —
+  /// the agent flips the real tab so the switch reads as a tap on the tab, not
+  /// a full-screen swap.
+  void Function(int index)? onLibraryTab;
+
+  /// Open the first catalog item's detail and generate its info (the catalog
+  /// "Fetch info" demo). No-op if the catalog is empty.
+  Future<void> Function()? onOpenCatalogItem;
+
+  // ── Screen-provided hooks (present only while that screen is mounted) ──── //
+
+  GraphAgentHooks? graph;
+  FeedAgentHooks? feed;
+  SearchAgentHooks? search;
+  ReaderAgentHooks? reader;
+
+  void attachGraph(GraphAgentHooks hooks) => graph = hooks;
+  void detachGraph(GraphAgentHooks hooks) {
+    if (identical(graph, hooks)) graph = null;
+  }
+
+  void attachFeed(FeedAgentHooks hooks) => feed = hooks;
+  void detachFeed(FeedAgentHooks hooks) {
+    if (identical(feed, hooks)) feed = null;
+  }
+
+  void attachSearch(SearchAgentHooks hooks) => search = hooks;
+  void detachSearch(SearchAgentHooks hooks) {
+    if (identical(search, hooks)) search = null;
+  }
+
+  void attachReader(ReaderAgentHooks hooks) => reader = hooks;
+  void detachReader(ReaderAgentHooks hooks) {
+    if (identical(reader, hooks)) reader = null;
+  }
+
+  // ── Spotlight target registry ─────────────────────────────────────────── //
+  //
+  // Screens tag the widget the agent acts on (search field, graph canvas, nav
+  // bar…) with a GlobalKey and register it here while mounted. The spotlight
+  // layer resolves live geometry from the key, so the guided-focus hole hugs
+  // the real widget instead of a guessed screen region.
+
+  final Map<String, GlobalKey> _spotlightKeys = {};
+
+  void registerSpotlight(String id, GlobalKey key) => _spotlightKeys[id] = key;
+
+  void unregisterSpotlight(String id, GlobalKey key) {
+    if (identical(_spotlightKeys[id], key)) _spotlightKeys.remove(id);
+  }
+
+  /// Current global-coordinate bounds of a registered target, or null while it
+  /// isn't mounted / laid out.
+  ///
+  /// A GlobalKey can still resolve a `currentContext` for an element that has
+  /// been deactivated (mid screen-swap during Present mode) — calling
+  /// `findRenderObject()` on it throws "Cannot get renderObject of inactive
+  /// element". Guard on `context.mounted` and catch defensively so a
+  /// transitioning target just reads as "not visible yet" instead of crashing
+  /// the frame.
+  Rect? spotlightRect(String id) {
+    final context = _spotlightKeys[id]?.currentContext;
+    if (context == null || !context.mounted) return null;
+    try {
+      final box = context.findRenderObject();
+      if (box is! RenderBox || !box.attached || !box.hasSize) return null;
+      return box.localToGlobal(Offset.zero) & box.size;
+    } catch (_) {
+      return null;
+    }
+  }
+
+  // ── Scrollable registry ───────────────────────────────────────────────── //
+  //
+  // Screens with a meaningful scroll surface (library grid, reader body)
+  // register their ScrollController here while mounted, so the agent can
+  // scroll the app the way a person would while presenting.
+
+  final Map<String, ScrollController> _scrollables = {};
+
+  void registerScrollable(String id, ScrollController controller) =>
+      _scrollables[id] = controller;
+
+  void unregisterScrollable(String id, ScrollController controller) {
+    if (identical(_scrollables[id], controller)) _scrollables.remove(id);
+  }
+
+  /// Smoothly scroll a registered surface by [dy] pixels (negative = up),
+  /// clamped to its extent. No-op while the surface isn't mounted.
+  Future<void> scrollBy(String id, double dy) async {
+    final c = _scrollables[id];
+    if (c == null || !c.hasClients) return;
+    final target =
+        (c.offset + dy).clamp(0.0, c.position.maxScrollExtent);
+    await c.animateTo(
+      target,
+      duration: const Duration(milliseconds: 900),
+      curve: Curves.easeInOutCubic,
+    );
+  }
+}

app/lib/ui/features/presenter/presenter_controller.dart

@@ -0,0 +1,1102 @@
+/// Drives the in-app "Present" mode: a self-navigating, spoken tour that
+/// actually *operates* Cachy live — creating a card, running a search, scrolling
+/// the feed, driving the knowledge graph — while narrating. The audience (or the
+/// presenter) can tap the agent glyph any time to ask a question or hand it a
+/// task; the agent stops the tour, performs it for real, asks if anything else
+/// is needed, and then resumes the tour where it left off.
+///
+/// Speech uses the browser's Web Speech API via `flutter_tts` (free, any OS, no
+/// install). Question answering runs server-side (`/presenter/ask`), which
+/// returns a sequence of [AgentBeat]s (say + do) so answers are *performed*, not
+/// just spoken. Everything the agent can do goes through the [AgentBus].
+library;
+
+import 'dart:async';
+
+import 'package:flutter/foundation.dart';
+import 'package:flutter_tts/flutter_tts.dart';
+
+import '../../../data/repositories/card_repository.dart';
+import '../../../domain/models/card.dart' as model;
+import '../../../domain/models/concept.dart';
+import '../../../domain/models/graph.dart';
+import 'agent_bus.dart';
+
+enum PresenterPhase { idle, speaking, thinking, acting, done }
+
+/// The scripted tour. Each beat may switch [view], [say] a line, and/or run an
+/// [action]; speech starts first and the action fires while the agent is still
+/// talking, the way a human narrates over their own clicks. Lines are written
+/// to be *spoken* — contractions, transitions, reactions — and avoid acronyms
+/// so both the voice and the on-screen caption read naturally.
+const List<AgentBeat> kTour = [
+  // ── 1. Home ──────────────────────────────────────────────────────────────
+  AgentBeat(
+    view: 'library',
+    say: "Hey! I'm Cachy's presenter, and instead of a slide deck I'll just "
+        "drive the app for real. This is live — tap me any time, ask anything, "
+        "and I'll show you.",
+  ),
+  AgentBeat(
+    focus: 'content',
+    say: "So this is home. Every reel, short, or article you share into Cachy "
+        "comes back as a knowledge card. Let me scroll down through the shelf "
+        "so you can see the collection... and back up to the top.",
+    action: AgentAction('scroll', {'target': 'library', 'dy': 720, 'sweep': true}),
+  ),
+
+  // ── 2. Open the first card → the reader ──────────────────────────────────
+  AgentBeat(
+    focus: 'card.first',
+    say: "Let me open this first card so you can see what's actually inside "
+        "one.",
+    action: AgentAction('open_card', {'query': 'auto'}),
+  ),
+  AgentBeat(
+    focus: 'reader.blocks',
+    say: "This is the good part. From any source online, Cachy pulls out proper "
+        "structured notes — a one-liner, a summary, then clean blocks: steps, "
+        "key facts, callouts. Let me scroll through them.",
+    action: AgentAction('scroll', {'target': 'reader', 'dy': 640, 'sweep': true}),
+  ),
+  AgentBeat(
+    focus: 'reader.insight',
+    say: "Further down there's a 'Going deeper' section — that's the AI adding "
+        "the analysis the source only hinted at.",
+    action: AgentAction('point'),
+  ),
+  AgentBeat(
+    focus: 'reader.references',
+    say: "Then references — books, films, products the card mentions. Here's "
+        "the trick: press and hold any reference and it's saved straight to "
+        "your catalog.",
+    action: AgentAction('point'),
+  ),
+  AgentBeat(
+    focus: 'reader.ask',
+    say: "Down on the bottom strip: Ask lets you chat with just this card, and "
+        "next to it is whatever action fits the content — share it, turn it "
+        "into a shopping list, drop it on a map.",
+    action: AgentAction('point'),
+  ),
+  AgentBeat(
+    focus: 'reader.more',
+    say: "And the three dots hide the rest — copy, share, shopping list, and "
+        "more.",
+    action: AgentAction('point'),
+  ),
+  AgentBeat(
+    focus: 'reader.insight',
+    say: "One more from in here — 'Dive deeper' opens a rabbit hole, pulling a "
+        "thread from the card out into wider knowledge. Watch.",
+    action: AgentAction('rabbit_hole', {'query': 'auto'}),
+  ),
+
+  // ── 3. Concepts (top segment) ────────────────────────────────────────────
+  AgentBeat(
+    view: 'concepts',
+    focus: 'content',
+    say: "Back up top there are three segments. This one's Concepts — shared "
+        "ideas Cachy mines across your cards and stitches together. Let me "
+        "open one and define it on the spot.",
+    action: AgentAction('define_concept', {'query': 'auto'}),
+  ),
+
+  // ── 4. Catalog (top segment) ─────────────────────────────────────────────
+  AgentBeat(
+    view: 'catalog',
+    focus: 'catalog.item',
+    say: "Next segment: the catalog. Remember those references you can hold to "
+        "save? They land here. Tap one and the AI fills in everything it can "
+        "find about it.",
+    action: AgentAction('catalog_item'),
+  ),
+
+  // ── 5. Nav bar, one by one ───────────────────────────────────────────────
+  AgentBeat(
+    view: 'collections',
+    focus: 'folders.create',
+    say: "Now the bottom bar. Folders — your cards get auto-sorted in here, and "
+        "you can make your own. Let me create one.",
+    action: AgentAction('create_collection', {'name': 'Demo Folder'}),
+  ),
+  AgentBeat(
+    focus: 'content',
+    say: "...and drop a card into it. Done.",
+    action: AgentAction('move_card'),
+  ),
+  AgentBeat(
+    view: 'actions',
+    focus: 'todo.item',
+    say: "To-do. When you mark something as 'track in actions' inside a card, "
+        "its tasks show up here. Let me follow one in.",
+    action: AgentAction('follow_actions'),
+  ),
+  AgentBeat(
+    focus: 'todo.item',
+    say: "Tap an item and it expands to every task from that one note — and "
+        "Cachy keeps nudging you until they're done.",
+    action: AgentAction('toggle_action_item'),
+  ),
+  AgentBeat(
+    view: 'feed',
+    focus: 'feed.page',
+    say: "Feed. Think of it like your Instagram feed, but it's your own saved "
+        "knowledge — one-liners you can flick through. Let me scroll a few.",
+    action: AgentAction('feed_next'),
+  ),
+  AgentBeat(
+    focus: 'feed.page',
+    say: "Keep going, or shuffle for a fresh set.",
+    action: AgentAction('feed_shuffle'),
+  ),
+  AgentBeat(
+    view: 'profile',
+    focus: 'content',
+    say: "Last tab is You — settings and your library stats. Nothing fancy, "
+        "it's just home base.",
+    action: AgentAction('point'),
+  ),
+
+  // ── 6. Top icons: Graph, Chat ────────────────────────────────────────────
+  AgentBeat(
+    view: 'library',
+    say: "Back home for a second — up top there are two more.",
+  ),
+  AgentBeat(
+    focus: 'top.graph',
+    say: "The graph. Every card and concept is a node, linked by meaning. Watch "
+        "the connections — and let me pull into one node's neighborhood.",
+    action: AgentAction('graph_wander'),
+  ),
+  AgentBeat(
+    focus: 'graph.canvas',
+    action: AgentAction('graph_focus', {'query': 'auto'}),
+  ),
+  AgentBeat(
+    view: 'library',
+    say: "And the chat.",
+  ),
+  AgentBeat(
+    focus: 'top.chat',
+    say: "This one talks to your whole library at once — ask anything across "
+        "everything you've saved and it answers from your own notes.",
+    action: AgentAction('library_chat', {
+      'query': 'What are the main themes across everything saved here?',
+    }),
+  ),
+
+  // ── 7. Adding something to Cachy ─────────────────────────────────────────
+  AgentBeat(
+    view: 'library',
+    say: "Last thing — let's add something new, live.",
+  ),
+  AgentBeat(
+    focus: 'home.plus',
+    say: "I'll hit the plus button, paste in a link, and Cachy runs the whole "
+        "pipeline — fetching the page, pulling the text, and shaping it into a "
+        "card while we watch.",
+    action: AgentAction('create_card', {
+      'url': 'https://en.wikipedia.org/wiki/Spaced_repetition',
+    }),
+  ),
+  AgentBeat(
+    focus: 'reader.blocks',
+    say: "And there it is — a brand-new card, built from nothing. That's Cachy. "
+        "I'm not going anywhere though — tap me, ask me anything, or hand me a "
+        "task.",
+    action: AgentAction('scroll', {'target': 'reader', 'dy': 560, 'sweep': true}),
+  ),
+];
+
+class PresenterController extends ChangeNotifier {
+  PresenterController({required CardRepository repository, required AgentBus bus})
+      : _repo = repository,
+        _bus = bus {
+    _initTts();
+  }
+
+  final CardRepository _repo;
+  final AgentBus _bus;
+  final FlutterTts _tts = FlutterTts();
+
+  PresenterPhase phase = PresenterPhase.idle;
+
+  /// The line currently being spoken / last spoken — shown as an on-screen
+  /// caption beside the glyph.
+  String caption = '';
+
+  /// Spotlight target the agent is currently presenting: a widget id
+  /// registered on the [AgentBus] (e.g. 'search.field', 'graph.canvas'),
+  /// a pseudo-region ('content', 'nav') the spotlight resolves to a coarse
+  /// rect, or null for no spotlight. Set for the *whole* beat — narration and
+  /// action — so the light behaves like a tour guide's pointer, gliding from
+  /// target to target instead of flashing per action.
+  String? focusId;
+
+  /// True for the brief moment the agent "taps" the focused target — the
+  /// overlay renders a tap ripple on the cursor. Every screen change / effect
+  /// is preceded by one of these so the audience sees the click that caused it.
+  bool tapping = false;
+
+  bool _active = false;
+  int _tourIndex = 0;
+  final List<String> _questionQueue = [];
+
+  // Cached library snapshot for resolving fuzzy targets ("open the coffee card").
+  List<model.Card>? _cards;
+  List<ConceptEntry>? _conceptCache;
+
+  // The card the agent is currently demonstrating (opened/created), so reader,
+  // chat, and rabbit-hole actions act on a coherent subject.
+  String? _currentCardId;
+
+  // The collection the agent most recently created, so it can move a card into
+  // it on the next beat.
+  String? _lastCollectionId;
+
+  // A generation token distinguishes a natural utterance end from one we cut
+  // short (to handle a barge-in). Each utterance bumps it; the awaiter checks
+  // whether its token still matches when the completer resolves.
+  int _gen = 0;
+  Completer<void>? _speakCompleter;
+
+  bool get isActive => _active;
+
+  bool _voicePicked = false;
+
+  Future<void> _initTts() async {
+    _tts.setCompletionHandler(_finishUtterance);
+    _tts.setCancelHandler(_finishUtterance);
+    _tts.setErrorHandler((_) => _finishUtterance());
+    try {
+      // Rate scale differs by engine: the browser's Web Speech API treats 1.0
+      // as normal speed (0.5 is half-speed — that's what felt sluggish), while
+      // the native mobile engines treat ~0.5 as normal.
+      await _tts.setSpeechRate(kIsWeb ? 1.0 : 0.52);
+      await _tts.setPitch(1.0);
+      await _tts.setVolume(1.0);
+      await _selectNaturalVoice();
+    } catch (e, st) {
+      // Voice params are best-effort; speech still works with defaults.
+      _logError('TTS init', e, st);
+    }
+  }
+
+  /// Pick the most natural-sounding English voice the platform offers, instead
+  /// of the robotic default. Web voices load asynchronously, so this is retried
+  /// before the first utterance (see [_speak]).
+  Future<void> _selectNaturalVoice() async {
+    try {
+      final raw = await _tts.getVoices;
+      if (raw is! List) return;
+      final voices = raw
+          .whereType<Map>()
+          .map((v) => v.map((k, val) => MapEntry('$k', '$val')))
+          .toList();
+      if (voices.isEmpty) return; // not loaded yet — try again next utterance
+      final english = voices
+          .where((v) => (v['locale'] ?? '').toLowerCase().startsWith('en'))
+          .toList();
+      final pool = english.isNotEmpty ? english : voices;
+
+      int score(Map<String, String> v) {
+        final name = (v['name'] ?? '').toLowerCase();
+        if (name.contains('natural')) return 6; // Edge/Azure "… Natural"
+        if (name.contains('google')) return 5; // Chrome's higher-quality set
+        if (name.contains('samantha') || name.contains('ava')) return 4; // Apple
+        if (name.contains('aria') || name.contains('jenny')) return 4; // MS
+        if (name.contains('female')) return 2;
+        return 1;
+      }
+
+      pool.sort((a, b) => score(b).compareTo(score(a)));
+      final best = pool.first;
+      await _tts.setVoice({
+        'name': best['name'] ?? '',
+        'locale': best['locale'] ?? 'en-US',
+      });
+      _voicePicked = true;
+    } catch (e, st) {
+      // Default voice is fine if selection isn't supported.
+      _logError('voice selection', e, st);
+    }
+  }
+
+  void _setPhase(PresenterPhase p, {String? caption}) {
+    phase = p;
+    if (caption != null) this.caption = caption;
+    notifyListeners();
+  }
+
+  /// Log a presenter error into the backend's pipeline console (`start.py`'s
+  /// terminal) — errors during Present mode are largely swallowed so one bad
+  /// action/network call doesn't kill a live demo, but that means they'd
+  /// otherwise vanish silently. Relayed to `/presenter/log` because
+  /// `debugPrint` alone depends on the browser's DWDS forwarding actually
+  /// reaching the terminal, which isn't reliable; also mirrored to
+  /// `debugPrint` for anyone watching the browser console instead.
+  void _logError(String where, Object error, [StackTrace? st]) {
+    final line = '$where failed: $error';
+    debugPrint('[Presenter] $line');
+    if (st != null) debugPrintStack(stackTrace: st, label: '[Presenter] $where');
+    _repo.api.presenterLog(line, level: 'error');
+  }
+
+  /// Trace an action the agent is about to take (navigate, run a search,
+  /// scroll, open a card…) into the same pipeline console — so the log reads
+  /// as a live transcript of the demo, not just a silence broken by errors.
+  void _logInfo(String message) {
+    debugPrint('[Presenter] $message');
+    _repo.api.presenterLog(message);
+  }
+
+  /// A component the agent expected to act on never showed up in time (screen
+  /// didn't mount, data never loaded) — the action just gets skipped rather
+  /// than throwing, so this is the only trace that it happened.
+  void _logWarn(String message) {
+    debugPrint('[Presenter] $message');
+    _repo.api.presenterLog(message, level: 'warning');
+  }
+
+  /// Run [fn], logging and swallowing any error under [label] instead of
+  /// letting it escape — used to tag individual screen-hook calls (graph,
+  /// feed, search, reader, the shell's onOpen* callbacks) so a failure names
+  /// exactly which hook broke, not just the outer action type.
+  Future<void> _try(String label, FutureOr<void> Function() fn) async {
+    try {
+      await fn();
+    } catch (e, st) {
+      _logError(label, e, st);
+    }
+  }
+
+  void _finishUtterance() {
+    final c = _speakCompleter;
+    if (c != null && !c.isCompleted) c.complete();
+  }
+
+  /// Speak [text]; resolve true if it finished naturally, false if superseded by
+  /// a barge-in.
+  Future<bool> _speak(String text) async {
+    if (text.trim().isEmpty) return true;
+    if (!_voicePicked) await _selectNaturalVoice(); // web voices load late
+    final myGen = ++_gen;
+    _setPhase(PresenterPhase.speaking, caption: text);
+    final completer = Completer<void>();
+    _speakCompleter = completer;
+    try {
+      await _tts.speak(text);
+    } catch (e, st) {
+      // Web without a user gesture, or an unavailable engine, can throw here —
+      // don't let it break the beat; treat the utterance as finished.
+      _logError('tts.speak', e, st);
+      _finishUtterance();
+    }
+    // Watchdog: on web the browser sometimes never fires the "end" event, which
+    // would hang the whole tour on this completer forever. Cap the wait at a
+    // generous estimate of how long the line takes to read so the beat always
+    // advances.
+    final words = text.trim().split(RegExp(r'\s+')).length;
+    final capMs = (words * 420 + 2500).clamp(4000, 30000);
+    await Future.any<void>([
+      completer.future,
+      Future<void>.delayed(Duration(milliseconds: capMs)),
+    ]);
+    return _gen == myGen && _active;
+  }
+
+  Future<void> _stopSpeaking() async {
+    _gen++; // supersede whatever is (or was) speaking
+    await _tts.stop();
+    _finishUtterance();
+  }
+
+  // ── Public control ──────────────────────────────────────────────────────── //
+
+  /// Begin the tour from the top.
+  Future<void> start() async {
+    if (_active) return;
+    _active = true;
+    _tourIndex = 0;
+    // A heartbeat the moment Present mode loads — confirms the log relay is
+    // wired before any error would need it.
+    _repo.api.presenterLog('Present mode started');
+    unawaited(_warmCards());
+    await _runTour();
+  }
+
+  /// The audience/presenter submitted a question or task. Interrupts the tour,
+  /// gets handled, then the tour resumes.
+  Future<void> ask(String question) async {
+    final q = question.trim();
+    if (q.isEmpty || !_active) return;
+    _questionQueue.add(q);
+    if (phase == PresenterPhase.speaking) {
+      await _stopSpeaking(); // tour/answer loop detects the barge-in and drains
+    } else if (phase == PresenterPhase.idle) {
+      await _handleQuestions();
+      if (_active) _setPhase(PresenterPhase.idle, caption: _idlePrompt);
+    }
+    // If acting/thinking, the current loop drains the queue when it next checks.
+  }
+
+  /// End the presentation and silence any speech.
+  Future<void> stop() async {
+    _active = false;
+    _questionQueue.clear();
+    await _stopSpeaking();
+    _setFocus(null);
+    _setPhase(PresenterPhase.done);
+    _repo.api.presenterLog('Present mode ended');
+  }
+
+  // ── Tour loop ─────────────────────────────────────────────────────────── //
+
+  static const String _idlePrompt = 'Ask me anything, or tap to wrap up.';
+
+  Future<void> _runTour() async {
+    while (_active && _tourIndex < kTour.length) {
+      final completed = await _runBeat(kTour[_tourIndex]);
+      if (!_active) return;
+      if (!completed || _questionQueue.isNotEmpty) {
+        await _handleQuestions();
+      } else {
+        // A short breath between beats so the tour doesn't feel read off a
+        // teleprompter.
+        await _settle(ms: 450);
+      }
+      _tourIndex++;
+    }
+    if (!_active) return;
+    _setFocus(null);
+    _setPhase(PresenterPhase.idle, caption: _idlePrompt);
+    // Idle floor: any later question is handled by ask().
+  }
+
+  /// Answer queued questions/tasks by performing them, then offer more before
+  /// returning to the tour's natural flow.
+  Future<void> _handleQuestions() async {
+    while (_active && _questionQueue.isNotEmpty) {
+      final q = _questionQueue.removeAt(0);
+      _setFocus(null);
+      _setPhase(PresenterPhase.thinking, caption: 'Thinking…');
+      List<AgentBeat> beats;
+      try {
+        final raw = await _repo.api.presenterAsk(q);
+        beats = raw.map(AgentBeat.fromJson).toList();
+      } catch (e, st) {
+        _logError('ask("$q")', e, st);
+        beats = const [
+          AgentBeat(say: "I couldn't reach the backend to answer that."),
+        ];
+      }
+      if (!_active) return;
+      for (final beat in beats) {
+        final completed = await _runBeat(beat);
+        if (!_active) return;
+        if (!completed) break; // a fresh barge-in — loop drains it next
+      }
+      if (!_active) return;
+      if (_questionQueue.isEmpty) {
+        // Offer the floor; if they stay quiet we resume the tour.
+        await _runBeat(const AgentBeat(
+          say: "Anything else? Otherwise I'll carry on.",
+        ));
+      }
+    }
+  }
+
+  /// Run one beat: switch view, light the spotlight target, then speak *while*
+  /// performing the action — narration leads, the "hands" follow half a second
+  /// later, like a human demoing. Returns false if speech was interrupted by a
+  /// barge-in (so the caller can drain questions).
+  Future<bool> _runBeat(AgentBeat beat) async {
+    if (!_active) return false;
+    // Navigation is itself a visible tap on the nav control that reaches it,
+    // so a screen change never appears out of nowhere.
+    if (beat.view != null) {
+      await _gesture(_navTargetFor(beat.view!), () async {
+        _logInfo('navigate → ${beat.view}');
+        _bus.onNavigate?.call(beat.view!);
+        await _settle();
+      });
+      if (!_active) return false;
+    }
+    // Light the target the narration is about, so the cursor glides onto it
+    // while the agent talks.
+    _setFocus(beat.focus ??
+        (beat.action != null ? _targetFor(beat.action!.type) : null));
+    Future<bool>? speech;
+    if (beat.say != null && beat.say!.isNotEmpty) {
+      speech = _speak(beat.say!);
+    }
+    if (beat.action != null) {
+      if (speech != null) {
+        // Let the narration lead before the hand moves.
+        await Future<void>.delayed(const Duration(milliseconds: 550));
+      } else {
+        _setPhase(PresenterPhase.acting);
+      }
+      if (_active) {
+        // Tap the lit target, then fire the effect — the click precedes the
+        // change the audience sees.
+        await _tap();
+        try {
+          await _execute(beat.action!);
+        } catch (e, st) {
+          // A live action failing shouldn't kill the presentation.
+          _logError('action "${beat.action!.type}"', e, st);
+        }
+      }
+    }
+    final spoken = speech == null || await speech;
+    if (!spoken) return false;
+    return _active && _questionQueue.isEmpty;
+  }
+
+  void _setFocus(String? id) {
+    if (focusId == id) return;
+    focusId = id;
+    tapping = false; // moving to a new target cancels any in-flight tap
+    notifyListeners();
+  }
+
+  void _setTapping(bool v) {
+    if (tapping == v) return;
+    tapping = v;
+    notifyListeners();
+  }
+
+  /// A visible "click" on the currently-focused target: pulse the tap ripple,
+  /// hold briefly, then release. Callers fire the real effect right after so
+  /// the audience sees the tap that caused the change. No-op if nothing's lit.
+  Future<void> _tap() async {
+    if (focusId == null || !_active) return;
+    _setTapping(true);
+    await _settle(ms: 220);
+    _setTapping(false);
+  }
+
+  /// Glide the cursor to [targetId], tap it, then run [effect] — the full
+  /// point-tap-act gesture used for navigation, so a screen change reads as a
+  /// tap on the nav control that triggered it rather than a magic swap.
+  Future<void> _gesture(String? targetId, FutureOr<void> Function() effect) async {
+    _setFocus(targetId);
+    await _settle(ms: 620); // let the cursor glide onto the target
+    if (!_active) return;
+    await _tap();
+    if (!_active) return;
+    await effect();
+  }
+
+  /// The nav control the agent taps to reach [view]: a bottom-nav tab, one of
+  /// the library's top segments (Concepts/Catalog), or a top-bar icon
+  /// (Graph/Chat/Search). Falls back to the coarse 'nav' region.
+  String _navTargetFor(String view) => switch (view) {
+        'library' => 'nav.home',
+        'collections' => 'nav.folders',
+        'actions' => 'nav.todo',
+        'feed' => 'nav.feed',
+        'profile' => 'nav.you',
+        'concepts' => 'library.tab.concepts',
+        'catalog' => 'library.tab.catalog',
+        'graph' => 'top.graph',
+        'search' => 'top.search',
+        'connections' || 'chat' => 'top.chat',
+        _ => 'nav',
+      };
+
+  /// Map an action to the spotlight target it visibly affects, so the light
+  /// guides the audience to the right widget (with coarse fallbacks).
+  String? _targetFor(String type) => switch (type) {
+        'search' => 'search.field',
+        'search_filter' => 'search.filters',
+        'navigate' => 'nav',
+        'graph_focus' ||
+        'graph_open' ||
+        'graph_wander' ||
+        'graph_reset' ||
+        'graph_cluster' ||
+        'graph_concepts' =>
+          'graph.canvas',
+        'feed_next' || 'feed_prev' || 'feed_shuffle' => 'feed.page',
+        'open_card' => 'card.first',
+        'create_card' => 'home.plus',
+        'reader_toggle' => 'reader.blocks',
+        'rabbit_hole' => 'reader.insight',
+        'card_chat' => 'reader.ask',
+        'catalog_item' => 'catalog.item',
+        'create_collection' => 'folders.create',
+        'follow_actions' || 'toggle_action_item' => 'todo.item',
+        'library_chat' => 'top.chat',
+        // 'point' and 'scroll' rely on the beat's explicit focus.
+        'point' || 'scroll' || 'wait' => null,
+        _ => 'content',
+      };
+
+  // ── Action executor ───────────────────────────────────────────────────── //
+
+  Future<void> _execute(AgentAction a) async {
+    _logInfo('action → ${a.type}${a.args.isEmpty ? '' : ' ${a.args}'}');
+    switch (a.type) {
+      case 'navigate':
+        if (a.view != null) {
+          _bus.onNavigate?.call(a.view!);
+          await _settle();
+        }
+      case 'wait':
+        final ms = (a.args['ms'] as num?)?.toInt() ?? 800;
+        await Future<void>.delayed(Duration(milliseconds: ms));
+      case 'scroll':
+        await _scrollSurface(a);
+      case 'create_card':
+        final url = a.url;
+        if (url != null && url.isNotEmpty) {
+          final id = await _bus.onCreateCard?.call(url);
+          if (id != null && id.isNotEmpty) _currentCardId = id;
+          await _settle(ms: 600);
+        }
+      case 'search':
+        await _runSearch(a.query);
+      case 'search_filter':
+        await _searchFilter();
+      case 'open_card':
+        await _openCard(a.query);
+      case 'reader_toggle':
+        await _readerToggle();
+      case 'graph_focus':
+        await _graphFocus(a.query, open: false);
+      case 'graph_open':
+        await _graphFocus(a.query, open: true);
+      case 'graph_wander':
+        await _graphWander();
+      case 'graph_reset':
+        await _ensureGraph();
+        await _try('graph.reset', () => _bus.graph?.reset());
+        await _settle(ms: 700);
+      case 'graph_cluster':
+        await _ensureGraph();
+        await _try('graph.filterCluster', () => _bus.graph?.filterCluster());
+      case 'graph_concepts':
+        await _ensureGraph();
+        await _try('graph.toggleConcepts', () => _bus.graph?.toggleConcepts());
+      case 'feed_next':
+        await _feedStep(forward: true);
+      case 'feed_prev':
+        await _feedStep(forward: false);
+      case 'feed_shuffle':
+        await _feedShuffle();
+      case 'open_concept':
+      case 'define_concept':
+        await _demoConcept(a.query);
+      case 'create_collection':
+        await _createCollection(a.args['name'] as String?);
+      case 'move_card':
+        await _moveCard();
+      case 'follow_actions':
+        await _followActions();
+      case 'toggle_action_item':
+        await _toggleActionItem();
+      case 'card_chat':
+        await _cardChat(a.query);
+      case 'library_chat':
+        await _libraryChat(a.query);
+      case 'rabbit_hole':
+        await _rabbitHole(a.query);
+      case 'open_connections':
+        _bus.onNavigate?.call('connections');
+        await _settle(ms: 700);
+      case 'catalog_item':
+        await _try('onOpenCatalogItem', () => _bus.onOpenCatalogItem?.call());
+        await _settle(ms: 900);
+      case 'point':
+        // Explain-only beat: the tap pulse already fired in _runBeat; nothing
+        // to execute. The lit target is what the audience is looking at.
+        break;
+      default:
+        break;
+    }
+  }
+
+  /// Scroll a registered surface ('library' grid, 'reader' body) by `dy`
+  /// pixels; with `sweep: true` it glides down, pauses, and glides back — the
+  /// browsing gesture a human makes while talking over a screen.
+  Future<void> _scrollSurface(AgentAction a) async {
+    final target = (a.args['target'] as String?) ?? 'library';
+    final dy = (a.args['dy'] as num?)?.toDouble() ?? 600;
+    await _try('scroll($target)', () => _bus.scrollBy(target, dy));
+    if (a.args['sweep'] == true) {
+      await _settle(ms: 600);
+      await _try('scroll($target, back)', () => _bus.scrollBy(target, -dy));
+    }
+  }
+
+  Future<void> _runSearch(String? query) async {
+    _bus.onNavigate?.call('search');
+    final ready =
+        await _waitFor(() => _bus.search != null, what: 'search screen', timeoutMs: 4000);
+    if (!ready) return;
+    final q = _resolveSearchQuery(query);
+    await _try('search.run("$q")', () => _bus.search?.run(q));
+    await _settle(ms: 900);
+  }
+
+  Future<void> _searchFilter() async {
+    _bus.onNavigate?.call('search');
+    final ready =
+        await _waitFor(() => _bus.search != null, what: 'search screen', timeoutMs: 4000);
+    if (!ready) return;
+    await _try('search.filter', () => _bus.search?.filter());
+    await _settle(ms: 700);
+  }
+
+  Future<void> _openCard(String? query) async {
+    final cards = await _warmCards();
+    final match = _bestCard(query, cards);
+    if (match != null) {
+      _currentCardId = match.cardId;
+      await _try('onOpenCard(${match.cardId})',
+          () => _bus.onOpenCard?.call(match.cardId));
+      await _settle(ms: 500);
+    }
+  }
+
+  Future<void> _readerToggle() async {
+    final card = await _cardForDemo();
+    if (card == null) return;
+    _currentCardId = card.cardId;
+    await _try(
+        'onOpenCard(${card.cardId})', () => _bus.onOpenCard?.call(card.cardId));
+    final ready =
+        await _waitFor(() => _bus.reader?.isReady() == true, what: 'reader');
+    final r = _bus.reader;
+    // No nested _speak here: actions may now run concurrently with narration,
+    // and a second utterance would orphan the first one's completer.
+    if (!ready || r == null) return;
+    var did = false;
+    await _try('reader.toggleCheck', () async => did = await r.toggleCheck());
+    if (!did) await _try('reader.toggleStep', () => r.toggleStep());
+    await _settle(ms: 600);
+  }
+
+  Future<void> _graphFocus(String? query, {required bool open}) async {
+    await _ensureGraph();
+    final g = _bus.graph;
+    if (g == null) return;
+    final nodes = g.nodes();
+    if (nodes.isEmpty) return;
+    final target = query == null || query.isEmpty || query == 'auto'
+        ? _mostConnected(nodes)
+        : _bestNode(query, nodes);
+    if (target == null) return;
+    if (open) {
+      if (target.isCard) _currentCardId = target.id;
+      await _try('graph.open(${target.id})', () => g.open(target.id));
+    } else {
+      await _try('graph.focus(${target.id})', () => g.focus(target.id));
+    }
+    await _settle(ms: 400);
+  }
+
+  Future<void> _graphWander() async {
+    await _ensureGraph();
+    await _try('graph.wander', () => _bus.graph?.wander());
+  }
+
+  Future<void> _feedStep({required bool forward}) async {
+    _bus.onNavigate?.call('feed');
+    final ready =
+        await _waitFor(() => _bus.feed != null, what: 'feed screen', timeoutMs: 4000);
+    final f = _bus.feed;
+    if (!ready || f == null) return;
+    await _try(forward ? 'feed.next' : 'feed.prev',
+        () => forward ? f.next() : f.prev());
+    await _settle(ms: 900);
+  }
+
+  Future<void> _feedShuffle() async {
+    _bus.onNavigate?.call('feed');
+    final ready =
+        await _waitFor(() => _bus.feed != null, what: 'feed screen', timeoutMs: 4000);
+    if (!ready) return;
+    await _try('feed.shuffle', () => _bus.feed?.shuffle());
+    await _settle(ms: 1200);
+  }
+
+  Future<void> _ensureGraph() async {
+    _bus.onNavigate?.call('graph');
+    await _waitFor(() => _bus.graph?.isReady() == true,
+        what: 'graph screen', timeoutMs: 9000);
+  }
+
+  Future<void> _demoConcept(String? query) async {
+    final concepts = await _warmConcepts();
+    if (concepts.isEmpty) return; // nothing mined yet — skip quietly
+    final match = (query == null || query.isEmpty || query == 'auto')
+        ? concepts.first
+        : (_bestBy(query, concepts, (c) => c.name) ?? concepts.first);
+    try {
+      await _repo.defineConcept(match.id);
+    } catch (e, st) {
+      // best-effort; the detail screen still opens and can define on demand.
+      _logError('defineConcept(${match.id})', e, st);
+    }
+    await _try('onOpenConcept(${match.id})',
+        () => _bus.onOpenConcept?.call(match.id, match.name));
+    await _settle(ms: 700);
+  }
+
+  Future<void> _createCollection(String? name) async {
+    final n = (name == null || name.isEmpty) ? 'Demo Folder' : name;
+    try {
+      final col = await _repo.createCollection(n);
+      _lastCollectionId = col.id;
+    } catch (e, st) {
+      _logError('createCollection("$n")', e, st);
+    }
+    _bus.onNavigate?.call('collections');
+    await _settle(ms: 900);
+  }
+
+  Future<void> _moveCard() async {
+    final card = await _cardForDemo();
+    if (card == null) return;
+    var colId = _lastCollectionId;
+    if (colId == null) {
+      try {
+        final col = await _repo.createCollection('Demo Folder');
+        colId = col.id;
+        _lastCollectionId = colId;
+      } catch (e, st) {
+        _logError('createCollection (for move)', e, st);
+        return;
+      }
+    }
+    try {
+      await _repo.moveCardToCollection(card.cardId, colId);
+    } catch (e, st) {
+      _logError('moveCardToCollection(${card.cardId})', e, st);
+    }
+    _bus.onNavigate?.call('collections');
+    await _settle(ms: 900);
+  }
+
+  Future<void> _followActions() async {
+    final card = await _cardWithActions();
+    if (card == null || card.actionItems.items.isEmpty) {
+      // Nothing to follow — still show the hub, but don't nest a _speak while
+      // the beat's narration may be running.
+      _bus.onNavigate?.call('actions');
+      await _settle(ms: 700);
+      return;
+    }
+    _currentCardId = card.cardId;
+    try {
+      await _repo.patchActionItems(
+        card.cardId,
+        model.ActionItems(followed: true, items: card.actionItems.items).toJson(),
+      );
+    } catch (e, st) {
+      _logError('patchActionItems (follow, ${card.cardId})', e, st);
+    }
+    _bus.onNavigate?.call('actions');
+    await _settle(ms: 900);
+  }
+
+  Future<void> _toggleActionItem() async {
+    final card = await _cardWithActions();
+    if (card == null || card.actionItems.items.isEmpty) return;
+    final first = card.actionItems.items.first;
+    final updated = model.ActionItems(
+      followed: true,
+      items: [
+        for (final it in card.actionItems.items)
+          it.id == first.id
+              ? model.ActionItem(id: it.id, text: it.text, done: !it.done)
+              : it,
+      ],
+    );
+    try {
+      await _repo.patchActionItems(card.cardId, updated.toJson());
+    } catch (e, st) {
+      _logError('patchActionItems (toggle, ${card.cardId})', e, st);
+    }
+    _bus.onNavigate?.call('actions');
+    await _settle(ms: 800);
+  }
+
+  Future<void> _cardChat(String? query) async {
+    final card = await _cardForDemo();
+    if (card == null) return;
+    final seed = (query == null || query.isEmpty)
+        ? 'What is the single most useful takeaway here?'
+        : query;
+    final title =
+        card.base.oneLiner.isNotEmpty ? card.base.oneLiner : 'This card';
+    await _try('onOpenCardChat(${card.cardId})',
+        () => _bus.onOpenCardChat?.call(card.cardId, title, seed));
+    await _settle(ms: 1000);
+  }
+
+  Future<void> _libraryChat(String? query) async {
+    final seed = (query == null || query.isEmpty)
+        ? 'What are the main themes across everything saved here?'
+        : query;
+    await _try('onOpenLibraryChat', () => _bus.onOpenLibraryChat?.call(seed));
+    await _settle(ms: 1000);
+  }
+
+  Future<void> _rabbitHole(String? query) async {
+    final card = await _cardForDemo();
+    if (card == null) return;
+    final seed = (query == null || query.isEmpty || query == 'auto')
+        ? (card.base.oneLiner.isNotEmpty ? card.base.oneLiner : 'Tell me more')
+        : query;
+    await _try('onOpenRabbitHole(${card.cardId})',
+        () => _bus.onOpenRabbitHole?.call(card.cardId, seed));
+    await _settle(ms: 1000);
+  }
+
+  // ── Target resolution ─────────────────────────────────────────────────── //
+
+  Future<List<model.Card>> _warmCards() async {
+    if (_cards != null) return _cards!;
+    try {
+      _cards = await _repo.list();
+    } catch (e, st) {
+      _logError('warmCards (repo.list)', e, st);
+      _cards = const [];
+    }
+    return _cards!;
+  }
+
+  Future<List<ConceptEntry>> _warmConcepts() async {
+    if (_conceptCache != null) return _conceptCache!;
+    try {
+      _conceptCache = await _repo.concepts();
+    } catch (e, st) {
+      _logError('warmConcepts (repo.concepts)', e, st);
+      _conceptCache = const [];
+    }
+    return _conceptCache!;
+  }
+
+  /// The card the agent should demonstrate: the one it's currently on, else the
+  /// first in the library.
+  Future<model.Card?> _cardForDemo() async {
+    final cards = await _warmCards();
+    if (cards.isEmpty) return null;
+    if (_currentCardId != null) {
+      for (final c in cards) {
+        if (c.cardId == _currentCardId) return c;
+      }
+    }
+    return cards.first;
+  }
+
+  /// The first card that actually has to-do items (for the Actions demo), else
+  /// any card.
+  Future<model.Card?> _cardWithActions() async {
+    final cards = await _warmCards();
+    for (final c in cards) {
+      if (c.actionItems.items.isNotEmpty) return c;
+    }
+    return cards.isEmpty ? null : cards.first;
+  }
+
+  String _resolveSearchQuery(String? query) {
+    if (query != null && query.isNotEmpty && query != 'auto') return query;
+    final cards = _cards ?? const [];
+    for (final c in cards) {
+      if (c.base.tags.isNotEmpty) return c.base.tags.first;
+    }
+    if (cards.isNotEmpty) {
+      final words = cards.first.base.oneLiner.split(RegExp(r'\s+'));
+      final word = words.firstWhere((w) => w.length > 4, orElse: () => 'idea');
+      return word.replaceAll(RegExp(r'[^A-Za-z]'), '');
+    }
+    return 'idea';
+  }
+
+  model.Card? _bestCard(String? query, List<model.Card> cards) {
+    if (cards.isEmpty) return null;
+    if (query == null || query.isEmpty) return cards.first;
+    String label(model.Card c) =>
+        '${c.base.oneLiner} ${c.source.caption} ${c.base.tags.join(' ')}';
+    return _bestBy(query, cards, label) ?? cards.first;
+  }
+
+  GraphNode? _bestNode(String query, List<GraphNode> nodes) =>
+      _bestBy(query, nodes, (n) => '${n.label} ${n.tags.join(' ')}');
+
+  GraphNode? _mostConnected(List<GraphNode> nodes) {
+    final sorted = [...nodes]..sort((a, b) => b.degree.compareTo(a.degree));
+    return sorted.isEmpty ? null : sorted.first;
+  }
+
+  /// Simple token-overlap fuzzy match — good enough to point the agent at the
+  /// right card/node from a spoken query.
+  T? _bestBy<T>(String query, List<T> items, String Function(T) labelOf) {
+    final qTokens = _tokens(query);
+    if (qTokens.isEmpty) return null;
+    T? best;
+    var bestScore = 0.0;
+    for (final item in items) {
+      final label = labelOf(item).toLowerCase();
+      final lTokens = _tokens(label);
+      var score = 0.0;
+      for (final t in qTokens) {
+        if (lTokens.contains(t)) {
+          score += 2;
+        } else if (label.contains(t)) {
+          score += 1;
+        }
+      }
+      if (score > bestScore) {
+        bestScore = score;
+        best = item;
+      }
+    }
+    return bestScore > 0 ? best : null;
+  }
+
+  Set<String> _tokens(String s) => s
+      .toLowerCase()
+      .split(RegExp(r'[^a-z0-9]+'))
+      .where((t) => t.length > 2)
+      .toSet();
+
+  // ── Timing helpers ────────────────────────────────────────────────────── //
+
+  /// Give a freshly-navigated screen a beat to mount/animate in.
+  Future<void> _settle({int ms = 320}) =>
+      Future<void>.delayed(Duration(milliseconds: ms));
+
+  /// Poll [ready] until true or [timeoutMs] elapses; returns whether it
+  /// became ready. A screen/hook that never mounts doesn't throw — the
+  /// dependent action just quietly no-ops — so this is the only trace that a
+  /// component failed to show up in time, logged under [what].
+  Future<bool> _waitFor(
+    bool Function() ready, {
+    required String what,
+    int timeoutMs = 5000,
+  }) async {
+    final deadline = DateTime.now().add(Duration(milliseconds: timeoutMs));
+    while (_active && !ready() && DateTime.now().isBefore(deadline)) {
+      await Future<void>.delayed(const Duration(milliseconds: 120));
+    }
+    final ok = ready();
+    if (!ok && _active) {
+      _logWarn('$what never became ready after ${timeoutMs}ms — skipped');
+    }
+    return ok;
+  }
+
+  @override
+  void dispose() {
+    _active = false;
+    _tts.stop();
+    super.dispose();
+  }
+}

app/lib/ui/features/presenter/presenter_overlay.dart

@@ -0,0 +1,335 @@
+/// The "Present" mode surface: a Siri-like glowing glyph that floats in a
+/// corner while the agent drives the app. It pulses in the agent's current phase
+/// colour, shows a live caption of what's being said/done, and — when tapped —
+/// expands into a panel where you can hand the agent a question or a task.
+library;
+
+import 'dart:ui';
+
+import 'package:flutter/material.dart';
+
+import '../../core/theme.dart';
+import 'presenter_controller.dart';
+
+class PresenterOverlay extends StatefulWidget {
+  const PresenterOverlay({super.key, required this.controller});
+  final PresenterController controller;
+
+  @override
+  State<PresenterOverlay> createState() => _PresenterOverlayState();
+}
+
+class _PresenterOverlayState extends State<PresenterOverlay>
+    with SingleTickerProviderStateMixin {
+  late final AnimationController _pulse = AnimationController(
+    vsync: this,
+    duration: const Duration(milliseconds: 2200),
+  )..repeat(reverse: true);
+
+  final _field = TextEditingController();
+  final _focus = FocusNode();
+  bool _expanded = false;
+
+  @override
+  void dispose() {
+    _pulse.dispose();
+    _field.dispose();
+    _focus.dispose();
+    super.dispose();
+  }
+
+  void _toggle() {
+    setState(() => _expanded = !_expanded);
+    if (_expanded) {
+      WidgetsBinding.instance.addPostFrameCallback((_) => _focus.requestFocus());
+    }
+  }
+
+  void _submit() {
+    final q = _field.text.trim();
+    if (q.isEmpty) return;
+    _field.clear();
+    widget.controller.ask(q);
+    _focus.requestFocus();
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    final width = MediaQuery.sizeOf(context).width;
+    final bottomInset = MediaQuery.of(context).padding.bottom;
+    // Clear the floating pill nav on mobile; the side rail leaves the corner free.
+    final bottom = bottomInset + (width >= Insets.desktop ? 24 : 92);
+
+    return Positioned(
+      right: 16,
+      bottom: bottom,
+      child: AnimatedBuilder(
+        animation: widget.controller,
+        builder: (context, _) {
+          return Column(
+            crossAxisAlignment: CrossAxisAlignment.end,
+            mainAxisSize: MainAxisSize.min,
+            children: [
+              if (_expanded)
+                _Panel(
+                  controller: widget.controller,
+                  field: _field,
+                  focus: _focus,
+                  onSubmit: _submit,
+                  onEnd: () => widget.controller.stop(),
+                )
+              else if (widget.controller.caption.isNotEmpty)
+                _CaptionBubble(text: widget.controller.caption),
+              const SizedBox(height: 12),
+              _Glyph(
+                phase: widget.controller.phase,
+                pulse: _pulse,
+                onTap: _toggle,
+                expanded: _expanded,
+              ),
+            ],
+          );
+        },
+      ),
+    );
+  }
+}
+
+// ── The glowing orb ─────────────────────────────────────────────────────── //
+
+class _Glyph extends StatelessWidget {
+  const _Glyph({
+    required this.phase,
+    required this.pulse,
+    required this.onTap,
+    required this.expanded,
+  });
+
+  final PresenterPhase phase;
+  final Animation<double> pulse;
+  final VoidCallback onTap;
+  final bool expanded;
+
+  @override
+  Widget build(BuildContext context) {
+    final color = _phaseColor(context, phase);
+    final busy = phase == PresenterPhase.speaking ||
+        phase == PresenterPhase.thinking ||
+        phase == PresenterPhase.acting;
+
+    return Semantics(
+      button: true,
+      label: 'Presenter agent — tap to ask or hand it a task',
+      child: MouseRegion(
+        cursor: SystemMouseCursors.click,
+        child: GestureDetector(
+          onTap: onTap,
+          child: AnimatedBuilder(
+            animation: pulse,
+            builder: (context, _) {
+              // A soft double-halo that breathes; wider when the agent is busy.
+              final t = pulse.value;
+              final haloBlur = (busy ? 30.0 : 20.0) + t * 14;
+              final haloSpread = (busy ? 8.0 : 4.0) + t * 6;
+              return Container(
+                width: 64,
+                height: 64,
+                decoration: BoxDecoration(
+                  shape: BoxShape.circle,
+                  gradient: RadialGradient(
+                    colors: [
+                      Color.lerp(color, Colors.white, 0.35)!,
+                      color,
+                      Color.lerp(color, Colors.black, 0.25)!,
+                    ],
+                    stops: const [0.0, 0.55, 1.0],
+                    center: const Alignment(-0.3, -0.4),
+                  ),
+                  boxShadow: [
+                    BoxShadow(
+                      color: color.withValues(alpha: 0.55),
+                      blurRadius: haloBlur,
+                      spreadRadius: haloSpread,
+                    ),
+                    BoxShadow(
+                      color: color.withValues(alpha: 0.25),
+                      blurRadius: haloBlur * 2,
+                      spreadRadius: haloSpread * 1.6,
+                    ),
+                  ],
+                ),
+                child: Center(
+                  child: Icon(
+                    expanded ? Icons.keyboard_arrow_down_rounded : _phaseIcon(phase),
+                    color: Colors.white,
+                    size: 28,
+                  ),
+                ),
+              );
+            },
+          ),
+        ),
+      ),
+    );
+  }
+}
+
+// ── Collapsed caption bubble ────────────────────────────────────────────── //
+
+class _CaptionBubble extends StatelessWidget {
+  const _CaptionBubble({required this.text});
+  final String text;
+
+  @override
+  Widget build(BuildContext context) {
+    final theme = Theme.of(context);
+    return ConstrainedBox(
+      constraints: const BoxConstraints(maxWidth: 320),
+      child: ClipRRect(
+        borderRadius: BorderRadius.circular(18),
+        child: BackdropFilter(
+          filter: ImageFilter.blur(sigmaX: 16, sigmaY: 16),
+          child: Container(
+            padding: const EdgeInsets.symmetric(horizontal: 16, vertical: 12),
+            decoration: BoxDecoration(
+              color: theme.colorScheme.surface.withValues(alpha: 0.82),
+              borderRadius: BorderRadius.circular(18),
+              border: Border.all(
+                color: theme.colorScheme.primary.withValues(alpha: 0.30),
+              ),
+            ),
+            child: Text(
+              text,
+              style: theme.textTheme.bodyMedium,
+              maxLines: 4,
+              overflow: TextOverflow.ellipsis,
+            ),
+          ),
+        ),
+      ),
+    );
+  }
+}
+
+// ── Expanded input panel ────────────────────────────────────────────────── //
+
+class _Panel extends StatelessWidget {
+  const _Panel({
+    required this.controller,
+    required this.field,
+    required this.focus,
+    required this.onSubmit,
+    required this.onEnd,
+  });
+
+  final PresenterController controller;
+  final TextEditingController field;
+  final FocusNode focus;
+  final VoidCallback onSubmit;
+  final VoidCallback onEnd;
+
+  @override
+  Widget build(BuildContext context) {
+    final theme = Theme.of(context);
+    return ConstrainedBox(
+      constraints: const BoxConstraints(maxWidth: 340),
+      child: ClipRRect(
+        borderRadius: BorderRadius.circular(20),
+        child: BackdropFilter(
+          filter: ImageFilter.blur(sigmaX: 18, sigmaY: 18),
+          child: Container(
+            padding: const EdgeInsets.all(14),
+            decoration: BoxDecoration(
+              color: theme.colorScheme.surface.withValues(alpha: 0.86),
+              borderRadius: BorderRadius.circular(20),
+              border: Border.all(
+                color: theme.colorScheme.primary.withValues(alpha: 0.35),
+              ),
+            ),
+            child: Column(
+              mainAxisSize: MainAxisSize.min,
+              crossAxisAlignment: CrossAxisAlignment.start,
+              children: [
+                Row(
+                  children: [
+                    Text(
+                      _phaseLabel(controller.phase),
+                      style: theme.textTheme.labelSmall?.copyWith(
+                        letterSpacing: 1.2,
+                        color: theme.colorScheme.primary,
+                      ),
+                    ),
+                    const Spacer(),
+                    TextButton.icon(
+                      onPressed: onEnd,
+                      icon: const Icon(Icons.stop_circle_outlined, size: 18),
+                      label: const Text('End'),
+                    ),
+                  ],
+                ),
+                const SizedBox(height: 2),
+                Text(
+                  controller.caption.isEmpty ? '…' : controller.caption,
+                  style: theme.textTheme.bodyMedium,
+                  maxLines: 4,
+                  overflow: TextOverflow.ellipsis,
+                ),
+                const SizedBox(height: 12),
+                TextField(
+                  controller: field,
+                  focusNode: focus,
+                  onSubmitted: (_) => onSubmit(),
+                  textInputAction: TextInputAction.send,
+                  decoration: InputDecoration(
+                    hintText: 'Ask, or hand me a task…',
+                    isDense: true,
+                    filled: true,
+                    fillColor: theme.colorScheme.surfaceContainerHighest
+                        .withValues(alpha: 0.5),
+                    border: OutlineInputBorder(
+                      borderRadius: BorderRadius.circular(14),
+                      borderSide: BorderSide.none,
+                    ),
+                    suffixIcon: IconButton(
+                      icon: const Icon(Icons.send_rounded),
+                      onPressed: onSubmit,
+                    ),
+                  ),
+                ),
+              ],
+            ),
+          ),
+        ),
+      ),
+    );
+  }
+}
+
+// ── Phase → colour / icon / label ───────────────────────────────────────── //
+
+Color _phaseColor(BuildContext context, PresenterPhase phase) {
+  final scheme = Theme.of(context).colorScheme;
+  return switch (phase) {
+    PresenterPhase.speaking => const Color(0xFF3DDC97),
+    PresenterPhase.thinking => const Color(0xFFF5A623),
+    PresenterPhase.acting => const Color(0xFF4DA8FF),
+    PresenterPhase.idle => scheme.primary,
+    PresenterPhase.done => Colors.grey,
+  };
+}
+
+IconData _phaseIcon(PresenterPhase phase) => switch (phase) {
+      PresenterPhase.speaking => Icons.graphic_eq_rounded,
+      PresenterPhase.thinking => Icons.auto_awesome_rounded,
+      PresenterPhase.acting => Icons.touch_app_rounded,
+      PresenterPhase.idle => Icons.mic_none_rounded,
+      PresenterPhase.done => Icons.check_rounded,
+    };
+
+String _phaseLabel(PresenterPhase p) => switch (p) {
+      PresenterPhase.speaking => 'PRESENTING',
+      PresenterPhase.thinking => 'THINKING',
+      PresenterPhase.acting => 'DOING IT LIVE',
+      PresenterPhase.idle => 'READY — ASK ME',
+      PresenterPhase.done => 'DONE',
+    };

app/lib/ui/features/presenter/presenter_spotlight.dart

@@ -0,0 +1,334 @@
+/// The guided-focus layer for Present mode: while the agent presents a beat it
+/// dims the surrounding interface, lights the widget it's talking about, and
+/// glides a presentation cursor there — the coach-marks feel of an app's
+/// first-run tour.
+///
+/// Targets are real widgets: screens register a GlobalKey per target id on the
+/// [AgentBus] (see `agent_bus.dart`), and this layer resolves live geometry
+/// from the key every ~150 ms while lit, so the hole hugs the actual widget
+/// even if it mounts late or the layout shifts. Ids with no registered widget
+/// fall back to a coarse screen region. The layer stays mounted for the whole
+/// presentation so the hole and cursor *animate between* targets instead of
+/// restarting, and it's wrapped in [IgnorePointer] so it never blocks input.
+library;
+
+import 'dart:async';
+
+import 'package:flutter/material.dart';
+
+import '../../core/theme.dart';
+import 'agent_bus.dart';
+import 'presenter_controller.dart';
+
+class PresenterSpotlight extends StatefulWidget {
+  const PresenterSpotlight({
+    super.key,
+    required this.controller,
+    required this.bus,
+  });
+
+  final PresenterController controller;
+  final AgentBus bus;
+
+  @override
+  State<PresenterSpotlight> createState() => _PresenterSpotlightState();
+}
+
+class _PresenterSpotlightState extends State<PresenterSpotlight> {
+  Timer? _poll;
+
+  @override
+  void initState() {
+    super.initState();
+    widget.controller.addListener(_onFocusChanged);
+    _onFocusChanged();
+  }
+
+  @override
+  void dispose() {
+    widget.controller.removeListener(_onFocusChanged);
+    _poll?.cancel();
+    super.dispose();
+  }
+
+  /// While a target is lit, re-resolve its geometry a few times a second so a
+  /// screen that mounts (or scrolls) after navigation still gets hugged.
+  void _onFocusChanged() {
+    final lit = widget.controller.focusId != null;
+    if (lit && _poll == null) {
+      _poll = Timer.periodic(const Duration(milliseconds: 150), (_) {
+        if (mounted) setState(() {});
+      });
+    } else if (!lit) {
+      _poll?.cancel();
+      _poll = null;
+    }
+    if (mounted) setState(() {});
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    return Positioned.fill(
+      child: IgnorePointer(
+        child: LayoutBuilder(
+          builder: (context, constraints) {
+            final size = Size(constraints.maxWidth, constraints.maxHeight);
+            final id = widget.controller.focusId;
+            final rect = id == null ? null : _resolve(id, size);
+            // Dim the app only around genuinely small targets (a button, a nav
+            // item); dimming a region that already fills the screen just makes
+            // everything darker. The cursor, though, always shows so the
+            // audience can see where the agent is clicking.
+            final small = rect != null &&
+                rect.width * rect.height < size.width * size.height * 0.5;
+            return _Guidance(
+              target: rect,
+              dim: small,
+              tapping: widget.controller.tapping,
+              screen: size,
+              color: Theme.of(context).colorScheme.primary,
+            );
+          },
+        ),
+      ),
+    );
+  }
+
+  /// Real widget bounds when the target is registered and mounted, else a
+  /// generous fallback region so guidance degrades instead of vanishing.
+  Rect _resolve(String id, Size size) {
+    final live = widget.bus.spotlightRect(id);
+    if (live != null && !live.isEmpty) {
+      // Keep the hole on screen even if the widget hangs off an edge.
+      final screen = Offset.zero & size;
+      final clamped = live.intersect(screen.inflate(-4));
+      if (!clamped.isEmpty) return clamped;
+    }
+    return _fallbackRect(id, size);
+  }
+
+  Rect _fallbackRect(String id, Size size) {
+    final w = size.width;
+    final h = size.height;
+    final desktop = w >= Insets.desktop;
+    // Bottom nav / side rail.
+    if (id == 'nav' || id.startsWith('nav.')) {
+      return desktop
+          ? Rect.fromLTWH(0, h * 0.18, 88, h * 0.64) // left rail
+          : Rect.fromLTWH(w * 0.08, h - 100, w * 0.84, 74); // bottom pill
+    }
+    // Add button — bottom-right on mobile, in the rail on desktop.
+    if (id == 'home.plus') {
+      return desktop
+          ? Rect.fromLTWH(16, 24, 56, 56)
+          : Rect.fromLTWH(w - 88, h - 168, 64, 64);
+    }
+    // Top bar: search field, top-bar icons, library segment tabs.
+    if (id.startsWith('search.') ||
+        id.startsWith('top.') ||
+        id.startsWith('library.tab') ||
+        id == 'top') {
+      final left = w * (desktop ? 0.18 : 0.06);
+      return Rect.fromLTWH(left, 8, w - left - 16, 96);
+    }
+    // The main content stage ('content', 'feed.page', 'graph.canvas',
+    // 'card.first', 'reader.*', 'catalog.item', 'folders.*', 'todo.*', …).
+    final left = desktop ? 96.0 : w * 0.06;
+    return Rect.fromLTWH(
+      left,
+      h * 0.14,
+      w - left - (desktop ? 24 : w * 0.06),
+      h * 0.66,
+    );
+  }
+}
+
+/// Always mounted so the implicit tweens retarget — the hole and cursor glide
+/// from the previous target to the next instead of resetting. When [target] is
+/// null the whole layer just fades out, holding its last geometry.
+class _Guidance extends StatefulWidget {
+  const _Guidance({
+    required this.target,
+    required this.dim,
+    required this.tapping,
+    required this.screen,
+    required this.color,
+  });
+
+  final Rect? target;
+
+  /// Punch a dimming hole around the target (only worthwhile for small ones).
+  final bool dim;
+
+  /// The agent is tapping the target right now — render a tap ripple.
+  final bool tapping;
+
+  final Size screen;
+  final Color color;
+
+  @override
+  State<_Guidance> createState() => _GuidanceState();
+}
+
+class _GuidanceState extends State<_Guidance> {
+  late Rect _target = Rect.fromCenter(
+    center: widget.screen.center(Offset.zero),
+    width: 120,
+    height: 120,
+  );
+
+  @override
+  void initState() {
+    super.initState();
+    if (widget.target != null) _target = widget.target!;
+  }
+
+  @override
+  void didUpdateWidget(_Guidance old) {
+    super.didUpdateWidget(old);
+    // Adopt a new target only when it actually moved — the ~150ms geometry
+    // poll re-resolves the same widget with sub-pixel jitter every tick, and
+    // feeding that into the tween would restart the glide forever (the old
+    // "broken spotlight"). A few pixels of slack absorbs the jitter.
+    final t = widget.target;
+    if (t != null && !_closeEnough(t, _target)) _target = t;
+  }
+
+  bool _closeEnough(Rect a, Rect b) =>
+      (a.center - b.center).distance < 6 &&
+      (a.width - b.width).abs() < 6 &&
+      (a.height - b.height).abs() < 6;
+
+  @override
+  Widget build(BuildContext context) {
+    return AnimatedOpacity(
+      opacity: widget.target != null ? 1 : 0,
+      duration: const Duration(milliseconds: 350),
+      curve: Curves.easeOut,
+      child: TweenAnimationBuilder<Rect?>(
+        // Only `end` matters — TweenAnimationBuilder animates from the current
+        // in-flight value to a new end whenever it changes, so the hole and
+        // cursor glide smoothly target-to-target.
+        tween: RectTween(begin: _target, end: _target),
+        duration: const Duration(milliseconds: 550),
+        curve: Curves.easeInOutCubic,
+        builder: (context, animated, _) {
+          final r = animated ?? _target;
+          return Stack(
+            children: [
+              if (widget.dim)
+                Positioned.fill(
+                  child:
+                      CustomPaint(painter: _SpotlightPainter(r, widget.color)),
+                ),
+              // Presentation cursor gliding to the target, like a tour guide's
+              // pointer, with a tap ripple when the agent clicks.
+              Positioned(
+                left: r.center.dx - 18,
+                top: r.center.dy - 18,
+                child: _Cursor(color: widget.color, tapping: widget.tapping),
+              ),
+            ],
+          );
+        },
+      ),
+    );
+  }
+}
+
+class _SpotlightPainter extends CustomPainter {
+  _SpotlightPainter(this.rect, this.color);
+  final Rect rect;
+  final Color color;
+
+  @override
+  void paint(Canvas canvas, Size size) {
+    final full = Offset.zero & size;
+    final cut = RRect.fromRectAndRadius(
+      rect.inflate(8),
+      const Radius.circular(16),
+    );
+    // Scrim with a hole punched out around the lit widget.
+    final scrim = Path.combine(
+      PathOperation.difference,
+      Path()..addRect(full),
+      Path()..addRRect(cut),
+    );
+    // Light enough that a dark theme doesn't collapse into a black wash.
+    canvas.drawPath(scrim, Paint()..color = Colors.black.withValues(alpha: 0.35));
+    // Glowing ring around the lit widget.
+    canvas.drawRRect(
+      cut,
+      Paint()
+        ..style = PaintingStyle.stroke
+        ..strokeWidth = 2
+        ..color = color.withValues(alpha: 0.85)
+        ..maskFilter = const MaskFilter.blur(BlurStyle.normal, 6),
+    );
+  }
+
+  @override
+  bool shouldRepaint(_SpotlightPainter old) =>
+      old.rect != rect || old.color != color;
+}
+
+/// The tour-guide pointer. A steady dot that glides to the target, plus an
+/// expanding ring that fires while [tapping] so a "click" is visible.
+class _Cursor extends StatelessWidget {
+  const _Cursor({required this.color, required this.tapping});
+  final Color color;
+  final bool tapping;
+
+  @override
+  Widget build(BuildContext context) {
+    return SizedBox(
+      width: 36,
+      height: 36,
+      child: Stack(
+        alignment: Alignment.center,
+        children: [
+          // Tap ripple: a ring that expands and fades out on each tap.
+          TweenAnimationBuilder<double>(
+            key: ValueKey(tapping),
+            tween: Tween(begin: tapping ? 0.0 : 1.0, end: 1.0),
+            duration: const Duration(milliseconds: 260),
+            curve: Curves.easeOut,
+            builder: (context, t, _) {
+              if (!tapping) return const SizedBox.shrink();
+              return Opacity(
+                opacity: (1 - t).clamp(0.0, 1.0),
+                child: Container(
+                  width: 12 + 30 * t,
+                  height: 12 + 30 * t,
+                  decoration: BoxDecoration(
+                    shape: BoxShape.circle,
+                    border: Border.all(
+                        color: Colors.white.withValues(alpha: 0.9), width: 2),
+                  ),
+                ),
+              );
+            },
+          ),
+          // The pointer dot.
+          Container(
+            width: 24,
+            height: 24,
+            decoration: BoxDecoration(
+              shape: BoxShape.circle,
+              color: color.withValues(alpha: 0.35),
+              border:
+                  Border.all(color: Colors.white.withValues(alpha: 0.9), width: 2),
+              boxShadow: [
+                BoxShadow(
+                  color: color.withValues(alpha: 0.7),
+                  blurRadius: 18,
+                  spreadRadius: 2,
+                ),
+              ],
+            ),
+          ),
+        ],
+      ),
+    );
+  }
+}

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

@@ -6,6 +6,7 @@ import 'package:flutter/foundation.dart';
 
 import '../../../../data/repositories/card_repository.dart';
 import '../../../../data/services/api_client.dart';
+import '../../../core/safe_notifier.dart';
 
 class ChatMessage {
   const ChatMessage({required this.role, required this.content});
@@ -16,7 +17,7 @@ class ChatMessage {
   Map<String, String> toWire() => {'role': role, 'content': content};
 }
 
-class ChatViewModel extends ChangeNotifier {
+class ChatViewModel extends ChangeNotifier with SafeNotifier {
   ChatViewModel({required CardRepository repository, required this.cardId})
       : _repository = repository;
 

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

@@ -8,8 +8,9 @@ import 'package:flutter/foundation.dart';
 
 import '../../../../data/repositories/card_repository.dart';
 import '../../../../data/services/api_client.dart';
+import '../../../core/safe_notifier.dart';
 
-class RabbitHoleViewModel extends ChangeNotifier {
+class RabbitHoleViewModel extends ChangeNotifier with SafeNotifier {
   RabbitHoleViewModel({required CardRepository repository, required this.cardId})
       : _repository = repository;
 

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

@@ -12,8 +12,9 @@ import '../../../../domain/models/artifact.dart';
 import '../../../../domain/models/card.dart';
 import '../../../../domain/models/concept.dart';
 import '../../../../domain/models/pipeline_event.dart';
+import '../../../core/safe_notifier.dart';
 
-class ReaderViewModel extends ChangeNotifier {
+class ReaderViewModel extends ChangeNotifier with SafeNotifier {
   ReaderViewModel({required CardRepository repository, required this.cardId})
       : _repository = repository;
 

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

@@ -72,10 +72,40 @@ class _ReaderAgentBridge extends StatefulWidget {
   State<_ReaderAgentBridge> createState() => _ReaderAgentBridgeState();
 }
 
+/// Spotlight anchors for the reader's sections, so the presenter's cursor can
+/// land on the real blocks / "Going deeper" / references / action bar it's
+/// talking about instead of a guessed region.
+class ReaderSpotlightKeys {
+  final blocks = GlobalKey();
+  final insight = GlobalKey();
+  final references = GlobalKey();
+  final actionBar = GlobalKey();
+}
+
+/// Hands the section keys down to [_ReaderView] without threading them through
+/// every constructor. Absent when not presenting.
+class _ReaderSpotlight extends InheritedWidget {
+  const _ReaderSpotlight({required this.keys, required super.child});
+  final ReaderSpotlightKeys keys;
+
+  static ReaderSpotlightKeys? of(BuildContext context) => context
+      .dependOnInheritedWidgetOfExactType<_ReaderSpotlight>()
+      ?.keys;
+
+  @override
+  bool updateShouldNotify(_ReaderSpotlight old) => false;
+}
+
 class _ReaderAgentBridgeState extends State<_ReaderAgentBridge> {
   AgentBus? _bus;
   ReaderAgentHooks? _hooks;
   ReaderViewModel? _vm;
+  final _bodyKey = GlobalKey();
+  final _spotlight = ReaderSpotlightKeys();
+
+  // Handed to the reader's scroll view below via PrimaryScrollController, so
+  // the agent can scroll through a card while narrating it.
+  final _scroll = ScrollController();
 
   @override
   void didChangeDependencies() {
@@ -90,6 +120,15 @@ class _ReaderAgentBridgeState extends State<_ReaderAgentBridge> {
     );
     _hooks = hooks;
     _bus!.attachReader(hooks);
+    _bus!.registerSpotlight('reader.body', _bodyKey);
+    _bus!.registerSpotlight('reader.blocks', _spotlight.blocks);
+    _bus!.registerSpotlight('reader.insight', _spotlight.insight);
+    _bus!.registerSpotlight('reader.references', _spotlight.references);
+    // Ask and the three-dots menu both live in the bottom action bar; point at
+    // it for both — the narration says which control.
+    _bus!.registerSpotlight('reader.ask', _spotlight.actionBar);
+    _bus!.registerSpotlight('reader.more', _spotlight.actionBar);
+    _bus!.registerScrollable('reader', _scroll);
   }
 
   Future<bool> _toggleCheck() async {
@@ -130,11 +169,25 @@ class _ReaderAgentBridgeState extends State<_ReaderAgentBridge> {
   void dispose() {
     final h = _hooks;
     if (h != null) _bus?.detachReader(h);
+    _bus?.unregisterSpotlight('reader.body', _bodyKey);
+    _bus?.unregisterSpotlight('reader.blocks', _spotlight.blocks);
+    _bus?.unregisterSpotlight('reader.insight', _spotlight.insight);
+    _bus?.unregisterSpotlight('reader.references', _spotlight.references);
+    _bus?.unregisterSpotlight('reader.ask', _spotlight.actionBar);
+    _bus?.unregisterSpotlight('reader.more', _spotlight.actionBar);
+    _bus?.unregisterScrollable('reader', _scroll);
+    _scroll.dispose();
     super.dispose();
   }
 
   @override
-  Widget build(BuildContext context) => widget.child;
+  Widget build(BuildContext context) => PrimaryScrollController(
+        controller: _scroll,
+        child: _ReaderSpotlight(
+          keys: _spotlight,
+          child: KeyedSubtree(key: _bodyKey, child: widget.child),
+        ),
+      );
 }
 
 class _ReaderView extends StatelessWidget {
@@ -168,6 +221,7 @@ class _ReaderView extends StatelessWidget {
     final accent = ContentAccent.of(card.base.contentType);
     final readMins = _estimateReadMinutes(card);
     final highlightStore = context.read<HighlightStore>();
+    final spotlight = _ReaderSpotlight.of(context);
 
     void onHighlight(String text) {
       highlightStore.add(Highlight(
@@ -241,7 +295,9 @@ class _ReaderView extends StatelessWidget {
 
                       // Structured blocks — skeleton while building, fades in on arrival
                       if (card.blocks.isNotEmpty) ...[
-                        _fadeIn(BlockList(
+                        _fadeIn(KeyedSubtree(
+                          key: spotlight?.blocks,
+                          child: BlockList(
                           blocks: card.blocks,
                           onToggleChecklist: vm.toggleChecklistItem,
                           onToggleStep: vm.toggleStep,
@@ -255,7 +311,7 @@ class _ReaderView extends StatelessWidget {
                             ),
                           ),
                           onHighlight: card.isReady ? onHighlight : null,
-                        )),
+                        ))),
                         if (card.isProcessing) ...[
                           const SizedBox(height: 12),
                           const _SkeletonBox(height: 70, radius: Insets.radius),
@@ -274,16 +330,23 @@ class _ReaderView extends StatelessWidget {
                       if (card.isReady &&
                           card.insight != null &&
                           card.insight!.hasContent)
-                        InsightSection(
-                          insight: card.insight!,
-                          accent: accent,
-                          cardId: card.cardId,
-                          cardTitle: card.base.oneLiner,
-                          readMinutes: readMins,
+                        KeyedSubtree(
+                          key: spotlight?.insight,
+                          child: InsightSection(
+                            insight: card.insight!,
+                            accent: accent,
+                            cardId: card.cardId,
+                            cardTitle: card.base.oneLiner,
+                            readMinutes: readMins,
+                          ),
                         ),
 
                       // Referenced catalog items
-                      if (card.isReady) _ReferencesStrip(entries: vm.artifacts),
+                      if (card.isReady)
+                        KeyedSubtree(
+                          key: spotlight?.references,
+                          child: _ReferencesStrip(entries: vm.artifacts),
+                        ),
 
                       // Concepts this card contributed to
                       if (card.isReady) _ConceptsStrip(entries: vm.concepts),
@@ -302,20 +365,30 @@ class _ReaderView extends StatelessWidget {
       return Column(
         children: [
           _EmbeddedHeader(card: card, accent: accent, onClose: onClose),
-          Expanded(child: SingleChildScrollView(child: content)),
-          if (card.isReady) PrimaryActionBar(card: card),
+          Expanded(child: SingleChildScrollView(primary: true, child: content)),
+          if (card.isReady)
+            KeyedSubtree(
+              key: spotlight?.actionBar,
+              child: PrimaryActionBar(card: card),
+            ),
         ],
       );
     }
 
     return Scaffold(
       body: CustomScrollView(
+        primary: true,
         slivers: [
           _FaceAppBar(card: card, api: api, accent: accent),
           SliverToBoxAdapter(child: content),
         ],
       ),
-      bottomSheet: card.isReady ? PrimaryActionBar(card: card) : null,
+      bottomSheet: card.isReady
+          ? KeyedSubtree(
+              key: spotlight?.actionBar,
+              child: PrimaryActionBar(card: card),
+            )
+          : null,
     );
   }
 

app/lib/ui/features/search/views/search_screen.dart

@@ -38,9 +38,12 @@ class _SearchScreenState extends State<SearchScreen> {
   String _query = '';
   ContentType? _filter; // null = All
 
-  // Agent driving: let the presenter agent run searches while mounted.
+  // Agent driving: let the presenter agent run searches while mounted, and
+  // give its spotlight real geometry for the field and the filter bar.
   AgentBus? _bus;
   SearchAgentHooks? _hooks;
+  final _fieldKey = GlobalKey();
+  final _filtersKey = GlobalKey();
 
   @override
   void didChangeDependencies() {
@@ -50,6 +53,9 @@ class _SearchScreenState extends State<SearchScreen> {
     final hooks = SearchAgentHooks(run: _runAgentQuery, filter: _applyAgentFilter);
     _hooks = hooks;
     _bus!.attachSearch(hooks);
+    _bus!
+      ..registerSpotlight('search.field', _fieldKey)
+      ..registerSpotlight('search.filters', _filtersKey);
   }
 
   void _runAgentQuery(String query) {
@@ -114,6 +120,9 @@ class _SearchScreenState extends State<SearchScreen> {
   void dispose() {
     final h = _hooks;
     if (h != null) _bus?.detachSearch(h);
+    _bus
+      ?..unregisterSpotlight('search.field', _fieldKey)
+      ..unregisterSpotlight('search.filters', _filtersKey);
     _debounce?.cancel();
     _controller.dispose();
     super.dispose();
@@ -126,6 +135,7 @@ class _SearchScreenState extends State<SearchScreen> {
       appBar: AppBar(
         titleSpacing: 0,
         title: TextField(
+          key: _fieldKey,
           controller: _controller,
           autofocus: true,
           onChanged: _onChanged,
@@ -182,6 +192,7 @@ class _SearchScreenState extends State<SearchScreen> {
           crossAxisAlignment: CrossAxisAlignment.stretch,
           children: [
             _FilterBar(
+              key: _filtersKey,
               types: _presentTypes,
               selected: _filter,
               total: _results.length,
@@ -224,6 +235,7 @@ class _SearchScreenState extends State<SearchScreen> {
 /// filters for types present in the results (docs/06 search).
 class _FilterBar extends StatelessWidget {
   const _FilterBar({
+    super.key,
     required this.types,
     required this.selected,
     required this.total,

backend/app/api/presenter.py

@@ -33,8 +33,8 @@ _VIEWS = {
 
 # Action verbs the Flutter agent knows how to execute (mirrors AgentAction).
 _ACTIONS = {
-    "navigate", "wait", "create_card", "search", "search_filter", "open_card",
-    "reader_toggle",
+    "navigate", "wait", "scroll", "create_card", "search", "search_filter",
+    "open_card", "reader_toggle",
     "graph_focus", "graph_open", "graph_wander", "graph_reset", "graph_cluster",
     "graph_concepts",
     "feed_next", "feed_prev", "feed_shuffle",
@@ -78,13 +78,19 @@ asks a question or hands you a task, don't just describe things — DEMONSTRATE
 them by driving the app, then narrate what's happening.
 
 You reply with an ordered list of "beats". Each beat has:
-  - "say": one short sentence to speak aloud (no markdown, spell out acronyms
-    like "U R L"), or null to just perform the action silently.
-  - "action": one thing to do, or null to just talk.
+  - "say": one short line to speak aloud, or null to perform the action silently.
+    Write it the way a friendly human presenter talks: casual, contractions,
+    short sentences, react to what's on screen ("okay, watch this", "there it
+    is"). No markdown. Avoid acronyms entirely — say "the link" not "URL",
+    "a quick summary" not "TL;DR" — never spell letters out.
+  - "action": one thing to do, or null to just talk. The app speaks the line
+    WHILE performing the action, like a person narrating over their own clicks.
 
 An action is an object with a "do" field and optional args:
   - {{"do":"navigate","view":"<view>"}}  — view is one of: library, feed, graph,
     search, collections, actions, profile, catalog, concepts, connections.
+  - {{"do":"scroll","target":"library|reader","dy":<pixels>}} — scroll the
+    library grid or the open card; negative dy scrolls up.
   - {{"do":"search","query":"<text>"}}   — open search and run a query.
   - {{"do":"search_filter"}}  — narrow current results by content type.
   - {{"do":"open_card","query":"<text>"}} — open the best-matching saved card.
@@ -125,6 +131,11 @@ class AskRequest(BaseModel):
     question: str
 
 
+class LogRequest(BaseModel):
+    message: str
+    level: str = "info"
+
+
 class Step(BaseModel):
     say: str | None = None
     action: dict[str, Any] | None = None
@@ -161,6 +172,15 @@ def _clean_action(raw: Any) -> dict[str, Any] | None:
             action["ms"] = int(raw.get("ms", 800))
         except (TypeError, ValueError):
             action["ms"] = 800
+    if verb == "scroll":
+        target = str(raw.get("target", "library")).strip().lower()
+        if target not in {"library", "reader"}:
+            return None
+        action["target"] = target
+        try:
+            action["dy"] = int(raw.get("dy", 600))
+        except (TypeError, ValueError):
+            action["dy"] = 600
     return action
 
 
@@ -198,6 +218,26 @@ def _parse(raw: str | None) -> AskResponse:
     return AskResponse(steps=steps) if steps else fallback
 
 
+_LOG_LEVELS = {
+    "debug": logging.DEBUG,
+    "info": logging.INFO,
+    "warning": logging.WARNING,
+    "error": logging.ERROR,
+}
+
+
+@router.post("/log")
+async def relay_log(req: LogRequest) -> dict[str, bool]:
+    """Relay a Present-mode event from the browser into this same pipeline
+    log, since `debugPrint` alone depends on the browser's DWDS log
+    forwarding making it back to the terminal — flaky enough that presenter
+    errors were going unseen. This endpoint is the reliable path: whatever
+    lands here is guaranteed to print in `start.py`'s console."""
+    level = _LOG_LEVELS.get(req.level.strip().lower(), logging.INFO)
+    log.log(level, "[frontend] %s", req.message.strip())
+    return {"ok": True}
+
+
 @router.post("/ask", response_model=AskResponse)
 async def ask(req: AskRequest) -> AskResponse:
     """Answer one audience question/task as an ordered list of speak+do beats."""