plan 10: docs (-n, README version and scope, trash identity, --json U+FFFD, limitations, changelog)

1 files changed, 16 insertions, 4 deletions

diff --git a/docs/design.md b/docs/design.md
index 07728fc..28c7c80 100644
--- a/docs/design.md
+++ b/docs/design.md
@@ -433,6 +433,11 @@ while evaluating this rule. Tests of equal cost keep their written order, so
 every such `name` test in it has at least N groups, and a rule that uses
 `{N}` with no `name` test at all.
 
+Known limitation: a `name` test matches the folded name when `fold` is on
+(the default), and its captures are taken from that same text, so `{1}`
+loses diacritics: `(name "^(.+)-faktura")` on `Łódź-faktura.pdf` makes `{1}`
+`Lodz`. Set `(fold no)` in the rule to keep them.
+
 ### 7.4 Conflicts
 
 When the target already exists:
@@ -661,7 +666,7 @@ Reversals, last step first within each file:
 |---|---|---|
 | move, rename | move `dst` back to `src` | `dst` missing or changed (size/mtime), or `src` now exists |
 | copy | move `dst` to Trash | `dst` missing or changed |
-| trash | restore from Trash, remove the `.trashinfo` | the Trash entry is gone, or `src` now exists |
+| trash | restore from Trash, remove the `.trashinfo` | the Trash entry is gone, is not the file this run trashed (size/mtime), or its `.trashinfo` now records another original path; or `src` now exists |
 | displace | restore the displaced target from Trash | as above |
 | mkdir | remove the directory if empty | not empty |
 | delete permanent | none; reported as not undoable | always |
@@ -672,6 +677,11 @@ not empty is the exception: it means another file still lives there, not that
 the world changed under us, so that refusal is recorded and the rest of the
 file's reversal proceeds. Undo runs are logged like any other run.
 
+Known limitation: a reversal recreates the directories it needs to move a
+file back and removes them again only when the file's reversal completes.
+An undo interrupted or failed after recreating one, and never finished for
+that file, leaves it behind, empty.
+
 ## 11. Command line
 
 ```
@@ -685,16 +695,18 @@ krino log [-n N]            list recent runs
 krino undo [RUN]            reverse a run (default: the last one)
 
 -y            apply without asking
--n            dry run: show the plan, change no file (the keyword cache may be refreshed)
+-n            dry run: show the plan, change no file (krino's empty state directory
+              may be created, the keyword cache refreshed)
 -v            also list unmatched, ignored and busy files; full match reasons
---json        with -n: the plan as JSON (format unstable before 1.0)
+--json        with -n: the plan as JSON (format unstable before 1.0); invalid
+              UTF-8 in a name becomes U+FFFD
 -c FILE       use FILE instead of ~/.config/krino/krino.conf
 --no-color    never colour the output, as when NO_COLOR is set
 -P, --no-pager  print the plan straight out, never through the pager
 --min-age D   for this run, every directory's min-age is D (0, 30s, 1d);
               sorting and explain only; a future modification time counts as age 0
 -h, --help    help
---version     print "krino 0.0.1"
+--version     print "krino VERSION"
 ```
 
 Exit status: 0 success, including nothing to do and everything declined;