doc: improve documentation.

docs/development/abstractions.md

@@ -114,7 +114,7 @@ Minimal set of rules for all electron based UI application. It works as a *funct
 
 !!! note ""
 
-    [apparmor.d/profile-s-z/spotify](https://github.com/roddhjav/apparmor.d/blob/e979fe05b06f525e5a65c767b4eabe5600147355/apparmor.d/profile-s-z/spotify#L10-L13)
+    [apparmor.d/profile-s-z/spotify](https://github.com/roddhjav/apparmor.d/blob/7d1380530aa56f31589ccc6a360a8144f3601731/apparmor.d/profiles-s-z/spotify#L10-L13)
     ``` sh linenums="10"
     @{name} = spotify
     @{lib_dirs} = /opt/@{name}

docs/development/dbus.md

@@ -2,7 +2,13 @@
 title: Dbus
 ---
 
-All dbus rules are labelled under the name of the given profiles that provide dbus data. If the profiles were going to change (a renaming, an architectural change), the dbus rules need to be updated accordingly.
+All dbus rules are labelled under the name of the given profiles that provide dbus data. It is one of the value added by this project, as we have profile for *everything*, we can restrict the bus further by limitint connection to a given peer label (the profile name). In case of a renaming of a profile, all dbus rules related it this profile need to be updated accordingly.
+
+## Profiles
+
+Regardless of the Dbus implementation used (`dbus-daemon` or `dbus-broker`), all dbus daemons are handled under the same set of profiles: [`dbus-system`](https://github.com/roddhjav/apparmor.d/blob/main/apparmor.d/groups/bus/dbus-system), [`dbus-session`](https://github.com/roddhjav/apparmor.d/blob/main/apparmor.d/groups/bus/dbus-session), and [`dbus-accessibility`](https://github.com/roddhjav/apparmor.d/blob/main/apparmor.d/groups/bus/dbus-accessibility). This structure largely improves the confinement of each profile.
+
+To ensure system and session bus are handled by a different profile, a [systemd drop-in](https://github.com/roddhjav/apparmor.d/blob/main/systemd/default/system/dbus.service) configuration file is used to set the specific dbus profile a dbus service must use.
 
 ## Abstractions
 

docs/development/directives.md

@@ -136,7 +136,7 @@ The `exec` directive is useful to allow executing transition to a profile withou
     include <abstractions/common/systemd>
     capability dac_override,
     capability kill,
-    unix (bind) type=stream addr=@@{hex}/bus/systemd-oomd/bus-api-oom,
+    unix (bind) type=stream addr=@@{hex16}/bus/systemd-oomd/bus-api-oom,
     #aa:dbus own bus=system name=org.freedesktop.oom1
     /etc/systemd/oomd.conf r,
     /etc/systemd/oomd.conf.d/{,**} r,

docs/development/guidelines.md

@@ -91,24 +91,23 @@ If there is no predictable label it can be omitted.
 
 ### Profile rules
 
-`bin, sbin & lib`
+#### :material-numeric-1-circle: Variables
 
-:   - Do not use: `/usr/lib` or `/usr/bin` but `@{bin}/` or `@{lib}/`
-    - Do not use: `/usr/sbin` or `/sbin` but `@{bin}/`.
+:   Always use the apparmor [variables](../variables.md).
+    Example:
 
-`Variables`
+    - `/usr/lib` or `/usr/bin` become `@{bin}` or `@{lib}`
+    - `/usr/sbin` or `/sbin` become `@{bin}`.
 
-:   Always use the apparmor variables.
-
-`Sort`
+#### :material-numeric-2-circle: Sort
 
 :   In a rule block, the rules must be alphabetically sorted.
 
-`Sub profile`
+#### :material-numeric-3-circle: Sub profile
 
 :   Sub profile should come at the end of a profile.
 
-`Similar purpose`
+#### :material-numeric-4-circle: Similar purpose
 
 :   When some rules share similar purpose, they may be sorted together. Eg:
     ```

docs/development/index.md

@@ -36,7 +36,7 @@ You want to contribute to `apparmor.d`, **thanks a lot for this.** Feedbacks, co
 
 :   As these are mandatory access control policies only what is explicitly required
     should be authorized. Meaning, you should **not** allow everything (or a large area)
-    and blacklist some sub areas.
+    and deny some sub areas.
 
 #### Rule :material-numeric-2-circle: - Do not break a program