docs(AGENTS): add Cursor Cloud environment setup instructions

[justrach]

Summary

Sets up the Cloud Agent development environment for this Zig codebase and records durable, non-obvious setup guidance in AGENTS.md. No source code changed.

The startup update script (registered separately, not committed) installs the exact pinned Zig dev snapshot 0.17.0-dev.813+2153f8143 (from build.zig.zon / release CI) to ~/.local/zig and symlinks it onto PATH. The vendored nanoregex is the only build dependency.

What was verified

• Build: zig build → zig-out/bin/codedb (dev/debug).
• Lint: zig fmt --check src runs. Exits non-zero only due to pre-existing formatting drift in ~6 tracked files (not introduced here).
• Tests: zig build test → 981/982 pass. The one crash is a pre-existing Linux-only inotify bug in src/watcher.zig (see below).
• E2E MCP harness: scripts/e2e_mcp_test.py → 53/54 pass (the lone failure is an unrelated codedb_index MCP-tool assertion; all live-watch scenarios pass).
• Run (hello-world): one-shot CLI (codedb <root> tree|search|find|word) indexes 643 files and returns real structural/trigram/word-index results; the mcp daemon answers tools/call requests.

Pre-existing Linux daemon crash (documented, not fixed)

The serve/mcp daemons and watcher-exercising tests panic on Linux (watcher.zig "integer does not fit in destination type") when arming inotify against the sentinel path /tmp/codedb-notify. Root cause: the binary links libc, so std.posix.errno uses libc semantics (only -1 is an error), but std.os.linux.inotify_add_watch returns -errno; -ENOENT on the missing sentinel is misread as success and @intCast panics. Maintainers develop on macOS (kqueue path), so this Linux path is currently unfixed on main. Workaround for running daemons/E2E without touching source: : > /tmp/codedb-notify. This is documented in AGENTS.md.

Notes

• AGENTS.md ## Cursor Cloud specific instructions captures the toolchain pin, build/lint/test/run commands, the Linux inotify gotcha + workaround, and the fact that e2e_mcp_test.py writes temp projects into --project's parent (so run it from a writable-parent dir, not /workspace).
• codedb.snapshot (generated) was intentionally left unmodified.

  

[github-actions]

👋 Thanks for the contribution! Quick heads-up: this repo lands changes on the current release/* branch, not main.

Please retarget this PR via Edit → base branch to the active release/* branch shown in the repository branch list.

(Automated hint — reply here if you need a hand.)