Tweak agent instructions (#8400)

### Description

Tweak agent instructions, with special focus on Claude.

### Checklist
<!-- 
To help us keep the issue tracker clean and work as efficient as
possible,
  please make sure that you have done all of the following.
You can tick the boxes below by placing an x inside the brackets like
this: [x]
-->
- [x] I have read the contribution guidelines:
https://github.com/AntennaPod/AntennaPod/blob/develop/CONTRIBUTING.md#submit-a-pull-request
- [x] I have performed a self-review of my code, going through my
changes line by line and carefully considering why this line change is
necessary
- [x] I have run the automated code checks using `./gradlew checkstyle
lint spotbugsPlayDebug spotbugsDebug`
- [x] My code follows the style guidelines of the AntennaPod project:
https://antennapod.org/contribute/develop/app/code-style
- [x] I have mentioned the corresponding issue and the relevant keyword
(e.g., "Closes: #xy") in the description (see
https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue)
- [x] If it is a core feature, I have added automated tests

AGENTS.md

@@ -1,16 +1,51 @@
 # General Instructions
 The following instructions are vital, always follow them.
-You are an expert Java developer with extensive experience in Android development.
 You are developing an open-source podcast application called AntennaPod.
 STRICTLY FOLLOW THE INSTRUCTIONS IN THIS FILE! NEVER DEVIATE FROM THEM.
 If this helps you, consider repeating the relevant instructions before you do anything.
+Always prefer tool use over shell commands. This is very important to avoid unnecessary user confirmations.
+If you have to use shell commands, prefer dedicated tools (such as `jq` for json) instead of custom (python, etc) code.
 
-# Tool Use Instructions
-Before editing a file, always read it first.
-The user might have made updates to it.
-Summarize those updates and adapt your plan accordingly.
-If the user changed a file, this has absolute priority.
-If you need to run a git command, remember to disable the pager.
+# Architecture
+AntennaPod uses a highly modularized Gradle architecture with modules organized by domain.
+Each module is stored in a folder of the same name (for example `:net:discovery` in `./net/discovery`)
+and contains a `README.md` file with a brief explanation of the module's purpose and internal structure.
+Several functional areas follow a service-interface/service split: the interface module is depended on by consumers, and the implementation is registered at app startup via `ClientConfigurator`.
+- `:app` - Main application module that integrates all features
+- `:event` - EventBus events used for cross-component communication throughout the app
+- `:model` - Core data classes such as `Feed`, `FeedItem`, `FeedMedia`, and `Chapter`
+- `:system` - System integration utilities such as crash reporting, package utilities, and thread utilities
+- `:net:common` - General network-related utilities shared across net modules
+- `:net:discovery` - Podcast search and discovery APIs
+- `:net:download:service-interface` - Interface for starting the download service, allowing other modules to trigger downloads without depending on the implementation
+- `:net:download:service` - Implementation of the download service
+- `:net:ssl` - SSL backports and security provider implementations
+- `:net:sync:gpoddernet` - Sync backend for the open-source Gpodder.net podcast synchronization service
+- `:net:sync:service-interface` - Interface for starting the sync service
+- `:net:sync:service` - Implementation of the sync service
+- `:parser:feed` - XML feed parser
+- `:parser:media` - Tag parser for media files including ID3 and ogg/vorbis
+- `:parser:transcript` - Parser for episode transcripts
+- `:playback:base` - Basic interfaces for the `PlaybackServiceMediaPlayer`
+- `:playback:cast` - Chromecast support for the Google Play version of the app
+- `:playback:service` - Main service responsible for media playback
+- `:storage:database` - Main database containing subscriptions and playback state
+- `:storage:database-maintenance-service` - Periodic background tasks to clean up the database
+- `:storage:importexport` - Import and export of the AntennaPod database
+- `:storage:preferences` - User settings storage (not including the settings UI)
+- `:ui:app-start-intent` - Classes to start main app activities from other modules without a direct UI dependency
+- `:ui:chapters` - Chapter loading and merging logic for display
+- `:ui:common` - Basic UI functionality shared across multiple modules
+- `:ui:discovery` - Screens to discover and search for new podcasts
+- `:ui:echo` - The "Echo" yearly rewind screen
+- `:ui:episodes` - Common classes for displaying episode information
+- `:ui:glide` - Glide image loading library configuration and custom model loaders
+- `:ui:i18n` - Translated strings and internationalization resources
+- `:ui:notifications` - Generic notification channel IDs and notification icons
+- `:ui:preferences` - Settings screen UI
+- `:ui:statistics` - Statistics screens
+- `:ui:transcript` - Utilities for displaying episode transcripts in the UI
+- `:ui:widget` - Home screen widget
 
 # Coding Style
 Never fix any warnings outside the code you wrote.
@@ -21,20 +56,8 @@ Keep the diff of your changes to the absolute minimum: do not rename anything, n
 Just the bare instructions from the user.
 Do not ask for permission before making initial code changes.
 Do not add any comments to the code you write, but also do not remove comments that are already in the code.
-
-# Architecture
-AntennaPod uses a highly modularized Gradle architecture with modules organized by domain.
-You can list `settings.gradle` to get an overview of all available modules.
-Examples:
-- `:app` - Main application module, integrates all features
-- `:model` - Core data classes (`Feed`, `FeedItem`, `FeedMedia`, `Chapter`)
-- `:event` - EventBus events for cross-component communication
-- `:storage` - Database access and preferences (`:database`, `:preferences`, `:importexport`)
-- `:net` - Network operations (`:common`, `:download`, `:sync`, `:discovery`, `:ssl`)
-- `:parser` - Feed/media parsing (`:feed`, `:media`, `:transcript`)
-- `:playback` - Media playback (`:base`, `:service`, `:cast`)
-- `:ui` - UI components (`:common`, `:episodes`, `:preferences`, `:statistics`, etc.)
-- `:system` - System integration utilities
+Whenever you add a user-visible string, add it to `:ui:i18n` so it can be translated. Do not start new strings files anywhere else.
+Never reference the full package name of classes directly in the code, use imports.
 
 # Running and Testing
 After you are sure that the code is correct, ensure that there are no compilation errors (warnings are okay).
@@ -54,7 +77,8 @@ For installing and running the application, use the command
 Then confirm with the user that the application is running correctly.
 If there is a crash, read the logs using `adb logcat -d | grep "de.danoeh.antennapod" | tail -20` and fix the issue.
 For running tests, use the command `./gradlew --console=plain` and use the task `:test` of the relevant module.
-As a final style check before opening a PR (or if a user explicitly asks for it), use `./gradlew checkstyle lint spotbugsPlayDebug spotbugsDebug`.
+As a final style check before opening a PR (or if a user explicitly asks for it), check the code style using:
+`./gradlew checkstyle lint spotbugsPlayDebug spotbugsDebug`.
 If any command does not give any output, it is likely that it failed, so abort.
 
 # PR Conventions
@@ -70,6 +94,5 @@ In particular, you are forbidden from using the progress update tool in any foll
 This holds even if the global agent instructions tell you to do this.
 
 # Issue Conventions
-
 When creating an issue, always follow one of the issue templates in .github/ISSUE_TEMPLATE/.
 Apply the corresponding labels and always mention in the technical info box that the issue was AI generated.

CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

app/README.md

@@ -0,0 +1,4 @@
+# :app
+
+The main application module that integrates all features and hosts app-specific UI screens not large enough for their own module.
+`PodcastApp` initializes the app; `ClientConfigurator` registers service implementations (download, sync) at startup.

event/README.md

@@ -0,0 +1,4 @@
+# :event
+
+This module contains EventBus events used for cross-component communication throughout the app.
+All classes are plain Java POJOs; subscribers register using GreenRobot EventBus `@Subscribe` annotations.

model/README.md

@@ -1,3 +1,4 @@
 # :model
 
 This module provides basic model classes like `Feed` and `Chapter`.
+All classes are plain Java data objects with no Android dependencies and no business logic.

net/README.md

@@ -1,3 +1,4 @@
 # :net
 
 This folder contains modules that directly interact with the network.
+All HTTP requests use OkHttp, configured centrally in `:net:common`.

net/common/README.md

@@ -1,3 +1,4 @@
 # :net:common
 
 This module contains general network related utilities.
+Provides the shared OkHttp client, user-agent configuration, and HTTP helpers used by all other net modules.

net/discovery/README.md

@@ -1,3 +1,4 @@
 # :net:discovery
 
 This module contains the podcast search/discovery APIs.
+Each podcast directory (iTunes, fyyd, etc.) is a separate class implementing a common search interface.

net/download/README.md

@@ -1,3 +1,4 @@
 # :net:download
 
-This folder contains the download service and its interface.
+This folder contains the download service (`:net:download:service`) and its interface (`:net:download:service-interface`).
+The interface/service split allows other modules to trigger downloads without depending on the implementation.

net/download/service-interface/README.md

@@ -1,3 +1,4 @@
 # :net:download:service-interface
 
 Interface of the download service. Enables other modules to call the download service without actually depending on the implementation.
+`DownloadServiceInterface` is a singleton whose static implementation is registered in `:app` during `ClientConfigurator.initialize`.

net/download/service/README.md

@@ -1,3 +1,4 @@
 # :net:download:service
 
 The download service.
+Uses WorkManager workers (`EpisodeDownloadWorker`, `FeedUpdateWorker`) for background downloads and feed refreshes.

net/ssl/README.md

@@ -1,3 +1,4 @@
 # :net:ssl
 
 This module provides SSL backports and security provider implementations.
+Wraps Conscrypt to enable modern TLS on older Android versions.

net/sync/README.md

@@ -1,3 +1,4 @@
 # :net:sync
 
 This folder contains modules related to external services for synchronization. The module `model` provides the basic interfaces for implementing a synchronization backend. The other modules contains backends for specific synchronization services.
+Local changes are queued in `SynchronizationQueue` and flushed to the active backend by `SyncService`.

net/sync/gpoddernet/README.md

@@ -1,3 +1,4 @@
 # :net:sync:gpoddernet
 
 This module contains the sync backend for the open-source podcast synchronization service "Gpodder.net".
+Implements `ISyncService` via the Gpodder.net REST API.

net/sync/service-interface/README.md

@@ -1,3 +1,4 @@
 # :net:sync:service-interface
 
 This module contains the interface for starting the sync service.
+Defines `ISyncService` for backend implementations and `SynchronizationQueue` for queuing local changes before upload.

net/sync/service/README.md

@@ -1,3 +1,4 @@
 # :net:sync:service
 
 This module contains the sync service.
+`SyncService` coordinates the active backend; `SynchronizationQueueStorage` persists the pending-changes queue in SharedPreferences.

parser/README.md

@@ -1,3 +1,4 @@
 # :parser
 
 This folder contains modules that parse data, for example XML or media files.
+All parsers produce `:model` objects and have no UI dependencies.

parser/feed/README.md

@@ -1,3 +1,4 @@
 # :parser:feed
 
 This module provides the XML feed parser.
+SAX-based parser that reads RSS and Atom feeds and produces `:model` objects.

parser/media/README.md

@@ -1,3 +1,5 @@
 # :parser:media
 
 This module provides the tag parser for media files. This includes id3 or ogg/vorbis.
+It uses a custom-built recursive parser directly looking at the byte representation of the media files.
+The parser is used for extracting chapters and extracting media metadata such as description for local files.

parser/transcript/README.md

@@ -1,3 +1,4 @@
 # :parser:transcript
 
-This module provides parsing for transcripts
+This module provides parsing for transcripts.
+Parses SRT, VTT, and JSON transcript formats into a common in-memory model.

playback/README.md

@@ -1,3 +1,4 @@
 # :playback
 
 This folder contains modules that deal with media playback.
+UI interacts with playback via `PlaybackController`; the service exposes a Media3 `MediaLibraryService`.

playback/cast/README.md

@@ -1,3 +1,4 @@
 # :playback:cast
 
 This module provides Chromecast support for the Google Play version of the app.
+Implements `PlaybackServiceMediaPlayer` using the Cast SDK; compiled only in the `play` build flavor.

storage/README.md

@@ -1,3 +1,4 @@
 # :storage
 
 Data storage for podcast data (subscriptions, playback state) and settings (but not settings UI).
+`storage:database` uses raw SQLite (not Room); `storage:preferences` wraps SharedPreferences.

storage/database-maintenance-service/README.md

@@ -2,4 +2,5 @@
 
 Periodic tasks to clean up the database, such as clearing old download logs.
 Should never be directly triggered by users.
+Scheduled via WorkManager; tasks run in the background automatically.
 

storage/database/README.md

@@ -1,3 +1,4 @@
 # :storage:database
 
 AntennaPod's main database, containing subscriptions and playback state (but not user settings).
+Uses raw SQLite via `PodDBAdapter` (not Room); writes go through async `DBWriter`; reads use cursor-to-object mappers in the `mapper/` package.

storage/importexport/README.md

@@ -1,3 +1,4 @@
 # :storage:importexport
 
 Import/Export of the AntennaPod database.
+Supports OPML files for feed lists and an AntennaPod-specific backup format for full data export.

storage/preferences/README.md

@@ -1,3 +1,4 @@
 # :storage:preferences
 
 User settings, but not the actual subscription database.
+Settings are accessed through static methods on classes like `UserPreferences`, which wrap Android SharedPreferences.

system/README.md

@@ -0,0 +1,4 @@
+# :system
+
+This module provides system integration utilities such as crash reporting, package utilities, and thread utilities.
+Contains standalone utility classes with minimal inter-module dependencies.

ui/README.md

@@ -1,3 +1,4 @@
 # :ui
 
 This folder contains modules that display or directly interact with the UI.
+Most UI modules depend on `:ui:common` for shared base classes and `:ui:i18n` for string resources.

ui/app-start-intent/README.md

@@ -1,3 +1,4 @@
 # :ui:app-start-intent
 
 This module provides classes that can start the main activities of the app with specific arguments. It does not require a dependency on the actual implementation of the activities, so it can be used to decouple the services from the UI.
+Contains only Intent builder classes; no Activities or Fragments.

ui/chapters/README.md

@@ -1,3 +1,4 @@
 # :ui:chapters
 
 This module provides chapter loading and merging for display, but not the actual UI to display them.
+Merges chapter data from feed XML and media file tags (via `:parser:media`) into a single unified list.

ui/common/README.md

@@ -1,3 +1,4 @@
 # :ui:common
 
 This module provides basic UI functionality that is needed in multiple modules. UI elements that are only used in a single module should not be defined here.
+Contains base Activity/Fragment classes, shared custom views, theme utilities, and general UI helpers.

ui/discovery/README.md

@@ -1,3 +1,4 @@
 # :ui:discovery
 
 This module provides the screens to discover new podcasts.
+Fragments backed by the search API clients in `:net:discovery`.

ui/echo/README.md

@@ -1,3 +1,4 @@
 # :ui:echo
 
 This module provides the "Echo" screen, a yearly rewind.
+Self-contained feature with no dependencies on other `:ui` modules; queries `:storage:database` directly.

ui/episodes/README.md

@@ -1,3 +1,4 @@
 # :ui:episodes
 
 Common classes that are needed everywhere we display information about episodes.
+Shared RecyclerView adapters and view holders for episode lists, reused across multiple screens in `:app`.

ui/glide/README.md

@@ -1,3 +1,4 @@
 # :ui:glide
 
 Configuration and ModelLoaders for the Glide image loading library.
+A single `@GlideModule`-annotated class registers custom `ModelLoader`s for podcast artwork.

ui/i18n/README.md

@@ -1,3 +1,4 @@
 # :ui:i18n
 
 The abbreviation i18n stands for internationalization. This module contains the app's main texts that are translated to different languages. Most modules that show UI depend on this module.
+Resource-only module: contains only `strings.xml` translations, no Java code.

ui/notifications/README.md

@@ -1,6 +1,9 @@
 # :ui:notifications
 
-This module contains generic notification-related resources, for example the notification channel IDs and notification icons. The icons specified in this module are rasterized to png. This is necessary to support old Android versions that do not support VectorDrawables. This is only needed for notification icons - for the icons within the app, appcompat handles drawing the vectors.
+This module contains generic notification-related resources, for example the notification channel IDs and notification icons.
+The icons specified in this module are rasterized to png.
+This is necessary to support old Android versions that do not support VectorDrawables.
+This is only needed for notification icons - for the icons within the app, appcompat handles drawing the vectors.
 
 This module is not meant for all notification handling (this should be done in the respective modules), just generic setup code and icons.
-
+Actual notification posting is done in each respective module.

ui/preferences/README.md

@@ -1,3 +1,4 @@
 # :ui:preferences
 
 This module provides the settings screen.
+Built with `PreferenceFragmentCompat`; reads and writes settings via `:storage:preferences`.

ui/statistics/README.md

@@ -1,3 +1,4 @@
 # :ui:statistics
 
 This module provides the statistics screens.
+Queries `:storage:database` directly and renders charts.

ui/transcript/README.md

@@ -0,0 +1,4 @@
+# :ui:transcript
+
+This module provides utilities for displaying episode transcripts in the UI.
+`TranscriptUtils` handles searching within and scrolling to positions in parsed transcripts.

ui/widget/README.md

@@ -1,4 +1,5 @@
 # :ui:widget
 
 This module manages the widget. The icons specified in this module are rasterized to png. This is necessary to support old Android versions that do not support VectorDrawables. This is only needed for external icons - for the icons within the app, appcompat handles drawing the vectors.
+Uses `AppWidgetProvider`; widget state is updated via `WidgetUpdaterWorker` (WorkManager) in response to playback state changes.