file format description

README.md

@@ -28,7 +28,7 @@ Add your SSH key(s) to your Forgejo account:
 - Add your key and give it a comment so you remember its purpose. Currently, all Forgejo SSH keys are general-purpose, but in case this ever changes, make sure the key can be used for commit singing.
 - The new key should appear as unverified. Click “Verify” next to the key you just created. Forgejo will provide you with a random string to sign with your SSH key and a command line which can be used to do this. Paste the SSH signature and your key should now be verified.
 
-Repeat this for at least every key you plan to use for signing, *not necessarily* every key you want to commit to the repository.
+Repeat this for at least every key you plan to use for signing, _not necessarily_ every key you want to commit to the repository.
 
 Make sure every email address you want to use with Git (see below) has been added to your profile. This is possible under the “Account” tab in the settings.
 
@@ -59,8 +59,22 @@ If you configured everything correctly, your commits should appear with a green
 
 ### Changing (and adding) your verified data
 
-Make all changes as necessary. (File structure TBD.) Make sure to only modify a subdirectory named *exactly* like your Forgejo user name. When you’re done, create a commit, ensure the commit has been signed properly, and open a pull request.
+Make all changes as necessary, see below for a description of user files and their formats. Make sure to only modify a subdirectory named _exactly_ like your Forgejo user name. When you’re done, create a commit, ensure the commit has been signed properly, and open a pull request.
 
 The CI will run on your PR and verify the changes have been signed by the correct user. **As an administrator of this repo, never merge a change that doesn’t pass CI.**
 
 Pull requests are merged by Git merge, which preserves the signing status. The CI should check out on main as well; otherwise, some user’s key data in Forgejo may have changed. These users must be notified ASAP so they remove their outdated keys and add new keys if they want to keep their verified data. Worst case, the files can be removed, removing them from the verification.
+
+### Signed user files
+
+There are only two mandatory files in your user directory: `keys` and `meta.toml`.
+
+`keys` is simply your list of SSH public keys. Any key you use to sign commits in this repository must be part of that key list. This is to provide extra verification that you didn’t commit wrong keys on accident.
+
+`meta.toml` provides metadata in TOML format. Not all of this metadata is currently checked (or required), but please stick to the format in case we decide to automate more parts of it in the future.
+
+| Option  | Type             | Explanation                                                                  |
+| ------- | ---------------- | ---------------------------------------------------------------------------- |
+| `name`  | string           | User name, must match the committer name and Forgejo name.                   |
+| `email` | string           | Email address, must match the committer email address.                       |
+| `teams` | array of strings | All administrative teams (i.e. services) that the user is currently part of. |