Productionize: build.zig.zon, autodoc, examples, agent metadata

[Jesssullivan]

Summary

• Add build.zig.zon with fingerprint for Zig package manager (zig fetch --save) support
• Add Zig module export (b.addModule) and zig build docs autodoc step to build.zig
• Add /// doc comments to all 4 FFI exports in src/ffi.zig and enrich comments in notify.zig, notify_linux.zig, notify_macos.zig
• Add examples/send_notification.c demonstrating init, send (with body and title-only), deinit
• Add CONTRIBUTING.md with install, dev prerequisites (libnotify-dev on Linux, none on macOS), and style guide
• Upgrade AGENTS.md to six-area format: Persona, Stack, Structure, Commands, Style, Boundaries
• Add Installation section to README.md with zig fetch and git submodule instructions
• Rename LLMS.txt to llms.txt, rewrite as slim llmstxt.org index; add llms-full.txt with complete API reference

Test plan

• CI builds pass on macOS and Linux (zig build -Doptimize=ReleaseFast)
• zig build docs generates autodoc output
• examples/send_notification.c compiles against the built library

[greptile-apps]

Greptile Summary

This PR productionizes zig-notify by adding build.zig.zon for the Zig package manager, a zig build docs autodoc step, /// doc comments across all source files, a C usage example, and updated documentation (CONTRIBUTING.md, AGENTS.md, README.md, llms.txt/llms-full.txt).

• build.zig: Both the b.addModule(\"zig-notify\", ...) call (result discarded via _ = ...) and the docs_lib module in the docs step are created without the Linux system include paths that root_module receives. On Linux, zig build docs will fail to resolve @cImport(\"libnotify/notify.h\"), and downstream zig fetch consumers will also fail to build.
• build.zig: The Zig module root is src/ffi.zig (C FFI wrappers returning c_int) rather than src/notify.zig (idiomatic Zig API with error unions), so Zig-to-Zig consumers get the wrong API surface.

Confidence Score: 3/5

Two P1 defects in build.zig cause zig build docs and the Zig package manager integration to fail on Linux; safe to merge only if Linux support is not yet a priority.

Two P1 issues both stem from the same root cause: new modules created from src/ffi.zig without the Linux system include paths. This breaks both zig build docs and zig fetch consumers on Linux, which are two of the primary features this PR advertises. All other changes (docs, comments, CONTRIBUTING.md, example) are clean.

build.zig — both the b.addModule call (lines 33-37) and the docs_lib module (lines 50-58) need Linux include paths added.

Important Files Changed

Filename	Overview
build.zig	Adds Zig module export and docs step, but both new modules (b.addModule and docs_lib) are missing Linux system include paths, breaking zig fetch consumers and zig build docs on Linux.
build.zig.zon	New package manifest with fingerprint, version 0.1.0, minimum Zig 0.14.1, and correct paths list.
examples/send_notification.c	Well-structured C example demonstrating init/send/deinit; build instructions assume repo root but don't say so explicitly.
src/ffi.zig	Adds comprehensive /// doc comments to all four C FFI exports; no logic changes.
src/notify.zig	Enriched doc comments on Urgency enum and all pub functions; no logic changes.
src/notify_linux.zig	Adds /// doc comments to init, deinit, and send; no logic changes.
src/notify_macos.zig	Replaces block comment with /// doc comments on send and escapeAppleScript; no logic changes.
README.md	Adds Installation section with zig fetch and git submodule instructions; corrects Zig version from 0.15.2 to 0.14.1.
CONTRIBUTING.md	New file covering installation, prerequisites, build/test commands, code style, and adding platform backends.
AGENTS.md	Upgraded to six-area format (Persona, Stack, Structure, Commands, Style, Boundaries); removes inline code example (moved to examples/).

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[zig build] --> B[root_module\nsrc/ffi.zig\n+ Linux include paths]
    B --> C[lib: libzig-notify.a\nb.installArtifact]

    A --> D[b.addModule zig-notify\nsrc/ffi.zig\n⚠️ NO Linux include paths\nresult discarded]
    D --> E[dep.module zig-notify\nfor downstream consumers\n❌ fails on Linux]

    A --> F[docs step\ndocs_lib module\nsrc/ffi.zig\n⚠️ NO Linux include paths]
    F --> G[getEmittedDocs\nzig-out/docs/\n❌ fails on Linux]

    A --> H[test step\nroot: src/notify.zig]
    H --> I[unit tests]

    style D fill:#f99,stroke:#c00
    style E fill:#f99,stroke:#c00
    style F fill:#f99,stroke:#c00
    style G fill:#f99,stroke:#c00

Loading

_{Reviews (1): Last reviewed commit: "Productionize: build.zig.zon, autodoc, e..." | Re-trigger Greptile}

[greptile-apps]

Zig module missing Linux include paths — breaks zig fetch consumers on Linux

The module returned by b.addModule is immediately discarded (_ = ...), so there is no way to attach the system include paths that root_module gets. When a downstream consumer calls dep.module("zig-notify") on Linux, the module resolves ffi.zig → notify.zig → notify_linux.zig → @cImport("libnotify/notify.h") without any of the /usr/include/libnotify or glib-2.0 paths, causing a compile error. The result should be retained so the same Linux include paths applied to root_module can be applied here.

[greptile-apps]

zig build docs fails on Linux — docs module missing C include paths

docs_lib is built from a freshly created module that has none of the Linux system include paths (/usr/include/libnotify, the glib-2.0 paths) that root_module receives. Zig's autodoc step does full semantic analysis, which resolves @cImport in notify_linux.zig. On Linux, this will fail with a "file not found" error for libnotify/notify.h. The fix is to apply the same conditional include paths to the docs module's inner module, or reuse the already-configured root_module for doc emission.

[greptile-apps]

Zig module root exposes C FFI surface instead of idiomatic Zig API

b.addModule points to src/ffi.zig, which only contains export fn wrappers returning c_int. Zig consumers following the README/CONTRIBUTING instructions (addImport("zig-notify", dep.module("zig-notify"))) will get C-style functions with no error unions or idiomatic types, instead of the ergonomic send/init/deinit from src/notify.zig. Consider using src/notify.zig as the module root so Zig-to-Zig callers get the proper API; the static library for C consumers can still use root_module (which is ffi.zig-rooted).

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

[greptile-apps]

Build instructions use relative paths that break when run from examples/

The comment says to compile with -Iinclude and -Lzig-out/lib, but the file lives in examples/, so those paths are only valid when the command is run from the repo root. A user who naturally cd examples/ before compiling will get "directory not found" errors. Either add a note that the commands should be run from the repo root, or adjust the paths.