docs: add AGENTS.md — reusable-workflow blast radius and tag discipline

[vernonstinebaker]

NullBuilder hosts the reusable CI workflows every null-stack repo pins (zig-ci.yml@v1 et al.), but had no agent/contributor guidance. Added a thin AGENTS.md documenting the org-wide blast radius: consumer repos pin version tags, so workflow changes follow main-first → validate on a consumer → then move the tag; toolchain bumps must be coordinated with consumer docs; dependabot action bumps affect all consumers. Docs-only.

[DonPrus]

The organization-wide impact deserves documentation, but the operational instructions need correction before approval.

1. v1 is currently a branch, not a version tag. git ls-remote origin refs/heads/v1 refs/tags/v1 returns only refs/heads/v1 (2b9c2f2...), and the tags/v1 REST lookup returns 404. The repeated instructions to move a published tag therefore describe a different release mechanism. It would be great to document the actual promotion procedure for the existing v1 branch and distinguish a moving version ref from a commit pin. Creating a same-named tag is not a harmless substitute: GitHub gives tags precedence over branches with the same name.

2. There is no YAML lint gate in the current CI. .github/workflows/ci.yml installs Zig and tests nightly_decide.zig and package_artifact.zig; it runs neither actionlint nor a YAML linter. Please replace the validation claim with the actual checks and an explicit workflow-validation command/process rather than implying that a green helper-test job validates the reusable workflows.

3. zig_version is not pinned by every consumer: nullclaw and nullboiler omit it and inherit the shared default, while nullhub explicitly passes 0.16.0. It would be useful to state this distinction when describing the impact of default-version changes.

I checked the full diff, existing README, all repository workflows, live v1 ref and representative consumer configurations. The PR merges cleanly, but withholding approval because this file directs future agents' publication and validation behavior.

[vernonstinebaker]

All three corrections addressed in b0b6798. Each verified against the live repo before editing:

1. v1 is a branch, not a tag. Confirmed with git ls-remote: refs/heads/v1 → 2b9c2f2, and the repository has no tags at all. Rewritten to say so plainly: @v1 resolves to a moving ref, and zig-ci.yml on main reaches nobody until v1 advances.

Added the promotion procedure you asked for — land/validate on main, then advance the v1 branch — plus the moving-ref vs frozen-ref distinction: consumers needing immutability pin a commit SHA (or a uniquely named tag). Explicitly warns against creating a tag also named v1, with the GitHub tag-over-branch precedence consequence you linked.

2. YAML lint claim replaced with what CI actually does. The doc now lists the real ci.yml job verbatim: zig test .github/actions/nightly-decide/nightly_decide.zig and zig test .github/actions/package-artifact/package_artifact.zig, and states that it neither lints YAML nor executes the reusable workflows — so a green Test actions job says nothing about zig-ci.yml. Validation is now an explicit manual step with a concrete command (actionlint .github/workflows/*.yml, or yamllint).

3. zig_version pinning corrected. Now recorded as optional and inconsistently pinned: nullhub passes zig_version: "0.16.0" explicitly; nullclaw, nullboiler and nullwatch omit it and inherit the zig-ci.yml default ("0.16.0", verified in the workflow input). Notes that a default bump therefore moves those three automatically while nullhub must be updated separately.

Validation — merge result 2e8879e2 (base = current main 94339fde):

• CI-equivalent helper tests: nightly_decide 5/5, package_artifact 2/2
• YAML sanity: all four workflows (ci.yml, zig-ci.yml, zig-nightly.yml, zig-release.yml) parse clean
• Merge vs main touches only AGENTS.md (+57/-0)
• CI Test actions pass

Ready for re-review.