From d73d8546946248d4d84cab12b2041fef74c807e9 Mon Sep 17 00:00:00 2001
From: Shihaam Abdul Rahman <shihaam@shihaam.me>
Date: Thu, 26 Mar 2026 23:49:39 +0500
Subject: [PATCH] add docs part 3

---
 docs/gallery-viewer.md | 63 +++++++++++++++++++++++-------------------
 docs/search.md         |  2 ++
 2 files changed, 37 insertions(+), 28 deletions(-)

diff --git a/docs/gallery-viewer.md b/docs/gallery-viewer.md
index 4a34b03..17c79cd 100644
--- a/docs/gallery-viewer.md
+++ b/docs/gallery-viewer.md
@@ -15,7 +15,8 @@ The gallery viewer provides:
 
 ```
 ┌─────────────────────────────────────────────────────────────┐
-│  ←  [Actions: Share, Edit, Cast, ⋮]           Info ℹ️      │
+│  ←  [♥] [🔍] [▶️] [⬆️] [⬇️] [+] [📺] [💬] [ℹ️]              │
+│     (contextual actions based on asset state)               │
 ├─────────────────────────────────────────────────────────────┤
 │                                                             │
 │                                                             │
@@ -25,9 +26,10 @@ The gallery viewer provides:
 │                                                             │
 │                                                             │
 ├─────────────────────────────────────────────────────────────┤
-│  [Stack thumbnails if stacked]                              │
+│  [Video controls - if video asset]                          │
 ├─────────────────────────────────────────────────────────────┤
-│  ♥    📤    ⬇️    🗑    [Add to Album]                       │
+│  [Share]  [Edit]  [Archive]  [Stack]  [Delete]              │
+│     (contextual actions - vary by asset ownership/type)     │
 └─────────────────────────────────────────────────────────────┘
 ```
 
@@ -99,34 +101,39 @@ Optional setting that enables:
 
 ## Top App Bar
 
-### Actions Available
-| Icon | Action |
-|------|--------|
-| ← | Close viewer |
-| Share | System share sheet |
-| Edit | Open image editor |
-| Cast | Cast to Chromecast |
-| ⋮ | More options menu |
-| ℹ️ | Show info panel |
-
-### More Options Menu
-- Download
-- Set as album cover
-- View in map
-- Show motion photo
-- Stack/unstack
-- Advanced info (debug)
+### Actions Available (conditional based on context)
+| Icon | Condition | Action |
+|------|-----------|--------|
+| ← | Always | Close viewer / Go back |
+| ♥ | Remote asset, owner only | Toggle favorite |
+| 🔍 | Owner, not in timeline/trash/locked | Locate in timeline |
+| ▶️ | Live/motion photo | Play motion photo |
+| ⬆️ | Local-only asset | Upload to server |
+| ⬇️ | Remote-only, owner | Download to device |
+| + | Remote, owner/partner, not trashed/locked | Add to album |
+| 📺 | Remote + WebSocket connected, or casting | Cast to Chromecast |
+| ↩️ | Trashed asset | Restore from trash |
+| 💬 | In shared album, not locked | View activities/comments |
+| ℹ️ | Always | Show info panel |
 
 ## Bottom Action Bar
 
-### Primary Actions
-| Icon | Action |
-|------|--------|
-| ♥ | Toggle favorite |
-| 📤 | Share |
-| ⬇️ | Download to device |
-| 🗑 | Move to trash |
-| 📁 | Add to album |
+### Actions (conditional based on context)
+| Icon | Condition | Action |
+|------|-----------|--------|
+| 📤 Share | Always | System share sheet |
+| 🎨 Edit | Image only, not locked | Open image editor |
+| 📦 Archive | Owner, not locked | Archive/Unarchive asset |
+| 📚 Stack | Owner with stacked assets, not locked | Show stack options |
+| 🗑 Delete | Owner, not in album | Move to trash or delete |
+| ⬇️ Download | Non-owner only | Download to device |
+| ✕ Remove | In album view | Remove from current album |
+
+### Context-Specific Behavior
+- **Owner viewing own asset**: Share, Edit, Archive, Delete visible
+- **Non-owner viewing partner asset**: Share, Download visible
+- **Viewing in album**: Share, Edit, Archive, Remove from album visible
+- **Viewing in locked folder**: Only Share and Delete visible
 
 ## Asset Info Panel
 
diff --git a/docs/search.md b/docs/search.md
index 7f882e7..7dcb83a 100644
--- a/docs/search.md
+++ b/docs/search.md
@@ -219,6 +219,8 @@ SearchFilter {
   }
   rating: RatingFilter  // If rating feature enabled
   language: String      // For AI search localization
+  assetId: String?      // Search for specific asset by ID
+  tagIds: List<String>? // Filter by tag IDs
 }
 ```