Add further doc about long name and crash.

README.md

@@ -104,3 +104,10 @@ See [here](docs/design.md).
 If you store `securefs` encrypted files on iCloud Drive, it might cause Spotlight Search on iOS to stop working. It is a bug in iOS, not in `securefs`.
 
 To work around that bug, you can disable the indexing of _Files_ app in Settings -> Siri & Suggestions.
+
+## Crash resistance
+If `securefs` exits abnormally, or if the computer suddenly powers down, we have only the following guarantees (assuming the underlying filesystem isn't corrupted)
+
+1. Files not being written will never be corrupted.
+2. In lite format, the directory structure and file names will not be corrupted, unless the file name is a [long name](docs/long_name.md).
+3. In full format, the directory structure and file names may be corrupted, but the files themselves can be recovered even in this case.

docs/long_name.md

@@ -0,0 +1,17 @@
+# Long file name support
+
+In full format, each filename can be up to 255 bytes long (in UTF-8 encoding). This is in line with most filesystems.
+
+In lite format, each filename is encrypted by AES-SIV, and then converted by Base32. This means that a 143 bytes long filename will be transformed into a 255 bytes filename. Beyond that, the encrypted filename will exceed the maximum length on most filesystems.
+
+Originally this will cause an error, but starting on securefs 1.0.0, we introduce long name support feature.
+
+When filename length exceeds a predefined threshold (default: 128), it will be converted to an underlying filename by `Base32(Blake2b(name_master_key, filename))` plus three dots. Then this transformed name and the AES-SIV encrypted name will be stored in a per directory SQLite database. The database will be queried during `ls` call, and be updated when files are created, deleted or moved.
+
+This approach has some performance penalty, but given the rarity of such long filenames, the tradeoff should make sense for most people.
+
+## Migration
+For lite format repositories created before `securefs` 1.0.0, they do not support long file names, but this can be fixed.
+Run `securefs migrate-long-name` to perform the migration.
+
+With the long file name support, we've also changed how symbolic links are encrypted. As a result, migration can only happen if the repository does not include symbolic links.