Builtins are chips that link to a glossary generated from the registry, and the virtual filesystem is drawn as a tree

#word draws a builtin as a chip on the tag's ground over a rule (Look and
Exec in acme's look green and exec red), a <code class="word"> in HTML,
and links it to its entry in a new Builtins chapter wherever that
chapter is in the same output (the book, the site). The chapter is
drawn from docs/typ/builtins-tty.json and builtins-gui.json, which
`zig build builtins-json -Dplatform=tty|gui` writes from the registry
and the Help rows (src/builtins_json.zig, tools/gen_builtins_json.zig;
summaryOf in ninep/ctl.zig is now pub); style.typ merges them, marking
the window-only words. The doc steps refresh their build's file first,
and each build's unit-test fails when its file is stale. Everyday words
first (`everyday` in style.typ), then groups by leader prefix as Help
has them, then settings, the words with no path, debugging and
internals, and last an A-Z index of every word. `zig build book` joins
the doc steps.

#fstree draws a directory tree with its connectors, a description
column and links to the sections that document each file; reference.typ
draws the served tree with it, each pane, pty and column file on its
own line, and a test in config.zig checks it against ninep/tree.zig's
files both ways. The cheatsheet has a two-level version. On the site
the tree reads as `tree` text in w3m and wraps descriptions under the
names on a phone.

The site's tutor draws its B1, B2, B3 and 1-2 chords as mouse glyphs;
the landing credits Plan 9 and acme, as does the book's title page;
install.typ no longer lists the mirrors (the footer does).

Co-Authored-By: Claude Opus 5.5 <[email protected]>

4 files changed, 171 insertions, 2 deletions

diff --git a/src/builtins_json.zig b/src/builtins_json.zig
new file mode 100644
index 00000000..7f998388
--- /dev/null
+++ b/src/builtins_json.zig
@@ -0,0 +1,97 @@
+//! Every builtin as JSON, for the docs' glossary (docs/typ/builtins-tty.json
+//! and builtins-gui.json, a build's list each; style.typ merges them):
+//! the rows the `Help` builtin draws (pardes.builtin_rows: the leader path
+//! and the other shortcuts) with what /commands says of each word (its doc
+//! comment's first sentence, or a setting's doc). One source, so the
+//! glossary and Help cannot drift; the test below fails when the committed
+//! copy is stale, and `zig build builtins-json` rewrites it.
+const std = @import("std");
+const pardes = @import("pardes.zig");
+const builtins = @import("builtins.zig");
+const config = @import("config.zig");
+const ctl = @import("ninep/ctl.zig");
+
+fn str(w: *std.Io.Writer, s: []const u8) !void {
+    try w.writeByte('"');
+    for (s) |c| switch (c) {
+        '"' => try w.writeAll("\\\""),
+        '\\' => try w.writeAll("\\\\"),
+        '\n' => try w.writeAll("\\n"),
+        0...9, 11...0x1f => try w.print("\\u{x:0>4}", .{c}),
+        else => try w.writeByte(c),
+    };
+    try w.writeByte('"');
+}
+
+const Entry = struct { name: []const u8, row: usize };
+
+fn lessName(_: void, a: Entry, b: Entry) bool {
+    return std.mem.lessThan(u8, a.name, b.name);
+}
+
+pub fn write(w: *std.Io.Writer) !void {
+    var order: [pardes.builtin_rows.len]Entry = undefined;
+    for (pardes.builtin_rows, 0..) |row, i| order[i] = .{ .name = @tagName(row.cmd), .row = i };
+    std.mem.sort(Entry, &order, {}, lessName);
+    try w.writeAll("[\n");
+    for (order, 0..) |e, n| {
+        const row = pardes.builtin_rows[e.row];
+        const b = row.cmd;
+        const name = @tagName(b);
+        try w.writeAll("  {\"name\": ");
+        try str(w, name);
+        try w.writeAll(", \"leader\": ");
+        if (row.path) |p| {
+            try w.writeAll("\"SPC");
+            for (p) |c| try w.print(" {c}", .{c});
+            try w.writeByte('"');
+        } else try w.writeAll("null");
+        // Help's line ends in the other shortcuts, after the name's column.
+        try w.writeAll(", \"also\": [");
+        const at = std.mem.indexOf(u8, row.line, name).? + name.len;
+        const rest = std.mem.trim(u8, row.line[at..], " ");
+        var parts = std.mem.splitSequence(u8, rest, ", ");
+        var first = true;
+        while (parts.next()) |part| if (part.len > 0) {
+            if (!first) try w.writeAll(", ");
+            first = false;
+            try str(w, part);
+        };
+        try w.writeAll("], \"arg\": ");
+        try w.writeAll(if (builtins.registry.takesArg(b)) "true" else "false");
+        try w.writeAll(", \"scope\": ");
+        try str(w, if (b == .Edit) "both" else if (builtins.registry.scope(b) == .session) "root" else "pane");
+        const setting = config.Runtime.find(name);
+        try w.writeAll(", \"setting\": ");
+        try w.writeAll(if (setting != null) "true" else "false");
+        try w.writeAll(", \"choices\": ");
+        if (setting) |s| if (config.Runtime.choices(s.action)) |v| try str(w, v) else try w.writeAll("null") else try w.writeAll("null");
+        var buf: [2048]u8 = undefined;
+        const doc = if (setting) |s| s.doc else ctl.summaryOf(name, &buf);
+        try w.writeAll(", \"doc\": ");
+        try str(w, doc);
+        try w.writeAll(if (n + 1 < order.len) "},\n" else "}\n");
+    }
+    try w.writeAll("]\n");
+}
+
+test "docs/typ/builtins-<platform>.json is what the registry says now" {
+    // a terminal build checks its file, a window build its own
+    const file = switch (pardes.platform) {
+        .tty => "builtins-tty.json",
+        .gui => "builtins-gui.json",
+        else => return error.SkipZigTest,
+    };
+    const gpa = std.testing.allocator;
+    var out: std.Io.Writer.Allocating = .init(gpa);
+    defer out.deinit();
+    try write(&out.writer);
+    var dir = try std.Io.Dir.cwd().openDir(std.testing.io, @import("doc_typ").dir, .{});
+    defer dir.close(std.testing.io);
+    const committed = try dir.readFileAlloc(std.testing.io, file, gpa, .limited(1 << 20));
+    defer gpa.free(committed);
+    if (!std.mem.eql(u8, committed, out.written())) {
+        std.debug.print("docs/typ/{s} is stale: run `zig build builtins-json -Dplatform={s} --prefix <dir>`\n", .{ file, @tagName(pardes.platform) });
+        return error.StaleBuiltinsJson;
+    }
+}
diff --git a/src/config.zig b/src/config.zig
index e9595a2a..f83e7945 100644
--- a/src/config.zig
+++ b/src/config.zig
@@ -2101,9 +2101,16 @@ const doc_typ = struct {
         }
     }
 
+    /// The other build's builtins (docs/typ/builtins-*.json), so the docs
+    /// may name a window-only word in a terminal build's test, and back.
+    var other_build: []const u8 = "";
+
     fn word(w: []const u8) bool {
         const name = w[0 .. std.mem.indexOfScalar(u8, w, '+') orelse w.len];
-        return std.meta.stringToEnum(Builtin, name) != null;
+        if (std.meta.stringToEnum(Builtin, name) != null) return true;
+        var buf: [96]u8 = undefined;
+        const needle = std.fmt.bufPrint(&buf, "{{\"name\": \"{s}\",", .{name}) catch return false;
+        return std.mem.indexOf(u8, other_build, needle) != null;
     }
 
     fn chord(tok: []const u8) ?Chord {
@@ -2195,6 +2202,10 @@ test "docs/typ names only words, keys and default tags that exist" {
     var dir = try std.Io.Dir.cwd().openDir(io, @import("doc_typ").dir, .{ .iterate = true });
     defer dir.close(io);
     var found: [3]std.ArrayList([]const u8) = @splat(.empty);
+    for ([_][]const u8{ "builtins-tty.json", "builtins-gui.json" }) |f| {
+        const text = dir.readFileAlloc(io, f, gpa, .limited(1 << 20)) catch continue;
+        doc_typ.other_build = try std.mem.concat(gpa, u8, &.{ doc_typ.other_build, text });
+    }
     var it = dir.iterate();
     while (try it.next(io)) |entry| if (entry.kind == .file and std.mem.endsWith(u8, entry.name, ".typ")) {
         const source = try dir.readFileAlloc(io, entry.name, gpa, .limited(1 << 20));
@@ -2331,3 +2342,61 @@ test "the tutor names only words, keys, paths and default tags that exist" {
         }
     }
 }
+
+test "reference.typ's #fstree is the tree the session serves, file for file" {
+    const tree = @import("ninep/tree.zig");
+    var arena: std.heap.ArenaAllocator = .init(std.testing.allocator);
+    defer arena.deinit();
+    const gpa = arena.allocator();
+    const io = std.testing.io;
+    var dir = try std.Io.Dir.cwd().openDir(io, @import("doc_typ").dir, .{});
+    defer dir.close(io);
+    const source = try dir.readFileAlloc(io, "reference.typ", gpa, .limited(1 << 20));
+    const open = "#fstree(```";
+    const start = (std.mem.indexOf(u8, source, open) orelse return error.NoFsTree) + open.len;
+    const end = std.mem.indexOfPos(u8, source, start, "```)") orelse return error.NoFsTree;
+
+    // what the reference draws: a path per line, from its indent
+    var drawn: std.StringArrayHashMapUnmanaged(void) = .empty;
+    var stack: [8][]const u8 = undefined;
+    var lines = std.mem.tokenizeScalar(u8, source[start..end], '\n');
+    while (lines.next()) |line| {
+        const body = std.mem.trimStart(u8, line, " ");
+        if (body.len == 0) continue;
+        const depth = (line.len - body.len) / 2;
+        const name = body[0 .. std.mem.indexOfScalar(u8, body, ' ') orelse body.len];
+        stack[depth] = name;
+        var path: std.ArrayList(u8) = .empty;
+        for (stack[0 .. depth + 1]) |part| try path.appendSlice(gpa, part);
+        try drawn.put(gpa, path.items, {});
+    }
+
+    // what the session serves: tree.zig's files, and fs.zig's os/ and src/
+    var served: std.StringArrayHashMapUnmanaged(void) = .empty;
+    for (std.enums.values(tree.TopFile)) |f| switch (f) {
+        .root => {},
+        .new => try served.put(gpa, "pane/new", {}),
+        else => try served.put(gpa, if (f.dir()) try std.fmt.allocPrint(gpa, "{s}/", .{f.fileName()}) else f.fileName(), {}),
+    };
+    try served.put(gpa, "os/", {});
+    try served.put(gpa, "src/", {});
+    try served.put(gpa, "pane/<n>/", {});
+    for (std.enums.values(tree.PaneFile)) |f| if (f != .dir) {
+        const under = if (f.inPty() and f != .pty) "pane/<n>/pty/" else "pane/<n>/";
+        try served.put(gpa, try std.fmt.allocPrint(gpa, "{s}{s}{s}", .{ under, f.fileName(), if (f.isDir()) "/" else "" }), {});
+    };
+    try served.put(gpa, "col/<n>/", {});
+    for (std.enums.values(tree.ColFile)) |f| if (f != .dir)
+        try served.put(gpa, try std.fmt.allocPrint(gpa, "col/<n>/{s}", .{f.fileName()}), {});
+
+    var drift = false;
+    for (served.keys()) |k| if (!drawn.contains(k)) {
+        std.debug.print("reference.typ's tree lacks {s}\n", .{k});
+        drift = true;
+    };
+    for (drawn.keys()) |k| if (!served.contains(k)) {
+        std.debug.print("reference.typ's tree has {s}, which the session does not serve\n", .{k});
+        drift = true;
+    };
+    if (drift) return error.FsTreeDrift;
+}
diff --git a/src/ninep/ctl.zig b/src/ninep/ctl.zig
index adfc91fa..f2490e38 100644
--- a/src/ninep/ctl.zig
+++ b/src/ninep/ctl.zig
@@ -789,7 +789,7 @@ fn sizeOf(line: []const u8) ?[2]u16 {
 /// itself, so a new builtin is listed the moment it exists.
 /// A builtin's doc comment, its first sentence, from the source itself: a
 /// line of /commands says what each word does without a second copy of it.
-fn summaryOf(word: []const u8, buf: []u8) []const u8 {
+pub fn summaryOf(word: []const u8, buf: []u8) []const u8 {
     const source = @embedFile("../builtins.zig");
     var needle_buf: [64]u8 = undefined;
     const needle = std.fmt.bufPrint(&needle_buf, "\npub const {s} = struct", .{word}) catch return "";
diff --git a/src/pardes.zig b/src/pardes.zig
index 38373266..310a4b56 100644
--- a/src/pardes.zig
+++ b/src/pardes.zig
@@ -46,6 +46,8 @@ pub const Region = @import("surface.zig").Region;
 pub const Chrome = @import("surface.zig").Chrome;
 pub const MAX_REGIONS = @import("surface.zig").MAX_REGIONS;
 pub const builtins = @import("builtins.zig");
+/// Every builtin as JSON, for the docs (tools/gen_builtins_json.zig).
+pub const builtins_json = @import("builtins_json.zig");
 const limits = memory.limits;
 const selection_pipe = @import("selection_pipe.zig");
 pub const config = @import("config.zig");
@@ -477,6 +479,7 @@ pub const Loc = struct {
 
 test {
     _ = @import("tagline.zig");
+    _ = @import("builtins_json.zig");
     _ = @import("exec.zig");
     _ = @import("look.zig");
     _ = @import("sam_edit.zig");