ammar vouch for 038

See toolshed/abra#793

docs/abra/cheat-sheet.md

@@ -70,7 +70,7 @@ To upgrade `abra` itself, run the following:
 $ abra upgrade
 ```
 
-Option flags: `--rc`
+Optional flags: `--rc`
 
 
 ### Upgrade a recipe
@@ -79,19 +79,13 @@ Option flags: `--rc`
 $ abra recipe upgrade $RECIPE`
 ```
 
-Option flags: `-x,y,z/--major,minor,patch`
-
-```
-$ abra recipe sync $RECIPE
-```
-
-Optional flags: `-x,y,z`
+Optional flags: `-x,y,z/--major,minor,patch`, `--commit`
 
 ```
 $ abra recipe release $RECIPE [$VERSION]
 ```
 
-Optional flags: `-p/--publish`, `-r/--dry-run`, `-x,y,z`
+Optional flags: `-r/--dry-run`, `-x,y,z`
 
 
 ### Manually restoring app data

docs/abra/hack.md

@@ -6,9 +6,9 @@ title: Hack
 
 Welcome to Hacking the Planet with `abra`! We're looking forward to see what you come up. If you have any questions, don't hesitate to ask 💖 However, please keep in mind that if any of your changes seems a bit controversial, it's probably best to come have a chat first to avoid heartache.
 
-In general, we're into the idea of "Optimistic Merging" (instead of "Pessimistic Merging" based on our understanding of [C4](https://hintjens.gitbooks.io/social-architecture/content/chapter4.html) (described further down under "Development Process" and also [in this blog post](http://hintjens.com/blog:106)).
+In general, we're into the idea of "Optimistic Merging" (instead of "Pessimistic Merging") based on our understanding of [C4](https://hintjens.gitbooks.io/social-architecture/content/chapter4.html) (described further down under "Development Process" and also [in this blog post](http://hintjens.com/blog:106)).
 
-In other words, we're happy to give you, as contributor, "the commit bit" (read/write permissions on the Git repositories) more or less as soon as you start to submit changes, write recipes, organise or in general, help out in the project. You don't have to prove anything, we can work and learn together! Mistakes are allowed and there are no "stupid questions".
+In other words, we're happy to grant contributors "the commit bit" (read/write permissions on our shared Git repositories) more or less as soon as you start to submit changes, write recipes, organise or in general, help out in the project. You don't have to prove anything, we can work and learn together! Mistakes are allowed and there are no "stupid questions".
 
 We maintain a "team" called "Co-operators" on our 2 main repositories:
 
@@ -182,31 +182,45 @@ For some tests an actual server is needed, where apps can be deployed. You can e
 
 ##### Remote swarm
 
+!!! warning
+
+    Right now, the test suite will check for a local swarm, see [abra/#769](https://git.coopcloud.tech/toolshed/abra/issues/769)
+
 ```
 export TEST_SERVER="test.example.com"
 export ABRA_DIR="$HOME/.abra_test"
 ```
 
-`ABRA_TEST_DOMAIN` should also have a DNS A record for `*.test.example.com` which points to the same server so that the test suite can deploy apps freely. The test suite does not deploy Traefik for you.
+There should also be a DNS A record for `*.test.example.com` which points to the same server so that the test suite can deploy apps freely. The test suite does not deploy Traefik for you.
 
 ##### Local swarm
 
-When running the test suite localy you need a running docker swarm setup:
+!!! note
+
+    This is currently necessary even if you only want to run tests which don't need a server
+
+When running the test suite locally you need a running docker swarm setup:
 
 ```
 docker swarm init
 docker network create -d overlay proxy
 ```
 
-To use the local swarm set the foloowing env var:
+To use the local swarm set the following env var:
 
 ```
 export TEST_SERVER=default
 export ABRA_DIR="$HOME/.abra_test"
 ```
 
+Make sure that the user running the tests can access the docker socket e.g. by adding it to the `docker` group (security considerations apply).
+
 ### Run tests
 
+!!! note
+
+    You need to remember to compile your current version of `abra` via `make` before running the tests. See [abra/#770](https://git.coopcloud.tech/toolshed/abra/issues/770)
+
 Now you can run the whole test suite:
 
 ```
@@ -319,6 +333,25 @@ It's also possible to translate using [`poedit`](https://poedit.net). Weblate is
 
 All translation files are located in [`pkg/i18n/locales`](https://git.coopcloud.tech/toolshed/abra/src/branch/main/pkg/i18n/locales). Once translations are updated in weblate, they will be incorporated into the next release of `abra` automatically.
 
+In general, the workflow for translators is:
+
+- Code freeze announced for `abra` before release. Strings are not updated by developers and merge conflicts are avoided.
+- Translation work proceeds on [`translate.coopcloud.tech/projects/co-op-cloud/abra`](https://translate.coopcloud.tech/projects/co-op-cloud/abra/)
+- Translators ensure that the latest translation changes are synchronised to the `abra` git repository via [the settings](https://translate.coopcloud.tech/projects/co-op-cloud/abra/#repository)
+- Translators and developers will [install `abra` locally](/abra/hack/#super-quick-start-ubuntu-server) and test the latest changes
+- If all is well, we can release `abra`
+
+### Updating `abradev`
+
+If you followed the [Super quick-start instructions](/abra/hack/#super-quick-start-ubuntu-server) to install `abra`, then these are the instructions you need to update your local `abra` to get the latest changes from Weblate. Make sure to check that the latest Weblate changes are synchronised with the `abra` repository.
+
+```
+cd
+cd abra
+git pull origin main
+make build
+```
+
 ### End-user workflow
 
 You simply export the `LANG` env var to match your desired translation.
@@ -404,15 +437,21 @@ For developers, while using this `-beta` format, the `y` part is the "major" ver
 - Commit that change (e.g. `git commit -m 'chore: publish next tag x.y.z-beta'`)
 - Make a new tag (e.g. `git tag -a x.y.z-beta`)
 - Push the new tag (e.g. `git push && git push --tags`)
-- Wait until the build finishes on [build.coopcloud.tech](https://build.coopcloud.tech/toolshed/abra)
+- Wait until the build finishes successfully on [build.coopcloud.tech](https://build.coopcloud.tech/toolshed/abra)
+- Set your `GITEA_TOKEN` in your `.envrc` and run `make release` to release `abra`
 - Deploy the new installer script (e.g. `cd ./scripts/installer && make`)
-- Clean up the changelog on the releases page so it includes most relevant
-  changes. See below for the announcement text that needs to be inserted above
-  the generated changelog. You can use something like `git shortlog -e -s -n
-  0.11.0-beta..HEAD` to get the list of authors.
-- Make sure there is a migration guide written in the docs (if necessary)
+- Clean up the changelog on the [releases
+  page](https://git.coopcloud.tech/toolshed/abra/releases) so it includes most
+  relevant changes. [See below](/abra/hack/#release-notes-text) for the
+  announcement text that needs to be inserted above the generated changelog.
+  You can use something like `git shortlog -e -s -n 0.XX.0-beta..HEAD` to get
+  the list of authors.
+- Make sure there is [a migration guide](/abra/upgrade/#migration-guides)
+  written in the docs (if necessary)
 - Check the release worked, (e.g. `abra upgrade; abra -v`)
-- Share the announcement on our General chat and fedi account:
+- Share [the standard announcement](/abra/hack/#general-announcement-text) on
+  our General chat and [fedi account](https://social.coop/@coopcloud)
+- Run away!
 
 #### Release notes text
 
@@ -467,6 +506,10 @@ We maintain a fork of [docker-cli](https://git.coopcloud.tech/toolshed/docker-cl
 
 A number of modules in [pkg/upstream](https://git.coopcloud.tech/toolshed/abra/src/branch/main/pkg/upstream) are copy/pasta'd from the upstream [docker/docker/client](https://pkg.go.dev/github.com/docker/docker/client). We had to do this because upstream are not exposing their API as public.
 
+### `spf13/cobra`
+
+Our command library doesn't support `i18n` so we need to implement a work-around specifically for translating the `--help` command. See [`spf13/cobra#2359`](https://github.com/spf13/cobra/issues/2359) for more.
+
 ### `github.com/schultz-is/passgen`
 
 Due to [`toolshed/organising#358`](https://git.coopcloud.tech/toolshed/organising/issues/358).

docs/abra/index.md

@@ -8,8 +8,6 @@ title: Abra
 [![Go Report Card](https://goreportcard.com/badge/git.coopcloud.tech/toolshed/abra)](https://goreportcard.com/report/git.coopcloud.tech/toolshed/abra)
 [![Go Reference](https://pkg.go.dev/badge/coopcloud.tech/abra.svg)](https://pkg.go.dev/coopcloud.tech/abra)
 
-`abra` is the flagship client & command-line for Co-op Cloud. It has been developed specifically for the purpose of making the day-to-day operations of operators and maintainers pleasant & convenient. It is libre software, written in Go and maintained and extended by the community :heart:
-
 `abra` is the flagship client & command-line tool for Co-op Cloud. It has been developed specifically for the purpose of making the day-to-day operations of [operators](https://docs.coopcloud.tech/operators/) and [maintainers](https://docs.coopcloud.tech/maintainers/) pleasant & convenient. It is libre software, written in [Go](https://go.dev) and maintained and extended by the community 💖
 
 Once you've got `abra` installed, you can start your own Co-op Cloud deployment.

docs/abra/upgrade.md

@@ -53,6 +53,15 @@ And test things work.
 
 > General release notes are [here](https://git.coopcloud.tech/toolshed/abra/releases/)
 
+### `0.12.x-beta` -> `0.13.x-beta`
+
+* `abra recipe sync` went away. You now only need to run `upgrade`/`release`.
+  See [`#682`](https://git.coopcloud.tech/toolshed/abra/issues/682) for the
+  design details and
+  [here](/maintainers/handbook/#upstream-released-a-new-version-how-do-i-upgrade-the-recipe)
+  for the revised documentation. Thanks to `@iexos` for getting this out the
+  door!
+
 ### `0.11.x-beta` -> `0.12.x-beta`
 
 * `kadabra` has been archived and is no longer published alongside `abra`

docs/federation/handbook.md

@@ -35,3 +35,5 @@ Here is some invitation boilerplate which you can use:
 > We take notes and doodle on [this collaboratively editable pad](https://pad.autonomic.zone/VtyrLUl9RWaJGgEDrncQUw?view). If you don't have time to attend, feel free to drop your questions and some contact details also, so we can get in touch. This is only the first Kite Flying Hour in a recurring series of Kite Flying Hours.
 >
 > Hope to see you there! ☁️ 🌞 🖥️
+
+To work around Hedgedoc length limits, [we keep past content from the kite-flying pad here](./kite-flying-pad-archive).

docs/federation/organisers.md

@@ -10,7 +10,7 @@ Welcome to the organisers guide! Organisers are folks who focus on the social wo
 
     One-stop shop for all you need to know to organise in the community :sparkles:
 
-    [Read Handbook](/organisers/handbook){ .md-button .md-button--primary }
+    [Read Handbook](/federation/handbook){ .md-button .md-button--primary }
 
 - __Say Hello First__
 

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

@@ -0,0 +1,29 @@
+---
+title: "Resolution 038: Merri-bek Tech joins Co-op Cloud Federation"
+---
+
+- Topic: Merri-bek Tech joins Coopcloud
+- Date: 2026-03-02
+- Deadline: 2026-03-16
+- Size: Large
+
+### Summary
+
+Merri-bek Tech is working towards neighbourhood-first, community controlled web services, building infrastructure using  the Co-op Cloud stack. Merri-bek Tech expects to pay membership dues.
+
+### Details
+
+Merri-bek Tech
+
+- currently depends on Traefik for neighbourhood-distributed nodes.
+- have developed and are maintaining Kiwix Co-op Cloud recipe for deploying Wikipedia across neighbourhood nodes
+- plans to use and contribute to maintenance, of additional components of Co-op Cloud stack as needed for subsequent phases of the project roadmap: neighbhourhood based email service, web hosting and decentralized social media.
+
+@jade:merri-bek.chat is an active member of the Co-op Cloud community.
+The group is based in Merri-bek, in the inner Northern suburbs of Naarm (Melbourne), Australia
+
+[Merri-bek Tech Inc.] is legally an incorporated association in Australia, which is a legal entity used for democratic clubs and societies. It is not intended to be a worker co-operative, it is a volunteer commons project, but it shares the mutuality goals of cooperatives. Full details are at [merri-bek.tech](https://merri-bek.tech).
+
+The project that Merri-bek Tech is running to promote Neighbourhood-First Software in Merri-bek and other regions, is detailed at [lores.tech](https://lores.tech).
+
+@ammaratef45 from RTM is honored to vouch

docs/maintainers/handbook.md

@@ -353,111 +353,143 @@ Therefore, we maintain an additional version part, in front of the project versi
 
 In all cases, we follow the semver semantics. So, if we upgrade the Gitea recipe from `1.14.3` to `1.15.3`, we still publish `1.1.0+1.15.3` as our recipe version. In this case, we skipped a few patch releases but it was all backwards compatible, so we only increment the minor version part.
 
-## How do I release a new recipe version?
+## Upstream released a new version, how do I upgrade the recipe?
 
-The commands uses for dealing with recipe versioning in `abra` are:
-
-- `abra recipe upgrade`: upgrade the image tags in the compose configs of a recipe
-- `abra recipe sync`: upgrade the deploy labels to match the new recipe version
-- `abra recipe release`: publish a git tag for the recipe repo
-
-The `abra` recipe publishing commands have been designed to complement a semi-automatic workflow. If `abra` breaks or doesn't understand what is going on, you can always finish the process manually with a few Git commands and a bit of luck. We designed `abra` to support this way due to the chaotic nature of container publishing versioning schemes.
-
-Let's take a practical example, publishing a new version of [Wordpress](https://git.coopcloud.tech/coop-cloud/wordpress).
-
-If we run `abra recipe upgrade wordpress` (at time of running), we end up with a prompt to upgrade Wordpress to `5.9.0`. We can skip the database upgrade for now. Here is what that looks like:
+`abra` can help you so you don't have to update the image tags in the compose files manually. Let us for example make an upgrade of [Wordpress](https://git.coopcloud.tech/coop-cloud/wordpress). Run:
 
 ```
-➜  ~ abra recipe upgrade wordpress
-? upgrade to which tag? (service: app, image: wordpress, tag: 5.8.3) 5.9.0
-? upgrade to which tag? (service: db, image: mariadb, tag: 10.6) skip
-WARN[0004] not upgrading mariadb, skipping as requested
+$ abra recipe upgrade wordpress
 ```
 
-Now, what happened? `abra` queried the upstream container repositories of all the images listed in the Wordpress recipe configuration and checked if there are new tags available. Once you make some choices on the prompt, `abra` will update the recipe configurations. Let's take a look by running `cd ~/.abra/recipes/wordpress && git diff`:
+If we run `abra recipe upgrade wordpress` (at time of running), we end up with a prompt to upgrade Wordpress to `6.9.1` and mariadb to `12.2`. Commit the changes when asked. Here is what that looks like:
 
-```diff
+```
+$ abra recipe upgrade wordpress
+? upgrade to which tag? (service: app, image: wordpress, tag: 6.9.0) 6.9.1
+? upgrade to which tag? (service: db, image: mariadb, tag: 12.1) 12.2
+WARN unable to read tag for image atmoz/sftp, is it missing? skipping upgrade for ftp
+INFO wordpress currently has these unstaged changes 👇
 diff --git a/compose.yml b/compose.yml
-index 1618ef5..6cd754d 100644
+index b3c3871..07d0a54 100644
 --- a/compose.yml
 +++ b/compose.yml
 @@ -3,7 +3,7 @@ version: "3.8"
-
+ 
  services:
    app:
--    image: "wordpress:5.8.3"
-+    image: "wordpress:5.9.0"
+-    image: "wordpress:6.9.0"
++    image: "wordpress:6.9.1"
      volumes:
        - "wordpress_content:/var/www/html/wp-content/"
      networks:
+@@ -65,7 +65,7 @@ services:
+         - "coop-cloud.${STACK_NAME}.version=2.17.0+6.9.0"
+ 
+   db:
+-    image: "mariadb:12.1"
++    image: "mariadb:12.2"
+     volumes:
+       - "mariadb:/var/lib/mysql"
+     networks:
+? commit changes? Yes
+INFO committed changes as 'chore: update image tags'
 ```
 
+Here is a rundown of what happened:
+
+- `abra` queried the upstream container repositories of all the images listed in the Wordpress recipe configuration and checked if there are new tags available
+- Once you make some choices on the prompt, `abra` will update the recipe configurations and show you the diff
+- If you choose to, a new commit containing the changes will be created
+
 !!! warning "Here be versioning dragons"
 
-    `abra` doesn't understand all image tags unfortunately. There are limitations which we're still running into. You can pass `-a` to have `abra` list all available image tags from the upstream repository and then make a choice manually. See [`tagcmp`](https://git.coopcloud.tech/toolshed/tagcmp) for more info on how we implement image parsing.
+    As you can see with `atmoz/sftp`, `abra` doesn't understand all image tags unfortunately. There are limitations which we're still running into. You can pass `-a` to have `abra` list all available image tags from the upstream repository and then make a choice manually. See [`tagcmp`](https://git.coopcloud.tech/toolshed/tagcmp) for more info on how we implement image parsing.
 
-Next, we need to update the label in the recipe, we can do that with `abra recipe sync wordpress`. You'll be prompted by a question asking what kind of upgrade this is. Take a moment to read the output and if it still doesn't make sense, read [this](/maintainers/handbook/#how-are-recipes-are-versioned). Since we're upgrading from `5.8.3` -> `5.9.0`, it is a minor release, so we choose `minor`:
+You will probably want to [test the upgrade](#how-are-new-recipe-versions-tested) now. Afterwards, you can release the upgraded recipe as outlined in the next section.
+
+## How do I release a new recipe version?
+
+!!! warning "Watch out for old versions of abra 🚧"
+
+    This section describes the release process with `abra` version `0.13.x`.
+    For older version, you will need to use these commands:
+    ```
+    abra recipe sync <recipe>
+    abra recipe release <recipe> -p
+    ```
+
+After upgrading the image tags and/or making some other changes to the recipe, you may want to release a new version. This can be done with
 
 ```
-➜  wordpress (master) ✗ abra recipe sync wordpress
-...
-INFO[0088] synced label coop-cloud.${STACK_NAME}.version=1.1.0+5.9.0 to service app
+abra recipe release
 ```
 
-Once again, we can run `cd ~/.abra/recipes/wordpress && git diff` to see what `abra` has done for us:
+Continuing our Wordpress example above, we can start the release process with `abra recipe release wordpress`. You'll be prompted by a question asking what kind of upgrade this is. Take a moment to read the output and if it still doesn't make sense, read [this](/maintainers/handbook/#how-are-recipes-are-versioned). Since we're upgrading Wordpress from `6.9.0` -> `6.9.1`, and the minor MariaDB upgrade does not change anything in our case, we consider this a `patch` release. Next, you will be prompted for release notes. Since there are no breaking changes or otherwise noteworthy changes in this upgrade, you can leave them empty.
 
-```diff
-diff --git a/compose.yml b/compose.yml
-index 1618ef5..4a08db6 100644
---- a/compose.yml
-+++ b/compose.yml
-@@ -3,7 +3,7 @@ version: "3.8"
+Here is what you will see:
 
- services:
-   app:
--    image: "wordpress:5.8.3"
-+    image: "wordpress:5.9.0"
-     volumes:
-       - "wordpress_content:/var/www/html/wp-content/"
-     networks:
-@@ -48,7 +48,7 @@ services:
-         #- "traefik.http.routers.${STACK_NAME}.rule=HostRegexp(`{subdomain:.+}.${DOMAIN}`, `${DOMAIN}`)"
-         - "traefik.http.routers.${STACK_NAME}.tls.certresolver=${LETS_ENCRYPT_ENV}"
-         - "traefik.http.routers.${STACK_NAME}.entrypoints=web-secure"
--        - "coop-cloud.${STACK_NAME}.version=1.0.2+5.8.3"
-+        - "coop-cloud.${STACK_NAME}.version=1.1.0+5.9.0"
-         - "backupbot.backup=true"
-         - "backupbot.backup.path=/var/www/html"
+```
+$ abra recipe release wordpress
+
+You need to make a decision about what kind of an update this new recipe
+version is. If someone else performs this upgrade, do they have to do some
+migration work or take care of some breaking changes? This can be signaled in
+the version you specify on the recipe deploy label and is called a semantic
+version.
+
+The latest published version is 2.17.0+6.9.0.
+
+┏━━━━━━━━━┳━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━┓
+┃ SERVICE ┃  2.17.0+6.9.0   ┃ PROPOSED CHANGES ┃
+┣━━━━━━━━━╋━━━━━━━━━━━━━━━━━╋━━━━━━━━━━━━━━━━━━┫
+┃ app     ┃ wordpress:6.9.0 ┃ wordpress:6.9.1  ┃
+┃ db      ┃ mariadb:12.1    ┃ mariadb:12.2     ┃
+┗━━━━━━━━━┻━━━━━━━━━━━━━━━━━┻━━━━━━━━━━━━━━━━━━┛
+
+Here is a semver cheat sheet (more on https://semver.org):
+
+    major: new features/bug fixes, backwards incompatible (e.g 1.0.0 -> 2.0.0).
+           the upgrade won't work without some preparation work and others need
+           to take care when performing it. "it could go wrong".
+
+    minor: new features/bug fixes, backwards compatible (e.g. 0.1.0 -> 0.2.0).
+           the upgrade should Just Work and there are no breaking changes in
+           the app and the recipe config. "it should go fine".
+
+    patch: bug fixes, backwards compatible (e.g. 0.0.1 -> 0.0.2). this upgrade
+           should also Just Work and is mostly to do with minor bug fixes
+           and/or security patches. "nothing to worry about".
+
+? select recipe version increment type patch
+INFO synced label coop-cloud.${STACK_NAME}.version=2.17.1+6.9.1 to service app
+? add release note? (leave empty to skip) 
+INFO new release published: https://git.coopcloud.tech/coop-cloud/wordpress.git/src/tag/2.17.1+6.9.1
 ```
 
-You'll notice that `abra` figured out how to upgrade the Co-op Cloud version label according to our choice, `1.0.2` -> `1.1.0` is a minor update.
+Here is a rundown of what happened:
 
-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 -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
+- with the choice of patch upgrade, `abra` determined the new recipe version label to be `2.17.1+6.9.1`
+- the label is updated in `compose.yml`
+- the changes to the label (and release notes if there are any) are committed
+- a new annotated git tag is created, similar to `git tag -am "chore: publish 2.17.1+6.9.1 release" 2.17.1+6.9.1`
+- commit and tag are pushed to the Wordpress recipe repository
 
 !!! 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.
 
-Here is the output:
+`abra` recipe publishing command have been designed to complement a semi-automatic workflow. If `abra` breaks or doesn't understand what is going on, you can always finish the process manually with a few Git commands and a bit of luck. We designed `abra` to support this way due to the chaotic nature of container publishing versioning schemes.
 
-```
-WARN[0000] discovered 1.1.0+5.9.0 as currently synced recipe label
-WARN[0000] previous git tags detected, assuming this is a new semver release
-? current: 1.0.2+5.8.3, new: 1.1.0+5.9.0, correct? Yes
-new release published: https://git.coopcloud.tech/coop-cloud/wordpress/src/tag/1.1.0+5.9.0
-```
+If you do this process manually, two important things to note for the release to be picked up in the catalogue:
 
-And once more, we can validate this tag has been created with `cd ~/.abra/recipes/wordpress && git tag -l`.
+- create an annotated git tag using `git tag -a`
+- push the tag with `git push --tags`
 
 ## How are new recipe versions tested?
 
 This is currently a manual process. Our best estimates are to do a backup and run a test deployment and see how things go. [We are working on improving this](https://git.coopcloud.tech/toolshed/-/projects/31).
 
-Following the [entry above](/maintainers/handbook/#how-do-i-release-a-new-recipe-version), before running `abra recipe release --publish <recipe>`, you can deploy the new version of the recipe. You find an app that relies on this recipe and pass `-C/--chaos` to `ugrade` so that it accepts the locally unstaged changes.
+Following the [entry above](/maintainers/handbook/#how-do-i-release-a-new-recipe-version), before running `abra recipe release <recipe>`, you can deploy the new version of the recipe. You find an app that relies on this recipe and pass `-C/--chaos` to `deploy` so that it accepts the locally unstaged changes.
 
 !!! warning "Here be more SSH dragons"
 
@@ -488,13 +520,11 @@ In the root of your recipe repository, run the following (if the folder doesn't
 mkdir -p release
 ```
 
-And then create a text file which corresponds to the version release, e.g. `1.1.0+5.9.0` and write some notes. `abra` will show these when another operator runs `abra app deploy` / `abra app upgrade`.
+And then create or append to the text file `release/next`. This file will be used when running `abra recipe release`. Abra will ask you to use these when running `abra recipe release` and rename it to the release tag, e.g. `release/1.1.0+5.9.0`.
 
-You can also add release notes for the next release into a special file `release/next`. This file will be used when running `abra recipe release`.
+You can also enter the release notes interactively when running `abra recipe release`.
 
-!!! warning "Watch out for old versions of `abra` 🚧"
-
-    This feature is only available in the >= 0.9.x series of `abra`.
+`abra` will show these notes when another operator runs `abra app deploy` / `abra app upgrade`.
 
 ## How do I know whether to accept version upgrades when running `abra recipe upgrade <something>`?
 
@@ -582,23 +612,6 @@ Add the `# generate=false` comment
 SECRET_JWT_SECRET_VERSION=v1 # generate=false
 ```
 
-## How do I specify the charset for a specific secret generation
-
-!!! warning "Watch out for old versions of `abra` 🚧"
-
-    This feature is only available in the >= 0.10.x series of `abra`.
-
-```
-SECRET_JWT_SECRET_VERSION=v1 # charset=default,special
-```
-
-Options are:
-
-* `special`: [source](https://github.com/decentral1se/passgen/blob/8404cb922dea92efa8c3514f0ec8c37ce12a880f/const.go#L22C29-L22C43)
-* `safespecial`: [source](https://git.coopcloud.tech/toolshed/abra/src/commit/6abaf7a094df1a96599af2c4cbae1769821ad17c/pkg/secret/secret.go#L182)
-* `default,special`: mix of `default` and `special`
-* `default,safespecial`: mix of `default` and `safespecial`
-
 ## How do I change secret generation length?
 
 It is possible to tell `abra` which length it should generate secrets with from your recipe config.
@@ -620,6 +633,13 @@ of passwords which admins have to type out in database shells.
 
 ## How do I change secret generation characters?
 
+!!! warning "Watch out for old versions of `abra` 🚧"
+
+    This feature is only available in the >= 0.10.x series of `abra`. 
+    The generation of `hex` secrets is only available in the >= 0.12.x series of `abra`.
+    The generation of `bytes` secrets is only available in the >= 0.13.x series of `abra`.
+
+
 It is also possible to tell `abra` which characters it should use to generate secrets with from your recipe config.
 
 You do this by adding an additional modifier in the inline comment on the secret definition in the `.env.sample` / `.env` file.
@@ -640,10 +660,52 @@ The possible Values are:
 | `default,special`                            | `abcdefghijkmnopqrstuvwxyzABCDEFGHJKLMNPQRSTUVWXYZ23456789!@#$%^&*_-+=` | Uses uppercase letters, lowercase letters and numbers and special characters              |
 | `default,safespecial`                        | `abcdefghijkmnopqrstuvwxyzABCDEFGHJKLMNPQRSTUVWXYZ23456789!@#%^&*_-+=`  | Uses uppercase letters, lowercase letters and numbers and console safe special characters |
 | `default`                                    | `abcdefghijkmnopqrstuvwxyzABCDEFGHJKLMNPQRSTUVWXYZ23456789`             | Uses uppercase letters, lowercase letters and numbers                                     |
+| `hex`                                        | `0123456789abcdef`                                                      | Uses only hexadecimal characters (0-9, a-f)                                                |
+| `bytes`                                      | N/A (generates random bytes)                                            | Generates random bytes instead of character-based passwords (requires `length` modifier, automatically uses `encoding=base64`) |
 | any other value or not setting one will be treated as `default` | `abcdefghijkmnopqrstuvwxyzABCDEFGHJKLMNPQRSTUVWXYZ23456789`             | Uses uppercase letters, lowercase letters and numbers                                     |
 
 The setting does only apply when you also set a length modifier to the secret (documented [here](/maintainers/handbook/#how-do-i-change-secret-generation-length)), so it is not applicable for the "easy to remember word" style generator that used when you don't set a length.
 
+## How do I encode generated secrets?
+
+!!! warning "Watch out for old versions of `abra` 🚧"
+
+    This feature is only available in the >= 0.13.x series of `abra`.
+
+You can tell `abra` to encode generated secrets using the `encoding` modifier in the inline comment on the secret definition in the `.env.sample` / `.env` file.
+
+Here is an example:
+
+```bash
+SECRET_API_KEY_VERSION=v1 # length=32 encoding=base64
+```
+
+This will generate a 32-character secret and then base64-encode it before storing.
+
+Currently supported encoding options:
+
+- `base64`: Base64-encodes the generated secret value
+
+**Note:** When using `charset=bytes`, the encoding automatically defaults to `base64` even if not explicitly specified, as raw binary data needs to be encoded for safe storage.
+
+## How do I add a prefix to generated secrets?
+
+!!! warning "Watch out for old versions of `abra` 🚧"
+
+    This feature is only available in the >= 0.13.x series of `abra`.
+
+You can tell `abra` to add a prefix to generated secrets using the `prefix` modifier in the inline comment on the secret definition in the `.env.sample` / `.env` file.
+
+Here is an example:
+
+```bash
+SECRET_APP_KEY_VERSION=v1 # length=32 charset=bytes prefix=base64:
+```
+
+This will generate a 32-byte random key, base64-encode it, and prefix it with `base64:`. This is useful for applications like Laravel that expect secrets in a specific format.
+
+The prefix is applied after any encoding transformations.
+
 ## How do I configure backup/restore?
 
 From the perspective of the recipe maintainer, backup/restore is just more

mkdocs.yml

@@ -84,6 +84,7 @@ nav:
       - federation/index.md
       - federation/handbook.md
       - federation/organisers.md
+      - federation/kite-flying-pad-archive.md
       - "Bylaws": federation/bylaws.md
       - "Finance": federation/finance.md
       - "Membership": federation/membership.md