feat: flip swap mechanism — MD as primary, RST as override (Phase 1)

This is the first of three phases inverting the per-page swap mechanism
so MD becomes the canonical primary and RST becomes the rare override.

Phase 1 — file renames + conf.py exclude_patterns flip only:
- Rename docs/**/md-<stem>.md to docs/**/<stem>.md (drop md- prefix)
  for all 254 stems previously listed in docs/_swap.txt
- Rename docs/**/<stem>.rst to docs/**/rst-<stem>.rst (add rst- prefix)
  for the same 254 stems
- Repurpose docs/_swap.txt as docs/_rst_overrides.txt; initially empty
  comment-only since no pages need the RST fallback right now
- conf.py exclude_patterns flipped: rst-*.rst is now excluded by default
  instead of md-*.md
- conf.py runtime-artifact references updated to _rst_override_state.json
  and _md_exclude.txt (Phase 2 will rewrite swap_sources.py to produce
  these names; for now no swap script runs because overrides list is empty)

Phase 2 (next commit on this branch) will rewrite scripts/swap_sources.py
with inverted rename direction, delete scripts/import_myst.py + tests, and
update tests/test_swap_sources.py for the new semantics.

Phase 3 will be the cleanup pass and ready-for-review flip.

Generated by robots https://vyos.io

1 files changed, 0 insertions, 378 deletions

diff --git a/docs/automation/md-cloud-init.md b/docs/automation/md-cloud-init.md
deleted file mode 100644
index b6350b54..00000000
--- a/docs/automation/md-cloud-init.md
+++ /dev/null
@@ -1,378 +0,0 @@
----
-lastproofread: '2026-04-13'
----
-
-(cloud-init)=
-
-# VyOS cloud-init
-
-VyOS instances in cloud and virtualized environments are initialized using the
-industry-standard `cloud-init`. Through `cloud-init`, VyOS injects SSH
-keys, configures network settings, and applies custom configurations during the
-initial instance boot.
-
-## Configuration sources
-
-VyOS `cloud-init` obtains configuration data from the following sources:
-
-- `meta-data`: Instance-specific details provided by the cloud platform or
-  hypervisor. In some cloud environments, this data is available via an HTTP
-  endpoint at `http://169.254.169.254`.
-- `network configuration`: Network settings such as IP addresses, routes, and
-  DNS (only available on certain cloud and virtualization platforms).
-- `user-data`: User-supplied CLI configuration commands.
-
-## User-data
-
-Major cloud providers support injecting `user-data` as plain text or base64
-encoding text during initial instance boot. As `user-data` has a strict size
-limit of \~16384 bytes, long configuration command lists can be compressed using
-`gzip`.
-
-The recommended method for configuring VyOS instances via `user-data` is to
-use the `cloud-config` syntax described below.
-
-## Cloud-config modules
-
-By default, VyOS enables only two `cloud-config` modules:
-
-- `write_files`: Inserts user-provided files such as encryption keys,
-  certificates, or `config.boot` into the filesystem during the initial
-  instance boot. See [Cloud-init-write_files] for file syntax and file format
-  requirements.
-- `vyos_userdata`: Executes user-provided CLI configuration commands during
-  the initial instance boot.
-
-The files to insert and the CLI commands to execute must be provided in a
-`cloud-config` YAML file.
-
-## Cloud-config file format
-
-`cloud-config` files are written in YAML and must begin with the
-`#cloud-config` line. Only `vyos_config_commands` and `write_files` are
-supported as top-level keys. The use of these keys is described in the
-following two sections.
-
-## Vyos_config_commands key
-
-Use the `vyos_config_commands` key to define configuration commands for
-initializing your VyOS instance. Commands must follow the set-style syntax
-and can include both `set` and `delete` statements.
-
-Syntax requirements:
-
-- Place one command per line.
-- Enclose values in single quotes.
-- Avoid single quotes within commands or values.
-
-Applying commands from `cloud-config` overrides both settings configured via
-`meta-data` and default VyOS settings. After commands are applied,
-`cloud-init` automatically performs `commit` and `save`.
-
-The following is an example of a `cloud-config` file:
-
-```yaml
-#cloud-config
-vyos_config_commands:
-  - set system host-name 'vyos-prod-ashburn'
-  - set service ntp server 1.pool.ntp.org
-  - set service ntp server 2.pool.ntp.org
-  - delete interfaces ethernet eth1 address 'dhcp'
-  - set interfaces ethernet eth1 address '192.0.2.247/24'
-  - set protocols static route 198.51.100.0/24 next-hop '192.0.2.1'
-```
-
-
-### Instance defaults/fallbacks
-
-If no external configuration data is provided, VyOS applies the following
-defaults:
-
-- **SSH:** port 22.
-- **Credentials:** `vyos`/`vyos`.
-- **Networking:** DHCP is enabled on the first Ethernet interface.
-
-All defaults can be overridden via `user-data` configurations.
-
-## Write_files key
-
-VyOS allows you to run custom scripts during the initial instance boot to
-execute operational, configuration, and standard Linux commands.
-
-Use the `write_files` key to insert these scripts into the
-`/opt/vyatta/etc/config/scripts/` directory.
-
-Depending on when your commands need to run, use one of the following paths:
-
-- `/opt/vyatta/etc/config/scripts/vyos-preconfig-bootup.script`: Commands
-  defined here are executed before the system configuration is applied.
-- `/opt/vyatta/etc/config/scripts/vyos-postconfig-bootup.script`: Commands
-  defined here are executed after the system configuration is applied.
-
-In both cases, commands are executed with `root` privileges.
-
-:::{note}
-Use the `/opt/vyatta/etc/config/` path instead of `/config/scripts/` as
-referenced in the {ref}`command-scripting` section. The `/config/scripts/`
-directory is not mounted when the `write_files` module runs.
-:::
-
-The following example shows how to use `write_files` to execute an
-operational command **after** the initial configuration is complete:
-
-```yaml
-#cloud-config
-write_files:
-  - path: /opt/vyatta/etc/config/scripts/vyos-postconfig-bootup.script
-    owner: root:vyattacfg
-    permissions: '0775'
-    content: |
-      #!/bin/vbash
-      source /opt/vyatta/etc/functions/script-template
-      filename=/tmp/bgp_status_`date +"%Y_%m_%d_%I_%M_%p"`.log
-      run show ip bgp summary >> $filename
-```
-
-You can combine standard Linux commands to fetch data and VyOS configuration
-commands (like `set` and `commit`) in the same script.
-
-The following example sets the `hostname` based on the instance identifier
-obtained from the EC2 Instance Metadata Service (IMDS).
-
-```yaml
-#cloud-config
-write_files:
-  - path: /opt/vyatta/etc/config/scripts/vyos-postconfig-bootup.script
-    owner: root:vyattacfg
-    permissions: '0775'
-    content: |
-      #!/bin/vbash
-      source /opt/vyatta/etc/functions/script-template
-      hostname=`curl -s http://169.254.169.254/latest/meta-data/instance-id`
-      configure
-      set system host-name $hostname
-      commit
-      exit
-```
-
-
-## NoCloud
-
-Injecting configuration data is not limited to cloud platforms. The NoCloud
-data source allows you to inject `user-data` and `meta-data` on
-virtualization platforms such as VMware, Hyper-V, and KVM.
-
-The simplest way to use the NoCloud data source is to create a `seed.iso`
-file and attach it to the virtual machine as a CD drive. The volume must be
-formatted as a VFAT or ISO 9660 file system with the label `cidata` or
-`CIDATA`.
-
-Create text files named `user-data` and `meta-data`. On Linux-based
-systems, use the `mkisofs` utility to create the `seed.iso` file. The
-following syntax adds these files to the ISO 9660 file system:
-
-```none
-mkisofs -joliet -rock -volid "cidata" -output seed.iso meta-data user-data
-```
-
-Once generated, attach the `seed.iso` file to your virtual machine. The
-following example shows how to attach the file as a CD drive using KVM:
-
-```none
-$ virt-install -n vyos_r1 \
-   --ram 4096 \
-   --vcpus 2 \
-   --cdrom seed.iso \
-   --os-type linux \
-   --os-variant debian10 \
-   --network network=default \
-   --graphics vnc \
-   --hvm \
-   --virt-type kvm \
-   --disk path=/var/lib/libvirt/images/vyos_kvm.qcow2,bus=virtio \
-   --import \
-   --noautoconsole
-```
-
-For more information on the NoCloud data source, visit the [NoCloud] page in
-the `cloud-init` documentation.
-
-## Troubleshooting
-
-If your configuration does not apply as expected, follow these troubleshooting
-steps:
-
-1. **Validate your YAML**: Ensure your `cloud-config` file follows proper
-   YAML syntax. Online resources such as [YAML Lint](https://www.yamllint.com/)
-   provide simple validation tools.
-2. **Check the logs**: `cloud-init` writes logs to `/var/log/cloud-init.log`.
-   Filter for VyOS-specific entries using:
-
-```none
-sudo grep vyos /var/log/cloud-init.log
-```
-
-
-## Cloud-init on Proxmox
-
-Before you begin, review the `cloud-init` [network-config-docs] to
-understand how to import user and network configuration data.
-
-Key considerations:
-
-- Define VyOS configuration commands in the `user-data` file.
-- Avoid including network configuration data in the `user-data` file.
-- If no network configuration data is provided, the DHCP client is enabled on
-  the first interface. This happens at the OS level and is not reflected in the
-  VyOS CLI.
-
-The following example shows how to disable the DHCP client on `eth0` to
-address this behavior.
-
-In this example:
-
-- **Proxmox IP address**: `192.168.0.253/24`.
-- **Storage**: The `local` volume is mounted at `/var/lib/vz` and contains
-  all content types, including snippets.
-
-The goal is to remove the default DHCP client from the first interface and
-apply a custom configuration during the initial instance boot using
-`cloud-init`.
-
-### Generate .qcow2 image
-
-First, generate a VyOS `.qcow2` image with `cloud-init` support from the
-[vyos-vm-images] repository:
-
-1. Clone the `vyos-vm-images` repository and comment out the `download-iso`
-   role in `qemu.yml`.
-2. Download your preferred VyOS `.iso` file and save it as `/tmp/vyos.iso`.
-3. Generate the `.qcow2` image (using a 10G disk size for this example):
-
-```sh
-sudo ansible-playbook qemu.yml -e disk_size=10 \
- -e iso_local=/tmp/vyos.iso -e grub_console=serial -e vyos_version=1.5.0 \
- -e cloud_init=true -e cloud_init_ds=NoCloud
-```
-
-This generates your new image at `/tmp/vyos-1.5.0-cloud-init-10G-qemu.qcow2`.
-
-4. Copy the resulting image to the Proxmox server:
-
-```sh
-sudo scp /tmp/vyos-1.5.0-cloud-init-10G-qemu.qcow2 root@192.168.0.253:/tmp/
-```
-
-
-### Prepare cloud-init files
-
-Create the following files on your Proxmox server to proceed with this setup:
-
-- `user-data`: Contains VyOS configuration commands.
-- `network-config`: Disables the DHCP client on the first interface.
-- `meta-data`: An empty file (required by `cloud-init`).
-
-All files must be placed in the `/tmp/` directory.
-
-Follow these steps to create the required files:
-
-1. Navigate to the `/tmp/` directory:
-
-   ```sh
-   cd /tmp/
-   ```
-
-2. Create the `user-data` file. Begin the file with `#cloud-config` and
-   include VyOS configuration commands.
-
-   ```none
-   #cloud-config
-   vyos_config_commands:
-     - set system host-name 'vyos-BRAS'
-     - set service ntp server '1.pool.ntp.org'
-     - set service ntp server '2.pool.ntp.org'
-     - delete interfaces ethernet eth0 address 'dhcp'
-     - set interfaces ethernet eth0 address '198.51.100.2/30'
-     - set interfaces ethernet eth0 description 'WAN - ISP01'
-     - set interfaces ethernet eth1 address '192.168.25.1/24'
-     - set interfaces ethernet eth1 description 'Coming through VLAN 25'
-     - set interfaces ethernet eth2 address '192.168.26.1/24'
-     - set interfaces ethernet eth2 description 'Coming through VLAN 26'
-     - set protocols static route 0.0.0.0/0 next-hop '198.51.100.1'
-   ```
-
-3. Create the `network-config` file. Include the following:
-
-   ```none
-   version: 2
-   ethernets:
-     eth0:
-       dhcp4: false
-       dhcp6: false
-   ```
-
-4. Create the required empty `meta-data` file.
-
-### Create seed.iso
-
-Once you have created the necessary files, generate the `seed.iso` image and
-mount it as a CD drive to the new VM.
-
-```sh
-mkisofs -joliet -rock -volid "cidata" -output seed.iso meta-data \
-user-data network-config
-```
-
-:::{note}
-Be careful while copying and pasting the above commands. Double quotes may need
-to be corrected.
-:::
-
-### Create the VM
-
-Note that the following settings apply to this particular example and may
-require adjustment for other setups:
-
-- **VM ID**: `555`.
-- **VM and .iso file storage**: The local volume (`directory` type,
-  mounted at `/var/lib/vz`).
-- **VM resources**: Can be modified as needed.
-
-The `seed.iso` file was previously created in the `/tmp/` directory. Move
-it to `/var/lib/vz/template/iso`:
-
-```sh
-mv /tmp/seed.iso /var/lib/vz/template/iso/
-```
-
-On the Proxmox server:
-
-```none
-## Create VM, import disk and define boot order
-qm create 555 --name vyos-1.5.0-cloudinit --memory 1024 --net0 virtio,bridge=vmbr0
-qm importdisk 555 vyos-1.5.0-cloud-init-10G-qemu.qcow2 local
-qm set 555 --virtio0 local:555/vm-555-disk-0.raw
-qm set 555 --boot order=virtio0
-
-## Import seed.iso for cloud init
-qm set 555 --ide2 media=cdrom,file=local:iso/seed.iso
-
-## Since this server has 1 nic, lets add network intefaces (vlan 25 and 26)
-qm set 555 --net1 virtio,bridge=vmbr0,firewall=1,tag=25
-qm set 555 --net2 virtio,bridge=vmbr0,firewall=1,tag=26
-```
-
-
-### Power on and verify the VM
-
-Power on the VM using the CLI or GUI. After it boots, verify the configuration.
-
-### References
-
-- Cloud-init [network-config-docs].
-- Proxmox [Cloud-init-Support].
-[cloud-init-support]: <https://pve.proxmox.com/pve-docs/pve-admin-guide.html#qm_cloud_init>
-[cloud-init-write_files]: https://cloudinit.readthedocs.io/en/latest/topics/examples.html#writing-out-arbitrary-files
-[network-config-docs]: https://cloudinit.readthedocs.io/en/latest/topics/network-config.html
-[nocloud]: https://cloudinit.readthedocs.io/en/latest/reference/datasources/nocloud.html
-[vyos-vm-images]: https://github.com/vyos/vyos-vm-images