general: T8595: restore richer AGENTS.md content from #5154

1 files changed, 93 insertions, 45 deletions

diff --git a/AGENTS.md b/AGENTS.md
index ee3e4f8ba..96ad48f9f 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,72 +1,120 @@
-# AGENTS.md — `vyos/vyos-1x`
+# AGENTS.md
 
 ## Project purpose
 
-The user-visible VyOS package: command definitions (XML), conf-mode and op-mode scripts, Jinja2 templates, validators, migration scripts, and the Python `vyos.*` library that all of the above import. This is the largest single VyOS package and the primary surface for new feature work in 1.4+.
+The user-visible VyOS package: command definitions (XML), conf-mode and op-mode
+scripts, Jinja2 templates, validators, migration scripts, and the Python
+`vyos.*` library imported by all of the above.
 
-## Tech stack
-
-- Python 3 (≥3.10) with `vyos.*` library under `python/vyos/`.
-- XML interface and op-mode definitions, Jinja2 templates under `data/templates/`.
-- C wrapper `libvyosconfig` (vendored at `libvyosconfig/`) — links statically against [`vyos/vyos1x-config`](https://github.com/vyos/vyos1x-config) (OCaml).
-- Build: Debian packaging via `debhelper` + `dh-python`. Build-deps in `debian/control` (see `protobuf-compiler`, `libpcre2-dev`, `libffi-dev`, `python3-vici`, `python3-fastapi`, ...).
-- Tests: `nose2` (`nose2.cfg`), Python `pylint`, ruff (`ruff.toml`).
+This is the largest single VyOS package and the primary surface for new feature
+work in 1.4+.
 
-## Build / test / run
+## Tech stack
 
-```
+- Python 3 (>=3.11) with the `vyos.*` library under `python/vyos/`.
+- XML interface definitions for configure mode (conf-mode) are located in
+  `interface-definitions/`. XML CLI building blocks can be split into include
+  files to reduce duplication. Include files are in
+  `interface-definitions/include/`.
+- XML definitions for operational mode (op-mode) CLI commands are stored in
+  `op-mode-definitions/`. They use the same include pattern as conf-mode.
+  Include files are in `op-mode-definitions/include/`.
+- Both conf-mode and op-mode make heavy use of Jinja2 as a templating engine.
+  Jinja2 templates are either inline Python strings or stored as discrete files
+  under `data/templates/`. Storing templates as files is preferred.
+- C wrapper `libvyosconfig` (vendored at `libvyosconfig/`) builds
+  `libvyosconfig.so.0` (shared library) using OCaml ctypes bindings against
+  [`vyos/vyos1x-config`](https://github.com/vyos/vyos1x-config).
+- Build: Debian packaging via `debhelper` + `dh-python`. Build dependencies are
+  in `debian/control` (for example: `protobuf-compiler`, `libpcre2-dev`,
+  `libffi-dev`, `python3-vici`, `python3-fastapi`, ...).
+- Tests: `nose2` (`nose2.cfg`), Python `pylint`, and ruff (`ruff.toml`).
+- Runtime smoketests are located under `smoketest/`. These tests are used by
+  `vyos-build` when assembling and testing ISO images.
+
+## Build instructions
+
+```bash
 # Debian package build (produces 6 binary packages)
 dpkg-buildpackage -uc -us -tc -b
-# Smoketests (against an installed VyOS, normally driven by vyos-build)
-./scripts/build-command-templates ...   # XML preprocessor
-make all                                # see Makefile targets
+# or
+make deb
+
+# In-tree build (XML preprocessing + shim compilation)
+make all  # see Makefile targets
 ```
 
-Produces: `vyos-1x`, `libvyosconfig0`, `vyos-1x-aws`, `vyos-1x-smoketest`, `vyos-1x-vmware`, `vyos-user-utils`.
+Produces: `vyos-1x`, `libvyosconfig0`, `vyos-1x-aws`, `vyos-1x-smoketest`,
+`vyos-1x-vmware`, `vyos-user-utils`.
+
+## Testing instructions
 
-Smoketests (`smoketest/`) run inside the QEMU harness invoked by `vyos-build`'s `scripts/check-qemu-install --smoketest`.
+Smoketests (`smoketest/`) run inside the QEMU harness invoked by
+`vyos-build`'s `scripts/check-qemu-install --smoketest`.
 
 ## Repository layout
 
-- `python/vyos/` — importable Python library (`config.py`, `configtree.py` ctypes wrapper, `configsession.py`, `firewall.py`, `frrender.py`, ifconfig drivers).
-- `src/conf_mode/` — set-mode entry-point scripts named after CLI components.
-- `src/op_mode/` — show/op-mode scripts.
-- `src/validators/` — value validators (Python; OCaml validators come from `vyos-utils`).
-- `src/migration-scripts/` — config-format migrations between releases.
-- `src/services/` — runtime services including the HTTP API implementation.
-- `interface-definitions/` — XML CLI declarations (preprocessed via `scripts/build-command-templates`, `scripts/override-default`, `scripts/transclude-template`).
-- `op-mode-definitions/` — op-mode XML.
-- `data/templates/` — Jinja2 outputs (FRR, strongSwan, nftables, dnsmasq, ...).
-- `libvyosconfig/` — C wrapper; source of the `libvyosconfig0` Debian package.
-- `smoketest/` — `nose2` CLI smoketests.
+- `python/vyos/` - importable Python library (`config.py`, `configtree.py`
+  ctypes wrapper, `configsession.py`, `firewall.py`, `frrender.py`, ifconfig
+  drivers).
+- `src/conf_mode/` - set-mode entry-point scripts named after CLI components.
+- `src/op_mode/` - show/op-mode scripts.
+- `src/validators/` - value validators (Python; OCaml validators come from
+  `src/ocaml/`).
+- `src/migration-scripts/` - config-format migrations between releases.
+- `src/services/` - runtime services, including the HTTP API implementation.
+- `interface-definitions/` - XML CLI declarations (preprocessed via
+  `scripts/build-command-templates`, `scripts/override-default`,
+  `scripts/transclude-template`).
+- `op-mode-definitions/` - op-mode XML.
+- `data/templates/` - Jinja2 input templates for third-party services consumed
+  by VyOS (FRR, strongSwan, nftables, dnsmasq, ...).
+- `libvyosconfig/` - C wrapper; source of the `libvyosconfig0` Debian package.
+- `smoketest/` - `nose2` CLI smoketests.
 - `schema/`, `mibs/`, `debian/`, `scripts/`.
 
 ## Cross-repo context
 
-- Imports `libvyosconfig0` (built from in-tree `libvyosconfig/`, which wraps `vyos/vyos1x-config`).
-- Calls OCaml validators from `vyos/vyos-utils` via `<validator name='...'/>` XML directives.
-- Listed in `VyOS-Networks/vyos-build-packages/repos.toml` as the canonical 14-repo build set; consumed by `vyos/vyos-build` at ISO assembly time.
-- `vyos/vyos-documentation` carries `docs/_include/vyos-1x` as a submodule **pinned to `sagitta`** — do not bump the doc submodule branch without a coordinated change.
-- `VyOS-Networks/vyos-1x` is the private mirror twin (canonical here). The `pr-mirror-repo-sync.yml` reusable workflow is live for this repo.
-- HTTP API runtime deps come from `vyos/vyos-http-api-tools`; the FastAPI implementation lives in `src/services/`.
-
-The standalone `VyOS-Networks/libvyosconfig` repo is a parallel mirror with its own pipeline; the canonical source for downstream Debian builds is the in-tree `libvyosconfig/` directory here.
+- Imports `libvyosconfig0` (built from in-tree `libvyosconfig/`, which wraps
+  `vyos/vyos1x-config`).
+- Calls OCaml validators from `src/ocaml/` via `<validator name='...'/>` XML
+  directives. OCaml validators reduce Python interpreter startup overhead and
+  make configuration commits faster.
+- `vyos/vyos-documentation` carries `docs/_include/vyos-1x` as a submodule
+  **pinned to `sagitta`** — do not bump the doc submodule branch without a
+  coordinated change.
+- `VyOS-Networks/vyos-1x` is the private mirror twin (canonical here). The
+  `pr-mirror-repo-sync.yml` reusable workflow is active for this repository.
+- HTTP API runtime dependencies come from `vyos/vyos-http-api-tools`; the
+  FastAPI implementation lives in `src/services/`.
 
 ## Conventions
 
-- Commit / PR title format: `component: T12345: description` (Phorge task ID at https://vyos.dev mandatory). Enforced by `vyos/.github/.github/workflows/check-pr-message.yml`.
-- Branch model: `current` (rolling, default), `circinus` (1.5 LTS), `sagitta` (1.4 LTS), `equuleus` (1.3 LTS). Backports via `@Mergifyio backport <branch>`.
-- Default-branch protection: 2 required approvals, status checks required.
-- Linting (`vyos/.github` reusables): ruff 0.6.4, darker, pylint W0611, Jinja2 lint. `ruff.toml` and `nose2.cfg` at repo root.
-- No `mergify.yml` — `vyos-1x` is one of the few mirror-pipeline consumers without it.
+- Commit/PR titles must follow: `component: T1234: description`. Phorge IDs are
+  at <https://vyos.dev>. This is enforced by the
+  `check-pr-message.yml` reusable workflow.
+- See `CONTRIBUTING.md` for additional commit message guidance.
+- Branch model: `current` (rolling, default), `circinus` (1.5 LTS), `sagitta`
+  (1.4 LTS), `equuleus` (1.3 LTS). Backports via
+  `@Mergifyio backport <branch>`.
+- Default-branch protection: 2 required approvals; required status checks.
+- Linting (`vyos/.github` reusables): ruff 0.6.4, darker, pylint W0611, Jinja2
+  lint. `ruff.toml` and `nose2.cfg` are at repository root.
+- No `mergify.yml` - `vyos-1x` is one of the few mirror-pipeline consumers
+  without it.
 
 ## Mirror relationship
 
-Mirror twin: `VyOS-Networks/vyos-1x`. Canonical side is **here** (`vyos/vyos-1x`). PRs merged on a release-train branch are mirrored downstream by `pr-mirror-repo-sync.yml`.
+- Mirror twin: `VyOS-Networks/vyos-1x`. The canonical side is here:
+  `vyos/vyos-1x`. PRs merged on a release-train branch are mirrored downstream
+  by `pr-mirror-repo-sync.yml`.
 
 ## Notes for future contributors
 
-- The vendored `libvyosconfig/` is **not** just a wrapper — it produces the `libvyosconfig0` Debian package. Edits there ripple to every consumer of the config-tree API.
-- New features go here, not in the legacy `vyatta-cfg*` repos.
-- 2 repo-level Actions secrets, 2 environments, 2 outbound webhooks (`ci.vyos.net`, `hooks.zapier.com`). Do not enumerate secret names in code or docs.
-- License: GPL/LGPL dual; see `LICENSE`, `LICENSE.GPL`, `LICENSE.LGPL`.
+- The vendored `libvyosconfig/` is **not** just a wrapper - it produces the
+  `libvyosconfig0` Debian package. Edits there affect every consumer of the
+  config-tree API.
+- New features go here, not in the legacy `vyatta-cfg*` repositories.
+- 2 repository-level Actions secrets, 2 environments, 2 outbound webhooks. Do
+  not enumerate secret names or infrastructure endpoints in code or docs.
+- License: GPL/LGPL dual; see `LICENSE`, `LICENSE.GPL`, `LICENSE.LGPL`.
\ No newline at end of file