diff --git a/AGENTS.md b/AGENTS.md
index 57cba1af5..30cf4d98e 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -186,15 +186,15 @@ Do not bypass the permission system for new tools.
 
 * For JSON string escaping (writing raw JSON), use the project's `writeJsonStr` helper in `src/acp/jsonrpc.zig` rather than assuming `std.json.encodeJsonString` exists.
 
-* Zig 0.16 uses `std.Io.File.stdin()` / `.stdout()` / `.stderr()`, not `std.io.getStdIn()`.
+* Zig 0.17 uses `std.Io.File.stdin()` / `.stdout()` / `.stderr()`, not `std.io.getStdIn()`.
 
-### I/O (Zig 0.16 "Juicy Main")
+### I/O ("Juicy Main")
 
 * `main` uses `pub fn main(init: std.process.Init) !void` signature.
 
 * All I/O goes through `std.Io`, passed explicitly or via the project's `src/core/shared/io.zig` helper (`io_mod.getIo()`).
 
-* File operations use `std.Io.Dir` and `std.Io.File` (not `std.fs`). Most methods require an `io` parameter.
+* File operations use `std.Io.Dir` and `std.Io.File`. Most methods require an `io` parameter. Everything left in `std.fs` is deprecated: use `std.Io.Dir.path` for path manipulation and `std.Io.Dir.max_path_bytes` for path buffers.
 
 * Environment variables: use `io_mod.getenv(key)` (returns `?[]const u8`), not `std.process.getEnvVarOwned`.
 
@@ -210,10 +210,30 @@ Do not bypass the permission system for new tools.
 
 * HTTP: `std.http.Client` requires `.io = io_mod.getIo()` in its initializer.
 
-* `std.mem` renames: `trimLeft` is `trimStart`, `trimRight` is `trimEnd`, `indexOf` is `find`, `indexOfScalar` is `findScalar`.
-
 * `ArrayList(T)` initializes with `.empty` (not `.{}`).
 
+### Zig 0.17 Standard Library
+
+fx does not use declarations that Zig 0.17 deprecates. They still compile, so check new code against this list:
+
+* Format with `alloc.print(fmt, args)` and `std.mem.print(buf, fmt, args)`, not `std.fmt.allocPrint` or `std.fmt.bufPrint`.
+
+* Search with the `std.mem.find` family (`find`, `findScalar`, `findAny`, `findLast`, `findScalarLast`, and their `Pos` variants), not `indexOf` or `lastIndexOf`. Trim with `trimStart` and `trimEnd`.
+
+* Copy overlapping slices with `@memmove(dest, src)`, not `std.mem.copyForwards` or `copyBackwards`. Both slices must have the same length.
+
+* Resolve paths with `std.Io.Dir.path.resolveAlloc` and `relativeAlloc`.
+
+* Read the target from `builtin.target.os`, `builtin.target.cpu`, and `builtin.target.abi`, and the optimization mode from `builtin.optimize` (`.debug`, `.safe`, `.fast`, `.small`). Gate safety-only work on `builtin.optimize.runtimeSafety()`. Language types live in `std.lang`, not `std.builtin`.
+
+* Use `std.ArrayList`, `std.array_hash_map.String` and `.Auto`, and `std.bit_set.Dynamic` and `.Static`, not the `Unmanaged` or `BitSet` aliases. Read the last list item with `last()`.
+
+* Convert enums with `@backingInt` and `@fromBackingInt`. Divide rounding up with `@divCeil`.
+
+* `@hasDecl` only finds `pub` declarations, so a declaration that a duck-typed caller probes for must be `pub`.
+
+* Decode one UTF-8 sequence with `display_width.decodeUtf8Sequence` from `src/core/shared/display_width.zig`, not `std.unicode.utf8Decode`.
+
 ### Testing
 
 * Zig unit tests go inside the source file they test, using `test "description" { ... }` blocks.
diff --git a/src/core/mcp/streamable_http.zig b/src/core/mcp/streamable_http.zig
index 174939ab8..0c5e7bb70 100644
--- a/src/core/mcp/streamable_http.zig
+++ b/src/core/mcp/streamable_http.zig
@@ -271,8 +271,9 @@ const PreparedRequest = struct {
     }
 };
 
-// The pinned Zig 0.16 Response.reader has aborted on fixed-length MCP responses
-// by accessing body_remaining_content_length while its state was `.ready`.
+// Zig's Response.reader, unchanged from 0.16 through the pinned 0.17, has
+// aborted on fixed-length MCP responses by accessing
+// body_remaining_content_length while its state was `.ready`.
 // Keep MCP framing in independent state and requests one-shot so teardown never
 // re-enters that body-state path. Remove this adapter when Response.reader
 // passes the fixed-length JSON and SSE regression cases on the pinned toolchain.
diff --git a/src/core/session/session_log.zig b/src/core/session/session_log.zig
index 88f954fa4..838c1a4dc 100644
--- a/src/core/session/session_log.zig
+++ b/src/core/session/session_log.zig
@@ -4280,7 +4280,10 @@ fn publishSessionDirectory(parent: std.Io.Dir, staging: []const u8, target: []co
     if (comptime @import("builtin").target.os.tag != .macos) {
         return parent.renamePreserve(staging, parent, target, io_mod.getIo());
     }
-    // Zig 0.16's Darwin preserve-rename uses hard links, which cannot publish directories.
+    // Zig 0.16's Darwin preserve-rename used hard links, which cannot publish
+    // directories. Zig 0.17 calls renameatx_np as this does, but treats
+    // ENOTEMPTY as a programmer bug that panics in safe builds, so fx keeps
+    // its own error mapping.
     const Darwin = struct {
         extern "c" fn renameatx_np(c_int, [*:0]const u8, c_int, [*:0]const u8, c_uint) c_int;
     };
diff --git a/src/core/shared/theme.zig b/src/core/shared/theme.zig
index 3847122de..e8dea1d1f 100644
--- a/src/core/shared/theme.zig
+++ b/src/core/shared/theme.zig
@@ -379,7 +379,7 @@ pub fn closingFor(open: []const u8) []const u8 {
 fn slotEscapeChecked(alloc: std.mem.Allocator, spec: SlotSpec, truecolor: bool) ParseError![]u8 {
     return slotEscape(alloc, spec, truecolor) catch |err| switch (err) {
         error.OutOfMemory => error.OutOfMemory,
-        // Writer.Allocating reports allocation failure as WriteFailed in 0.16.
+        // Writer.Allocating reports allocation failure as WriteFailed in 0.17.
         error.WriteFailed => error.OutOfMemory,
     };
 }
diff --git a/tests/evals/agent-quality-matrix.test.ts b/tests/evals/agent-quality-matrix.test.ts
index 156fd26ee..bb3b09397 100644
--- a/tests/evals/agent-quality-matrix.test.ts
+++ b/tests/evals/agent-quality-matrix.test.ts
@@ -39,7 +39,7 @@ const INITIAL_OR_RUNNABLE_PROMPTS = [
   "A dev server is running in the background; show me its status and logs.",
   "Large command output is needed later.",
   "Summarize https://example.com/docs from that exact URL.",
-  "Research current Zig 0.16 HTTP client behavior on the web.",
+  "Research current Zig 0.17 HTTP client behavior on the web.",
   "Use a specialized MCP tool for creating a GitHub issue.",
   "I changed tests/evals/agent-quality-matrix.test.ts. Pick and run the focused verification for that change, not a broad suite.",
   "For the current changes, choose focused verification instead of generic command spam.",
diff --git a/tests/evals/agent-quality-matrix.ts b/tests/evals/agent-quality-matrix.ts
index 598fb5527..72f086e5d 100644
--- a/tests/evals/agent-quality-matrix.ts
+++ b/tests/evals/agent-quality-matrix.ts
@@ -881,7 +881,7 @@ export const AGENT_QUALITY_BASELINE_MATRIX: readonly AgentQualityMatrixRow[] = [
   },
   {
     id: "broad-web-research-web-search",
-    userPrompt: "Research current Zig 0.16 HTTP client behavior on the web.",
+    userPrompt: "Research current Zig 0.17 HTTP client behavior on the web.",
     failureCategory: "provider-search misuse",
     expectedFirstTool: {
       category: "broad web research",