Improving the catalogue docs

docs/maintainers/catalogue.md

@@ -8,7 +8,7 @@ title: The Recipe Catalogue
 > `coop-cloud` "Organisation" on https://git.coopcloud.tech. 
 >
 > This is a temporary  situation, we want to open out this process & also introduce some automation 
-> to support making thie process more convenient. Please nag us to move things along.
+> to support making thie process more convenient. Please nag us to move things along on Matrix.
 
 - Publish your new recipe on the [git.coopcloud.tech](https://git.coopcloud.tech/coop-cloud) "Organisation"
 - Run `abra catalogue generate <recipe> -p`
@@ -26,36 +26,7 @@ For now, it is best to [get in touch](https://docs.coopcloud.tech/intro/contact/
 
 In the future, we'd like to support [multiple catalogues](https://git.coopcloud.tech/toolshed/organising/issues/139).
 
-## How do I generate the recipe catalogue
+## How do I make the catalogue automatically regenerate after new recipe versions are published? 
-
-To generate an entire new copy of the catalogue:
-
-```
-abra catalogue generate
-```
-
-You will most likely want to pass `--user/--username` / `--pass/--password` with container regsitry credentials to avoid rate limiting.
-
-If you just want to generate a catalogue entry for a single recipe:
-
-```
-abra catalogue generate <recipe>
-```
-
-The changes are generated and added to `~/.abra/catalogue`, you can validate what is done by running:
-
-```
-cd ~/.abra/catalogue
-git diff
-```
-
-You can pass `--publish` to have `abra` automatically publish those changes.
-
-!!! warning "Here be more SSH dragons"
-
-    In order to have `abra` publish changes for you automatically, you'll have to have write permissons to the git.coopcloud.tech repository and your account must have a working SSH key configuration. `abra` will use the SSH based URL connection details for Git by automagically creating an `origin-ssh` remote in the repository and pushing to it.
-
-## How do I make the catalogue automatically regenerate after new versions are published? 
 
 "I'd like to make it so that whenever I push a new git tag to the
 [`coop-cloud/rallly` repository](https://git.coopcloud.tech/coop-cloud/rallly)
@@ -90,3 +61,35 @@ The expectation is that this repo will only be updated automatically. While manu
 Automatic regeneration is handled by this Drone step, in the separate `auto-recipes-catalogue-json` repo: https://git.coopcloud.tech/toolshed/auto-recipes-catalogue-json/src/branch/main/.drone.yml#L5-L25
 
 This is run on a daily schedule (question: where is `nightly-app-date` configured?), and can also be triggered by recipe repositories to make new versions available quicker – see "[How do I make the catalogue automatically regenerate after new versions are published?](#how-do-i-make-the-catalogue-automatically-regenerate-after-new-versions-are-published)" above.
+
+## How do I manually generate the recipe catalogue
+
+> These days, doing this is only useful in the event of troubleshooting the automatic catalogue regeneration
+
+To generate an entire new copy of the catalogue:
+
+```
+abra catalogue generate
+```
+
+You will most likely want to pass `--user/--username` / `--pass/--password` with container regsitry credentials to avoid rate limiting.
+
+If you just want to generate a catalogue entry for a single recipe:
+
+```
+abra catalogue generate <recipe>
+```
+
+The changes are generated and added to `~/.abra/catalogue`, you can validate what is done by running:
+
+```
+cd ~/.abra/catalogue
+git diff
+```
+
+You can pass `--publish` to have `abra` automatically publish those changes.
+
+!!! warning "Here be more SSH dragons"
+
+    In order to have `abra` publish changes for you automatically, you'll have to have write permissons to the git.coopcloud.tech repository and your account must have a working SSH key configuration. `abra` will use the SSH based URL connection details for Git by automagically creating an `origin-ssh` remote in the repository and pushing to it.
+