feat: add @init command to scaffold new zig projects

Scaffolds build.zig, build.zig.zon, src/main.zig, and AGENTS.md with
current Zig API patterns. Automatically generates the required fingerprint
by parsing the zig build error output.

Author: rockorager

AGENTS.md

@@ -2,7 +2,7 @@
 
 ## Zig Development
 
-Always use `zigdoc` to discover APIs for the Zig standard library AND any third-party dependencies (modules). Assume training data is out of date.
+Always use `zigdoc` to discover APIs for the Zig standard library and any third-party dependencies.
 
 Examples:
 ```bash
@@ -14,6 +14,8 @@ zigdoc vaxis.Window
 
 ## Common Zig Patterns
 
+These patterns reflect current Zig APIs and may differ from older documentation.
+
 **ArrayList:**
 ```zig
 var list: std.ArrayList(u32) = .empty;
@@ -29,6 +31,18 @@ defer writer.flush();
 try writer.print("hello {s}\n", .{"world"});
 ```
 
+**build.zig executable/test:**
+```zig
+b.addExecutable(.{
+    .name = "foo",
+    .root_module = b.createModule(.{
+        .root_source_file = b.path("src/main.zig"),
+        .target = target,
+        .optimize = optimize,
+    }),
+});
+```
+
 ## Zig Code Style
 
 **Naming:**

README.md

@@ -28,6 +28,18 @@ Examples:
 Options:
   -h, --help        Show this help message
   --dump-imports    Dump module imports from build.zig as JSON
+
+Commands:
+  @init             Initialize a new Zig project with AGENTS.md
+```
+
+## Project Initialization
+
+`zigdoc @init` scaffolds a minimal Zig project with an `AGENTS.md` file containing up-to-date API patterns and coding conventions for AI assistants.
+
+```bash
+mkdir my-project && cd my-project
+zigdoc @init
 ```
 
 ## Examples

build_readme.zig

@@ -35,6 +35,15 @@ pub fn main() !void {
         \\```
         \\{s}```
         \\
+        \\## Project Initialization
+        \\
+        \\`zigdoc @init` scaffolds a minimal Zig project with an `AGENTS.md` file containing up-to-date API patterns and coding conventions for AI assistants.
+        \\
+        \\```bash
+        \\mkdir my-project && cd my-project
+        \\zigdoc @init
+        \\```
+        \\
         \\## Examples
         \\
         \\```bash

src/main.zig

@@ -6,6 +6,11 @@ const log = std.log.scoped(.zigdoc);
 const build_runner_0_14 = @embedFile("build_runner_0.14.zig");
 const build_runner_0_15 = @embedFile("build_runner_0.15.zig");
 
+const template_build_zig = @embedFile("templates/build.zig.template");
+const template_main_zig = @embedFile("templates/main.zig.template");
+const template_build_zig_zon = @embedFile("templates/build.zig.zon.template");
+const template_agents_md = @embedFile("templates/AGENTS.md.template");
+
 pub fn main() !void {
     var debug_allocator: std.heap.DebugAllocator(.{}) = .init;
     const gpa, const is_debug = gpa: {
@@ -42,6 +47,11 @@ pub fn main() !void {
         return;
     }
 
+    if (std.mem.eql(u8, symbol.?, "@init")) {
+        try initProject(arena.allocator());
+        return;
+    }
+
     Walk.init(arena.allocator());
     Walk.Decl.init(arena.allocator());
 
@@ -84,10 +94,71 @@ fn printUsage() !void {
         \\  -h, --help        Show this help message
         \\  --dump-imports    Dump module imports from build.zig as JSON
         \\
+        \\Commands:
+        \\  @init             Initialize a new Zig project with AGENTS.md
+        \\
     );
     try stdout_writer.interface.flush();
 }
 
+fn initProject(allocator: std.mem.Allocator) !void {
+    const cwd = std.fs.cwd();
+
+    // Check if project already exists
+    if (cwd.access("build.zig", .{})) |_| {
+        std.debug.print("Error: build.zig already exists\n", .{});
+        return error.ProjectExists;
+    } else |_| {}
+
+    // Get project name from current directory
+    var path_buf: [std.fs.max_path_bytes]u8 = undefined;
+    const cwd_path = try cwd.realpath(".", &path_buf);
+    const name = std.fs.path.basename(cwd_path);
+
+    // Create src directory
+    try cwd.makeDir("src");
+
+    // Write files with substitutions
+    try cwd.writeFile(.{ .sub_path = "build.zig", .data = try substitute(allocator, template_build_zig, name) });
+    try cwd.writeFile(.{ .sub_path = "build.zig.zon", .data = try substitute(allocator, template_build_zig_zon, name) });
+    try cwd.writeFile(.{ .sub_path = "src/main.zig", .data = template_main_zig });
+    try cwd.writeFile(.{ .sub_path = "AGENTS.md", .data = template_agents_md });
+
+    // Run zig build to get suggested fingerprint from error message
+    const result = std.process.Child.run(.{
+        .allocator = allocator,
+        .argv = &.{ "zig", "build" },
+    }) catch {
+        std.debug.print("Initialized Zig project '{s}' (run 'zig build' to generate fingerprint)\n", .{name});
+        return;
+    };
+
+    // Parse fingerprint from error: "suggested value: 0x..."
+    if (std.mem.indexOf(u8, result.stderr, "suggested value: ")) |start| {
+        const fp_start = start + "suggested value: ".len;
+        const fp_end = std.mem.indexOfPos(u8, result.stderr, fp_start, "\n") orelse result.stderr.len;
+        const fingerprint = result.stderr[fp_start..fp_end];
+
+        // Read current build.zig.zon and insert fingerprint
+        const zon_content = try cwd.readFileAlloc(allocator, "build.zig.zon", 64 * 1024);
+        const new_zon = try std.mem.replaceOwned(
+            u8,
+            allocator,
+            zon_content,
+            ".version = \"0.0.0\",",
+            try std.fmt.allocPrint(allocator, ".version = \"0.0.0\",\n    .fingerprint = {s},", .{fingerprint}),
+        );
+        try cwd.writeFile(.{ .sub_path = "build.zig.zon", .data = new_zon });
+    }
+
+    std.debug.print("Initialized Zig project '{s}'\n", .{name});
+}
+
+fn substitute(allocator: std.mem.Allocator, template: []const u8, name: []const u8) ![]const u8 {
+    const sanitized = try std.mem.replaceOwned(u8, allocator, name, "-", "_");
+    return std.mem.replaceOwned(u8, allocator, template, "{{name}}", sanitized);
+}
+
 fn dumpImports(arena: *std.heap.ArenaAllocator) !void {
     // Check if build.zig exists
     std.fs.cwd().access("build.zig", .{}) catch {

src/templates/AGENTS.md.template

@@ -0,0 +1,91 @@
+# AGENTS.md
+
+## Zig Development
+
+Always use `zigdoc` to discover APIs for the Zig standard library and any third-party dependencies.
+
+Examples:
+```bash
+zigdoc std.fs
+zigdoc std.posix.getuid
+zigdoc ghostty-vt.Terminal
+zigdoc vaxis.Window
+```
+
+## Common Zig Patterns
+
+These patterns reflect current Zig APIs and may differ from older documentation.
+
+**ArrayList:**
+```zig
+var list: std.ArrayList(u32) = .empty;
+defer list.deinit(allocator);
+try list.append(allocator, 42);
+```
+
+**stdout/stderr Writer:**
+```zig
+var buf: [4096]u8 = undefined;
+const writer = std.fs.File.stdout().writer(&buf);
+defer writer.flush();
+try writer.print("hello {s}\n", .{"world"});
+```
+
+**build.zig executable/test:**
+```zig
+b.addExecutable(.{
+    .name = "foo",
+    .root_module = b.createModule(.{
+        .root_source_file = b.path("src/main.zig"),
+        .target = target,
+        .optimize = optimize,
+    }),
+});
+```
+
+## Zig Code Style
+
+**Naming:**
+- `camelCase` for functions and methods
+- `snake_case` for variables and parameters
+- `PascalCase` for types, structs, and enums
+- `SCREAMING_SNAKE_CASE` for constants
+
+**Struct initialization:** Prefer explicit type annotation with anonymous literals:
+```zig
+const foo: Type = .{ .field = value };  // Good
+const foo = Type{ .field = value };     // Avoid
+```
+
+**File structure:**
+1. `//!` doc comment describing the module
+2. `const Self = @This();` (for self-referential types)
+3. Imports: `std` → `builtin` → project modules
+4. `const log = std.log.scoped(.module_name);`
+
+**Functions:** Order methods as `init` → `deinit` → public API → private helpers
+
+**Memory:** Pass allocators explicitly, use `errdefer` for cleanup on error
+
+**Documentation:** Use `///` for public API, `//` for implementation notes. Always explain *why*, not just *what*.
+
+**Tests:** Inline in the same file, register in src/main.zig test block
+
+## Safety Conventions
+
+Inspired by [TigerStyle](https://github.com/tigerbeetle/tigerbeetle/blob/main/docs/TIGER_STYLE.md).
+
+**Assertions:**
+- Add assertions that catch real bugs, not trivially true statements
+- Focus on API boundaries and state transitions where invariants matter
+- Good: bounds checks, null checks before dereference, state machine transitions
+- Avoid: asserting something immediately after setting it, checking internal function arguments
+
+**Function size:**
+- Soft limit of 70 lines per function
+- Centralize control flow (switch/if) in parent functions
+- Push pure computation to helper functions
+
+**Comments:**
+- Explain *why* the code exists, not *what* it does
+- Document non-obvious thresholds, timing values, protocol details

src/templates/build.zig.template

@@ -0,0 +1,39 @@
+const std = @import("std");
+
+pub fn build(b: *std.Build) void {
+    const target = b.standardTargetOptions(.{});
+    const optimize = b.standardOptimizeOption(.{});
+
+    const exe = b.addExecutable(.{
+        .name = "{{name}}",
+        .root_module = b.createModule(.{
+            .root_source_file = b.path("src/main.zig"),
+            .target = target,
+            .optimize = optimize,
+        }),
+    });
+
+    b.installArtifact(exe);
+
+    const run_cmd = b.addRunArtifact(exe);
+    run_cmd.step.dependOn(b.getInstallStep());
+    if (b.args) |args| {
+        run_cmd.addArgs(args);
+    }
+
+    const run_step = b.step("run", "Run the application");
+    run_step.dependOn(&run_cmd.step);
+
+    const test_step = b.step("test", "Run unit tests");
+    const exe_tests = b.addTest(.{
+        .root_module = b.createModule(.{
+            .root_source_file = b.path("src/main.zig"),
+            .target = target,
+            .optimize = optimize,
+        }),
+    });
+    test_step.dependOn(&b.addRunArtifact(exe_tests).step);
+
+    const fmt_check = b.addFmt(.{ .paths = &.{ "src", "build.zig", "build.zig.zon" } });
+    test_step.dependOn(&fmt_check.step);
+}

src/templates/build.zig.zon.template

@@ -0,0 +1,9 @@
+.{
+    .name = .{{name}},
+    .version = "0.0.0",
+    .paths = .{
+        "build.zig",
+        "build.zig.zon",
+        "src",
+    },
+}

src/templates/main.zig.template

@@ -0,0 +1,3 @@
+const std = @import("std");
+
+pub fn main() void {}