docs: update README

README.md

@@ -2,11 +2,11 @@
 
 Feather is a RSS reader client. It can:
 
-* connect to any server supporting the Tiny Tiny RSS API or the Google Reader API (FreshRSS, Miniflux, etc.) :D
+* connect to any server supporting the Tiny Tiny RSS API or the Google Reader API (FreshRSS, Miniflux, many others) :D
 * read your feeds in a native interface, regardless of desktop environment, CLI or GUI :D
 * read your feeds fully offline :D
 * integrate with many other programs effortlessly :D
-* run on pretty much anything :D
+* and do all that while using less resources than a web browser showing a blank page :D
 
 That's right, using an innovative technology known as "plain files", Feather allows you to read your feeds in any file manager that exist or will exist in the future.
 See [usage](#usage) to admire it working.
@@ -67,7 +67,7 @@ html.filename_template = "{% if unread %}☐{% else %}☑{% endif %} [{{ feed_ti
 
 Note that if you delete a read article from the reader directory, it will be marked as unread and the file will be recreated during the next synchronization.
 
-![mark_read_articles_unread]()
+![]() TODO
 
 ### Updating with the server
 
@@ -76,7 +76,7 @@ Run `feather sync` to synchronize all local data with the server. The synchroniz
 - `feather sync-up` which upload local changes to the server (e.g. update read status of local articles);
 - `feather sync-down` which download all articles from the server into the local state. This might be a lot of data depending on how many articles you have on the server.
 
-If you don't want to bother running `feather sync` manually, you can also start the Feather update daemon using `feather daemon`. The daemon will periodically call `sync-up` (by default every minute) and `sync-down` (by default every 15 minutes) for as long as it runs.
+If you don't want to bother running `feather sync` manually, you can also start the Feather update daemon using `feather daemon`. The daemon will periodically call `sync-up` and `sync-down` for as long as it runs.
 
 #### If you are offline
 
@@ -95,27 +95,71 @@ If you changed to another remote server or if you somehow messed up your local f
 Since, as the kids say, everything is a file, Feather can be easily integrated with any other program which operate on files (and there's a lot of those). A couple examples:
 
 - you can use Syncthing to synchronize the reader directory with other computer without having to install Feather on each one. You'd still have to install Syncthing on each one, but if for some unknown reason you prefer installing Syncthing to Feather, it works. Note that Syncthing real-time change detection can sometime miss changes when there's a lot of small files like with Feather, so you may want to reduce the _Full Rescan Interval_ in the share settings unless you're fine with some of your feeds taking a whole hour to update;
-- you can process your feeds easily with regular scripts: `find reader/ -iname 'trump' -delete` will mark all feeds containing "Trump" in their filename as read; which I think is way easier than messing around with your feed reader API or convoluted filtering rules directly, but that's just my opinion.
+- you can process your feeds easily with regular scripts: `find reader/ -iname 'trump' -delete` will mark all feeds containing "Trump" in their filename as read; which I think is easier than messing around with your feed reader API or convoluted filtering rules directly, but that's just my opinion.
 
 ## Installation
 
 ### Docker
 
-TODO
+If use Docker or Podman, an image is available at `codeberg.org/TODO`.
 
-`docker run -d -v ./config.toml:/feather/config.toml -v feather-data:/feather/data -v ./reader:/feather/reader --name feather feather daemon`
+For example, to start a new container with the Feather daemon running, using the `config.yml` (see [basic configuration](#basic-configuration)) in the current directory and exposing the feeds in the `reader` directory:
 
-`docker exec feather feather sync`
+```sh
+docker run -d -v ./config.toml:/feather/config.toml:ro -v ./reader:/feather/reader -v feather-data:/feather/data --name feather TODO/feather daemon
+```
 
-If you're wondering how monstrous the resources required by Feather are, with my ~600 feeds on my Tiny Tiny RSS feather, it stays below ~50MB RAM usage and take ~4KB of disk space per article. The docker image is <200MB, which does not fit on a floppy disk but does easily on a CD.
+Instead of using a configuration file, you may also use environment variables; see [the default configuration file](src/feather/config.default.toml) for details.
+
+If you need to run Feather commands in a running container, run for example `docker exec feather feather regenerate`. Otherwise you could also start a new container as described above but using a command other than `daemon`.
+
+If you're wondering how monstrous the resources required by Feather are, with my ~600 feeds on my Tiny Tiny RSS, Feather stays at ~50MB RAM usage and take ~4KB of disk space per article. The docker image is ~120MB, which does not fit on a floppy disk but does easily on a CD.
+
+#### Quadlet
+
+If you're using Podman on Linux/systemd with Quadlet to manage your containers, here's an example Quadlet user file you can put in `~/.config/containers/systemd/feather.quadlet`:
+
+```ini
+[Unit]
+Description=Feather container
+
+[Container]
+ContainerName=feather
+Image=feather
+Exec=daemon
+
+# Auto-update container TODO
+#AutoUpdate=registry
+
+# Configuration file
+Volume=%h/Feather/config.toml:/feather/config.toml:ro,Z
+# Reader/article directory
+Volume=%h/Feather:/feather/reader:z
+# Feather data volume
+Volume=feather-data:/feather/data
+
+[Service]
+Restart=on-failure
+TimeoutStartSec=300
+
+[Install]
+WantedBy=default.target
+```
+
+Kindly ask systemd to reload unit files, start Feather, done:
+
+```sh
+systemctl --user daemon-reload
+systemctl --user start feather
+```
 
 ### Raw
 
 Feather should be able to run on anything that can run Python 3.12 or newer (you might need to change `html.max_filename_length` and `html.filename_replacement` in the configuration if your filesystem has exotic limitations).
 
-Once you have Python installed, download this repository and pip it up by running `pip install` inside it. You should be able to run `feather sync` or whatever command you want to run according to the (usage)[#usage] chapter. Although I personally use uv, so I'd just run `uv sync` and then `uv run feather sync` to run feather.
+Once you have Python installed, download this repository and pip it up by running `pip install` inside it. You should be able to run `feather sync` or whatever command you want to run according to the [usage chapter](#usage). Although I personally use uv, so I'd just run `uv sync` and then `uv run feather sync` to run Feather.
 
-### Configuration
+### Basic configuration
 
 In order for Feather to be able to do something useful, it needs to be able to connect to your RSS reader server. Here's some basic `config.toml` configuration files depending on what API you use:
 
@@ -124,12 +168,12 @@ In order for Feather to be able to do something useful, it needs to be able to c
 ```toml
 [server]
 api = "ttrss"
-url = "https://ttrss.example.com"
-user = "rsslad"
-password = "hunter2"
+url = "https://ttrss.example.com" # Tiny Tiny RSS URL
+user = "rsslad" # RSS reader username
+password = "hunter2" # RSS reader password/application password
 
 [datetime]
-timezone = "Europe/Bucharest"
+timezone = "Europe/Bucharest" # set your local timezone
 ```
 
 #### Google Reader API (FreshRSS, Miniflux, and others)
@@ -137,37 +181,45 @@ timezone = "Europe/Bucharest"
 ```toml
 [server]
 api = "googlereader"
-url = "https://freshrss.example.com/api/greader.php"
-user = "rsslad"
-password = "hunter2"
+url = "https://freshrss.example.com/api/greader.php" # API endpoint URL
+user = "rsslad" # RSS reader username
+password = "hunter2" # RSS reader password/application password
 
 [datetime]
-timezone = "Europe/Bucharest"
+timezone = "Europe/Bucharest" # set your local timezone
 ```
 
-There's more you can change in the configuration file, see [the default configuration file](src/feather/config.default.toml) and the (configuration chapter)[#configuration] for details.
+There's more you can change in the configuration file, see [the default configuration file](src/feather/config.default.toml) and the [configuration chapter](#configuration) for details.
 
 ## FAQ
 
-TODO
+I mean nobody asked them yet but I think I have a pretty good grasp on what people what to know.
 
-### Why
+### Why?
 
-### Name
+I rely on RSS a lot to keep in touch with outside my room, and I've been using Tiny Tiny RSS to do that for years at this point. Unfortunately, the historical developer decided to stop development this October 2025, and after trying other RSS readers I was unsatisfied and decided to make my own. As I was contemplating how to design the RSS reader of my dreams, I had a epiphany: a RSS reader is nothing more than directories and files. This was great because it meant I didn't have to make a GUI, as like most people, I find working more than necessary generally unpleasant. But then, it turned out that as far as personal effort go, something even better happened: the Tiny Tiny RSS community is continuing its development. Relieved but at the same time dejected that my epiphany went to waste, I thus decided to make only the directories and files part of my RSS reader, and let Tiny Tiny RSS do the rest. And here we are.
 
-### What should I eat tonight
+### Why the name "feather"?
 
-## TODO
+My mom taught me that if all my friends jump off a bridge I should too, and since most popular open-source projects are named after a common English noun I decided to do the same. If you're looking for a set of icons, a JavaScript framework, ML libraries, data analytics libraries, a game server, a smartphone application, or a lot of other things that aren't a RSS reader client, I regret to inform you that you have unfortunately found the wrong Feather.
 
-before publishing:
+### What should I eat tonight?
+
+Spaghetti alla carbonara is often a safe choice; even if you substitutes all of the ingredients you'll likely still end up with something decent. It still counts as carbonara if you use cream and mushrooms, trust me, I know how to say hello in Italian.
+
+## Future improvements
+
+While I mostly started this project for fun, it ended up actually quite usable, so I'm at least going to maintain it. As for new features, unless an incredible idea comes I'd like to keep this project simple (try your luck in the issue tracker!). But still, here's still some things that I wrote down during development that _may_ be done at some point:
+
+- [ ] Store & expose article attachments in the templates
+- [x] Use inotify for real-time article mark-as-read action, or other ways to make the synchronization more responsive in daemon mode (e.g. use a min-max range for synchronization periodicity, and trigger it before reaching max if a inotify event happened)
+- [ ] Partial synchronization (using since_id for ttrss and start_time for googlereader)
+
+
+
+# TODO before publishing
 
 - [ ] Write documentation
 - [ ] Share the fun somewhere
-- [ ] Test with FreshRSS
-    - [ ] Feed & category order for googlereader ??
-
-"i'll look into it later":
-
-- [ ] Get article attachments
-- [ ] Use inotify for real-time article mark-as-read action
-- [ ] Partial sync (using since_id for ttrss and start_time for googlereader)
+- [x] Test with FreshRSS
+    - [x] Feed & category order for googlereader ?? - doesn't seem to be available, sorry