add orienting language to 0.15 notes

make each file more accessible - explain what the thing is for,
why you'd care, and what the patterns mean in context.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <[e-mail]>

languages/ziglang/0.15/arraylist.md

···
 # arraylist
 
-0.15 made arraylist unmanaged - allocator passed to each method. the compiler catches missing allocators immediately, so that's not worth documenting. what matters is ownership.
+`ArrayList` is zig's growable buffer - you use it when you don't know the size upfront. common for building strings, collecting results, or accumulating data before sending it somewhere.
+
+in 0.15, arraylist became "unmanaged" - you pass the allocator to each method instead of storing it in the struct. the compiler catches missing allocators immediately, so that's not the tricky part. the tricky part is ownership.
 
 ## ownership patterns
 
-**build and discard** - most common. defer cleanup, use `.items` to borrow:
+when you build up data in an arraylist, you eventually need to do something with it. there are two paths:
+
+**build and discard** - you use the data, then throw it away. this is most common (e.g., building an http response):
 
 ```zig
 var buf: std.ArrayList(u8) = .empty;
-defer buf.deinit(alloc);
+defer buf.deinit(alloc);  // cleanup when we're done
 
 try buf.print(alloc, "{s}: {d}", .{ name, value });
-sendResponse(buf.items);  // borrow the slice
+sendResponse(buf.items);  // borrow the slice, arraylist still owns it
 ```
 
-**build and return** - transfer ownership, no defer:
+**build and return** - you're building something to give to a caller. they'll own the memory:
 
 ```zig
 var buf: std.ArrayList(u8) = .empty;
-// no defer - caller owns the memory
+// no defer here - we're transferring ownership
 
 try buf.appendSlice(alloc, data);
-return buf.toOwnedSlice(alloc);
+return buf.toOwnedSlice(alloc);  // caller must free this
 ```
 
-the difference: `.items` borrows (arraylist still owns the memory), `.toOwnedSlice()` transfers (caller must free).
+the key difference: `.items` gives you a view into the arraylist's memory (it still owns it). `.toOwnedSlice()` hands ownership to you (arraylist forgets about it, you must free it).
 
 see: [dashboard.zig#L187](https://tangled.sh/@zzstoatzz.io/music-atmosphere-feed/tree/main/src/dashboard.zig#L187) for the return pattern
 
 ## direct methods vs writer
 
-arraylist has `.print()` directly - you don't always need a writer:
+you might think you need to get a writer to write formatted output, but arraylist has `.print()` built in:
 
 ```zig
 try buf.print(alloc, "{{\"count\":{d}}}", .{count});
 ```
 
-use `.writer(alloc)` when you need to pass to something expecting `std.Io.Writer`:
+use `.writer(alloc)` when you need to pass to something that expects a generic `std.Io.Writer`:
 
 ```zig
 const w = buf.writer(alloc);
···
 
 ## why unmanaged
 
-from the [release notes](https://ziglang.org/download/0.15.1/release-notes.html): storing the allocator had costs - worse method signatures for reservations, can't statically initialize, extra memory for nested containers. the benefits (convenience, avoiding wrong allocator) didn't justify it since the allocator is always nearby.
+from the [release notes](https://ziglang.org/download/0.15.1/release-notes.html): storing the allocator had costs - worse method signatures for reservations, can't statically initialize, extra memory for nested containers. the benefits (convenience, avoiding wrong allocator) didn't justify it since the allocator is always nearby anyway.

languages/ziglang/0.15/build.md

···
 # build
 
+`build.zig` is where you configure how your project compiles - what files to include, what dependencies to pull in, what artifacts to produce. zig's build system is written in zig itself, so it's just code.
+
 ## 0.15 change
 
-pre-0.15 used `exe.addModule()`. now use `createModule` with `imports` array:
+the way you attach dependencies to your executable changed. before 0.15, you'd call `exe.addModule()` after creating the executable. now you declare everything upfront in a `createModule` call with an `imports` array:
 
 ```zig
 const exe = b.addExecutable(.{
···
 });
 ```
 
+the `.name` in the imports array is what you'll use in your code: `@import("websocket")`.
+
 ## dependency hash trick
 
-to get the hash for build.zig.zon, run `zig build` with a wrong hash. it tells you the correct one:
+dependencies are declared in `build.zig.zon` with a hash for verification. to get the correct hash for a new dependency, just put any placeholder hash and run `zig build`. the error message tells you what the hash should be:
 
 ```
 error: hash mismatch... expected 1220abc..., found 1220def...
 ```
 
+copy the "found" value into your .zon file.
+
 ## don't forget
 
-`b.installArtifact(exe)` - without this, `zig build` produces nothing.
+after creating your executable, you need to tell zig to actually install it:
+
+```zig
+b.installArtifact(exe);
+```
+
+without this line, `zig build` runs successfully but produces no output. easy to miss.

languages/ziglang/0.15/comptime.md

···
 # comptime
 
-comptime lets you generate types, validate inputs, and catch errors at compile time. for a complete example, see [zql](https://tangled.sh/@zzstoatzz.io/zql) which parses SQL at comptime and generates type-safe bindings.
+zig runs code at compile time. not just constants - actual logic, loops, conditionals. you can generate types, validate inputs, and catch errors before your program ever runs.
+
+the payoff: things that would be runtime checks in other languages become compile errors in zig. if your code compiles, certain classes of bugs are impossible.
+
+for a complete example, see [zql](https://tangled.sh/@zzstoatzz.io/zql) - it parses SQL at compile time and generates type-safe bindings. typo in a parameter name? compile error.
 
 ## type-returning functions
 
-a function that takes comptime params and returns a `type`:
+the core pattern: a function that takes comptime parameters and returns a `type`. you're generating a struct definition:
 
 ```zig
 pub fn Wrapper(comptime T: type) type {
···
 }
 ```
 
-`@This()` refers to the struct being defined - necessary since the struct is anonymous.
+`@This()` refers to the struct being defined - you need it because the struct doesn't have a name (it's an anonymous struct returned from a function).
 
 ## generating tuple types from struct fields
 
-extract field types in a specific order to build a tuple:
+sometimes you need to reorder or extract types from a struct. this pattern builds a tuple type by pulling field types in a specific order:
 
 ```zig
 fn BindTuple(comptime Args: type, comptime param_names: []const []const u8) type {
···
 }
 ```
 
-this reorders struct fields into a tuple matching the parameter order. useful for binding named args to positional parameters.
+use case: you have named arguments (`.{ .name = "alice", .age = 25 }`) but need to bind them to positional SQL parameters in a specific order.
 
 see: [zql/src/Query.zig#L78](https://tangled.sh/@zzstoatzz.io/zql/tree/main/src/Query.zig#L78)
 
 ## compile-time validation
 
-`@compileError` stops compilation with a message:
+`@compileError` stops compilation with a custom message. combine with `inline for` to check things at compile time:
 
 ```zig
 inline for (required_fields) |name| {
···
 }
 ```
 
-if your code compiles, it's valid. invalid states are unrepresentable.
+if someone forgets a required field, they get a compile error pointing at exactly what's missing.
 
 ## branch quota
 
-complex comptime parsing hits the default branch quota (1000 backwards branches). scale it with input:
+zig limits how much work comptime code can do (prevents infinite loops from hanging compilation). the default is 1000 "backwards branches" (loops, recursion). for complex parsing, you'll hit this:
 
 ```zig
 @setEvalBranchQuota(input.len * 100);
 ```
 
-without this, complex parsing fails with "evaluation exceeded maximum branch quota."
+scale it with your input size so small inputs compile fast and large inputs still work.
 
 see: [zql/src/parse.zig#L48](https://tangled.sh/@zzstoatzz.io/zql/tree/main/src/parse.zig#L48)
 
 ## constraints
 
-- no allocation at comptime - use fixed-size arrays
-- no runtime values - everything must be known at compile time
-- comptime code runs during compilation, adding build time
+a few things to know:
+- no allocation at comptime - you can't call an allocator, so use fixed-size arrays
+- no runtime values - everything must be known at compile time (that's the point)
+- comptime code runs during compilation, so complex logic adds build time

languages/ziglang/0.15/concurrency.md

···
 # concurrency
 
-zig has threads, mutexes, and atomics. no async/await. for syntax, see std.Thread docs. these notes cover design decisions.
+when your program needs to do multiple things at once - handle many connections, run background tasks, update stats while processing requests. zig gives you threads, mutexes, and atomics. no async/await.
+
+these notes focus on design decisions, not syntax. for api details, see std.Thread docs.
 
 ## when to use atomics vs mutex
 
-**atomics for simple counters:**
+you often need to share state between threads. the question is how to protect it.
+
+**atomics** are for simple counters - things where each operation is independent:
 
 ```zig
 posts_checked: std.atomic.Value(u64) = .init(0),
 
+// in some thread:
 _ = self.posts_checked.fetchAdd(1, .monotonic);
 ```
 
-**mutex for complex data structures:**
+**mutex** is for complex data or multi-step operations:
 
 ```zig
 bufo_matches: std.StringHashMap(MatchInfo),
 bufo_mutex: Thread.Mutex = .{},
 
+// in some thread:
 self.bufo_mutex.lock();
 defer self.bufo_mutex.unlock();
 try self.bufo_matches.put(name, info);
 ```
 
-the pattern in [find-bufo/bot/src/stats.zig](https://tangled.sh/@zzstoatzz.io/find-bufo/tree/main/bot/src/stats.zig): atomics for the five simple counters (posts_checked, matches_found, etc.), mutex for the hashmap of per-bufo match data.
+the pattern in [find-bufo/bot/src/stats.zig](https://tangled.sh/@zzstoatzz.io/find-bufo/tree/main/bot/src/stats.zig): five simple counters use atomics (posts_checked, matches_found, etc.), but the hashmap of per-bufo match data uses a mutex.
 
-rule: if it's a single integer, use atomic. if it's a container or multi-field update, use mutex.
+rule of thumb: single integer that threads increment independently? atomic. anything else? mutex.
 
 ## memory ordering
 
-all usages in these projects use `.monotonic` - sufficient for independent counters where you just need eventual visibility, not synchronization between threads.
+you'll see `.monotonic` everywhere in these projects. it's the weakest ordering - just means "this operation is atomic, but i don't care about ordering relative to other operations."
 
-use stricter orderings (`.acquire`, `.release`) when one thread's write must be visible to another thread before proceeding. none of these projects need that.
+that's fine for independent counters. you'd use stricter orderings (`.acquire`, `.release`) when one thread's write must be visible to another thread before it proceeds - like signaling that data is ready. none of these projects need that.
 
 ## callback pattern
 
-jetstream doesn't use channels or message passing. it takes a function pointer:
+the jetstream client doesn't use channels or complicated message passing. it just takes a function pointer and calls it when a message arrives:
 
 ```zig
 callback: *const fn (Post) void,
 
+// when a message comes in:
 self.callback(.{
     .uri = uri,
     .text = text,
 });
 ```
 
-simpler than channels when you just need to notify one consumer.
+simpler than channels when you have one producer and one consumer. the callback runs on the producer's thread, so keep it fast.
 
 see: [find-bufo/bot/src/jetstream.zig#L18](https://tangled.sh/@zzstoatzz.io/find-bufo/tree/main/bot/src/jetstream.zig#L18)
 
-## reconnection
+## reconnection with backoff
 
-exponential backoff for network consumers:
+network connections fail. when they do, don't hammer the server - back off exponentially:
 
 ```zig
 var backoff: u64 = 1;
···
 }
 ```
 
-starts at 1s, doubles each failure, caps at 60s.
+starts at 1 second, doubles each failure, caps at 60 seconds. simple and effective.

languages/ziglang/0.15/io.md

···
 # i/o
 
-0.15 replaced generic `anytype` reader/writer with concrete types using explicit buffers. see [release notes](https://ziglang.org/download/0.15.1/release-notes.html) for the rationale.
+reading and writing data - files, sockets, http. zig 0.15 overhauled this entirely, replacing generic `anytype` interfaces with concrete types that use explicit buffers. the [release notes](https://ziglang.org/download/0.15.1/release-notes.html) explain why (better error messages, no generic pollution, clearer ownership).
+
+the main thing to know: you provide the buffers, and you call `.interface()` to get the type that APIs expect.
 
-## http server pattern
+## http server
+
+when handling incoming connections, you set up buffers for reading requests and writing responses:
 
 ```zig
 var read_buffer: [8192]u8 = undefined;
···
 var server = http.Server.init(reader.interface(), &writer.interface);
 ```
 
-the buffers are yours - stack allocated, explicit size. `.interface()` extracts the concrete type that http.Server expects.
+you own these buffers (they're on your stack). the http.Server borrows them. `.interface()` extracts the concrete reader/writer type.
 
 see: [http.zig#L14](https://tangled.sh/@zzstoatzz.io/music-atmosphere-feed/tree/main/src/http.zig#L14)
 
-## http client pattern
+## http client
 
-for api calls, use `Io.Writer.Allocating` to collect the response:
+when making outgoing requests (calling APIs, fetching data), use `Io.Writer.Allocating` to collect the response body:
 
 ```zig
 var client = http.Client{ .allocator = allocator };
···
 
 if (result.status != .ok) return error.FetchFailed;
 
-const response = aw.toArrayList().items;
+const response = aw.toArrayList().items;  // the response body
 ```
+
+the allocating writer grows as needed to hold whatever the server sends back.
 
 see: [find-bufo/bot/src/main.zig#L196](https://tangled.sh/@zzstoatzz.io/find-bufo/tree/main/bot/src/main.zig#L196)
 
 ## tls reading quirk
 
-when reading from raw tls (not http.Client), you must loop until data arrives. `n == 0` means "try again", not EOF:
+if you're doing raw tls (not using http.Client), there's a gotcha: when reading, `n == 0` doesn't mean end-of-stream. it means "i consumed some input but don't have output yet" - tls may be buffering partial records or handling renegotiation. you have to keep trying:
 
 ```zig
 outer: while (total_read < response_buf.len) {
···
             total_read += n;
             break;
         }
-        // n == 0: tls may have consumed input without producing output
-        // (buffering partial records, renegotiation, etc.)
+        // n == 0: keep trying, tls isn't done yet
     }
 }
 ```
 
-this happens because tls decryption can consume input bytes without producing output yet. the inner loop keeps trying until actual data appears.
+also, raw tls needs explicit flushes at both the tls layer and the underlying stream:
 
-also: raw tls needs explicit flush at both layers:
 ```zig
 tls_client.writer.flush() catch return error.Failed;
 stream_writer.interface.flush() catch return error.Failed;
···
 
 ## when you don't need to flush
 
-high-level apis (http.Server, http.Client) handle flushing internally. `request.respond()` flushes for you. only raw tls/stream code needs explicit flushes.
+the high-level apis handle this for you. `http.Server`'s `request.respond()` flushes internally. `http.Client` flushes when the request completes. you only need manual flushes when working with raw streams or tls directly.