From 03dc9108a35c72483331b1ad91afc4c8810135ad Mon Sep 17 00:00:00 2001 From: bvandeusen Date: Mon, 6 Apr 2026 17:34:20 -0400 Subject: [PATCH] docs: update README to reflect current app features and architecture Replaces outdated Library/stub descriptions with accurate coverage of Knowledge, Calendar, News, Voice I/O, chat tool-status notifications, auto-refresh, and the current file tree. Co-Authored-By: Claude Sonnet 4.6 --- README.md | 66 ++++++++++++++++++++++++++++++++++++------------------- 1 file changed, 44 insertions(+), 22 deletions(-) diff --git a/README.md b/README.md index ba254cf..9c65a23 100644 --- a/README.md +++ b/README.md @@ -6,11 +6,16 @@ Native Android client for FabledAssistant, a self-hosted AI second-brain and pro - **Daily Briefing** — the primary screen; opens on launch. Shows your AI-compiled morning digest (tasks, calendar, weather, RSS) with a full conversation you can reply to inline. Refresh manually or browse past briefings from the overflow menu. - **Quick Capture** — always-visible input bar above all tabs. Type a note or task and submit; multiple captures queue sequentially so the input is never blocked. Falls back to offline persistence when the server is unreachable. -- **Library** — unified browsable list of notes, tasks, and projects with filter pills (All · Notes · Tasks · Projects). Tasks have a secondary status sub-filter and a tappable status icon to cycle todo → in progress → done without opening the editor. Inline search filters results live. -- **Chat** — streaming AI conversations with real-time SSE display. Tap + to start a new conversation or open an existing one. +- **Knowledge** — unified browsable feed of notes, people, places, lists, and tasks across six filter tabs. Tag filters, inline search (debounced), and two-tier pagination (ID list → batch hydration). Tasks load from `/api/tasks` directly and are fully integrated with the knowledge feed. +- **Chat** — streaming AI conversations with real-time SSE display, including live tool-use status notifications (e.g. "Calling create_note…"). Tap + to start a new conversation or open an existing one. +- **Calendar** — month strip + daily agenda view backed by the server's internal event store. Full event CRUD with a modal form: title, all-day toggle, start/end date+time pickers, repeat (None/Daily/Weekly/Monthly/Yearly), description, location, and colour chips. Custom RRULE strings are preserved read-only. +- **News** — RSS article feed with per-feed filtering and reactions. Tap "Discuss" to open any article in a new chat conversation. +- **Projects** — browse and edit projects; tap a project to see its milestone-grouped task list. +- **Voice I/O** — tap the microphone in the capture bar or chat to dictate. Server-side STT transcribes audio; TTS reads assistant replies aloud in voice mode. - **Note & task editing** — full Markdown editor for notes, task editor with due date, priority, project, and milestone assignment. - **OAuth / SSO** — authenticates via your server's OIDC provider; local username/password login also supported if enabled server-side. - **Session persistence** — stays logged in across restarts via a persistent cookie jar. +- **Auto-refresh** — data refreshes automatically when the app returns to the foreground (throttled to once per 5 minutes) and when switching between shell tabs. - **Auto-update** — checks your Forgejo releases on launch and prompts to download and install new APKs in-app. ## Requirements @@ -39,33 +44,50 @@ On first launch, enter your FabledAssistant server URL (e.g. `https://fabled.exa ``` lib/ -├── main.dart # Entry point; resolves async deps before runApp -├── app.dart # GoRouter + auth redirect guards + 3-tab shell +├── main.dart # Entry point; resolves async deps before runApp +├── app.dart # GoRouter + auth guards + 3-tab shell + auto-refresh ├── core/ -│ ├── constants.dart # Route name constants -│ ├── exceptions.dart # AppException hierarchy -│ └── theme.dart # Custom slate-indigo ColorScheme + Fraunces typography +│ ├── constants.dart # Route name constants +│ ├── exceptions.dart # AppException hierarchy +│ └── theme.dart # Custom slate-indigo ColorScheme + Fraunces typography ├── data/ -│ ├── api/ # Dio HTTP layer (one class per resource) -│ ├── models/ # Plain Dart models with fromJson/toJson -│ └── repositories/ # Thin wrappers over API classes -├── providers/ # Riverpod providers (state + dependency wiring) -│ ├── briefing_provider.dart # Today's briefing — optimistic UI, SSE, polling +│ ├── api/ # Dio HTTP layer (one class per resource) +│ │ ├── chat_api.dart # SSE streaming; typed ChatStreamEvent (text/status) +│ │ ├── events_api.dart # Calendar event CRUD +│ │ ├── knowledge_api.dart # Two-tier paginated knowledge feed +│ │ ├── news_api.dart # RSS feed + reactions +│ │ └── voice_api.dart # STT + TTS endpoints +│ ├── models/ # Plain Dart models with fromJson/toJson +│ │ ├── calendar_event.dart # CalendarEvent + dateOnly() helper +│ │ ├── knowledge_item.dart # KnowledgeItem (notes/tasks unified) +│ │ └── message.dart # Chat message with streaming status +│ └── repositories/ # Thin wrappers over API classes +├── providers/ # Riverpod providers (state + dependency wiring) +│ ├── briefing_provider.dart # Today's briefing — optimistic UI, SSE, polling +│ ├── calendar_provider.dart # CalendarNotifier: month navigation + event CRUD +│ ├── chat_provider.dart # Conversations + streaming messages + status +│ ├── knowledge_provider.dart # Two-tier pagination; delegates tasks to TasksApi +│ ├── news_provider.dart # NewsNotifier + FeedsNotifier │ └── capture_work_queue_provider.dart # Sequential in-memory capture queue ├── screens/ -│ ├── briefing/ # BriefingScreen + BriefingHistoryScreen -│ ├── library/ # LibraryScreen (unified notes/tasks/projects) -│ ├── chat/ # ConversationsTabScreen + ChatScreen -│ ├── notes/ # NoteDetailScreen + NoteEditScreen -│ ├── tasks/ # TaskEditScreen +│ ├── briefing/ # BriefingScreen + BriefingHistoryScreen +│ ├── calendar/ # CalendarScreen (TableCalendar) + EventFormSheet +│ ├── chat/ # ConversationsTabScreen + ChatScreen +│ ├── knowledge/ # KnowledgeScreen (6-tab feed + search + tag filters) +│ ├── library/ # ProjectTasksScreen (milestone-grouped task list) +│ ├── news/ # NewsScreen (feed filter + reactions + discuss) +│ ├── notes/ # NoteDetailScreen + NoteEditScreen +│ ├── projects/ # ProjectsScreen + ProjectEditScreen +│ ├── tasks/ # TaskEditScreen │ └── settings/ auth/ setup/ splash/ └── widgets/ - ├── chat_message_bubble.dart # Shared bubble (used by Chat + Briefing) - ├── briefing_digest_card.dart # Expandable first-message card - └── library_item_card.dart # Note / task / project row widgets + ├── chat_message_bubble.dart # Shared bubble (Chat + Briefing); shows tool status + ├── knowledge_item_card.dart # Card for notes, people, places, lists, tasks + ├── news_card.dart # RSS article card with reactions + └── voice_mic_button.dart # Animated mic button (capture bar + chat) ``` -**Key packages:** `flutter_riverpod`, `go_router`, `dio` + `cookie_jar`, `google_fonts`, `flutter_markdown_plus` +**Key packages:** `flutter_riverpod`, `go_router`, `dio` + `cookie_jar`, `google_fonts`, `flutter_markdown_plus`, `table_calendar`, `record`, `just_audio` ## Building a Release APK @@ -91,7 +113,7 @@ The build job has `needs: [analyze]` — a failed analyze or test blocks the APK To cut a release: ```bash -git tag v26.03.11 && git push origin v26.03.11 +git tag v26.04.06 && git push origin v26.04.06 ``` Requires a `RELEASE_TOKEN` secret (Forgejo PAT with `write:repository` scope) set in repo Settings → Secrets → Actions.