zig-docs

Zig work rules (fresh docs + lightweight-performance discipline)

Use with the zig-docs-mcp skill (zdoc singleton). The point: never trust memory about Zig APIs (they churn between minor releases), always serve the LATEST release's truth, and default to high-performance lightweight patterns.

Workflow

1. Version gate — await zdoc.zig_version_status() at the start of any Zig task that touches the local toolchain. If up_to_date is false:
   • tell the user plainly: local X < latest Y,
   • run await zdoc.zig_update() and summarize the dry-run plan,
   • update only after they agree: await zdoc.zig_update(dry_run=False, confirm=True).
2. Docs before code — for any non-trivial API use:
   • await zdoc.zig_std(symbol="std.the.Symbol") for exact signatures/docs,
   • await zdoc.zig_langref(section=...) for language semantics,
   • await zdoc.zig_changelog() when upgrading across versions.
3. Performance by default — consult await zdoc.perf_guidance(topic=...) when designing modules: allocation strategy first, data layout second, comptime third.
4. Claims need mechanics — justify performance claims mechanically (bytes copied, cache misses, syscalls, pages mapped). Cite the doc version you used.
5. Lightweight bias — prefer fewer dependencies, smaller binaries, lazy init, zero-copy parsing, arena lifecycles. Delete work; don't optimize it.

Anti-patterns

• Answering Zig API questions from training memory without checking zdoc.
• Writing Zig against an old release's std layout after seeing up_to_date:false.
• Running zig_update with confirm without explicit user consent.
• Micro-optimizing before checking allocation/layout choices.