docs: document naming convention

See toolshed/organising#680

docs/abra/hack.md

@@ -30,8 +30,7 @@ Install [Go >= 1.16](https://golang.org/doc/install) and then:
 - `make build` to build. If this fails, run `go mod tidy`.
 - `./abra` to run commands
 - `make test` will run tests
-- `make install-abra` will install abra to `$GOPATH/bin`
-- `make install-kadabra` will install kadabra to `$GOPATH/bin`
+- `make install` will install abra to `$GOPATH/bin`
 - `go get <package>`, `go mod tidy` and `go mod vendor` to add a new dependency
 
 Our [Drone CI configuration](https://git.coopcloud.tech/toolshed/abra/src/branch/main/.drone.yml) runs a number of checks on each pushed commit. See the [Makefile](https://git.coopcloud.tech/toolshed/abra/src/branch/main/Makefile) for more handy targets.
@@ -127,16 +126,7 @@ Then, before running tests, set `export BATS_LIB_PATH=~/.local/share/bats/`
 ##### Debian
 
 ```
-apt install bats-file bats-assert bats-support jq make git
-```
-
-Unfortunately, the latest `bats` version in Debian stable does not have the "filter tests by tags" feature, which is very handy for running a subset of the tests. For this, we need to install `bats` from source. It's easy.
-
-```
-apt purge -y bats
-git clone https://github.com/bats-core/bats-core.git
-cd bats-core
-sudo ./install.sh /usr/local
+apt install bats bats-file bats-assert bats-support jq make git
 ```
 
 #### Setup Test Server
@@ -330,7 +320,7 @@ func main() {
 
 Some tools that are making use of the API so far are:
 
-* [`kadabra`](https://git.coopcloud.tech/toolshed/abra/src/branch/main/cmd/kadabra/main.go)
+* [`kadabra`](https://git.coopcloud.tech/toolshed/kadabra)
 
 ## Cross-compiling
 

docs/federation/resolutions/in-progress/034.md

@@ -0,0 +1,20 @@
+---
+title: Resolution 034
+---
+
+- Topic: Budget 015: Extra budget for recipes needed by Escuela Común
+- Date: 2025-10-27
+- Deadline: 2025-11-10
+- Size: medium
+
+## Summary
+
+Budget 015 for 20 estimated hours of work towards Escuela Común, **to be reimbursed** from next year's budget from the Sepal fund to the Co-op Cloud Federation Common Fund.
+
+## Details
+
+As Escuela Común 2026 planning proceeds, many `abra` bugs were closed, and we even gained the translations feature, but we've realised that we'll need at least one extra recipe to support Escuela's organizing: [`tellaweb`](https://github.com/Horizontal-org/tellaweb).
+
+This work has been supported by the Sepal fund we're sharing with Escuela Común. The budget allocated for this year has been used in full, so we're requesting the Federation to allocate budget from its own funds to cover for 20 estimated hours, to be reimbursed from next year's budget, that will be available on April 2026.
+
+`@3wc` will carry out this work.

docs/federation/resolutions/passed/032.md

@@ -1,5 +1,5 @@
 ---
-title: "Resolution 032: RIM joins"
+title: "Resolution 032: RTM joins"
 ---
 
 - Topic: RTM joins Coopcloud
@@ -11,7 +11,7 @@ title: "Resolution 032: RIM joins"
 
 Ammar's membership was approved in [Resolution 022](/federation/resolutions/passed/022).
 
-Since the establishment of RTM (Resist Rech Monopolies) collective in Seattle, Ammar has been unofficially representing the collective with coopcloud and vice versa.
+Since the establishment of RTM (Resist Tech Monopolies) collective in Seattle, Ammar has been unofficially representing the collective with coopcloud and vice versa.
 	
 ### Details
 	

docs/intro/comparisons.md

@@ -175,6 +175,29 @@ handful of popular team collaboration apps.
 - 👎 It is not designed to be a general specification.
 - 👎 Hard to share configurations into the commons.
 - 👎 Limited library of apps.
-- 👎 Uses *OpenNebula*, *Ansible*, and *Puppet* as underlying technologies.
+- 👎 Uses Ansible (see above)
 - 👎 Appears to be only a team of two people.
 - 👎 Appears to be inactive on Mastodon and limited GitLab activity. 
+
+### Dokploy 
+
+[Dokploy](https://dokploy.com/) (who have [their own comparison](https://docs.dokploy.com/docs/core/comparison)).
+
+- 👍 Supports builds from Git repositories, Dockerfiles, Nixpacks, and Buildpacks like Heroku and Paketo.
+- 👍 [~100 application templates](https://docs.dokploy.com/docs/core/templates)
+
+- 👎 [Bespoke TOML config](https://github.com/Dokploy/templates?tab=readme-ov-file#templatetoml-structure)
+- 👎 Community on Discord and Github discussions
+- 👎 Freemium / open-core model
+
+### Cosmos Cloud 
+
+[Cosmos Cloud](https://cosmos-cloud.io/), "The cloud doesn't need to be someone else's computer"
+
+- 👍 [Native client apps](https://cosmos-cloud.io/clients/)
+- 👍 Built-in VPN 
+
+- 👎 Community on Discord, Github discussions, and Reddit
+- 👎 "Up to 19 users" even on paid plans
+- 👎 Freemium / open-core model
+- 👎 ["Commons clause"](https://github.com/azukaar/Cosmos-Server/blob/master/LICENCE)

docs/maintainers/handbook.md

@@ -86,6 +86,16 @@ Because configurations are maintained in-repository by maintainers, we version t
 export NGINX_CONFIG_VERSION=v1
 ```
 
+!!! warning
+
+    It is **very important** that the naming convention of the config matches
+    the whole way down. In the above example, that is `nginx_config` in the
+    `configs:` stanza, `nginx_config` in `name:
+    ${STACK_NAME}_nginx_config_${NGINX_CONFIG_VERSION}` and finally
+    `NGINX_CONFIG_VERSION` in the `abra.sh`. This is the naming convention that
+    `abra` will perform to carry out the lookup of all matching names/values.
+    See [`#693`](https://git.coopcloud.tech/toolshed/abra/issues/693) for more.
+
 ## Manage environment variables
 
 !!! warning
@@ -124,6 +134,45 @@ You can also access it in your configs using the following syntax:
 {{ env "FOO" }}
 ```
 
+### Example: Adding environment variables to existing recipe
+Here is a four step example how to add a new environment variable to a recipe without breaking existing deployments. 
+
+1. add env-var to the `compose.yml` in section `environment`:
+   ```yaml
+       environment:
+         # ... existing envs
+         - REQUIRE_AUTH_FOR_PROFILE_REQUESTS=${REQUIRE_AUTH_FOR_PROFILE_REQUESTS:-false}
+         # ... other existing envs
+   ```
+
+   With `${REQUIRE_AUTH_FOR_PROFILE_REQUESTS:-false}` you set a default value (`false`), ensuring not to break existing deployments. 
+   If you're sure that it won't cause problems, if operators of existing deployments don't set the variable, you could also just put:
+   ```yaml
+       environment:
+         # ... existing envs
+         - REQUIRE_AUTH_FOR_PROFILE_REQUESTS
+         # ... other exisitng envs
+   ```
+   
+   Note: If you need to break something, make sure to add a [release note](/maintainers/handbook/#how-do-i-write-version-release-notes) explaining to operators what they should change before upgrading.
+
+2. add env-var to the `.env.sample`
+   ```yaml
+   #REQUIRE_AUTH_FOR_PROFILE_REQUESTS=true
+   ```
+
+3. now you can use the environment-variable in your `.tmpl` files, e.g. add to `homserver.yaml.tmpl`
+   ```yaml
+   require_auth_for_profile_requests: {{ env "REQUIRE_AUTH_FOR_PROFILE_REQUESTS" }}
+   ```
+   
+4. increase number of YAML-version in `abra.sh` (e.g. from `v30` to `v31`), only then it will be deployed. 
+   ```yaml
+   export HOMESERVER_YAML_VERSION=v31
+   ```
+
+   Note: If during development and testing you have to increase it several times, you can just "flatten" it in the end. Only make sure that you `undeploy`/`deploy` your existing instance.
+
 ### Global environment variables
 
 - `TYPE`: specifies the recipe name
@@ -368,7 +417,7 @@ You'll notice that `abra` figured out how to upgrade the Co-op Cloud version lab
 At this point, we're all set, we can run `abra recipe release --publish wordpress`. This will do the following:
 
 1. run `git commit` the new changes
-1. run `git tag` to create a new git tag named `1.1.0+5.9.0`
+1. run `git tag -am "chore: publish 1.1.0+5.9.0 release" 1.1.0+5.9.0` to create a new annotated git tag named `1.1.0+5.9.0` (abra only accepts annotated tags)
 1. run `git push` to publish changes to the Wordpress repository
 
 !!! warning "Here be more SSH dragons"
@@ -702,10 +751,10 @@ Please note:
 1. The `file_env` / `_FILE` hack is to pass secrets into the container runtime without exposing them in plaintext in the configuration. See [this entry](/maintainers/handbook/#exposing-secrets) for more.
 
 1. In order to pass execution back to the original entrypoint, it's a good idea to find the original entrypoint script and run it from your own entrypoint script. If there is none, you may want to reference the `CMD` definition or if that isn't working, try to actually specify `cmd: ...` in the `compose.yml` definition (there are other recipes which do this).
-  
+
 1. Also it might be necessary to define command: although there is an original entrypoint. That's [due to the fact](https://docs.docker.com/reference/compose-file/services/#entrypoint) that if entrypoint is non-null, Compose ignores any default command from the image, for example the `CMD` instruction in the Dockerfile.
 
-  1. Pratically you would e.g. look for the Dockerfile of the upstream image. In there you should find the docker-entrypoint.sh (or similar) and where it's located. Furthermore you find the `CMD`-line there. 
+  1. Pratically you would e.g. look for the Dockerfile of the upstream image. In there you should find the docker-entrypoint.sh (or similar) and where it's located. Furthermore you find the `CMD`-line there.
   1. Just put in your entrypoint.sh in the last line: exec /path/to/docker-entrypoint.sh "@" (path and filename you should find in upstream Dockerfile) and insert  command:  to your service in compose.yml with the value of what you find in the CMD line of the Dockerfile.
 
 1. If you're feeling reckless, you can also use the Golang templating engine to do things conditionally.

docs/operators/tutorial.md

@@ -271,35 +271,6 @@ To upgrade an app manually to the newest available version run:
 abra app upgrade <nextcloud-domain>
 ```
 
-### Automatic Upgrades
-
-`kadabra` the auto-updater is still under development, use it with care and don't use it in production environments. To setup the auto-updater copy the `kadabra` binary to the server and configure a cronjob for regular app upgrades. The following script will configure ssmtp for email notifications and setup a cronjob. This cronjob checks daily for new app versions, notifies if any kind of update is available and upgrades all apps to the latest patch/minor version.
-
-
-```bash
-apt install ssmtp
-
-cat > /etc/ssmtp/ssmtp.conf << EOF
-mailhub=$MAIL_SERVER:587
-hostname=$MAIL_DOMAIN
-AuthUser=$USER
-AuthPass=$PASSWORD
-FromLineOverride=yes
-UseSTARTTLS=yes
-EOF
-
-cat > /etc/cron.d/abra_updater << EOF
-MAILTO=admin@example.com
-MAILFROM=noreply@example.com
-
-0  6 * * *       root    ~/kadabra notify --major
-30 4 * * *       root    ~/kadabra upgrade --all
-EOF
-
-```
-
-Add `ENABLE_AUTO_UPDATE=true` to the env config (`abra app config <app name>`) to enable the auto-updater for a specific app.
-
 ## Finishing up
 
 Hopefully you got something running! Well done! The [operators handbook](/operators/handbook) would probably be the next place to go check out if you're looking for more help. Especially on topics of ongoing maintenance.

mkdocs.yml

@@ -125,12 +125,13 @@ nav:
               - federation/resolutions/passed/029.md
               - federation/resolutions/passed/032.md
               - federation/resolutions/passed/031.md
+              - federation/resolutions/passed/033.md
           - "Stalled":
               - federation/resolutions/stalled/013.md
               - federation/resolutions/stalled/030.md
           - "In Progress":
               - federation/resolutions/index.md
-              - federation/resolutions/in-progress/033.md
+              - federation/resolutions/in-progress/034.md
       - "Minutes":
           - federation/minutes/index.md
           - "Recently":