Document every public function; fix a real gap the audit found

Cross-checked every function declared in include/packfs.h against
nm -D libpackfs.so.0 as the starting point for a full documentation
pass, per the request to document literally everything rather than
just the parts already covered.

That check found a genuine bug, not just a documentation gap:
backend_pack_new was declared in the public header and named in
CLAUDE.md's architecture map, but never implemented in src/pack.c —
any caller would fail at link time. Implemented it as a standalone,
read-only `pack` Backend (every mutating call returns VFS_ERR_PERM,
consistent with concept.md Section 2.1 listing `pack` as its own
backend kind distinct from the overlay), covered it with a new test
case, and verified it under -fsanitize=undefined per CLAUDE.md's
sanitizer rule.

Added a doc comment to every previously-undocumented function and
struct field in packfs.h and internal.h (vfs_open/read/write/close/
stat/readdir/mkdir/unlink/rename, every upper_* structural/content
function, pfs_dir_*, pfs_fnv1a64, PackIndexEntry/Pack fields). Updated
README and CLAUDE.md to mention backend_pack_new and to stop gesturing
at zip/tar as though import/export exists.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UqJpkdJ6Njnt1pw3CbghzB

README.md

@@ -1,10 +1,9 @@
 # PackFS
 
 A statically linked, in-process virtual file system for C. PackFS treats a
-shipped file tree as an immutable **pack** image, derives writability from a
-`mem` or `dir` upper layer through a copy-on-write overlay, and confines
-`zip`/`tar` to import/export roles rather than treating either as a live,
-writable store.
+shipped file tree as an immutable **pack** image and derives writability
+from a `mem` or `dir` upper layer through a copy-on-write overlay. `zip` and
+`tar` are not part of this project and never will be — see "Status" below.
 
 The full design rationale — why this shape, what alternatives were rejected,
 and the concurrency, path-containment, and integrity models this
@@ -17,9 +16,11 @@ followed from it, not a restatement of the rationale.
 
 This is an initial, partial implementation of the spec, not a complete one.
 
-**Implemented and tested:** mount table, `mem`/`dir`/`pack`/overlay backends,
-copy-up, whiteouts, compaction, an append journal, path containment, and
-pack integrity validation.
+**Implemented and tested:** mount table, `mem`/`dir`/`pack`/overlay backends
+(including the standalone read-only `pack` backend, `backend_pack_new` —
+every mutating call against it returns `VFS_ERR_PERM`), copy-up, whiteouts,
+compaction, an append journal, path containment, and pack integrity
+validation.
 
 **Will never be built, by explicit project decision:** the `zip` (miniz) and
 `tar` (USTAR) import/export backends. `concept.md` Section 11 recommends
@@ -110,6 +111,17 @@ vfs_mount(v, "/data", dir);
  * ".." and symlink escapes are rejected, not merely discouraged. */
 ```
 
+A shipped pack mounted read-only, no writable layer at all:
+
+```c
+int perr = 0;
+Backend *ro = backend_pack_new("assets.pack", &perr);
+vfs_mount(v, "/assets", ro);
+/* vfs_write, vfs_mkdir, vfs_unlink, vfs_rename, vfs_sync against anything
+ * under /assets all return VFS_ERR_PERM; there is no upper layer to
+ * absorb a write into. */
+```
+
 ## API
 
 The public API is [`include/packfs.h`](include/packfs.h); every function and
@@ -117,8 +129,12 @@ struct is documented there with a pointer to the `concept.md` section that
 specifies its behavior. In outline:
 
 - `vfs_new` / `vfs_free` — a `Vfs` owns a mount table, nothing else.
-- `backend_mem_new` / `backend_dir_new` / `backend_overlay_new` — construct a
-  backend; `vfs_mount`/`vfs_unmount` attach or detach it at a path prefix.
+- `backend_mem_new` / `backend_dir_new` / `backend_pack_new` /
+  `backend_overlay_new` — construct a backend; `vfs_mount`/`vfs_unmount`
+  attach or detach it at a path prefix. `backend_pack_new` mounts a pack
+  read-only, with no writable upper layer at all — every mutating call
+  against it returns `VFS_ERR_PERM`; wrap the same pack in
+  `backend_overlay_new` instead when writability is wanted.
 - `vfs_open` / `vfs_read` / `vfs_write` / `vfs_close` — file I/O.
 - `vfs_stat` / `vfs_readdir` / `vfs_mkdir` / `vfs_unlink` / `vfs_rename` —
   metadata and namespace operations.