fix readme repo diagram, add agents.md

AGENTS.md

@@ -0,0 +1,175 @@
+# AGENTS.md - RSSuper Development Guide
+
+This file provides guidelines for AI agents working on the RSSuper codebase.
+
+## Project Overview
+
+RSSuper is a native multi-platform RSS reader:
+- **iOS/macOS**: Swift + SwiftUI + Xcode
+- **Android**: Kotlin + Jetpack Compose + Gradle
+- **Linux**: Vala + GTK4 + Libadwaita + Meson
+- **Windows**: Planned (C# + WinUI3)
+
+## Build Commands
+
+### Main Build Script (all platforms)
+```bash
+./scripts/build.sh                           # Build all platforms (debug)
+./scripts/build.sh -p ios,android            # Build specific platforms
+./scripts/build.sh -t release                # Release build
+./scripts/build.sh --test                    # Build and test
+./scripts/build.sh -a clean                  # Clean all
+```
+
+### iOS/macOS
+```bash
+./scripts/build-ios.sh                       # Debug build
+./scripts/build-ios.sh Release iOS build     # Release build
+./scripts/build-ios.sh Debug iOS test         # Run tests
+./scripts/build-ios.sh Debug iOS clean        # Clean
+
+# Single test file (in Xcode)
+xcodebuild test -scheme RSSuper -destination 'platform=iOS Simulator,name=iPhone 15' \
+  -only-testing:RSSuperTests/SearchQueryTests
+```
+
+### Android
+```bash
+cd android && ./gradlew assembleDebug       # Debug APK
+cd android && ./gradlew assembleRelease     # Release APK
+cd android && ./gradlew test                 # Run all unit tests
+cd android && ./gradlew test --tests "com.rssuper.search.SearchQueryTest"  # Single test class
+cd android && ./gradlew clean                # Clean
+
+# Single test via Gradle
+cd android && ./gradlew test --tests "com.rssuper.search.SearchQueryTest.testParse*"
+```
+
+### Linux
+```bash
+./scripts/build-linux.sh debug build         # Debug build
+./scripts/build-linux.sh release test        # Run tests
+./scripts/build-linux.sh debug clean          # Clean
+```
+
+## Code Style Guidelines
+
+### General Principles
+- Write clean, readable code with minimal comments (only when logic is complex)
+- Follow existing patterns in each platform's codebase
+- Use dependency injection for testability
+- Prefer explicit over implicit
+
+### Kotlin (Android)
+- **Formatting**: 4 spaces indentation, 140 char line limit
+- **Naming**: `camelCase` for functions/variables, `PascalCase` for classes
+- **Imports**: Grouped: standard library → Android → third-party → project
+- **Types**: Use Kotlin null safety, prefer `val` over `var`
+- **Error Handling**: Use `Result<T>` or sealed classes for errors (see `SearchQuery.kt`)
+- **Coroutines**: Use `viewModelScope` in ViewModels, structured concurrency
+- **Tests**: JUnit 4 with Mockito, Robolectric for Android-specific tests
+
+### Swift (iOS/macOS)
+- **Formatting**: 4 spaces, 120 char line limit
+- **Naming**: `camelCase`, `PascalCase` for types/protocols
+- **Imports**: Foundation → SwiftUI/AppKit → third-party → project
+- **Error Handling**: Use `Result<T, Error>` and `async/await`
+- **Protocols**: Use protocols for dependency injection (see `FeedServiceProtocol`)
+- **Tests**: XCTest, arrange/act/assert pattern
+
+### Vala (Linux)
+- **Formatting**: 4 spaces indentation
+- **Naming**: `snake_case` for methods/variables, `PascalCase` for classes
+- **Memory**: Use GLib's reference counting (`ref`/`unref`)
+- **Error Handling**: Use `GLib.Error` and `try/catch`
+
+### Android-specific
+- **ViewModels**: Use `androidx.lifecycle.ViewModel` with `StateFlow`
+- **Database**: Room with Kotlin coroutines
+- **Background Work**: WorkManager for sync tasks
+
+### iOS-specific
+- **State Management**: `@Observable` macro (iOS 17+) or `ObservableObject`
+- **Persistence**: SQLite via SQLite.swift
+- **Background**: BGTaskScheduler for background refresh
+
+## Architecture Patterns
+
+### Clean Architecture Layers
+1. **UI Layer**: SwiftUI Views / Jetpack Compose
+2. **ViewModel/ViewModel**: Business logic, state management
+3. **Service Layer**: `FeedService`, `SearchService`, `BookmarkStore`
+4. **Data Layer**: Database managers, network clients
+
+### Dependency Injection
+- Android: Manual DI in constructors (no framework)
+- iOS: Protocol-based DI with default implementations
+
+## Testing Guidelines
+
+### Unit Tests Location
+- **Android**: `android/src/test/java/com/rssuper/`
+- **iOS**: `iOS/RSSuperTests/`
+- **Linux**: Test files alongside source in `linux/src/`
+
+### Test Naming Convention
+- `MethodName_State_ExpectedResult` (e.g., `SearchQueryTest.parseEmptyQueryReturnsNull`)
+
+### Test Data
+- Fixtures in `tests/fixtures/` (sample RSS/Atom feeds)
+
+## File Organization
+
+```
+RSSuper/
+├── android/                    # Kotlin Android library
+│   ├── src/main/java/com/rssuper/
+│   │   ├── model/             # Data models
+│   │   ├── parsing/           # Feed parsers
+│   │   ├── state/             # State management
+│   │   ├── viewmodel/         # ViewModels
+│   │   ├── search/            # Search service
+│   │   └── database/          # Room database
+│   └── src/test/              # Unit tests
+├── iOS/RSSuper/               # Swift iOS app
+│   ├── Models/                # Data models
+│   ├── Parsing/               # Feed parsers
+│   ├── Services/              # Business logic
+│   ├── ViewModels/            # ViewModels
+│   ├── Networking/            # HTTP client
+│   ├── Settings/              # User preferences
+│   └── Database/              # SQLite layer
+├── iOS/RSSuperTests/          # Unit tests
+├── linux/                     # Vala GTK app
+│   └── src/                   # Source + tests
+├── scripts/                   # Build scripts
+└── tests/fixtures/           # Test data
+```
+
+## Common Tasks
+
+### Running a Single Android Test
+```bash
+cd android
+./gradlew test --tests "com.rssuper.search.SearchQueryTest"
+```
+
+### Running a Single iOS Test
+```bash
+./scripts/build-ios.sh Debug iOS test
+# Or in Xcode: Product > Run Tests (select specific test)
+```
+
+### Adding a New Platform Module
+1. Create directory under `native-route/`
+2. Add build command to `./scripts/build.sh`
+3. Add test configuration to CI workflow
+4. Update this AGENTS.md
+
+## Important Notes
+
+- The Android project uses a library module structure (not application)
+- iOS minimum deployment: iOS 16.0+
+- Android minimum SDK: 24 (Android 7.0)
+- Linux requires GTK4, Libadwaita, SQLite3 development headers
+- All platform modules share similar business logic patterns