Add comprehensive AGENTS.md agent guide

[PeterDaveHello]

Add AGENTS.md: an agent‑facing guide for this repository that documents layout, workflows, and the exact commands agents should run.

Generated mainly by codex-cli v0.46.0 with gpt-5-codex (high) and this AGENTS.md construction prompt:

• https://gist.github.com/PeterDaveHello/f30c38a156982a35683edfd5ece2d474

Reference:

• https://agents.md/

Motivation and Context

Establish a dedicated, machine‑consumable reference so agents can act
consistently and safely:

• Provide a single source of truth for agent workflows and guardrails.
• Reduce back‑and‑forth in reviews by codifying do/don'ts and commands.
• Mirror CI and real paths to avoid local/CI drift and false negatives.
• Improve onboarding for both AI agents and human contributors.

Testing Details

• Queried with a supported AI Agent to confirm it reads AGENTS.md and
  surfaces the corrected commands and coverage.
• Cross‑checked AGENTS.md guidance against CI workflow definitions to
  ensure parity for shfmt/shellcheck/doctoc/markdown‑link‑check.

Types of changes

• Documentation
• Version change (Update, remove or add more Node.js versions)
• Variant change (Update, remove or add more variants, or versions of variants)
• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Other (none of the above)

Checklist

• My code follows the code style of this project.
• My change requires a change to the documentation.
• I have updated the documentation accordingly.
• I have read the CONTRIBUTING.md document.
• All new and existing tests passed.

Summary from GitHub Copilot

This pull request adds a comprehensive set of repository guidelines to the AGENTS.md file. The new documentation provides clear instructions on repository operations, project structure, development workflows, coding standards, testing procedures, commit and PR practices, safety, permissions, and security protocols. This will help standardize contributions and streamline onboarding for new contributors.

Documentation and process guidelines:

• Added detailed "Dos and Don'ts" for updating Node.js versions, managing signing keys, and maintaining consistency across Dockerfiles and scripts.
• Documented the overall project structure, module organization, and the role of key files and directories.
• Outlined build, test, and development commands, including Docker build/test flows and documentation checks.
• Specified coding style, naming conventions, and formatting requirements for shell scripts, Dockerfiles, and Markdown documents.
• Provided guidelines for testing, commit/PR workflow, safety, permissions, and security reporting.

[Copilot]

Pull Request Overview

This PR adds a comprehensive agent-facing guide (AGENTS.md) that documents repository layout, workflows, and exact commands for AI agents and contributors working with this Node.js Docker image repository.

• Establishes standardized workflows for Node.js version updates, Docker builds, and documentation maintenance
• Documents project structure, coding standards, and testing procedures to ensure consistency
• Provides clear safety guidelines and permission boundaries for different types of repository operations

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[Copilot]

Pull Request Overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated 2 comments.

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[MikeMcC399]

@PeterDaveHello

I've submitted PR #2296 to address the Markdown link check failure in CI.

[Copilot]

Pull Request Overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated 2 comments.

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[nschonni]

I won't block this, but I'm -1. I've found the co-pilot reviews to just be noise that add no value. For our generated PRs, it takes less time for a reviewer to flip to the Files tab and look at the changes, then request Co-Pilot to guess.
It has also suggested a user "fix" something historical that actually broke the images and needed to be reverted.

[Copilot]

Pull Request Overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[PeterDaveHello]

@nschonni I see your point, and I agree that AI code review still has some limitations and even hallucinations.

That said, another key purpose of AGENTS.md is to give us a way to use AI agents to assist with future updates to this project.

Since the project is basically maintained by volunteers and there are some pending issues to handle later, this could help ease both the workload and mental effort.

As tools and LLMs continue to improve, some of these challenges will gradually be resolved.

That's the idea behind adding AGENTS.md.

[MikeMcC399]

@PeterDaveHello

If you rebase your branch on main (or merge main into your branch), you should find that the markdown-link-check errors are now suppressed. PR #2296 is now merged.