feat(stdlib): add Fs.* / Path.* / Mime.* — filesystem, paths, content types (#10)

A cohesive filesystem & IO library — the foundation for saves, config, mods, and
asset loading — wrapping the bare file_* builtins into one safe, ergonomic API a
non-expert can use without touching a file descriptor or a byte buffer.

  Path.*  join / dir / base / ext / stem / normalize   (pure lexical string ops)
  Fs.*    exists / is_dir / read_text / write_text / append_text / remove /
          size / mkdir / copy / list
  Mime.*  of (extension table) / sniff (magic bytes: PNG/JPEG/GIF/PDF)

Pure string IR for Path.*; libc (fopen/access/mkdir/rename/opendir…) for Fs.*;
C-free, emitted on demand (g_uses_fsrt). Safety and determinism baked in:
- write_text and copy are atomic (write a temp file, then rename over the target)
  so a crash mid-write never corrupts the previous file;
- mkdir creates parents (mkdir -p);
- list is sorted for a stable, reproducible directory walk;
- fallible calls return values (null / false / -1), never crashes — ready for a
  first-class try/else when the error-handling work lands.

Complements Os.* (#21): Os supplies per-user locations, Fs the operations. v1
targets the native macOS/BSD filesystem with "/" separators; Windows separators,
a sandboxed wasm virtual FS, recursive directory copy, and richer magic-byte
sniffing are documented follow-ups.

- examples/library/fs.ludic: 32 assertions across pure Path ops (incl. normalize
  resolving ./ .. and duplicate slashes), a real create/read/append/copy/list/
  remove cycle under build/, and Mime by-extension + by-magic (GIF signature vs a
  .bin extension). Wired into `x test` (now 56 passed).
- docs: new Path, Fs, and Mime sections + 18 per-symbol pages; inventory updated;
  every fence passes check-docs; site builds via docgen.
- seed regenerated; `x bootstrap-cfree` fixpoint holds.

Closes #10

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

docs/language/fs/_section.md

@@ -0,0 +1,11 @@
+---
+id: fs
+title: Fs
+order: 6
+---
+
+The filesystem, wrapped into one safe, ergonomic API — no file descriptors, no byte buffers, no half-written files. The foundation for saves, config, mods, and asset loading: read and write whole files as text, check existence, make directories, copy, and list a folder. The bare <code>file_*</code> builtins remain underneath for streaming; <code>Fs.*</code> is the everyday layer.
+
+Fallible calls surface failure as a value — <code>null</code>, <code>false</code>, or <code>-1</code> — that you branch on, never a crash (a first-class <code>try/else</code> lands with the error-handling work). Writes are atomic (written to a temporary file and renamed into place), so a crash mid-write never corrupts the previous file. <a href="fs-list"><code>list</code></a> returns entries sorted, so a directory walk is reproducible across runs and platforms.
+
+Paths are <code>/</code>-separated over the native (macOS/BSD) filesystem — the fully supported target today; a sandboxed virtual filesystem for wasm and recursive directory copy are follow-ups. Text helpers are UTF-8 (they pair with <a href="ns-Unicode"><code>Unicode</code></a>); use <a href="ns-Path"><code>Path</code></a> to build the paths and <a href="ns-Os"><code>Os</code></a> for per-user locations.

docs/language/fs/fs-append_text.md

@@ -0,0 +1,26 @@
+---
+id: fs-append_text
+name: Fs.append_text
+category: fs
+kind: namespace-method
+tokens: Fs.append_text
+sig: Fs.append_text(p, s) -> bool
+tip: Append a string to a file.
+order: 5
+ns: Fs
+member: append_text
+---
+
+Appends a string to the end of a file, creating it if necessary. Returns <code>true</code> on success. Handy for logs and event journals.
+
+Parameters:
+- `p` — the path
+- `s` — the string to append
+
+```ludic
+program AppendText {
+  entry {
+    if Fs.append_text("run.log", "started\n") { print(1) }
+  }
+}
+```

docs/language/fs/fs-copy.md

@@ -0,0 +1,26 @@
+---
+id: fs-copy
+name: Fs.copy
+category: fs
+kind: namespace-method
+tokens: Fs.copy
+sig: Fs.copy(src, dst) -> bool
+tip: Copy a file byte-for-byte.
+order: 9
+ns: Fs
+member: copy
+---
+
+Copies a file's bytes to a new path (atomically at the destination), returning <code>true</code> on success. Binary-safe, so it works for assets as well as text. Copying directories is a follow-up.
+
+Parameters:
+- `src` — the source path
+- `dst` — the destination path
+
+```ludic
+program Copy {
+  entry {
+    if Fs.copy("saves/slot1.json", "saves/slot1.bak") { print(1) }
+  }
+}
+```

docs/language/fs/fs-exists.md

@@ -0,0 +1,25 @@
+---
+id: fs-exists
+name: Fs.exists
+category: fs
+kind: namespace-method
+tokens: Fs.exists
+sig: Fs.exists(p) -> bool
+tip: Does a path exist?
+order: 1
+ns: Fs
+member: exists
+---
+
+Returns whether anything (file or directory) exists at the path. A cheap existence check before reading or writing.
+
+Parameters:
+- `p` — the path to test
+
+```ludic
+program Exists {
+  entry {
+    if Fs.exists("settings.ini") { print(1) } else { print(0) }
+  }
+}
+```

docs/language/fs/fs-is_dir.md

@@ -0,0 +1,25 @@
+---
+id: fs-is_dir
+name: Fs.is_dir
+category: fs
+kind: namespace-method
+tokens: Fs.is_dir
+sig: Fs.is_dir(p) -> bool
+tip: Is a path a directory?
+order: 2
+ns: Fs
+member: is_dir
+---
+
+Returns whether the path exists and is a directory (as opposed to a file). Useful when walking a tree or deciding whether to recurse.
+
+Parameters:
+- `p` — the path to test
+
+```ludic
+program IsDir {
+  entry {
+    if Fs.is_dir("mods") { print(1) } else { print(0) }
+  }
+}
+```

docs/language/fs/fs-list.md

@@ -0,0 +1,27 @@
+---
+id: fs-list
+name: Fs.list
+category: fs
+kind: namespace-method
+tokens: Fs.list
+sig: Fs.list(dir) -> []string
+tip: Directory entries, sorted.
+order: 10
+ns: Fs
+member: list
+---
+
+Returns the names of the entries in a directory (excluding <code>.</code> and <code>..</code>), sorted ascending for a stable, reproducible order — important for deterministic mod loading. Names are relative; combine with <a href="path-join"><code>Path.join</code></a> for full paths.
+
+Parameters:
+- `dir` — the directory to list
+
+```ludic
+program List {
+  entry {
+    let names = Fs.list("mods")
+    var i = 0
+    while i < len(names) { print(len(names[i])); i = i + 1 }
+  }
+}
+```

docs/language/fs/fs-mkdir.md

@@ -0,0 +1,25 @@
+---
+id: fs-mkdir
+name: Fs.mkdir
+category: fs
+kind: namespace-method
+tokens: Fs.mkdir
+sig: Fs.mkdir(p) -> bool
+tip: Create a directory and its parents.
+order: 8
+ns: Fs
+member: mkdir
+---
+
+Creates a directory, including any missing parent directories (like <code>mkdir -p</code>). Returns <code>true</code> if the directory exists afterwards, so calling it on an existing directory is fine.
+
+Parameters:
+- `p` — the directory path to create
+
+```ludic
+program Mkdir {
+  entry {
+    if Fs.mkdir("saves/campaign") { print(1) }
+  }
+}
+```

docs/language/fs/fs-read_text.md

@@ -0,0 +1,28 @@
+---
+id: fs-read_text
+name: Fs.read_text
+category: fs
+kind: namespace-method
+tokens: Fs.read_text
+sig: Fs.read_text(p) -> string
+tip: Read a whole file as a string.
+order: 3
+ns: Fs
+member: read_text
+---
+
+Reads an entire file into a string (UTF-8 text), or returns <code>null</code> when it cannot be opened — check for <code>null</code> rather than assuming success. For a missing or unreadable save, fall back to a fresh default.
+
+Parameters:
+- `p` — the path to read
+
+```ludic
+program ReadText {
+  entry {
+    if Fs.exists("saves/slot1.json") {
+      let text = Fs.read_text("saves/slot1.json")
+      print(len(text))
+    }
+  }
+}
+```

docs/language/fs/fs-remove.md

@@ -0,0 +1,25 @@
+---
+id: fs-remove
+name: Fs.remove
+category: fs
+kind: namespace-method
+tokens: Fs.remove
+sig: Fs.remove(p) -> bool
+tip: Delete a file.
+order: 6
+ns: Fs
+member: remove
+---
+
+Deletes a file, returning <code>true</code> on success. Use it to clear a save slot or a temporary export.
+
+Parameters:
+- `p` — the path to delete
+
+```ludic
+program Remove {
+  entry {
+    if Fs.remove("saves/slot1.json") { print(1) } else { print(0) }
+  }
+}
+```

docs/language/fs/fs-size.md

@@ -0,0 +1,26 @@
+---
+id: fs-size
+name: Fs.size
+category: fs
+kind: namespace-method
+tokens: Fs.size
+sig: Fs.size(p) -> int
+tip: File size in bytes.
+order: 7
+ns: Fs
+member: size
+---
+
+Returns the size of a file in bytes, or <code>-1</code> if it cannot be opened. Useful for progress bars or sanity checks before loading.
+
+Parameters:
+- `p` — the path
+
+```ludic
+program Size {
+  entry {
+    let n = Fs.size("assets/level1.dat")
+    if n >= 0 { print(n) }
+  }
+}
+```

docs/language/fs/fs-write_text.md

@@ -0,0 +1,26 @@
+---
+id: fs-write_text
+name: Fs.write_text
+category: fs
+kind: namespace-method
+tokens: Fs.write_text
+sig: Fs.write_text(p, s) -> bool
+tip: Write a string to a file (atomically).
+order: 4
+ns: Fs
+member: write_text
+---
+
+Writes a string to a file, replacing any existing contents. The write is atomic — the bytes go to a temporary file that is renamed into place — so an interrupted write never corrupts the previous file. Returns <code>true</code> on success.
+
+Parameters:
+- `p` — the path to write
+- `s` — the string contents
+
+```ludic
+program WriteText {
+  entry {
+    if Fs.write_text("settings.ini", "fullscreen=1") { print(1) }
+  }
+}
+```

docs/language/mime/_section.md

@@ -0,0 +1,9 @@
+---
+id: mime
+title: Mime
+order: 6
+---
+
+Content-type detection for assets and downloads: map a filename to its MIME type, or refine the guess by peeking at a file's leading bytes. Useful for deciding how to load a dropped-in mod file, labelling an export, or picking a decoder.
+
+<a href="mime-of"><code>of</code></a> is a pure lookup by extension; <a href="mime-sniff"><code>sniff</code></a> reads the first bytes and recognises a few well-known signatures (PNG, JPEG, GIF, PDF), falling back to the extension when nothing matches. The extension table is deliberately compact and documented; richer magic-byte coverage is a follow-up.

docs/language/mime/mime-of.md

@@ -0,0 +1,25 @@
+---
+id: mime-of
+name: Mime.of
+category: mime
+kind: namespace-method
+tokens: Mime.of
+sig: Mime.of(path) -> string
+tip: MIME type from a file extension.
+order: 1
+ns: Mime
+member: of
+---
+
+Returns the MIME type inferred from the file extension (e.g. <code>hero.png</code> → <code>image/png</code>), or <code>application/octet-stream</code> for an unknown extension. A pure lookup — it does not open the file.
+
+Parameters:
+- `path` — the path or filename
+
+```ludic
+program MimeOf {
+  entry {
+    if Mime.of("hero.png") == "image/png" { print(1) }
+  }
+}
+```

docs/language/mime/mime-sniff.md

@@ -0,0 +1,26 @@
+---
+id: mime-sniff
+name: Mime.sniff
+category: mime
+kind: namespace-method
+tokens: Mime.sniff
+sig: Mime.sniff(path) -> string
+tip: MIME type refined by magic bytes.
+order: 2
+ns: Mime
+member: sniff
+---
+
+Reads the file's leading bytes and recognises well-known signatures (PNG, JPEG, GIF, PDF), so a mislabelled or extension-less file is still identified. Falls back to <a href="mime-of"><code>Mime.of</code></a> when no signature matches or the file cannot be read.
+
+Parameters:
+- `path` — the path to inspect
+
+```ludic
+program MimeSniff {
+  entry {
+    let kind = Mime.sniff("download.bin")
+    print(len(kind))
+  }
+}
+```

docs/language/path/_section.md

@@ -0,0 +1,9 @@
+---
+id: path
+title: Path
+order: 6
+---
+
+Path manipulation as pure string operations — no disk access, no allocation surprises, just the joining and splitting every save system, mod loader, and asset pipeline needs. Separate a filename from its folder, get an extension, join segments without worrying about doubled or missing separators, and collapse <code>.</code>/<code>..</code>/duplicate slashes into a canonical form.
+
+Paths use <code>/</code> as the separator, matching the native (macOS/BSD) filesystem — the fully supported target today; Windows-style separators are a follow-up. Pair these with <a href="ns-Os"><code>Os</code></a> (which supplies per-user directory *locations*) and <a href="ns-Fs"><code>Fs</code></a> (which does the actual reading and writing).

docs/language/path/path-base.md

@@ -0,0 +1,25 @@
+---
+id: path-base
+name: Path.base
+category: path
+kind: namespace-method
+tokens: Path.base
+sig: Path.base(p) -> string
+tip: The final component of a path.
+order: 3
+ns: Path
+member: base
+---
+
+Returns the final component — the file or last directory name — after the last <code>/</code>. A path with no separator is returned unchanged. The complement of <a href="path-dir"><code>dir</code></a>.
+
+Parameters:
+- `p` — the path
+
+```ludic
+program Base {
+  entry {
+    if Path.base("mods/foo/data.json") == "data.json" { print(1) }
+  }
+}
+```

docs/language/path/path-dir.md

@@ -0,0 +1,25 @@
+---
+id: path-dir
+name: Path.dir
+category: path
+kind: namespace-method
+tokens: Path.dir
+sig: Path.dir(p) -> string
+tip: The directory part of a path.
+order: 2
+ns: Path
+member: dir
+---
+
+Returns everything before the last <code>/</code> — the containing directory. A path with no separator yields <code>"."</code> (the current directory); the root <code>/</code> stays <code>/</code>.
+
+Parameters:
+- `p` — the path
+
+```ludic
+program Dir {
+  entry {
+    if Path.dir("mods/foo/data.json") == "mods/foo" { print(1) }
+  }
+}
+```

docs/language/path/path-ext.md

@@ -0,0 +1,25 @@
+---
+id: path-ext
+name: Path.ext
+category: path
+kind: namespace-method
+tokens: Path.ext
+sig: Path.ext(p) -> string
+tip: The file extension, including the dot.
+order: 4
+ns: Path
+member: ext
+---
+
+Returns the extension of the final component, including the leading dot (e.g. <code>".json"</code>), or the empty string when there is none. A leading-dot name (a dotfile like <code>.gitignore</code>) has no extension.
+
+Parameters:
+- `p` — the path
+
+```ludic
+program Ext {
+  entry {
+    if Path.ext("hero.png") == ".png" { print(1) }
+  }
+}
+```

docs/language/path/path-join.md

@@ -0,0 +1,26 @@
+---
+id: path-join
+name: Path.join
+category: path
+kind: namespace-method
+tokens: Path.join
+sig: Path.join(a, b) -> string
+tip: Join two path segments with the separator.
+order: 1
+ns: Path
+member: join
+---
+
+Joins two path segments with a single <code>/</code>, inserting one only when needed (so <code>join("a/", "b")</code> and <code>join("a", "b")</code> both give <code>a/b</code>). If <code>b</code> is absolute it wins; if either side is empty the other is returned.
+
+Parameters:
+- `a` — the leading path
+- `b` — the trailing path or filename
+
+```ludic
+program Join {
+  entry {
+    if Path.join("mods", "foo.ludic") == "mods/foo.ludic" { print(1) }
+  }
+}
+```

docs/language/path/path-normalize.md

@@ -0,0 +1,25 @@
+---
+id: path-normalize
+name: Path.normalize
+category: path
+kind: namespace-method
+tokens: Path.normalize
+sig: Path.normalize(p) -> string
+tip: Collapse . / .. / duplicate separators.
+order: 6
+ns: Path
+member: normalize
+---
+
+Canonicalizes a path lexically (without touching disk): duplicate separators collapse, <code>.</code> segments drop, and <code>..</code> pops the preceding segment. An absolute path never rises above its root. The result is stable, so it is a good key for comparing or sandboxing paths.
+
+Parameters:
+- `p` — the path
+
+```ludic
+program Normalize {
+  entry {
+    if Path.normalize("a/./b/../c") == "a/c" { print(1) }
+  }
+}
+```

docs/language/path/path-stem.md

@@ -0,0 +1,25 @@
+---
+id: path-stem
+name: Path.stem
+category: path
+kind: namespace-method
+tokens: Path.stem
+sig: Path.stem(p) -> string
+tip: The final component without its extension.
+order: 5
+ns: Path
+member: stem
+---
+
+Returns the final component with its extension removed — the "stem". Useful for deriving an id or a sibling filename. <code>stem("mods/foo/data.json")</code> is <code>"data"</code>.
+
+Parameters:
+- `p` — the path
+
+```ludic
+program Stem {
+  entry {
+    if Path.stem("data.json") == "data" { print(1) }
+  }
+}
+```