docs: Document core concepts

Change-Id: I6a6a6964d6bded229cd640463eaac70fd52df233

docs/modules/ROOT/pages/core/vfs.adoc

@@ -0,0 +1,54 @@
+= The Zilch Virtual Filesystem
+:page-pagination:
+
+In many places, it's necessary to build up a structure of files and
+directories. These structures are a subset of e.g. a project's source code. To
+make these, Zilch has a `vfs` record.
+
+Core Zilch can create a VFS from two sources: an on-disk directory, as well as
+a Nix store path:
+
+[,scheme,line-comment=;]
+----
+(vfs-from-directory "/home/puck/example")
+;; #<zilch.vfs#<vfs>>
+
+(define example-vfs
+ (vfs-from-store
+  (zdir "zero" (zsymlink "/dev/zero")))
+;; #<zilch.vfs#<vfs>>
+----
+
+These VFSes can be read out using `vfs-contents`:
+
+[,scheme,line-comment=;]
+----
+(mapping->alist
+ (vfs-contents example-vfs))
+;; ((("" . "zero")
+;;   . #<z-symlink -> "/dev/zero">))
+----
+
+VFS records store their contents as an SRFI 146 mapping, with a pair
+`(dir . name)` as key, and the store path (or zexpr) to point at as its value.
+Directories are indicated by the directory itself having a `'directory` symbol
+as contents; these markers are used during serialization.
+
+`(zilch vfs)` contains a series of helpers to make standard changes to the
+filesystem; such as filtering, and reading subtrees.
+
+== Serializing virtual filesystems to the store
+
+When a virtual filesystem is written to the store using `vfs-to-store`, a
+xref:generated:zilch.file.adoc[`(zilch file)`]-based structure is created,
+which can then be ``zexp-unquote``d safely inside a `zexp`. An important caveat
+to this, however, is that the created structure uses symlinks to every file in
+the vfs, rather than copying. This is chosen to both limit the expense of
+copying the contents of a large file to the store when many VFSes contain it,
+and a logistical limitation in the way Zilch interacts with Nix. It's possible
+this restriction will be lifted in the future.
+
+== Language-specific
+
+Zilch's Go support has a special handler that can create a VFS from a `go.sum`
+line. See the xref:go/library.adoc#vfs[Go] documentation for this procedure.