](http://apps.obtainium.imranr.dev/redirect.html?r=obtainium://add/https://github.com/stormlightlabs/lazurite/releases)
+[](http://apps.obtainium.imranr.dev/redirect.html?r=obtainium://add/https://github.com/stormlightlabs/lazurite/releases)
## Features
-### Home Feed & Composer
-
-| Home Feed | Composer | Profile |
-| --------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
-|  |  |  |
-| View your personal timeline with support for threads and media. | Create new posts with rich text and media attachments. Supports replies and quoting. | View detailed actor profiles, including their feed and metadata. |
-
-### Search & Profile
-
-| Search | About | DevTools |
-| ----------------------------------------------------- | ------------------------------------ | ------------------------------------------------------------------------------------- |
-|  |  |  |
-| Discover people and posts across the Bluesky network. | About (showing Rose Pine Moon theme) | Built-in logs and developer utilities for exploring the AT Protocol (Rose Pine Dawn). |
-
-### Offline Support & Drafts
-
-Local-only drafts and caching powered by Drift (SQLite).
-
-- **Drafts:** Save posts locally and publish later.
-- **Search History:** Persisted local search history.
-- **Saved Feeds:** Manage and pin your favorite feeds.
-
-## What Lazurite Offers Beyond Bluesky
-
-### Available Now
-
-- **Semantic Search:** On-device vector embeddings (all-MiniLM-L6-v2) let you search saved
- and liked posts by meaning, not just keywords.
-- **Post Scheduling:** Write posts now, publish them later.
-- **Follow Audit:** Bulk-analyze your follows to find deleted, deactivated, suspended, or
- blocking accounts. Batch unfollow in one tap like [clean follows](https://cleanfollow-bsky.pages.dev/)
-- **Constellation Integration:** See who has blocked you and which lists you appear on,
- powered by [Constellation](https://constellation.microcosm.blue) backlinks.
-- **AT Protocol Dev Tools:** Browse any user's PDS repository, inspect collections and
- individual records as JSON, like an in-app [pds.ls](https://pds.ls/).
-- **Rich Theming:** Five full palettes (Lazurite™️[^2], Rose Pine, Catppuccin, Nord, Oxocarbon),
- each with light and dark variants, built on Material 3.
-- **Offline First:** First page of feeds is cached locally; drafts, search history, and saved
- posts persist in an on-device database.
-- **Local Drafts:** Auto-saved to the database, surviving crashes and force-closes. Multiple
- drafts per account with full reply/quote/media context.
-- **Layout Options:** Toggle between Card and Compact feed views. Configure thread
- auto-collapse depth (off, 1–6 levels).
-- **In-App Logs:** Filter by level, full-text search, share or export, useful for
- debugging and AT Protocol development.
-
-### On the Roadmap
-
-- **RSS Feed Export:** View and export any public Bluesky profile as an RSS feed.
-- **Custom Fonts:** User-selectable serif, sans-serif, and monospace typefaces across the
- entire app.
-- **Markdown Posts:** Toggleable Markdown rendering in post bodies.
-- **Firehose & Jetstream Viewers:** Live AT Protocol event streams inside Dev Tools.
-- **Auto-Threading:** Automatically split long posts into threaded replies.
-- **Last Read Position:** Resume your timeline exactly where you left off.
+### Core Bluesky & BlackSky Client
+
+- Home timeline, custom feeds, feed pinning, and feed reordering.
+- Post threads, replies, quote posts, reposts, likes, saves, and sharing.
+- Rich post composition with facets, images, video uploads, replies, quotes, drafts, and scheduling.
+- Profile screens with author feeds, likes, starter packs, lists, follows, followers, and profile actions.
+- Search for posts, actors, hashtags, starter packs, and profile-scoped posts.
+- Notifications, direct messages, lists, starter packs, labelers, and moderation preferences.
+- In-app image viewer, video playback, media sharing, and media download support.
+
+### Local And Offline Features
+
+- Drift-backed local cache for the first page of feeds and profile data.
+- Local drafts with account-scoped reply, quote, and media context.
+- Local saved posts, liked-post sync, and search history.
+- On-device semantic search for saved and liked posts using MiniLM embeddings and ObjectBox vector search.
+- Offline-aware screens that render cached data and disable network-only actions when needed.
+
+### Account And Protocol Tools
+
+- OAuth login, account switching, session restore, and debug app-password login.
+- Provider-aware AppView routing for Bluesky, Blacksky, and validated custom AppViews.
+- Follow audit for deleted, deactivated, suspended, blocking, hidden, and self-follow records.
+- Profile context powered by [Constellation](https://constellation.microcosm.blue) backlinks.
+- AT Protocol Dev Tools for browsing PDS repositories, collections, and records as JSON.
+- In-app logs with level filters, search, sharing, and export for debugging.
+
+### Customization
+
+- Five theme palettes: Lazurite™️[^2], Rose Pine, Catppuccin, Nord, and Oxocarbon.
+- Light and dark variants built on Material 3.
+- Card and Compact feed layouts.
+- Configurable thread auto-collapse depth.
+
+## Planned
+
+### Reading And Media
+
+- Gallery mode for browsing media-heavy feeds and post threads.
+- Last-read position for resuming timelines.
+- RSS feed export for public Bluesky profiles.
+
+### Publishing
+
+- Markdown rendering for post bodies.
+- Auto-threading for long posts.
+
+### Customization
+
+- User-selectable serif, sans-serif, and monospace typefaces.
+- Expanded layout controls for feed density and feed architecture.
+
+### Protocol And Maintenance
+
+- Social graph visualization.
+- Firehose and Jetstream viewers inside Dev Tools.
+- Expanded notification settings, permission flows, and remote push validation.
## Architecture
diff --git a/docs/dev/animate.md b/docs/dev/animate.md
new file mode 100644
index 0000000..ef848eb
--- /dev/null
+++ b/docs/dev/animate.md
@@ -0,0 +1,65 @@
+---
+title: Motion
+updated: 2026-05-07
+---
+
+Lazurite uses small motion cues to show navigation, feedback, and loading
+state. Motion should help the user understand what changed. It should not draw
+attention to itself.
+
+`flutter_animate` is the shared animation package for widget-level effects such
+as fades, slides, scales, shimmer, and staggered entrances. Use raw controllers
+only when the interaction needs custom timing or scroll-driven behavior that
+the shared package does not fit.
+
+## Shared Tokens
+
+Animation durations, curves, and stagger offsets belong in
+`lib/core/theme/animation_tokens.dart`. Shared helpers live in
+`lib/core/theme/animation_utils.dart`. Widget files should use those tokens
+instead of local magic numbers. This keeps feed cards, snackbars, buttons, and
+empty states moving at the same pace.
+
+Common timing buckets are fast feedback, normal entrance or exit, and slower
+state transitions. Staggered lists cap the number of offset items so pagination
+does not create long delayed sequences.
+
+## Where Motion Is Used
+
+Feed cards, notification rows, search results, follow-audit rows, list members,
+and saved posts use a one-time entrance as new items appear. Track seen item
+keys so scrolling back does not replay the animation.
+
+Like, repost, and bookmark controls use short scale feedback when toggled.
+Bottom navigation uses a small active-icon transition. Floating action buttons
+scale in when they appear and scale out when removed. Snackbars enter from the
+bottom and dismiss quickly.
+
+Loading placeholders use shimmer where it communicates waiting for content with
+known shape. Empty states fade and scale in once, avoiding abrupt swaps between
+loading and empty UI.
+
+Profile banner parallax is scroll-driven and should stay separate from
+`flutter_animate`. It is implemented with scroll offset and transforms so it
+does not trigger layout work.
+
+## Reduced Motion
+
+Respect `MediaQuery.disableAnimations`. When the platform asks for reduced
+motion, skip nonessential transitions. Route changes can use a short crossfade,
+and loading indicators may continue when they communicate progress rather than
+decoration.
+
+Reduced-motion behavior needs widget coverage. Tests should mount the widget
+with disabled animations and verify that optional animation wrappers are not in
+the tree or that the final state is reached without waiting for motion.
+
+## Performance And Tests
+
+Prefer transform and opacity effects because they stay on the compositor path.
+Avoid animating dimensions in scrolling lists. Check feed and profile surfaces
+with Flutter performance tools when adding broad motion.
+
+Tests should settle animations before checking final state. Token tests guard
+against accidental timing drift, while focused widget tests cover action
+feedback, reduced motion, shimmer placeholders, and one-time list entrances.
diff --git a/docs/dev/compose-notifications-actions.md b/docs/dev/compose-notifications-actions.md
new file mode 100644
index 0000000..9542a19
--- /dev/null
+++ b/docs/dev/compose-notifications-actions.md
@@ -0,0 +1,70 @@
+---
+title: Compose, Notifications, And Actions
+updated: 2026-05-07
+---
+
+Compose, notification polling, post actions, profile actions, and saved posts
+touch local state and network writes. Use optimistic UI only where rollback
+behavior is clear and tested.
+
+## Compose
+
+`ComposeBloc` in `lib/features/compose/bloc/compose_bloc.dart` tracks text,
+facets, media, reply refs, quote refs, language tags, and submission status.
+Posts are written through `ComposeRepository` with `com.atproto.repo.createRecord`
+in the `app.bsky.feed.post` collection.
+
+Text length is counted with Dart grapheme clusters, not code units. The submit
+action is disabled for empty text and over-limit posts. Rich text facets are
+detected before submission and rendered as a live preview while the user types.
+
+Images upload through `com.atproto.repo.uploadBlob` and are embedded as
+`app.bsky.embed.images`. A post may include up to four images. Video upload
+uses `app.bsky.video.uploadVideo`, then polls job status until the processed
+blob is available. Video and image embeds are mutually exclusive; switching
+between them should ask before replacing existing attachments.
+
+Drafts are account-scoped Drift rows. Network failure and explicit save both
+persist the draft. Scheduled posts extend the draft model with a future publish
+time and rely on platform background scheduling to retry when connectivity
+returns.
+
+## Notifications
+
+`NotificationBloc` in `lib/features/notifications/bloc` owns polling state.
+Polling notifications use `app.bsky.notification.listNotifications`,
+`getUnreadCount`, and `updateSeen`. Notifications are grouped by day and render
+author, reason, reason icon, read state, and an optional post preview.
+
+Foreground unread polling runs on an interval while the app is active. Opening
+the notifications screen marks current notifications as seen. Tapping a
+notification routes to the relevant post or profile. Later push notification
+work builds on this navigation and seen-state model.
+
+## Post And Profile Actions
+
+Likes, reposts, follows, and blocks are AT Protocol records. Muting is a server
+procedure call. `PostActionRepository` and `ProfileActionRepository` should
+derive delete keys from viewer state URIs rather than guessing record keys.
+
+Post actions manage like, repost, reply, share, save, report, and copy-link
+behavior. Profile actions manage follow, mute, block, report, DID copy, and
+profile sharing. Destructive actions require confirmation where user intent
+could be ambiguous.
+
+Optimistic updates immediately adjust icon state and counts, run the network
+request, then reconcile with the server response. On failure, state rolls back
+and the user receives a snackbar. Tests should cover success, rollback, and
+viewer-state hydration.
+
+## Saved Posts
+
+Saved posts are private and local-only. `SavedPostsCubit` reads and writes
+Drift rows with
+`account_did`, `post_uri`, serialized post JSON, and `saved_at`. The table has a
+unique account/post constraint so repeated saves update one row instead of
+creating duplicates.
+
+The save action is shown from post controls and overflow menus. Saved posts are
+read back through a Cubit that exposes both the saved-post list and a quick
+lookup stream for filled bookmark state in feeds.
diff --git a/docs/dev/feeds-search-logging.md b/docs/dev/feeds-search-logging.md
new file mode 100644
index 0000000..e7d8707
--- /dev/null
+++ b/docs/dev/feeds-search-logging.md
@@ -0,0 +1,67 @@
+---
+title: Feeds, Search, And Logging
+updated: 2026-05-07
+---
+
+Feeds, search, logging, and the PDS explorer share two implementation rules:
+repositories hide network details, and UI state stays explicit enough to test
+without live services.
+
+## Logging
+
+`AppLogger` in `lib/core/logging/app_logger.dart` is the shared logging entry
+point. Feature code should log through that wrapper so filtering, redaction,
+file output, and in-app viewing stay consistent.
+
+Console logging is development-only. File logging is available in all builds
+and writes rotated daily files in the app documents directory. HTTP logging
+must redact authorization data and avoid full request or response bodies. Use
+summary fields, route names, status codes, and bounded body previews.
+
+The log viewer in `lib/features/logs` reads persisted log files from disk. It
+supports level filtering, text search, sharing the current log, and clearing
+logs with confirmation. File reads and UI filters belong in `LogViewerCubit`
+rather than a larger feature Bloc.
+
+## Home Feeds
+
+`FeedRepository` in `lib/features/feed/data/feed_repository.dart` loads the
+Following timeline and user-pinned feed generators. The timeline uses
+`app.bsky.feed.getTimeline`. Generator feeds use `app.bsky.feed.getFeed` with
+the generator AT-URI. Both return hydrated post views and paginate by cursor.
+
+Pinned feed preferences live in the user's Bluesky preferences, backed by
+local Drift caching for offline startup. The `savedFeedsPrefV2` array controls
+which feeds appear as tabs, their order, and whether each entry is a timeline,
+generator, or list. Mutations should update local state optimistically, persist
+to the server, and reconcile with the returned preference state.
+
+The feed renderer reuses the shared post-card stack. Feed-specific code should
+own only pagination, refresh state, and feed identity.
+
+## Search
+
+`SearchRepository` in `lib/features/search/data/search_repository.dart` owns
+post and actor search. Post search uses `app.bsky.feed.searchPosts`. Actor
+search uses `app.bsky.actor.searchActors`, and handle autocomplete uses the
+typeahead path documented in [typeahead.md](./typeahead.md).
+
+Search history is account-scoped in Drift. Insertions update the timestamp for
+repeat queries, and each account keeps a bounded recent history. UI actions
+include re-running a past search, deleting one entry, and clearing all entries.
+
+Search state should keep result type, query, pagination cursor, loading state,
+and error state separate. Avoid mixing actor typeahead into post-search
+pagination state; the shared typeahead repository and cubit own autocomplete.
+
+## PDS Explorer
+
+The PDS explorer in `lib/features/devtools` is a developer tool for inspecting
+AT Protocol repositories. It resolves handles to DIDs, lists repo collections,
+paginates records, and opens individual records as formatted JSON. It also
+accepts AT-URIs so a developer can jump directly to a record.
+
+Explorer requests use `com.atproto.identity.resolveHandle`,
+`com.atproto.repo.describeRepo`, `com.atproto.repo.listRecords`, and
+`com.atproto.repo.getRecord`. The tool is read-only and should stay isolated
+from production feed or profile state.
diff --git a/docs/dev/follow-hygiene.md b/docs/dev/follow-hygiene.md
new file mode 100644
index 0000000..5a365fe
--- /dev/null
+++ b/docs/dev/follow-hygiene.md
@@ -0,0 +1,60 @@
+---
+title: Follow Hygiene
+updated: 2026-05-07
+---
+
+Follow hygiene audits the active account's follow records and helps the user
+remove dead or problematic follows in batches. It works from the user's own
+repo records, then hydrates followed accounts to classify their current state.
+
+## Audit Flow
+
+`FollowAuditRepository` in `lib/features/profile/data/follow_audit_repository.dart`
+paginates `app.bsky.graph.follow` records through
+`com.atproto.repo.listRecords` for the active DID. Each record provides the
+follow URI, record key, and subject DID. The repository then batch-hydrates
+subjects with `app.bsky.actor.getProfiles`.
+
+Missing profiles are resolved individually so the app can distinguish deleted,
+deactivated, and suspended accounts where the API exposes that difference.
+Profiles that hydrate successfully are classified from viewer state and labels.
+The implemented statuses include deleted, deactivated, suspended, blocked by,
+blocking, mutual block, hidden, and self-follow.
+
+## Rate Limits And Partial Results
+
+Profile hydration uses the SDK batch limit of 25 actors. Batches run with
+bounded concurrency and backoff on transient errors. Partial hydration failure
+does not discard the whole audit. The Cubit reports failed profile count and
+continues with the results it could classify.
+
+## Batch Unfollow
+
+Batch removal uses `com.atproto.repo.applyWrites` delete operations against the
+`app.bsky.graph.follow` collection. Each delete operation uses the rkey from
+the original follow record URI. Writes are chunked to the protocol limit and
+executed sequentially.
+
+After each successful chunk, local state updates the completed count. If a chunk
+fails, the Cubit stops, reports how many accounts were already unfollowed, and
+leaves the remaining selected rows available for retry.
+
+## UI Model
+
+`FollowAuditCubit` in `lib/features/profile/cubit/follow_audit_cubit.dart`
+drives the audit screen through fetching records, classifying profiles, ready,
+unfollowing, complete, and error states. The UI shows scan progress, category
+counts, selectable rows, visibility filters, and selected totals.
+
+Rows include checkbox, handle, truncated DID, status badge, and profile
+navigation. The screen renders empty and complete states for clean audits and
+finished removals. Entry points are guarded behind the authenticated account and
+appear where account maintenance actions are expected.
+
+## Boundaries
+
+The audit does not infer inactivity from posting history. That would require
+fetching feeds for every followed account and would be expensive for large
+follow lists. There is also no automatic undo; unfollow is a protocol write.
+Any future undo flow should keep a local, time-bounded list of removed DIDs and
+make re-follow explicit.
diff --git a/docs/dev/foundation.md b/docs/dev/foundation.md
new file mode 100644
index 0000000..92815a0
--- /dev/null
+++ b/docs/dev/foundation.md
@@ -0,0 +1,78 @@
+---
+title: App Foundation
+updated: 2026-05-07
+---
+
+Lazurite's app shell is feature-first Flutter code backed by `flutter_bloc`,
+`go_router`, and Drift. Cross-feature concerns live under `lib/core`; feature
+modules own their data, state, and presentation code under `lib/features`.
+
+State is modeled with small Bloc or Cubit classes. Presentation widgets render
+state and dispatch user intent; they should not own network or persistence
+rules. State classes are immutable and use explicit `copyWith` methods. Session
+or preference values that must survive app restarts are loaded from Drift rather
+than widget state.
+
+## Persistence
+
+Drift is the primary local store. The schema lives in
+`lib/core/database/tables.dart` and `lib/core/database/app_database.dart`.
+Account, cached profile, cached post, and settings rows form the base local
+model. Any user-scoped row must include the active account DID, and repository
+queries should filter by that DID. Drift migrations remain mandatory for schema
+changes.
+
+The account table stores the DID, handle, and token material needed to restore
+the active session. Sensitive values must not be logged. Settings store theme
+choice, active account, and later feature preferences.
+
+## Authentication
+
+Production login uses AT Protocol OAuth. Lazurite is a public native client
+with a hosted client metadata document and DPoP-bound tokens. The login flow
+resolves the user's account authority, sends the user through the system
+browser, captures the callback, exchanges the authorization code, and stores
+the resulting session for later restore.
+
+DPoP proof generation belongs in the auth layer. Every authenticated request
+uses the access token plus a fresh DPoP header. Refresh behavior is owned by
+the OAuth client and recovery services, not individual screens.
+
+App-password login exists only for debug paths. It calls
+`com.atproto.server.createSession`, stores the returned JWTs, and should remain
+guarded by debug flags. App-password sessions do not have the same protocol
+coverage as OAuth sessions, so production behavior should assume OAuth.
+
+Logout revokes or discards the active token state, clears the in-memory
+authentication state, and returns the user to login. Account switching builds
+on the same account table, but the active DID setting decides which session is
+currently hydrated.
+
+## Profile Rendering
+
+Profiles are fetched through `app.bsky.actor.getProfile` or batched with
+`getProfiles`. The profile UI renders avatar, banner, display name, handle,
+description, counts, and any supported extended fields.
+
+Author feeds come from `app.bsky.feed.getAuthorFeed`, paginated with cursors.
+The feed renderer consumes hydrated `feedViewPost` values, including embeds,
+reply metadata, language tags, and viewer state. The same post-card renderer is
+used across later feed, search, saved-post, and list surfaces.
+
+Rich text facets use UTF-8 byte ranges, not Dart UTF-16 indices. Use
+`bluesky_text` or existing shared facet helpers to detect and render mentions,
+links, and tags. Mentions navigate to profile routes, hashtags navigate to
+topic or search routes, and normal links open externally unless a provider-aware
+internal route exists.
+
+## Settings And Themes
+
+Settings expose system, light, and dark modes plus named theme palettes. Theme
+selection is persisted in Drift and applied through `ThemeMode` at the app
+root. New widgets should read theme data through the shared theme extensions in
+`lib/core/theme`.
+
+The implemented palette work includes built-in families such as Oxocarbon,
+Catppuccin, Nord, and Rose Pine. Each palette maps into Flutter `ThemeData` and
+`ColorScheme` objects. Feature code should depend on semantic colors from the
+theme, not raw palette constants, unless it is implementing the theme itself.
diff --git a/docs/dev/patterns.md b/docs/dev/patterns.md
index 6fc5cb1..3b76a47 100644
--- a/docs/dev/patterns.md
+++ b/docs/dev/patterns.md
@@ -1,4 +1,7 @@
-# Lazurite Code Patterns
+---
+title: Code Patterns
+updated: 2026-05-07
+---
This document captures recurring architectural and implementation patterns in the Lazurite codebase.
@@ -110,7 +113,7 @@ State copyWith({
## Testing Patterns
-- Per-file harness builders are standard (`buildSubject(...)`, plus helpers like `openSheet(...)`) so test bodies focus on behavior, not setup.
+- Per-file setup builders are standard (`buildSubject(...)`, plus helpers like `openSheet(...)`) so test bodies focus on behavior, not setup.
- Widget tests usually mount through `MaterialApp`/`Scaffold` for component tests, and `MaterialApp.router` + `GoRouter` for navigation tests.
- Interaction flow follows a consistent shape:
`pumpWidget` -> input (`tap`, `enterText`) -> `pump`/`pumpAndSettle` -> assertions on visible UI and side effects.
@@ -120,4 +123,4 @@ State copyWith({
- `MockClient` from `http/testing.dart` for HTTP-level contracts
- Small local fake implementations when protocol surfaces are complex
- Async UI timing is made explicit where animations/debounce are relevant (`pump(const Duration(...))` in sheet/search tests), and responsive behavior is exercised with `setSurfaceSize` in router/shell tests.
-- Defensive assertions are common for robustness: boundary-value checks in utility tests, null/empty/error-path repository tests, and `expect(tester.takeException(), isNull)` guards in navigation/router tests.
+- Defensive assertions are common: boundary-value checks in utility tests, null/empty/error-path repository tests, and `expect(tester.takeException(), isNull)` guards in navigation/router tests.
diff --git a/docs/dev/routing.md b/docs/dev/routing.md
new file mode 100644
index 0000000..0074ecd
--- /dev/null
+++ b/docs/dev/routing.md
@@ -0,0 +1,76 @@
+---
+title: AppView Routing
+updated: 2026-05-07
+---
+
+Lazurite can route AppView reads through Bluesky, Blacksky, or a validated
+custom provider. The selected provider controls `app.bsky.*` content routing
+and web-link resolution. It does not decide where the user's account
+authenticates; OAuth authority still comes from the account's PDS metadata.
+
+## Provider Model
+
+Provider selection is persisted from login and settings. Built-in providers
+define a stable key, AppView service DID, public XRPC host, login entryway, and
+web base URL. Custom providers require validation before use.
+
+`AppViewRouter` in `lib/core/network/app_view_router.dart` is the runtime
+source of provider state. Repositories should ask it for headers, public
+endpoint URLs, auth entryway URLs, web-link resolution, and health results.
+Long-lived services should not cache provider fields independently.
+
+## Request Policy
+
+`AppBskyRoutingPolicy` applies the request policy. Authenticated `app.bsky.*`
+requests route through the user's PDS with an explicit `atproto-proxy` header
+for the selected AppView. Signed-out public `app.bsky.*` reads call the
+selected provider's public host directly. `com.atproto.*` requests bypass
+AppView routing and resolve to the relevant repo or PDS.
+
+Provider switching requires a soft restart. The app persists the new provider,
+stops new requests, cancels in-flight work where possible, rebuilds dependency
+injection, and drops stale responses by routing epoch. This prevents mixed
+provider state across long-lived Cubits and repositories.
+
+## Fallbacks
+
+Cross-provider fallback is opt-in and limited to read-only public endpoints. It
+can retry transient failures such as rate limits, server errors, timeouts, or
+DNS failure against another built-in provider. It must not retry writes across
+providers.
+
+Identity fallback through Slingshot and backlink enrichment through
+Constellation are separate settings and separate trust boundaries. Treat
+fallback data as recovery or enrichment, not as authority for writes.
+
+## Health And Capability
+
+Provider health probes run at startup and through a manual settings action.
+Capability checks track specific endpoints such as profile reads, post-thread
+reads, trends, and trending topics. The router uses capability state to avoid
+blind retries against a provider that does not support a path.
+
+Logs should include provider, endpoint, fallback reason, and circuit-breaker
+state without including auth tokens or full payloads.
+
+## Trending
+
+Trending is a route at `/trending`. `TrendingScreen` loads trending topics and
+trend metadata from the selected provider. `lib/features/feed/data/trending_join.dart`
+joins topic rows with trend rows by parsed link key first, then by normalized
+topic text. If multiple candidates match, the newest trend wins, with a stable
+link tie-breaker.
+
+The screen handles provider divergence. Bluesky and Blacksky can return
+different link formats and suggested topic sets. Unknown internal links fall
+back to provider-aware external URLs. If topic loading fails, the screen shows a
+blocking error. If topic loading succeeds but metadata fails, the screen renders
+usable topic rows with a non-blocking metadata warning.
+
+## OAuth Boundary
+
+Selected AppView controls content reads. OAuth host selection starts with the
+account authority: resolve handle or DID, fetch protected-resource metadata, and
+prefer the advertised authorization server. Fallbacks can use the resolved PDS,
+then default entryways, but the selected AppView must not override account
+authority.
diff --git a/docs/dev/semantic-search.md b/docs/dev/semantic-search.md
new file mode 100644
index 0000000..e951e28
--- /dev/null
+++ b/docs/dev/semantic-search.md
@@ -0,0 +1,72 @@
+---
+title: Semantic Search
+updated: 2026-05-07
+---
+
+Semantic search lets users search saved and liked posts by meaning while
+keeping all indexing and query work on device. Drift remains the source of truth
+for post content. ObjectBox stores embedding vectors and the metadata needed to
+join search results back to Drift rows.
+
+## Storage Model
+
+ObjectBox is the secondary store for vectors. `EmbeddedPost` in
+`lib/core/objectbox/embedded_post.dart` records the post URI, active account
+DID, source (`saved` or `liked`), indexed text, vector, and embedding timestamp.
+The vector uses a 384-dimensional HNSW cosine index.
+
+All queries filter by account DID. Account switching must not query another
+account's vector rows. Removing a saved or liked post deletes the matching
+embedded row.
+
+Liked posts are cached in Drift so they can participate in local search. The
+liked-post table is account-scoped, keyed by post URI, and capped to keep
+storage bounded. Sync fetches recent likes until it reaches a known URI or the
+configured cap.
+
+## Embedding Runtime
+
+`EmbeddingService` in `lib/core/embedding/embedding_service.dart` loads the
+bundled MiniLM INT8 TFLite model and WordPiece vocabulary in a long-lived
+isolate. The isolate keeps model work off the UI thread. Each request tokenizes
+text, pads or truncates to the model limit, runs inference, normalizes the
+vector, and returns it to the caller.
+
+Searchable text comes from the post text, image alt text, and link-card title
+or description. If the model or tokenizer cannot load, the service reports
+unavailable and UI entry points hide or explain semantic search rather than
+throwing.
+
+## Indexing
+
+`SemanticIndexer` in `lib/features/search/data/semantic_indexer.dart` handles
+incremental indexing when a post is saved or synced as liked. The indexer
+extracts text, embeds it, and upserts the ObjectBox row. Backfill runs when the
+feature is enabled for an account or when the user requests reindexing. It
+processes posts in batches and reports progress for the settings UI.
+
+Posts on AT Protocol are immutable for this purpose, so embeddings do not need
+content refresh. Deletion paths still matter: unsave and unlike must remove
+vectors so search results match the user's visible saved and liked sets.
+
+## Query Flow
+
+`SemanticSearchRepository` embeds the query with the same model, runs ObjectBox
+nearest-neighbor search, applies account and source filters, then hydrates full
+post views from Drift. Results are ordered by vector similarity and shown with a
+relevance indicator.
+
+The UI lives as a Search tab on the saved-posts screen. It debounces input,
+supports saved/liked/both scopes, reuses post cards, and exposes empty,
+unavailable, loading, and no-result states. Settings control feature enablement,
+default scope, indexed count, reindexing, and maximum result count.
+
+## Operational Notes
+
+ObjectBox initialization runs once at startup after Drift. The generated
+ObjectBox model files must stay committed. Entity changes require code
+generation and a review of migration impact on existing vector data.
+
+The feature has clear limits: image meaning is available only through alt text,
+search is scoped to one account, results are not BM25 re-ranked, and very old
+likes may fall outside the local like cap.
diff --git a/docs/dev/social-features-and-moderation.md b/docs/dev/social-features-and-moderation.md
new file mode 100644
index 0000000..b5543aa
--- /dev/null
+++ b/docs/dev/social-features-and-moderation.md
@@ -0,0 +1,93 @@
+---
+title: Social Features And Moderation
+updated: 2026-05-07
+---
+
+Messaging, in-app media, multi-account behavior, offline rendering, moderation, lists,
+and starter packs extend the same repository, Cubit, and presentation patterns used by
+feeds and profiles.
+
+## Direct Messages
+
+Direct messages use the `chat.bsky.*` namespace. `ConvoListBloc` in
+`lib/features/messages/bloc` manages conversation list state.
+`chat.bsky.convo.listConvos` loads conversations, and message threads paginate
+through `chat.bsky.convo.getMessages`. Sending uses `sendMessage`; starting a
+thread uses `getConvoForMembers`.
+
+The list separates primary conversations from requests. A request is a conversation
+where the active user has not sent a message. Threads render own messages on the
+trailing side and other messages on the leading side. Long press copies one message,
+while the conversation overflow can copy the full thread.
+
+## Media
+
+Media screens live under `lib/features/feed/presentation/media`. Images open
+in an in-app full-screen viewer with paging, zoom, alt text, share, and
+download controls. Videos open in an in-app player that uses the embed HLS
+playlist, respects aspect ratio, disposes controllers on pop, and handles
+GIF-style looping playback.
+
+Downloads ask for media-library permission only when the user starts a save.
+Images use their full-size URL. Videos resolve the best available playlist
+variant before saving. The UI reports progress and surfaces permission or
+download failures through snackbars.
+
+## Accounts And Offline State
+
+The active account DID is persisted in settings. Switching accounts updates the
+active DID, rebuilds account-scoped repositories and Cubits, and reloads data
+for the new identity. If refresh fails for the selected account, navigation
+returns to login for that account.
+
+Offline rendering depends on cached posts and profiles. Screens should show
+cached data first, fetch fresh data in the background, and keep rendering cache
+if the network call fails. Actions that require network access are disabled
+while offline with a clear explanation.
+
+## Moderation
+
+`ModerationService` in `lib/features/moderation/data/moderation_service.dart`
+uses Bluesky labelers, user preferences, and the SDK moderation engine. The app
+builds moderation options from the active account's preferences and subscribed
+labelers, then runs posts, profiles, and notifications through the appropriate
+moderation helper before display.
+
+Rendering uses the moderation UI decision for the current context. Filtered
+content is removed from lists. Blurred content gets a click-through overlay
+unless the decision forbids override. Inform and alert labels render as badges.
+Avatar-specific decisions use placeholder avatars when needed.
+
+Subscribed labeler definitions are cached in Drift so preference screens and
+moderation decisions can use recent data when offline. The XRPC client includes
+the accepted-labelers header on content requests and updates that header when
+preferences change.
+
+## Lists
+
+`ListRepository` in `lib/features/lists/data/list_repository.dart` manages AT
+Protocol graph list records. Curation lists provide feeds, moderation lists can
+be muted or blocked as a group, and reference lists back starter packs. List
+records, list items, and list blocks are created and deleted through
+`com.atproto.repo` operations.
+
+My Lists shows lists created by the active account. List detail screens show
+metadata, members, and for curation lists, a feed backed by
+`app.bsky.feed.getListFeed`. Member management uses actor typeahead, creates
+`app.bsky.graph.listitem` records, and deletes the corresponding item records
+when removing members.
+
+## Starter Packs
+
+`StarterPackRepository` in `lib/features/starter_packs/data` manages starter
+packs. A starter pack points at a reference list for members and can include up
+to three feed generator URIs.
+
+Creating a starter pack first creates the reference list, then member list-item
+records, then the starter pack record. Editing members changes the backing
+reference list. Editing name, description, or feeds updates the starter pack
+record.
+
+Starter pack detail screens render creator, description, member sample, feed
+recommendations, and join counts. Actor profile surfaces can show starter packs
+created by that actor, and search can route directly to a pack detail screen.
diff --git a/docs/dev/typeahead.md b/docs/dev/typeahead.md
new file mode 100644
index 0000000..9151818
--- /dev/null
+++ b/docs/dev/typeahead.md
@@ -0,0 +1,74 @@
+---
+title: Typeahead
+updated: 2026-05-07
+---
+
+Typeahead is a shared actor autocomplete system used by login, search,
+jump-to-profile, list member management, and starter pack member management. It
+normalizes results from more than one backend so UI code can render one result
+model.
+
+## Providers
+
+The official provider calls `app.bsky.actor.searchActorsTypeahead` through the
+Bluesky SDK. It requires an authenticated session and returns profile basics,
+including viewer data when available.
+
+The community provider calls the waow.tech compatible XRPC endpoint over HTTP.
+It does not require authentication, so login can offer suggestions before the
+user has a session. It returns a compatible actors array but omits viewer state.
+The app adds an `X-Client: lazurite` header and applies local moderation after
+parsing.
+
+Both providers normalize into the shared typeahead result model: DID, handle,
+optional display name, optional avatar URL, and labels. UI code should not
+branch on raw provider response shapes.
+
+## Repository Behavior
+
+`TypeaheadRepository` in `lib/features/typeahead/data/typeahead_repository.dart`
+owns provider selection, HTTP calls, SDK calls, parsing, moderation filtering,
+and fallback. When the configured provider is official, it delegates to the SDK
+and includes moderation-aware request behavior. When the configured provider is
+community, it performs the HTTP request, parses JSON, and filters locally.
+
+If the community endpoint fails and an authenticated Bluesky client is
+available, the repository can fall back to the official endpoint. Login cannot
+use this fallback because there is no session yet. Fallbacks should be logged
+with provider and failure reason.
+
+## Settings
+
+The selected provider is stored in settings as `typeahead_provider`. The
+default is the official Bluesky provider. Settings expose both official and
+community options, with copy that makes the third-party nature of the community
+provider clear.
+
+Login overrides the setting and uses the community provider because official
+typeahead requires auth. All authenticated surfaces respect the saved setting.
+
+## UI And State
+
+`TypeaheadCubit` owns query changes, debounce, loading, results, and error
+state. Consumers should use the shared Cubit or repository instead of calling
+search repositories directly for actor autocomplete.
+
+`TypeaheadTextField` in `lib/features/typeahead/presentation/typeahead_text_field.dart`
+anchors suggestions below a text field with an overlay. It debounces input,
+ignores empty or too-short queries, and updates overlay position with keyboard
+and layout changes. Selecting a result fills the field and calls the consumer's
+selection callback.
+
+The search screen should keep post search state separate from actor typeahead.
+Jump-to-profile, list member add, and starter pack member add use the same
+autocomplete path so moderation, rate limiting, and provider choice remain
+consistent.
+
+## Limits
+
+Debounce defaults to 300 ms and empty queries return without network calls.
+In-flight requests should be canceled or ignored when a newer query starts.
+
+Community responses do not include viewer state, so follow badges or other
+viewer-dependent affordances should hide rather than guess. DID entry bypasses
+typeahead because typeahead is handle and display-name search.
diff --git a/docs/images/about.png b/docs/images/about.png
deleted file mode 100644
index 387b329f94f9f1229f67a70ae6817fb151f7f580..0000000000000000000000000000000000000000
GIT binary patch
literal 0
HcmV?d00001
literal 117125
zcmeAS@N?(olHy`uVBq!ia0y~yV0y>Ez-q?9#=yXE>bfzAVk{1FcVbv~PUa;81A|Ly
zglC$sFM}2X0|N&GV|yk83j+fKBLf426axq_FJNR~28%Enbp3kqp(RS2aGW6QzlMRfuM^3ky@=gd{9p-xUlHc>4L1(+gt@Ll?Zqs~t
z%Gp^nnx%EdJl;hO3zh^;&-n8+e9zR*-|gJ&lkW$(o4a>J9JUZ-EBh$;d~sC3H4mMH
zEA}F9@7Mi4yR+}ZME$Hsr#