Initial Comicviewer implementation

AGENTS.md

@@ -0,0 +1,86 @@
+# AGENTS.md
+
+## Project Overview
+
+Comicviewer is a desktop comic archive viewer for CachyOS and Arch Linux.
+It browses local, SMB, FTP, and SFTP locations and opens image files stored in
+ZIP archives.
+
+## Technology
+
+- Rust
+- GTK4 with GIO/GVfs for desktop and remote filesystem integration
+- SQLite for cached directory metadata, search indexes, and reading history
+- AppImage as the primary distribution format
+- Korean-first UI with all user-facing strings kept translatable
+
+## Core Requirements
+
+- Save local and remote location profiles, including credentials.
+- Store credentials as plain text in the application configuration as requested,
+  but restrict the configuration file permissions to `0600`.
+- Cache remote directory metadata and refresh it asynchronously when browsing.
+- Download remote ZIP archives before opening them.
+- Limit the persistent ZIP cache with a user-configurable LRU quota. The default
+  is 10 GB. A quota of 0 disables persistent ZIP caching and uses temporary files.
+- Support JPEG, PNG, WebP, static GIF, BMP, and AVIF images in ZIP archives.
+- Sort archive images and browser entries using natural filename ordering.
+- Support ascending and descending sorting by name, modification time, and
+  creation time. Treat unavailable creation times as unknown rather than
+  inventing values.
+- Search folder and ZIP names recursively below the current location using the
+  cached index.
+- Provide 100%, fit-width, fit-height, two-page, and continuous vertical viewing.
+- Support both right-to-left and left-to-right two-page layouts, plus controls
+  that advance by one page to adjust page pairing.
+- Save progress per ZIP and save the most recently read ZIP for resume support.
+
+## Data Locations
+
+Follow the XDG Base Directory specification:
+
+- Configuration: `${XDG_CONFIG_HOME:-~/.config}/comicviewer/`
+- Persistent data: `${XDG_DATA_HOME:-~/.local/share}/comicviewer/`
+- Cache: `${XDG_CACHE_HOME:-~/.cache}/comicviewer/`
+
+Do not write application state into the source tree.
+
+## Engineering Guidelines
+
+- Prefer the smallest correct implementation and avoid speculative abstractions.
+- Keep network and archive work off the GTK main thread.
+- Show cached directory data immediately, then update it in the background.
+- Use atomic writes for configuration, database migrations, and completed remote
+  downloads. Incomplete downloads must use a distinct temporary suffix.
+- Do not extract an entire archive to disk. Decode only requested images and
+  prefetch a small window around the current page.
+- Validate archive entry sizes and image dimensions before allocation.
+- Never trust archive paths or use them as extraction destinations.
+- Preserve errors from GIO, ZIP parsing, and image decoding and present concise,
+  actionable messages in the UI.
+- Keep protocol-independent browsing logic separate from GTK widgets.
+- Do not introduce credential encryption or keyring integration unless the
+  requirement changes.
+
+## Quality Checks
+
+Before considering a change complete, run the checks available in the project,
+including formatting, linting, and tests. Once the Rust project exists, the
+minimum expected commands are:
+
+```sh
+cargo fmt --check
+cargo clippy --all-targets --all-features -- -D warnings
+cargo test --all-features
+```
+
+Add focused tests for natural sorting, cache eviction, metadata refresh,
+archive filtering, reading progress, and remote file change detection.
+
+## Git Practices
+
+- Keep commits focused and do not commit generated build output or cached data.
+- Do not commit real server addresses, usernames, passwords, or local test
+  configuration.
+- Update documentation when runtime dependencies or AppImage requirements
+  change.