Start documenting the file transfer kitten

docs/kittens/remote_file.rst

@@ -22,12 +22,15 @@ transferred to the remote computer. Note that this happens without needing
 to install *any* special software on the server, beyond ``ls`` that supports
 hyperlinks.
 
+.. seealso:: See the :doc:`transfer` kitten
+
 .. versionadded:: 0.19.0
 
 .. note::
    Nested SSH sessions are not supported. The kitten will always try to copy
    remote files from the first SSH host. This is because there is no way for
-   |kitty| to detect and follow a nested SSH session robustly.
+   |kitty| to detect and follow a nested SSH session robustly. Use the
+   :doc:`transfer` kitten for such situations.
 
 .. note::
    If you have not setup automatic password-less SSH access, then, when

docs/kittens/transfer.rst

@@ -0,0 +1,26 @@
+Transfer files
+================
+
+.. warning::
+   This kitten is currently experimental, use with care.
+
+Transfer files to and from remote computers over the ``TTY`` device itself.
+This means that file transfer works over nested SSH sessions, serial links,
+etc. Anywhere you have a terminal device, you can transfer files.
+
+This kitten support transferring entire directory trees, preserving soft and
+hard links, file permissions and times, etc. It even supports the `rsync
+<https://en.wikipedia.org/wiki/Rsync>`_ protocol to transfer only changes to
+large files and to automatically resume interrupted transfers.
+
+.. seealso:: See the :doc:`remote_file` kitten
+
+.. note::
+   This kitten (which practically means kitty) must be installed on the remote
+   machine. If that is not possible you can use the :doc:`remote_file` kitten
+   instead. Or write your own script to use the underlying file transfer
+   protocol.
+
+.. versionadded:: 0.24.0
+
+.. include:: ../generated/cli-kitten-transfer.rst