Update documentation

README.adoc

@@ -5,15 +5,18 @@ Dawn
 'Dawn' is a multiplatform colour-managed image browser, with very high standards
 for fidelity and responsivity.
 
+See link:docs/why.adoc[Why you need a better image viewer]
+if you don't get this.
+
 image::docs/dn.webp["Screenshot of both the browser and the viewer"]
 
 Design-wise, the project is an amalgamation of
 https://git.janouch.name/p/fiv[older efforts] and
 https://git.janouch.name/p/gallery[desires].
-Right now, we've mostly reached our first milestone, and we're cleaning up
-AI-accelerated mess before we can afford to continue making large steps.
+Right now, we've mostly reached our first milestone, and we're mostly cleaning
+up after rapid development before we can afford to continue making large steps.
 
-The project comes with a promise of basic maintenance.
+The project comes with a maintenance guarantee.
 Also see link:docs/plan.adoc[Plan],
 and a detailed link:docs/rationale.adoc[Rationale].
 

docs/plan.adoc

@@ -26,8 +26,9 @@ Milestones
  - [x] Plain out replace https://git.janouch.name/p/fiv[fiv]
        (excluding GVfs, printing, reverse search, JPEG cropper)
     * [ ] Debug, clean up, branch a stable version
- - [ ] Integrate filesystem scanning, automatic tagging, browsing from
-       https://git.janouch.name/p/gallery[gallery]
+ - [ ] Become capable of browsing
+       https://git.janouch.name/p/gallery[gallery] databases
+ - [ ] Plain out replace https://git.janouch.name/p/gallery[gallery]
     * This will replace _wide-thumbnail-spec_ with an internal database,
       plus platform-based thumbnailers as backup.
     * [ ] Debug, clean up, branch a stable version

docs/rationale.adoc

@@ -25,7 +25,7 @@ problems, at a significant cost.
 
 Over time, I've noticed I'm becoming more and more exasperated.  Perhaps as
 the problems become more complex.  Perhaps as I'm shifting to believing
-that it can read my mind.
+that the models can read my mind.
 
 Constraints
 -----------
@@ -106,7 +106,7 @@ be useful.  (I've since checked that a GDK 4 path is impossible.)
 Its largest dependency is ICU, which we don't strictly require, and Qt can
 actually be built without it if needed for smaller standalone packages.
 
-Qt is pretty nuke-able, and the minimal platform abstraction layer it provides
+Qt is somewhat nuke-able, and the minimal platform abstraction layer it provides
 _still_ creates problems of its own anyway.  It's likely that we'll get rid of
 it eventually, whether due to licencing or otherwise.
 

docs/why.adoc

@@ -0,0 +1,27 @@
+Why you need a better image viewer
+==================================
+
+Wide gamuts
+-----------
+// TODO(p): show the CIE picture.
+
+Today's displays commonly have colour gamuts superpassing sRGB.
+
+Bit depth
+---------
+// TODO(p): show emphasised banding.
+
+Today's displays can often display more than 16.7 million colours.
+
+Gamma correctness
+-----------------
+// TODO(p): show artifacts; architecture is enough.
+
+Zooming in or out requires correct colour handling.
+Even an iPhone fails at this.
+
+Scaling
+-------
+// TODO(p): show extreme close-ups.
+
+You can do better than use bilinear scaling.