Docs: improve clanService docs

docs/mkdocs.yml

@@ -54,6 +54,7 @@ nav:
       - Deploy Machine: getting-started/deploy.md
       - Continuous Integration: getting-started/check.md
   - Guides:
+      - clanServices: guides/clanServices.md
       - Disk Encryption: getting-started/disk-encryption.md
       - Mesh VPN: getting-started/mesh-vpn.md
       - Backup & Restore: getting-started/backups.md
@@ -86,6 +87,7 @@ nav:
           - 03-adr-numbering-process: decisions/03-adr-numbering-process.md
           - Template: decisions/_template.md
       - Clan Services:
+          - reference/clanServices/index.md
           - reference/clanServices/admin.md
           - reference/clanServices/hello-world.md
           - reference/clanServices/wifi.md

docs/nix/render_options/__init__.py

@@ -438,6 +438,33 @@ def produce_clan_service_docs() -> None:
         msg = f"Environment variables are not set correctly: $out={OUT}"
         raise ClanError(msg)
 
+    indexfile = Path(OUT) / "clanServices/index.md"
+    indexfile.parent.mkdir(
+        parents=True,
+        exist_ok=True,
+    )
+    index = "# Clan Services\n\n"
+    index += """
+**`clanServices`** are modular building blocks that simplify the configuration and orchestration of multi-host services.
+
+Each `clanService`:
+
+* Is a module of class **`clan.service`**
+* Can define **roles** (e.g., `client`, `server`)
+* Uses **`inventory.instances`** to configure where and how it is deployed
+* Replaces the legacy `clanModules` and `inventory.services` system altogether
+
+!!! Note
+    `clanServices` are part of Clan's next-generation service model and are intended to replace `clanModules`.
+
+    See [Migration Guide](../../guides/migrate-inventory-services.md) for help on migrating.
+
+Learn how to use `clanServices` in practice in the [Using clanServices guide](../../guides/clanServices.md).
+"""
+
+    with indexfile.open("w") as of:
+        of.write(index)
+
     with Path(CLAN_MODULES_VIA_SERVICE).open() as f3:
         service_links: dict[str, dict[str, dict[str, Any]]] = json.load(f3)
 
@@ -527,6 +554,22 @@ def produce_clan_modules_docs() -> None:
         if frontmatter.description:
             output += f"*{frontmatter.description}*\n\n"
 
+        # 2. Deprecation note if the module is deprecated
+        if "deprecated" in frontmatter.features:
+            output += f"""
+!!! Warning "Deprecated"
+    The `{module_name}` module is deprecated.*
+
+    Use: [clanServices/{module_name}](../clanServices/{module_name}.md) instead
+"""
+        else:
+            output += f"""
+!!! Warning "Will be deprecated"
+    The `{module_name}` module might eventually be migrated to 'clanServices'*
+
+    See: [clanServices](../../guides/clanServices.md)
+"""
+
         # 3. Categories from README.md
         output += "## Categories\n\n"
         output += render_categories(frontmatter.categories, frontmatter.categories_info)

docs/site/guides/clanServices.md

@@ -0,0 +1,76 @@
+# Using `clanServices`
+
+Clan’s `clanServices` system is a composable way to define and deploy services across machines. It replaces the legacy `clanModules` approach and introduces better structure, flexibility, and reuse.
+
+This guide shows how to **instantiate** a `clanService`, explains how service definitions are structured in your inventory, and how to pick or create services from modules exposed by flakes.
+
+---
+
+## Overview
+
+A `clanService` is used in:
+
+```nix
+inventory.instances.<instance_name>
+```
+
+Each instance includes a reference to a **module specification** — this is how Clan knows which service module to use and where it came from.
+You can reference services from any flake input, allowing you to compose services from multiple flake sources.
+
+---
+
+## Basic Example
+
+Example of instantiating a `borgbackup` service using `clan-core`:
+
+```nix
+inventory.instances = {
+    # Arbitrary unique name for this 'borgbackup' instance
+    borgbackup-example = {
+        module =  {
+            name = "borgbackup";  # <-- Name of the module
+            input = "clan-core"; # <-- The flake input where the service is defined
+        };
+        # Participation of the machines is defined via roles
+        roles.client.machines."machine-a" = {};
+        roles.server.machines."backup-host" = {};
+    };
+}
+```
+
+If you used `clan-core` as an input attribute for your flake:
+
+```nix
+      # ↓ module.input = "clan-core"
+inputs.clan-core.url = "git+https://git.clan.lol/clan/clan-core"
+```
+
+## Picking a clanService
+
+You can use services exposed by Clan’s core module library, `clan-core`.
+
+🔗 See: [List of Available Services in clan-core](../reference/clanServices/index.md)
+
+## Defining Your Own Service
+
+You can also author your own `clanService` modules.
+
+🔗 Learn how to write your own service: [Authoring a clanService](../authoring/clanServices/index.md)
+
+You might expose your service module from your flake — this makes it easy for other people to also use your module in their clan.
+
+---
+
+## 💡 Tips for Working with clanServices
+
+* You can add multiple inputs to your flake (`clan-core`, `your-org-modules`, etc.) to mix and match services.
+* Each service instance is isolated by its key in `inventory.instances`, allowing you to deploy multiple versions or roles of the same service type.
+* Roles can target different machines or be scoped dynamically.
+
+---
+
+## What’s Next?
+
+* [Author your own clanService →](../authoring/clanServices/index.md)
+* [Migrate from clanModules →](../guides/migrate-inventory-services.md)
+<!-- TODO: * [Understand the architecture →](../explanation/clan-architecture.md) -->