ci: add CLAUDE.md and Copilot custom instructions (#1830)

* ci: add CLAUDE.md and GitHub Copilot custom instructions

Add AI assistant instructions to improve automated review quality:
- CLAUDE.md: project conventions, RST rules, linter details
- .github/copilot-instructions.md: repo-wide Copilot context
- .github/instructions/rst-linter.instructions.md: linter rules
  for RST files (address space, line length, suppression syntax)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* docs: fix build commands, code-block exemption, and address space heading

- Fix Docker build/run commands to match README (vyos/vyos-documentation
  image, /vyos mount, /vyos/docs workdir)
- Fix local build to run from docs/ directory
- Clarify code-block lines are exempt from 80-char limit
- Expand address space heading to reference docs/documentation.rst
- Fix confusing 0.0.0.0/0 entry in common mistakes
- Simplify inline code backtick example

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* docs: expand Copilot instructions to reduce false positive reviews

Add guidance for common false positives observed in automated reviews:
- Only flag issues introduced by the PR, not pre-existing
- Column-0 linter markers are the repo convention, not a bug
- Code-block lines are exempt from 80-char limit
- RFC 1918 and other private IPs are allowed without suppression
- TODO markers can be intentionally added for tracking
- YAML in code blocks uses RST-relative indentation

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* docs: fix backtick rendering and linter marker indentation guidance

- CLAUDE.md: use fenced code span to show RST double-backtick syntax
- copilot-instructions.md: markers match surrounding indentation inside
  directives, column 0 at top level (both patterns exist in repo)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

3 files changed, 256 insertions, 0 deletions

diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
new file mode 100644
index 00000000..dd18e7e6
--- /dev/null
+++ b/.github/copilot-instructions.md
@@ -0,0 +1,68 @@
+## VyOS Documentation Project
+
+This is VyOS user documentation written in reStructuredText (RST) and built with Sphinx.
+
+### Review Scope
+
+When reviewing pull requests, only flag issues **introduced by the PR's changes**. Do not flag pre-existing issues in unchanged lines. Compare against the base branch to determine what was actually changed.
+
+### RST Heading Hierarchy
+
+All files must use this heading order:
+
+```
+##### (Title — one per file, with overline)
+***** (Chapters)
+===== (Sections)
+----- (Subsections)
+^^^^^ (Subsubsections)
+""""" (Paragraphs)
+```
+
+### Line Length
+
+Maximum 80 characters per line. Exception: content inside `.. code-block::` directives is **exempt** — they render with `<pre>` tags and preserve source formatting. Do not flag long lines inside code blocks.
+
+### Linter Suppression Markers
+
+`.. stop_vyoslinter` and `.. start_vyoslinter` are RST comments used to suppress CI linter checks. Key conventions:
+
+- When used **inside an indented directive** (`.. cfgcmd::`, `.. opcmd::`, list items), markers should match the surrounding indentation to stay within the block.
+- When used **at top level** (outside any directive), markers are placed at column 0.
+- Both patterns exist in this repo. Do not flag either placement as incorrect.
+- They must always appear in pairs (stop then start). A missing `start_vyoslinter` is a real issue.
+- A `stop_vyoslinter` that covers a large section is acceptable when the content requires it (e.g., files full of real debug output with production IPs).
+
+### IP Address Rules
+
+The CI linter checks IP addresses. These are **allowed without suppression** — do not flag them:
+
+- RFC 5737 documentation addresses: `192.0.2.0/24`, `198.51.100.0/24`, `203.0.113.0/24`
+- RFC 3849 documentation IPv6: `2001:db8::/32`
+- RFC 1918 private ranges: `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`
+- Loopback (`127.0.0.0/8`), link-local (`169.254.0.0/16`), `0.0.0.0/0`
+
+Real public IPs (e.g., `8.8.8.8`) require `stop/start_vyoslinter` suppression. Do not suggest replacing them with documentation addresses if the example intentionally uses real IPs.
+
+### TODO Markers
+
+`.. TODO::` directives serve two purposes in this repo:
+
+1. **Tracking markers** on pages that need `cfgcmd`/`opcmd` conversion (these are intentionally added).
+2. **Stale markers** on pages that already have full content (these should be removed).
+
+A PR that removes some TODOs and adds others is not contradictory — the intent matters.
+
+### VyOS Directives
+
+- `.. cfgcmd::` for configuration mode commands
+- `.. opcmd::` for operational mode commands
+- Do not convert these to plain `.. code-block::` — they are tracked for command coverage.
+
+### YAML in Code Blocks
+
+Ansible playbook examples in `.. code-block::` use RST indentation (typically 4 spaces from the directive). The YAML indentation within the block may differ from standalone YAML files. Verify carefully before flagging YAML as invalid — count spaces from the code-block's own indentation base, not from column 0.
+
+### Page Structure
+
+Configuration pages follow this order: Theory, Configuration (cfgcmd), Examples, Known Issues, Debugging.
diff --git a/.github/instructions/rst-linter.instructions.md b/.github/instructions/rst-linter.instructions.md
new file mode 100644
index 00000000..419f094a
--- /dev/null
+++ b/.github/instructions/rst-linter.instructions.md
@@ -0,0 +1,70 @@
+---
+applyTo: "**/*.rst"
+---
+
+## RST Linter Rules
+
+Every pull request is automatically linted by `doc-linter.py` (from the `vyos/.github` repository). It checks **only changed files** for two things: IP address usage and line length.
+
+### IP Address Rules
+
+The linter rejects public IP addresses that are not reserved for documentation.
+
+**Use these documentation-reserved addresses (no suppression needed):**
+
+| Type | Range | RFC |
+|------|-------|-----|
+| IPv4 | `192.0.2.0/24` (TEST-NET-1) | RFC 5737 |
+| IPv4 | `198.51.100.0/24` (TEST-NET-2) | RFC 5737 |
+| IPv4 | `203.0.113.0/24` (TEST-NET-3) | RFC 5737 |
+| IPv6 | `2001:db8::/32` | RFC 3849 |
+
+**These are allowed without suppression (not flagged by linter):**
+
+| Type | Range | Why |
+|------|-------|-----|
+| RFC 1918 private | `10.0.0.0/8` | Private address space |
+| RFC 1918 private | `172.16.0.0/12` | Private address space |
+| RFC 1918 private | `192.168.0.0/16` | Private address space |
+| Loopback | `127.0.0.0/8` | Loopback range |
+| Link-local | `169.254.0.0/16` | Link-local |
+
+**These require `stop/start_vyoslinter` suppression:**
+
+| Example | Why suppression is needed |
+|---------|--------------------------|
+| `8.8.8.8` (Google DNS) | Real public IP, not documentation-reserved |
+| `64:ff9b::/96` (NAT64) | Well-known prefix, not in doc ranges |
+| Real provider IPs in examples | Authenticity matters for the example |
+
+### Line Length Rules
+
+Maximum 80 characters per line. Lines inside `.. code-block::` directives are **exempt** from the line length limit (they render with `<pre>` tags and preserve source formatting).
+
+### Suppression Syntax
+
+When real public IPs or long lines are unavoidable, wrap the block:
+
+```rst
+.. stop_vyoslinter
+
+.. code-block:: none
+
+   set system name-server '8.8.8.8'
+
+.. start_vyoslinter
+```
+
+**Rules for suppression markers:**
+
+- Place `.. stop_vyoslinter` on its own line, immediately before the content
+- Place `.. start_vyoslinter` on its own line, immediately after the content
+- Always re-enable the linter — never leave it stopped for the rest of the file
+- Suppress the smallest possible region
+- Do NOT use suppression for content that can use documentation-reserved addresses instead
+
+### Common Mistakes
+
+- Removing `stop/start_vyoslinter` markers without fixing the underlying issue (exposes the line to the linter and fails CI)
+- Using real public IPs when documentation addresses would work just as well
+- Adding suppression markers around content that only has private (RFC 1918) addresses or `0.0.0.0/0` — these are allowed and don't need suppression
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 00000000..d5330e0b
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,118 @@
+# VyOS Documentation
+
+RST documentation for VyOS, built with Sphinx and hosted on Read the Docs.
+
+## Build
+
+```bash
+# Docker (recommended)
+docker build -t vyos/vyos-documentation docker
+docker run --rm -it -v "$(pwd)":/vyos -w /vyos/docs \
+  -e GOSU_UID=$(id -u) -e GOSU_GID=$(id -g) \
+  vyos/vyos-documentation make html
+
+# Local (run from docs/ directory)
+pip install -r requirements.txt
+cd docs && make html
+```
+
+Output goes to `docs/_build/html/`.
+
+## RST Conventions
+
+### Heading Hierarchy
+
+```rst
+#####
+Title
+#####
+
+********
+Chapters
+********
+
+Sections
+========
+
+Subsections
+-----------
+
+Subsubsections
+^^^^^^^^^^^^^^
+
+Paragraphs
+""""""""""
+```
+
+Every RST file must start with a `#` overline+underline title.
+
+### Formatting Rules
+
+- 80 character line limit (except inside `.. code-block::`)
+- American English
+- Indent with 2 spaces
+- Leave a blank line before and after headers
+- Use double backticks for inline code: ``` ``command`` ```
+- Use `.. code-block:: none` for command/output blocks
+
+### Address Space
+
+See `docs/documentation.rst` for canonical rules. Per RFC 5737, RFC 3849, RFC 5389, and RFC 7042:
+
+The linter enforces documentation-reserved addresses. Use only:
+
+- IPv4: `192.0.2.0/24`, `198.51.100.0/24`, `203.0.113.0/24`
+- IPv6: `2001:db8::/32`
+- ASN: `64496-64511` (16-bit), `65536-65551` (32-bit)
+- MAC: `00-53-00` to `00-53-FF` (unicast), `90-10-00` to `90-10-FF` (multicast)
+
+**Allowed without suppression:**
+- RFC 1918 private ranges: `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`
+- Link-local, loopback, and other non-public ranges
+
+**Requires `stop/start_vyoslinter`:**
+- Real public IPs when needed for authenticity (e.g., `8.8.8.8` in DNS examples)
+- NAT64 well-known prefix `64:ff9b::/96`
+- Long URLs or certificate fingerprints that exceed 80 chars
+
+### Linter Suppression
+
+```rst
+.. stop_vyoslinter
+
+.. code-block:: none
+
+   content with real IPs or long lines here
+
+.. start_vyoslinter
+```
+
+Place markers immediately before/after the block they suppress. Always re-enable with `start_vyoslinter`.
+
+### VyOS-Specific Directives
+
+- `.. cfgcmd::` — configuration mode commands
+- `.. opcmd::` — operational mode commands
+- `.. cmdinclude::` — include command definitions from XML
+
+### Page Structure
+
+Each configuration page should contain:
+
+1. **Theory** — what it is, when to use it, relevant RFCs
+2. **Configuration** — all CLI options with `.. cfgcmd::` directives
+3. **Examples** — practical configurations with topology diagrams
+4. **Known issues** — problems and workarounds
+5. **Debugging** — log collection, `show` commands, state indicators
+
+## CI
+
+- **Linter** (`doc-linter.py` from `vyos/.github`): checks line length and IP addresses on changed files only
+- **Sphinx build**: runs on Read the Docs for each PR
+- **CLA check**: contributors must sign the CLA
+
+## Git Workflow
+
+- Base branch: `current`
+- Branch naming: `fix/docs-*`, `feat/docs-*`
+- PRs target `current` branch