docs: partially write the README

README.md

@@ -1,62 +1,152 @@
 # Feather: file-based RSS reader client
 
+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
+* 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
+
+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.
+
+Note however that Feather is meant to be used alongside a RSS reader server, meaning:
+
+* no grabbing feeds on its own, requiring a server to connect to :(
+* no feed management interface; Feather only support reading articles and marking them as read/unread :(
+
 ## Usage
 
-start with pictures/gif each time
+All demonstrations are done under Linux with GNOME Files, but a file manager is a file manager, use what you fancy.
 
-### Navigating feeds
+### Navigating feeds a.k.a. "using a file manager"
 
-Directories, sorting/searching by date/title (a.k.a. using a file manager), flattening nested dirs, etc.
+#### Navigating articles
 
-### Reading an article
+Feed categories are directories, and each file in these directories is an article.
 
-opening an article
+![]() TODO
+
+#### Sorting articles
+
+![]() TODO
+
+search + sort
+
+#### Searching
+
+![]() TODO
+
+Tip: if you have nested categories, search "html" to list all the articles in the category and its sub-categories in the same view.
+
+#### Reading an article
+
+![]() TODO
 
 ### Marking articles as read
 
-Delete
+![]() TODO
+
+Deleting an article will toggle their read status (will take effect on the next synchronization to the server).
 
 #### Handling read articles
 
-See read articles in the trash can.
+Surprisingly, the read articles can be found in the trash. If you restore them before the next synchronization, it's be as if nothing happened.
 
-Or ask feather to keep read articles:
+![]() TODO
 
-`server.only_sync_unread_articles = false`
-`html.filename_template = "{% if unread %}☐{% else %}☑{% endif %} [{{ feed_title }}]\t{{ title }} ({{ published }}).html"`
+Or, if you'd rather show read articles in the Feather reader directory directly, you could add to your configuration file:
+
+```toml
+# Grab both read and unread articles into the local directory
+server.only_sync_unread_articles = false
+# Add a checkmark in the article filename indicating the read status
+html.filename_template = "{% if unread %}☐{% else %}☑{% endif %} [{{ feed_title }}]\t{{ title }} ({{ published }}).html"
+```
+
+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]()
 
 ### Updating with the server
 
-Call `feather sync` to synchronize all local data with the server (read articles, new articles from the server, etc.).
+Run `feather sync` to synchronize all local data with the server. The synchronization is done in two parts:
 
-`feather daemon`
+- `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.
 
 ### Configuration
 
-After changing the configuration, you can call `feather regenerate` to regenerate all local files with the new configuration (to reflect the changes in the HTML template, filenames, etc.).
+Feather will try to load the configuration from the file `config.toml` by default. A lot of things can be configured, see [the default configuration file](src/feather/config.default.toml) for details. Most configuration options can also be set using environment variables - this is also detailed in the default configuration file ([here's another link if your mouse is too far from the previous one](src/feather/config.default.toml)).
 
-`feather clear-data`
+If you already have local data but have changed configuration that affect how files are generated (like the HTML or filename templates), you can call `feather regenerate` to regenerate all local files with the new configuration.
+
+If you changed to another remote server or if you somehow messed up your local files, you can also call `feather clear-data` to nuke all local data, likely followed by a full synchronization using `feather sync`.
 
 ### Layer other things on top
 
-#### Syncthing
+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:
 
-#### Processing with scripts
+- 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.
 
 ## Installation
 
 ### Docker
 
+TODO
+
 `docker run -d -v ./config.toml:/feather/config.toml -v feather-data:/feather/data -v ./reader:/feather/reader --name feather feather daemon`
 
+`docker exec feather feather sync`
+
+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.
+
 ### Raw
 
-You need Python 3.12 or newer. Then pip it up, as the kids say.
+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).
 
-`uv 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)[#usage] chapter. Although I personally use uv, so I'd just run `uv sync` and then `uv run feather sync` to run feather.
+
+### 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:
+
+#### Tiny Tiny RSS
+
+```toml
+[server]
+api = "ttrss"
+url = "https://ttrss.example.com"
+user = "rsslad"
+password = "hunter2"
+
+[datetime]
+timezone = "Europe/Bucharest"
+```
+
+#### Google Reader API (FreshRSS, Miniflux, and others)
+
+```toml
+[server]
+api = "googlereader"
+url = "https://freshrss.example.com/api/greader.php"
+user = "rsslad"
+password = "hunter2"
+
+[datetime]
+timezone = "Europe/Bucharest"
+```
+
+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
+
 ### Why
 
 ### Name
@@ -71,6 +161,7 @@ before publishing:
 - [ ] Share the fun somewhere
 - [ ] Test with FreshRSS
     - [ ] Feed & category order for googlereader ??
+- [ ] Detect offline mode
 
 "i'll look into it later":
 

src/feather/config.default.toml

@@ -1,6 +1,6 @@
 # Feather default configuration file.
 # You can overwrite any of these values by either:
-# - creating a config.toml file containing your user configuration. You can choose another filename by setting the CONFIG_PATH environment variable.
+# - creating a config.toml file containing your user configuration. You can choose to load the configuration file from somewhere else by setting the CONFIG_PATH environment variable.
 # - setting environment variables for the values you want to overwrite (the environment variable name for each value can be found in the comments below).
 
 [server]
@@ -28,10 +28,10 @@ articles_per_request = 0
 only_sync_unread_articles = true
 
 [directories]
-# Directory path where the internal feather data will be stored.
+# Data directory: path where the internal feather data will be stored.
 # Can be set through the environment variable DIRECTORIES_DATA.
 data = "data"
-# Directory path where the user-facing files will be stored.
+# Reader directory: path where the user-facing files (category directories, article files) will be stored.
 # Can be set through the environment variable DIRECTORIES_READER.
 reader = "reader"
 
@@ -109,7 +109,7 @@ article_template = '''
 # Can be set through the environment variable HTML_FILENAME_TEMPLATE.
 filename_template = "[{{ feed_title }}]\t{{ title }} ({{ published }}).html"
 # Category directory name template for generated HTML files.
-# Fields availables:
+# Fields available:
 # - id: category id (str | int)
 # - title: category name (str)
 # - parents: list of parent categories (list[Category])