Merge branch 'main' into chore/deprecated-cleanupchore/deprecated-cleanup

4 files changed, 43 insertions, 50 deletions

diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
index fc25faa1..be77ac83 100644..120000
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -1,49 +1 @@
-# Copilot Review Instructions — vyos.vyos
-
-This is the `vyos.vyos` Ansible network collection for managing VyOS devices.
-Namespace `vyos`, name `vyos`, version `6.0.0`. All modules are prefixed `vyos_`.
-
-## Commit and PR standards
-
-- Every commit title must start with a Phorge task ID: `T<number>: description`.
-- Every PR must have exactly one changelog fragment in `changelogs/fragments/`.
-- PR descriptions that state a test count (e.g. "Add 8 unit tests") must match the actual number of test methods in the changed files. Flag mismatches.
-
-## Changelog fragments
-
-Fragments are YAML files under `changelogs/fragments/`. Valid top-level keys:
-
-| Key | Use for |
-|-----|---------|
-| `trivial` | Developer tooling, CI, housekeeping, formatting-only changes |
-| `bugfixes` | Bug fixes |
-| `minor_changes` | New features or user-visible improvements |
-| `major_changes` | Breaking changes |
-| `security_fixes` | Security fixes |
-| `doc_changes` | Documentation-only changes |
-
-Flag any fragment that uses `minor_changes` for what is actually developer tooling (linting, formatting, gitignore, test scaffolding). Those should use `trivial`.
-
-## Module architecture
-
-Two module families:
-
-**Resource modules** (`vyos_interfaces`, `vyos_firewall_rules`, `vyos_bgp_global`, etc.) follow a four-part structure under `plugins/module_utils/network/vyos/`:
-- `argspec/{resource}/` — argument spec
-- `config/{resource}/` — config builder
-- `facts/{resource}/` — facts parser
-- `rm_templates/{resource}.py` — regex/Jinja2 CLI templates
-
-Resource modules support all states: `merged`, `replaced`, `overridden`, `deleted`, `rendered`, `gathered`, `parsed`.
-
-**Legacy modules** (`vyos_vlan`, `vyos_config`, `vyos_command`, `vyos_user`, etc.) do not follow the resource module pattern.
-
-## VyOS CLI conventions
-
-- Set commands: `set interfaces ethernet eth0 address '192.0.2.1/24'`
-- Delete commands: `delete interfaces ethernet eth0 address '192.0.2.1/24'`
-- Quoting varies by context. In general, string values (descriptions, names, ELIN numbers) are single-quoted; boolean flags and bare keywords are not. However, address/prefix values may be quoted or unquoted depending on where they appear:
-  - Quoted: `address '192.0.2.1/24'`, `description 'my-iface'`, `elin '0000000911'`
-  - Unquoted: `address 192.0.2.1` (in firewall groups), `disable`, `mtu-ignore`, `vif 200`
-- When reviewing tests and fixtures, align with the quoting style used by surrounding fixtures rather than flagging a missing quote as an error.
-- Interface types: `ethernet`, `loopback`, `bonding`, `bridge`, `tunnel`, `wireguard`.
+../AGENTS.md
\ No newline at end of file
diff --git a/.github/workflows/ah_token_refresh.yml b/.github/workflows/ah_token_refresh.yml
index 0c8cba7b..09d2f9db 100644
--- a/.github/workflows/ah_token_refresh.yml
+++ b/.github/workflows/ah_token_refresh.yml
@@ -7,7 +7,7 @@ on:
 
 jobs:
     refresh:
-        uses: ansible/team-devtools/.github/workflows/ah_token_refresh.yml@v26.2.0
+        uses: ansible/team-devtools/.github/workflows/ah_token_refresh.yml@v26.4.0
         with:
             environment: release
         secrets:
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 00000000..436b6785
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,39 @@
+# AGENTS.md
+
+## Project purpose
+The official Ansible Collection for managing VyOS network appliances (`vyos.vyos` namespace). Provides modules, plugins, action handlers, terminal plugins, and resource modules for BGP, OSPF, firewall, interfaces, NTP, etc.
+
+## Tech stack
+- Ansible Collection (Galaxy). Python control-plane code under `plugins/`.
+- `galaxy.yml` declares `namespace: vyos`, `name: vyos`, `version: 6.0.0`, dep `ansible.netcommon >= 2.5.1`, license_file `LICENSE` (GPL-3.0).
+- Test stack: `pytest` + `tox-ansible.ini`; lint via flake8, isort, black (line-length 100), pre-commit, ansible-lint.
+- Runtime deps: `paramiko`, `scp` (`requirements.txt`); `bindep.txt` for system deps.
+
+## Build / test / run
+- Build: `ansible-galaxy collection build` produces a `vyos-vyos-<version>.tar.gz`.
+- Install local dev: `ansible-galaxy collection install . --force`.
+- Test (unit): `ansible-test units` (matches `unit-galaxy` CI job; requires collection installed under `~/.ansible/collections/`). Fast local alternative: `source .venv/bin/activate && PYTHONPATH=".collections" python -m pytest tests/unit` (matches `unit-source` CI path; config in `pyproject.toml`). CI (`.github/workflows/tests.yml`) runs the changelog / build-import / ansible-lint / sanity / unit-galaxy / unit-source jobs; integration tests live under `tests/integration/` but are not yet wired into CI. Per `README.md`, the collection targets VyOS 1.3.8 / 1.4.1 / 1.5-rolling (no version matrix in the workflow itself).
+
+## Repository layout
+- `plugins/{action,cliconf,doc_fragments,filter,inventory,module_utils,modules,terminal}/` — collection content.
+- `tests/` — sanity, unit, integration directories. CI (`.github/workflows/tests.yml`) runs sanity + unit-galaxy + unit-source (plus changelog / build-import / ansible-lint); integration is not yet wired into CI.
+- `docs/` — generated module docs.
+- `meta/`, `changelogs/`, `CHANGELOG.rst` — Galaxy + release metadata.
+- `pyproject.toml` (black/pytest config), `.flake8`, `.isort.cfg`, `.ansible-lint`, `.pre-commit-config.yaml`.
+- `.github/workflows/` — `tests.yml`, `release.yml`, `codecoverage.yml`, `cla-check.yml`, `ah_token_refresh.yml`, `check_label.yaml`.
+
+## Cross-repo context
+- Consumed by Ansible users running playbooks against VyOS routers built by `vyos/vyos-build`.
+- The `vyos.vyos` collection talks to VyOS via `network_cli` connections; supports the same train branches (`current`, `circinus`, `sagitta`, `equuleus`).
+
+## Conventions
+- Commit headline: `T12345: description` (Phorge ID at https://vyos.dev mandatory). No workflow enforces PR title format in this repo.
+- Every PR must include exactly one changelog fragment under `changelogs/fragments/`; use `doc_changes` for documentation-only updates, or `trivial` for tooling / housekeeping changes.
+- Default branch `main` (not `current` — this repo predates the rename convention).
+- Issues tracked at https://vyos.dev (see `galaxy.yml`).
+- Codecov + CodeRabbit configured (`codecov.yml`, `.coderabbit.yaml`).
+
+## Notes for future contributors
+- Galaxy versioning is independent of VyOS train versioning — bump in `galaxy.yml` per release.
+- Tested matrix is in README; expand only after smoketesting against real images.
+- `PR408_README.md` plus `pr408-diagram.png` document a non-trivial historical refactor; read before touching resource-module structure.
diff --git a/changelogs/fragments/T8595_add_agents_md.yml b/changelogs/fragments/T8595_add_agents_md.yml
new file mode 100644
index 00000000..5d7fb0a4
--- /dev/null
+++ b/changelogs/fragments/T8595_add_agents_md.yml
@@ -0,0 +1,2 @@
+trivial:
+  - Add AGENTS.md tool-neutral contributor documentation, with .github/copilot-instructions.md symlink for Copilot code review compatibility.