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/index.md b/docs/index.md
new file mode 100644
index 00000000..359fea44
--- /dev/null
+++ b/docs/index.md
@@ -0,0 +1,113 @@
+(index)=
+
+# VyOS User Guide
+
+::::::{grid} 3
+:gutter: 2
+
+:::::{grid-item-card} Get / Build VyOS
+
+Quickly {ref}`Build<contributing/build-vyos:build vyos>`
+your own Image or take a look at how to
+{ref}`download<installation/install:download>`
+a free or supported version.
+:::::
+
+:::::{grid-item-card} Install VyOS
+
+Read about how to install VyOS on
+{ref}`Bare Metal<installation/install:installation>`
+or in a {ref}`VM <installation/virtual/index:Virtual Environments>`
+and how to use an image with the usual
+{ref}`cloud<installation/cloud/index:Cloud Environments>`
+providers
+:::::
+
+:::::{grid-item-card} Configuration and Operation
+
+Use the {ref}`Quickstart Guide<quick-start:Quick Start>`,
+to have a fast overview. Or go deeper and set up
+{ref}`advanced routing<configuration/protocols/index:protocols>`,
+{ref}`VRFs<configuration/vrf/index:vrf>`, or
+{ref}`VPNs<configuration/vpn/index:vpn>` for example.
+:::::
+
+:::::{grid-item-card} Automate
+
+Integrate VyOS in your automation Workflow with
+{ref}`Ansible<vyos-ansible>`,
+have your own {ref}`local scripts<command-scripting>`,
+or configure VyOS with the
+{ref}`HTTPS-API<vyosapi>`.
+:::::
+
+:::::{grid-item-card} Examples
+
+Get some inspiration from the
+{ref}`Blueprints <configexamples/index:Configuration Blueprints>`
+to build your infrastructure.
+:::::
+
+:::::{grid-item-card} Contribute and Community
+
+There are many ways to contribute to the project.
+Add missing parts or improve the
+{ref}`Documentation<documentation:Write Documentation>`.
+
+Discuss in [Slack](https://slack.vyos.io/)
+or the [Forum](https://forum.vyos.io).
+
+Or you can pick up a [Task](https://vyos.dev/)
+and fix the
+{ref}`code<contributing/development:development>`.
+:::::
+::::::
+
+```{toctree}
+:hidden: true
+:maxdepth: 1
+
+introducing/about
+introducing/history
+```
+
+```{toctree}
+:caption: First Steps
+:hidden: true
+:maxdepth: 2
+
+installation/index
+quick-start
+cli
+```
+
+```{toctree}
+:caption: Adminguide
+:hidden: true
+:maxdepth: 2
+
+configuration/index
+operation/index
+automation/index
+troubleshooting/index
+configexamples/index
+vpp/index
+```
+
+```{toctree}
+:caption: Development
+:hidden: true
+:maxdepth: 2
+
+contributing/index
+```
+
+```{toctree}
+:caption: Misc
+:hidden: true
+:maxdepth: 2
+
+documentation
+coverage
+copyright
+```