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, 113 insertions, 0 deletions

diff --git a/docs/installation/image.md b/docs/installation/image.md
new file mode 100644
index 00000000..a0fc89d4
--- /dev/null
+++ b/docs/installation/image.md
@@ -0,0 +1,113 @@
+---
+lastproofread: '2026-01-26'
+---
+
+(image-mgmt)=
+
+# Image Management
+
+VyOS uses an image-based installation that creates a directory for each image
+on the storage device you select during installation.
+
+The boot device has the following directory structure:
+
+```none
+/
+/boot
+/boot/grub
+/boot/2025.07.16-0020-rolling.squashfs
+```
+
+The image directory contains the system kernel, a compressed root filesystem
+image, and a directory for persistent storage (such as configuration). During
+boot, the system extracts the OS image into memory and mounts the appropriate
+live-rw subdirectories to provide persistent storage for system configuration.
+
+This process ensures that the system always boots to a known working state,
+since the OS image is fixed and non-persistent. You can also install multiple
+VyOS releases on the same storage device. You can manually select the image at
+boot if needed, but the system boots the default image by default.
+
+```{opcmd} show system image
+
+List all available system images which can be booted on the current system.
+
+:::{code-block} none
+vyos@vyos:~$ show system image
+Name                     Default boot    Running
+-----------------------  --------------  ---------
+2025.07.16-0020-rolling  Yes             Yes
+1.4.1
+1.4.0
+:::
+```
+```{opcmd} delete system image [image-name]
+
+   Delete unused images from the system. You can specify an optional image name
+   to delete. Use the {opcmd}`show system image` command to list available
+   images.
+
+   :::{code-block} none
+   vyos@vyos:~$ delete system image
+   The following images are installed:
+           1: 2025.07.16-0020-rolling (running) (default boot)
+           2: 1.4.1
+           3: 1.4.0
+   Select an image to delete: 3
+   Do you really want to delete the image 1.4.0? [y/N] y
+   The image "1.4.0" was successfully deleted
+   :::
+```
+
+
+```{opcmd} show version
+
+Show current system image version.
+
+:::{code-block} none
+vyos@vyos:~$ show version
+Version:          VyOS 2025.07.16-0020-rolling
+Release train:    current
+Release flavor:   generic
+
+Built by:         autobuild@vyos.net
+Built on:         Wed 16 Jul 2025 00:21 UTC
+Build UUID:       20d432ee-6d55-4ebc-8462-46fe836246c9
+Build Commit ID:  f7ce0d8a692f2d
+
+Architecture:     x86_64
+Boot via:         installed image
+System type:      KVM guest
+Secure Boot:      n/a (BIOS)
+
+Hardware vendor:  QEMU
+Hardware model:   Standard PC (i440FX + PIIX, 1996)
+Hardware S/N:
+Hardware UUID:    b9831d42-c1fe-b2bd-7d3d-49db9418f5c9
+
+Copyright:        VyOS maintainers and contributors
+:::
+```
+
+## System rollback
+
+To roll back to a previous image, first view the available images by using the
+{opcmd}`show system image` command, then select your image with the following
+command:
+
+```{opcmd} set system image default-boot [image-name]
+
+Select the default boot image which will be started on the next boot
+of the system.
+```
+
+Then reboot the system.
+
+:::{note}
+VyOS automatically associates the configuration with each image,
+so you don't need to manage this separately. Each image has its own unique
+configuration copy.
+:::
+
+If you have console access, you can also select the boot image by restarting
+the system and using the GRUB menu at startup.