Merge pull request 'Release v26.04.14.2 — News card title readability' (#22) from dev into main

Purple-on-black was eye-catching but hard to read. Switch title text
to onSurface for contrast; keep the underline in primary at 70% alpha
as the "this is a link" signal.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

.forgejo/workflows/ci.yml

@@ -1,6 +1,12 @@
-# CI runs only on release tags.
+# CI runs first; build only proceeds if all checks pass.
 #
-# Tag v*:  analyze + test → build APK → attach to Forgejo Release
+# Push to dev:       flutter analyze + flutter test
+# Tag v* (release):  gates + signed APK build + attach to Forgejo Release
+#
+# main pushes are NOT gated here: a merge to main only happens after
+# dev has already passed CI, and the release tag is the sole trigger
+# for a signed APK build. Re-running analyze+test on the merge commit
+# just burns runner time without changing the outcome.
 #
 # To cut a release:
 #   Create a release via the Forgejo UI on main with a v* tag name.
@@ -11,19 +17,39 @@
 # commands directly instead.
 #
 # Required secrets (repo → Settings → Secrets → Actions):
-#   RELEASE_TOKEN  — Forgejo PAT with write:repository scope
+#   RELEASE_TOKEN                   — Forgejo PAT with write:repository scope
+#   RELEASE_KEYSTORE_BASE64         — base64 of the signing keystore
+#   RELEASE_KEYSTORE_PASSWORD       — keystore + key password
+#   RELEASE_KEY_ALIAS               — key alias within the keystore
 name: CI & Build
 
 on:
   push:
+    branches: [dev]
     tags: ["v*"]
 
+# Cancel older runs on the same branch when a newer push lands. Tag runs
+# are never cancelled so a release build can't kill itself mid-flight.
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: ${{ !startsWith(github.ref, 'refs/tags/') }}
+
+# Least-privilege default. The build job upgrades to contents: write
+# so it can attach the APK to a Forgejo release.
+permissions:
+  contents: read
+
 jobs:
   analyze:
     name: Analyze & test
-    runs-on: py3.12-node22
+    runs-on: ci-runner
     container:
-      image: ghcr.io/cirruslabs/flutter:stable
+      # Pinned to a specific Flutter version for reproducible builds.
+      # Floating :stable means a random Flutter minor bump could change
+      # analyzer output or break the build without any commit landing.
+      # Bump this line (and verify locally with `flutter --version`)
+      # when you intentionally want a newer Flutter.
+      image: ghcr.io/cirruslabs/flutter:3.41.6
     steps:
       - name: Checkout
         run: |
@@ -42,9 +68,14 @@ jobs:
   build:
     name: Build release APK
     needs: [analyze]
-    runs-on: py3.12-node22
+    # Only tag pushes produce a signed release build. dev pushes
+    # run the gates above and stop there.
+    if: startsWith(github.ref, 'refs/tags/')
+    runs-on: ci-runner
     container:
-      image: ghcr.io/cirruslabs/flutter:stable
+      image: ghcr.io/cirruslabs/flutter:3.41.6
+    permissions:
+      contents: write
     steps:
       - name: Checkout
         run: |
@@ -74,57 +105,12 @@ jobs:
             --build-name="$BUILD_NAME" \
             --build-number="$BUILD_NUMBER"
 
-      - name: Set artifact name
-        id: artifact
-        run: |
-          echo "name=fabledapp-${{ github.ref_name }}-${{ github.sha }}" >> $GITHUB_OUTPUT
-
-      - name: Upload artifact to Forgejo
-        env:
-          RELEASE_TOKEN: ${{ secrets.RELEASE_TOKEN }}
-          APK: build/app/outputs/flutter-apk/app-release.apk
-          API: https://git.fabledsword.com/api/v1/repos/bvandeusen/FabledApp
-          ARTIFACT_NAME: ${{ steps.artifact.outputs.name }}
-        run: |
-          # Upload the APK as a workflow artifact via the Forgejo API.
-          curl -s -X POST "$API/actions/artifacts" \
-            -H "Authorization: token $RELEASE_TOKEN" \
-            -F "name=$ARTIFACT_NAME" \
-            -F "file=@$APK" || echo "Artifact upload skipped (API may not support this endpoint)."
-
       - name: Publish Forgejo release
+        # Release-publish logic lives in a shell script so it's
+        # testable locally (bash -x scripts/publish_apk_release.sh
+        # with env vars set) instead of trapped in YAML.
         env:
           RELEASE_TOKEN: ${{ secrets.RELEASE_TOKEN }}
           TAG: ${{ github.ref_name }}
-          API: https://git.fabledsword.com/api/v1/repos/bvandeusen/FabledApp
+          APK: build/app/outputs/flutter-apk/app-release.apk
-        run: |
+        run: bash scripts/publish_apk_release.sh
-          # Look for an existing release (created via the UI or a prior run).
-          EXISTING=$(curl -s \
-            "$API/releases/tags/$TAG" \
-            -H "Authorization: token $RELEASE_TOKEN")
-
-          RELEASE_ID=$(echo "$EXISTING" | grep -oE '"id":[[:space:]]*[0-9]+' | head -1 | grep -oE '[0-9]+')
-
-          if [ -n "$RELEASE_ID" ]; then
-            echo "Found existing release $TAG (id $RELEASE_ID), attaching APK..."
-          else
-            echo "No existing release found, creating $TAG..."
-            RESPONSE=$(curl -s -X POST "$API/releases" \
-              -H "Authorization: token $RELEASE_TOKEN" \
-              -H "Content-Type: application/json" \
-              -d "{\"tag_name\": \"$TAG\", \"name\": \"$TAG\", \"body\": \"\"}")
-            RELEASE_ID=$(echo "$RESPONSE" | grep -oE '"id":[[:space:]]*[0-9]+' | head -1 | grep -oE '[0-9]+')
-            if [ -z "$RELEASE_ID" ]; then
-              echo "Failed to create release. API response:"
-              echo "$RESPONSE"
-              exit 1
-            fi
-            echo "Release created with id $RELEASE_ID."
-          fi
-
-          curl -s -X POST "$API/releases/$RELEASE_ID/assets" \
-            -H "Authorization: token $RELEASE_TOKEN" \
-            -F "attachment=@build/app/outputs/flutter-apk/app-release.apk"
-
-          echo "Done — $TAG is live at:"
-          echo "https://git.fabledsword.com/bvandeusen/FabledApp/releases/tag/$TAG"

lib/data/api/chat_api.dart

@@ -18,6 +18,15 @@ class ChatStatusUpdate extends ChatStreamEvent {
   ChatStatusUpdate(this.status);
 }
 
+/// A single tool call fired during generation. Mirrors the `tool_call` SSE
+/// event emitted by `generation_task.py` and the `tool_calls` array persisted
+/// on the assistant Message row — same shape either way so the UI can render
+/// live chips during streaming and re-render them from storage after reload.
+class ChatToolCall extends ChatStreamEvent {
+  final Map<String, dynamic> toolCall;
+  ChatToolCall(this.toolCall);
+}
+
 class ChatApi {
   final Dio _dio;
   const ChatApi(this._dio);
@@ -136,6 +145,14 @@ class ChatApi {
               } catch (_) {
                 // Ignore malformed status events
               }
+            } else if (currentEvent == 'tool_call') {
+              try {
+                final obj = json.decode(data) as Map<String, dynamic>;
+                final tc = obj['tool_call'];
+                if (tc is Map<String, dynamic>) yield ChatToolCall(tc);
+              } catch (_) {
+                // Ignore malformed tool_call events
+              }
             }
           } else if (line.isEmpty) {
             currentEvent = ''; // blank line = SSE event separator

lib/data/api/voice_api.dart

@@ -15,8 +15,9 @@ class VoiceStatus {
     required this.tts,
   });
 
-  /// True only when voice is enabled AND both STT and TTS are ready.
+  /// True when voice is enabled and at least STT is ready.
-  bool get fullyAvailable => enabled && stt && tts;
+  /// TTS is optional — voice mode works without it (STT-only).
+  bool get fullyAvailable => enabled && stt;
 
   factory VoiceStatus.fromJson(Map<String, dynamic> json) => VoiceStatus(
         enabled: json['enabled'] as bool? ?? false,

lib/data/models/message.dart

@@ -8,6 +8,11 @@ class Message {
   final String status; // "complete" | "generating"
   final DateTime? createdAt;
   final Map<String, dynamic>? metadata;
+  // Tool invocations attached to this message. Each entry matches the shape
+  // persisted by the backend (`function`, `arguments`, `result`, `status`) so
+  // the UI can render the same chips whether they arrive live over SSE or
+  // from a reload.
+  final List<Map<String, dynamic>>? toolCalls;
 
   const Message({
     this.id,
@@ -17,21 +22,39 @@ class Message {
     this.status = 'complete',
     this.createdAt,
     this.metadata,
+    this.toolCalls,
   });
 
-  factory Message.fromJson(Map<String, dynamic> json) => Message(
+  factory Message.fromJson(Map<String, dynamic> json) {
-        id: json['id'] as int?,
+    final rawCalls = json['tool_calls'];
-        conversationId: json['conversation_id'] as int,
+    List<Map<String, dynamic>>? parsedCalls;
-        role: json['role'] == 'user' ? MessageRole.user : MessageRole.assistant,
+    if (rawCalls is List) {
-        content: json['content'] as String,
+      parsedCalls = [
-        status: json['status'] as String? ?? 'complete',
+        for (final tc in rawCalls)
-        createdAt: json['created_at'] != null
+          if (tc is Map<String, dynamic>) tc,
-            ? DateTime.parse(json['created_at'] as String)
+      ];
-            : null,
+      if (parsedCalls.isEmpty) parsedCalls = null;
-        metadata: json['metadata'] as Map<String, dynamic>?,
+    }
-      );
+    return Message(
+      id: json['id'] as int?,
+      conversationId: json['conversation_id'] as int,
+      role: json['role'] == 'user' ? MessageRole.user : MessageRole.assistant,
+      content: json['content'] as String,
+      status: json['status'] as String? ?? 'complete',
+      createdAt: json['created_at'] != null
+          ? DateTime.parse(json['created_at'] as String)
+          : null,
+      metadata: json['metadata'] as Map<String, dynamic>?,
+      toolCalls: parsedCalls,
+    );
+  }
 
-  Message copyWith({String? content, String? status}) => Message(
+  Message copyWith({
+    String? content,
+    String? status,
+    List<Map<String, dynamic>>? toolCalls,
+  }) =>
+      Message(
         id: id,
         conversationId: conversationId,
         role: role,
@@ -39,5 +62,6 @@ class Message {
         status: status ?? this.status,
         createdAt: createdAt,
         metadata: metadata,
+        toolCalls: toolCalls ?? this.toolCalls,
       );
 }

lib/data/repositories/chat_repository.dart

@@ -1,5 +1,6 @@
 import '../api/chat_api.dart';
-export '../api/chat_api.dart' show ChatStreamEvent, ChatTextChunk, ChatStatusUpdate;
+export '../api/chat_api.dart'
+    show ChatStreamEvent, ChatTextChunk, ChatStatusUpdate, ChatToolCall;
 import '../models/conversation.dart';
 import '../models/message.dart';
 

lib/providers/briefing_provider.dart

@@ -1,3 +1,5 @@
+import 'dart:async';
+
 import 'package:flutter_riverpod/flutter_riverpod.dart';
 
 import '../data/api/chat_api.dart';
@@ -49,6 +51,40 @@ class BriefingNotifier extends AsyncNotifier<BriefingConversation> {
     await future;
   }
 
+  /// Re-fetch the current briefing conversation and unfreeze a stuck
+  /// streaming state if the server-side message is already complete.
+  ///
+  /// Same role as MessagesNotifier.refresh() in chat_provider: when an SSE
+  /// socket dies silently (mobile network handoff, app backgrounded mid-stream,
+  /// reverse proxy dropping idle sockets) the send loop never observes close
+  /// and [isBriefingStreamingProvider] stays stuck true. This is the manual
+  /// recovery path hit by pull-to-refresh, the AppBar refresh button, and the
+  /// lifecycle-resume hook.
+  Future<void> refreshMessages() async {
+    final current = state.value;
+    if (current == null) {
+      ref.invalidateSelf();
+      return;
+    }
+    try {
+      final fresh = await ref.read(briefingApiProvider).getToday();
+      state = AsyncData(fresh);
+      final messages = fresh.messages;
+      Message? lastAssistant;
+      for (var i = messages.length - 1; i >= 0; i--) {
+        if (messages[i].role == MessageRole.assistant) {
+          lastAssistant = messages[i];
+          break;
+        }
+      }
+      if (lastAssistant != null && lastAssistant.status != 'generating') {
+        ref.read(isBriefingStreamingProvider.notifier).state = false;
+      }
+    } catch (_) {
+      // Network hiccup — keep existing state; user can retry.
+    }
+  }
+
   /// Inject a news article as context and trigger generation.
   ///
   /// Mirrors sendReply() but calls the /discuss endpoint instead of
@@ -77,26 +113,106 @@ class BriefingNotifier extends AsyncNotifier<BriefingConversation> {
       rethrow;
     }
 
-    // SSE stream (best-effort)
+    final streamedContent = await _consumeStream(chatApi.streamGeneration(convId));
-    bool streamedContent = false;
+    await _pollUntilComplete(convId, streamedContent);
+  }
+
+  /// Send a reply to today's briefing conversation.
+  ///
+  /// Mirrors MessagesNotifier.sendMessage() in chat_provider with the same
+  /// stall-watchdog pattern:
+  ///   1. Optimistic UI update
+  ///   2. POST message to chat endpoint
+  ///   3. SSE stream with per-event timeout (stall watchdog)
+  ///   4. Poll until complete
+  Future<void> sendReply(String content) async {
+    final conv = state.value;
+    if (conv == null) return;
+    final convId = conv.id;
+    final chatApi = ref.read(chatApiProvider);
+
+    final previous = conv.messages;
+    final userMsg = Message(
+      conversationId: convId,
+      role: MessageRole.user,
+      content: content,
+    );
+    final placeholder = Message(
+      conversationId: convId,
+      role: MessageRole.assistant,
+      content: '',
+      status: 'generating',
+    );
+    state = AsyncData(conv.copyWith(messages: [...previous, userMsg, placeholder]));
+    ref.read(isBriefingStreamingProvider.notifier).state = true;
+
     try {
-      await for (final event in chatApi.streamGeneration(convId)) {
+      await chatApi.sendMessage(convId, content);
-        if (event is! ChatTextChunk) continue;
+    } catch (e) {
-        streamedContent = true;
+      state = AsyncData(conv.copyWith(messages: previous));
+      ref.read(isBriefingStreamingProvider.notifier).state = false;
+      rethrow;
+    }
+
+    final streamedContent = await _consumeStream(chatApi.streamGeneration(convId));
+    await _pollUntilComplete(convId, streamedContent);
+  }
+
+  /// Consume an SSE stream into the current briefing conversation state.
+  ///
+  /// Uses a StreamIterator with a per-event timeout as a stall watchdog —
+  /// same rationale as MessagesNotifier.sendMessage() in chat_provider.dart.
+  /// Mobile networks occasionally drop SSE sockets silently: the TCP
+  /// connection is half-closed, Dio never sees the close, and `await for`
+  /// hangs forever with [isBriefingStreamingProvider] stuck true. If no event
+  /// arrives within the watchdog window we bail out and let the polling pass
+  /// below reconcile state from the server.
+  ///
+  /// Returns whether any text content was actually streamed (the polling
+  /// pass uses this to decide whether it's safe to overwrite with a possibly
+  /// empty server-side row).
+  Future<bool> _consumeStream(Stream<ChatStreamEvent> stream) async {
+    const stallTimeout = Duration(seconds: 45);
+    bool streamedContent = false;
+    final iter = StreamIterator(stream);
+    try {
+      while (await iter.moveNext().timeout(stallTimeout)) {
+        final event = iter.current;
         final current = state.value;
         if (current == null) break;
         final msgs = current.messages;
         if (msgs.isEmpty) continue;
-        final updated =
+        if (event is ChatTextChunk) {
-            msgs.last.copyWith(content: msgs.last.content + event.text);
+          streamedContent = true;
-        state = AsyncData(current.copyWith(
+          final updated =
-            messages: [...msgs.sublist(0, msgs.length - 1), updated]));
+              msgs.last.copyWith(content: msgs.last.content + event.text);
+          state = AsyncData(current.copyWith(
+              messages: [...msgs.sublist(0, msgs.length - 1), updated]));
+        } else if (event is ChatToolCall) {
+          final last = msgs.last;
+          if (last.role != MessageRole.assistant) continue;
+          final nextCalls = [...?last.toolCalls, event.toolCall];
+          final updated = last.copyWith(toolCalls: nextCalls);
+          state = AsyncData(current.copyWith(
+              messages: [...msgs.sublist(0, msgs.length - 1), updated]));
+        }
       }
+    } on TimeoutException {
+      // Stall watchdog — no SSE event for stallTimeout. Fall through to
+      // polling so the UI eventually unfreezes even if the socket is dead.
     } catch (_) {
-      // Fall through to polling.
+      // SSE failed — fall through to polling.
+    } finally {
+      await iter.cancel();
     }
+    return streamedContent;
+  }
 
-    // Poll until complete (max 20 attempts, 2s apart)
+  /// Poll /api/briefing messages until the last assistant row is complete,
+  /// same reconcile pattern as MessagesNotifier.sendMessage(). Always clears
+  /// [isBriefingStreamingProvider] at the end so the input can't stay locked.
+  Future<void> _pollUntilComplete(int convId, bool streamedContent) async {
+    final briefingApi = ref.read(briefingApiProvider);
     try {
       for (var attempt = 0; attempt < 20; attempt++) {
         if (attempt > 0) await Future.delayed(const Duration(seconds: 2));
@@ -128,93 +244,4 @@ class BriefingNotifier extends AsyncNotifier<BriefingConversation> {
       ref.read(isBriefingStreamingProvider.notifier).state = false;
     }
   }
-
-  /// Send a reply to today's briefing conversation.
-  ///
-  /// Mirrors MessagesNotifier.sendMessage():
-  ///   1. Optimistic UI update
-  ///   2. POST message to chat endpoint
-  ///   3. SSE stream (best-effort)
-  ///   4. Poll until complete
-  Future<void> sendReply(String content) async {
-    final conv = state.value;
-    if (conv == null) return;
-    final convId = conv.id;
-    final chatApi = ref.read(chatApiProvider);
-
-    final previous = conv.messages;
-    final userMsg = Message(
-      conversationId: convId,
-      role: MessageRole.user,
-      content: content,
-    );
-    final placeholder = Message(
-      conversationId: convId,
-      role: MessageRole.assistant,
-      content: '',
-      status: 'generating',
-    );
-    state = AsyncData(conv.copyWith(messages: [...previous, userMsg, placeholder]));
-    ref.read(isBriefingStreamingProvider.notifier).state = true;
-
-    try {
-      await chatApi.sendMessage(convId, content);
-    } catch (e) {
-      state = AsyncData(conv.copyWith(messages: previous));
-      ref.read(isBriefingStreamingProvider.notifier).state = false;
-      rethrow;
-    }
-
-    // SSE stream (best-effort)
-    bool streamedContent = false;
-    try {
-      await for (final event in chatApi.streamGeneration(convId)) {
-        if (event is! ChatTextChunk) continue;
-        streamedContent = true;
-        final current = state.value;
-        if (current == null) break;
-        final msgs = current.messages;
-        if (msgs.isEmpty) continue;
-        final updated =
-            msgs.last.copyWith(content: msgs.last.content + event.text);
-        state = AsyncData(current.copyWith(
-            messages: [...msgs.sublist(0, msgs.length - 1), updated]));
-      }
-    } catch (_) {
-      // Fall through to polling.
-    }
-
-    // Poll until complete (max 20 attempts, 2s apart)
-    try {
-      for (var attempt = 0; attempt < 20; attempt++) {
-        if (attempt > 0) await Future.delayed(const Duration(seconds: 2));
-        final fresh = await ref.read(briefingApiProvider).getMessages(convId);
-        final done = fresh.any(
-          (m) => m.role == MessageRole.assistant && m.status != 'generating',
-        );
-        final hasContent = fresh.any(
-          (m) => m.role == MessageRole.assistant && m.content.isNotEmpty,
-        );
-        final current = state.value;
-        if (current != null && (!streamedContent || done || hasContent)) {
-          state = AsyncData(current.copyWith(messages: fresh));
-        }
-        if (done) break;
-      }
-    } catch (_) {
-      // Clear the generating placeholder so UI doesn't spin forever.
-      final current = state.value;
-      if (current != null) {
-        final msgs = current.messages;
-        if (msgs.isNotEmpty && msgs.last.status == 'generating') {
-          state = AsyncData(current.copyWith(messages: [
-            ...msgs.sublist(0, msgs.length - 1),
-            msgs.last.copyWith(status: 'complete'),
-          ]));
-        }
-      }
-    } finally {
-      ref.read(isBriefingStreamingProvider.notifier).state = false;
-    }
-  }
 }

lib/providers/chat_provider.dart

@@ -1,3 +1,5 @@
+import 'dart:async';
+
 import 'package:flutter_riverpod/flutter_riverpod.dart';
 
 import '../data/models/conversation.dart';
@@ -93,10 +95,141 @@ class MessagesNotifier extends AsyncNotifier<List<Message>> {
   }
 
   /// Re-fetch messages without clearing the current list (no flicker).
+  ///
+  /// Also unfreezes the UI if streaming state got stuck true — this happens
+  /// when an SSE connection dies silently (mobile network handoff, app
+  /// backgrounded mid-stream, reverse proxy dropping idle sockets) and the
+  /// send loop never observes a close. If the server-side message is already
+  /// done, we clear `isStreamingProvider` so the input unlocks.
   Future<void> refresh() async {
     final (_, messages) =
         await ref.read(chatRepositoryProvider).getMessages(_convId);
     state = AsyncData(messages);
+    Message? lastAssistant;
+    for (var i = messages.length - 1; i >= 0; i--) {
+      if (messages[i].role == MessageRole.assistant) {
+        lastAssistant = messages[i];
+        break;
+      }
+    }
+    if (lastAssistant != null && lastAssistant.status != 'generating') {
+      ref.read(isStreamingProvider(_convId).notifier).state = false;
+      ref.read(streamingStatusProvider(_convId).notifier).state = '';
+    }
+  }
+
+  /// Attach to an already-running generation for this conversation.
+  ///
+  /// Used when the chat screen lands on a conversation that was started by
+  /// something other than a direct user message — e.g. the /news discuss
+  /// button, which creates a conversation on the backend and auto-kicks a
+  /// generation before navigating. Without this the stream runs to
+  /// completion invisibly and the screen only shows the final persisted
+  /// message after a manual refresh.
+  ///
+  /// Safe to call unconditionally on screen init: no-ops when there is no
+  /// generating assistant message. Mirrors the web chat store's
+  /// reconnectIfGenerating() helper.
+  Future<void> attachToGeneration() async {
+    final convId = _convId;
+    final repo = ref.read(chatRepositoryProvider);
+
+    // Make sure we're looking at fresh server state before deciding whether
+    // to attach. The provider's build() fetches once; if the conversation
+    // was seeded via a POST that happened between build() and this call the
+    // generating placeholder won't be in our in-memory list yet.
+    try {
+      final (_, fresh) = await repo.getMessages(convId);
+      state = AsyncData(fresh);
+    } catch (_) {
+      // If we can't load messages we can't attach either — bail cleanly.
+      return;
+    }
+
+    if (ref.read(isStreamingProvider(convId))) return;
+    final msgs = state.value ?? const <Message>[];
+    final hasGeneratingAssistant = msgs.any(
+      (m) => m.role == MessageRole.assistant && m.status == 'generating',
+    );
+    if (!hasGeneratingAssistant) return;
+
+    ref.read(isStreamingProvider(convId).notifier).state = true;
+
+    const stallTimeout = Duration(seconds: 45);
+    bool streamedContent = false;
+    final iter = StreamIterator(repo.streamGeneration(convId));
+    try {
+      while (await iter.moveNext().timeout(stallTimeout)) {
+        final event = iter.current;
+        if (event is ChatTextChunk) {
+          streamedContent = true;
+          ref.read(streamingStatusProvider(convId).notifier).state = '';
+          final cur = state.requireValue;
+          if (cur.isEmpty) continue;
+          // Route text chunks into the generating assistant message. The
+          // last message is usually the placeholder, but tool-call fan-in
+          // means we can't rely on that universally.
+          final idx = _findGeneratingAssistantIndex(cur);
+          if (idx < 0) continue;
+          final updated = cur[idx].copyWith(content: cur[idx].content + event.text);
+          state = AsyncData([
+            ...cur.sublist(0, idx),
+            updated,
+            ...cur.sublist(idx + 1),
+          ]);
+        } else if (event is ChatStatusUpdate) {
+          ref.read(streamingStatusProvider(convId).notifier).state = event.status;
+        } else if (event is ChatToolCall) {
+          final cur = state.requireValue;
+          if (cur.isEmpty) continue;
+          final idx = _findGeneratingAssistantIndex(cur);
+          if (idx < 0) continue;
+          final nextCalls = [...?cur[idx].toolCalls, event.toolCall];
+          final updated = cur[idx].copyWith(toolCalls: nextCalls);
+          state = AsyncData([
+            ...cur.sublist(0, idx),
+            updated,
+            ...cur.sublist(idx + 1),
+          ]);
+        }
+      }
+    } on TimeoutException {
+      // Stall — fall through to polling.
+    } catch (_) {
+      // Stream failed — fall through to polling.
+    } finally {
+      await iter.cancel();
+    }
+
+    try {
+      for (var attempt = 0; attempt < 20; attempt++) {
+        if (attempt > 0) await Future.delayed(const Duration(seconds: 2));
+        final (_, fresh) = await repo.getMessages(convId);
+        final done = fresh.any(
+          (m) => m.role == MessageRole.assistant && m.status != 'generating',
+        );
+        final polledHasContent = fresh.any(
+          (m) => m.role == MessageRole.assistant && m.content.isNotEmpty,
+        );
+        if (!streamedContent || done || polledHasContent) {
+          state = AsyncData(fresh);
+        }
+        if (done) break;
+      }
+    } catch (_) {
+      // Give up silently — user can pull-to-refresh.
+    } finally {
+      ref.read(isStreamingProvider(convId).notifier).state = false;
+      ref.read(streamingStatusProvider(convId).notifier).state = '';
+    }
+  }
+
+  int _findGeneratingAssistantIndex(List<Message> msgs) {
+    for (var i = msgs.length - 1; i >= 0; i--) {
+      final m = msgs[i];
+      if (m.role == MessageRole.assistant && m.status == 'generating') return i;
+    }
+    return -1;
   }
 
   Future<void> sendMessage(String content) async {
@@ -129,9 +262,19 @@ class MessagesNotifier extends AsyncNotifier<List<Message>> {
     }
 
     // ── Step 2: Stream the response (best effort — silent on failure). ──
+    //
+    // We use a StreamIterator with a per-event timeout as a stall watchdog.
+    // Mobile networks occasionally drop SSE sockets silently: the TCP
+    // connection is half-closed, Dio never sees the close, and `await for`
+    // hangs forever with `isStreaming=true`, freezing the input. If no
+    // event arrives within the watchdog window we bail out and let the
+    // polling pass below reconcile state from the server.
+    const stallTimeout = Duration(seconds: 45);
     bool streamedContent = false;
+    final iter = StreamIterator(repo.streamGeneration(convId));
     try {
-      await for (final event in repo.streamGeneration(convId)) {
+      while (await iter.moveNext().timeout(stallTimeout)) {
+        final event = iter.current;
         if (event is ChatTextChunk) {
           streamedContent = true;
           ref.read(streamingStatusProvider(convId).notifier).state = '';
@@ -143,10 +286,27 @@ class MessagesNotifier extends AsyncNotifier<List<Message>> {
         } else if (event is ChatStatusUpdate) {
           ref.read(streamingStatusProvider(convId).notifier).state =
               event.status;
+        } else if (event is ChatToolCall) {
+          // Append the tool call to the in-flight assistant message so the
+          // chip appears live. The reload pass at the end of this function
+          // will overwrite with the persisted version, which carries the
+          // same shape — no de-dup needed.
+          final msgs = state.requireValue;
+          if (msgs.isEmpty) continue;
+          final last = msgs.last;
+          if (last.role != MessageRole.assistant) continue;
+          final nextCalls = [...?last.toolCalls, event.toolCall];
+          final updated = last.copyWith(toolCalls: nextCalls);
+          state = AsyncData([...msgs.sublist(0, msgs.length - 1), updated]);
         }
       }
+    } on TimeoutException {
+      // Stall watchdog — no SSE event for stallTimeout. Fall through to
+      // polling so the UI eventually unfreezes even if the socket is dead.
     } catch (_) {
       // SSE failed — fall through to the polling reload below.
+    } finally {
+      await iter.cancel();
     }
 
     // ── Step 3: Poll the API until we have a completed assistant response.

lib/providers/knowledge_provider.dart

@@ -246,6 +246,9 @@ class KnowledgeNotifier extends Notifier<KnowledgeState> {
         isLoadingIds: false,
         hasMore: combined.length < total,
       );
+      // Hydrate the newly fetched IDs immediately — the user is
+      // already at the scroll bottom so _onScroll won't re-fire.
+      await hydrateNext();
     } catch (_) {
       state = state.copyWith(isLoadingIds: false);
     }

lib/providers/voice_provider.dart

@@ -112,6 +112,9 @@ class VoiceNotifier extends Notifier<VoiceState> {
   // to reduce STT mishearings of domain-specific words.
   String _lastAssistantContent = '';
 
+  // Empty transcript counter — show feedback after consecutive blanks
+  int _emptyTranscriptCount = 0;
+
   // TTS playback queue
   final _ttsQueue = Queue<Uint8List>();
   bool _ttsPlaying = false;
@@ -120,7 +123,6 @@ class VoiceNotifier extends Notifier<VoiceState> {
 
   @override
   VoiceState build() {
-    _recorder = AudioRecorder();
     _player = AudioPlayer();
     ref.onDispose(() {
       _amplitudeSubscription?.cancel();
@@ -146,32 +148,38 @@ class VoiceNotifier extends Notifier<VoiceState> {
       return;
     }
 
-    // Check server availability
+    // Check server availability — STT is required, TTS is optional.
     try {
       final status = await ref.read(voiceRepositoryProvider).checkStatus();
-      if (!status.fullyAvailable) {
+      if (!status.enabled || !status.stt) {
-        onError('Voice not available on this server');
+        onError('Speech-to-text not available on this server');
         return;
       }
+      // Downgrade to STT-only when TTS is unavailable
+      if (!status.tts) enableTts = false;
     } catch (_) {
-      onError('Voice not available on this server');
+      onError('Could not reach voice service');
       return;
     }
 
     // Check microphone permission
-    final permStatus = await Permission.microphone.request();
+    var permStatus = await Permission.microphone.request();
-    if (permStatus == PermissionStatus.denied ||
+    if (permStatus == PermissionStatus.permanentlyDenied) {
-        permStatus == PermissionStatus.permanentlyDenied) {
+      onError('Microphone blocked — opening settings');
+      final opened = await openAppSettings();
+      if (!opened) return;
+      // Re-check after user returns from settings
+      permStatus = await Permission.microphone.status;
+    }
+    if (!permStatus.isGranted) {
       onError('Microphone permission required');
-      if (permStatus == PermissionStatus.permanentlyDenied) {
-        await openAppSettings();
-      }
       return;
     }
 
     _onTranscript = onTranscript;
     _onError = onError;
     _enableTts = enableTts;
+    _emptyTranscriptCount = 0;
     _tempDir = await getTemporaryDirectory();
 
     state = state.copyWith(voiceModeActive: true, available: true);
@@ -225,12 +233,22 @@ class VoiceNotifier extends Notifier<VoiceState> {
     state = state.copyWith(mode: VoiceMode.recording);
 
     final dir = _tempDir ?? await getTemporaryDirectory();
-    // AAC/M4A is reliably supported on Android (unlike WebM/Opus which can
-    // produce OGG bytes in a .webm file, confusing server-side decoders).
     final path =
         '${dir.path}/voice_rec_${DateTime.now().millisecondsSinceEpoch}.m4a';
 
     try {
+      // Recreate the recorder each session — the record package can leave
+      // the native AudioRecord in a bad state after stop/error cycles,
+      // and a stale instance is the most common cause of "could not start".
+      _recorder?.dispose();
+      _recorder = AudioRecorder();
+
+      if (!await _recorder!.hasPermission()) {
+        _onError?.call('Microphone permission was revoked');
+        exitVoiceMode();
+        return;
+      }
+
       await _recorder!.start(
         const RecordConfig(encoder: AudioEncoder.aacLc, sampleRate: 16000),
         path: path,
@@ -241,7 +259,7 @@ class VoiceNotifier extends Notifier<VoiceState> {
           .onAmplitudeChanged(const Duration(milliseconds: 200))
           .listen(_onAmplitude);
     } catch (e) {
-      _onError?.call('Microphone error: could not start recording');
+      _onError?.call('Microphone error: $e');
       exitVoiceMode();
     }
   }
@@ -291,10 +309,16 @@ class VoiceNotifier extends Notifier<VoiceState> {
       if (!state.voiceModeActive) return;
 
       if (transcript.isEmpty) {
-        // Empty transcript — restart silently
+        _emptyTranscriptCount++;
+        if (_emptyTranscriptCount >= 3) {
+          _onError?.call('No speech detected — tap the mic to try again');
+          exitVoiceMode();
+          return;
+        }
         await _startListening();
         return;
       }
+      _emptyTranscriptCount = 0;
 
       // Reset TTS state for this new turn
       _sentenceBuffer = '';

lib/screens/briefing/briefing_screen.dart

@@ -41,7 +41,14 @@ class _BriefingScreenState extends ConsumerState<BriefingScreen>
 
   @override
   void didChangeAppLifecycleState(AppLifecycleState state) {
+    final wasBackground = !_appInForeground;
     _appInForeground = state == AppLifecycleState.resumed;
+    // On resume, force a message refresh. This also unfreezes a stuck
+    // streaming state if the SSE socket died while the app was backgrounded
+    // — silentRefresh won't do that because it guards on isStreaming.
+    if (_appInForeground && wasBackground && mounted) {
+      ref.read(briefingProvider.notifier).refreshMessages();
+    }
   }
 
   void _pollSilently() {
@@ -51,6 +58,18 @@ class _BriefingScreenState extends ConsumerState<BriefingScreen>
     ref.read(briefingProvider.notifier).silentRefresh();
   }
 
+  Future<void> _pullToRefresh() async {
+    try {
+      await ref.read(briefingProvider.notifier).refreshMessages();
+    } catch (_) {
+      if (mounted) {
+        ScaffoldMessenger.of(context).showSnackBar(
+          const SnackBar(content: Text('Could not refresh.')),
+        );
+      }
+    }
+  }
+
   @override
   void dispose() {
     _pollTimer?.cancel();
@@ -250,9 +269,14 @@ class _BriefingScreenState extends ConsumerState<BriefingScreen>
           return Column(
             children: [
               Expanded(
-                child: CustomScrollView(
+                child: RefreshIndicator(
-                  controller: _scrollController,
+                  onRefresh: _pullToRefresh,
-                  slivers: [
+                  child: CustomScrollView(
+                    controller: _scrollController,
+                    // AlwaysScrollable so pull-to-refresh fires even when
+                    // the briefing is empty or shorter than the viewport.
+                    physics: const AlwaysScrollableScrollPhysics(),
+                    slivers: [
                     if (conv.messages.isEmpty)
                       SliverFillRemaining(
                         child: Center(
@@ -293,7 +317,8 @@ class _BriefingScreenState extends ConsumerState<BriefingScreen>
                           },
                         ),
                       ),
-                  ],
+                    ],
+                  ),
                 ),
               ),
 

lib/screens/chat/chat_screen.dart

@@ -20,11 +20,40 @@ class _ChatScreenState extends ConsumerState<ChatScreen>
     with WidgetsBindingObserver {
   final _controller = TextEditingController();
   final _scrollController = ScrollController();
+  bool _refreshing = false;
+
+  Future<void> _refreshMessages() async {
+    if (_refreshing) return;
+    setState(() => _refreshing = true);
+    try {
+      await ref
+          .read(messagesProvider(widget.conversationId).notifier)
+          .refresh();
+    } catch (_) {
+      if (mounted) {
+        ScaffoldMessenger.of(context).showSnackBar(
+          const SnackBar(content: Text('Could not refresh messages.')),
+        );
+      }
+    } finally {
+      if (mounted) setState(() => _refreshing = false);
+    }
+  }
 
   @override
   void initState() {
     super.initState();
     WidgetsBinding.instance.addObserver(this);
+    // If we land on a conversation whose last assistant message is already
+    // mid-stream (e.g. the /news discuss button creates a conv and
+    // auto-kicks generation), attach to the running stream so the user sees
+    // live tokens instead of a frozen placeholder.
+    WidgetsBinding.instance.addPostFrameCallback((_) {
+      if (!mounted) return;
+      ref
+          .read(messagesProvider(widget.conversationId).notifier)
+          .attachToGeneration();
+    });
   }
 
   @override
@@ -136,6 +165,19 @@ class _ChatScreenState extends ConsumerState<ChatScreen>
     return Scaffold(
       appBar: AppBar(
         title: Text(convTitle?.isNotEmpty == true ? convTitle! : 'Chat'),
+        actions: [
+          IconButton(
+            tooltip: 'Refresh',
+            onPressed: _refreshing ? null : _refreshMessages,
+            icon: _refreshing
+                ? const SizedBox(
+                    width: 18,
+                    height: 18,
+                    child: CircularProgressIndicator(strokeWidth: 2),
+                  )
+                : const Icon(Icons.refresh),
+          ),
+        ],
       ),
       body: Column(
         children: [
@@ -147,22 +189,32 @@ class _ChatScreenState extends ConsumerState<ChatScreen>
                 child: Text('Could not load messages.'),
               ),
               data: (messages) {
-                if (messages.isEmpty) {
+                return RefreshIndicator(
-                  return const Center(
+                  onRefresh: _refreshMessages,
-                      child: Text('Send a message to start.'));
+                  child: messages.isEmpty
-                }
+                      ? ListView(
-                return ListView.builder(
+                          // Needs to be scrollable for RefreshIndicator to
-                  controller: _scrollController,
+                          // fire on empty state — plain Center won't work.
-                  padding: const EdgeInsets.symmetric(
+                          physics: const AlwaysScrollableScrollPhysics(),
-                      horizontal: 8, vertical: 12),
+                          children: const [
-                  itemCount: messages.length,
+                            SizedBox(height: 240),
-                  itemBuilder: (context, i) => ChatMessageBubble(
+                            Center(child: Text('Send a message to start.')),
-                    message: messages[i],
+                          ],
-                    streamingStatus: (i == messages.length - 1 &&
+                        )
-                            messages[i].status == 'generating')
+                      : ListView.builder(
-                        ? streamingStatus
+                          controller: _scrollController,
-                        : '',
+                          physics: const AlwaysScrollableScrollPhysics(),
-                  ),
+                          padding: const EdgeInsets.symmetric(
+                              horizontal: 8, vertical: 12),
+                          itemCount: messages.length,
+                          itemBuilder: (context, i) => ChatMessageBubble(
+                            message: messages[i],
+                            streamingStatus: (i == messages.length - 1 &&
+                                    messages[i].status == 'generating')
+                                ? streamingStatus
+                                : '',
+                          ),
+                        ),
                 );
               },
             ),

lib/widgets/chat_message_bubble.dart

@@ -4,6 +4,7 @@ import 'package:flutter/material.dart';
 import 'package:flutter_markdown_plus/flutter_markdown_plus.dart';
 
 import '../data/models/message.dart';
+import 'tool_call_chip.dart';
 
 class ChatMessageBubble extends StatelessWidget {
   final Message message;
@@ -19,6 +20,12 @@ class ChatMessageBubble extends StatelessWidget {
     final isUser = message.role == MessageRole.user;
     final scheme = Theme.of(context).colorScheme;
     final isGenerating = message.status == 'generating';
+    final toolCalls = message.toolCalls ?? const [];
+
+    // An assistant bubble with no text, no tool calls, and still generating
+    // falls back to the spinner+status "waiting for the first token" view.
+    final showSpinnerOnly =
+        isGenerating && message.content.isEmpty && toolCalls.isEmpty;
 
     return Align(
       alignment: isUser ? Alignment.centerRight : Alignment.centerLeft,
@@ -29,7 +36,6 @@ class ChatMessageBubble extends StatelessWidget {
         margin: const EdgeInsets.symmetric(vertical: 4, horizontal: 4),
         decoration: isUser
             ? BoxDecoration(
-                // Ghost style: transparent bg, thin border
                 color: Colors.transparent,
                 border: Border.all(
                   color: scheme.primary.withValues(alpha: 0.35),
@@ -43,7 +49,6 @@ class ChatMessageBubble extends StatelessWidget {
                 ),
               )
             : BoxDecoration(
-                // Assistant: elevated surface + left accent border
                 color: scheme.surfaceContainerHighest,
                 border: Border(
                   left: BorderSide(color: scheme.primary, width: 2),
@@ -57,46 +62,102 @@ class ChatMessageBubble extends StatelessWidget {
               ),
         child: Padding(
           padding: const EdgeInsets.symmetric(horizontal: 12, vertical: 8),
-          child: isGenerating && message.content.isEmpty
+          child: showSpinnerOnly
-              ? Row(
+              ? _buildSpinner(scheme)
+              : Column(
+                  crossAxisAlignment: CrossAxisAlignment.start,
                   mainAxisSize: MainAxisSize.min,
                   children: [
-                    SizedBox(
+                    // Accumulated tool-call chips: visible both during
-                      width: 16,
+                    // streaming (fed live over SSE) and after reload (from
-                      height: 16,
+                    // the persisted message.tool_calls array).
-                      child: CircularProgressIndicator(
+                    if (toolCalls.isNotEmpty) ...[
-                        strokeWidth: 2,
+                      Wrap(
-                        color: scheme.onSurfaceVariant,
+                        spacing: 6,
+                        runSpacing: 6,
+                        children: [
+                          for (final tc in toolCalls) ToolCallChip(toolCall: tc),
+                        ],
                       ),
-                    ),
+                      const SizedBox(height: 6),
-                    if (streamingStatus.isNotEmpty) ...[
+                    ],
-                      const SizedBox(width: 8),
+                    // Rolling status line — shows backend stage text
-                      Flexible(
+                    // ("Creating note", "Searching calendar") while the
-                        child: Text(
+                    // model is between tool rounds or just before the
-                          streamingStatus,
+                    // first token. Stays above any already-streamed text
-                          style: TextStyle(
+                    // so the user can see what's happening mid-turn.
-                            fontSize: 12,
+                    if (isGenerating && streamingStatus.isNotEmpty) ...[
-                            color: scheme.onSurfaceVariant,
+                      Row(
-                            fontStyle: FontStyle.italic,
+                        mainAxisSize: MainAxisSize.min,
+                        children: [
+                          SizedBox(
+                            width: 12,
+                            height: 12,
+                            child: CircularProgressIndicator(
+                              strokeWidth: 1.5,
+                              color: scheme.onSurfaceVariant,
+                            ),
+                          ),
+                          const SizedBox(width: 6),
+                          Flexible(
+                            child: Text(
+                              streamingStatus,
+                              style: TextStyle(
+                                fontSize: 11,
+                                color: scheme.onSurfaceVariant,
+                                fontStyle: FontStyle.italic,
+                              ),
+                            ),
+                          ),
+                        ],
+                      ),
+                      const SizedBox(height: 6),
+                    ],
+                    if (message.content.isNotEmpty)
+                      MarkdownBody(
+                        data: message.content,
+                        styleSheet: MarkdownStyleSheet(
+                          p: TextStyle(
+                            color: isUser
+                                ? scheme.onSurface.withValues(alpha: 0.75)
+                                : scheme.onSurface,
+                            fontSize: 14,
                           ),
                         ),
                       ),
-                    ],
                   ],
-                )
-              : MarkdownBody(
-                  data: message.content.isEmpty ? '…' : message.content,
-                  styleSheet: MarkdownStyleSheet(
-                    p: TextStyle(
-                      color: isUser
-                          ? scheme.onSurface.withValues(alpha: 0.75)
-                          : scheme.onSurface,
-                      fontSize: 14,
-                    ),
-                  ),
                 ),
         ),
       ),
     );
   }
+
+  Widget _buildSpinner(ColorScheme scheme) {
+    return Row(
+      mainAxisSize: MainAxisSize.min,
+      children: [
+        SizedBox(
+          width: 16,
+          height: 16,
+          child: CircularProgressIndicator(
+            strokeWidth: 2,
+            color: scheme.onSurfaceVariant,
+          ),
+        ),
+        if (streamingStatus.isNotEmpty) ...[
+          const SizedBox(width: 8),
+          Flexible(
+            child: Text(
+              streamingStatus,
+              style: TextStyle(
+                fontSize: 12,
+                color: scheme.onSurfaceVariant,
+                fontStyle: FontStyle.italic,
+              ),
+            ),
+          ),
+        ],
+      ],
+    );
+  }
 }

lib/widgets/news_card.dart

@@ -113,16 +113,20 @@ class NewsCard extends StatelessWidget {
               ],
             ),
             const SizedBox(height: 4),
-            // Title — tappable if URL present
+            // Title — tappable if URL present. Text stays in onSurface for
+            // contrast; the primary-colored underline carries the "this is a
+            // link" signal without tanking readability.
             GestureDetector(
               onTap: item.url.isNotEmpty ? _openUrl : null,
               child: Text(
                 item.title,
-                style: textTheme.bodyMedium?.copyWith(
+                style: textTheme.titleSmall?.copyWith(
                   fontWeight: FontWeight.w600,
-                  color: item.url.isNotEmpty ? scheme.primary : scheme.onSurface,
+                  color: scheme.onSurface,
+                  height: 1.3,
                   decoration: item.url.isNotEmpty ? TextDecoration.underline : null,
-                  decorationColor: scheme.primary,
+                  decorationColor: scheme.primary.withValues(alpha: 0.7),
+                  decorationThickness: 1.5,
                 ),
               ),
             ),

lib/widgets/tool_call_chip.dart

@@ -0,0 +1,181 @@
+import 'package:flutter/material.dart';
+import 'package:go_router/go_router.dart';
+
+import '../core/constants.dart';
+
+/// Human-readable labels for each backend tool. Kept in sync with
+/// `_TOOL_LABELS` in `fabledassistant/services/generation_task.py` so the
+/// mobile chips use the same wording as the web ToolCallCard status pills.
+const Map<String, String> _toolLabels = {
+  'create_note': 'Created note',
+  'update_note': 'Updated note',
+  'delete_note': 'Deleted note',
+  'create_task': 'Created task',
+  'update_task': 'Updated task',
+  'delete_task': 'Deleted task',
+  'read_note': 'Read note',
+  'list_notes': 'Listed notes',
+  'list_tasks': 'Searched tasks',
+  'search_notes': 'Searched notes',
+  'create_event': 'Created event',
+  'list_events': 'Searched calendar',
+  'search_events': 'Searched calendar',
+  'update_event': 'Updated event',
+  'delete_event': 'Removed event',
+  'list_calendars': 'Listed calendars',
+  'search_web': 'Searched the web',
+  'research_topic': 'Researched topic',
+  'search_images': 'Searched images',
+  'create_project': 'Created project',
+  'update_project': 'Updated project',
+  'list_projects': 'Listed projects',
+  'get_project': 'Read project',
+  'search_projects': 'Searched projects',
+  'create_milestone': 'Created milestone',
+  'update_milestone': 'Updated milestone',
+  'list_milestones': 'Listed milestones',
+  'set_rag_scope': 'Changed knowledge scope',
+  'calculate': 'Calculated',
+  'read_article': 'Read article',
+  'get_profile': 'Read profile',
+  'update_profile': 'Updated profile',
+  'update_person': 'Updated person',
+  'update_place': 'Updated place',
+  'add_task_log': 'Logged task progress',
+};
+
+IconData _iconFor(String fn) {
+  if (fn.contains('note')) return Icons.sticky_note_2_outlined;
+  if (fn.contains('task')) return Icons.check_circle_outline;
+  if (fn.contains('event') || fn.contains('calendar')) {
+    return Icons.event_outlined;
+  }
+  if (fn.contains('project')) return Icons.folder_outlined;
+  if (fn.contains('milestone')) return Icons.flag_outlined;
+  if (fn.contains('web') || fn.contains('research') || fn.contains('article')) {
+    return Icons.public;
+  }
+  if (fn.contains('image')) return Icons.image_outlined;
+  if (fn.contains('person') || fn.contains('profile')) {
+    return Icons.person_outline;
+  }
+  if (fn.contains('place')) return Icons.place_outlined;
+  if (fn.contains('rag') || fn.contains('scope')) return Icons.tune;
+  if (fn.contains('calculate')) return Icons.calculate_outlined;
+  return Icons.auto_awesome;
+}
+
+/// Pull the destination route for this tool call from its `result` payload,
+/// if the tool produced something we can navigate to. Returns `null` for
+/// read-only / no-target tools so the chip stays visible but non-tappable.
+///
+/// Backend tool results use the shape:
+///   `{success, type: "note"|"task"|"event"|"project"|..., data: {id, ...}}`
+/// which is defined alongside each tool handler (see
+/// `services/tools/notes.py`, `calendar.py`, etc.).
+String? _routeForToolCall(Map<String, dynamic> tc) {
+  final result = tc['result'];
+  if (result is! Map<String, dynamic>) return null;
+  if (result['success'] != true) return null;
+  final type = result['type'] as String?;
+  final data = result['data'];
+  if (type == null || data is! Map<String, dynamic>) return null;
+  final id = data['id'];
+  if (id is! int) return null;
+  switch (type) {
+    case 'note':
+      return Routes.noteDetail.replaceFirst(':id', '$id');
+    case 'task':
+      return Routes.taskEdit.replaceFirst(':id', '$id');
+    case 'event':
+    case 'event_updated':
+      // No single-event route on mobile — fall back to the calendar.
+      return Routes.calendar;
+    case 'project':
+      return Routes.projectTasks.replaceFirst(':id', '$id');
+    default:
+      return null;
+  }
+}
+
+/// Small status pill rendered inside an assistant message bubble for each
+/// tool invocation. Mirrors the web app's ToolCallCard header at a glance —
+/// icon + label + success/error tint — and, when the tool produced a
+/// navigable entity (note, task, event, project), tapping the chip opens it.
+class ToolCallChip extends StatelessWidget {
+  final Map<String, dynamic> toolCall;
+  const ToolCallChip({super.key, required this.toolCall});
+
+  @override
+  Widget build(BuildContext context) {
+    final scheme = Theme.of(context).colorScheme;
+    final function = (toolCall['function'] as String?) ?? 'tool';
+    final status = (toolCall['status'] as String?) ?? 'success';
+    final isError = status == 'error';
+    final label = _toolLabels[function] ?? function;
+
+    final route = isError ? null : _routeForToolCall(toolCall);
+
+    final bg = isError
+        ? scheme.errorContainer.withValues(alpha: 0.55)
+        : scheme.primary.withValues(alpha: 0.12);
+    final fg = isError ? scheme.onErrorContainer : scheme.primary;
+
+    // Pull the entity title from the result payload so the chip can show
+    // "Created note: Grocery List" instead of a generic label. Falls back
+    // to the generic label when the tool didn't return a titled entity.
+    String? entityTitle;
+    final result = toolCall['result'];
+    if (result is Map<String, dynamic>) {
+      final data = result['data'];
+      if (data is Map<String, dynamic>) {
+        final t = data['title'];
+        if (t is String && t.isNotEmpty) entityTitle = t;
+      }
+    }
+    final displayText =
+        entityTitle != null ? '$label: $entityTitle' : label;
+
+    final chip = Container(
+      padding: const EdgeInsets.symmetric(horizontal: 8, vertical: 4),
+      decoration: BoxDecoration(
+        color: bg,
+        borderRadius: BorderRadius.circular(10),
+        border: Border.all(color: fg.withValues(alpha: 0.35), width: 0.5),
+      ),
+      child: Row(
+        mainAxisSize: MainAxisSize.min,
+        children: [
+          Icon(_iconFor(function), size: 13, color: fg),
+          const SizedBox(width: 5),
+          Flexible(
+            child: Text(
+              displayText,
+              style: TextStyle(
+                fontSize: 11,
+                color: fg,
+                fontWeight: FontWeight.w500,
+              ),
+              overflow: TextOverflow.ellipsis,
+            ),
+          ),
+          if (route != null) ...[
+            const SizedBox(width: 4),
+            Icon(Icons.arrow_forward, size: 11, color: fg),
+          ],
+        ],
+      ),
+    );
+
+    if (route == null) return chip;
+    return Material(
+      color: Colors.transparent,
+      borderRadius: BorderRadius.circular(10),
+      child: InkWell(
+        borderRadius: BorderRadius.circular(10),
+        onTap: () => context.push(route),
+        child: chip,
+      ),
+    );
+  }
+}

scripts/publish_apk_release.sh

@@ -0,0 +1,72 @@
+#!/usr/bin/env bash
+#
+# Publish a signed release APK to Forgejo.
+#
+# Finds the release matching $TAG (creating it if the CI job got here
+# before the UI did), then attaches the APK as a release asset.
+#
+# Required env:
+#   RELEASE_TOKEN  — Forgejo PAT with write:repository scope
+#   TAG            — release tag (e.g. v26.04.11)
+#   APK            — path to the built APK
+#
+# Optional env:
+#   FORGEJO_API    — defaults to the FabledApp repo API root
+#
+# Exits non-zero if the release can't be created or the asset upload
+# fails. Designed to be testable locally:
+#   RELEASE_TOKEN=... TAG=v0.0.1 APK=/tmp/test.apk bash -x scripts/publish_apk_release.sh
+set -euo pipefail
+
+: "${RELEASE_TOKEN:?RELEASE_TOKEN not set}"
+: "${TAG:?TAG not set}"
+: "${APK:?APK not set}"
+
+if [ ! -f "$APK" ]; then
+  echo "APK not found at $APK" >&2
+  exit 1
+fi
+
+API="${FORGEJO_API:-https://git.fabledsword.com/api/v1/repos/bvandeusen/FabledApp}"
+
+# jq isn't in the cirruslabs Flutter image, so we parse JSON with grep.
+# Fragile but bounded: we only care about the first "id": <n> field,
+# which is always the release id in Forgejo's responses for these
+# endpoints. If Forgejo ever adds a preceding id field, revisit.
+extract_id() {
+  echo "$1" | grep -oE '"id"[[:space:]]*:[[:space:]]*[0-9]+' | head -1 | grep -oE '[0-9]+'
+}
+
+# Look for an existing release (created via the UI or a prior run).
+# curl -f turns 4xx/5xx into non-zero so we can distinguish "not found"
+# (no release yet) from "auth broken" (real failure).
+existing=$(curl -fsS -H "Authorization: token $RELEASE_TOKEN" \
+  "$API/releases/tags/$TAG" 2>/dev/null || true)
+
+release_id=$(extract_id "$existing")
+
+if [ -z "$release_id" ]; then
+  echo "No existing release for $TAG — creating one..."
+  response=$(curl -fsS -X POST \
+    -H "Authorization: token $RELEASE_TOKEN" \
+    -H "Content-Type: application/json" \
+    -d "{\"tag_name\": \"$TAG\", \"name\": \"$TAG\", \"body\": \"\"}" \
+    "$API/releases")
+  release_id=$(extract_id "$response")
+  if [ -z "$release_id" ]; then
+    echo "Failed to create release. API response:" >&2
+    echo "$response" >&2
+    exit 1
+  fi
+  echo "Created release $TAG (id=$release_id)."
+else
+  echo "Found existing release $TAG (id=$release_id). Attaching APK..."
+fi
+
+curl -fsS -X POST \
+  -H "Authorization: token $RELEASE_TOKEN" \
+  -F "attachment=@$APK" \
+  "$API/releases/$release_id/assets" > /dev/null
+
+echo "Done — $TAG is live at:"
+echo "https://git.fabledsword.com/bvandeusen/FabledApp/releases/tag/$TAG"