feat(offline): tier 2 phase 1 — Drift cache + read-through for notes

First slice of the tier 2 offline mode work tracked in Fable #147.
Notes are the only domain wired so far; this PR establishes the
shape and proves the round-trip end-to-end before extending to tasks
/ projects / events / etc. in phase 2.

Local store
- Adds drift ^2.20.0 + sqlite3_flutter_libs ^0.5.24 + path ^1.9.0
  runtime deps and drift_dev / build_runner dev deps.
- New lib/data/local/database.dart: FabledDatabase with CachedNotes
  (mirroring the Note model 1:1; tags stored as JSON-encoded text) and
  SyncMetadata (per-domain last_synced_at). Database file lives at
  $appDocs/fabled_cache.sqlite; opened lazily in a background isolate.
- fabledDatabaseProvider on the existing api_client_provider; closes
  the DB when the ProviderScope disposes.

Repository pattern
- NotesRepository now takes (NotesApi, FabledDatabase). Reads attempt
  the network first; on success the response is written to the cache.
  On NetworkException reads fall back to the cache (rethrowing if it
  is empty so fresh-install offline still surfaces the network error).
- Writes (create/update/delete) hit the server then sync the cache;
  offline write queueing is phase 3 and explicitly not wired here.
- AuthStatus.offline stays owned by AuthNotifier.verify()'s heartbeat;
  this repo deliberately doesn't poke that state.

OfflineBanner
- Reads notesRepository.lastSyncedAt(); when present, swaps
  "Offline — showing cached data." for "Offline — last sync X min
  ago." A 30s timer refreshes the relative-time string while the
  banner is mounted.
- Falls back to the generic message if no cache exists yet (fresh
  install offline).

Verification
- flutter analyze: No issues found

Out of scope (later phases per the task body)
- Tasks / projects / milestones / events / conversation list / journal
  day caching (phase 2 — same wrapper pattern, repeated)
- Generic write queue with conflict resolution on updated_at (phase 3)
- Read-only UI indicators on screens that depend on cached data
  (phase 4)
- Full offline chat (out of scope; needs a local model)
- RAG / search over cached content (out of scope)

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

lib/data/local/database.dart

@@ -0,0 +1,152 @@
+import 'dart:convert';
+import 'dart:io';
+
+import 'package:drift/drift.dart';
+import 'package:drift/native.dart';
+import 'package:path/path.dart' as p;
+import 'package:path_provider/path_provider.dart';
+import 'package:sqlite3_flutter_libs/sqlite3_flutter_libs.dart';
+
+import '../models/note.dart';
+
+part 'database.g.dart';
+
+/// Local cache of server-side Notes for offline reads.
+///
+/// Mirrors the shape of [Note] one-to-one. Tags are stored as a JSON-encoded
+/// string because SQLite has no native list type and Drift's typed converters
+/// add ceremony we don't need for a simple read cache. `cachedAt` tracks when
+/// the row was last written from a successful API response.
+class CachedNotes extends Table {
+  IntColumn get id => integer()();
+  TextColumn get title => text()();
+  TextColumn get body => text()();
+  TextColumn get tagsJson => text().withDefault(const Constant('[]'))();
+  TextColumn get noteType => text().withDefault(const Constant('note'))();
+  IntColumn get projectId => integer().nullable()();
+  IntColumn get milestoneId => integer().nullable()();
+  DateTimeColumn get createdAt => dateTime()();
+  DateTimeColumn get updatedAt => dateTime()();
+  DateTimeColumn get cachedAt =>
+      dateTime().clientDefault(() => DateTime.now())();
+
+  @override
+  Set<Column> get primaryKey => {id};
+}
+
+/// Per-domain sync timestamp. Keyed by a short domain string ('notes',
+/// 'tasks', 'projects', 'events', etc.) so the OfflineBanner and any
+/// stale-while-revalidate logic can ask "when did we last fetch this".
+class SyncMetadata extends Table {
+  TextColumn get domain => text()();
+  DateTimeColumn get lastSyncedAt => dateTime()();
+
+  @override
+  Set<Column> get primaryKey => {domain};
+}
+
+const String kSyncDomainNotes = 'notes';
+
+@DriftDatabase(tables: [CachedNotes, SyncMetadata])
+class FabledDatabase extends _$FabledDatabase {
+  FabledDatabase() : super(_openConnection());
+  FabledDatabase.forTesting(super.executor);
+
+  @override
+  int get schemaVersion => 1;
+
+  // ── Notes ────────────────────────────────────────────────────────────────
+
+  Future<List<Note>> getAllNotes() async {
+    final rows = await (select(cachedNotes)
+          ..orderBy([(t) => OrderingTerm.desc(t.updatedAt)]))
+        .get();
+    return rows.map(_noteFromRow).toList();
+  }
+
+  Future<Note?> getNote(int id) async {
+    final row = await (select(cachedNotes)..where((t) => t.id.equals(id)))
+        .getSingleOrNull();
+    return row == null ? null : _noteFromRow(row);
+  }
+
+  /// Replace the entire notes cache with the latest server snapshot.
+  /// Used after a successful `getAll()` so the cache reflects deletions
+  /// (a row that's gone from the server should be gone locally too).
+  Future<void> replaceAllNotes(List<Note> notes) async {
+    await transaction(() async {
+      await delete(cachedNotes).go();
+      if (notes.isNotEmpty) {
+        await batch((b) {
+          b.insertAll(
+            cachedNotes,
+            notes.map(_companionFromNote).toList(),
+          );
+        });
+      }
+      await _setLastSyncIn(kSyncDomainNotes, DateTime.now());
+    });
+  }
+
+  /// Upsert a single note (after a successful create / update / getOne).
+  Future<void> upsertNote(Note note) async {
+    await into(cachedNotes).insertOnConflictUpdate(_companionFromNote(note));
+  }
+
+  Future<void> deleteNote(int id) async {
+    await (delete(cachedNotes)..where((t) => t.id.equals(id))).go();
+  }
+
+  // ── Sync metadata ────────────────────────────────────────────────────────
+
+  Future<DateTime?> getLastSync(String domain) async {
+    final row = await (select(syncMetadata)
+          ..where((t) => t.domain.equals(domain)))
+        .getSingleOrNull();
+    return row?.lastSyncedAt;
+  }
+
+  Future<void> _setLastSyncIn(String domain, DateTime timestamp) {
+    return into(syncMetadata).insertOnConflictUpdate(
+      SyncMetadataCompanion(
+        domain: Value(domain),
+        lastSyncedAt: Value(timestamp),
+      ),
+    );
+  }
+}
+
+CachedNotesCompanion _companionFromNote(Note note) => CachedNotesCompanion(
+      id: Value(note.id),
+      title: Value(note.title),
+      body: Value(note.body),
+      tagsJson: Value(jsonEncode(note.tags)),
+      noteType: Value(note.noteType),
+      projectId: Value(note.projectId),
+      milestoneId: Value(note.milestoneId),
+      createdAt: Value(note.createdAt),
+      updatedAt: Value(note.updatedAt),
+    );
+
+Note _noteFromRow(CachedNote row) => Note(
+      id: row.id,
+      title: row.title,
+      body: row.body,
+      tags: (jsonDecode(row.tagsJson) as List<dynamic>).cast<String>(),
+      noteType: row.noteType,
+      projectId: row.projectId,
+      milestoneId: row.milestoneId,
+      createdAt: row.createdAt,
+      updatedAt: row.updatedAt,
+    );
+
+LazyDatabase _openConnection() {
+  return LazyDatabase(() async {
+    if (Platform.isAndroid) {
+      await applyWorkaroundToOpenSqlite3OnOldAndroidVersions();
+    }
+    final dir = await getApplicationDocumentsDirectory();
+    final file = File(p.join(dir.path, 'fabled_cache.sqlite'));
+    return NativeDatabase.createInBackground(file);
+  });
+}

lib/data/repositories/notes_repository.dart

@@ -1,12 +1,50 @@
+import '../../core/exceptions.dart';
 import '../api/notes_api.dart';
+import '../local/database.dart';
 import '../models/note.dart';
 
+/// Notes repository with read-through caching for Tier 2 offline support.
+///
+/// Reads attempt the network first; on success the response is written to
+/// the local Drift cache. On `NetworkException` the read falls back to the
+/// cache (rethrowing if the cache is empty so the UI can show its
+/// fresh-install empty state). Writes (create / update / delete) hit the
+/// server then sync the cache; offline write queueing is Phase 3 work and
+/// not yet wired here — write methods will throw on `NetworkException` in
+/// the meantime.
+///
+/// `AuthStatus.offline` is owned by `AuthNotifier.verify()` (a periodic
+/// heartbeat). This repository deliberately does not poke that state — its
+/// only job is to serve what's cached when the network is unreachable.
 class NotesRepository {
   final NotesApi _api;
-  const NotesRepository(this._api);
+  final FabledDatabase _db;
 
-  Future<List<Note>> getAll() => _api.getAll();
-  Future<Note> getOne(int id) => _api.getOne(id);
+  const NotesRepository(this._api, this._db);
+
+  Future<List<Note>> getAll() async {
+    try {
+      final notes = await _api.getAll();
+      await _db.replaceAllNotes(notes);
+      return notes;
+    } on NetworkException {
+      final cached = await _db.getAllNotes();
+      if (cached.isEmpty) rethrow;
+      return cached;
+    }
+  }
+
+  Future<Note> getOne(int id) async {
+    try {
+      final note = await _api.getOne(id);
+      await _db.upsertNote(note);
+      return note;
+    } on NetworkException {
+      final cached = await _db.getNote(id);
+      if (cached == null) rethrow;
+      return cached;
+    }
+  }
 
   Future<Note> create(
     String title,
@@ -14,9 +52,17 @@ class NotesRepository {
     List<String> tags = const [],
     int? projectId,
     String noteType = 'note',
-  }) =>
-      _api.create(title, body,
-          tags: tags, projectId: projectId, noteType: noteType);
+  }) async {
+    final note = await _api.create(
+      title,
+      body,
+      tags: tags,
+      projectId: projectId,
+      noteType: noteType,
+    );
+    await _db.upsertNote(note);
+    return note;
+  }
 
   Future<Note> update(
     int id,
@@ -26,12 +72,27 @@ class NotesRepository {
     int? projectId,
     bool clearProject = false,
     String noteType = 'note',
-  }) =>
-      _api.update(id, title, body,
-          tags: tags,
-          projectId: projectId,
-          clearProject: clearProject,
-          noteType: noteType);
+  }) async {
+    final updated = await _api.update(
+      id,
+      title,
+      body,
+      tags: tags,
+      projectId: projectId,
+      clearProject: clearProject,
+      noteType: noteType,
+    );
+    await _db.upsertNote(updated);
+    return updated;
+  }
 
-  Future<void> delete(int id) => _api.delete(id);
+  Future<void> delete(int id) async {
+    await _api.delete(id);
+    await _db.deleteNote(id);
+  }
+
+  /// Last successful `getAll` sync timestamp. Surfaced by the OfflineBanner
+  /// when the network is unreachable so the user knows how stale the
+  /// cached notes list is.
+  Future<DateTime?> lastSyncedAt() => _db.getLastSync(kSyncDomainNotes);
 }

lib/providers/api_client_provider.dart

@@ -15,6 +15,7 @@ import '../data/api/projects_api.dart';
 import '../data/api/quick_capture_api.dart';
 import '../data/api/settings_api.dart';
 import '../data/api/tasks_api.dart';
+import '../data/local/database.dart';
 import '../data/repositories/auth_repository.dart';
 import '../data/repositories/chat_repository.dart';
 import '../data/repositories/knowledge_repository.dart';
@@ -60,12 +61,24 @@ final projectsApiProvider = Provider<ProjectsApi>((ref) {
   return ProjectsApi(ref.watch(dioProvider));
 });
 
+/// Local SQLite cache used by repositories for read-through caching and
+/// offline fallback. Backed by Drift; lives for the lifetime of the
+/// ProviderScope and is closed automatically when the scope disposes.
+final fabledDatabaseProvider = Provider<FabledDatabase>((ref) {
+  final db = FabledDatabase();
+  ref.onDispose(db.close);
+  return db;
+});
+
 final authRepositoryProvider = Provider<AuthRepository>((ref) {
   return AuthRepository(ref.watch(authApiProvider));
 });
 
 final notesRepositoryProvider = Provider<NotesRepository>((ref) {
-  return NotesRepository(ref.watch(notesApiProvider));
+  return NotesRepository(
+    ref.watch(notesApiProvider),
+    ref.watch(fabledDatabaseProvider),
+  );
 });
 
 final tasksRepositoryProvider = Provider<TasksRepository>((ref) {

lib/widgets/offline_banner.dart

@@ -1,12 +1,15 @@
+import 'dart:async';
+
 import 'package:flutter/material.dart';
 import 'package:lucide_icons/lucide_icons.dart';
 import 'package:flutter_riverpod/flutter_riverpod.dart';
 
+import '../providers/api_client_provider.dart';
 import '../providers/auth_provider.dart';
 
 /// Sticky banner shown when the backend is unreachable. Surfaces a retry
-/// action and reserves space for future "last sync X min ago" messaging once
-/// Tier 2 offline caching lands.
+/// action plus a "last sync X ago" hint when there is cached content to
+/// fall back on (Tier 2 offline mode).
 class OfflineBanner extends ConsumerStatefulWidget {
   const OfflineBanner({super.key});
 
@@ -16,6 +19,38 @@ class OfflineBanner extends ConsumerStatefulWidget {
 
 class _OfflineBannerState extends ConsumerState<OfflineBanner> {
   bool _retrying = false;
+  DateTime? _lastSync;
+  Timer? _refreshTimer;
+
+  @override
+  void initState() {
+    super.initState();
+    _loadLastSync();
+    // Refresh the relative-time string every 30s so "5 min ago" rolls
+    // forward without the user having to interact with the banner.
+    _refreshTimer = Timer.periodic(
+      const Duration(seconds: 30),
+      (_) => _loadLastSync(),
+    );
+  }
+
+  @override
+  void dispose() {
+    _refreshTimer?.cancel();
+    super.dispose();
+  }
+
+  Future<void> _loadLastSync() async {
+    if (!mounted) return;
+    try {
+      final ts =
+          await ref.read(notesRepositoryProvider).lastSyncedAt();
+      if (!mounted) return;
+      setState(() => _lastSync = ts);
+    } catch (_) {
+      // Non-critical — banner just won't show the sync hint.
+    }
+  }
 
   Future<void> _retry() async {
     if (_retrying) return;
@@ -27,12 +62,30 @@ class _OfflineBannerState extends ConsumerState<OfflineBanner> {
     }
   }
 
+  String? _relativeAgo(DateTime ts) {
+    final diff = DateTime.now().difference(ts);
+    if (diff.isNegative) return null;
+    if (diff.inMinutes < 1) return 'just now';
+    if (diff.inMinutes < 60) return '${diff.inMinutes} min ago';
+    if (diff.inHours < 24) {
+      final h = diff.inHours;
+      return '$h ${h == 1 ? 'hour' : 'hours'} ago';
+    }
+    final d = diff.inDays;
+    return '$d ${d == 1 ? 'day' : 'days'} ago';
+  }
+
   @override
   Widget build(BuildContext context) {
     final status = ref.watch(authProvider);
     if (status != AuthStatus.offline) return const SizedBox.shrink();
 
     final scheme = Theme.of(context).colorScheme;
+    final ago = _lastSync == null ? null : _relativeAgo(_lastSync!);
+    final message = ago == null
+        ? 'Offline — showing cached data.'
+        : 'Offline — last sync $ago.';
+
     return Material(
       color: scheme.errorContainer,
       child: SafeArea(
@@ -46,7 +99,7 @@ class _OfflineBannerState extends ConsumerState<OfflineBanner> {
               const SizedBox(width: 8),
               Expanded(
                 child: Text(
-                  'Offline — showing cached data.',
+                  message,
                   style: TextStyle(color: scheme.onErrorContainer),
                 ),
               ),