nmstate · ihuguet · May 7, 2026 · May 7, 2026 · May 7, 2026 · May 7, 2026
diff --git a/demos.md b/demos.md
diff --git a/devel/design/networking-api.md b/devel/design/networking-api.md
@@ -2,7 +2,8 @@
 
 This document was created over the year 2018, much before this git repository
 and web site were a reality. It presents the original design of Nmstate and
-provides the motiviation for its existence.
+provides the motivation for its existence. It doesn't accurately reflect the
+current state and design of the project.
 
 ## OVERVIEW
 Networking has always been a major subsystem in the Linux ecosystem. Its

diff --git a/devel/dev_guide.md b/devel/dev_guide.md
diff --git a/index.md b/index.md
@@ -7,6 +7,7 @@ host networking settings in a declarative manner.
 The networking state is described by a pre-defined schema.
 Reporting of current state and changes to it (desired state) both conform to
 the schema.
+Changes to the current state are applied in a stateless and idempotent manner.
 
 Nmstate is aimed to satisfy enterprise needs to manage host networking through
 a northbound declarative API and multi provider support on the southbound.
@@ -71,12 +72,13 @@ interfaces:
 
 ## Documentation
 - [Nmstate Quick Start Guide](./user/quick_guide.md)
-- [Nmstate Developer Guide](./devel/dev_guide.md)
-- [Design](./devel/design/networking-api.md)
+- [Nmstatectl (CLI tool)](./user/cli_guide.md)
+- [Nmstate contribution guide](https://github.com/nmstate/nmstate/blob/base/CONTRIBUTING.md)
 - [YAML API documentation](./devel/yaml_api.md)
 - [Rust API document](https://docs.rs/nmstate)
-- [Python API documentation](./devel/api.md)
+- [Python API documentation (unmantained doc, see YAML API instead)](./devel/api.md)
 - [Nmpolicy](./nmpolicy)
+- [Original design and motivation](./devel/design/networking-api.md)
 - [Nmstate 1.x: Plugin Design(Deprecated)](./devel/plugin.md)
 - [Nmstate 1.x: Varlink support for libnmstate(Deprecated)](./devel/varlink-libnmstate.md)
 
@@ -85,12 +87,13 @@ interfaces:
 - [nm-configurator](https://github.com/suse-edge/nm-configurator)
 
 ## Contacts
-- You can find us on Matrix room: [`#nmstate:fedora.im`][matrix_room_url]
-The maintainers are Gris, edwardh and ffmancera, please feel free to ask
-whatever you need!
+- You can find us on Matrix room: [`#nmstate:fedora.im`][matrix_room_url],
+ please feel free to ask whatever you need!
+The current active maintainers are listed in [MAINTAINERS.md][MAINTAINERS.md].
 
 - Nmstate uses the [github issue][github_issue_url] for discussion or bug
  report.
 
 [github_issue_url]: https://github.com/nmstate/nmstate/issues
 [matrix_room_url]: https://matrix.to/#/#nmstate:fedora.im
+[MAINTAINERS.md]: https://github.com/nmstate/nmstate/blob/base/MAINTAINERS.md
diff --git a/cli_guide.md → user/cli_guide.md b/cli_guide.md → user/cli_guide.md
diff --git a/utils/ci_docker b/utils/ci_docker
diff --git a/utils/ci_docker_slow b/utils/ci_docker_slow
diff --git a/utils/ci_env b/utils/ci_env