Add accessibility improvements and update documentation

Accessibility (Phase 4.2):
- Add descriptive tooltips to all header bar buttons
- Add title/author tooltips to book tiles for screen readers
- Add tooltips to batch action bar buttons
- Add tooltips to BookDetails and SettingsDialog buttons

Documentation updates:
- Update PLAN.md with Phase 4 completion status
- Update README.md with implemented features summary
- Update database_manager.md with new API methods and schema

🤖 Generated with [Claude Code](https://claude.com/claude-code)

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

PLAN.md

@@ -215,13 +215,20 @@ Note: Arrow key navigation in grid is handled by GTK's GridView natively.
 Tab navigation works through GTK's focus system.
 
 ### 4.2 Accessibility Labels
-**Files**: All UI files
-**Status**: Not Started
+**Files**: `src/BibliothecaWindow.cpp`, `src/BookTile.cpp`, `src/BookDetails.cpp`, `src/SettingsDialog.cpp`
+**Status**: COMPLETED
 
-- [ ] Add ARIA labels to all buttons
-- [ ] Screen reader support for book tiles
-- [ ] High contrast mode support
-- [ ] Focus indicators
+Implemented:
+- [x] Header bar buttons: descriptive tooltips (back, search, tags, settings, add)
+- [x] Book tiles: tooltip with title and author for screen readers
+- [x] Batch action bar: tooltips for Select All, Clear, Add Tag, Delete
+- [x] BookDetails: tooltips for Open Book and Add Tag buttons
+- [x] SettingsDialog: tooltips for Save, Cancel, scan button
+- [x] TagManagerDialog: tooltips for rename and delete buttons (already had)
+
+Note: GTK4 uses tooltips as accessible names for icon-only buttons. High contrast mode
+and focus indicators are handled by the GTK theme system. ARIA is a web standard;
+GTK uses the ATK/AT-SPI accessibility framework natively.
 
 ### 4.3 Documentation Updates
 **Files**: `docs/*.md`

docs/README.md

@@ -46,12 +46,16 @@ through the system.
 - **libzip + tinyxml2**: EPUB metadata extraction.
 - **OpenSSL (libcrypto)**: SHA-256 hashing.
 
+## Implemented features
+
+- **Batch operations**: Multi-select mode with rubberband selection, batch tagging, batch delete.
+- **Tag management**: Rename, merge, and delete tags via dedicated dialog.
+- **Settings panel**: Adjustable tile size, default import folder, library maintenance.
+- **File change detection**: Scan for and remove books with missing files.
+- **Accessibility**: Descriptive tooltips for all buttons/controls for screen reader support.
+
 ## Future work
 
 - Add ADRs (`docs/decisions/`) for larger architectural choices.
 - Document additional subsystems as they appear (e.g., reader view).
 - Add screenshots or diagrams for quick onboarding.
-- Batch operations (multi-select, bulk tagging).
-- Tag management UI (rename, merge, delete tags).
-- Settings panel.
-- File change detection.

docs/database_manager.md

@@ -34,10 +34,22 @@ operation.
 ```sql
 CREATE TABLE IF NOT EXISTS books (
   id TEXT PRIMARY KEY,
-  title TEXT,
-  author TEXT,
-  file_path TEXT,
-  cover_path TEXT
+  title TEXT NOT NULL,
+  author TEXT NOT NULL DEFAULT '',
+  file_path TEXT NOT NULL,
+  cover_path TEXT NOT NULL DEFAULT '',
+  size_bytes INTEGER NOT NULL DEFAULT 0,
+  mtime_unix INTEGER NOT NULL DEFAULT 0,
+  added_at INTEGER NOT NULL DEFAULT (strftime('%s','now'))
+);
+```
+
+### settings table
+
+```sql
+CREATE TABLE IF NOT EXISTS settings (
+  key TEXT PRIMARY KEY,
+  value TEXT NOT NULL DEFAULT ''
 );
 ```
 
@@ -84,6 +96,27 @@ manager is the canonical place to evolve storage.
 | `add_tag_to_book(book_id, tag)`     | Associates a tag with a book.            |
 | `remove_tag_from_book(book_id, tag)`| Removes a tag association from a book.   |
 | `get_tags_for_book(book_id)`        | Returns all tags for a specific book.    |
+| `get_all_tags()`                    | Returns all tags with usage counts.      |
+| `rename_tag(old, new)`              | Renames a tag (merges if target exists). |
+| `delete_tag(tag_name)`              | Deletes a tag from all books.            |
+| `delete_unused_tags()`              | Removes orphan tags with no associations.|
+
+### Settings operations
+
+| Method                              | Description                              |
+|-------------------------------------|------------------------------------------|
+| `get_setting(key)`                  | Get a string setting value.              |
+| `get_setting(key, default)`         | Get setting with fallback value.         |
+| `set_setting(key, value)`           | Store a string setting.                  |
+| `get_setting_int(key, default)`     | Get an integer setting.                  |
+| `set_setting_int(key, value)`       | Store an integer setting.                |
+
+### Library scanning
+
+| Method                              | Description                              |
+|-------------------------------------|------------------------------------------|
+| `get_all_book_files()`              | Returns book file info for scanning.     |
+| `remove_books_by_ids(ids)`          | Batch remove books by ID.                |
 
 Internally each method locks `mtx_`, executes the prepared statement, and
 translates SQLite rows into `Book` objects. The `add_tag_to_book` method

src/BibliothecaWindow.cpp

@@ -169,10 +169,11 @@ BibliothecaWindow::BibliothecaWindow(DatabaseManager& db, BookList& bookList)
 }
 
 void BibliothecaWindow::buildHeaderBar() {
+  // Back button - tooltip serves as accessible label for icon-only buttons
   m_backButton.set_icon_name("go-previous-symbolic");
   m_backButton.set_has_frame(false);
   m_backButton.add_css_class("flat");
-  m_backButton.set_tooltip_text("Back");
+  m_backButton.set_tooltip_text("Go back to library");
   m_backButton.signal_clicked().connect([this]() {
     m_stack.set_visible_child("shelf");
     // Restore search filter when returning from details
@@ -183,10 +184,11 @@ void BibliothecaWindow::buildHeaderBar() {
   });
   m_headerBar.pack_start(m_backButton);
 
+  // Search toggle button
   m_searchButton.set_icon_name("system-search-symbolic");
   m_searchButton.set_has_frame(false);
   m_searchButton.add_css_class("flat");
-  m_searchButton.set_tooltip_text("Search (Ctrl+F)");
+  m_searchButton.set_tooltip_text("Search library (Ctrl+F)");
   m_searchButton.signal_toggled().connect(sigc::mem_fun(*this, &BibliothecaWindow::onSearchToggle));
   m_headerBar.pack_start(m_searchButton);
 
@@ -202,14 +204,14 @@ void BibliothecaWindow::buildHeaderBar() {
   m_settingsButton.set_icon_name("emblem-system-symbolic");
   m_settingsButton.set_has_frame(false);
   m_settingsButton.add_css_class("flat");
-  m_settingsButton.set_tooltip_text("Settings");
+  m_settingsButton.set_tooltip_text("Open settings");
   m_settingsButton.signal_clicked().connect(sigc::mem_fun(*this, &BibliothecaWindow::onSettingsClicked));
   m_headerBar.pack_end(m_settingsButton);
 
   // Add (+) button on the right
   m_addBookButton.set_icon_name("list-add-symbolic");
   m_addBookButton.set_has_frame(false);
-  m_addBookButton.set_tooltip_text("Add books to your library");
+  m_addBookButton.set_tooltip_text("Add books to library");
   m_addBookButton.signal_clicked().connect(sigc::mem_fun(*this, &BibliothecaWindow::onAddBookClicked));
 
   m_headerBar.pack_end(m_addBookButton);
@@ -310,20 +312,24 @@ void BibliothecaWindow::buildBatchActionBar() {
 
   m_batchSelectAllButton.set_label("Select All");
   m_batchSelectAllButton.add_css_class("flat");
+  m_batchSelectAllButton.set_tooltip_text("Select all books in the library");
   m_batchSelectAllButton.signal_clicked().connect(sigc::mem_fun(*this, &BibliothecaWindow::onBatchSelectAllClicked));
 
   m_batchClearButton.set_label("Clear");
   m_batchClearButton.add_css_class("flat");
+  m_batchClearButton.set_tooltip_text("Clear selection");
   m_batchClearButton.signal_clicked().connect(sigc::mem_fun(*this, &BibliothecaWindow::onBatchClearSelectionClicked));
 
   m_batchTagButton.set_label("Add Tag");
   m_batchTagButton.set_icon_name("tag-symbolic");
   m_batchTagButton.add_css_class("suggested-action");
+  m_batchTagButton.set_tooltip_text("Add a tag to selected books");
   m_batchTagButton.signal_clicked().connect(sigc::mem_fun(*this, &BibliothecaWindow::onBatchTagClicked));
 
   m_batchDeleteButton.set_label("Delete");
   m_batchDeleteButton.set_icon_name("user-trash-symbolic");
   m_batchDeleteButton.add_css_class("destructive-action");
+  m_batchDeleteButton.set_tooltip_text("Delete selected books from library");
   m_batchDeleteButton.signal_clicked().connect(sigc::mem_fun(*this, &BibliothecaWindow::onBatchDeleteClicked));
 
   // Build tag popover

src/BookDetails.cpp

@@ -22,6 +22,7 @@ BookDetails::BookDetails(DatabaseManager& db, BookList& book_list) :
   append(m_author);
 
   m_open_button.set_label("Open Book");
+  m_open_button.set_tooltip_text("Open book in default application");
   m_open_button.signal_clicked().connect(sigc::mem_fun(*this, &BookDetails::on_open_button_clicked));
   append(m_open_button);
 
@@ -39,6 +40,7 @@ BookDetails::BookDetails(DatabaseManager& db, BookList& book_list) :
   m_tag_entry.set_placeholder_text("New tag...");
   tag_entry_box.append(m_tag_entry);
   m_add_tag_button.set_label("Add Tag");
+  m_add_tag_button.set_tooltip_text("Add the entered tag to this book");
   m_add_tag_button.signal_clicked().connect(sigc::mem_fun(*this, &BookDetails::on_add_tag_button_clicked));
   tag_entry_box.append(m_add_tag_button);
   append(tag_entry_box);

src/BookTile.cpp

@@ -158,9 +158,18 @@ void BookTile::rebuild() {
   m_cover.set_paintable(tex);
 
   m_cover.set_size_request(m_coverSize, m_coverSize);
-  m_title.set_text(m_book.title().empty()
+
+  Glib::ustring displayTitle = m_book.title().empty()
                    ? Glib::path_get_basename(m_book.filePath())
-                   : m_book.title());
+                   : m_book.title();
+  m_title.set_text(displayTitle);
+
+  // Build accessible tooltip with title and author
+  Glib::ustring tooltip = displayTitle;
+  if (!m_book.author().empty()) {
+    tooltip += " by " + m_book.author();
+  }
+  set_tooltip_text(tooltip);
 }
 
 void BookTile::onActivated() {

src/SettingsDialog.cpp

@@ -83,7 +83,9 @@ SettingsDialog::SettingsDialog(Gtk::Window& parent, DatabaseManager& db)
   buttonBox->set_margin(12);
   buttonBox->set_halign(Gtk::Align::END);
   m_cancelButton.add_css_class("destructive-action");
+  m_cancelButton.set_tooltip_text("Discard changes and close");
   m_saveButton.add_css_class("suggested-action");
+  m_saveButton.set_tooltip_text("Save settings and close");
   buttonBox->append(m_cancelButton);
   buttonBox->append(m_saveButton);
   m_contentBox.append(*buttonBox);