From 5c9373d0c6e0457f47a67425285f5a641575fffd Mon Sep 17 00:00:00 2001 From: Yuriy Andamasov Date: Sun, 10 May 2026 19:45:32 +0300 Subject: docs: expand context7 rules — VyOS-specific LLM guardrails MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add 5 rules to `context7.json` targeting recurring LLM mistakes when answering VyOS questions through the context7-served index: 1. `commit` vs `save` semantics + verification step. Most common mistake: forgetting that `set/delete` are staged-only, that `commit` runs validation (failure = no change), and that `save` is a separate persistence step. 2. Image-based, not package-managed. Stops `apt install ` recommendations. Upgrade is `add system image ` then `set system image default-boot `. 3. No raw Linux commands for configuration (`ip`, `iptables`, `systemctl`, NetworkManager). They bypass the CLI and do not persist. 4. CLI quoting with single quotes for whitespace/special chars + hierarchical-path reminder (paths under a parent extend without re-stating it). 5. Routing protocols are FRR-backed but only the VyOS-CLI-exposed subset is valid. Synthesizing from FRR docs produces invalid VyOS commands. Reinforces existing rule 5 with the most common synthesis trap. Each rule fits the 255-char per-rule limit. Total now 11 of 50. Lower-priority candidates intentionally omitted (low LLM-mistake yield): `compare`/`discard`/`rollback` mechanics, interface naming conventions, `commit-confirm`, `load`/`merge`, Equuleus EOL status — already implicit in the version-branches rule. 🤖 Generated by [robots](https://vyos.io) --- context7.json | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/context7.json b/context7.json index f2bff61c..3eba41f9 100644 --- a/context7.json +++ b/context7.json @@ -28,7 +28,12 @@ "Configuration commands are wrapped in `cfgcmd` fenced blocks; operational commands in `opcmd` fenced blocks. Treat these as authoritative command syntax.", "Branch `rolling` tracks the rolling release and the next stable line. Branch `circinus` tracks 1.5.x. Branch `sagitta` tracks 1.4.x. Always cite version-appropriate documentation.", "Do not invent CLI commands. If a command isn't in the docs, say so rather than guess — VyOS syntax is strict and unknown commands fail validation at commit time.", - "Use reserved documentation IP space in examples: 192.0.2.0/24, 198.51.100.0/24, 203.0.113.0/24 (RFC 5737), 2001:db8::/32 (RFC 3849). Never use real or RFC1918 addresses." + "Use reserved documentation IP space in examples: 192.0.2.0/24, 198.51.100.0/24, 203.0.113.0/24 (RFC 5737), 2001:db8::/32 (RFC 3849). Never use real or RFC1918 addresses.", + "`commit` activates pending config and runs validation (errors = no change applied); `save` persists across reboot. `set`/`delete` alone are staged only. Verify with `show ` in op mode after commit. Always include both steps in examples.", + "VyOS is image-based, not package-managed. Upgrade with `add system image ` then `set system image default-boot `. Do not recommend `apt install` for VyOS components — it bypasses the image system and does not survive reboot.", + "Do not recommend raw Linux commands (`ip`, `iptables`, `systemctl`, NetworkManager) for VyOS configuration — they bypass the CLI and do not persist. Use `set/delete/commit/save`. Read-only Linux inspection from op mode is fine.", + "Quote CLI string values that contain spaces or special characters with single quotes (e.g. `set system host-name 'edge-01'`). Configuration is hierarchical — paths under a parent (e.g. `set firewall name FOO rule 10`) extend without re-stating it.", + "Routing protocols (BGP, OSPF, IS-IS, RIP) are FRR-backed, but not every FRR knob is exposed through the VyOS CLI. Confirm a command exists in the VyOS docs before suggesting it — synthesizing from FRR documentation produces invalid VyOS commands." ], "previousVersions": [ { "tag": "1.5" }, -- cgit v1.2.3 From 96e06fadd4790b43f51abaf11e6ec30fa698879f Mon Sep 17 00:00:00 2001 From: Yuriy Andamasov Date: Sun, 10 May 2026 20:43:52 +0300 Subject: docs: address review on context7 rules — op-mode set/add, edit-subtree MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Three corrections from Copilot review on #1946: Rule 2: Mode framing was technically wrong. `set ... ` is not unique to config mode — op mode has its own `set`/`add` commands for image management (`add system image`, `set system image default-boot`). Replace the `set/delete/show` listing with mode entry mechanics (`configure` enters config; op mode is the default after login) and acknowledge image-mgmt commands live in op mode. Rule 8: `add system image` and `set system image default-boot` are operational-mode commands (verified: docs/installation/update.md wraps `add system image` in `{opcmd}`; docs/installation/image.md does the same for `set system image default-boot`). The upgrade also is not in effect until reboot. Update to: op mode + reboot to activate. Rule 10: "Configuration is hierarchical — paths extend without re-stating it" was misleading. At the top level (just after `configure`), every `set`/`delete` line must include the full path. Relative paths only work inside an `edit ` context. The original phrasing would have led an LLM to omit parent nodes and emit invalid CLI examples. All revised rules verified ≤255 chars. 🤖 Generated by [robots](https://vyos.io) --- context7.json | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/context7.json b/context7.json index 3eba41f9..404fe797 100644 --- a/context7.json +++ b/context7.json @@ -24,15 +24,15 @@ ], "rules": [ "Documentation sources are MyST Markdown (.md). Cite and link to the .md form.", - "VyOS has two CLI modes: configuration mode (`set ...`, `delete ...`, `commit`, `save`) and operational mode (`show ...`, `monitor ...`, `restart ...`). Do not mix them.", + "VyOS has two CLI modes: configuration mode (entered via `configure`; uses `set`/`delete`/`commit`/`save`) and operational mode (default after login; uses `show`/`monitor`/`restart`, plus image-mgmt commands like `add system image`). Do not mix.", "Configuration commands are wrapped in `cfgcmd` fenced blocks; operational commands in `opcmd` fenced blocks. Treat these as authoritative command syntax.", "Branch `rolling` tracks the rolling release and the next stable line. Branch `circinus` tracks 1.5.x. Branch `sagitta` tracks 1.4.x. Always cite version-appropriate documentation.", "Do not invent CLI commands. If a command isn't in the docs, say so rather than guess — VyOS syntax is strict and unknown commands fail validation at commit time.", "Use reserved documentation IP space in examples: 192.0.2.0/24, 198.51.100.0/24, 203.0.113.0/24 (RFC 5737), 2001:db8::/32 (RFC 3849). Never use real or RFC1918 addresses.", "`commit` activates pending config and runs validation (errors = no change applied); `save` persists across reboot. `set`/`delete` alone are staged only. Verify with `show ` in op mode after commit. Always include both steps in examples.", - "VyOS is image-based, not package-managed. Upgrade with `add system image ` then `set system image default-boot `. Do not recommend `apt install` for VyOS components — it bypasses the image system and does not survive reboot.", + "VyOS is image-based, not package-managed. Upgrade in op mode: `add system image `, optionally `set system image default-boot `, then `reboot` to activate. Do not recommend `apt install` for VyOS components — it bypasses the image system.", "Do not recommend raw Linux commands (`ip`, `iptables`, `systemctl`, NetworkManager) for VyOS configuration — they bypass the CLI and do not persist. Use `set/delete/commit/save`. Read-only Linux inspection from op mode is fine.", - "Quote CLI string values that contain spaces or special characters with single quotes (e.g. `set system host-name 'edge-01'`). Configuration is hierarchical — paths under a parent (e.g. `set firewall name FOO rule 10`) extend without re-stating it.", + "Quote CLI strings containing spaces or special chars with single quotes (e.g. `set system host-name 'edge-01'`). Top-level `set`/`delete` lines must include the full path; relative paths only work inside an `edit` subtree (e.g. `edit firewall name FOO`).", "Routing protocols (BGP, OSPF, IS-IS, RIP) are FRR-backed, but not every FRR knob is exposed through the VyOS CLI. Confirm a command exists in the VyOS docs before suggesting it — synthesizing from FRR documentation produces invalid VyOS commands." ], "previousVersions": [ -- cgit v1.2.3 From e5105c905e6bb4c0bdc2f4435687437c78fd27ad Mon Sep 17 00:00:00 2001 From: Yuriy Andamasov Date: Sun, 10 May 2026 21:48:58 +0300 Subject: docs: address review on context7 rules — show in both modes MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two more corrections from Copilot review on #1946: Rule 2: `show` exists in both modes. Config-mode `show` displays the working config (verified: `docs/cli.md:389` wraps `show` in `{cfgcmd}`). Op-mode `show` displays running state. Previous wording listed `show` under operational mode only, which contradicted `cli.md`. Reframe to list `show` in both, scoped to "config-state" vs running state. Rule 7: `show ` was hand-wavy and arguably invented syntax — conflicts with rule 5 ("do not invent CLI commands"). Replace with documented forms: `show ` (config mode, verified at `docs/cli.md:389`) or `show configuration commands` (op mode, verified at `docs/cli.md:224`). Both are direct quotes from the canonical CLI reference. 🤖 Generated by [robots](https://vyos.io) --- context7.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/context7.json b/context7.json index 404fe797..804004b2 100644 --- a/context7.json +++ b/context7.json @@ -24,12 +24,12 @@ ], "rules": [ "Documentation sources are MyST Markdown (.md). Cite and link to the .md form.", - "VyOS has two CLI modes: configuration mode (entered via `configure`; uses `set`/`delete`/`commit`/`save`) and operational mode (default after login; uses `show`/`monitor`/`restart`, plus image-mgmt commands like `add system image`). Do not mix.", + "VyOS has two CLI modes: configuration mode (entered via `configure`; for `set`/`delete`/`commit`/`save` and config-state `show`) and operational mode (default after login; for `show`, `monitor`, plus image-mgmt like `add system image`). Do not mix.", "Configuration commands are wrapped in `cfgcmd` fenced blocks; operational commands in `opcmd` fenced blocks. Treat these as authoritative command syntax.", "Branch `rolling` tracks the rolling release and the next stable line. Branch `circinus` tracks 1.5.x. Branch `sagitta` tracks 1.4.x. Always cite version-appropriate documentation.", "Do not invent CLI commands. If a command isn't in the docs, say so rather than guess — VyOS syntax is strict and unknown commands fail validation at commit time.", "Use reserved documentation IP space in examples: 192.0.2.0/24, 198.51.100.0/24, 203.0.113.0/24 (RFC 5737), 2001:db8::/32 (RFC 3849). Never use real or RFC1918 addresses.", - "`commit` activates pending config and runs validation (errors = no change applied); `save` persists across reboot. `set`/`delete` alone are staged only. Verify with `show ` in op mode after commit. Always include both steps in examples.", + "`commit` activates pending `set`/`delete` changes and runs validation (errors = no change applied); `save` persists across reboot. Verify with `show ` (config mode) or `show configuration commands` (op mode). Always include `commit` and `save`.", "VyOS is image-based, not package-managed. Upgrade in op mode: `add system image `, optionally `set system image default-boot `, then `reboot` to activate. Do not recommend `apt install` for VyOS components — it bypasses the image system.", "Do not recommend raw Linux commands (`ip`, `iptables`, `systemctl`, NetworkManager) for VyOS configuration — they bypass the CLI and do not persist. Use `set/delete/commit/save`. Read-only Linux inspection from op mode is fine.", "Quote CLI strings containing spaces or special chars with single quotes (e.g. `set system host-name 'edge-01'`). Top-level `set`/`delete` lines must include the full path; relative paths only work inside an `edit` subtree (e.g. `edit firewall name FOO`).", -- cgit v1.2.3