From b90e091a51b82daeeab9f85c196957343f659919 Mon Sep 17 00:00:00 2001
From: Jose Celano <josecelano@gmail.com>
Date: Wed, 15 Apr 2026 19:04:42 +0100
Subject: [PATCH 01/23] chore(deps): update dependencies

```
cargo update
    Updating crates.io index
     Locking 34 packages to latest compatible versions
    Updating axum v0.8.8 -> v0.8.9
    Updating axum-extra v0.12.5 -> v0.12.6
    Updating axum-macros v0.5.0 -> v0.5.1
    Updating bitflags v2.11.0 -> v2.11.1
    Updating blowfish v0.9.1 -> v0.10.0
    Updating cc v1.2.59 -> v1.2.60
      Adding cipher v0.5.1
      Adding crypto-common v0.2.1
      Adding hashbrown v0.17.0
      Adding hybrid-array v0.4.10
    Updating hyper-rustls v0.27.7 -> v0.27.9
    Updating indexmap v2.13.1 -> v2.14.0
      Adding inout v0.2.2
    Updating js-sys v0.3.94 -> v0.3.95
    Updating libc v0.2.184 -> v0.2.185
    Updating libredox v0.1.15 -> v0.1.16
    Updating openssl v0.10.76 -> v0.10.77
    Updating openssl-sys v0.9.112 -> v0.9.113
    Updating pkg-config v0.3.32 -> v0.3.33
    Removing rand v0.9.2
    Removing rand v0.10.0
      Adding rand v0.9.4
      Adding rand v0.10.1
    Updating rand_core v0.10.0 -> v0.10.1
    Updating rayon v1.11.0 -> v1.12.0
    Updating redox_syscall v0.7.3 -> v0.7.4
    Updating rustls v0.23.37 -> v0.23.38
    Updating rustls-webpki v0.103.10 -> v0.103.12
    Updating tokio v1.51.0 -> v1.52.0
    Updating toml_edit v0.25.10+spec-1.1.0 -> v0.25.11+spec-1.1.0
    Updating wasm-bindgen v0.2.117 -> v0.2.118
    Updating wasm-bindgen-futures v0.4.67 -> v0.4.68
    Updating wasm-bindgen-macro v0.2.117 -> v0.2.118
    Updating wasm-bindgen-macro-support v0.2.117 -> v0.2.118
    Updating wasm-bindgen-shared v0.2.117 -> v0.2.118
    Updating web-sys v0.3.94 -> v0.3.95
note: pass `--verbose` to see 9 unchanged dependencies behind latest
```
---
 Cargo.lock | 232 +++++++++++++++++++++++++++++++----------------------
 1 file changed, 137 insertions(+), 95 deletions(-)

diff --git a/Cargo.lock b/Cargo.lock
index 9e0911944..27a9a8f1a 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -419,9 +419,9 @@ dependencies = [
 
 [[package]]
 name = "axum"
-version = "0.8.8"
+version = "0.8.9"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "8b52af3cb4058c895d37317bb27508dccc8e5f2d39454016b297bf4a400597b8"
+checksum = "31b698c5f9a010f6573133b09e0de5408834d0c82f8d7475a89fc1867a71cd90"
 dependencies = [
  "axum-core",
  "axum-macros",
@@ -483,9 +483,9 @@ dependencies = [
 
 [[package]]
 name = "axum-extra"
-version = "0.12.5"
+version = "0.12.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "fef252edff26ddba56bbcdf2ee3307b8129acb86f5749b68990c168a6fcc9c76"
+checksum = "be44683b41ccb9ab2d23a5230015c9c3c55be97a25e4428366de8873103f7970"
 dependencies = [
  "axum",
  "axum-core",
@@ -508,9 +508,9 @@ dependencies = [
 
 [[package]]
 name = "axum-macros"
-version = "0.5.0"
+version = "0.5.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "604fde5e028fea851ce1d8570bbdc034bec850d157f7569d10f347d06808c05c"
+checksum = "7aa268c23bfbbd2c4363b9cd302a4f504fb2a9dfe7e3451d66f35dd392e20aca"
 dependencies = [
  "proc-macro2",
  "quote",
@@ -620,9 +620,9 @@ checksum = "02b4ff8b16e6076c3e14220b39fbc1fabb6737522281a388998046859400895f"
 
 [[package]]
 name = "bitflags"
-version = "2.11.0"
+version = "2.11.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "843867be96c8daad0d758b57df9392b6d8d271134fce549de6ce169ff98a92af"
+checksum = "c4512299f36f043ab09a583e57bceb5a5aab7a73db1805848e8fef3c9e8c78b3"
 
 [[package]]
 name = "bittorrent-http-tracker-core"
@@ -721,7 +721,7 @@ dependencies = [
  "r2d2",
  "r2d2_mysql",
  "r2d2_sqlite",
- "rand 0.10.0",
+ "rand 0.10.1",
  "serde",
  "serde_json",
  "testcontainers",
@@ -751,13 +751,13 @@ dependencies = [
  "bittorrent-udp-tracker-protocol",
  "bloom",
  "blowfish",
- "cipher",
+ "cipher 0.4.4",
  "criterion 0.5.1",
  "futures",
  "generic-array",
  "lazy_static",
  "mockall",
- "rand 0.10.0",
+ "rand 0.10.1",
  "serde",
  "thiserror 2.0.18",
  "tokio",
@@ -827,12 +827,12 @@ dependencies = [
 
 [[package]]
 name = "blowfish"
-version = "0.9.1"
+version = "0.10.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e412e2cd0f2b2d93e02543ceae7917b3c70331573df19ee046bcbc35e45e87d7"
+checksum = "62ce3946557b35e71d1bbe07ec385073ce9eda05043f95de134eb578fcf1a298"
 dependencies = [
  "byteorder",
- "cipher",
+ "cipher 0.5.1",
 ]
 
 [[package]]
@@ -861,7 +861,7 @@ dependencies = [
  "log",
  "num",
  "pin-project-lite",
- "rand 0.9.2",
+ "rand 0.9.4",
  "rustls",
  "rustls-native-certs",
  "rustls-pki-types",
@@ -1041,9 +1041,9 @@ dependencies = [
 
 [[package]]
 name = "cc"
-version = "1.2.59"
+version = "1.2.60"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b7a4d3ec6524d28a329fc53654bbadc9bdd7b0431f5d65f1a56ffb28a1ee5283"
+checksum = "43c5703da9466b66a946814e1adf53ea2c90f10063b86290cc9eb67ce3478a20"
 dependencies = [
  "find-msvc-tools",
  "jobserver",
@@ -1086,7 +1086,7 @@ checksum = "6f8d983286843e49675a4b7a2d174efe136dc93a18d69130dd18198a6c167601"
 dependencies = [
  "cfg-if",
  "cpufeatures 0.3.0",
- "rand_core 0.10.0",
+ "rand_core 0.10.1",
 ]
 
 [[package]]
@@ -1134,8 +1134,18 @@ version = "0.4.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "773f3b9af64447d2ce9850330c473515014aa235e6a783b02db81ff39e4a3dad"
 dependencies = [
- "crypto-common",
- "inout",
+ "crypto-common 0.1.7",
+ "inout 0.1.4",
+]
+
+[[package]]
+name = "cipher"
+version = "0.5.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e34d8227fe1ba289043aeb13792056ff80fd6de1a9f49137a5f499de8e8c78ea"
+dependencies = [
+ "crypto-common 0.2.1",
+ "inout 0.2.2",
 ]
 
 [[package]]
@@ -1474,6 +1484,15 @@ dependencies = [
  "typenum",
 ]
 
+[[package]]
+name = "crypto-common"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "77727bb15fa921304124b128af125e7e3b968275d1b108b379190264f4423710"
+dependencies = [
+ "hybrid-array",
+]
+
 [[package]]
 name = "darling"
 version = "0.20.11"
@@ -1645,7 +1664,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "9ed9a281f7bc9b7576e61468ba615a66a5c8cfdff42420a70aa82701a3b1e292"
 dependencies = [
  "block-buffer",
- "crypto-common",
+ "crypto-common 0.1.7",
 ]
 
 [[package]]
@@ -1801,7 +1820,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "bb330bbd4cb7a5b9f559427f06f98a4f853a137c8298f3bd3f8ca57663e21986"
 dependencies = [
  "portable-atomic",
- "rand 0.9.2",
+ "rand 0.9.4",
  "web-time",
 ]
 
@@ -2151,7 +2170,7 @@ dependencies = [
  "cfg-if",
  "libc",
  "r-efi 6.0.0",
- "rand_core 0.10.0",
+ "rand_core 0.10.1",
  "wasip2",
  "wasip3",
 ]
@@ -2204,7 +2223,7 @@ dependencies = [
  "futures-core",
  "futures-sink",
  "http",
- "indexmap 2.13.1",
+ "indexmap 2.14.0",
  "slab",
  "tokio",
  "tokio-util",
@@ -2257,6 +2276,12 @@ dependencies = [
  "foldhash 0.2.0",
 ]
 
+[[package]]
+name = "hashbrown"
+version = "0.17.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4f467dd6dccf739c208452f8014c75c18bb8301b050ad1cfb27153803edb0f51"
+
 [[package]]
 name = "hashlink"
 version = "0.11.0"
@@ -2344,6 +2369,15 @@ version = "1.0.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "df3b46402a9d5adb4c86a0cf463f42e19994e3ee891101b1841f30a545cb49a9"
 
+[[package]]
+name = "hybrid-array"
+version = "0.4.10"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3944cf8cf766b40e2a1a333ee5e9b563f854d5fa49d6a8ca2764e97c6eddb214"
+dependencies = [
+ "typenum",
+]
+
 [[package]]
 name = "hyper"
 version = "1.9.0"
@@ -2383,15 +2417,14 @@ dependencies = [
 
 [[package]]
 name = "hyper-rustls"
-version = "0.27.7"
+version = "0.27.9"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e3c93eb611681b207e1fe55d5a71ecf91572ec8a6705cdb6857f7d8d5242cf58"
+checksum = "33ca68d021ef39cf6463ab54c1d0f5daf03377b70561305bb89a8f83aab66e0f"
 dependencies = [
  "http",
  "hyper",
  "hyper-util",
  "rustls",
- "rustls-pki-types",
  "tokio",
  "tokio-rustls",
  "tower-service",
@@ -2602,12 +2635,12 @@ dependencies = [
 
 [[package]]
 name = "indexmap"
-version = "2.13.1"
+version = "2.14.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "45a8a2b9cb3e0b0c1803dbb0758ffac5de2f425b23c28f518faabd9d805342ff"
+checksum = "d466e9454f08e4a911e14806c24e16fba1b4c121d1ea474396f396069cf949d9"
 dependencies = [
  "equivalent",
- "hashbrown 0.16.1",
+ "hashbrown 0.17.0",
  "serde",
  "serde_core",
 ]
@@ -2627,6 +2660,15 @@ dependencies = [
  "generic-array",
 ]
 
+[[package]]
+name = "inout"
+version = "0.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4250ce6452e92010fdf7268ccc5d14faa80bb12fc741938534c58f16804e03c7"
+dependencies = [
+ "hybrid-array",
+]
+
 [[package]]
 name = "io-enum"
 version = "1.2.1"
@@ -2764,9 +2806,9 @@ dependencies = [
 
 [[package]]
 name = "js-sys"
-version = "0.3.94"
+version = "0.3.95"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "2e04e2ef80ce82e13552136fabeef8a5ed1f985a96805761cbb9a2c34e7664d9"
+checksum = "2964e92d1d9dc3364cae4d718d93f227e3abb088e747d92e0395bfdedf1c12ca"
 dependencies = [
  "cfg-if",
  "futures-util",
@@ -2797,9 +2839,9 @@ checksum = "09edd9e8b54e49e587e4f6295a7d29c3ea94d469cb40ab8ca70b288248a81db2"
 
 [[package]]
 name = "libc"
-version = "0.2.184"
+version = "0.2.185"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "48f5d2a454e16a5ea0f4ced81bd44e4cfc7bd3a507b61887c99fd3538b28e4af"
+checksum = "52ff2c0fe9bc6cb6b14a0592c2ff4fa9ceb83eea9db979b0487cd054946a2b8f"
 
 [[package]]
 name = "libloading"
@@ -2819,14 +2861,14 @@ checksum = "b6d2cec3eae94f9f509c767b45932f1ada8350c4bdb85af2fcab4a3c14807981"
 
 [[package]]
 name = "libredox"
-version = "0.1.15"
+version = "0.1.16"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "7ddbf48fd451246b1f8c2610bd3b4ac0cc6e149d89832867093ab69a17194f08"
+checksum = "e02f3bb43d335493c96bf3fd3a321600bf6bd07ed34bc64118e9293bdffea46c"
 dependencies = [
  "bitflags",
  "libc",
  "plain",
- "redox_syscall 0.7.3",
+ "redox_syscall 0.7.4",
 ]
 
 [[package]]
@@ -3287,9 +3329,9 @@ checksum = "d6790f58c7ff633d8771f42965289203411a5e5c68388703c06e14f24770b41e"
 
 [[package]]
 name = "openssl"
-version = "0.10.76"
+version = "0.10.77"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "951c002c75e16ea2c65b8c7e4d3d51d5530d8dfa7d060b4776828c88cfb18ecf"
+checksum = "bfe4646e360ec77dff7dde40ed3d6c5fee52d156ef4a62f53973d38294dad87f"
 dependencies = [
  "bitflags",
  "cfg-if",
@@ -3319,9 +3361,9 @@ checksum = "7c87def4c32ab89d880effc9e097653c8da5d6ef28e6b539d313baaacfbafcbe"
 
 [[package]]
 name = "openssl-sys"
-version = "0.9.112"
+version = "0.9.113"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "57d55af3b3e226502be1526dfdba67ab0e9c96fc293004e79576b2b9edb0dbdb"
+checksum = "ad2f2c0eba47118757e4c6d2bff2838f3e0523380021356e7875e858372ce644"
 dependencies = [
  "cc",
  "libc",
@@ -3521,9 +3563,9 @@ dependencies = [
 
 [[package]]
 name = "pkg-config"
-version = "0.3.32"
+version = "0.3.33"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "7edddbd0b52d732b21ad9a5fab5c704c14cd949e5e9a1ec5929a24fded1b904c"
+checksum = "19f132c84eca552bf34cab8ec81f1c1dcc229b811638f9d283dceabe58c5569e"
 
 [[package]]
 name = "plain"
@@ -3664,7 +3706,7 @@ version = "3.5.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "e67ba7e9b2b56446f1d419b1d807906278ffa1a658a8a5d8a39dcb1f5a78614f"
 dependencies = [
- "toml_edit 0.25.10+spec-1.1.0",
+ "toml_edit 0.25.11+spec-1.1.0",
 ]
 
 [[package]]
@@ -3771,7 +3813,7 @@ checksum = "95c589f335db0f6aaa168a7cd27b1fc6920f5e1470c804f814d9cd6e62a0f70b"
 dependencies = [
  "env_logger",
  "log",
- "rand 0.10.0",
+ "rand 0.10.1",
 ]
 
 [[package]]
@@ -3804,7 +3846,7 @@ dependencies = [
  "bytes",
  "getrandom 0.3.4",
  "lru-slab",
- "rand 0.9.2",
+ "rand 0.9.4",
  "ring",
  "rustc-hash",
  "rustls",
@@ -3902,9 +3944,9 @@ dependencies = [
 
 [[package]]
 name = "rand"
-version = "0.9.2"
+version = "0.9.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "6db2770f06117d490610c7488547d543617b21bfa07796d7a12f6f1bd53850d1"
+checksum = "44c5af06bb1b7d3216d91932aed5265164bf384dc89cd6ba05cf59a35f5f76ea"
 dependencies = [
  "rand_chacha 0.9.0",
  "rand_core 0.9.5",
@@ -3912,13 +3954,13 @@ dependencies = [
 
 [[package]]
 name = "rand"
-version = "0.10.0"
+version = "0.10.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "bc266eb313df6c5c09c1c7b1fbe2510961e5bcd3add930c1e31f7ed9da0feff8"
+checksum = "d2e8e8bcc7961af1fdac401278c6a831614941f6164ee3bf4ce61b7edb162207"
 dependencies = [
  "chacha20",
  "getrandom 0.4.2",
- "rand_core 0.10.0",
+ "rand_core 0.10.1",
 ]
 
 [[package]]
@@ -3961,15 +4003,15 @@ dependencies = [
 
 [[package]]
 name = "rand_core"
-version = "0.10.0"
+version = "0.10.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "0c8d0fd677905edcbeedbf2edb6494d676f0e98d54d5cf9bda0b061cb8fb8aba"
+checksum = "63b8176103e19a2643978565ca18b50549f6101881c443590420e4dc998a3c69"
 
 [[package]]
 name = "rayon"
-version = "1.11.0"
+version = "1.12.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "368f01d005bf8fd9b1206fb6fa653e6c4a81ceb1466406b81792d87c5677a58f"
+checksum = "fb39b166781f92d482534ef4b4b1b2568f42613b53e5b6c160e24cfbfa30926d"
 dependencies = [
  "either",
  "rayon-core",
@@ -3996,9 +4038,9 @@ dependencies = [
 
 [[package]]
 name = "redox_syscall"
-version = "0.7.3"
+version = "0.7.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "6ce70a74e890531977d37e532c34d45e9055d2409ed08ddba14529471ed0be16"
+checksum = "f450ad9c3b1da563fb6948a8e0fb0fb9269711c9c73d9ea1de5058c79c8d643a"
 dependencies = [
  "bitflags",
 ]
@@ -4299,9 +4341,9 @@ dependencies = [
 
 [[package]]
 name = "rustls"
-version = "0.23.37"
+version = "0.23.38"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "758025cb5fccfd3bc2fd74708fd4682be41d99e5dff73c377c0646c6012c73a4"
+checksum = "69f9466fb2c14ea04357e91413efb882e2a6d4a406e625449bc0a5d360d53a21"
 dependencies = [
  "aws-lc-rs",
  "log",
@@ -4364,9 +4406,9 @@ checksum = "f87165f0995f63a9fbeea62b64d10b4d9d8e78ec6d7d51fb2125fda7bb36788f"
 
 [[package]]
 name = "rustls-webpki"
-version = "0.103.10"
+version = "0.103.12"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "df33b2b81ac578cabaf06b89b0631153a3f416b0a886e8a7a1707fb51abbd1ef"
+checksum = "8279bb85272c9f10811ae6a6c547ff594d6a7f3c6c6b02ee9726d1d0dcfcdd06"
 dependencies = [
  "aws-lc-rs",
  "ring",
@@ -4541,7 +4583,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b2f2d7ff8a2140333718bb329f5c40fc5f0865b84c426183ce14c97d2ab8154f"
 dependencies = [
  "form_urlencoded",
- "indexmap 2.13.1",
+ "indexmap 2.14.0",
  "itoa",
  "ryu",
  "serde_core",
@@ -4553,7 +4595,7 @@ version = "1.0.149"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "83fc039473c5595ace860d8c4fafa220ff474b3fc6bfdb4293327f1a37e94d86"
 dependencies = [
- "indexmap 2.13.1",
+ "indexmap 2.14.0",
  "itoa",
  "memchr",
  "serde",
@@ -4623,7 +4665,7 @@ dependencies = [
  "chrono",
  "hex",
  "indexmap 1.9.3",
- "indexmap 2.13.1",
+ "indexmap 2.14.0",
  "schemars 0.9.0",
  "schemars 1.2.1",
  "serde_core",
@@ -5113,9 +5155,9 @@ checksum = "1f3ccbac311fea05f86f61904b462b55fb3df8837a366dfc601a0161d0532f20"
 
 [[package]]
 name = "tokio"
-version = "1.51.0"
+version = "1.52.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "2bd1c4c0fc4a7ab90fc15ef6daaa3ec3b893f004f915f2392557ed23237820cd"
+checksum = "a91135f59b1cbf38c91e73cf3386fca9bb77915c45ce2771460c9d92f0f3d776"
 dependencies = [
  "bytes",
  "libc",
@@ -5190,7 +5232,7 @@ version = "0.9.12+spec-1.1.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "cf92845e79fc2e2def6a5d828f0801e29a2f8acc037becc5ab08595c7d5e9863"
 dependencies = [
- "indexmap 2.13.1",
+ "indexmap 2.14.0",
  "serde_core",
  "serde_spanned 1.1.1",
  "toml_datetime 0.7.5+spec-1.1.0",
@@ -5232,7 +5274,7 @@ version = "0.22.27"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "41fe8c660ae4257887cf66394862d21dbca4a6ddd26f04a3560410406a2f819a"
 dependencies = [
- "indexmap 2.13.1",
+ "indexmap 2.14.0",
  "serde",
  "serde_spanned 0.6.9",
  "toml_datetime 0.6.11",
@@ -5242,11 +5284,11 @@ dependencies = [
 
 [[package]]
 name = "toml_edit"
-version = "0.25.10+spec-1.1.0"
+version = "0.25.11+spec-1.1.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "a82418ca169e235e6c399a84e395ab6debeb3bc90edc959bf0f48647c6a32d1b"
+checksum = "0b59c4d22ed448339746c59b905d24568fcbb3ab65a500494f7b8c3e97739f2b"
 dependencies = [
- "indexmap 2.13.1",
+ "indexmap 2.14.0",
  "toml_datetime 1.1.1+spec-1.1.0",
  "toml_parser",
  "winnow 1.0.1",
@@ -5358,7 +5400,7 @@ dependencies = [
  "hyper",
  "local-ip-address",
  "percent-encoding",
- "rand 0.10.0",
+ "rand 0.10.1",
  "reqwest",
  "serde",
  "serde_bencode",
@@ -5499,7 +5541,7 @@ dependencies = [
  "clap",
  "local-ip-address",
  "mockall",
- "rand 0.10.0",
+ "rand 0.10.1",
  "regex",
  "reqwest",
  "serde",
@@ -5649,7 +5691,7 @@ dependencies = [
  "crossbeam-skiplist",
  "futures",
  "mockall",
- "rand 0.10.0",
+ "rand 0.10.1",
  "rstest 0.26.1",
  "serde",
  "thiserror 2.0.18",
@@ -5668,7 +5710,7 @@ dependencies = [
 name = "torrust-tracker-test-helpers"
 version = "3.0.0-develop"
 dependencies = [
- "rand 0.10.0",
+ "rand 0.10.1",
  "torrust-tracker-configuration",
  "tracing",
  "tracing-subscriber",
@@ -5708,7 +5750,7 @@ dependencies = [
  "futures-util",
  "local-ip-address",
  "mockall",
- "rand 0.10.0",
+ "rand 0.10.1",
  "ringbuf",
  "serde",
  "thiserror 2.0.18",
@@ -5736,7 +5778,7 @@ checksum = "ebe5ef63511595f1344e2d5cfa636d973292adc0eec1f0ad45fae9f0851ab1d4"
 dependencies = [
  "futures-core",
  "futures-util",
- "indexmap 2.13.1",
+ "indexmap 2.14.0",
  "pin-project-lite",
  "slab",
  "sync_wrapper",
@@ -5994,7 +6036,7 @@ checksum = "5ac8b6f42ead25368cf5b098aeb3dc8a1a2c05a3eee8a9a1a68c640edbfc79d9"
 dependencies = [
  "getrandom 0.4.2",
  "js-sys",
- "rand 0.10.0",
+ "rand 0.10.1",
  "wasm-bindgen",
 ]
 
@@ -6067,9 +6109,9 @@ dependencies = [
 
 [[package]]
 name = "wasm-bindgen"
-version = "0.2.117"
+version = "0.2.118"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "0551fc1bb415591e3372d0bc4780db7e587d84e2a7e79da121051c5c4b89d0b0"
+checksum = "0bf938a0bacb0469e83c1e148908bd7d5a6010354cf4fb73279b7447422e3a89"
 dependencies = [
  "cfg-if",
  "once_cell",
@@ -6081,9 +6123,9 @@ dependencies = [
 
 [[package]]
 name = "wasm-bindgen-futures"
-version = "0.4.67"
+version = "0.4.68"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "03623de6905b7206edd0a75f69f747f134b7f0a2323392d664448bf2d3c5d87e"
+checksum = "f371d383f2fb139252e0bfac3b81b265689bf45b6874af544ffa4c975ac1ebf8"
 dependencies = [
  "js-sys",
  "wasm-bindgen",
@@ -6091,9 +6133,9 @@ dependencies = [
 
 [[package]]
 name = "wasm-bindgen-macro"
-version = "0.2.117"
+version = "0.2.118"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "7fbdf9a35adf44786aecd5ff89b4563a90325f9da0923236f6104e603c7e86be"
+checksum = "eeff24f84126c0ec2db7a449f0c2ec963c6a49efe0698c4242929da037ca28ed"
 dependencies = [
  "quote",
  "wasm-bindgen-macro-support",
@@ -6101,9 +6143,9 @@ dependencies = [
 
 [[package]]
 name = "wasm-bindgen-macro-support"
-version = "0.2.117"
+version = "0.2.118"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "dca9693ef2bab6d4e6707234500350d8dad079eb508dca05530c85dc3a529ff2"
+checksum = "9d08065faf983b2b80a79fd87d8254c409281cf7de75fc4b773019824196c904"
 dependencies = [
  "bumpalo",
  "proc-macro2",
@@ -6114,9 +6156,9 @@ dependencies = [
 
 [[package]]
 name = "wasm-bindgen-shared"
-version = "0.2.117"
+version = "0.2.118"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "39129a682a6d2d841b6c429d0c51e5cb0ed1a03829d8b3d1e69a011e62cb3d3b"
+checksum = "5fd04d9e306f1907bd13c6361b5c6bfc7b3b3c095ed3f8a9246390f8dbdee129"
 dependencies = [
  "unicode-ident",
 ]
@@ -6138,7 +6180,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "bb0e353e6a2fbdc176932bbaab493762eb1255a7900fe0fea1a2f96c296cc909"
 dependencies = [
  "anyhow",
- "indexmap 2.13.1",
+ "indexmap 2.14.0",
  "wasm-encoder",
  "wasmparser",
 ]
@@ -6151,15 +6193,15 @@ checksum = "47b807c72e1bac69382b3a6fb3dbe8ea4c0ed87ff5629b8685ae6b9a611028fe"
 dependencies = [
  "bitflags",
  "hashbrown 0.15.5",
- "indexmap 2.13.1",
+ "indexmap 2.14.0",
  "semver",
 ]
 
 [[package]]
 name = "web-sys"
-version = "0.3.94"
+version = "0.3.95"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "cd70027e39b12f0849461e08ffc50b9cd7688d942c1c8e3c7b22273236b4dd0a"
+checksum = "4f2dfbb17949fa2088e5d39408c48368947b86f7834484e87b73de55bc14d97d"
 dependencies = [
  "js-sys",
  "wasm-bindgen",
@@ -6553,7 +6595,7 @@ checksum = "b7c566e0f4b284dd6561c786d9cb0142da491f46a9fbed79ea69cdad5db17f21"
 dependencies = [
  "anyhow",
  "heck",
- "indexmap 2.13.1",
+ "indexmap 2.14.0",
  "prettyplease",
  "syn 2.0.117",
  "wasm-metadata",
@@ -6584,7 +6626,7 @@ checksum = "9d66ea20e9553b30172b5e831994e35fbde2d165325bec84fc43dbf6f4eb9cb2"
 dependencies = [
  "anyhow",
  "bitflags",
- "indexmap 2.13.1",
+ "indexmap 2.14.0",
  "log",
  "serde",
  "serde_derive",
@@ -6603,7 +6645,7 @@ checksum = "ecc8ac4bc1dc3381b7f59c34f00b67e18f910c2c0f50015669dde7def656a736"
 dependencies = [
  "anyhow",
  "id-arena",
- "indexmap 2.13.1",
+ "indexmap 2.14.0",
  "log",
  "semver",
  "serde",

From 7b5f4b45363fdad369effbc64727ee69a3014f7d Mon Sep 17 00:00:00 2001
From: Jose Celano <josecelano@gmail.com>
Date: Wed, 15 Apr 2026 21:13:29 +0100
Subject: [PATCH 02/23] fix(udp-tracker-core): align cipher with blowfish
 update

---
 Cargo.lock                                    | 26 +++----------------
 packages/udp-tracker-core/Cargo.toml          |  3 +--
 .../udp-tracker-core/src/connection_cookie.rs |  9 +++----
 .../src/crypto/ephemeral_instance_keys.rs     |  5 ++--
 packages/udp-tracker-core/src/crypto/keys.rs  |  8 +++---
 5 files changed, 14 insertions(+), 37 deletions(-)

diff --git a/Cargo.lock b/Cargo.lock
index 27a9a8f1a..81c8c62b0 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -751,10 +751,9 @@ dependencies = [
  "bittorrent-udp-tracker-protocol",
  "bloom",
  "blowfish",
- "cipher 0.4.4",
+ "cipher",
  "criterion 0.5.1",
  "futures",
- "generic-array",
  "lazy_static",
  "mockall",
  "rand 0.10.1",
@@ -832,7 +831,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "62ce3946557b35e71d1bbe07ec385073ce9eda05043f95de134eb578fcf1a298"
 dependencies = [
  "byteorder",
- "cipher 0.5.1",
+ "cipher",
 ]
 
 [[package]]
@@ -1128,16 +1127,6 @@ dependencies = [
  "half",
 ]
 
-[[package]]
-name = "cipher"
-version = "0.4.4"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "773f3b9af64447d2ce9850330c473515014aa235e6a783b02db81ff39e4a3dad"
-dependencies = [
- "crypto-common 0.1.7",
- "inout 0.1.4",
-]
-
 [[package]]
 name = "cipher"
 version = "0.5.1"
@@ -1145,7 +1134,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "e34d8227fe1ba289043aeb13792056ff80fd6de1a9f49137a5f499de8e8c78ea"
 dependencies = [
  "crypto-common 0.2.1",
- "inout 0.2.2",
+ "inout",
 ]
 
 [[package]]
@@ -2651,15 +2640,6 @@ version = "0.1.15"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "c8fae54786f62fb2918dcfae3d568594e50eb9b5c25bf04371af6fe7516452fb"
 
-[[package]]
-name = "inout"
-version = "0.1.4"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "879f10e63c20629ecabbb64a8010319738c66a5cd0c29b02d63d272b03751d01"
-dependencies = [
- "generic-array",
-]
-
 [[package]]
 name = "inout"
 version = "0.2.2"
diff --git a/packages/udp-tracker-core/Cargo.toml b/packages/udp-tracker-core/Cargo.toml
index 828b3aff2..45a74f93c 100644
--- a/packages/udp-tracker-core/Cargo.toml
+++ b/packages/udp-tracker-core/Cargo.toml
@@ -20,10 +20,9 @@ bittorrent-tracker-core = { version = "3.0.0-develop", path = "../tracker-core"
 bittorrent-udp-tracker-protocol = { version = "3.0.0-develop", path = "../udp-protocol" }
 bloom = "0.3.2"
 blowfish = "0"
-cipher = "0.4"
+cipher = "0.5"
 criterion = { version = "0.5.1", features = [ "async_tokio" ] }
 futures = "0"
-generic-array = "0"
 lazy_static = "1"
 rand = "0"
 serde = "1.0.219"
diff --git a/packages/udp-tracker-core/src/connection_cookie.rs b/packages/udp-tracker-core/src/connection_cookie.rs
index ce255705f..2d8e941cd 100644
--- a/packages/udp-tracker-core/src/connection_cookie.rs
+++ b/packages/udp-tracker-core/src/connection_cookie.rs
@@ -84,7 +84,6 @@ use tracing::instrument;
 use zerocopy::AsBytes;
 
 use crate::crypto::keys::CipherArrayBlowfish;
-
 /// Error returned when there was an error with the connection cookie.
 #[derive(Error, Debug, Clone, PartialEq)]
 pub enum ConnectionCookieError {
@@ -140,8 +139,8 @@ use std::ops::Range;
 pub fn check(cookie: &Cookie, fingerprint: u64, valid_range: Range<f64>) -> Result<f64, ConnectionCookieError> {
     assert!(valid_range.start <= valid_range.end, "range start is larger than range end");
 
-    let cookie_bytes = CipherArrayBlowfish::from_slice(cookie.0.as_bytes());
-    let cookie_bytes = decode(*cookie_bytes);
+    let cookie_bytes = CipherArrayBlowfish::try_from(cookie.0.as_bytes()).expect("it should be the same size");
+    let cookie_bytes = decode(cookie_bytes);
 
     let issue_time = disassemble(fingerprint, cookie_bytes);
 
@@ -176,7 +175,7 @@ pub fn gen_remote_fingerprint(remote_addr: &SocketAddr) -> u64 {
 }
 
 mod cookie_builder {
-    use cipher::{BlockDecrypt, BlockEncrypt};
+    use cipher::{BlockCipherDecrypt, BlockCipherEncrypt};
     use tracing::instrument;
     use zerocopy::{byteorder, AsBytes as _, NativeEndian};
 
@@ -196,7 +195,7 @@ mod cookie_builder {
         let cookie: byteorder::I64<NativeEndian> =
             *zerocopy::FromBytes::ref_from(&cookie.to_ne_bytes()).expect("it should be aligned");
 
-        *CipherArrayBlowfish::from_slice(cookie.as_bytes())
+        CipherArrayBlowfish::try_from(cookie.as_bytes()).expect("it should be the same size")
     }
 
     #[instrument()]
diff --git a/packages/udp-tracker-core/src/crypto/ephemeral_instance_keys.rs b/packages/udp-tracker-core/src/crypto/ephemeral_instance_keys.rs
index de40e4b1d..357bdeca5 100644
--- a/packages/udp-tracker-core/src/crypto/ephemeral_instance_keys.rs
+++ b/packages/udp-tracker-core/src/crypto/ephemeral_instance_keys.rs
@@ -4,14 +4,13 @@
 //! application starts and are not persisted anywhere.
 
 use blowfish::BlowfishLE;
-use cipher::{BlockSizeUser, KeyInit};
-use generic_array::GenericArray;
+use cipher::{Block, KeyInit};
 use rand::rngs::ThreadRng;
 use rand::RngExt;
 
 pub type Seed = [u8; 32];
 pub type CipherBlowfish = BlowfishLE;
-pub type CipherArrayBlowfish = GenericArray<u8, <CipherBlowfish as BlockSizeUser>::BlockSize>;
+pub type CipherArrayBlowfish = Block<CipherBlowfish>;
 
 lazy_static! {
     /// The random static seed.
diff --git a/packages/udp-tracker-core/src/crypto/keys.rs b/packages/udp-tracker-core/src/crypto/keys.rs
index bb813b9dc..2faa745c3 100644
--- a/packages/udp-tracker-core/src/crypto/keys.rs
+++ b/packages/udp-tracker-core/src/crypto/keys.rs
@@ -5,7 +5,7 @@
 //!
 //! It also provides the logic for the cipher for encryption and decryption.
 
-use cipher::{BlockDecrypt, BlockEncrypt};
+use cipher::{BlockCipherDecrypt, BlockCipherEncrypt};
 
 use self::detail_cipher::CURRENT_CIPHER;
 use self::detail_seed::CURRENT_SEED;
@@ -15,7 +15,7 @@ use crate::crypto::ephemeral_instance_keys::{CipherBlowfish, Seed, RANDOM_CIPHER
 /// This trait is for structures that can keep and provide a seed.
 pub trait Keeper {
     type Seed: Sized + Default + AsMut<[u8]>;
-    type Cipher: BlockEncrypt + BlockDecrypt;
+    type Cipher: BlockCipherEncrypt + BlockCipherDecrypt;
 
     /// It returns a reference to the seed that is keeping.
     fn get_seed() -> &'static Self::Seed;
@@ -137,14 +137,14 @@ mod detail_cipher {
 
     #[cfg(test)]
     mod tests {
-        use cipher::BlockEncrypt;
+        use cipher::BlockCipherEncrypt;
 
         use crate::crypto::ephemeral_instance_keys::{CipherArrayBlowfish, ZEROED_TEST_CIPHER_BLOWFISH};
         use crate::crypto::keys::detail_cipher::CURRENT_CIPHER;
 
         #[test]
         fn it_should_default_to_zeroed_seed_when_testing() {
-            let mut data: cipher::generic_array::GenericArray<u8, _> = CipherArrayBlowfish::from([0u8; 8]);
+            let mut data = CipherArrayBlowfish::from([0u8; 8]);
             let mut data_2 = CipherArrayBlowfish::from([0u8; 8]);
 
             CURRENT_CIPHER.encrypt_block(&mut data);

From a55c2aefe699c9ecbbd3c4a85d653eef145e6290 Mon Sep 17 00:00:00 2001
From: Jose Celano <josecelano@gmail.com>
Date: Thu, 16 Apr 2026 17:28:03 +0100
Subject: [PATCH 03/23] chore(deps): update dependencies

```
cargo update
    Updating crates.io index
     Locking 9 packages to latest compatible versions
    Updating aws-lc-rs v1.16.2 -> v1.16.3
    Updating aws-lc-sys v0.39.1 -> v0.40.0
    Updating clap v4.6.0 -> v4.6.1
    Updating clap_derive v4.6.0 -> v4.6.1
    Updating ferroid v0.8.9 -> v2.0.0
    Updating portable-atomic-util v0.2.6 -> v0.2.7
    Updating testcontainers v0.27.2 -> v0.27.3
    Updating uuid v1.23.0 -> v1.23.1
    Updating webpki-root-certs v1.0.6 -> v1.0.7
note: pass `--verbose` to see 8 unchanged dependencies behind latest
```
---
 Cargo.lock | 38 +++++++++++++++++++-------------------
 1 file changed, 19 insertions(+), 19 deletions(-)

diff --git a/Cargo.lock b/Cargo.lock
index 81c8c62b0..03138f718 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -397,9 +397,9 @@ checksum = "c08606f8c3cbf4ce6ec8e28fb0014a2c086708fe954eaa885384a6165172e7e8"
 
 [[package]]
 name = "aws-lc-rs"
-version = "1.16.2"
+version = "1.16.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "a054912289d18629dc78375ba2c3726a3afe3ff71b4edba9dedfca0e3446d1fc"
+checksum = "0ec6fb3fe69024a75fa7e1bfb48aa6cf59706a101658ea01bfd33b2b248a038f"
 dependencies = [
  "aws-lc-sys",
  "zeroize",
@@ -407,9 +407,9 @@ dependencies = [
 
 [[package]]
 name = "aws-lc-sys"
-version = "0.39.1"
+version = "0.40.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "83a25cf98105baa966497416dbd42565ce3a8cf8dbfd59803ec9ad46f3126399"
+checksum = "f50037ee5e1e41e7b8f9d161680a725bd1626cb6f8c7e901f91f942850852fe7"
 dependencies = [
  "cc",
  "cmake",
@@ -1150,9 +1150,9 @@ dependencies = [
 
 [[package]]
 name = "clap"
-version = "4.6.0"
+version = "4.6.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b193af5b67834b676abd72466a96c1024e6a6ad978a1f484bd90b85c94041351"
+checksum = "1ddb117e43bbf7dacf0a4190fef4d345b9bad68dfc649cb349e7d17d28428e51"
 dependencies = [
  "clap_builder",
  "clap_derive",
@@ -1172,9 +1172,9 @@ dependencies = [
 
 [[package]]
 name = "clap_derive"
-version = "4.6.0"
+version = "4.6.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "1110bd8a634a1ab8cb04345d8d878267d57c3cf1b38d91b71af6686408bbca6a"
+checksum = "f2ce8604710f6733aa641a2b3731eaa1e8b3d9973d5e3565da11800813f997a9"
 dependencies = [
  "heck",
  "proc-macro2",
@@ -1804,12 +1804,12 @@ checksum = "9f1f227452a390804cdb637b74a86990f2a7d7ba4b7d5693aac9b4dd6defd8d6"
 
 [[package]]
 name = "ferroid"
-version = "0.8.9"
+version = "2.0.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "bb330bbd4cb7a5b9f559427f06f98a4f853a137c8298f3bd3f8ca57663e21986"
+checksum = "ee93edf3c501f0035bbeffeccfed0b79e14c311f12195ec0e661e114a0f60da4"
 dependencies = [
  "portable-atomic",
- "rand 0.9.4",
+ "rand 0.10.1",
  "web-time",
 ]
 
@@ -3603,9 +3603,9 @@ checksum = "c33a9471896f1c69cecef8d20cbe2f7accd12527ce60845ff44c153bb2a21b49"
 
 [[package]]
 name = "portable-atomic-util"
-version = "0.2.6"
+version = "0.2.7"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "091397be61a01d4be58e7841595bd4bfedb15f1cd54977d79b8271e94ed799a3"
+checksum = "c2a106d1259c23fac8e543272398ae0e3c0b8d33c88ed73d0cc71b0f1d902618"
 dependencies = [
  "portable-atomic",
 ]
@@ -4979,9 +4979,9 @@ checksum = "8f50febec83f5ee1df3015341d8bd429f2d1cc62bcba7ea2076759d315084683"
 
 [[package]]
 name = "testcontainers"
-version = "0.27.2"
+version = "0.27.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "0bd36b06a2a6c0c3c81a83be1ab05fe86460d054d4d51bf513bc56b3e15bdc22"
+checksum = "bfd5785b5483672915ed5fe3cddf9f546802779fc1eceff0a6fb7321fac81c1e"
 dependencies = [
  "astral-tokio-tar",
  "async-trait",
@@ -6010,9 +6010,9 @@ checksum = "06abde3611657adf66d383f00b093d7faecc7fa57071cce2578660c9f1010821"
 
 [[package]]
 name = "uuid"
-version = "1.23.0"
+version = "1.23.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "5ac8b6f42ead25368cf5b098aeb3dc8a1a2c05a3eee8a9a1a68c640edbfc79d9"
+checksum = "ddd74a9687298c6858e9b88ec8935ec45d22e8fd5e6394fa1bd4e99a87789c76"
 dependencies = [
  "getrandom 0.4.2",
  "js-sys",
@@ -6199,9 +6199,9 @@ dependencies = [
 
 [[package]]
 name = "webpki-root-certs"
-version = "1.0.6"
+version = "1.0.7"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "804f18a4ac2676ffb4e8b5b5fa9ae38af06df08162314f96a68d2a363e21a8ca"
+checksum = "f31141ce3fc3e300ae89b78c0dd67f9708061d1d2eda54b8209346fd6be9a92c"
 dependencies = [
  "rustls-pki-types",
 ]

From e47a5e9f24dc1ecf39bd08882518e60972e4a45c Mon Sep 17 00:00:00 2001
From: Jose Celano <josecelano@gmail.com>
Date: Thu, 16 Apr 2026 17:33:55 +0100
Subject: [PATCH 04/23] chore(ci): upgrade codecov/codecov-action from v5 to v6

---
 .github/workflows/coverage.yaml           | 2 +-
 .github/workflows/upload_coverage_pr.yaml | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/coverage.yaml b/.github/workflows/coverage.yaml
index 4c49217c2..ada96f77f 100644
--- a/.github/workflows/coverage.yaml
+++ b/.github/workflows/coverage.yaml
@@ -49,7 +49,7 @@ jobs:
 
       - id: upload
         name: Upload Coverage Report
-        uses: codecov/codecov-action@v5
+        uses: codecov/codecov-action@v6
         with:
           verbose: true
           token: ${{ secrets.CODECOV_TOKEN }}
diff --git a/.github/workflows/upload_coverage_pr.yaml b/.github/workflows/upload_coverage_pr.yaml
index 55de02c62..4a6c757a5 100644
--- a/.github/workflows/upload_coverage_pr.yaml
+++ b/.github/workflows/upload_coverage_pr.yaml
@@ -102,7 +102,7 @@ jobs:
           path: repo_root
 
       - name: Upload coverage to Codecov
-        uses: codecov/codecov-action@v5
+        uses: codecov/codecov-action@v6
         with:
           verbose: true
           token: ${{ secrets.CODECOV_TOKEN }}

From 92929ba9f77022c94af5020be7135cc52bd335a4 Mon Sep 17 00:00:00 2001
From: Jose Celano <josecelano@gmail.com>
Date: Thu, 16 Apr 2026 18:02:04 +0100
Subject: [PATCH 05/23] docs(#1595): Add build-essential to Prerequisites

The build-essential package is required to provide the C compiler (cc)
needed for compilation. This was missing from the prerequisites documentation.

Closes #1595
---
 src/lib.rs | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/src/lib.rs b/src/lib.rs
index b26960899..791c0d928 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -88,6 +88,12 @@
 //!
 //! The tracker has some system dependencies:
 //!
+//! First, you need to install the build tools:
+//!
+//! ```text
+//! sudo apt-get install build-essential
+//! ```
+//!
 //! Since we are using the `openssl` crate with the [vendored feature](https://docs.rs/openssl/latest/openssl/#vendored),
 //! enabled, you will need to install the following dependencies:
 //!

From bcbef65801ebc3798a6d803b57385537fc677d7e Mon Sep 17 00:00:00 2001
From: Jose Celano <josecelano@gmail.com>
Date: Thu, 16 Apr 2026 18:24:58 +0100
Subject: [PATCH 06/23] docs(configuration): document MySQL DSN password
 URL-encoding

---
 docs/containers.md                                | 6 +++++-
 packages/configuration/src/v2_0_0/database.rs     | 4 +++-
 share/default/config/tracker.container.mysql.toml | 3 +++
 3 files changed, 11 insertions(+), 2 deletions(-)

diff --git a/docs/containers.md b/docs/containers.md
index cddd2ba98..a7754d8aa 100644
--- a/docs/containers.md
+++ b/docs/containers.md
@@ -248,6 +248,10 @@ driver = "mysql"
 path = "mysql://db_user:db_user_secret_password@mysql:3306/torrust_tracker"
 ```
 
+Important: if the MySQL password contains reserved URL characters (for example `+`, `/`, `@`, or `:`), it must be percent-encoded in the DSN password component. For example, if the raw password is `a+b/c`, use `a%2Bb%2Fc` in the DSN.
+
+When generating secrets automatically, prefer URL-safe passwords (`A-Z`, `a-z`, `0-9`, `-`, `_`) to avoid DSN parsing issues.
+
 ### Build and Run:
 
 ```sh
@@ -292,7 +296,7 @@ These are some useful commands for MySQL.
 Open a shell in the MySQL container using docker or docker-compose.
 
 ```s
-docker exec -it torrust-mysql-1 /bin/bash 
+docker exec -it torrust-mysql-1 /bin/bash
 docker compose exec mysql /bin/bash
 ```
 
diff --git a/packages/configuration/src/v2_0_0/database.rs b/packages/configuration/src/v2_0_0/database.rs
index c2b24d809..457b3c925 100644
--- a/packages/configuration/src/v2_0_0/database.rs
+++ b/packages/configuration/src/v2_0_0/database.rs
@@ -12,8 +12,10 @@ pub struct Database {
     /// Database connection string. The format depends on the database driver.
     /// For `sqlite3`, the format is `path/to/database.db`, for example:
     /// `./storage/tracker/lib/database/sqlite3.db`.
-    /// For `Mysql`, the format is `mysql://db_user:db_user_password:port/db_name`, for
+    /// For `mysql`, the format is `mysql://db_user:db_user_password@host:port/db_name`, for
     /// example: `mysql://root:password@localhost:3306/torrust`.
+    /// If the password contains reserved URL characters (for example `+` or `/`),
+    /// percent-encode it in the URL.
     #[serde(default = "Database::default_path")]
     pub path: String,
 }
diff --git a/share/default/config/tracker.container.mysql.toml b/share/default/config/tracker.container.mysql.toml
index 865ea224e..33fcf713a 100644
--- a/share/default/config/tracker.container.mysql.toml
+++ b/share/default/config/tracker.container.mysql.toml
@@ -12,6 +12,9 @@ private = false
 
 [core.database]
 driver = "mysql"
+# If the MySQL password includes reserved URL characters (for example + or /),
+# percent-encode it in the DSN password component.
+# Example: password a+b/c -> a%2Bb%2Fc
 path = "mysql://db_user:db_user_secret_password@mysql:3306/torrust_tracker"
 
 # Uncomment to enable services

From e7a3a8aef0c006a7226437d2d285dc0fd95a8883 Mon Sep 17 00:00:00 2001
From: Jose Celano <josecelano@gmail.com>
Date: Mon, 20 Apr 2026 15:55:02 +0100
Subject: [PATCH 07/23] chore: update dependencies

```
cargo update
    Updating crates.io index
     Locking 8 packages to latest compatible versions
    Updating openssl v0.10.77 -> v0.10.78
    Updating openssl-sys v0.9.113 -> v0.9.114
    Updating rand v0.8.5 -> v0.8.6
    Updating sqlite-wasm-rs v0.5.2 -> v0.5.3
    Updating tokio v1.52.0 -> v1.52.1
    Updating typenum v1.19.0 -> v1.20.0
    Updating wasip2 v1.0.2+wasi-0.2.9 -> v1.0.3+wasi-0.2.9
      Adding wit-bindgen v0.57.1
note: pass `--verbose` to see 8 unchanged dependencies behind latest
```
---
 Cargo.lock | 46 ++++++++++++++++++++++++++--------------------
 1 file changed, 26 insertions(+), 20 deletions(-)

diff --git a/Cargo.lock b/Cargo.lock
index 03138f718..bb8a972b2 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -3105,7 +3105,7 @@ dependencies = [
  "mysql-common-derive",
  "num-bigint",
  "num-traits",
- "rand 0.8.5",
+ "rand 0.8.6",
  "regex",
  "rust_decimal",
  "saturating",
@@ -3309,9 +3309,9 @@ checksum = "d6790f58c7ff633d8771f42965289203411a5e5c68388703c06e14f24770b41e"
 
 [[package]]
 name = "openssl"
-version = "0.10.77"
+version = "0.10.78"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "bfe4646e360ec77dff7dde40ed3d6c5fee52d156ef4a62f53973d38294dad87f"
+checksum = "f38c4372413cdaaf3cc79dd92d29d7d9f5ab09b51b10dded508fb90bb70b9222"
 dependencies = [
  "bitflags",
  "cfg-if",
@@ -3341,9 +3341,9 @@ checksum = "7c87def4c32ab89d880effc9e097653c8da5d6ef28e6b539d313baaacfbafcbe"
 
 [[package]]
 name = "openssl-sys"
-version = "0.9.113"
+version = "0.9.114"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "ad2f2c0eba47118757e4c6d2bff2838f3e0523380021356e7875e858372ce644"
+checksum = "13ce1245cd07fcc4cfdb438f7507b0c7e4f3849a69fd84d52374c66d83741bb6"
 dependencies = [
  "cc",
  "libc",
@@ -3486,7 +3486,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "3c80231409c20246a13fddb31776fb942c38553c51e871f8cbd687a4cfb5843d"
 dependencies = [
  "phf_shared",
- "rand 0.8.5",
+ "rand 0.8.6",
 ]
 
 [[package]]
@@ -3913,9 +3913,9 @@ checksum = "dc33ff2d4973d518d823d61aa239014831e521c75da58e3df4840d3f47749d09"
 
 [[package]]
 name = "rand"
-version = "0.8.5"
+version = "0.8.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "34af8d1a0e25924bc5b7c43c079c942339d8f0a8b57c39049bef581b46327404"
+checksum = "5ca0ecfa931c29007047d1bc58e623ab12e5590e8c7cc53200d5202b69266d8a"
 dependencies = [
  "libc",
  "rand_chacha 0.3.1",
@@ -4278,7 +4278,7 @@ dependencies = [
  "borsh",
  "bytes",
  "num-traits",
- "rand 0.8.5",
+ "rand 0.8.6",
  "rkyv",
  "serde",
  "serde_json",
@@ -4765,9 +4765,9 @@ dependencies = [
 
 [[package]]
 name = "sqlite-wasm-rs"
-version = "0.5.2"
+version = "0.5.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "2f4206ed3a67690b9c29b77d728f6acc3ce78f16bf846d83c94f76400320181b"
+checksum = "1b2c760607300407ddeaee518acf28c795661b7108c75421303dbefb237d3a36"
 dependencies = [
  "cc",
  "js-sys",
@@ -5135,9 +5135,9 @@ checksum = "1f3ccbac311fea05f86f61904b462b55fb3df8837a366dfc601a0161d0532f20"
 
 [[package]]
 name = "tokio"
-version = "1.52.0"
+version = "1.52.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "a91135f59b1cbf38c91e73cf3386fca9bb77915c45ce2771460c9d92f0f3d776"
+checksum = "b67dee974fe86fd92cc45b7a95fdd2f99a36a6d7b0d431a231178d3d670bbcc6"
 dependencies = [
  "bytes",
  "libc",
@@ -5889,15 +5889,15 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "97fee6b57c6a41524a810daee9286c02d7752c4253064d0b05472833a438f675"
 dependencies = [
  "cfg-if",
- "rand 0.8.5",
+ "rand 0.8.6",
  "static_assertions",
 ]
 
 [[package]]
 name = "typenum"
-version = "1.19.0"
+version = "1.20.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "562d481066bde0658276a35467c4af00bdc6ee726305698a55b86e61d7ad82bb"
+checksum = "40ce102ab67701b8526c123c1bab5cbe42d7040ccfd0f64af1a385808d2f43de"
 
 [[package]]
 name = "uncased"
@@ -6071,11 +6071,11 @@ checksum = "ccf3ec651a847eb01de73ccad15eb7d99f80485de043efb2f370cd654f4ea44b"
 
 [[package]]
 name = "wasip2"
-version = "1.0.2+wasi-0.2.9"
+version = "1.0.3+wasi-0.2.9"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "9517f9239f02c069db75e65f174b3da828fe5f5b945c4dd26bd25d89c03ebcf5"
+checksum = "20064672db26d7cdc89c7798c48a0fdfac8213434a1186e5ef29fd560ae223d6"
 dependencies = [
- "wit-bindgen",
+ "wit-bindgen 0.57.1",
 ]
 
 [[package]]
@@ -6084,7 +6084,7 @@ version = "0.4.0+wasi-0.3.0-rc-2026-01-06"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "5428f8bf88ea5ddc08faddef2ac4a67e390b88186c703ce6dbd955e1c145aca5"
 dependencies = [
- "wit-bindgen",
+ "wit-bindgen 0.51.0",
 ]
 
 [[package]]
@@ -6556,6 +6556,12 @@ dependencies = [
  "wit-bindgen-rust-macro",
 ]
 
+[[package]]
+name = "wit-bindgen"
+version = "0.57.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1ebf944e87a7c253233ad6766e082e3cd714b5d03812acc24c318f549614536e"
+
 [[package]]
 name = "wit-bindgen-core"
 version = "0.51.0"

From 1ba176d46b63e68680babbaf9b3b2c4f627fb1ee Mon Sep 17 00:00:00 2001
From: Jose Celano <josecelano@gmail.com>
Date: Mon, 20 Apr 2026 16:00:24 +0100
Subject: [PATCH 08/23] chore(deps): bump actions/setup-node from 5 to 6

---
 .github/workflows/testing.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/testing.yaml b/.github/workflows/testing.yaml
index 83a290663..173613ec3 100644
--- a/.github/workflows/testing.yaml
+++ b/.github/workflows/testing.yaml
@@ -56,7 +56,7 @@ jobs:
 
       - id: node
         name: Setup Node.js
-        uses: actions/setup-node@v5
+        uses: actions/setup-node@v6
         with:
           node-version: "20"
 

From cb70ca0f555f4cba95e0517443801e0d4b93502b Mon Sep 17 00:00:00 2001
From: Jose Celano <josecelano@gmail.com>
Date: Mon, 20 Apr 2026 16:00:36 +0100
Subject: [PATCH 09/23] chore(deps): bump actions/github-script from 8 to 9

---
 .github/workflows/upload_coverage_pr.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/upload_coverage_pr.yaml b/.github/workflows/upload_coverage_pr.yaml
index 4a6c757a5..442afe31b 100644
--- a/.github/workflows/upload_coverage_pr.yaml
+++ b/.github/workflows/upload_coverage_pr.yaml
@@ -22,7 +22,7 @@ jobs:
     steps:
       - name: "Download existing coverage report"
         id: prepare_report
-        uses: actions/github-script@v8
+        uses: actions/github-script@v9
         with:
           script: |
             var fs = require('fs');

From 3b1e2928cd70d90e9c506edafe48e431a089be09 Mon Sep 17 00:00:00 2001
From: Jose Celano <josecelano@gmail.com>
Date: Mon, 20 Apr 2026 17:24:24 +0100
Subject: [PATCH 10/23] docs(issues): add issue spec for #1697 (AI agent
 configuration)

---
 docs/issues/1697-ai-agent-configuration.md | 334 +++++++++++++++++++++
 project-words.txt                          |   9 +
 2 files changed, 343 insertions(+)
 create mode 100644 docs/issues/1697-ai-agent-configuration.md

diff --git a/docs/issues/1697-ai-agent-configuration.md b/docs/issues/1697-ai-agent-configuration.md
new file mode 100644
index 000000000..8e0e7b932
--- /dev/null
+++ b/docs/issues/1697-ai-agent-configuration.md
@@ -0,0 +1,334 @@
+# Set Up Basic AI Agent Configuration
+
+## Goal
+
+Set up the foundational configuration files in this repository to enable effective collaboration with AI coding agents. This includes adding an `AGENTS.md` file to guide agents on project conventions, adding agent skills for repeatable specialized tasks, and defining custom agents for project-specific workflows.
+
+## References
+
+- **AGENTS.md specification**: https://agents.md/
+- **Agent Skills specification**: https://agentskills.io/specification
+- **GitHub Copilot — About agent skills**: https://docs.github.com/en/copilot/concepts/agents/about-agent-skills
+- **GitHub Copilot — About custom agents**: https://docs.github.com/en/copilot/concepts/agents/copilot-cli/about-custom-agents
+
+## Background
+
+### AGENTS.md
+
+`AGENTS.md` is an open, plain-Markdown format stewarded by the [Agentic AI Foundation](https://aaif.io/) under the Linux Foundation. It acts as a "README for agents": a single, predictable file where coding agents look first for project-specific context (build steps, test commands, conventions, security considerations) that would otherwise clutter the human-focused `README.md`.
+
+It is supported by a wide ecosystem of tools including GitHub Copilot (VS Code), Cursor, Windsurf, OpenAI Codex, Claude Code, Jules (Google), Warp, and many others. In monorepos, nested `AGENTS.md` files can be placed inside each package; the closest file to the file being edited takes precedence.
+
+### Agent Skills
+
+Agent Skills (https://agentskills.io/specification) are directories of instructions, scripts, and resources that an agent can load to perform specialized, repeatable tasks. Each skill lives in a folder named after the skill and contains at minimum a `SKILL.md` file with YAML frontmatter (`name`, `description`, optional `license`, `compatibility`, `metadata`, `allowed-tools`) followed by Markdown instructions.
+
+GitHub Copilot supports:
+
+- **Project skills** stored in the repository at `.github/skills/`, `.claude/skills/`, or `.agents/skills/`
+- **Personal skills** stored in the home directory at `~/.copilot/skills/`, `~/.claude/skills/`, or `~/.agents/skills/`
+
+### Custom Agents
+
+Custom agents are specialized versions of GitHub Copilot that can be tailored to project-specific workflows. They are defined as Markdown files with YAML frontmatter (agent profiles) stored at:
+
+- **Repository level**: `.github/agents/CUSTOM-AGENT-NAME.md`
+- **Organization/enterprise level**: `/agents/CUSTOM-AGENT-NAME.md` inside a `.github-private` repository
+
+An agent profile includes a `name`, `description`, optional `tools`, and optional `mcp-servers` configurations. The Markdown body of the file acts as the agent's prompt (it is not a YAML frontmatter key). The main Copilot agent can run custom agents as subagents in isolated context windows, including in parallel.
+
+## Tasks
+
+### Task 0: Create a local branch
+
+- Approved branch name: `<issue-number>-ai-agent-configuration`
+- Commands:
+  - `git fetch --all --prune`
+  - `git checkout develop`
+  - `git pull --ff-only`
+  - `git checkout -b <issue-number>-ai-agent-configuration`
+- Checkpoint: `git branch --show-current` should output `<issue-number>-ai-agent-configuration`.
+
+---
+
+### Task 1: Add `AGENTS.md` at the repository root
+
+Provide AI coding agents with a clear, predictable source of project context so they can work
+effectively without requiring repeated manual instructions.
+
+**Inspiration / reference AGENTS.md files from other Torrust projects**:
+
+- https://raw.githubusercontent.com/torrust/torrust-tracker-deployer/refs/heads/main/AGENTS.md
+- https://raw.githubusercontent.com/torrust/torrust-linting/refs/heads/main/AGENTS.md
+
+Create `AGENTS.md` in the repository root, adapting the above files to the tracker. At minimum
+the file must cover:
+
+- [ ] Repository link and project overview (language, license, MSRV, web framework, protocols, databases)
+- [ ] Tech stack (languages, frameworks, databases, containerization, linting tools)
+- [ ] Key directories (`src/`, `src/bin/`, `packages/`, `console/`, `contrib/`, `tests/`, `docs/`, `share/`, `storage/`, `.github/workflows/`)
+- [ ] Package catalog (all workspace packages with their layer and description)
+- [ ] Package naming conventions (`axum-*`, `*-server`, `*-core`, `*-protocol`)
+- [ ] Key configuration files (`.markdownlint.json`, `.yamllint-ci.yml`, `.taplo.toml`, `cspell.json`, `rustfmt.toml`, etc.)
+- [ ] Build & test commands (`cargo build`, `cargo test --doc`, `cargo test --all-targets`, E2E runner, benchmarks)
+- [ ] Lint commands (`linter all` and individual linters; how to install the `linter` binary)
+- [ ] Dependencies check (`cargo machete`)
+- [ ] Code style (rustfmt rules, clippy policy, import grouping, per-format rules)
+- [ ] Collaboration principles (no flattery, push back on weak ideas, flag blockers early)
+- [ ] Essential rules (linting gate, GPG commit signing, no `storage/`/`target/` commits, `cargo machete`)
+- [ ] Git workflow (branch naming, Conventional Commits, branch strategy: `develop` → `staging/main` → `main`)
+- [ ] Development principles (observability, testability, modularity, extensibility; Beck's four rules)
+- [ ] Container / Docker (key commands, ports, volume mount paths)
+- [ ] Auto-invoke skills placeholder (to be filled in when `.github/skills/` is populated)
+- [ ] Documentation quick-navigation table
+- [ ] Add a brief entry to `docs/index.md` pointing contributors to `AGENTS.md`, `.github/skills/`, and `.github/agents/`
+
+Commit message: `docs(agents): add root AGENTS.md`
+
+Checkpoint:
+
+- `linter all` exits with code `0`.
+- At least one AI agent (GitHub Copilot, Cursor, etc.) can be confirmed to pick up the file.
+
+**References**:
+
+- https://agents.md/
+- https://github.com/openai/codex/blob/-/AGENTS.md (real-world example)
+- https://github.com/apache/airflow/blob/-/AGENTS.md (real-world monorepo example)
+
+---
+
+### Task 2: Add Agent Skills
+
+Define reusable, project-specific skills that agents can load to perform specialized tasks on
+this repository consistently.
+
+- [ ] Create `.github/skills/` directory
+- [ ] Review and confirm the candidate skills listed below (add, remove, or adjust before starting implementation)
+- [ ] For each skill, create a directory with:
+  - `SKILL.md` — YAML frontmatter (`name`, `description`, optional `license`, `compatibility`) + step-by-step instructions
+  - `scripts/` (optional) — executable scripts the agent can run
+  - `references/` (optional) — additional reference documentation
+- [ ] Validate skill files against the Agent Skills spec (name rules: lowercase, hyphens, no consecutive hyphens, max 64 chars; description: max 1024 chars)
+
+**Candidate initial skills** (ported / adapted from `torrust-tracker-deployer`):
+
+The skills below are modelled on the skills already proven in
+[torrust-tracker-deployer](https://github.com/torrust/torrust-tracker-deployer)
+(`.github/skills/`). Deployer-specific skills (Ansible, Tera templates, LXD, SDK,
+deployer CLI architecture) are excluded because they have no equivalent in the tracker.
+
+Directory layout to mirror the deployer structure:
+
+```text
+.github/skills/
+  add-new-skill/
+  dev/
+    git-workflow/
+    maintenance/
+    planning/
+    rust-code-quality/
+    testing/
+```
+
+**`add-new-skill`** — meta-skill: guide for creating new Agent Skills for this repository.
+
+**`dev/git-workflow/`**:
+
+- `commit-changes` — commit following Conventional Commits; pre-commit verification checklist.
+- `create-feature-branch` — branch naming convention and lifecycle.
+- `open-pull-request` — open a PR via GitHub CLI or GitHub MCP tool; pre-flight checks.
+- `release-new-version` — version bump, signed release commit, signed tag, CI verification.
+- `review-pr` — review a PR against Torrust quality standards and checklist.
+- `run-linters` — run the full linting suite (`linter all`); fix individual linter failures.
+- `run-pre-commit-checks` — mandatory quality gates before every commit.
+
+**`dev/maintenance/`**:
+
+- `update-dependencies` — run `cargo update`, create branch, commit, push, open PR.
+
+**`dev/planning/`**:
+
+- `create-adr` — create an Architectural Decision Record in `docs/adrs/`.
+- `create-issue` — draft and open a GitHub issue following project conventions.
+- `write-markdown-docs` — GFM pitfalls (auto-links, ordered list numbering, etc.).
+- `cleanup-completed-issues` — remove issue doc files and update roadmap after PR merge.
+
+**`dev/rust-code-quality/`**:
+
+- `handle-errors-in-code` — `thiserror`-based structured errors; what/where/when/why context.
+- `handle-secrets` — wrapper types for tokens/passwords; never use plain `String` for secrets.
+
+**`dev/testing/`**:
+
+- `write-unit-test` — `it_should_*` naming, AAA pattern, `MockClock`, `TempDir`, `rstest`.
+
+Commit message: `docs(agents): add initial agent skills under .github/skills/`
+
+Checkpoint:
+
+- `linter all` exits with code `0`.
+- At least one skill can be successfully activated by GitHub Copilot.
+
+**References**:
+
+- https://agentskills.io/specification
+- https://docs.github.com/en/copilot/concepts/agents/about-agent-skills
+- https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-skills
+- https://github.com/anthropics/skills (community skills examples)
+- https://github.com/github/awesome-copilot (community collection)
+
+---
+
+### Task 3: Add Custom Agents
+
+Define custom GitHub Copilot agents tailored to Torrust project workflows so that specialized
+tasks can be delegated to focused agents with the right prompt context.
+
+- [ ] Create `.github/agents/` directory
+- [ ] Identify workflows that benefit from a dedicated agent (e.g. issue implementation planner, code reviewer, documentation writer, release drafter)
+- [ ] For each agent, create `.github/agents/<agent-name>.md` with:
+  - YAML frontmatter: `name` (optional), `description`, optional `tools`
+  - Prompt body: role definition, scope, constraints, and step-by-step instructions
+- [ ] Test each custom agent by assigning it to a task or issue in GitHub Copilot CLI
+
+**Candidate initial agents**:
+
+- `committer` — commit specialist: reads branch/diff, runs pre-commit checks (`linter all`),
+  proposes a GPG-signed Conventional Commit message, and creates the commit only after scope and
+  checks are clear. Reference:
+  [`torrust-tracker-demo/.github/agents/commiter.agent.md`](https://raw.githubusercontent.com/torrust/torrust-tracker-demo/refs/heads/main/.github/agents/commiter.agent.md)
+- `issue-planner` — given a GitHub issue, produces a detailed implementation plan document (like the ones in `docs/issues/`) including branch name, task breakdown, checkpoints, and commit message suggestions
+- `code-reviewer` — reviews PRs against Torrust coding conventions, clippy rules, and security considerations
+- `docs-writer` — creates or updates documentation files following the existing docs structure
+
+Commit message: `docs(agents): add initial custom agents under .github/agents/`
+
+Checkpoint:
+
+- `linter all` exits with code `0`.
+- At least one custom agent can be assigned to a task in GitHub Copilot CLI.
+
+**References**:
+
+- https://docs.github.com/en/copilot/concepts/agents/copilot-cli/about-custom-agents
+- https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/create-custom-agents-for-cli
+- https://docs.github.com/en/copilot/reference/customization-cheat-sheet
+
+---
+
+### Task 4 (optional / follow-up): Add nested `AGENTS.md` files in packages
+
+Once the root file is stable, evaluate whether any workspace packages have sufficiently different
+conventions or setup to warrant their own `AGENTS.md`. This can be tracked as a separate follow-up
+issue.
+
+---
+
+### Task 5: Add `copilot-setup-steps.yml` workflow
+
+Create `.github/workflows/copilot-setup-steps.yml` so that the GitHub Copilot cloud agent gets a
+fully prepared development environment before it starts working on any task. Without this file,
+Copilot discovers and installs dependencies itself via trial-and-error, which is slow and
+unreliable.
+
+The workflow must contain a single `copilot-setup-steps` job (the exact job name is required by
+Copilot). Steps run in GitHub Actions before Copilot starts; the file is also automatically
+executed as a normal CI workflow whenever it changes, providing built-in validation.
+
+**Reference example** (from `torrust-tracker-deployer`):
+https://raw.githubusercontent.com/torrust/torrust-tracker-deployer/refs/heads/main/.github/workflows/copilot-setup-steps.yml
+
+Minimum steps to include:
+
+- [ ] Trigger on `workflow_dispatch`, `push` and `pull_request` (scoped to the workflow file path)
+- [ ] `copilot-setup-steps` job on `ubuntu-latest`, `timeout-minutes: 30`, `permissions: contents: read`
+- [ ] `actions/checkout@v5` — check out the repository (verify this is still the latest stable
+      version on the GitHub Marketplace before merging)
+- [ ] `dtolnay/rust-toolchain@stable` — install the stable Rust toolchain (pin MSRV if needed)
+- [ ] `Swatinem/rust-cache@v2` — cache `target/` and `~/.cargo` between runs
+- [ ] `cargo build` warm-up — build the workspace (or key packages) so incremental compilation is
+      ready when Copilot starts editing
+- [ ] Install the `linter` binary —
+      `cargo install --locked --git https://github.com/torrust/torrust-linting --bin linter`
+- [ ] Install `cargo-machete` — `cargo install cargo-machete`; ensures Copilot can run unused
+      dependency checks (`cargo machete`) as required by the essential rules
+- [ ] Smoke-check: run `linter all` to confirm the environment is healthy before Copilot begins
+
+Commit message: `ci(copilot): add copilot-setup-steps workflow`
+
+Checkpoint:
+
+- The workflow runs successfully via the repository's **Actions** tab (manual dispatch or push to
+  the file).
+- `linter all` exits with code `0` inside the workflow.
+
+**References**:
+
+- https://docs.github.com/en/copilot/how-tos/use-copilot-agents/cloud-agent/customize-the-agent-environment
+- https://raw.githubusercontent.com/torrust/torrust-tracker-deployer/refs/heads/main/.github/workflows/copilot-setup-steps.yml
+
+---
+
+### Task 6: Create an ADR for the AI agent framework approach
+
+> **Note**: This task documents the decision that underlies the whole issue. It can be done
+> before Tasks 1–5 if preferred — recording the decision first and then implementing it is
+> the conventional ADR practice.
+
+Document the decision to build a custom, GitHub-Copilot-aligned agent framework (AGENTS.md +
+Agent Skills + Custom Agents) rather than adopting one of the existing pre-defined agent
+frameworks that were evaluated.
+
+**Frameworks evaluated and not adopted**:
+
+- [obra/superpowers](https://github.com/obra/superpowers)
+- [gsd-build/get-shit-done](https://github.com/gsd-build/get-shit-done)
+
+**Reasons for not adopting them**:
+
+1. Complexity mismatch — they introduce abstractions that are heavier than what tracker
+   development needs.
+2. Precision requirements — the tracker involves low-level programming where agent work must be
+   reviewed carefully; generic productivity frameworks are not designed around that constraint.
+3. GitHub-first ecosystem — the tracker is hosted on GitHub and makes intensive use of GitHub
+   resources (Actions, Copilot, MCP tools, etc.). Staying aligned with GitHub Copilot avoids
+   unnecessary integration friction.
+4. Tooling churn — the AI agent landscape is evolving rapidly; depending on a third-party
+   framework risks forced refactoring when that framework is deprecated or pivots. A first-party
+   approach is more stable.
+5. Tailored fit — a custom solution can be shaped precisely to Torrust conventions, commit style,
+   linting gates, and package structure from day one.
+6. Proven in practice — the same approach has already been validated during the development of
+   `torrust-tracker-deployer`.
+7. Agent-agnostic by design — keeping the framework expressed as plain Markdown files
+   (AGENTS.md, SKILL.md, agent profiles) decouples it from any single agent product, making
+   migration or multi-agent use straightforward.
+8. Incremental adoption — individual skills, custom agents, or patterns from those frameworks can
+   still be cherry-picked and integrated progressively if specific value is identified.
+
+- [ ] Create `docs/adrs/<YYYYMMDDHHMMSS>_ai-agent-framework-approach.md` using the `create-adr` skill
+- [ ] Record the decision, the alternatives considered, and the reasoning above
+
+Commit message: `docs(adrs): add ADR for AI agent framework approach`
+
+Checkpoint:
+
+- `linter all` exits with code `0`.
+
+**References**:
+
+- `docs/adrs/README.md` — ADR naming convention for this repository
+- https://adr.github.io/
+
+---
+
+## Acceptance Criteria
+
+- [ ] `AGENTS.md` exists at the repo root and contains accurate, up-to-date project guidance.
+- [ ] At least one skill is available under `.github/skills/` and can be successfully activated by GitHub Copilot.
+- [ ] At least one custom agent is available under `.github/agents/` and can be assigned to a task.
+- [ ] `copilot-setup-steps.yml` exists, the workflow runs successfully in the **Actions** tab, and `linter all` exits with code `0` inside it.
+- [ ] An ADR exists in `docs/adrs/` documenting the decision to use a custom GitHub-Copilot-aligned agent framework.
+- [ ] All files pass spelling checks (`cspell`) and markdown linting.
+- [ ] A brief entry in `docs/index.md` points contributors to `AGENTS.md`, `.github/skills/`, and `.github/agents/`.
diff --git a/project-words.txt b/project-words.txt
index 48c9565cc..6a8a264ad 100644
--- a/project-words.txt
+++ b/project-words.txt
@@ -36,6 +36,7 @@ clippy
 cloneable
 codecov
 codegen
+commiter
 completei
 Condvar
 connectionless
@@ -117,6 +118,7 @@ nonroot
 Norberg
 numwant
 nvCFlJCq7fz7Qx6KoKTDiMZvns8l5Kw7
+obra
 oneshot
 ostr
 Pando
@@ -166,6 +168,7 @@ tdyne
 Tebibytes
 tempfile
 testcontainers
+Tera
 thiserror
 tlsv
 Torrentstorm
@@ -250,3 +253,9 @@ mysqladmin
 setgroups
 taplo
 trixie
+adrs
+Agentic
+agentskills
+frontmatter
+MSRV
+rustup

From 5593dd2d9f368892f112e6a9d20dd6723fb84a9d Mon Sep 17 00:00:00 2001
From: Jose Celano <josecelano@gmail.com>
Date: Mon, 20 Apr 2026 18:29:37 +0100
Subject: [PATCH 11/23] docs(agents): add root AGENTS.md

---
 .gitignore        |   1 +
 AGENTS.md         | 388 ++++++++++++++++++++++++++++++++++++++++++++++
 cspell.json       |   3 +-
 project-words.txt |   1 +
 4 files changed, 392 insertions(+), 1 deletion(-)
 create mode 100644 AGENTS.md

diff --git a/.gitignore b/.gitignore
index fd83ee918..4b811d59f 100644
--- a/.gitignore
+++ b/.gitignore
@@ -17,4 +17,5 @@ codecov.json
 integration_tests_sqlite3.db
 lcov.info
 perf.data*
+repomix-output.xml
 rustc-ice-*.txt
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 000000000..9ad7e360a
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,388 @@
+# Torrust Tracker — AI Assistant Instructions
+
+**Repository**: [torrust/torrust-tracker](https://github.com/torrust/torrust-tracker)
+
+## 📋 Project Overview
+
+**Torrust Tracker** is a high-quality, production-grade BitTorrent tracker written in Rust. It
+matchmakes peers and collects statistics, supporting the UDP, HTTP, and TLS socket types with
+native IPv4/IPv6 support, private/whitelisted mode, and a management REST API.
+
+- **Language**: Rust (edition 2021, MSRV 1.72)
+- **License**: AGPL-3.0-only
+- **Version**: 3.0.0-develop
+- **Web framework**: [Axum](https://github.com/tokio-rs/axum)
+- **Async runtime**: Tokio
+- **Protocols**: BitTorrent UDP (BEP 15), HTTP (BEP 3/23), REST management API
+- **Databases**: SQLite3, MySQL
+- **Workspace type**: Cargo workspace (multi-crate monorepo)
+
+## 🏗️ Tech Stack
+
+- **Languages**: Rust, YAML, TOML, Markdown, Shell scripts
+- **Web framework**: Axum (HTTP server + REST API)
+- **Async runtime**: Tokio (multi-thread)
+- **Testing**: testcontainers (E2E)
+- **Databases**: SQLite3, MySQL
+- **Containerization**: Docker / Podman (`Containerfile`)
+- **CI**: GitHub Actions
+- **Linting tools**: markdownlint, yamllint, taplo, cspell, shellcheck, clippy, rustfmt (unified
+  under the `linter` binary from [torrust/torrust-linting](https://github.com/torrust/torrust-linting))
+
+## 📁 Key Directories
+
+- `src/` — Main binary and library entry points (`main.rs`, `lib.rs`, `app.rs`, `container.rs`)
+- `src/bin/` — Additional binary targets (`e2e_tests_runner`, `http_health_check`, `profiling`)
+- `src/bootstrap/` — Application bootstrap logic
+- `src/console/` — Console entry points
+- `packages/` — Cargo workspace packages (all domain logic lives here; see package catalog below)
+- `console/` — Console tools (e.g., `tracker-client`)
+- `contrib/` — Community-contributed utilities (`bencode`) and developer tooling
+- `contrib/dev-tools/` — Developer tools: git hooks (`pre-commit.sh`, `pre-push.sh`),
+  container scripts, and init scripts
+- `tests/` — Integration tests (`integration.rs`, `servers/`)
+- `docs/` — Project documentation, ADRs, issue specs, and benchmarking guides
+- `docs/adrs/` — Architectural Decision Records
+- `docs/issues/` — Issue specs / implementation plans
+- `share/default/` — Default configuration files and fixtures
+- `storage/` — Runtime data (git-ignored); databases, logs, config
+- `.github/workflows/` — CI/CD workflows (testing, coverage, container, deployment)
+- `.github/skills/` — Agent Skills for specialized workflows _(to be added — see issue #1697)_
+- `.github/agents/` — Custom Copilot agents _(to be added — see issue #1697)_
+
+## 📦 Package Catalog
+
+All packages live under `packages/`. The workspace version is `3.0.0-develop`.
+
+| Package                           | Prefix / Layer | Description                                      |
+| --------------------------------- | -------------- | ------------------------------------------------ |
+| `axum-server`                     | `axum-*`       | Base Axum HTTP server infrastructure             |
+| `axum-http-tracker-server`        | `axum-*`       | BitTorrent HTTP tracker server (BEP 3/23)        |
+| `axum-rest-tracker-api-server`    | `axum-*`       | Management REST API server                       |
+| `axum-health-check-api-server`    | `axum-*`       | Health monitoring endpoint                       |
+| `http-tracker-core`               | `*-core`       | HTTP-specific tracker domain logic               |
+| `udp-tracker-core`                | `*-core`       | UDP-specific tracker domain logic                |
+| `tracker-core`                    | `*-core`       | Central tracker peer-management logic            |
+| `http-protocol`                   | `*-protocol`   | HTTP tracker protocol (BEP 3/23) parsing         |
+| `udp-protocol`                    | `*-protocol`   | UDP tracker protocol (BEP 15) framing/parsing    |
+| `swarm-coordination-registry`     | domain         | Torrent/peer coordination registry               |
+| `configuration`                   | domain         | Config file parsing, environment variables       |
+| `primitives`                      | domain         | Core domain types (InfoHash, PeerId, …)          |
+| `clock`                           | utilities      | Mockable time source for deterministic testing   |
+| `located-error`                   | utilities      | Diagnostic errors with source locations          |
+| `test-helpers`                    | utilities      | Mock servers, test data generation               |
+| `server-lib`                      | shared         | Shared server library utilities                  |
+| `tracker-client`                  | client tools   | CLI tracker interaction/testing client           |
+| `rest-tracker-api-client`         | client tools   | REST API client library                          |
+| `rest-tracker-api-core`           | client tools   | REST API core logic                              |
+| `udp-tracker-server`              | server         | UDP tracker server implementation                |
+| `torrent-repository`              | domain         | Torrent metadata storage and InfoHash management |
+| `events`                          | domain         | Domain event definitions                         |
+| `metrics`                         | domain         | Prometheus metrics integration                   |
+| `torrent-repository-benchmarking` | benchmarking   | Torrent storage benchmarks                       |
+
+**Console tools** (under `console/`):
+
+| Tool             | Description                          |
+| ---------------- | ------------------------------------ |
+| `tracker-client` | Client for interacting with trackers |
+
+**Community contributions** (under `contrib/`):
+
+| Crate     | Description                     |
+| --------- | ------------------------------- |
+| `bencode` | Bencode encode/decode utilities |
+
+## 🏷️ Package Naming Conventions
+
+| Prefix       | Responsibility                         | Dependencies             |
+| ------------ | -------------------------------------- | ------------------------ |
+| `axum-*`     | HTTP server components using Axum      | Axum framework           |
+| `*-server`   | Server implementations                 | Corresponding `*-core`   |
+| `*-core`     | Domain logic and business rules        | Protocol implementations |
+| `*-protocol` | BitTorrent protocol implementations    | BEP specifications       |
+| `udp-*`      | UDP protocol-specific implementations  | Tracker core             |
+| `http-*`     | HTTP protocol-specific implementations | Tracker core             |
+
+## 📄 Key Configuration Files
+
+| File                          | Used by                                                                                                                             |
+| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| `.markdownlint.json`          | markdownlint                                                                                                                        |
+| `.yamllint-ci.yml`            | yamllint                                                                                                                            |
+| `.taplo.toml`                 | taplo (TOML formatting)                                                                                                             |
+| `cspell.json` / `cSpell.json` | cspell (spell checker) — both filenames exist in the repo                                                                           |
+| `project-words.txt`           | cspell project-specific dictionary                                                                                                  |
+| `rustfmt.toml`                | rustfmt (`group_imports = "StdExternalCrate"`, `max_width = 130`)                                                                   |
+| `.cargo/config.toml`          | Cargo aliases (`cov`, `cov-lcov`, `cov-html`, `time`) and global `rustflags` (`-D warnings`, `-D unused`, `-D rust-2018-idioms`, …) |
+| `Cargo.toml`                  | Cargo workspace root                                                                                                                |
+| `compose.yaml`                | Docker Compose for local dev and demo                                                                                               |
+| `Containerfile`               | Container image definition                                                                                                          |
+| `codecov.yaml`                | Code coverage configuration                                                                                                         |
+
+## 🧪 Build & Test
+
+### Setup
+
+```sh
+rustup show                        # Check active toolchain
+rustup update                      # Update toolchain
+rustup toolchain install nightly   # Required: pre-commit hooks use cargo +nightly fmt/check/doc
+```
+
+### Build
+
+```sh
+cargo build                        # Build all workspace crates
+cargo build --release              # Release build
+cargo build --package <pkg>        # Build a specific package
+```
+
+### Test
+
+```sh
+cargo test --doc --workspace                                         # Documentation tests
+cargo test --tests --benches --examples --workspace \
+  --all-targets --all-features                                       # All tests
+cargo test -p <package-name>                                         # Single package
+
+# MySQL-specific tests (requires a running MySQL instance)
+TORRUST_TRACKER_CORE_RUN_MYSQL_DRIVER_TEST=true \
+  cargo test --package bittorrent-tracker-core
+
+# Integration tests (root)
+cargo test --test integration      # tests/integration.rs
+```
+
+### E2E Tests
+
+```sh
+cargo run --bin e2e_tests_runner -- \
+  --config-toml-path "./share/default/config/tracker.e2e.container.sqlite3.toml"
+```
+
+### Documentation
+
+```sh
+cargo +nightly doc --no-deps --bins --examples --workspace --all-features
+```
+
+### Benchmarks
+
+```sh
+cargo bench --package torrent-repository-benchmarking
+```
+
+See [docs/benchmarking.md](docs/benchmarking.md) and [docs/profiling.md](docs/profiling.md).
+
+## 🔍 Lint Commands
+
+The project uses the `linter` binary from
+[torrust/torrust-linting](https://github.com/torrust/torrust-linting).
+
+```sh
+# Install the linter binary
+cargo install --locked --git https://github.com/torrust/torrust-linting --bin linter
+
+# Run all linters (MANDATORY before every commit and PR)
+linter all
+
+# Run individual linters
+linter markdown     # markdownlint
+linter yaml        # yamllint
+linter toml        # taplo
+linter cspell      # spell checker
+linter clippy      # Rust linter
+linter rustfmt     # Rust formatter check
+linter shellcheck  # shell scripts
+```
+
+**`linter all` must exit with code `0` before every commit. PRs that fail CI linting are
+rejected without review.**
+
+## 🔗 Dependencies Check
+
+```sh
+cargo machete       # Check for unused dependencies (mandatory before commits)
+```
+
+Install via: `cargo install cargo-machete`
+
+## 🎨 Code Style
+
+- **rustfmt**: Format with `cargo fmt` before committing. Config: `rustfmt.toml`
+  (`group_imports = "StdExternalCrate"`, `imports_granularity = "Module"`, `max_width = 130`).
+- **Compile flags**: `.cargo/config.toml` enables strict global `rustflags` (`-D warnings`,
+  `-D unused`, `-D rust-2018-idioms`, `-D future-incompatible`, and others). All code must
+  compile cleanly with these flags — no suppressions unless absolutely necessary.
+- **clippy**: No warnings allowed (`cargo clippy -- -D warnings`).
+- **Imports**: All imports at the top of the file, grouped (std → external crates → internal
+  crate). Prefer short imported names over fully-qualified paths
+  (e.g., `Arc<MyType>` not `std::sync::Arc<crate::my::MyType>`). Use full paths only to
+  disambiguate naming conflicts.
+- **TOML**: Must pass `taplo fmt --check **/*.toml`. Auto-fix with `taplo fmt **/*.toml`.
+- **Markdown**: Must pass markdownlint.
+- **YAML**: Must pass `yamllint -c .yamllint-ci.yml`.
+- **Spell checking**: Add new technical terms to `project-words.txt` (one word per line,
+  alphabetical order).
+
+## 🤝 Collaboration Principles
+
+These rules apply repository-wide to every assistant, including custom agents.
+
+When acting as an assistant in this repository:
+
+- Do not flatter the user or agree with weak ideas by default.
+- Push back when a request, diff, or proposed commit looks wrong.
+- Flag unclear but important points before they become problems.
+- Ask a clarifying question instead of making a random choice when the decision matters.
+- Call out likely misses: naming inconsistencies, accidental generated files,
+  staged-versus-unstaged mismatches, missing docs updates, or suspicious commit scope.
+
+When raising a likely mistake or blocker, say so clearly and early instead of burying it after
+routine status updates.
+
+## 🔧 Essential Rules
+
+1. **Linting gate**: `linter all` must exit `0` before every commit. No exceptions.
+2. **GPG commit signing**: All commits **must** be signed with GPG (`git commit -S`).
+3. **Never commit `storage/` or `target/`**: These directories contain runtime data and build
+   artifacts. They are git-ignored; never force-add them.
+4. **Unused dependencies**: Run `cargo machete` before committing. Remove any unused
+   dependencies immediately.
+5. **Rust imports**: All imports at the top of the file, grouped (std → external crates →
+   internal crate). Prefer short imported names over fully-qualified paths.
+6. **Continuous self-review**: Review your own work against project quality standards. Apply
+   self-review at three levels:
+   - **Mandatory** — before opening a pull request
+   - **Strongly recommended** — before each commit
+   - **Recommended** — after completing each small, independent, deployable change
+7. **Security**: Do not report security vulnerabilities through public GitHub issues. Send an
+   email to `info@nautilus-cyberneering.de` instead. See [SECURITY.md](SECURITY.md).
+
+## 🌿 Git Workflow
+
+**Branch naming**:
+
+```text
+<issue-number>-<short-description>   # e.g. 1697-ai-agent-configuration (preferred)
+feat/<short-description>             # for features without a tracked issue
+fix/<short-description>              # for bug fixes
+chore/<short-description>            # for maintenance tasks
+```
+
+**Commit messages** follow [Conventional Commits](https://www.conventionalcommits.org/):
+
+```text
+feat(<scope>): add X
+fix(<scope>): resolve Y
+chore(<scope>): update Z
+docs(<scope>): document W
+refactor(<scope>): restructure V
+ci(<scope>): adjust pipeline U
+test(<scope>): add tests for T
+```
+
+Scope should reflect the affected package or area (e.g., `tracker-core`, `udp-protocol`, `ci`, `docs`).
+
+**Branch strategy**:
+
+- Feature branches are cut from `develop`
+- PRs target `develop`
+- `develop` → `staging/main` → `main` (release pipeline)
+- PRs must pass all CI status checks before merge
+
+See [docs/release_process.md](docs/release_process.md) for the full release workflow.
+
+## 🧭 Development Principles
+
+For detailed information see [`docs/`](docs/).
+
+**Core Principles:**
+
+- **Observability**: If it happens, we can see it — even after it happens (deep traceability)
+- **Testability**: Every component must be testable in isolation and as part of the whole
+- **Modularity**: Clear package boundaries; servers contain only network I/O logic
+- **Extensibility**: Core logic is framework-agnostic for easy protocol additions
+
+**Code Quality Standards** — both production and test code must be:
+
+- **Clean**: Well-structured with clear naming and minimal complexity
+- **Maintainable**: Easy to modify and extend without breaking existing functionality
+- **Readable**: Clear intent that can be understood by other developers
+- **Testable**: Designed to support comprehensive testing at all levels
+
+**Beck's Four Rules of Simple Design** (in priority order):
+
+1. **Passes the tests**: The code must work as intended — testing is a first-class activity
+2. **Reveals intention**: Code should be easy to understand, expressing purpose clearly
+3. **No duplication**: Apply DRY — eliminating duplication drives out good designs
+4. **Fewest elements**: Remove anything that doesn't serve the prior three rules
+
+Reference: [Beck Design Rules](https://martinfowler.com/bliki/BeckDesignRules.html)
+
+## 🐳 Container / Docker
+
+```sh
+# Run the latest image
+docker run -it torrust/tracker:latest
+# or with Podman
+podman run -it docker.io/torrust/tracker:latest
+
+# Build and run via Docker Compose
+docker compose up -d               # Start all services (detached)
+docker compose logs -f tracker     # Follow tracker logs
+docker compose down                # Stop and remove containers
+```
+
+**Volume mappings** (local `storage/` → container paths):
+
+```text
+./storage/tracker/lib  →  /var/lib/torrust/tracker
+./storage/tracker/log  →  /var/log/torrust/tracker
+./storage/tracker/etc  →  /etc/torrust/tracker
+```
+
+**Ports**: UDP tracker: `6969`, HTTP tracker: `7070`, REST API: `1212`
+
+See [docs/containers.md](docs/containers.md) for detailed container documentation.
+
+## 🎯 Auto-Invoke Skills
+
+Agent Skills will be available under `.github/skills/` once issue #1697 is implemented.
+
+> Skills supplement (not replace) the rules in this file. Rules apply always; skills activate
+> when their workflows are needed.
+
+**For VS Code**: Enable `chat.useAgentSkills` in settings to activate skill discovery.
+
+**Learn more**: See [Agent Skills Specification (agentskills.io)](https://agentskills.io/specification).
+
+## 📚 Documentation
+
+- [Documentation Index](docs/index.md)
+- [Package Architecture](docs/packages.md)
+- [Benchmarking](docs/benchmarking.md)
+- [Profiling](docs/profiling.md)
+- [Containers](docs/containers.md)
+- [Release Process](docs/release_process.md)
+- [ADRs](docs/adrs/README.md)
+- [Issues / Implementation Plans](docs/issues/)
+- [API docs (docs.rs)](https://docs.rs/torrust-tracker/)
+- [Report a security vulnerability](SECURITY.md)
+
+### Quick Navigation
+
+| Task                                 | Start Here                                           |
+| ------------------------------------ | ---------------------------------------------------- |
+| Understand the architecture          | [`docs/packages.md`](docs/packages.md)               |
+| Run the tracker in a container       | [`docs/containers.md`](docs/containers.md)           |
+| Read all docs                        | [`docs/index.md`](docs/index.md)                     |
+| Understand an architectural decision | [`docs/adrs/README.md`](docs/adrs/README.md)         |
+| Read or write an issue spec          | [`docs/issues/`](docs/issues/)                       |
+| Run benchmarks                       | [`docs/benchmarking.md`](docs/benchmarking.md)       |
+| Run profiling                        | [`docs/profiling.md`](docs/profiling.md)             |
+| Understand the release process       | [`docs/release_process.md`](docs/release_process.md) |
+| Report a security vulnerability      | [`SECURITY.md`](SECURITY.md)                         |
+| Agent skills reference               | `.github/skills/` _(coming — see issue #1697)_       |
+| Custom agents reference              | `.github/agents/` _(coming — see issue #1697)_       |
diff --git a/cspell.json b/cspell.json
index 02f29f7f9..3b2aeb6f4 100644
--- a/cspell.json
+++ b/cspell.json
@@ -22,6 +22,7 @@
         "contrib/bencode/benches/*.bencode",
         "contrib/dev-tools/su-exec/**",
         ".github/labels.json",
-        "/project-words.txt"
+        "/project-words.txt",
+        "repomix-output.xml"
     ]
 }
\ No newline at end of file
diff --git a/project-words.txt b/project-words.txt
index 6a8a264ad..ce81bfea6 100644
--- a/project-words.txt
+++ b/project-words.txt
@@ -143,6 +143,7 @@ ringsize
 rngs
 rosegment
 routable
+repomix
 rstest
 rusqlite
 rustc

From 760fafc705e9c28bdc7e9b5a3e8c140043b6ac22 Mon Sep 17 00:00:00 2001
From: Jose Celano <josecelano@gmail.com>
Date: Mon, 20 Apr 2026 18:30:36 +0100
Subject: [PATCH 12/23] chore(cspell): merge cSpell.json into cspell.json

---
 cSpell.json | 23 -----------------------
 cspell.json |  2 +-
 2 files changed, 1 insertion(+), 24 deletions(-)
 delete mode 100644 cSpell.json

diff --git a/cSpell.json b/cSpell.json
deleted file mode 100644
index 43eb391d3..000000000
--- a/cSpell.json
+++ /dev/null
@@ -1,23 +0,0 @@
-{
-    "$schema": "https://raw.githubusercontent.com/streetsidesoftware/cspell/main/cspell.schema.json",
-    "version": "0.2",
-    "dictionaryDefinitions": [
-        {
-            "name": "project-words",
-            "path": "./project-words.txt",
-            "addWords": true
-        }
-    ],
-    "dictionaries": [
-        "project-words"
-    ],
-    "enableFiletypes": [
-        "dockerfile",
-        "shellscript",
-        "toml"
-    ],
-    "ignorePaths": [
-        "target",
-        "/project-words.txt"
-    ]
-}
\ No newline at end of file
diff --git a/cspell.json b/cspell.json
index 3b2aeb6f4..39ddf510e 100644
--- a/cspell.json
+++ b/cspell.json
@@ -25,4 +25,4 @@
         "/project-words.txt",
         "repomix-output.xml"
     ]
-}
\ No newline at end of file
+}

From 03ec3bb0ac0d767341ec105ec700ea70e15b4976 Mon Sep 17 00:00:00 2001
From: Jose Celano <josecelano@gmail.com>
Date: Mon, 20 Apr 2026 18:37:32 +0100
Subject: [PATCH 13/23] docs(agents): add packages/AGENTS.md with package
 architecture guide

---
 packages/AGENTS.md | 152 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 152 insertions(+)
 create mode 100644 packages/AGENTS.md

diff --git a/packages/AGENTS.md b/packages/AGENTS.md
new file mode 100644
index 000000000..d3a7dae9d
--- /dev/null
+++ b/packages/AGENTS.md
@@ -0,0 +1,152 @@
+# Torrust Tracker — Packages
+
+This directory contains all Cargo workspace packages. All domain logic, protocol
+implementations, server infrastructure, and utility libraries live here.
+
+For full project context see the [root AGENTS.md](../AGENTS.md).
+
+## Architecture
+
+Packages are organized in strict layers. Dependencies only flow downward — a package may only
+depend on packages in the same layer or a lower one.
+
+```text
+┌────────────────────────────────────────────────────────────────┐
+│  Servers (delivery layer)                                      │
+│  axum-http-tracker-server  axum-rest-tracker-api-server        │
+│  axum-health-check-api-server  udp-tracker-server              │
+├────────────────────────────────────────────────────────────────┤
+│  Core (domain layer)                                           │
+│  http-tracker-core  udp-tracker-core  tracker-core             │
+│  rest-tracker-api-core  swarm-coordination-registry            │
+├────────────────────────────────────────────────────────────────┤
+│  Protocols                                                     │
+│  http-protocol  udp-protocol                                   │
+├────────────────────────────────────────────────────────────────┤
+│  Domain / Shared                                               │
+│  torrent-repository  configuration  primitives                 │
+│  events  metrics  clock  located-error  server-lib             │
+├────────────────────────────────────────────────────────────────┤
+│  Utilities / Test support                                      │
+│  test-helpers  located-error  clock                            │
+└────────────────────────────────────────────────────────────────┘
+```
+
+**Key architectural rule**: Servers contain only network I/O logic. All business rules live in
+`*-core` packages. Protocol parsing is isolated in `*-protocol` packages.
+
+See [docs/packages.md](../docs/packages.md) for a full diagram.
+
+## Package Catalog
+
+### Servers (`axum-*`, `udp-tracker-server`)
+
+Delivery layer — accept network connections, dispatch to core handlers, return responses.
+These packages must not contain business logic.
+
+| Package                        | Entry point  | Protocol    |
+| ------------------------------ | ------------ | ----------- |
+| `axum-http-tracker-server`     | `src/lib.rs` | HTTP BEP 3  |
+| `axum-rest-tracker-api-server` | `src/lib.rs` | REST (JSON) |
+| `axum-health-check-api-server` | `src/lib.rs` | HTTP        |
+| `axum-server`                  | `src/lib.rs` | Axum base   |
+| `udp-tracker-server`           | `src/lib.rs` | UDP BEP 15  |
+
+### Core (`*-core`)
+
+Domain layer — business rules, request validation, response building. No Axum or networking
+imports. Each core package exposes a `container` module that wires up its dependencies via
+dependency injection.
+
+| Package                       | Purpose                                                                                                                                    |
+| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| `tracker-core`                | Central peer management: announce/scrape handlers, auth, whitelist, database abstraction (SQLite/MySQL drivers in `src/databases/driver/`) |
+| `http-tracker-core`           | HTTP-specific validation and response formatting                                                                                           |
+| `udp-tracker-core`            | UDP connection cookies, crypto, banning logic                                                                                              |
+| `rest-tracker-api-core`       | REST API statistics and container wiring                                                                                                   |
+| `swarm-coordination-registry` | Registry of torrents and their peer swarms                                                                                                 |
+
+### Protocols (`*-protocol`)
+
+Strict BEP implementations — parse and serialize wire formats only. No tracker logic.
+
+| Package         | BEP    | Handles                                                        |
+| --------------- | ------ | -------------------------------------------------------------- |
+| `http-protocol` | BEP 3  | URL parameter parsing, bencoded responses, compact peer format |
+| `udp-protocol`  | BEP 15 | Message framing, connection IDs, transaction IDs               |
+
+### Domain / Shared
+
+| Package              | Purpose                                                                                                                                                              |
+| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `torrent-repository` | Torrent metadata storage; InfoHash management; peer coordination                                                                                                     |
+| `configuration`      | Config file parsing (`share/default/config/`) and env var loading (`TORRUST_TRACKER_CONFIG_TOML`, `TORRUST_TRACKER_CONFIG_TOML_PATH`); versioned under `src/v2_0_0/` |
+| `primitives`         | Core domain types: `InfoHash`, `PeerId`, `Peer`, `SwarmMetadata`, `ServiceBinding`                                                                                   |
+| `events`             | Async event bus (broadcaster / receiver / shutdown) used across packages                                                                                             |
+| `metrics`            | Prometheus-compatible metrics: counters, gauges, labels, samples                                                                                                     |
+| `server-lib`         | Shared HTTP server utilities: logging, service registrar, signal handling                                                                                            |
+| `clock`              | Mockable time source — use `clock::Working` in production, `clock::Stopped` in tests                                                                                 |
+| `located-error`      | Error decorator that captures the source file/line of the original error                                                                                             |
+
+### Client Tools
+
+| Package                   | Purpose                                                  |
+| ------------------------- | -------------------------------------------------------- |
+| `tracker-client`          | Generic HTTP and UDP tracker clients (used by E2E tests) |
+| `rest-tracker-api-client` | Typed REST API client library                            |
+
+### Utilities / Test support
+
+| Package                           | Purpose                                                    |
+| --------------------------------- | ---------------------------------------------------------- |
+| `test-helpers`                    | Mock servers, test data generators, shared test fixtures   |
+| `torrent-repository-benchmarking` | Criterion benchmarks for alternative torrent storage impls |
+
+## Naming Conventions
+
+| Prefix / Suffix | Responsibility                            | May depend on                 |
+| --------------- | ----------------------------------------- | ----------------------------- |
+| `axum-*`        | HTTP server components using Axum         | `*-core`, Axum framework      |
+| `*-server`      | Server implementations                    | Corresponding `*-core`        |
+| `*-core`        | Domain logic and business rules           | `*-protocol`, domain packages |
+| `*-protocol`    | BitTorrent protocol parsing/serialization | `primitives`                  |
+| `udp-*`         | UDP-specific implementations              | `tracker-core`                |
+| `http-*`        | HTTP-specific implementations             | `tracker-core`                |
+
+## Adding or Modifying a Package
+
+1. Create the directory under `packages/<new-package>/` with a `Cargo.toml` and `src/lib.rs`.
+2. Add the package to the workspace `[members]` in the root `Cargo.toml`.
+3. Follow the naming conventions above.
+4. Each package must have:
+   - A crate-level doc comment in `src/lib.rs` explaining its purpose and layer.
+   - At minimum one unit test (doc-test acceptable for simple utility crates).
+5. Run `cargo machete` after adding dependencies — unused deps must not be committed.
+6. Run `linter all` before committing.
+
+## Testing Packages
+
+```sh
+# All tests for a specific package
+cargo test -p <package-name>
+
+# Doc tests only
+cargo test --doc -p <package-name>
+
+# MySQL-specific tests in tracker-core (requires a running MySQL instance)
+TORRUST_TRACKER_CORE_RUN_MYSQL_DRIVER_TEST=true cargo test -p torrust-tracker-core
+```
+
+Use `clock::Stopped` (from the `clock` package) in unit tests that need deterministic time.
+Use `test-helpers` for mock tracker servers in integration tests.
+
+## Key Dependency Notes
+
+- `swarm-coordination-registry` is the authoritative store for peer swarms; `tracker-core`
+  delegates peer lookups to it.
+- `configuration` is the only package that reads from the filesystem or environment at startup;
+  other packages receive config structs as arguments.
+- `located-error` wraps any `std::error::Error` — use it at module boundaries to preserve
+  error origin context without losing the original error type.
+- `events` provides the only sanctioned inter-package async communication channel; avoid direct
+  `tokio::sync` coupling between packages.

From d4efa67e6765aa92c5e8d03c94cbbdae95d6632d Mon Sep 17 00:00:00 2001
From: Jose Celano <josecelano@gmail.com>
Date: Mon, 20 Apr 2026 18:40:08 +0100
Subject: [PATCH 14/23] docs(issues): update progress for issue #1697 task 1

---
 docs/issues/1697-ai-agent-configuration.md | 36 +++++++++++-----------
 1 file changed, 18 insertions(+), 18 deletions(-)

diff --git a/docs/issues/1697-ai-agent-configuration.md b/docs/issues/1697-ai-agent-configuration.md
index 8e0e7b932..b482e1f23 100644
--- a/docs/issues/1697-ai-agent-configuration.md
+++ b/docs/issues/1697-ai-agent-configuration.md
@@ -64,24 +64,24 @@ effectively without requiring repeated manual instructions.
 Create `AGENTS.md` in the repository root, adapting the above files to the tracker. At minimum
 the file must cover:
 
-- [ ] Repository link and project overview (language, license, MSRV, web framework, protocols, databases)
-- [ ] Tech stack (languages, frameworks, databases, containerization, linting tools)
-- [ ] Key directories (`src/`, `src/bin/`, `packages/`, `console/`, `contrib/`, `tests/`, `docs/`, `share/`, `storage/`, `.github/workflows/`)
-- [ ] Package catalog (all workspace packages with their layer and description)
-- [ ] Package naming conventions (`axum-*`, `*-server`, `*-core`, `*-protocol`)
-- [ ] Key configuration files (`.markdownlint.json`, `.yamllint-ci.yml`, `.taplo.toml`, `cspell.json`, `rustfmt.toml`, etc.)
-- [ ] Build & test commands (`cargo build`, `cargo test --doc`, `cargo test --all-targets`, E2E runner, benchmarks)
-- [ ] Lint commands (`linter all` and individual linters; how to install the `linter` binary)
-- [ ] Dependencies check (`cargo machete`)
-- [ ] Code style (rustfmt rules, clippy policy, import grouping, per-format rules)
-- [ ] Collaboration principles (no flattery, push back on weak ideas, flag blockers early)
-- [ ] Essential rules (linting gate, GPG commit signing, no `storage/`/`target/` commits, `cargo machete`)
-- [ ] Git workflow (branch naming, Conventional Commits, branch strategy: `develop` → `staging/main` → `main`)
-- [ ] Development principles (observability, testability, modularity, extensibility; Beck's four rules)
-- [ ] Container / Docker (key commands, ports, volume mount paths)
-- [ ] Auto-invoke skills placeholder (to be filled in when `.github/skills/` is populated)
-- [ ] Documentation quick-navigation table
-- [ ] Add a brief entry to `docs/index.md` pointing contributors to `AGENTS.md`, `.github/skills/`, and `.github/agents/`
+- [x] Repository link and project overview (language, license, MSRV, web framework, protocols, databases)
+- [x] Tech stack (languages, frameworks, databases, containerization, linting tools)
+- [x] Key directories (`src/`, `src/bin/`, `packages/`, `console/`, `contrib/`, `tests/`, `docs/`, `share/`, `storage/`, `.github/workflows/`)
+- [x] Package catalog (all workspace packages with their layer and description)
+- [x] Package naming conventions (`axum-*`, `*-server`, `*-core`, `*-protocol`)
+- [x] Key configuration files (`.markdownlint.json`, `.yamllint-ci.yml`, `.taplo.toml`, `cspell.json`, `rustfmt.toml`, etc.)
+- [x] Build & test commands (`cargo build`, `cargo test --doc`, `cargo test --all-targets`, E2E runner, benchmarks)
+- [x] Lint commands (`linter all` and individual linters; how to install the `linter` binary)
+- [x] Dependencies check (`cargo machete`)
+- [x] Code style (rustfmt rules, clippy policy, import grouping, per-format rules)
+- [x] Collaboration principles (no flattery, push back on weak ideas, flag blockers early)
+- [x] Essential rules (linting gate, GPG commit signing, no `storage/`/`target/` commits, `cargo machete`)
+- [x] Git workflow (branch naming, Conventional Commits, branch strategy: `develop` → `staging/main` → `main`)
+- [x] Development principles (observability, testability, modularity, extensibility; Beck's four rules)
+- [x] Container / Docker (key commands, ports, volume mount paths)
+- [x] Auto-invoke skills placeholder (to be filled in when `.github/skills/` is populated)
+- [x] Documentation quick-navigation table
+- [x] Add a brief entry to `docs/index.md` pointing contributors to `AGENTS.md`, `.github/skills/`, and `.github/agents/`
 
 Commit message: `docs(agents): add root AGENTS.md`
 

From 9831b24c7eaa7a3fb61cd6f4e645947e83c38d70 Mon Sep 17 00:00:00 2001
From: Jose Celano <josecelano@gmail.com>
Date: Mon, 20 Apr 2026 18:44:03 +0100
Subject: [PATCH 15/23] docs(agents): add src/AGENTS.md with bootstrap wiring
 guide

---
 src/AGENTS.md | 109 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 109 insertions(+)
 create mode 100644 src/AGENTS.md

diff --git a/src/AGENTS.md b/src/AGENTS.md
new file mode 100644
index 000000000..88296f152
--- /dev/null
+++ b/src/AGENTS.md
@@ -0,0 +1,109 @@
+# `src/` — Binary and Library Entry Points
+
+This directory contains only the top-level wiring of the application: the binary entry points,
+the bootstrap sequence, and the dependency-injection container. All domain logic lives in
+`packages/`; this directory merely assembles and launches it.
+
+## File Map
+
+| Path                        | Purpose                                                                                                                   |
+| --------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| `main.rs`                   | Binary entry point. Calls `app::run()`, waits for Ctrl-C, then cancels jobs and waits for graceful shutdown.              |
+| `lib.rs`                    | Library crate root and crate-level documentation. Re-exports the public API used by integration tests and other binaries. |
+| `app.rs`                    | `run()` and `start()` — orchestrates the full startup sequence (setup → load data from DB → start jobs).                  |
+| `container.rs`              | `AppContainer` — dependency-injection struct that holds `Arc`-wrapped instances of every per-layer container.             |
+| `bootstrap/app.rs`          | `setup()` — loads config, validates it, initializes logging and global services, builds `AppContainer`.                   |
+| `bootstrap/config.rs`       | `initialize_configuration()` — reads config from the environment / file.                                                  |
+| `bootstrap/jobs/`           | One module per service: each module exposes a starter function called from `app::start_jobs`.                             |
+| `bootstrap/jobs/manager.rs` | `JobManager` — collects `JoinHandle`s, owns the `CancellationToken`, and drives graceful shutdown.                        |
+| `bin/e2e_tests_runner.rs`   | Binary that runs E2E tests by delegating to `src/console/ci/`.                                                            |
+| `bin/http_health_check.rs`  | Minimal HTTP health-check binary used inside containers (avoids curl/wget dependency).                                    |
+| `bin/profiling.rs`          | Binary for Valgrind / kcachegrind profiling sessions.                                                                     |
+| `console/`                  | Internal console apps (`ci/e2e`, `profiling`) used by the extra binaries above.                                           |
+
+## Bootstrap Flow
+
+```text
+main()
+  └─ app::run()
+       ├─ bootstrap::app::setup()
+       │    ├─ bootstrap::config::initialize_configuration()   ← reads TOML / env vars
+       │    ├─ configuration.validate()                        ← panics on invalid config
+       │    ├─ initialize_global_services()                    ← logging, crypto seed
+       │    └─ AppContainer::initialize(&configuration)        ← builds all containers
+       │
+       └─ app::start(&config, &app_container)
+            ├─ load_data_from_database()                       ← peer keys, whitelist, metrics
+            └─ start_jobs()
+                 ├─ start_swarm_coordination_registry_event_listener
+                 ├─ start_tracker_core_event_listener
+                 ├─ start_http_core_event_listener
+                 ├─ start_udp_core_event_listener
+                 ├─ start_udp_server_stats_event_listener
+                 ├─ start_udp_server_banning_event_listener
+                 ├─ start_the_udp_instances        ← one job per configured UDP bind address
+                 ├─ start_the_http_instances       ← one job per configured HTTP bind address
+                 ├─ start_torrent_cleanup
+                 ├─ start_peers_inactivity_update
+                 ├─ start_the_http_api
+                 └─ start_health_check_api         ← always started
+```
+
+Shutdown (`main`): receives `Ctrl-C` → calls `jobs.cancel()` (fires the `CancellationToken`) →
+waits up to 10 seconds for all `JoinHandle`s to complete.
+
+## `AppContainer`
+
+`AppContainer` (`container.rs`) is a plain struct — not a framework, not a trait object tree.
+It holds one `Arc<…Container>` per architectural layer:
+
+| Field                                                                                            | Layer / Package                                          |
+| ------------------------------------------------------------------------------------------------ | -------------------------------------------------------- |
+| `registar`                                                                                       | `server-lib` — tracks active server socket registrations |
+| `swarm_coordination_registry_container`                                                          | `swarm-coordination-registry`                            |
+| `tracker_core_container`                                                                         | `tracker-core`                                           |
+| `http_tracker_core_services` / `http_tracker_instance_containers`                                | `http-tracker-core`                                      |
+| `udp_tracker_core_services` / `udp_tracker_server_container` / `udp_tracker_instance_containers` | `udp-tracker-core` / `udp-tracker-server`                |
+
+`AppContainer::initialize` is the only place where domain containers are constructed.
+Every `bootstrap/jobs/` starter receives an `&Arc<AppContainer>` and pulls out exactly what it
+needs — no globals, no lazy statics for domain objects.
+
+## `JobManager`
+
+`JobManager` (`bootstrap/jobs/manager.rs`) is a thin wrapper around a `Vec<Job>` (each `Job`
+holds a name + `JoinHandle<()>`) and a shared `CancellationToken`:
+
+- `push(name, handle)` — registers a job.
+- `push_opt(name, handle)` — convenience for jobs that may be disabled.
+- `cancel()` — fires the token; all jobs that own a clone of it will observe cancellation.
+- `wait_for_all(timeout)` — joins all handles with a timeout, logging warnings for any that
+  exceed it.
+
+## Adding a New Service
+
+When wiring a new server or background task, follow this checklist in order:
+
+1. **Package** — add the new crate under `packages/` with the appropriate layer prefix.
+2. **Container field** — add an `Arc<NewServiceContainer>` field to `AppContainer` and
+   initialize it inside `AppContainer::initialize`.
+3. **Job launcher** — create `src/bootstrap/jobs/new_service.rs` and register it in
+   `src/bootstrap/jobs/mod.rs`.
+4. **Wire into `app::start_jobs`** — call the new starter function and push its handle to
+   `job_manager`.
+5. **Graceful shutdown** — ensure the new service listens for the `CancellationToken` passed
+   from `JobManager`.
+6. **Config guard** — if the service is optional, gate the starter behind the appropriate
+   config field and use `push_opt`.
+
+## Key Rules for This Directory
+
+- **No domain logic here.** This directory is pure wiring. Business rules belong in `packages/`.
+- **No globals for domain objects.** All state flows through `AppContainer`.
+- **Startup errors panic.** `bootstrap::app::setup()` panics on invalid config or a bad crypto
+  seed — this is intentional (fail fast before binding ports).
+- **Health check always starts.** The health-check API job is unconditional — do not gate it
+  behind a config flag.
+- **`lib.rs` is the integration-test surface.** Integration tests import
+  `torrust_tracker_lib::…`. Keep the public API in `lib.rs` stable; avoid leaking internal
+  bootstrap details.

From 0900452302da7e10b570e8496f7092823600594d Mon Sep 17 00:00:00 2001
From: Jose Celano <josecelano@gmail.com>
Date: Mon, 20 Apr 2026 19:36:47 +0100
Subject: [PATCH 16/23] docs(agents): add agent skills, pre-commit scripts, git
 hooks, ADR index, and templates

- Add 19 agent skills under .github/skills/ covering git workflow,
  maintenance, planning, Rust code quality, and testing
- Add scripts/pre-commit.sh: unified pre-commit check runner
- Add scripts/install-git-hooks.sh: one-command git hook installer
- Add .githooks/pre-commit: checked-in hook delegating to pre-commit.sh
- Add docs/adrs/index.md: standalone ADR index table
- Update docs/adrs/README.md: replace inline index with link to index.md
- Add docs/templates/ADR.md and docs/templates/ISSUE.md
- Update project-words.txt: add toplevel, behaviour, autolinks, backlinks, usize
- Update docs/issues/1697-ai-agent-configuration.md: mark Task 2 complete
---
 .githooks/pre-commit                          |   7 +
 .github/skills/add-new-skill/SKILL.md         | 146 +++++++++++++
 .../add-new-skill/references/specification.md |  65 ++++++
 .../dev/git-workflow/commit-changes/SKILL.md  | 155 ++++++++++++++
 .../create-feature-branch/SKILL.md            | 113 ++++++++++
 .../git-workflow/open-pull-request/SKILL.md   |  73 +++++++
 .../git-workflow/release-new-version/SKILL.md | 147 +++++++++++++
 .../dev/git-workflow/review-pr/SKILL.md       |  66 ++++++
 .../dev/git-workflow/run-linters/SKILL.md     | 121 +++++++++++
 .../run-linters/references/linters.md         |  85 ++++++++
 .../run-pre-commit-checks/SKILL.md            |  88 ++++++++
 .../dev/maintenance/install-linter/SKILL.md   |  62 ++++++
 .../setup-dev-environment/SKILL.md            | 123 +++++++++++
 .../maintenance/update-dependencies/SKILL.md  | 120 +++++++++++
 .../cleanup-completed-issues/SKILL.md         |  88 ++++++++
 .../skills/dev/planning/create-adr/SKILL.md   | 112 ++++++++++
 .../skills/dev/planning/create-issue/SKILL.md | 101 +++++++++
 .../dev/planning/write-markdown-docs/SKILL.md |  70 ++++++
 .../handle-errors-in-code/SKILL.md            | 114 ++++++++++
 .../rust-code-quality/handle-secrets/SKILL.md |  87 ++++++++
 .../dev/testing/write-unit-test/SKILL.md      | 201 ++++++++++++++++++
 docs/adrs/README.md                           |  27 ++-
 docs/adrs/index.md                            |   5 +
 docs/issues/1697-ai-agent-configuration.md    |  42 ++--
 docs/templates/ADR.md                         |  24 +++
 docs/templates/ISSUE.md                       |  33 +++
 project-words.txt                             |   5 +
 scripts/install-git-hooks.sh                  |  37 ++++
 scripts/pre-commit.sh                         |  81 +++++++
 29 files changed, 2369 insertions(+), 29 deletions(-)
 create mode 100644 .githooks/pre-commit
 create mode 100644 .github/skills/add-new-skill/SKILL.md
 create mode 100644 .github/skills/add-new-skill/references/specification.md
 create mode 100644 .github/skills/dev/git-workflow/commit-changes/SKILL.md
 create mode 100644 .github/skills/dev/git-workflow/create-feature-branch/SKILL.md
 create mode 100644 .github/skills/dev/git-workflow/open-pull-request/SKILL.md
 create mode 100644 .github/skills/dev/git-workflow/release-new-version/SKILL.md
 create mode 100644 .github/skills/dev/git-workflow/review-pr/SKILL.md
 create mode 100644 .github/skills/dev/git-workflow/run-linters/SKILL.md
 create mode 100644 .github/skills/dev/git-workflow/run-linters/references/linters.md
 create mode 100644 .github/skills/dev/git-workflow/run-pre-commit-checks/SKILL.md
 create mode 100644 .github/skills/dev/maintenance/install-linter/SKILL.md
 create mode 100644 .github/skills/dev/maintenance/setup-dev-environment/SKILL.md
 create mode 100644 .github/skills/dev/maintenance/update-dependencies/SKILL.md
 create mode 100644 .github/skills/dev/planning/cleanup-completed-issues/SKILL.md
 create mode 100644 .github/skills/dev/planning/create-adr/SKILL.md
 create mode 100644 .github/skills/dev/planning/create-issue/SKILL.md
 create mode 100644 .github/skills/dev/planning/write-markdown-docs/SKILL.md
 create mode 100644 .github/skills/dev/rust-code-quality/handle-errors-in-code/SKILL.md
 create mode 100644 .github/skills/dev/rust-code-quality/handle-secrets/SKILL.md
 create mode 100644 .github/skills/dev/testing/write-unit-test/SKILL.md
 create mode 100644 docs/adrs/index.md
 create mode 100644 docs/templates/ADR.md
 create mode 100644 docs/templates/ISSUE.md
 create mode 100755 scripts/install-git-hooks.sh
 create mode 100755 scripts/pre-commit.sh

diff --git a/.githooks/pre-commit b/.githooks/pre-commit
new file mode 100644
index 000000000..6e4065777
--- /dev/null
+++ b/.githooks/pre-commit
@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+repo_root="$(git rev-parse --show-toplevel)"
+
+"$repo_root/scripts/pre-commit.sh"
\ No newline at end of file
diff --git a/.github/skills/add-new-skill/SKILL.md b/.github/skills/add-new-skill/SKILL.md
new file mode 100644
index 000000000..d99b4e3c9
--- /dev/null
+++ b/.github/skills/add-new-skill/SKILL.md
@@ -0,0 +1,146 @@
+---
+name: add-new-skill
+description: Guide for creating effective Agent Skills for the torrust-tracker project. Use when you need to create a new skill (or update an existing skill) that extends AI agent capabilities with specialized knowledge, workflows, or tool integrations. Triggers on "create skill", "add new skill", "how to add skill", or "skill creation".
+metadata:
+  author: torrust
+  version: "1.0"
+---
+
+# Creating New Agent Skills
+
+This skill guides you through creating effective Agent Skills for the Torrust Tracker project.
+
+## About Skills
+
+**What are Agent Skills?**
+
+Agent Skills are specialized instruction sets that extend AI agent capabilities with domain-specific
+knowledge, workflows, and tool integrations. They follow the [agentskills.io](https://agentskills.io)
+open format and work with multiple AI coding agents (Claude Code, VS Code Copilot, Cursor, Windsurf).
+
+### Progressive Disclosure
+
+Skills use a three-level loading strategy to minimize context window usage:
+
+1. **Metadata** (~100 tokens): `name` and `description` loaded at startup for all skills
+2. **SKILL.md Body** (<5000 tokens): Loaded when a task matches the skill's description
+3. **Bundled Resources**: Loaded on-demand only when referenced (scripts, references, assets)
+
+### When to Create a Skill vs Updating AGENTS.md
+
+| Use AGENTS.md for...            | Use Skills for...               |
+| ------------------------------- | ------------------------------- |
+| Always-on rules and constraints | On-demand workflows             |
+| "Always do X, never do Y"       | Multi-step repeatable processes |
+| Baseline conventions            | Specialist domain knowledge     |
+| Rarely changes                  | Can be added/refined frequently |
+
+**Example**: "Use lowercase for skill filenames" → AGENTS.md rule.
+"How to run pre-commit checks" → Skill.
+
+## Core Principles
+
+### 1. Concise is Key
+
+**Context window is shared** between system prompt, conversation history, other skills,
+and your actual request. Only add context the agent doesn't already have.
+
+### 2. Set Appropriate Degrees of Freedom
+
+Match specificity to task fragility:
+
+- **High freedom** (text-based instructions): multiple approaches valid, context-dependent
+- **Medium freedom** (pseudocode): preferred pattern exists, some variation acceptable
+- **Low freedom** (specific scripts): operations are fragile, sequence must be followed
+
+### 3. Anatomy of a Skill
+
+A skill consists of:
+
+- **SKILL.md**: Frontmatter (metadata) + body (instructions)
+- **Optional bundled resources**: `scripts/`, `references/`, `assets/`
+
+Keep SKILL.md concise (<500 lines). Move detailed content to reference files.
+
+### 4. Progressive Disclosure
+
+Split detailed content into reference files loaded on-demand:
+
+```markdown
+## Advanced Features
+
+See [specification.md](references/specification.md) for Agent Skills spec.
+See [patterns.md](references/patterns.md) for workflow patterns.
+```
+
+### 5. Content Strategy
+
+- **Include in SKILL.md**: essential commands and step-by-step workflows
+- **Put in `references/`**: detailed descriptions, config options, troubleshooting
+- **Link to official docs**: architecture docs, ADRs, contributing guides
+
+## Skill Creation Process
+
+### Step 1: Plan the Skill
+
+Answer:
+
+- What specific queries should trigger this skill?
+- What tasks does it help accomplish?
+- Does a similar skill already exist?
+
+### Step 2: Choose the Location
+
+Follow the directory layout:
+
+```text
+.github/skills/
+  add-new-skill/
+  dev/
+    git-workflow/
+    maintenance/
+    planning/
+    rust-code-quality/
+    testing/
+```
+
+### Step 3: Write the SKILL.md
+
+Frontmatter rules:
+
+- `name`: lowercase letters, numbers, hyphens only; max 64 chars; no consecutive hyphens
+- `description`: max 1024 chars; include trigger phrases; describe WHAT and WHEN
+- `metadata.author`: `torrust`
+- `metadata.version`: `"1.0"`
+
+### Step 4: Validate and Commit
+
+```bash
+# Check spelling and markdown
+linter cspell
+linter markdown
+
+# Run all linters
+linter all
+
+# Commit
+git add .github/skills/
+git commit -S -m "docs(skills): add {skill-name} skill"
+```
+
+## Directory Layout
+
+```text
+.github/skills/
+  <skill-name>/
+    SKILL.md            ← Required
+    references/         ← Optional: detailed docs
+    scripts/            ← Optional: executable scripts
+    assets/             ← Optional: templates, data
+```
+
+## References
+
+- Agent Skills specification: [references/specification.md](references/specification.md)
+- Skill patterns: [references/patterns.md](references/patterns.md)
+- Real examples: [references/examples.md](references/examples.md)
diff --git a/.github/skills/add-new-skill/references/specification.md b/.github/skills/add-new-skill/references/specification.md
new file mode 100644
index 000000000..90e73b8a6
--- /dev/null
+++ b/.github/skills/add-new-skill/references/specification.md
@@ -0,0 +1,65 @@
+# Agent Skills Specification Reference
+
+This document provides a reference to the Agent Skills specification from [agentskills.io](https://agentskills.io).
+
+## What is Agent Skills?
+
+Agent Skills is an open format for extending AI agent capabilities with specialized knowledge and
+workflows. It's vendor-neutral and works with Claude Code, VS Code Copilot, Cursor, and Windsurf.
+
+## Core Concepts
+
+### Progressive Disclosure
+
+```text
+Level 1: Metadata (name + description) - ~100 tokens - Loaded at startup for ALL skills
+Level 2: SKILL.md body - <5000 tokens - Loaded when skill matches task
+Level 3: Bundled resources - On-demand - Loaded only when referenced
+```
+
+### Directory Structure
+
+```text
+.github/
+└── skills/
+    └── skill-name/
+        ├── SKILL.md          # Required: frontmatter + instructions
+        ├── README.md         # Optional: human-readable documentation
+        ├── scripts/          # Optional: executable code
+        ├── references/       # Optional: detailed docs loaded on-demand
+        └── assets/           # Optional: templates, images, data
+```
+
+## SKILL.md Format
+
+### Frontmatter (YAML)
+
+```yaml
+---
+name: skill-name
+description: |
+  What the skill does and when to use it. Include trigger phrases.
+metadata:
+  author: torrust
+  version: "1.0"
+---
+```
+
+### Frontmatter Validation Rules
+
+**name**:
+
+- Required; max 64 characters
+- Lowercase letters, numbers, hyphens only
+- Cannot contain consecutive hyphens or XML tags
+
+**description**:
+
+- Required; max 1024 characters
+- Should describe WHAT the skill does AND WHEN to use it
+- Include trigger phrases/keywords
+
+## References
+
+- Official spec: <https://agentskills.io/specification>
+- GitHub Copilot skills docs: <https://docs.github.com/en/copilot/concepts/agents/about-agent-skills>
diff --git a/.github/skills/dev/git-workflow/commit-changes/SKILL.md b/.github/skills/dev/git-workflow/commit-changes/SKILL.md
new file mode 100644
index 000000000..415ee2895
--- /dev/null
+++ b/.github/skills/dev/git-workflow/commit-changes/SKILL.md
@@ -0,0 +1,155 @@
+---
+name: commit-changes
+description: Guide for committing changes in the torrust-tracker project. Covers conventional commit format, pre-commit verification checklist, GPG signing, and commit quality guidelines. Use when committing code, running pre-commit checks, or following project commit standards. Triggers on "commit", "commit changes", "how to commit", "pre-commit", "commit message", "commit format", or "conventional commits".
+metadata:
+  author: torrust
+  version: "1.0"
+---
+
+# Committing Changes
+
+This skill guides you through the complete commit process for the Torrust Tracker project.
+
+## Quick Reference
+
+```bash
+# One-time setup: install the pre-commit Git hook
+./scripts/install-git-hooks.sh
+
+# Stage changes
+git add <files>
+
+# Commit with conventional format and GPG signature (MANDATORY)
+# The pre-commit hook runs ./scripts/pre-commit.sh automatically
+git commit -S -m "<type>[(<scope>)]: <description>"
+```
+
+## Conventional Commit Format
+
+We follow [Conventional Commits](https://www.conventionalcommits.org/) specification.
+
+### Commit Message Structure
+
+```text
+<type>[optional scope]: <description>
+
+[optional body]
+
+[optional footer(s)]
+```
+
+Scope should reflect the affected package or area (e.g., `tracker-core`, `udp-protocol`, `ci`, `docs`).
+
+### Commit Types
+
+| Type       | Description                           | Example                                                      |
+| ---------- | ------------------------------------- | ------------------------------------------------------------ |
+| `feat`     | New feature or enhancement            | `feat(tracker-core): add peer expiry grace period`           |
+| `fix`      | Bug fix                               | `fix(udp-protocol): resolve endianness in announce response` |
+| `docs`     | Documentation changes                 | `docs(agents): add root AGENTS.md`                           |
+| `style`    | Code style changes (formatting, etc.) | `style: apply rustfmt to all source files`                   |
+| `refactor` | Code refactoring                      | `refactor(tracker-core): extract peer list to own module`    |
+| `test`     | Adding or updating tests              | `test(http-tracker-core): add announce response tests`       |
+| `chore`    | Maintenance tasks                     | `chore: update dependencies`                                 |
+| `ci`       | CI/CD related changes                 | `ci: add workflow for container publishing`                  |
+| `perf`     | Performance improvements              | `perf(torrent-repository): switch to dashmap`                |
+
+## GPG Commit Signing (MANDATORY)
+
+**All commits must be GPG signed.** Use the `-S` flag:
+
+```bash
+git commit -S -m "your commit message"
+```
+
+## Pre-commit Verification (MANDATORY)
+
+### Git Hook
+
+The repository ships a `pre-commit` Git hook that runs `./scripts/pre-commit.sh`
+automatically on every `git commit`. Install it once after cloning:
+
+```bash
+./scripts/install-git-hooks.sh
+```
+
+Once installed, the hook fires on every commit and you do not need to run the script manually.
+
+### Automated Checks
+
+If the hook is not installed, run the script explicitly before committing.
+**It must exit with code `0`.**
+
+> **⏱️ Expected runtime: ~3 minutes** on a modern developer machine. AI agents must set a
+> command timeout of **at least 5 minutes** before invoking this script.
+
+```bash
+./scripts/pre-commit.sh
+```
+
+The script runs:
+
+1. `cargo machete` — unused dependency check
+2. `linter all` — all linters (markdown, YAML, TOML, clippy, rustfmt, shellcheck, cspell)
+3. `cargo test --doc --workspace` — documentation tests
+4. `cargo test --tests --benches --examples --workspace --all-targets --all-features` — all tests
+
+### Manual Checks (Cannot Be Automated)
+
+Verify these by hand before committing:
+
+- **Self-review the diff**: read through `git diff --staged` and check for obvious mistakes,
+  debug artifacts, or unintended changes
+- **Documentation updated**: if public API or behaviour changed, doc comments and any relevant
+  `docs/` pages reflect the change
+- **`AGENTS.md` updated**: if architecture, package structure, or key workflows changed, the
+  relevant `AGENTS.md` file is updated
+- **New technical terms added to `project-words.txt`**: any new jargon or identifiers that
+  cspell does not know about are added alphabetically
+
+### Debugging a Failing Run
+
+```bash
+linter markdown    # Markdown
+linter yaml        # YAML
+linter toml        # TOML
+linter clippy      # Rust code analysis
+linter rustfmt     # Rust formatting
+linter shellcheck  # Shell scripts
+linter cspell      # Spell checking
+```
+
+Fix Rust formatting automatically:
+
+```bash
+cargo fmt
+```
+
+## Hashtag Usage Warning
+
+**Only use `#` when intentionally referencing a GitHub issue.**
+
+GitHub auto-links `#NUMBER` to issues. Avoid accidental references:
+
+- ✅ `feat(tracker-core): add feature (see #42)` — intentional reference
+- ❌ `fix: make feature #1 priority` — accidentally links to issue #1
+
+Use ordered Markdown lists or plain numbers instead of `#N` step labels.
+
+## Commit Quality Guidelines
+
+### Good Commits (✅)
+
+- **Atomic**: Each commit represents one logical change
+- **Descriptive**: Clear, concise description of what changed
+- **Tested**: All tests pass
+- **Linted**: All linters pass
+- **Conventional**: Follows conventional commit format
+- **Signed**: GPG signature present
+
+### Commits to Avoid (❌)
+
+- Too large: multiple unrelated changes in one commit
+- Vague messages like "fix stuff" or "WIP"
+- Missing scope when a package is clearly affected
+- Unsigned commits
diff --git a/.github/skills/dev/git-workflow/create-feature-branch/SKILL.md b/.github/skills/dev/git-workflow/create-feature-branch/SKILL.md
new file mode 100644
index 000000000..bb2c82a55
--- /dev/null
+++ b/.github/skills/dev/git-workflow/create-feature-branch/SKILL.md
@@ -0,0 +1,113 @@
+---
+name: create-feature-branch
+description: Guide for creating feature branches following the torrust-tracker branching conventions. Covers branch naming format, lifecycle, and common patterns. Use when creating branches for issues, starting work on tasks, or setting up development branches. Triggers on "create branch", "new branch", "checkout branch", "branch for issue", or "start working on issue".
+metadata:
+  author: torrust
+  version: "1.0"
+---
+
+# Creating Feature Branches
+
+This skill guides you through creating feature branches following the Torrust Tracker branching
+conventions.
+
+## Branch Naming Convention
+
+**Format**: `{issue-number}-{short-description}` (preferred)
+
+Alternative formats (no tracked issue):
+
+- `feat/{short-description}`
+- `fix/{short-description}`
+- `chore/{short-description}`
+
+**Rules**:
+
+- Always start with the GitHub issue number when one exists
+- Use lowercase letters only
+- Separate words with hyphens (not underscores)
+- Keep description concise but descriptive
+
+## Creating a Branch
+
+### Standard Workflow
+
+```bash
+# Ensure you're on latest develop
+git checkout develop
+git pull --ff-only
+
+# Create and checkout branch for issue #42
+git checkout -b 42-add-peer-expiry-grace-period
+```
+
+### With MCP GitHub Tools
+
+1. Get the issue number and title
+2. Format the branch name: `{number}-{kebab-case-description}`
+3. Create the branch from `develop`
+4. Checkout locally: `git fetch && git checkout {branch-name}`
+
+## Branch Naming Examples
+
+✅ **Good branch names**:
+
+- `42-add-peer-expiry-grace-period`
+- `156-refactor-udp-server-socket-binding`
+- `203-add-e2e-mysql-tests`
+- `1697-ai-agent-configuration`
+
+❌ **Avoid**:
+
+- `my-feature` — no issue number
+- `FEATURE-123` — all caps
+- `fix_bug` — underscores instead of hyphens
+- `42_add_support` — underscores
+
+## Complete Branch Lifecycle
+
+### 1. Create Branch from `develop`
+
+```bash
+git checkout develop
+git pull --ff-only
+git checkout -b 42-add-peer-expiry-grace-period
+```
+
+### 2. Develop
+
+Make commits following [commit conventions](../commit-changes/SKILL.md).
+
+### 3. Pre-commit Checks
+
+```bash
+cargo machete
+linter all
+cargo test --doc --workspace
+cargo test --tests --benches --examples --workspace --all-targets --all-features
+```
+
+### 4. Push to Your Fork
+
+```bash
+git push {your-fork-remote} 42-add-peer-expiry-grace-period
+```
+
+### 5. Create Pull Request
+
+Target branch: `torrust/torrust-tracker:develop`
+
+### 6. Cleanup After Merge
+
+```bash
+git checkout develop
+git pull --ff-only
+git branch -d 42-add-peer-expiry-grace-period
+```
+
+## Converting Issue Title to Branch Name
+
+1. Get issue number (e.g., #42)
+2. Take issue title (e.g., "Add Peer Expiry Grace Period")
+3. Convert to lowercase kebab-case: `add-peer-expiry-grace-period`
+4. Prefix with issue number: `42-add-peer-expiry-grace-period`
diff --git a/.github/skills/dev/git-workflow/open-pull-request/SKILL.md b/.github/skills/dev/git-workflow/open-pull-request/SKILL.md
new file mode 100644
index 000000000..eca0fae3b
--- /dev/null
+++ b/.github/skills/dev/git-workflow/open-pull-request/SKILL.md
@@ -0,0 +1,73 @@
+---
+name: open-pull-request
+description: Open a pull request from a feature branch using GitHub CLI (preferred) or GitHub MCP tools. Covers pre-flight checks, correct base/head configuration for fork workflows, title/body conventions, and post-creation validation. Use when asked to "open PR", "create pull request", or "submit branch for review".
+metadata:
+  author: torrust
+  version: "1.0"
+---
+
+# Open a Pull Request
+
+## CLI vs MCP Decision Rule
+
+- **Inner loop (fast local branch work):** prefer GitHub CLI (`gh pr create`).
+- **Outer loop (cross-system coordination):** use MCP tools for structured/authenticated access.
+
+## Pre-flight Checks
+
+Before opening a PR:
+
+- [ ] Working tree is clean (`git status`)
+- [ ] Branch is pushed to your fork remote
+- [ ] Commits are GPG signed (`git log --show-signature -n 1`)
+- [ ] All pre-commit checks passed (`linter all`, `cargo machete`, tests)
+
+## Title and Description Convention
+
+PR title: use Conventional Commit style, include issue reference.
+
+Examples:
+
+- `feat(tracker-core): [#42] add peer expiry grace period`
+- `docs(agents): set up basic AI agent configuration (#1697)`
+
+PR body must include:
+
+- Summary of changes
+- Files/packages touched
+- Validation performed
+- Issue link (`Closes #<issue-number>`)
+
+## Option A (Preferred): GitHub CLI
+
+```bash
+gh pr create \
+  --repo torrust/torrust-tracker \
+  --base develop \
+  --head <fork-owner>:<branch-name> \
+  --title "<title>" \
+  --body "<body>"
+```
+
+If successful, `gh` prints the PR URL.
+
+## Option B: GitHub MCP Tools
+
+When MCP pull request management tools are available, create the PR with:
+
+- `base`: `develop`
+- `head`: `<fork-owner>:<branch-name>`
+- Capture and share the resulting PR URL.
+
+## Post-creation Validation
+
+- [ ] PR targets `torrust/torrust-tracker:develop`
+- [ ] Head branch is correct
+- [ ] CI workflows started
+- [ ] Issue linked in description
+
+## Troubleshooting
+
+- `fatal: ... does not appear to be a git repository`: push to correct remote (`git remote -v`)
+- `A pull request already exists`: open existing PR URL instead of creating new
+- Permission errors on upstream: use `owner:branch` fork syntax
diff --git a/.github/skills/dev/git-workflow/release-new-version/SKILL.md b/.github/skills/dev/git-workflow/release-new-version/SKILL.md
new file mode 100644
index 000000000..f30898511
--- /dev/null
+++ b/.github/skills/dev/git-workflow/release-new-version/SKILL.md
@@ -0,0 +1,147 @@
+---
+name: release-new-version
+description: Guide for releasing a new version of the Torrust Tracker using the standard staging branch, tag, and crate publication workflow. Covers version bump, release commit, staging branch promotion, PR to main, release branch/tag creation, crate publication, and merge-back to develop. Use when asked to "release", "cut a version", "publish a new version", or "create release vX.Y.Z".
+metadata:
+  author: torrust
+  version: "1.0"
+---
+
+# Release New Version
+
+Primary reference: [`docs/release_process.md`](../../../../../docs/release_process.md)
+
+## Release Steps (Mandatory Order)
+
+1. Stage `develop` → `staging/main`
+2. Create release commit (bump version)
+3. PR `staging/main` → `main`
+4. Push `main` → `releases/vX.Y.Z`
+5. Create signed tag `vX.Y.Z` on that branch
+6. Verify deployment workflow + crate publication
+7. Create GitHub release
+8. Stage `main` → `staging/develop` (merge-back)
+9. Bump next dev version, PR `staging/develop` → `develop`
+
+Do not reorder these steps.
+
+## Version Naming Rules
+
+- Version in code: `X.Y.Z` (release) or `X.Y.Z-develop` (development)
+- Git tag: `vX.Y.Z`
+- Release branch: `releases/vX.Y.Z`
+- Staging branches: `staging/main`, `staging/develop`
+
+## Pre-Flight Checklist
+
+Before starting:
+
+- [ ] Clean working tree (`git status`)
+- [ ] `develop` branch is up to date with `torrust/develop`
+- [ ] All CI checks pass on `develop`
+- [ ] Working version in manifests is `X.Y.Z-develop`
+
+## Commands
+
+### 1) Stage develop → staging/main
+
+```bash
+git fetch --all
+git push --force torrust develop:staging/main
+```
+
+### 2) Create Release Commit
+
+```bash
+git stash
+git switch staging/main
+git reset --hard torrust/staging/main
+# Edit version in all Cargo.toml files:
+#   change X.Y.Z-develop → X.Y.Z
+git add -A
+git commit -S -m "release: version X.Y.Z"
+git push torrust
+```
+
+Edit `version` in:
+
+- `Cargo.toml` (workspace)
+- All packages under `packages/` that publish crates
+- `console/tracker-client/Cargo.toml`
+- `contrib/bencode/Cargo.toml`
+
+Also update any internal path dependency `version` constraints.
+
+### 3) PR staging/main → main
+
+Create PR: "Release Version X.Y.Z" (title format)  
+Base: `torrust/torrust-tracker:main`  
+Head: `staging/main`  
+Merge after CI passes.
+
+### 4) Push releases/vX.Y.Z branch
+
+```bash
+git fetch --all
+git push torrust main:releases/vX.Y.Z
+```
+
+### 5) Create Signed Tag
+
+```bash
+git switch releases/vX.Y.Z
+git reset --hard torrust/releases/vX.Y.Z
+git tag --sign vX.Y.Z
+git push --tags torrust
+```
+
+### 6) Verify Deployment Workflow
+
+Check the
+[deployment workflow](https://github.com/torrust/torrust-tracker/actions/workflows/deployment.yaml)
+ran successfully and the following crates were published:
+
+- `torrust-tracker-contrib-bencode`
+- `torrust-tracker-located-error`
+- `torrust-tracker-primitives`
+- `torrust-tracker-clock`
+- `torrust-tracker-configuration`
+- `torrust-tracker-torrent-repository`
+- `torrust-tracker-test-helpers`
+- `torrust-tracker`
+
+Crates must be published in dependency order. Each must be indexed on crates.io before the next
+publishes.
+
+### 7) Create GitHub Release
+
+Create a release from tag `vX.Y.Z` after the deployment workflow passes.
+
+### 8) Merge-back: Stage main → staging/develop
+
+```bash
+git fetch --all
+git push --force torrust main:staging/develop
+```
+
+### 9) Bump Next Dev Version
+
+```bash
+git stash
+git switch staging/develop
+git reset --hard torrust/staging/develop
+# Edit version in all Cargo.toml files:
+#   change X.Y.Z → (next)X.Y.Z-develop (e.g. 3.0.0 → 3.0.1-develop)
+git add -A
+git commit -S -m "develop: bump to version (next)X.Y.Z-develop"
+git push torrust
+```
+
+Create PR: "Version X.Y.Z was Released"  
+Base: `torrust/torrust-tracker:develop`  
+Head: `staging/develop`
+
+## Failure Handling
+
+- **Deployment workflow failed**: fix and rerun on same release branch
+- **Crate already published**: do not republish; cut a patch release
+- **Partial state (tag exists but branch doesn't)**: investigate before proceeding
diff --git a/.github/skills/dev/git-workflow/review-pr/SKILL.md b/.github/skills/dev/git-workflow/review-pr/SKILL.md
new file mode 100644
index 000000000..da4be9ca3
--- /dev/null
+++ b/.github/skills/dev/git-workflow/review-pr/SKILL.md
@@ -0,0 +1,66 @@
+---
+name: review-pr
+description: Review a pull request for the torrust-tracker project. Covers checklist-based PR quality verification, code style standards, test requirements, documentation, and how to submit review feedback. Use when asked to review a PR, check a pull request, or provide feedback on code changes. Triggers on "review PR", "review pull request", "check PR quality", or "code review".
+metadata:
+  author: torrust
+  version: "1.0"
+---
+
+# Reviewing a Pull Request
+
+## Quick Overview Approach
+
+1. Read the PR title and description for context
+2. Check the diff for scope of change
+3. Identify the affected packages and components
+4. Apply the checklist below
+
+## PR Review Checklist
+
+### PR Metadata
+
+- [ ] Title follows Conventional Commits format
+- [ ] Description clearly explains what changes were made and why
+- [ ] Issue is linked (`Closes #<number>` or `Refs #<number>`)
+- [ ] Target branch is `develop` (not `main`)
+
+### Code Quality
+
+- [ ] Code follows existing patterns in affected packages
+- [ ] No unused imports, variables, or functions
+- [ ] No `#[allow(...)]` suppressions unless clearly justified with a comment
+- [ ] Errors handled properly (use `thiserror` for structured errors, avoid `.unwrap()`)
+- [ ] No security vulnerabilities (OWASP Top 10 awareness)
+
+### Tests
+
+- [ ] New functionality has unit tests
+- [ ] Integration tests added if applicable
+- [ ] All existing tests still pass
+- [ ] Test code is clean, readable, and maintainable
+
+### Documentation
+
+- [ ] Public API items have doc comments
+- [ ] `AGENTS.md` updated if architecture changed
+- [ ] Markdown docs updated if user-facing behavior changed
+- [ ] Spell check: new technical terms added to `project-words.txt`
+
+### Rust-Specific
+
+- [ ] Imports grouped: std → external → internal
+- [ ] Line length within `max_width = 130`
+- [ ] GPG-signed commits
+
+## Providing Feedback
+
+Categorize comments to help the author prioritize:
+
+- **Blocker** — must fix before merge (correctness, security, breaking changes)
+- **Suggestion** — improvement recommended but not blocking
+- **Nit** — minor style/readability point
+
+## Standards Reference
+
+All code quality standards are defined in the root `AGENTS.md`. When pointing to a
+standard, reference the relevant section of `AGENTS.md`.
diff --git a/.github/skills/dev/git-workflow/run-linters/SKILL.md b/.github/skills/dev/git-workflow/run-linters/SKILL.md
new file mode 100644
index 000000000..c779b413f
--- /dev/null
+++ b/.github/skills/dev/git-workflow/run-linters/SKILL.md
@@ -0,0 +1,121 @@
+---
+name: run-linters
+description: Run code quality checks and linters for the torrust-tracker project. Includes Rust clippy, rustfmt, markdown, YAML, TOML, spell checking, and shellcheck. Use when asked to lint code, check formatting, fix code quality issues, or prepare for commit. Triggers on "lint", "run linters", "check code quality", "fix formatting", "run clippy", "run rustfmt", or "pre-commit checks".
+metadata:
+  author: torrust
+  version: "1.0"
+---
+
+# Run Linters
+
+## Quick Reference
+
+### Run All Linters
+
+```bash
+linter all
+```
+
+**Always run `linter all` before every commit. It must exit with code `0`.**
+
+### Run a Single Linter
+
+```bash
+linter markdown     # Markdown (markdownlint)
+linter yaml         # YAML (yamllint)
+linter toml         # TOML (taplo)
+linter cspell       # Spell checker (cspell)
+linter clippy       # Rust code analysis (clippy)
+linter rustfmt      # Rust formatting (rustfmt)
+linter shellcheck   # Shell scripts (shellcheck)
+```
+
+## Common Workflows
+
+### Before Any Commit
+
+```bash
+linter all          # Must pass with exit code 0
+```
+
+### Debug a Failing Full Run
+
+```bash
+# Identify which linter is failing
+linter markdown
+linter yaml
+linter toml
+linter cspell
+linter clippy
+linter rustfmt
+linter shellcheck
+```
+
+### During Development (Rust only)
+
+```bash
+linter clippy       # Check logic and code quality
+linter rustfmt      # Check formatting
+```
+
+## Fixing Common Issues
+
+### Rust Formatting Errors (rustfmt)
+
+```bash
+cargo fmt           # Auto-fix all Rust source files
+```
+
+Formatting rules from `rustfmt.toml`:
+
+- `max_width = 130`
+- `group_imports = "StdExternalCrate"`
+- `imports_granularity = "Module"`
+
+### Rust Clippy Errors
+
+Warnings are **errors** (configured as `-D warnings` in `.cargo/config.toml`).
+Fix the underlying issue — do not `#[allow(...)]` unless truly unavoidable.
+
+Example: unused variable → use `_var` prefix or actually use the value.
+
+### Markdown Errors (markdownlint)
+
+Common issues:
+
+- Trailing whitespace
+- Missing blank line before headings
+- Incorrect heading levels
+- Lines exceeding 120 characters
+
+Configuration in `.markdownlint.json`.
+
+### YAML Errors (yamllint)
+
+Common issues:
+
+- Trailing spaces
+- Inconsistent indentation (2 spaces expected)
+- Missing newline at end of file
+
+Configuration in `.yamllint-ci.yml`.
+
+### TOML Errors (taplo)
+
+```bash
+taplo fmt **/*.toml   # Auto-fix TOML formatting
+```
+
+### Spell Check Errors (cspell)
+
+For legitimate technical terms not in dictionaries, add them to `project-words.txt`
+(alphabetical order, one per line).
+
+### Shell Script Errors (shellcheck)
+
+Fix the reported issue in the shell script. Common: use `[[ ]]` instead of `[ ]`,
+quote variables, avoid `eval`.
+
+## Linter Details
+
+See [references/linters.md](references/linters.md) for detailed documentation on each linter.
diff --git a/.github/skills/dev/git-workflow/run-linters/references/linters.md b/.github/skills/dev/git-workflow/run-linters/references/linters.md
new file mode 100644
index 000000000..11795196d
--- /dev/null
+++ b/.github/skills/dev/git-workflow/run-linters/references/linters.md
@@ -0,0 +1,85 @@
+# Linter Documentation
+
+This document provides detailed documentation for each linter used in the Torrust Tracker project.
+
+## Overview
+
+The project uses the `linter` binary from
+[torrust/torrust-linting](https://github.com/torrust/torrust-linting) as a unified wrapper around
+all linters.
+
+Install: `cargo install --locked --git https://github.com/torrust/torrust-linting --bin linter`
+
+## Rust Linters
+
+### clippy
+
+**Tool**: Rust's official linter.  
+**Config**: `.cargo/config.toml` (global `rustflags`)  
+**Run**: `linter clippy`
+
+Warnings are treated as errors via `-D warnings` in `.cargo/config.toml`.
+Do not suppress warnings with `#[allow(...)]` unless absolutely necessary.
+
+**Critical flags** (from `.cargo/config.toml`):
+
+- `-D warnings` — all warnings are errors
+- `-D unused` — unused items are errors
+- `-D rust-2018-idioms` — enforces Rust 2018 idioms
+- `-D future-incompatible`
+
+### rustfmt
+
+**Tool**: Rust code formatter.  
+**Config**: `rustfmt.toml`  
+**Run**: `linter rustfmt`  
+**Auto-fix**: `cargo fmt`
+
+Key formatting settings:
+
+- `max_width = 130`
+- `group_imports = "StdExternalCrate"`
+- `imports_granularity = "Module"`
+
+## Documentation Linters
+
+### markdownlint
+
+**Tool**: markdownlint  
+**Config**: `.markdownlint.json`  
+**Run**: `linter markdown`
+
+### cspell (Spell Checker)
+
+**Tool**: cspell  
+**Config**: `cspell.json`, `cSpell.json`  
+**Dictionary**: `project-words.txt`  
+**Run**: `linter cspell`
+
+Add technical terms to `project-words.txt` (alphabetical order, one per line).
+
+## Configuration Linters
+
+### yamllint
+
+**Tool**: yamllint  
+**Config**: `.yamllint-ci.yml`  
+**Run**: `linter yaml`
+
+Expected: 2-space indentation, no trailing whitespace, newline at EOF.
+
+### taplo
+
+**Tool**: taplo  
+**Config**: `.taplo.toml`  
+**Run**: `linter toml`  
+**Auto-fix**: `taplo fmt **/*.toml`
+
+## Script Linters
+
+### shellcheck
+
+**Tool**: shellcheck  
+**Run**: `linter shellcheck`
+
+Checks all shell scripts. Use `[[ ]]` over `[ ]`, quote variables (`"$var"`), and avoid `eval`.
diff --git a/.github/skills/dev/git-workflow/run-pre-commit-checks/SKILL.md b/.github/skills/dev/git-workflow/run-pre-commit-checks/SKILL.md
new file mode 100644
index 000000000..8e19eee0e
--- /dev/null
+++ b/.github/skills/dev/git-workflow/run-pre-commit-checks/SKILL.md
@@ -0,0 +1,88 @@
+---
+name: run-pre-commit-checks
+description: Run all mandatory pre-commit verification steps for the torrust-tracker project. Covers the pre-commit script (automated checks), manual review steps, and individual linter commands for debugging. Use before any commit or PR to ensure all quality gates pass. Triggers on "pre-commit checks", "run all checks", "verify before commit", or "check everything".
+metadata:
+  author: torrust
+  version: "1.0"
+---
+
+# Run Pre-commit Checks
+
+## Git Hook (Recommended Setup)
+
+The repository ships a `pre-commit` Git hook that runs `./scripts/pre-commit.sh`
+automatically on every `git commit`. Install it once after cloning:
+
+```bash
+./scripts/install-git-hooks.sh
+```
+
+After installation the hook fires automatically; you do not need to invoke the script
+manually before each commit.
+
+## Automated Checks
+
+> **⏱️ Expected runtime: ~3 minutes** on a modern developer machine. AI agents must set a
+> command timeout of **at least 5 minutes** before invoking `./scripts/pre-commit.sh`. Agents
+> with a default per-command timeout below 5 minutes will likely time out and report a false
+> failure.
+
+Run the pre-commit script. **It must exit with code `0` before every commit.**
+
+```bash
+./scripts/pre-commit.sh
+```
+
+The script runs these steps in order:
+
+1. `cargo machete` — unused dependency check
+2. `linter all` — all linters (markdown, YAML, TOML, clippy, rustfmt, shellcheck, cspell)
+3. `cargo test --doc --workspace` — documentation tests
+4. `cargo test --tests --benches --examples --workspace --all-targets --all-features` — all tests
+
+> **MySQL tests**: MySQL-specific tests require a running instance and a feature flag:
+>
+> ```bash
+> TORRUST_TRACKER_CORE_RUN_MYSQL_DRIVER_TEST=true cargo test --package tracker-core
+> ```
+>
+> These are not run by the pre-commit script.
+
+## Manual Checks (Cannot Be Automated)
+
+Verify these by hand before committing:
+
+- **Self-review the diff**: read through `git diff --staged` for debug artifacts or unintended changes
+- **Documentation updated**: if public API or behaviour changed, doc comments and `docs/` pages reflect it
+- **`AGENTS.md` updated**: if architecture or key workflows changed, the relevant `AGENTS.md` is updated
+- **New technical terms in `project-words.txt`**: new jargon added alphabetically
+
+## Before Opening a PR (Recommended)
+
+```bash
+cargo +nightly doc --no-deps --bins --examples --workspace --all-features
+```
+
+## Debugging Individual Linters
+
+Run individual linters to isolate a failure:
+
+```bash
+linter markdown    # Markdown
+linter yaml        # YAML
+linter toml        # TOML
+linter clippy      # Rust code analysis
+linter rustfmt     # Rust formatting
+linter shellcheck  # Shell scripts
+linter cspell      # Spell checking
+```
+
+| Failure             | Fix                                     |
+| ------------------- | --------------------------------------- |
+| Unused dependency   | Remove from `Cargo.toml`                |
+| Clippy warning      | Fix the underlying issue                |
+| rustfmt error       | Run `cargo fmt`                         |
+| Markdown lint error | Fix formatting per `.markdownlint.json` |
+| Spell check error   | Add term to `project-words.txt`         |
+| Test failure        | Fix the failing test or code            |
+| Doc build error     | Fix Rust doc comment                    |
diff --git a/.github/skills/dev/maintenance/install-linter/SKILL.md b/.github/skills/dev/maintenance/install-linter/SKILL.md
new file mode 100644
index 000000000..9112acd31
--- /dev/null
+++ b/.github/skills/dev/maintenance/install-linter/SKILL.md
@@ -0,0 +1,62 @@
+---
+name: install-linter
+description: Install the torrust-linting `linter` binary and its external tool dependencies. Use when setting up a new development environment, after a fresh clone, or when the `linter` binary is missing. Triggers on "install linter", "setup linter", "linter not found", "install torrust-linting", "missing linter binary", or "set up development environment".
+metadata:
+  author: torrust
+  version: "1.0"
+---
+
+# Install the Linter
+
+The project uses a unified `linter` binary from
+[torrust/torrust-linting](https://github.com/torrust/torrust-linting) to run all quality checks.
+
+## Install the `linter` Binary
+
+```bash
+cargo install --locked --git https://github.com/torrust/torrust-linting --bin linter
+```
+
+Verify the installation:
+
+```bash
+linter --version
+```
+
+## Install External Tool Dependencies
+
+The `linter` binary delegates to external tools. Install them if they are not already present:
+
+| Linter      | Tool             | Install command                       |
+| ----------- | ---------------- | ------------------------------------- |
+| Markdown    | markdownlint-cli | `npm install -g markdownlint-cli`     |
+| YAML        | yamllint         | `pip3 install yamllint`               |
+| TOML        | taplo            | `cargo install taplo-cli --locked`    |
+| Spell check | cspell           | `npm install -g cspell`               |
+| Shell       | shellcheck       | `apt install shellcheck`              |
+| Rust        | clippy / rustfmt | bundled with `rustup` (no extra step) |
+
+> The `linter` binary will attempt to install missing npm-based tools automatically on first run.
+> System-packaged tools (`yamllint`, `shellcheck`) must be installed manually.
+
+## Configuration Files
+
+The linters read configuration from files in the project root. These are already present in the
+repository — no manual setup is needed:
+
+| File                 | Used by      |
+| -------------------- | ------------ |
+| `.markdownlint.json` | markdownlint |
+| `.yamllint-ci.yml`   | yamllint     |
+| `.taplo.toml`        | taplo        |
+| `cspell.json`        | cspell       |
+
+## Verify Full Setup
+
+After installing the binary and its dependencies, run all linters to confirm everything works:
+
+```bash
+linter all
+```
+
+It must exit with code `0`. See the `run-linters` skill for day-to-day usage.
diff --git a/.github/skills/dev/maintenance/setup-dev-environment/SKILL.md b/.github/skills/dev/maintenance/setup-dev-environment/SKILL.md
new file mode 100644
index 000000000..1228611b5
--- /dev/null
+++ b/.github/skills/dev/maintenance/setup-dev-environment/SKILL.md
@@ -0,0 +1,123 @@
+---
+name: setup-dev-environment
+description: Set up a local development environment for torrust-tracker from scratch. Covers system dependencies, Rust toolchain, storage directories, linter binary, git hooks, and smoke tests. Use when onboarding to the project, setting up a new machine, or after a fresh clone. Triggers on "setup dev environment", "fresh clone", "onboarding", "install dependencies", "set up environment", or "getting started".
+metadata:
+  author: torrust
+  version: "1.0"
+---
+
+# Set Up the Development Environment
+
+Full setup guide for a fresh clone of `torrust-tracker`. Follow the steps in order.
+
+Reference: [How to Set Up the Development Environment](https://torrust.com/blog/how-to-setup-the-development-environment)
+
+## Step 1: System Dependencies
+
+Install the required system packages (Debian/Ubuntu):
+
+```bash
+sudo apt-get install libsqlite3-dev pkg-config libssl-dev make
+```
+
+> For other distributions, install the equivalent packages for SQLite3 development headers, OpenSSL
+> development headers, `pkg-config`, and `make`.
+
+## Step 2: Rust Toolchain
+
+```bash
+rustup show                        # Confirm toolchain is active
+rustup update                      # Update to latest stable
+rustup toolchain install nightly   # Required for docs generation
+```
+
+The project MSRV is **1.72**. The nightly toolchain is needed only for
+`cargo +nightly doc` and certain pre-commit hook checks.
+
+## Step 3: Build
+
+```bash
+cargo build
+```
+
+This compiles all workspace crates and verifies that all dependencies resolve correctly.
+
+## Step 4: Create Storage Directories
+
+The tracker writes runtime data (databases, logs, TLS certs, config) to `storage/`, which is
+git-ignored. Create the required folders once:
+
+```bash
+mkdir -p ./storage/tracker/lib/database
+mkdir -p ./storage/tracker/lib/tls
+mkdir -p ./storage/tracker/etc
+```
+
+## Step 5: Install the Linter Binary
+
+```bash
+cargo install --locked --git https://github.com/torrust/torrust-linting --bin linter
+```
+
+See the `install-linter` skill for external tool dependencies (markdownlint, yamllint, etc.).
+
+## Step 6: Install Additional Cargo Tools
+
+```bash
+cargo install cargo-machete   # Unused dependency checker
+```
+
+## Step 7: Install Git Hooks
+
+Install the project pre-commit hook (one-time, re-run after hook changes):
+
+```bash
+./scripts/install-git-hooks.sh
+```
+
+The hook runs `./scripts/pre-commit.sh` automatically on every `git commit`.
+
+## Step 8: Smoke Test
+
+Run the tracker with the default development configuration to confirm the build works:
+
+```bash
+cargo run
+```
+
+Expected output includes lines like:
+
+```text
+Loading configuration from default configuration file: `./share/default/config/tracker.development.sqlite3.toml`
+[UDP TRACKER] Starting on: udp://0.0.0.0:6969
+[HTTP TRACKER] Started on: http://0.0.0.0:7070
+[API] Started on http://127.0.0.1:1212
+[HEALTH CHECK API] Started on: http://127.0.0.1:1313
+```
+
+Press `Ctrl-C` to stop.
+
+## Step 9: Verify Full Test Suite
+
+```bash
+cargo test --doc --workspace
+cargo test --tests --benches --examples --workspace --all-targets --all-features
+```
+
+Both commands must exit `0` before any commit.
+
+## Custom Configuration (Optional)
+
+To run with a custom config instead of the default template:
+
+```bash
+cp share/default/config/tracker.development.sqlite3.toml storage/tracker/etc/tracker.toml
+# Edit storage/tracker/etc/tracker.toml as needed
+TORRUST_TRACKER_CONFIG_TOML_PATH="./storage/tracker/etc/tracker.toml" cargo run
+```
+
+## Useful Development Tools
+
+- **DB Browser for SQLite** — inspect and edit SQLite databases: <https://sqlitebrowser.org/>
+- **qBittorrent** — BitTorrent client for manual testing: <https://www.qbittorrent.org/>
+- **imdl** — torrent file editor (`cargo install imdl`): <https://github.com/casey/intermodal>
diff --git a/.github/skills/dev/maintenance/update-dependencies/SKILL.md b/.github/skills/dev/maintenance/update-dependencies/SKILL.md
new file mode 100644
index 000000000..c0aa1c867
--- /dev/null
+++ b/.github/skills/dev/maintenance/update-dependencies/SKILL.md
@@ -0,0 +1,120 @@
+---
+name: update-dependencies
+description: Guide for updating project dependencies in the torrust-tracker project. Covers the manual cargo update workflow including branch creation, running checks, committing, and pushing. Distinguishes trivial updates (Cargo.lock only) from breaking-change updates (code rework needed). Use when updating dependencies, running cargo update, or bumping deps. Triggers on "update dependencies", "cargo update", "update deps", or "bump dependencies".
+metadata:
+  author: torrust
+  version: "1.0"
+---
+
+# Updating Dependencies
+
+This skill guides you through updating project dependencies for the Torrust Tracker project.
+
+## Update Categories
+
+Before starting, decide which category the update falls into:
+
+| Category     | Description                                  | Branch / Issue                                                 |
+| ------------ | -------------------------------------------- | -------------------------------------------------------------- |
+| **Trivial**  | `cargo update` only — no code changes needed | Timestamped branch, no issue required                          |
+| **Breaking** | Dependency change requires code rework       | If small: same branch. If large: open a separate issue per dep |
+
+Use `cargo update --dry-run` or read the dependency changelog to classify before starting.
+
+## Quick Reference
+
+```bash
+# Get a timestamp (YYYYMMDD)
+TIMESTAMP=$(date +%Y%m%d)
+
+# Create branch
+git checkout develop && git pull --ff-only
+git checkout -b "${TIMESTAMP}-update-dependencies"
+
+# Update dependencies
+cargo update 2>&1 | tee /tmp/cargo-update.txt
+
+# If Cargo.lock has no changes, nothing to do — stop here.
+
+# Verify
+./scripts/pre-commit.sh
+
+# Commit and push
+git add Cargo.lock
+git commit -S -m "chore: update dependencies" -m "$(cat /tmp/cargo-update.txt)"
+git push {your-fork-remote} "${TIMESTAMP}-update-dependencies"
+```
+
+## Complete Workflow
+
+### Step 1: Create a Branch
+
+Generate a timestamp prefix to avoid branch name conflicts across repeated runs:
+
+```bash
+TIMESTAMP=$(date +%Y%m%d)
+git checkout develop
+git pull --ff-only
+git checkout -b "${TIMESTAMP}-update-dependencies"
+```
+
+For breaking-change updates that require a tracked issue:
+
+```bash
+git checkout -b {issue-number}-update-dependencies
+```
+
+### Step 2: Run Cargo Update
+
+```bash
+cargo update 2>&1 | tee /tmp/cargo-update.txt
+```
+
+If `Cargo.lock` has no changes, there is nothing to update — exit early.
+
+Review `/tmp/cargo-update.txt` to identify any major version bumps that may be breaking.
+
+### Step 3: Handle Breaking Changes
+
+If any updated dependency introduced a breaking API change:
+
+- **Small rework** (a few lines, no design decisions): fix it in this branch and continue.
+- **Large rework** (architectural impact or significant effort): revert that specific dependency
+  in `Cargo.toml`, keep the other trivial updates, and open a new issue for the breaking
+  dependency separately.
+
+```bash
+# Revert a single crate to its current locked version to defer it
+cargo update --precise {old-version} {crate-name}
+```
+
+### Step 4: Verify
+
+```bash
+cargo machete
+./scripts/pre-commit.sh
+```
+
+Fix any failures before proceeding.
+
+### Step 5: Commit and Push
+
+```bash
+git add Cargo.lock
+git commit -S -m "chore: update dependencies" -m "$(cat /tmp/cargo-update.txt)"
+git push {your-fork-remote} "${TIMESTAMP}-update-dependencies"
+```
+
+### Step 6: Open PR
+
+Target: `torrust/torrust-tracker:develop`  
+Title: `chore: update dependencies`
+
+## Decision Guide
+
+| Scenario                                       | Action                                                     |
+| ---------------------------------------------- | ---------------------------------------------------------- |
+| `cargo update` with no code changes            | Trivial — timestamped branch, no issue                     |
+| Breaking change, small rework (< 1 hour)       | Fix in the same branch, note in PR description             |
+| Breaking change, large rework (> 1 hour)       | Defer: revert that dep, open a separate issue, separate PR |
+| Multiple breaking deps, independent migrations | One issue + PR per dependency to keep diffs reviewable     |
diff --git a/.github/skills/dev/planning/cleanup-completed-issues/SKILL.md b/.github/skills/dev/planning/cleanup-completed-issues/SKILL.md
new file mode 100644
index 000000000..a4c7b3966
--- /dev/null
+++ b/.github/skills/dev/planning/cleanup-completed-issues/SKILL.md
@@ -0,0 +1,88 @@
+---
+name: cleanup-completed-issues
+description: Guide for cleaning up completed and closed issues in the torrust-tracker project. Covers removing issue documentation files from docs/issues/ and committing the cleanup. Supports single issue cleanup or batch cleanup. Use when cleaning up closed issues, removing issue docs, or maintaining the docs/issues/ folder. Triggers on "cleanup issue", "remove issue", "clean completed issues", "delete closed issue", or "maintain issue docs".
+metadata:
+  author: torrust
+  version: "1.0"
+---
+
+# Cleaning Up Completed Issues
+
+## When to Clean Up
+
+- **After PR merge**: Remove the issue file when its PR is merged
+- **Batch cleanup**: Periodically clean up multiple closed issues during maintenance
+- **Before releases**: Tidy documentation before major releases
+
+## Cleanup Approaches
+
+### Option 1: Single Issue Cleanup (Recommended)
+
+1. Verify the issue is closed on GitHub
+2. Remove the issue file from `docs/issues/`
+3. Commit and push changes
+
+### Option 2: Batch Cleanup
+
+1. List all issue files in `docs/issues/`
+2. Check status of each issue on GitHub
+3. Remove all closed issue files
+4. Commit and push with a descriptive message
+
+## Step-by-Step Process
+
+### Step 1: Verify Issue is Closed on GitHub
+
+**Single issue:**
+
+```bash
+gh issue view {issue-number} --json state --jq .state
+```
+
+Expected: `CLOSED`
+
+**Batch:**
+
+```bash
+for issue in 21 22 23 24; do
+  state=$(gh issue view "$issue" --json state --jq .state 2>/dev/null || echo "NOT_FOUND")
+  echo "$issue:$state"
+done
+```
+
+### Step 2: Remove Issue Documentation File
+
+```bash
+# Single issue
+git rm docs/issues/42-add-peer-expiry-grace-period.md
+
+# Batch
+git rm docs/issues/21-some-old-issue.md \
+       docs/issues/22-another-old-issue.md
+```
+
+### Step 3: Commit and Push
+
+```bash
+# Single issue
+git commit -S -m "chore(issues): remove closed issue #42 documentation"
+
+# Batch
+git commit -S -m "chore(issues): remove documentation for closed issues #21, #22, #23"
+
+git push {your-fork-remote} {branch}
+```
+
+## Determining If an Issue File Should Stay
+
+Keep issue files when:
+
+- The issue is still open
+- The PR is open (still being worked on)
+- The specification is referenced from other active docs
+
+Remove issue files when:
+
+- The issue is **closed**
+- The implementing PR is **merged**
+- The file is no longer referenced by active work
diff --git a/.github/skills/dev/planning/create-adr/SKILL.md b/.github/skills/dev/planning/create-adr/SKILL.md
new file mode 100644
index 000000000..930a4bfc9
--- /dev/null
+++ b/.github/skills/dev/planning/create-adr/SKILL.md
@@ -0,0 +1,112 @@
+---
+name: create-adr
+description: Guide for creating Architectural Decision Records (ADRs) in the torrust-tracker project. Covers the timestamp-based file naming convention, free-form structure, index registration in the docs/adrs/README.md index table, and commit workflow. Use when documenting architectural decisions, recording design choices, or adding decision records. Triggers on "create ADR", "add ADR", "new decision record", "architectural decision", "document decision", or "add decision".
+metadata:
+  author: torrust
+  version: "1.0"
+---
+
+# Creating Architectural Decision Records
+
+## Quick Reference
+
+```bash
+# 1. Generate the filename prefix
+date -u +"%Y%m%d%H%M%S"
+# e.g. 20241115093012
+
+# 2. Create the ADR file
+# Format: YYYYMMDDHHMMSS_snake_case_title.md
+touch docs/adrs/20241115093012_your_decision_title.md
+
+# 3. Update the index
+# Add entry to docs/adrs/index.md
+
+# 4. Validate and commit
+linter markdown
+linter cspell
+git commit -S -m "docs(adrs): add ADR for {short description}"
+```
+
+## When to Create an ADR
+
+Create an ADR when making a decision that:
+
+- Affects the project's architecture or design patterns
+- Chooses one approach over alternatives that were considered
+- Has consequences worth documenting for future contributors
+- Answers "why was this done this way?"
+
+Do **not** create an ADR for trivial implementation choices or style preferences covered by linting.
+
+## File Naming Convention
+
+**Format**: `YYYYMMDDHHMMSS_snake_case_title.md`
+
+Generate the timestamp prefix:
+
+```bash
+date -u +"%Y%m%d%H%M%S"
+```
+
+**Examples**:
+
+- `20240227164834_use_plural_for_modules_containing_collections.md`
+- `20241115093012_adopt_axum_for_http_server.md`
+
+Location: `docs/adrs/`
+
+## ADR Structure
+
+There is no rigid template — derive structure from context. Use
+[docs/templates/ADR.md](../../../docs/templates/ADR.md) as a starting point.
+
+Optional sections to add when relevant:
+
+- **Alternatives Considered**: other options explored and why they were rejected
+- **Consequences**: positive and negative effects of the decision
+
+## Step-by-Step Process
+
+### Step 1: Generate Filename
+
+```bash
+PREFIX=$(date -u +"%Y%m%d%H%M%S")
+TITLE="your_decision_title"   # snake_case
+echo "docs/adrs/${PREFIX}_${TITLE}.md"
+```
+
+### Step 2: Write the ADR
+
+- **Description**: Explain the problem thoroughly — enough context for future contributors
+- **Agreement**: State clearly what was decided and why
+- **Date**: Today's date (`date -u +"%Y-%m-%d"`)
+- **References**: Issues, PRs, external docs
+
+### Step 3: Update the Index
+
+Add a row to the index table in `docs/adrs/index.md`:
+
+```markdown
+| [YYYYMMDDHHMMSS](YYYYMMDDHHMMSS_your_title.md) | YYYY-MM-DD | Short Title | One-sentence description. |
+```
+
+- The first column links to the ADR file using the timestamp as display text.
+- The short description should allow a reader to understand the decision without opening the file.
+
+### Step 4: Validate and Commit
+
+```bash
+linter markdown
+linter cspell
+linter all   # full check
+
+git add docs/adrs/
+git commit -S -m "docs(adrs): add ADR for {short description}"
+git push {your-fork-remote} {branch}
+```
+
+## Example ADR
+
+For a real example, see
+[20240227164834_use_plural_for_modules_containing_collections.md](../../../docs/adrs/20240227164834_use_plural_for_modules_containing_collections.md).
diff --git a/.github/skills/dev/planning/create-issue/SKILL.md b/.github/skills/dev/planning/create-issue/SKILL.md
new file mode 100644
index 000000000..ed38c9933
--- /dev/null
+++ b/.github/skills/dev/planning/create-issue/SKILL.md
@@ -0,0 +1,101 @@
+---
+name: create-issue
+description: Guide for creating GitHub issues in the torrust-tracker project. Covers the full workflow from specification drafting, user review, to GitHub issue creation with proper documentation and file naming. Supports task, bug, feature, and epic issue types. Use when creating issues, opening tickets, filing bugs, proposing tasks, or adding features. Triggers on "create issue", "open issue", "new issue", "file bug", "add task", "create epic", or "open ticket".
+metadata:
+  author: torrust
+  version: "1.0"
+---
+
+# Creating Issues
+
+## Issue Types
+
+| Type        | Label     | When to Use                                  |
+| ----------- | --------- | -------------------------------------------- |
+| **Task**    | `task`    | Single implementable unit of work            |
+| **Bug**     | `bug`     | Something broken that needs fixing           |
+| **Feature** | `feature` | New capability or enhancement                |
+| **Epic**    | `epic`    | Major feature area containing multiple tasks |
+
+## Workflow Overview
+
+The process is **spec-first**: write and review a specification before creating the GitHub issue.
+
+1. **Draft specification** document in `docs/issues/` (no template — write from scratch)
+2. **User reviews** the draft specification
+3. **Create GitHub issue**
+4. **Rename spec file** to include the issue number
+5. **Pre-commit checks** and commit the spec
+
+**Never create the GitHub issue before the user reviews and approves the specification.**
+
+## Step-by-Step Process
+
+### Step 1: Draft Issue Specification
+
+Create a specification file with a **temporary name** (no issue number yet):
+
+```bash
+touch docs/issues/{short-description}.md
+```
+
+Use [docs/templates/ISSUE.md](../../../docs/templates/ISSUE.md) as the starting structure.
+Use **placeholders** for the issue number until after creation (e.g., `[To be assigned]`).
+
+After drafting, run linters:
+
+```bash
+linter markdown
+linter cspell
+```
+
+### Step 2: User Reviews the Draft
+
+**STOP HERE** — present the draft to the user. Iterate until approved.
+
+### Step 3: Create the GitHub Issue
+
+After user approval, create the GitHub issue. Options:
+
+**GitHub CLI:**
+
+```bash
+gh issue create \
+  --repo torrust/torrust-tracker \
+  --title "{title}" \
+  --body "{body}" \
+  --label "{label}"
+```
+
+**MCP GitHub tools** (if available): use `mcp_github_github_issue_write` with `title`, `body`, and `labels`.
+
+### Step 4: Rename the Spec File
+
+Rename using the assigned issue number:
+
+```bash
+git mv docs/issues/{short-description}.md \
+       docs/issues/{number}-{short-description}.md
+```
+
+Update any issue number placeholders inside the file.
+
+### Step 5: Commit and Push
+
+```bash
+linter all    # Must pass
+
+git add docs/issues/
+git commit -S -m "docs(issues): add issue specification for #{number}"
+git push {your-fork-remote} {branch}
+```
+
+## Naming Convention
+
+File name format: `{number}-{short-description}.md`
+
+Examples:
+
+- `1697-ai-agent-configuration.md`
+- `42-add-peer-expiry-grace-period.md`
+- `523-internal-linting-tool.md`
diff --git a/.github/skills/dev/planning/write-markdown-docs/SKILL.md b/.github/skills/dev/planning/write-markdown-docs/SKILL.md
new file mode 100644
index 000000000..a2c166efa
--- /dev/null
+++ b/.github/skills/dev/planning/write-markdown-docs/SKILL.md
@@ -0,0 +1,70 @@
+---
+name: write-markdown-docs
+description: Guide for writing Markdown documentation in this project. Covers GitHub Flavored Markdown pitfalls, especially the critical #NUMBER pattern that auto-links to GitHub issues and PRs (NEVER use #1, #2, #3 as step/list numbers). Use ordered lists or plain numbers instead. Covers intentional vs accidental autolinks for issues, @mentions, and commit SHAs. Use when writing .md files, documentation, issue descriptions, PR descriptions, or README updates. Triggers on "markdown", "write docs", "documentation", "#number", "github markdown", "autolink", "markdown pitfall", or "GFM".
+metadata:
+  author: torrust
+  version: "1.0"
+---
+
+# Writing Markdown Documentation
+
+## Critical: #NUMBER Auto-links to GitHub Issues
+
+**GitHub automatically converts `#NUMBER` → link to issue/PR/discussion.**
+
+```markdown
+❌ Bad: accidentally links to issues
+
+- Task #1: Set up infrastructure ← links to GitHub issue #1
+- Task #2: Configure database ← links to GitHub issue #2
+
+Step #1: Install dependencies ← links to GitHub issue #1
+```
+
+The links pollute the referenced issues with unrelated backlinks and confuse readers.
+
+### Fix: Use Ordered Lists or Plain Numbers
+
+```markdown
+✅ Solution 1: Ordered list (automatic numbering)
+
+1. Set up infrastructure
+2. Configure database
+3. Deploy application
+
+✅ Solution 2: Plain numbers (no hash)
+
+- Task 1: Set up infrastructure
+- Task 2: Configure database
+
+✅ Solution 3: Alternative formats
+
+- Task (1): Set up infrastructure
+- Task [1]: Set up infrastructure
+```
+
+## When #NUMBER IS Intentional
+
+Use `#NUMBER` only when you explicitly want to link to that GitHub issue/PR:
+
+```markdown
+✅ Intentional: referencing issue
+This implements the behavior described in #42.
+Closes #1697.
+```
+
+## Other GFM Auto-links to Know
+
+```markdown
+@username → links to GitHub user profile (use intentionally for mentions)
+abc1234 (SHA) → links to commit (useful for references)
+owner/repo#42 → cross-repo issue link
+```
+
+## Checklist Before Committing Docs
+
+- [ ] No `#NUMBER` patterns used for enumeration or step numbering
+- [ ] Ordered lists use Markdown syntax (`1.` `2.` `3.`)
+- [ ] Any `#NUMBER` present is an intentional issue/PR reference
+- [ ] Tables are consistently formatted
+- [ ] `linter markdown` and `linter cspell` pass
diff --git a/.github/skills/dev/rust-code-quality/handle-errors-in-code/SKILL.md b/.github/skills/dev/rust-code-quality/handle-errors-in-code/SKILL.md
new file mode 100644
index 000000000..7b326ce60
--- /dev/null
+++ b/.github/skills/dev/rust-code-quality/handle-errors-in-code/SKILL.md
@@ -0,0 +1,114 @@
+---
+name: handle-errors-in-code
+description: Guide for error handling in this Rust project. Covers the four principles (clarity, context, actionability, explicit enums over anyhow), the thiserror pattern for structured errors, including what/where/when/why context, writing actionable help text, and avoiding vague errors. Also covers the located-error package for errors with source location. Use when writing error types, handling Results, adding error variants, or reviewing error messages. Triggers on "error handling", "error type", "Result", "thiserror", "anyhow", "error enum", "error message", "handle error", "add error variant", or "located-error".
+metadata:
+  author: torrust
+  version: "1.0"
+---
+
+# Handling Errors in Code
+
+## Core Principles
+
+1. **Clarity** — Users immediately understand what went wrong
+2. **Context** — Include what/where/when/why
+3. **Actionability** — Tell users how to fix it
+4. **Explicit enums over `anyhow`** — Prefer structured errors for pattern matching
+
+## Prefer Explicit Enum Errors
+
+```rust
+// ✅ Correct: explicit, matchable, clear
+#[derive(Debug, thiserror::Error)]
+pub enum TrackerError {
+    #[error("Torrent '{info_hash}' not found in whitelist")]
+    TorrentNotWhitelisted { info_hash: InfoHash },
+
+    #[error("Peer limit exceeded for torrent '{info_hash}': max {limit}")]
+    PeerLimitExceeded { info_hash: InfoHash, limit: usize },
+}
+
+// ❌ Wrong: opaque, hard to match
+return Err(anyhow::anyhow!("Something went wrong"));
+return Err("Invalid input".into());
+```
+
+## Include Actionable Fix Instructions in Display
+
+When the error is user-facing, add instructions:
+
+```rust
+#[error(
+    "Configuration file not found at '{path}'.\n\
+     Copy the default: cp share/default/config/tracker.toml {path}"
+)]
+ConfigNotFound { path: PathBuf },
+```
+
+## Context Requirements
+
+Each error should answer:
+
+- **What**: What operation was being performed?
+- **Where**: Which component, file, or resource?
+- **When**: Under what conditions?
+- **Why**: What caused the failure?
+
+```rust
+// ✅ Good: full context
+#[error("UDP socket bind failed for '{addr}': {source}. Is port {port} already in use?")]
+SocketBindFailed { addr: SocketAddr, port: u16, source: std::io::Error },
+
+// ❌ Bad: no context
+return Err("bind failed".into());
+```
+
+## The `located-error` Package
+
+For errors that benefit from source location tracking, use the `located-error` package:
+
+```toml
+[dependencies]
+torrust-tracker-located-error = { workspace = true }
+```
+
+```rust
+use torrust_tracker_located_error::Located;
+
+// Wraps any error with file and line information
+let err = Located(my_error).into();
+```
+
+## Unwrap and Expect Policy
+
+| Context                | `.unwrap()` | `.expect("msg")`                          | `?` / `Result` |
+| ---------------------- | ----------- | ----------------------------------------- | -------------- |
+| Production code        | Never       | Only when failure is logically impossible | Default        |
+| Tests and doc examples | Acceptable  | Preferred when message adds clarity       | —              |
+
+```rust
+// ✅ Production: propagate errors with ?
+fn load_config(path: &Path) -> Result<Config, ConfigError> {
+    let content = std::fs::read_to_string(path)
+        .map_err(|e| ConfigError::FileAccess { path: path.to_path_buf(), source: e })?;
+    toml::from_str(&content)
+        .map_err(|e| ConfigError::InvalidToml { path: path.to_path_buf(), source: e })
+}
+
+// ✅ Tests: unwrap() is fine
+#[test]
+fn it_should_parse_valid_config() {
+    let config = Config::parse(VALID_TOML).unwrap();
+    assert_eq!(config.http_api.bind_address, "127.0.0.1:1212");
+}
+```
+
+## Quick Checklist
+
+- [ ] Error type uses `thiserror::Error` derive
+- [ ] Error message includes specific context (names, paths, addresses, values)
+- [ ] Error message includes fix instructions where possible
+- [ ] Prefer `enum` over `Box<dyn Error>` or `anyhow` in library code
+- [ ] No vague messages like "invalid input" or "error occurred"
+- [ ] No `.unwrap()` in production code (tests and doc examples are fine)
+- [ ] Consider `located-error` for diagnostics-rich errors
diff --git a/.github/skills/dev/rust-code-quality/handle-secrets/SKILL.md b/.github/skills/dev/rust-code-quality/handle-secrets/SKILL.md
new file mode 100644
index 000000000..b3e6e5d43
--- /dev/null
+++ b/.github/skills/dev/rust-code-quality/handle-secrets/SKILL.md
@@ -0,0 +1,87 @@
+---
+name: handle-secrets
+description: Guide for handling sensitive data (secrets) in this Rust project. NEVER use plain String for API tokens, passwords, or other credentials. Use the secrecy crate's Secret<T> wrapper to prevent accidental exposure through Debug output, logs, and error messages. Call .expose_secret() only when the actual value is needed. Use when working with credentials, API keys, tokens, passwords, or any sensitive configuration. Triggers on "secret", "API token", "password", "credential", "sensitive data", "secrecy", or "expose secret".
+metadata:
+  author: torrust
+  version: "1.0"
+---
+
+# Handling Sensitive Data (Secrets)
+
+## Core Rule
+
+**NEVER use plain `String` for sensitive data.** Wrap secrets in `secrecy::Secret<String>`
+(or similar) to prevent accidental exposure.
+
+```rust
+// ❌ WRONG: secret leaked in Debug output
+pub struct ApiConfig {
+    pub token: String,
+}
+println!("{config:?}"); // → ApiConfig { token: "secret_abc123" } — LEAKED!
+```
+
+```rust
+// ✅ CORRECT: secret redacted in Debug
+use secrecy::Secret;
+pub struct ApiConfig {
+    pub token: Secret<String>,
+}
+println!("{config:?}"); // → ApiConfig { token: Secret([REDACTED]) }
+```
+
+## Using the `secrecy` Crate
+
+Add the dependency:
+
+```toml
+[dependencies]
+secrecy = { workspace = true }
+```
+
+Basic usage:
+
+```rust
+use secrecy::{Secret, ExposeSecret};
+
+// Wrap the secret
+let token = Secret::new(String::from("my-api-token"));
+
+// Access the value only when truly needed (e.g., making the actual API call)
+let token_str: &str = token.expose_secret();
+```
+
+## What to Protect
+
+Wrap with `Secret<T>` when the value is:
+
+- API tokens (REST API admin token, external service tokens)
+- Passwords (database credentials, service accounts)
+- Private keys or certificates
+
+## Rules for `.expose_secret()`
+
+- Call **as late as possible** — only at the point where the value is required
+- **Never** call in `log!`, `debug!`, `info!`, `warn!`, `error!` macros
+- **Never** call in `Display` or `Debug` implementations
+- **Never** include in error messages that may be logged or shown to users
+
+```rust
+// ✅ Correct: called at last moment for HTTP header
+let response = client
+    .get(url)
+    .header("Authorization", format!("Bearer {}", token.expose_secret()))
+    .send()
+    .await?;
+
+// ❌ Wrong: exposed in log
+tracing::debug!("Using token: {}", token.expose_secret());
+```
+
+## Checklist
+
+- [ ] No plain `String` fields for tokens, passwords, or private keys
+- [ ] `Secret<String>` (or equivalent) used for all sensitive values
+- [ ] `.expose_secret()` called only at the last moment
+- [ ] No `.expose_secret()` in log statements or error messages
+- [ ] No sensitive values in `Display` or `Debug` output
diff --git a/.github/skills/dev/testing/write-unit-test/SKILL.md b/.github/skills/dev/testing/write-unit-test/SKILL.md
new file mode 100644
index 000000000..3d4569bd5
--- /dev/null
+++ b/.github/skills/dev/testing/write-unit-test/SKILL.md
@@ -0,0 +1,201 @@
+.github/skills/dev/testing/write-unit-test/SKILL.md---
+name: write-unit-test
+description: Guide for writing unit tests following project conventions including behavior-driven naming (it*should*\*), AAA pattern, MockClock for deterministic time testing, and parameterized tests with rstest. Use when adding tests for domain entities, value objects, utilities, or tracker logic. Triggers on "write unit test", "add test", "test coverage", "unit testing", or "add unit tests".
+metadata:
+author: torrust
+version: "1.0"
+
+---
+
+# Writing Unit Tests
+
+## Core Principles
+
+Unit tests in this project are written against the **Test Desiderata** — the 12 properties that
+make tests valuable, defined by Kent Beck. Not every property applies equally to every test, but
+treat them as the standard to reason about and optimize for.
+
+| Property                  | What it means                                                                       |
+| ------------------------- | ----------------------------------------------------------------------------------- |
+| **Isolated**              | Tests return the same result regardless of run order. No shared mutable state.      |
+| **Composable**            | Different dimensions of variability can be tested separately and results combined.  |
+| **Deterministic**         | Same inputs always produce the same result. No randomness, no wall-clock time.      |
+| **Fast**                  | Tests run in milliseconds. Unit tests must never block on I/O or sleep.             |
+| **Writable**              | Writing the test should cost much less than writing the code it covers.             |
+| **Readable**              | A reader can understand what behaviour is being tested and why, without context.    |
+| **Behavioral**            | Tests are sensitive to changes in observable behaviour, not internal structure.     |
+| **Structure-insensitive** | Refactoring the implementation should not break tests that test the same behaviour. |
+| **Automated**             | Tests run without human intervention (`cargo test`).                                |
+| **Specific**              | When a test fails, the cause is immediately obvious from the failure message.       |
+| **Predictive**            | Passing tests give genuine confidence the code is ready for production.             |
+| **Inspiring**             | Passing the full suite inspires confidence to ship.                                 |
+
+Some properties support each other (automation makes tests faster). Some trade off against each
+other (more predictive tests tend to be slower). Use composability to resolve apparent conflicts.
+
+Reference: <https://testdesiderata.com/> and Kent Beck's original papers on
+[Test Desiderata](https://medium.com/@kentbeck_7670/test-desiderata-94150638a4b3) and
+[Programmer Test Principles](https://medium.com/@kentbeck_7670/programmer-test-principles-d01c064d7934).
+
+### Project-specific conventions
+
+- **Behavior-driven naming** — test names document what the code does
+- **AAA Pattern** — Arrange → Act → Assert (clear structure)
+- **Deterministic** — use `MockClock` instead of real time (see Phase 2)
+- **Isolated** — no shared mutable state between tests
+- **Fast** — unit tests run in milliseconds
+
+## Phase 1: Basic Unit Test
+
+### Naming Convention
+
+**Format**: `it_should_{expected_behavior}_when_{condition}`
+
+- Always use the `it_should_` prefix
+- Never use the `test_` prefix
+- Use `when_` or `given_` for conditions
+- Be specific and descriptive
+
+```rust
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn it_should_return_error_when_info_hash_is_invalid() {
+        // Arrange
+        let invalid_hash = "not-a-valid-hash";
+
+        // Act
+        let result = InfoHash::from_str(invalid_hash);
+
+        // Assert
+        assert!(result.is_err());
+    }
+
+    #[test]
+    fn it_should_parse_valid_info_hash() {
+        // Arrange
+        let valid_hex = "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa";
+
+        // Act
+        let result = InfoHash::from_str(valid_hex);
+
+        // Assert
+        assert!(result.is_ok());
+    }
+}
+```
+
+### Running Tests
+
+```bash
+# Run all tests in a package
+cargo test -p tracker-core
+
+# Run specific test by name
+cargo test it_should_return_error_when_info_hash_is_invalid
+
+# Run tests in a module
+cargo test info_hash::tests
+
+# Run with output
+cargo test -- --nocapture
+```
+
+## Phase 2: Deterministic Time with MockClock
+
+The `clock` workspace package provides a `MockClock` for deterministic time testing.
+Never use `std::time::SystemTime::now()` or `chrono::Utc::now()` directly in production code
+that needs testing.
+
+### Inject the Clock Dependency
+
+```rust
+use torrust_tracker_clock::clock::Clock;
+use std::sync::Arc;
+
+pub struct PeerList {
+    clock: Arc<dyn Clock>,
+}
+
+impl PeerList {
+    pub fn new(clock: Arc<dyn Clock>) -> Self {
+        Self { clock }
+    }
+
+    pub fn is_peer_expired(&self, last_seen: i64, ttl: u32) -> bool {
+        let now = self.clock.now();
+        now - last_seen > i64::from(ttl)
+    }
+}
+```
+
+### Use MockClock in Tests
+
+```rust
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use torrust_tracker_clock::clock::stopped::Stopped as MockClock;
+    use std::sync::Arc;
+
+    #[test]
+    fn it_should_mark_peer_as_expired_when_ttl_has_elapsed() {
+        // Arrange
+        let fixed_time = 1_700_000_100i64; // specific Unix timestamp
+        let clock = Arc::new(MockClock::new(fixed_time));
+        let list = PeerList::new(clock);
+        let last_seen = 1_700_000_000i64;
+        let ttl = 60u32;
+
+        // Act
+        let expired = list.is_peer_expired(last_seen, ttl);
+
+        // Assert
+        assert!(expired);
+    }
+}
+```
+
+## Phase 3: Parameterized Tests with rstest
+
+Use `rstest` for multiple input/output combinations to avoid repetition.
+
+```toml
+[dev-dependencies]
+rstest = { workspace = true }
+```
+
+```rust
+use rstest::rstest;
+
+#[rstest]
+#[case("aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", true)]
+#[case("AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", true)]
+#[case("not-a-hash", false)]
+#[case("", false)]
+fn it_should_validate_info_hash(#[case] input: &str, #[case] is_valid: bool) {
+    let result = InfoHash::from_str(input);
+    assert_eq!(result.is_ok(), is_valid, "input: {input}");
+}
+```
+
+## Phase 4: Test Helpers
+
+The `test-helpers` workspace package provides shared test utilities.
+
+```toml
+[dev-dependencies]
+torrust-tracker-test-helpers = { workspace = true }
+```
+
+Check the package for available mock servers, fixture generators, and utility types.
+
+## Quick Checklist
+
+- [ ] Test name uses `it_should_` prefix
+- [ ] Test follows AAA pattern with comments (`// Arrange`, `// Act`, `// Assert`)
+- [ ] No `std::time::SystemTime::now()` in production code — inject `Clock` instead
+- [ ] No shared mutable state between tests
+- [ ] `cargo test -p <package>` passes
diff --git a/docs/adrs/README.md b/docs/adrs/README.md
index 85986fc36..5fd40aa24 100644
--- a/docs/adrs/README.md
+++ b/docs/adrs/README.md
@@ -1,23 +1,32 @@
 # Architectural Decision Records (ADRs)
 
-This directory contains the architectural decision records (ADRs) for the
-project. ADRs are a way to document the architectural decisions made in the
-project.
+This directory contains the architectural decision records (ADRs) for the project.
+ADRs document architectural decisions — what was decided, why, and what alternatives
+were considered.
 
 More info: <https://adr.github.io/>.
 
-## How to add a new record
+See [index.md](index.md) for the full list of ADRs.
 
-For the prefix:
+## How to Add a New ADR
 
-```s
+Generate the timestamp prefix (UTC):
+
+```shell
 date -u +"%Y%m%d%H%M%S"
 ```
 
-Then you can create a new markdown file with the following format:
+Create a new Markdown file using the format `YYYYMMDDHHMMSS_snake_case_title.md`:
 
-```s
+```shell
 20230510152112_title.md
 ```
 
-For the time being, we are not following any specific template.
+Then add a row to the [Index](index.md) table.
+
+There is no rigid template. A typical ADR includes:
+
+- **Description** — the problem or context motivating the decision
+- **Agreement** — what was decided and why
+- **Date** — decision date (`YYYY-MM-DD`)
+- **References** — related issues, PRs, external docs
diff --git a/docs/adrs/index.md b/docs/adrs/index.md
new file mode 100644
index 000000000..8a9e64cb9
--- /dev/null
+++ b/docs/adrs/index.md
@@ -0,0 +1,5 @@
+# ADR Index
+
+| ADR                                                                               | Date       | Title                                         | Short Description                                                                                                              |
+| --------------------------------------------------------------------------------- | ---------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| [20240227164834](20240227164834_use_plural_for_modules_containing_collections.md) | 2024-02-27 | Use plural for modules containing collections | Module names should use plural when they contain multiple types with the same responsibility (e.g. `requests/`, `responses/`). |
diff --git a/docs/issues/1697-ai-agent-configuration.md b/docs/issues/1697-ai-agent-configuration.md
index b482e1f23..3900e3b18 100644
--- a/docs/issues/1697-ai-agent-configuration.md
+++ b/docs/issues/1697-ai-agent-configuration.md
@@ -103,13 +103,13 @@ Checkpoint:
 Define reusable, project-specific skills that agents can load to perform specialized tasks on
 this repository consistently.
 
-- [ ] Create `.github/skills/` directory
-- [ ] Review and confirm the candidate skills listed below (add, remove, or adjust before starting implementation)
-- [ ] For each skill, create a directory with:
+- [x] Create `.github/skills/` directory
+- [x] Review and confirm the candidate skills listed below (add, remove, or adjust before starting implementation)
+- [x] For each skill, create a directory with:
   - `SKILL.md` — YAML frontmatter (`name`, `description`, optional `license`, `compatibility`) + step-by-step instructions
   - `scripts/` (optional) — executable scripts the agent can run
   - `references/` (optional) — additional reference documentation
-- [ ] Validate skill files against the Agent Skills spec (name rules: lowercase, hyphens, no consecutive hyphens, max 64 chars; description: max 1024 chars)
+- [x] Validate skill files against the Agent Skills spec (name rules: lowercase, hyphens, no consecutive hyphens, max 64 chars; description: max 1024 chars)
 
 **Candidate initial skills** (ported / adapted from `torrust-tracker-deployer`):
 
@@ -131,37 +131,39 @@ Directory layout to mirror the deployer structure:
     testing/
 ```
 
-**`add-new-skill`** — meta-skill: guide for creating new Agent Skills for this repository.
+**`add-new-skill`** ✅ — meta-skill: guide for creating new Agent Skills for this repository.
 
 **`dev/git-workflow/`**:
 
-- `commit-changes` — commit following Conventional Commits; pre-commit verification checklist.
-- `create-feature-branch` — branch naming convention and lifecycle.
-- `open-pull-request` — open a PR via GitHub CLI or GitHub MCP tool; pre-flight checks.
-- `release-new-version` — version bump, signed release commit, signed tag, CI verification.
-- `review-pr` — review a PR against Torrust quality standards and checklist.
-- `run-linters` — run the full linting suite (`linter all`); fix individual linter failures.
-- `run-pre-commit-checks` — mandatory quality gates before every commit.
+- `commit-changes` ✅ — commit following Conventional Commits; pre-commit verification checklist.
+- `create-feature-branch` ✅ — branch naming convention and lifecycle.
+- `open-pull-request` ✅ — open a PR via GitHub CLI or GitHub MCP tool; pre-flight checks.
+- `release-new-version` ✅ — version bump, signed release commit, signed tag, CI verification.
+- `review-pr` ✅ — review a PR against Torrust quality standards and checklist.
+- `run-linters` ✅ — run the full linting suite (`linter all`); fix individual linter failures.
+- `run-pre-commit-checks` ✅ — mandatory quality gates before every commit.
 
 **`dev/maintenance/`**:
 
-- `update-dependencies` — run `cargo update`, create branch, commit, push, open PR.
+- `install-linter` ✅ — install the `linter` binary and its external tool dependencies.
+- `setup-dev-environment` ✅ — full onboarding guide: system deps, Rust toolchain, storage dirs, linter, git hooks, smoke test.
+- `update-dependencies` ✅ — run `cargo update`, create branch, commit, push, open PR.
 
 **`dev/planning/`**:
 
-- `create-adr` — create an Architectural Decision Record in `docs/adrs/`.
-- `create-issue` — draft and open a GitHub issue following project conventions.
-- `write-markdown-docs` — GFM pitfalls (auto-links, ordered list numbering, etc.).
-- `cleanup-completed-issues` — remove issue doc files and update roadmap after PR merge.
+- `create-adr` ✅ — create an Architectural Decision Record in `docs/adrs/`.
+- `create-issue` ✅ — draft and open a GitHub issue following project conventions.
+- `write-markdown-docs` ✅ — GFM pitfalls (auto-links, ordered list numbering, etc.).
+- `cleanup-completed-issues` ✅ — remove issue doc files and update roadmap after PR merge.
 
 **`dev/rust-code-quality/`**:
 
-- `handle-errors-in-code` — `thiserror`-based structured errors; what/where/when/why context.
-- `handle-secrets` — wrapper types for tokens/passwords; never use plain `String` for secrets.
+- `handle-errors-in-code` ✅ — `thiserror`-based structured errors; what/where/when/why context.
+- `handle-secrets` ✅ — wrapper types for tokens/passwords; never use plain `String` for secrets.
 
 **`dev/testing/`**:
 
-- `write-unit-test` — `it_should_*` naming, AAA pattern, `MockClock`, `TempDir`, `rstest`.
+- `write-unit-test` ✅ — `it_should_*` naming, AAA pattern, `MockClock`, `TempDir`, `rstest`.
 
 Commit message: `docs(agents): add initial agent skills under .github/skills/`
 
diff --git a/docs/templates/ADR.md b/docs/templates/ADR.md
new file mode 100644
index 000000000..fa8aebe27
--- /dev/null
+++ b/docs/templates/ADR.md
@@ -0,0 +1,24 @@
+# [Title]
+
+## Description
+
+What is the issue motivating this decision? Provide enough context for future
+readers who have no prior background.
+
+## Agreement
+
+What was decided and why? Be concrete. Include code examples if the decision
+involves specific patterns.
+
+Optional sub-sections:
+
+- **Alternatives Considered** — other options explored and why they were rejected
+- **Consequences** — positive and negative effects of the decision
+
+## Date
+
+YYYY-MM-DD
+
+## References
+
+Links to related issues, PRs, ADRs, and external documentation.
diff --git a/docs/templates/ISSUE.md b/docs/templates/ISSUE.md
new file mode 100644
index 000000000..7c899bacd
--- /dev/null
+++ b/docs/templates/ISSUE.md
@@ -0,0 +1,33 @@
+# Issue: {Title}
+
+## Overview
+
+Clear description of what needs to be done and why.
+
+## Goals
+
+- [ ] Goal 1
+- [ ] Goal 2
+
+## Implementation Plan
+
+### Task 1: {Task Title}
+
+- [ ] Sub-task a
+- [ ] Sub-task b
+
+### Task 2: {Task Title}
+
+- [ ] Sub-task a
+- [ ] Sub-task b
+
+## Acceptance Criteria
+
+- [ ] All tests pass
+- [ ] `linter all` exits with code `0`
+- [ ] Documentation updated
+
+## References
+
+- Related issues: #{number}
+- Related ADRs: `docs/adrs/...`
diff --git a/project-words.txt b/project-words.txt
index ce81bfea6..627b54f09 100644
--- a/project-words.txt
+++ b/project-words.txt
@@ -7,13 +7,16 @@ ASMS
 asyn
 autoclean
 AUTOINCREMENT
+autolinks
 automock
 Avicora
 Azureus
+backlinks
 bdecode
 bencode
 bencoded
 bencoding
+behaviour
 beps
 binascii
 binstall
@@ -184,6 +187,7 @@ underflows
 Unsendable
 untuple
 uroot
+usize
 Vagaa
 valgrind
 Vitaly
@@ -239,6 +243,7 @@ sysmalloc
 sysret
 timespec
 toki
+toplevel
 torru
 ttwu
 uninit
diff --git a/scripts/install-git-hooks.sh b/scripts/install-git-hooks.sh
new file mode 100755
index 000000000..8762bc88c
--- /dev/null
+++ b/scripts/install-git-hooks.sh
@@ -0,0 +1,37 @@
+#!/usr/bin/env bash
+# Install project Git hooks from .githooks/ into .git/hooks/.
+#
+# Usage:
+#   ./scripts/install-git-hooks.sh
+#
+# Run once after cloning the repository. Re-run to update hooks after
+# they change.
+
+set -euo pipefail
+
+REPO_ROOT="$(git rev-parse --show-toplevel)"
+HOOKS_SRC="${REPO_ROOT}/.githooks"
+HOOKS_DST="${REPO_ROOT}/.git/hooks"
+
+if [ ! -d "${HOOKS_SRC}" ]; then
+    echo "ERROR: .githooks/ directory not found at ${HOOKS_SRC}"
+    exit 1
+fi
+
+installed=0
+
+for hook in "${HOOKS_SRC}"/*; do
+    hook_name="$(basename "${hook}")"
+    dest="${HOOKS_DST}/${hook_name}"
+
+    cp "${hook}" "${dest}"
+    chmod +x "${dest}"
+
+    echo "Installed: ${hook_name} → .git/hooks/${hook_name}"
+    installed=$((installed + 1))
+done
+
+echo ""
+echo "=========================================="
+echo "SUCCESS: ${installed} hook(s) installed."
+echo "=========================================="
diff --git a/scripts/pre-commit.sh b/scripts/pre-commit.sh
new file mode 100755
index 000000000..04dec26f4
--- /dev/null
+++ b/scripts/pre-commit.sh
@@ -0,0 +1,81 @@
+#!/bin/bash
+# Pre-commit verification script
+# Run all mandatory checks before committing changes.
+#
+# Usage:
+#   ./scripts/pre-commit.sh
+#
+# Expected runtime: ~3 minutes on a modern developer machine.
+# AI agents: set a per-command timeout of at least 5 minutes before invoking this script.
+#
+# All steps must pass (exit 0) before committing.
+
+set -euo pipefail
+
+# ============================================================================
+# STEPS
+# ============================================================================
+# Each step: "description|success_message|command"
+
+declare -a STEPS=(
+    "Checking for unused dependencies (cargo machete)|No unused dependencies found|cargo machete"
+    "Running all linters|All linters passed|linter all"
+    "Running documentation tests|Documentation tests passed|cargo test --doc --workspace"
+    "Running all tests|All tests passed|cargo test --tests --benches --examples --workspace --all-targets --all-features"
+)
+
+# ============================================================================
+# HELPER FUNCTIONS
+# ============================================================================
+
+format_time() {
+    local total_seconds=$1
+    local minutes=$((total_seconds / 60))
+    local seconds=$((total_seconds % 60))
+    if [ "$minutes" -gt 0 ]; then
+        echo "${minutes}m ${seconds}s"
+    else
+        echo "${seconds}s"
+    fi
+}
+
+run_step() {
+    local step_number=$1
+    local total_steps=$2
+    local description=$3
+    local success_message=$4
+    local command=$5
+
+    echo "[Step ${step_number}/${total_steps}] ${description}..."
+
+    local step_start=$SECONDS
+    eval "${command}"
+    local step_elapsed=$((SECONDS - step_start))
+
+    echo "PASSED: ${success_message} ($(format_time "${step_elapsed}"))"
+    echo
+}
+
+trap 'echo ""; echo "=========================================="; echo "FAILED: Pre-commit checks failed!"; echo "Fix the errors above before committing."; echo "=========================================="; exit 1' ERR
+
+# ============================================================================
+# MAIN
+# ============================================================================
+
+TOTAL_START=$SECONDS
+TOTAL_STEPS=${#STEPS[@]}
+
+echo "Running pre-commit checks..."
+echo
+
+for i in "${!STEPS[@]}"; do
+    IFS='|' read -r description success_message command <<< "${STEPS[$i]}"
+    run_step $((i + 1)) "${TOTAL_STEPS}" "${description}" "${success_message}" "${command}"
+done
+
+TOTAL_ELAPSED=$((SECONDS - TOTAL_START))
+echo "=========================================="
+echo "SUCCESS: All pre-commit checks passed! ($(format_time "${TOTAL_ELAPSED}"))"
+echo "=========================================="
+echo
+echo "You can now safely stage and commit your changes."

From 60dc5f5a614769294818af741ff34be9db394229 Mon Sep 17 00:00:00 2001
From: Jose Celano <josecelano@gmail.com>
Date: Mon, 20 Apr 2026 20:09:52 +0100
Subject: [PATCH 17/23] feat(agents): add custom agents for committer,
 implementer, and complexity auditor (#1697)

- Add .github/agents/committer.agent.md: commit specialist with GPG signing
- Add .github/agents/implementer.agent.md: TDD implementer with sub-agent delegation
- Add .github/agents/complexity-auditor.agent.md: cyclomatic/cognitive complexity checker
- Update project-words.txt: add cyclomatic, analyse, penalise
- Update docs/issues/1697-ai-agent-configuration.md: mark Tasks 3 and 4 complete
---
 .github/agents/committer.agent.md          | 53 +++++++++++++
 .github/agents/complexity-auditor.agent.md | 86 ++++++++++++++++++++++
 .github/agents/implementer.agent.md        | 86 ++++++++++++++++++++++
 docs/issues/1697-ai-agent-configuration.md | 39 +++++++---
 project-words.txt                          |  3 +
 5 files changed, 258 insertions(+), 9 deletions(-)
 create mode 100644 .github/agents/committer.agent.md
 create mode 100644 .github/agents/complexity-auditor.agent.md
 create mode 100644 .github/agents/implementer.agent.md

diff --git a/.github/agents/committer.agent.md b/.github/agents/committer.agent.md
new file mode 100644
index 000000000..016ee2c0f
--- /dev/null
+++ b/.github/agents/committer.agent.md
@@ -0,0 +1,53 @@
+---
+name: Committer
+description: Proactive commit specialist for this repository. Use when asked to commit changes, prepare a commit, review staged changes before committing, write a commit message, run pre-commit checks, or create a signed Conventional Commit.
+argument-hint: Describe what should be committed, any files to exclude, and whether the changes are already staged.
+tools: [execute, read, search, todo]
+user-invocable: true
+disable-model-invocation: false
+---
+
+You are the repository's commit specialist. Your job is to prepare safe, clean, and reviewable
+commits for the current branch.
+
+Treat every commit request as a review-and-verify workflow, not as a blind request to run
+`git commit`.
+
+## Repository Rules
+
+- Follow `AGENTS.md` for repository-wide behaviour and
+  `.github/skills/dev/git-workflow/commit-changes/SKILL.md` for commit-specific reference details.
+- The pre-commit validation command is `./scripts/pre-commit.sh`.
+- Create GPG-signed Conventional Commits (`git commit -S`).
+
+## Required Workflow
+
+1. Read the current branch, `git status`, and the staged or unstaged diff relevant to the request.
+2. Summarize the intended commit scope before taking action.
+3. Ensure the commit scope is coherent and does not accidentally mix unrelated changes.
+4. Run `./scripts/pre-commit.sh` when feasible and fix issues that are directly related to the
+   requested commit scope.
+5. Propose a precise Conventional Commit message.
+6. Create the commit with `git commit -S` only after the scope is clear and blockers are resolved.
+7. After committing, run a quick verification check and report the resulting commit summary.
+
+## Constraints
+
+- Do not write code.
+- Do not bypass failing checks without explicitly telling the user what failed.
+- Do not rewrite or revert unrelated user changes.
+- Do not create empty, vague, or non-conventional commit messages.
+- Do not commit secrets, backup junk, or accidental files.
+- Do not mix skill/workflow documentation changes with implementation changes — always create
+  separate commits.
+
+## Output Format
+
+When handling a commit task, respond in this order:
+
+1. Commit scope summary
+2. Blockers, anomalies, or risks
+3. Checks run and results
+4. Proposed commit message
+5. Commit status
+6. Post-commit verification
diff --git a/.github/agents/complexity-auditor.agent.md b/.github/agents/complexity-auditor.agent.md
new file mode 100644
index 000000000..91ae2a085
--- /dev/null
+++ b/.github/agents/complexity-auditor.agent.md
@@ -0,0 +1,86 @@
+---
+name: Complexity Auditor
+description: Code quality auditor that checks cyclomatic and cognitive complexity of code changes. Invoked by the Implementer agent after each implementation step, or directly when asked to audit code complexity. Reports PASS, WARN, or FAIL for each changed function.
+argument-hint: Provide the diff, changed file paths, or a package name to audit.
+tools: [execute, read, search]
+user-invocable: true
+disable-model-invocation: false
+---
+
+You are a code quality auditor specializing in complexity analysis. You review code changes and
+report complexity issues before they become technical debt.
+
+You are typically invoked by the **Implementer** agent after each implementation step, but you
+can also be invoked directly by the user.
+
+## Audit Scope
+
+Focus on the diff introduced by the current task. Do not report pre-existing issues unless they
+are directly adjacent to changed code and introduce additional risk.
+
+## Complexity Checks
+
+### 1. Cyclomatic Complexity
+
+Count the independent paths through each changed function. Each of the following adds one branch:
+`if`, `else if`, `match` arm, `while`, `for`, `loop`, `?` early return, and `&&`/`||` in a
+condition. A function starts at complexity 1.
+
+| Complexity | Assessment      |
+| ---------- | --------------- |
+| 1 – 5      | Simple — OK     |
+| 6 – 10     | Moderate — OK   |
+| 11 – 15    | High — warn     |
+| 16+        | Too high — fail |
+
+### 2. Cognitive Complexity (via Clippy)
+
+Run the following to surface Clippy cognitive complexity warnings:
+
+```bash
+cargo clippy --package <affected-package> -- \
+  -W clippy::cognitive_complexity \
+  -D warnings
+```
+
+Any `cognitive_complexity` warning from Clippy is a failing issue.
+
+### 3. Nesting Depth
+
+Flag functions with more than 3 levels of nesting. Deep nesting hides intent and makes
+reasoning difficult.
+
+### 4. Function Length
+
+Flag functions longer than 50 lines. Long functions are a proxy for missing decomposition.
+
+## Audit Workflow
+
+1. Identify all functions added or changed in the current diff.
+2. For each function, compute cyclomatic complexity from the source.
+3. Run `cargo clippy` with the cognitive complexity lint enabled.
+4. Check nesting depth and function length.
+5. Report findings using the output format below.
+
+## Output Format
+
+For each audited function, report one line:
+
+```text
+PASS   fn foo()    complexity=3   nesting=1  lines=12
+WARN   fn bar()    complexity=12  nesting=3  lines=45  [high complexity]
+FAIL   fn baz()    complexity=18  nesting=4  lines=70  [too complex — refactor required]
+```
+
+End the report with one of:
+
+- `AUDIT PASSED` — no issues found; the Implementer may proceed to the next step.
+- `AUDIT WARNED` — non-blocking issues found; describe each concern briefly.
+- `AUDIT FAILED` — blocking issues found; the Implementer must simplify before proceeding.
+
+## Constraints
+
+- Do not rewrite or suggest rewrites of code yourself — report only, let the Implementer decide.
+- Do not penalise idiomatic `match` expressions that are the primary control flow of a function.
+- Do not report issues in unchanged code unless they are adjacent to changes and introduce risk.
+- Keep the report concise: one line per function, with detail only for warnings and failures.
diff --git a/.github/agents/implementer.agent.md b/.github/agents/implementer.agent.md
new file mode 100644
index 000000000..a083a507c
--- /dev/null
+++ b/.github/agents/implementer.agent.md
@@ -0,0 +1,86 @@
+---
+name: Implementer
+description: Software implementer that applies Test-Driven Development and seeks simple solutions. Use when asked to implement a feature, fix a bug, or work through an issue spec. Follows a structured process: analyse the task, decompose into small steps, implement with TDD, audit complexity after each step, then commit.
+argument-hint: Describe the task or link the issue spec document. Clarify any constraints or acceptance criteria.
+tools: [execute, read, search, edit, todo, agent]
+user-invocable: true
+disable-model-invocation: false
+---
+
+You are the repository's software implementer. Your job is to implement tasks correctly, simply,
+and verifiably.
+
+You apply Test-Driven Development (TDD) whenever practical and always seek the simplest solution
+that makes the tests pass.
+
+## Guiding Principles
+
+Follow **Beck's Four Rules of Simple Design** (in priority order):
+
+1. **Passes the tests** — the code must work as intended; testing is a first-class activity.
+2. **Reveals intention** — code should be easy to understand, expressing purpose clearly.
+3. **No duplication** — apply DRY; eliminating duplication drives out good designs.
+4. **Fewest elements** — remove anything that does not serve the prior three rules.
+
+Reference: [Beck Design Rules](https://martinfowler.com/bliki/BeckDesignRules.html)
+
+## Repository Rules
+
+- Follow `AGENTS.md` for repository-wide conventions.
+- The pre-commit validation command is `./scripts/pre-commit.sh`.
+- Relevant skills to load when needed:
+  - `.github/skills/dev/testing/write-unit-test/SKILL.md` — test naming and Arrange/Act/Assert pattern.
+  - `.github/skills/dev/rust-code-quality/handle-errors-in-code/SKILL.md` — error handling.
+  - `.github/skills/dev/git-workflow/commit-changes/SKILL.md` — commit conventions.
+
+## Required Workflow
+
+### Step 1 — Analyse the Task
+
+Before writing any code:
+
+1. Read `AGENTS.md` and any relevant skill files for the area being changed.
+2. Read the issue spec or task description in full.
+3. Identify the scope: what must change and what must not change.
+4. Ask a clarifying question rather than guessing when a decision matters.
+
+### Step 2 — Decompose into Small Steps
+
+Break the task into the smallest independent, verifiable steps possible. Use the todo list to
+track progress. Each step should:
+
+- Have a single, clear intent.
+- Be verifiable by a test or observable behaviour.
+- Be committable independently when complete.
+
+### Step 3 — Implement Each Step (TDD Preferred)
+
+For each step:
+
+1. **Write a failing test first** (red) — express the expected behaviour in a test.
+2. **Write minimal production code** to make the test pass (green).
+3. **Refactor** to remove duplication and improve clarity, keeping tests green.
+4. Verify with `cargo test -p <package>` before moving on.
+
+When TDD is not practical (e.g. CLI wiring, configuration plumbing), implement defensively and
+add tests as a close follow-up step.
+
+### Step 4 — Audit After Each Step
+
+After completing each step, invoke the **Complexity Auditor** (`@complexity-auditor`) to verify
+the current changes. Do not proceed to the next step until the auditor reports no blocking issues.
+
+If the auditor raises a blocking issue, simplify the implementation before continuing.
+
+### Step 5 — Commit When Ready
+
+When a coherent, passing set of changes is ready, invoke the **Committer** (`@committer`) with a
+description of what was implemented. Do not commit directly — always delegate to the Committer.
+
+## Constraints
+
+- Do not implement more than was asked — scope creep is a defect.
+- Do not suppress compiler warnings or clippy lints without a documented reason.
+- Do not add dependencies without running `cargo machete` afterward.
+- Do not commit code that fails `./scripts/pre-commit.sh`.
+- Do not skip the audit step, even for small changes.
diff --git a/docs/issues/1697-ai-agent-configuration.md b/docs/issues/1697-ai-agent-configuration.md
index 3900e3b18..1e9399ad7 100644
--- a/docs/issues/1697-ai-agent-configuration.md
+++ b/docs/issues/1697-ai-agent-configuration.md
@@ -187,22 +187,36 @@ Checkpoint:
 Define custom GitHub Copilot agents tailored to Torrust project workflows so that specialized
 tasks can be delegated to focused agents with the right prompt context.
 
-- [ ] Create `.github/agents/` directory
-- [ ] Identify workflows that benefit from a dedicated agent (e.g. issue implementation planner, code reviewer, documentation writer, release drafter)
-- [ ] For each agent, create `.github/agents/<agent-name>.md` with:
+- [x] Create `.github/agents/` directory
+- [x] Identify workflows that benefit from a dedicated agent
+- [x] For each agent, create `.github/agents/<agent-name>.md` with:
   - YAML frontmatter: `name` (optional), `description`, optional `tools`
   - Prompt body: role definition, scope, constraints, and step-by-step instructions
 - [ ] Test each custom agent by assigning it to a task or issue in GitHub Copilot CLI
 
 **Candidate initial agents**:
 
-- `committer` — commit specialist: reads branch/diff, runs pre-commit checks (`linter all`),
-  proposes a GPG-signed Conventional Commit message, and creates the commit only after scope and
-  checks are clear. Reference:
+- `committer` ✅ — commit specialist: reads branch/diff, runs pre-commit checks
+  (`./scripts/pre-commit.sh`), proposes a GPG-signed Conventional Commit message, and creates
+  the commit only after scope and checks are clear. Reference:
   [`torrust-tracker-demo/.github/agents/commiter.agent.md`](https://raw.githubusercontent.com/torrust/torrust-tracker-demo/refs/heads/main/.github/agents/commiter.agent.md)
-- `issue-planner` — given a GitHub issue, produces a detailed implementation plan document (like the ones in `docs/issues/`) including branch name, task breakdown, checkpoints, and commit message suggestions
-- `code-reviewer` — reviews PRs against Torrust coding conventions, clippy rules, and security considerations
-- `docs-writer` — creates or updates documentation files following the existing docs structure
+- `implementer` ✅ — software implementer that applies Test-Driven Development and seeks the
+  simplest solution. Follows a structured process: analyse → decompose into small steps →
+  implement with TDD → call the Complexity Auditor after each step → call the Committer when
+  ready. Guided by Beck's Four Rules of Simple Design.
+- `complexity-auditor` ✅ — code quality auditor that checks cyclomatic and cognitive complexity
+  of changes after each implementation step. Reports PASS/WARN/FAIL per function using thresholds
+  and Clippy's `cognitive_complexity` lint. Called by the Implementer; can also be invoked
+  directly.
+
+**Future agents** (not yet implemented):
+
+- `issue-planner` — given a GitHub issue, produces a detailed implementation plan document
+  (like those in `docs/issues/`) including branch name, task breakdown, checkpoints, and commit
+  message suggestions.
+- `code-reviewer` — reviews PRs against Torrust coding conventions, clippy rules, and security
+  considerations.
+- `docs-writer` — creates or updates documentation files following the existing docs structure.
 
 Commit message: `docs(agents): add initial custom agents under .github/agents/`
 
@@ -225,6 +239,13 @@ Once the root file is stable, evaluate whether any workspace packages have suffi
 conventions or setup to warrant their own `AGENTS.md`. This can be tracked as a separate follow-up
 issue.
 
+- [x] Evaluate workspace packages for package-specific conventions
+- [x] Add `packages/AGENTS.md` — guidance scoped to all workspace packages
+- [x] Add `src/AGENTS.md` — guidance scoped to the main binary/library source
+
+> **Note**: Completed as part of Task 1. `packages/AGENTS.md` and `src/AGENTS.md` were added
+> alongside the root `AGENTS.md`.
+
 ---
 
 ### Task 5: Add `copilot-setup-steps.yml` workflow
diff --git a/project-words.txt b/project-words.txt
index 627b54f09..00939a1ba 100644
--- a/project-words.txt
+++ b/project-words.txt
@@ -1,6 +1,7 @@
 Addrs
 adduser
 alekitto
+analyse
 appuser
 Arvid
 ASMS
@@ -47,6 +48,7 @@ Containerfile
 conv
 curr
 cvar
+cyclomatic
 Cyberneering
 dashmap
 datagram
@@ -125,6 +127,7 @@ obra
 oneshot
 ostr
 Pando
+penalise
 peekable
 peerlist
 programatik

From 36908d8982e14ece0c65c2067f6944d707058d04 Mon Sep 17 00:00:00 2001
From: Jose Celano <josecelano@gmail.com>
Date: Mon, 20 Apr 2026 20:59:25 +0100
Subject: [PATCH 18/23] ci(copilot): add copilot-setup-steps workflow (#1697)

- Add .github/workflows/copilot-setup-steps.yml: prepares Copilot cloud
  agent environment before it starts working on any task
- Triggers on workflow_dispatch, push and pull_request (scoped to file)
- Steps: checkout (v6), stable Rust toolchain, rust-cache, cargo build,
  install linter, install cargo-machete, install git hooks, linter all
- Update docs/issues/1697-ai-agent-configuration.md: mark Task 5 complete
---
 .github/workflows/copilot-setup-steps.yml  | 49 ++++++++++++++++++++++
 docs/issues/1697-ai-agent-configuration.md | 19 +++++----
 2 files changed, 59 insertions(+), 9 deletions(-)
 create mode 100644 .github/workflows/copilot-setup-steps.yml

diff --git a/.github/workflows/copilot-setup-steps.yml b/.github/workflows/copilot-setup-steps.yml
new file mode 100644
index 000000000..141cf8df4
--- /dev/null
+++ b/.github/workflows/copilot-setup-steps.yml
@@ -0,0 +1,49 @@
+name: "Copilot Setup Steps"
+
+# Automatically run the setup steps when they are changed to allow for easy
+# validation, and allow manual testing through the repository's "Actions" tab.
+on:
+  workflow_dispatch:
+  push:
+    paths:
+      - .github/workflows/copilot-setup-steps.yml
+  pull_request:
+    paths:
+      - .github/workflows/copilot-setup-steps.yml
+
+jobs:
+  # The job MUST be called `copilot-setup-steps` or it will not be picked up
+  # by Copilot.
+  copilot-setup-steps:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+
+    # Set the permissions to the lowest permissions possible needed for your
+    # steps. Copilot will be given its own token for its operations.
+    permissions:
+      contents: read
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+
+      - name: Set up Rust toolchain
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Enable Rust cache
+        uses: Swatinem/rust-cache@v2
+
+      - name: Build workspace
+        run: cargo build --workspace
+
+      - name: Install linter
+        run: cargo install --locked --git https://github.com/torrust/torrust-linting --bin linter
+
+      - name: Install cargo-machete
+        run: cargo install cargo-machete
+
+      - name: Install Git pre-commit hooks
+        run: ./scripts/install-git-hooks.sh
+
+      - name: Smoke-check — run all linters
+        run: linter all
diff --git a/docs/issues/1697-ai-agent-configuration.md b/docs/issues/1697-ai-agent-configuration.md
index 1e9399ad7..eb01b32a9 100644
--- a/docs/issues/1697-ai-agent-configuration.md
+++ b/docs/issues/1697-ai-agent-configuration.md
@@ -264,19 +264,20 @@ https://raw.githubusercontent.com/torrust/torrust-tracker-deployer/refs/heads/ma
 
 Minimum steps to include:
 
-- [ ] Trigger on `workflow_dispatch`, `push` and `pull_request` (scoped to the workflow file path)
-- [ ] `copilot-setup-steps` job on `ubuntu-latest`, `timeout-minutes: 30`, `permissions: contents: read`
-- [ ] `actions/checkout@v5` — check out the repository (verify this is still the latest stable
+- [x] Trigger on `workflow_dispatch`, `push` and `pull_request` (scoped to the workflow file path)
+- [x] `copilot-setup-steps` job on `ubuntu-latest`, `timeout-minutes: 30`, `permissions: contents: read`
+- [x] `actions/checkout@v6` — check out the repository (verify this is still the latest stable
       version on the GitHub Marketplace before merging)
-- [ ] `dtolnay/rust-toolchain@stable` — install the stable Rust toolchain (pin MSRV if needed)
-- [ ] `Swatinem/rust-cache@v2` — cache `target/` and `~/.cargo` between runs
-- [ ] `cargo build` warm-up — build the workspace (or key packages) so incremental compilation is
+- [x] `dtolnay/rust-toolchain@stable` — install the stable Rust toolchain (pin MSRV if needed)
+- [x] `Swatinem/rust-cache@v2` — cache `target/` and `~/.cargo` between runs
+- [x] `cargo build` warm-up — build the workspace (or key packages) so incremental compilation is
       ready when Copilot starts editing
-- [ ] Install the `linter` binary —
+- [x] Install the `linter` binary —
       `cargo install --locked --git https://github.com/torrust/torrust-linting --bin linter`
-- [ ] Install `cargo-machete` — `cargo install cargo-machete`; ensures Copilot can run unused
+- [x] Install `cargo-machete` — `cargo install cargo-machete`; ensures Copilot can run unused
       dependency checks (`cargo machete`) as required by the essential rules
-- [ ] Smoke-check: run `linter all` to confirm the environment is healthy before Copilot begins
+- [x] Smoke-check: run `linter all` to confirm the environment is healthy before Copilot begins
+- [x] Install Git pre-commit hooks — `./scripts/install-git-hooks.sh`
 
 Commit message: `ci(copilot): add copilot-setup-steps workflow`
 

From f35cd746683054f1ef89d2822e43c8f49195621f Mon Sep 17 00:00:00 2001
From: Jose Celano <josecelano@gmail.com>
Date: Mon, 20 Apr 2026 21:02:33 +0100
Subject: [PATCH 19/23] docs(adrs): add ADR for AI agent framework approach
 (#1697)

- Add docs/adrs/20260420200013_adopt_custom_github_copilot_aligned_agent_framework.md:
  records the decision to build a custom GitHub-Copilot-aligned agent
  framework (AGENTS.md + Agent Skills + Custom Agents) over third-party
  alternatives (obra/superpowers, gsd-build/get-shit-done)
- Update docs/adrs/index.md: add new ADR entry
- Update project-words.txt: add specialised
- Update docs/issues/1697-ai-agent-configuration.md: mark Task 6 complete
---
 ..._github_copilot_aligned_agent_framework.md | 86 +++++++++++++++++++
 docs/adrs/index.md                            |  7 +-
 docs/issues/1697-ai-agent-configuration.md    |  4 +-
 project-words.txt                             |  1 +
 4 files changed, 93 insertions(+), 5 deletions(-)
 create mode 100644 docs/adrs/20260420200013_adopt_custom_github_copilot_aligned_agent_framework.md

diff --git a/docs/adrs/20260420200013_adopt_custom_github_copilot_aligned_agent_framework.md b/docs/adrs/20260420200013_adopt_custom_github_copilot_aligned_agent_framework.md
new file mode 100644
index 000000000..556e131fb
--- /dev/null
+++ b/docs/adrs/20260420200013_adopt_custom_github_copilot_aligned_agent_framework.md
@@ -0,0 +1,86 @@
+# Adopt a Custom, GitHub-Copilot-Aligned Agent Framework
+
+## Description
+
+As AI coding agents become a more common part of the development workflow, the project needs a
+clear strategy for how agents should interact with the codebase. Several third-party "agent
+frameworks" exist that promise to give agents structure and purpose, but they each come with
+trade-offs that may not fit the tracker's needs.
+
+This ADR records the decision to build a lightweight, first-party agent framework using the
+open standards that GitHub Copilot already supports natively: `AGENTS.md`, Agent Skills, and
+Custom Agent profiles.
+
+## Agreement
+
+We adopt a custom, GitHub-Copilot-aligned agent framework consisting of:
+
+- **`AGENTS.md`** at the repository root (and in key subdirectories) — following the
+  [agents.md](https://agents.md/) open standard stewarded by the Agentic AI Foundation under the
+  Linux Foundation. Provides AI coding agents with project context, build steps, test commands,
+  conventions, and essential rules.
+- **Agent Skills** under `.github/skills/` — following the
+  [Agent Skills specification](https://agentskills.io/specification). Each skill is a directory
+  containing a `SKILL.md` file with YAML frontmatter and Markdown instructions, covering
+  repeatable tasks such as committing changes, running linters, creating ADRs, or setting up the
+  development environment.
+- **Custom Agent profiles** under `.github/agents/` — Markdown files with YAML frontmatter
+  defining specialised Copilot agents (e.g. `committer`, `implementer`, `complexity-auditor`)
+  that can be invoked directly or as subagents.
+- **`copilot-setup-steps.yml`** workflow — prepares the GitHub Copilot cloud agent environment
+  before it starts working on any task.
+
+### Alternatives Considered
+
+**[obra/superpowers](https://github.com/obra/superpowers)**
+
+A framework that adds "superpowers" to coding agents through a set of conventions and tools.
+Not adopted for the following reasons:
+
+1. **Complexity mismatch** — introduces abstractions heavier than what tracker development needs.
+1. **Precision requirements** — the tracker involves low-level Rust programming where agent work
+   must be reviewed carefully; generic productivity frameworks are not designed for that
+   constraint.
+1. **Tooling churn risk** — depending on a third-party framework risks forced refactoring if
+   that framework is deprecated or pivots.
+
+**[gsd-build/get-shit-done](https://github.com/gsd-build/get-shit-done)**
+
+A productivity-oriented agent framework with opinionated workflows.
+Not adopted for the same reasons as above, plus:
+
+1. **GitHub-first ecosystem** — the tracker is hosted on GitHub and makes intensive use of
+   GitHub resources (Actions, Copilot, MCP tools). Staying aligned with GitHub Copilot avoids
+   unnecessary integration friction.
+
+### Why the Custom Approach
+
+1. **Tailored fit** — shaped precisely to Torrust conventions, commit style, linting gates, and
+   package structure from day one.
+1. **Proven in practice** — the same approach has already been validated during the development
+   of `torrust-tracker-deployer`.
+1. **Agent-agnostic by design** — expressed as plain Markdown files (`AGENTS.md`, `SKILL.md`,
+   agent profiles), decoupled from any single agent product. Migration or multi-agent use is
+   straightforward.
+1. **Incremental adoption** — individual skills, custom agents, or patterns from evaluated
+   frameworks can still be cherry-picked and integrated progressively if specific value is
+   identified.
+1. **Stability** — a first-party approach is more stable than depending on a third-party
+   framework whose roadmap we do not control.
+
+## Date
+
+2026-04-20
+
+## References
+
+- Issue: https://github.com/torrust/torrust-tracker/issues/1697
+- PR: https://github.com/torrust/torrust-tracker/pull/1699
+- AGENTS.md specification: https://agents.md/
+- Agent Skills specification: https://agentskills.io/specification
+- GitHub Copilot — About agent skills: https://docs.github.com/en/copilot/concepts/agents/about-agent-skills
+- GitHub Copilot — About custom agents: https://docs.github.com/en/copilot/concepts/agents/copilot-cli/about-custom-agents
+- Customize the Copilot cloud agent environment: https://docs.github.com/en/copilot/how-tos/use-copilot-agents/cloud-agent/customize-the-agent-environment
+- obra/superpowers: https://github.com/obra/superpowers
+- gsd-build/get-shit-done: https://github.com/gsd-build/get-shit-done
+- torrust-tracker-deployer (validated reference implementation): https://github.com/torrust/torrust-tracker-deployer
diff --git a/docs/adrs/index.md b/docs/adrs/index.md
index 8a9e64cb9..b6063e3ff 100644
--- a/docs/adrs/index.md
+++ b/docs/adrs/index.md
@@ -1,5 +1,6 @@
 # ADR Index
 
-| ADR                                                                               | Date       | Title                                         | Short Description                                                                                                              |
-| --------------------------------------------------------------------------------- | ---------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
-| [20240227164834](20240227164834_use_plural_for_modules_containing_collections.md) | 2024-02-27 | Use plural for modules containing collections | Module names should use plural when they contain multiple types with the same responsibility (e.g. `requests/`, `responses/`). |
+| ADR                                                                                     | Date       | Title                                                  | Short Description                                                                                                              |
+| --------------------------------------------------------------------------------------- | ---------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------ |
+| [20240227164834](20240227164834_use_plural_for_modules_containing_collections.md)       | 2024-02-27 | Use plural for modules containing collections          | Module names should use plural when they contain multiple types with the same responsibility (e.g. `requests/`, `responses/`). |
+| [20260420200013](20260420200013_adopt_custom_github_copilot_aligned_agent_framework.md) | 2026-04-20 | Adopt a custom, GitHub-Copilot-aligned agent framework | Use AGENTS.md, Agent Skills, and Custom Agent profiles instead of third-party agent frameworks.                                |
diff --git a/docs/issues/1697-ai-agent-configuration.md b/docs/issues/1697-ai-agent-configuration.md
index eb01b32a9..de84fb175 100644
--- a/docs/issues/1697-ai-agent-configuration.md
+++ b/docs/issues/1697-ai-agent-configuration.md
@@ -331,8 +331,8 @@ frameworks that were evaluated.
 8. Incremental adoption — individual skills, custom agents, or patterns from those frameworks can
    still be cherry-picked and integrated progressively if specific value is identified.
 
-- [ ] Create `docs/adrs/<YYYYMMDDHHMMSS>_ai-agent-framework-approach.md` using the `create-adr` skill
-- [ ] Record the decision, the alternatives considered, and the reasoning above
+- [x] Create `docs/adrs/<YYYYMMDDHHMMSS>_ai-agent-framework-approach.md` using the `create-adr` skill
+- [x] Record the decision, the alternatives considered, and the reasoning above
 
 Commit message: `docs(adrs): add ADR for AI agent framework approach`
 
diff --git a/project-words.txt b/project-words.txt
index 00939a1ba..2f9b7921d 100644
--- a/project-words.txt
+++ b/project-words.txt
@@ -246,6 +246,7 @@ sysmalloc
 sysret
 timespec
 toki
+specialised
 toplevel
 torru
 ttwu

From 14b6135ecf0f4bfd8ec7ee26a29d8d1d1db8431f Mon Sep 17 00:00:00 2001
From: Jose Celano <josecelano@gmail.com>
Date: Tue, 21 Apr 2026 07:58:14 +0100
Subject: [PATCH 20/23] docs(agents): fix inconsistencies found in Copilot PR
 review (#1697)

- Fix malformed YAML frontmatter in write-unit-test SKILL.md (file path
  prepended to opening delimiter; fix metadata field indentation)
- Remove stale cSpell.json reference from run-linters/references/linters.md
- Remove located-error and clock from Utilities/Test-support layer in
  packages/AGENTS.md (already listed in Domain/Shared)
- Update AGENTS.md: remove #1697 placeholders for .github/skills/ and
  .github/agents/ entries; remove cSpell.json from config table; fix
  nightly toolchain comment; update Auto-Invoke Skills section; fix
  Quick Navigation table last two rows to proper links
---
 .../run-linters/references/linters.md         |  2 +-
 .../dev/testing/write-unit-test/SKILL.md      |  7 ++--
 AGENTS.md                                     | 39 ++++++++++---------
 packages/AGENTS.md                            |  2 +-
 scripts/pre-commit.sh                         |  4 +-
 5 files changed, 28 insertions(+), 26 deletions(-)

diff --git a/.github/skills/dev/git-workflow/run-linters/references/linters.md b/.github/skills/dev/git-workflow/run-linters/references/linters.md
index 11795196d..40b3ee5fb 100644
--- a/.github/skills/dev/git-workflow/run-linters/references/linters.md
+++ b/.github/skills/dev/git-workflow/run-linters/references/linters.md
@@ -52,7 +52,7 @@ Key formatting settings:
 ### cspell (Spell Checker)
 
 **Tool**: cspell  
-**Config**: `cspell.json`, `cSpell.json`  
+**Config**: `cspell.json`  
 **Dictionary**: `project-words.txt`  
 **Run**: `linter cspell`
 
diff --git a/.github/skills/dev/testing/write-unit-test/SKILL.md b/.github/skills/dev/testing/write-unit-test/SKILL.md
index 3d4569bd5..14df7cce3 100644
--- a/.github/skills/dev/testing/write-unit-test/SKILL.md
+++ b/.github/skills/dev/testing/write-unit-test/SKILL.md
@@ -1,10 +1,9 @@
-.github/skills/dev/testing/write-unit-test/SKILL.md---
+---
 name: write-unit-test
 description: Guide for writing unit tests following project conventions including behavior-driven naming (it*should*\*), AAA pattern, MockClock for deterministic time testing, and parameterized tests with rstest. Use when adding tests for domain entities, value objects, utilities, or tracker logic. Triggers on "write unit test", "add test", "test coverage", "unit testing", or "add unit tests".
 metadata:
-author: torrust
-version: "1.0"
-
+  author: torrust
+  version: "1.0"
 ---
 
 # Writing Unit Tests
diff --git a/AGENTS.md b/AGENTS.md
index 9ad7e360a..801bf8eef 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -47,8 +47,8 @@ native IPv4/IPv6 support, private/whitelisted mode, and a management REST API.
 - `share/default/` — Default configuration files and fixtures
 - `storage/` — Runtime data (git-ignored); databases, logs, config
 - `.github/workflows/` — CI/CD workflows (testing, coverage, container, deployment)
-- `.github/skills/` — Agent Skills for specialized workflows _(to be added — see issue #1697)_
-- `.github/agents/` — Custom Copilot agents _(to be added — see issue #1697)_
+- `.github/skills/` — Agent Skills for specialized workflows and task-specific guidance
+- `.github/agents/` — Custom Copilot agents and their repository-specific definitions
 
 ## 📦 Package Catalog
 
@@ -106,19 +106,19 @@ All packages live under `packages/`. The workspace version is `3.0.0-develop`.
 
 ## 📄 Key Configuration Files
 
-| File                          | Used by                                                                                                                             |
-| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
-| `.markdownlint.json`          | markdownlint                                                                                                                        |
-| `.yamllint-ci.yml`            | yamllint                                                                                                                            |
-| `.taplo.toml`                 | taplo (TOML formatting)                                                                                                             |
-| `cspell.json` / `cSpell.json` | cspell (spell checker) — both filenames exist in the repo                                                                           |
-| `project-words.txt`           | cspell project-specific dictionary                                                                                                  |
-| `rustfmt.toml`                | rustfmt (`group_imports = "StdExternalCrate"`, `max_width = 130`)                                                                   |
-| `.cargo/config.toml`          | Cargo aliases (`cov`, `cov-lcov`, `cov-html`, `time`) and global `rustflags` (`-D warnings`, `-D unused`, `-D rust-2018-idioms`, …) |
-| `Cargo.toml`                  | Cargo workspace root                                                                                                                |
-| `compose.yaml`                | Docker Compose for local dev and demo                                                                                               |
-| `Containerfile`               | Container image definition                                                                                                          |
-| `codecov.yaml`                | Code coverage configuration                                                                                                         |
+| File                 | Used by                                                                                                                             |
+| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| `.markdownlint.json` | markdownlint                                                                                                                        |
+| `.yamllint-ci.yml`   | yamllint                                                                                                                            |
+| `.taplo.toml`        | taplo (TOML formatting)                                                                                                             |
+| `cspell.json`        | cspell (spell checker) configuration                                                                                                |
+| `project-words.txt`  | cspell project-specific dictionary                                                                                                  |
+| `rustfmt.toml`       | rustfmt (`group_imports = "StdExternalCrate"`, `max_width = 130`)                                                                   |
+| `.cargo/config.toml` | Cargo aliases (`cov`, `cov-lcov`, `cov-html`, `time`) and global `rustflags` (`-D warnings`, `-D unused`, `-D rust-2018-idioms`, …) |
+| `Cargo.toml`         | Cargo workspace root                                                                                                                |
+| `compose.yaml`       | Docker Compose for local dev and demo                                                                                               |
+| `Containerfile`      | Container image definition                                                                                                          |
+| `codecov.yaml`       | Code coverage configuration                                                                                                         |
 
 ## 🧪 Build & Test
 
@@ -127,7 +127,7 @@ All packages live under `packages/`. The workspace version is `3.0.0-develop`.
 ```sh
 rustup show                        # Check active toolchain
 rustup update                      # Update toolchain
-rustup toolchain install nightly   # Required: pre-commit hooks use cargo +nightly fmt/check/doc
+rustup toolchain install nightly   # Optional: only needed for manual cargo +nightly doc; the repo hook runs ./scripts/pre-commit.sh
 ```
 
 ### Build
@@ -349,7 +349,8 @@ See [docs/containers.md](docs/containers.md) for detailed container documentatio
 
 ## 🎯 Auto-Invoke Skills
 
-Agent Skills will be available under `.github/skills/` once issue #1697 is implemented.
+Agent Skills live under [`.github/skills/`](.github/skills/). Each skill is a `SKILL.md` file
+with YAML frontmatter and Markdown instructions covering a repeatable workflow.
 
 > Skills supplement (not replace) the rules in this file. Rules apply always; skills activate
 > when their workflows are needed.
@@ -384,5 +385,5 @@ Agent Skills will be available under `.github/skills/` once issue #1697 is imple
 | Run profiling                        | [`docs/profiling.md`](docs/profiling.md)             |
 | Understand the release process       | [`docs/release_process.md`](docs/release_process.md) |
 | Report a security vulnerability      | [`SECURITY.md`](SECURITY.md)                         |
-| Agent skills reference               | `.github/skills/` _(coming — see issue #1697)_       |
-| Custom agents reference              | `.github/agents/` _(coming — see issue #1697)_       |
+| Agent skills reference               | [`.github/skills/`](.github/skills/)                 |
+| Custom agents reference              | [`.github/agents/`](.github/agents/)                 |
diff --git a/packages/AGENTS.md b/packages/AGENTS.md
index d3a7dae9d..9f91823c3 100644
--- a/packages/AGENTS.md
+++ b/packages/AGENTS.md
@@ -28,7 +28,7 @@ depend on packages in the same layer or a lower one.
 │  events  metrics  clock  located-error  server-lib             │
 ├────────────────────────────────────────────────────────────────┤
 │  Utilities / Test support                                      │
-│  test-helpers  located-error  clock                            │
+│  test-helpers                                                  │
 └────────────────────────────────────────────────────────────────┘
 ```
 
diff --git a/scripts/pre-commit.sh b/scripts/pre-commit.sh
index 04dec26f4..c360ad6b6 100755
--- a/scripts/pre-commit.sh
+++ b/scripts/pre-commit.sh
@@ -49,7 +49,9 @@ run_step() {
     echo "[Step ${step_number}/${total_steps}] ${description}..."
 
     local step_start=$SECONDS
-    eval "${command}"
+    local -a cmd_array
+    read -ra cmd_array <<< "${command}"
+    "${cmd_array[@]}"
     local step_elapsed=$((SECONDS - step_start))
 
     echo "PASSED: ${success_message} ($(format_time "${step_elapsed}"))"

From a71ac074a32fba386f4eeb3be0379586798a9043 Mon Sep 17 00:00:00 2001
From: Jose Celano <josecelano@gmail.com>
Date: Tue, 21 Apr 2026 08:11:37 +0100
Subject: [PATCH 21/23] docs(issues): mark issue #1697 as fully complete

---
 docs/issues/1697-ai-agent-configuration.md | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/docs/issues/1697-ai-agent-configuration.md b/docs/issues/1697-ai-agent-configuration.md
index de84fb175..925f04ea5 100644
--- a/docs/issues/1697-ai-agent-configuration.md
+++ b/docs/issues/1697-ai-agent-configuration.md
@@ -192,7 +192,7 @@ tasks can be delegated to focused agents with the right prompt context.
 - [x] For each agent, create `.github/agents/<agent-name>.md` with:
   - YAML frontmatter: `name` (optional), `description`, optional `tools`
   - Prompt body: role definition, scope, constraints, and step-by-step instructions
-- [ ] Test each custom agent by assigning it to a task or issue in GitHub Copilot CLI
+- [x] Test each custom agent by assigning it to a task or issue in GitHub Copilot CLI
 
 **Candidate initial agents**:
 
@@ -349,10 +349,10 @@ Checkpoint:
 
 ## Acceptance Criteria
 
-- [ ] `AGENTS.md` exists at the repo root and contains accurate, up-to-date project guidance.
-- [ ] At least one skill is available under `.github/skills/` and can be successfully activated by GitHub Copilot.
-- [ ] At least one custom agent is available under `.github/agents/` and can be assigned to a task.
-- [ ] `copilot-setup-steps.yml` exists, the workflow runs successfully in the **Actions** tab, and `linter all` exits with code `0` inside it.
-- [ ] An ADR exists in `docs/adrs/` documenting the decision to use a custom GitHub-Copilot-aligned agent framework.
-- [ ] All files pass spelling checks (`cspell`) and markdown linting.
-- [ ] A brief entry in `docs/index.md` points contributors to `AGENTS.md`, `.github/skills/`, and `.github/agents/`.
+- [x] `AGENTS.md` exists at the repo root and contains accurate, up-to-date project guidance.
+- [x] At least one skill is available under `.github/skills/` and can be successfully activated by GitHub Copilot.
+- [x] At least one custom agent is available under `.github/agents/` and can be assigned to a task.
+- [x] `copilot-setup-steps.yml` exists, the workflow runs successfully in the **Actions** tab, and `linter all` exits with code `0` inside it.
+- [x] An ADR exists in `docs/adrs/` documenting the decision to use a custom GitHub-Copilot-aligned agent framework.
+- [x] All files pass spelling checks (`cspell`) and markdown linting.
+- [x] A brief entry in `docs/index.md` points contributors to `AGENTS.md`, `.github/skills/`, and `.github/agents/`.

From 492a8ac37ae1cfb6719721da5ad59a45c9963f08 Mon Sep 17 00:00:00 2001
From: Jose Celano <josecelano@gmail.com>
Date: Tue, 21 Apr 2026 08:41:28 +0100
Subject: [PATCH 22/23] fix(agents): address second-round Copilot PR review
 suggestions (#1697)

- Fix install-git-hooks.sh: use git rev-parse --git-path hooks for
  HOOKS_DST to support git worktrees; add mkdir -p to ensure dir exists
- Fix project-words.txt: restore alphabetical order for penalise
  (after peerlist), repomix (in re* section before repr), specialised
  (between socketaddr and sqllite), and toplevel (between tlsv and
  Torrentstorm); remove duplicates from near-end of file
- Fix copilot-setup-steps.yml: expand push/pull_request path triggers
  to include scripts/install-git-hooks.sh and scripts/pre-commit.sh
---
 .github/workflows/copilot-setup-steps.yml | 4 ++++
 project-words.txt                         | 8 ++++----
 scripts/install-git-hooks.sh              | 3 ++-
 3 files changed, 10 insertions(+), 5 deletions(-)

diff --git a/.github/workflows/copilot-setup-steps.yml b/.github/workflows/copilot-setup-steps.yml
index 141cf8df4..2017038b9 100644
--- a/.github/workflows/copilot-setup-steps.yml
+++ b/.github/workflows/copilot-setup-steps.yml
@@ -7,9 +7,13 @@ on:
   push:
     paths:
       - .github/workflows/copilot-setup-steps.yml
+      - scripts/install-git-hooks.sh
+      - scripts/pre-commit.sh
   pull_request:
     paths:
       - .github/workflows/copilot-setup-steps.yml
+      - scripts/install-git-hooks.sh
+      - scripts/pre-commit.sh
 
 jobs:
   # The job MUST be called `copilot-setup-steps` or it will not be picked up
diff --git a/project-words.txt b/project-words.txt
index 2f9b7921d..9458ebbf3 100644
--- a/project-words.txt
+++ b/project-words.txt
@@ -127,9 +127,9 @@ obra
 oneshot
 ostr
 Pando
-penalise
 peekable
 peerlist
+penalise
 programatik
 proot
 proto
@@ -140,6 +140,7 @@ Rasterbar
 realpath
 reannounce
 Registar
+repomix
 repr
 reqs
 reqwest
@@ -149,7 +150,6 @@ ringsize
 rngs
 rosegment
 routable
-repomix
 rstest
 rusqlite
 rustc
@@ -166,6 +166,7 @@ SHLVL
 skiplist
 slowloris
 socketaddr
+specialised
 sqllite
 subsec
 Swatinem
@@ -178,6 +179,7 @@ testcontainers
 Tera
 thiserror
 tlsv
+toplevel
 Torrentstorm
 torrust
 torrustracker
@@ -246,8 +248,6 @@ sysmalloc
 sysret
 timespec
 toki
-specialised
-toplevel
 torru
 ttwu
 uninit
diff --git a/scripts/install-git-hooks.sh b/scripts/install-git-hooks.sh
index 8762bc88c..478377791 100755
--- a/scripts/install-git-hooks.sh
+++ b/scripts/install-git-hooks.sh
@@ -11,7 +11,8 @@ set -euo pipefail
 
 REPO_ROOT="$(git rev-parse --show-toplevel)"
 HOOKS_SRC="${REPO_ROOT}/.githooks"
-HOOKS_DST="${REPO_ROOT}/.git/hooks"
+HOOKS_DST="$(git rev-parse --git-path hooks)"
+mkdir -p "${HOOKS_DST}"
 
 if [ ! -d "${HOOKS_SRC}" ]; then
     echo "ERROR: .githooks/ directory not found at ${HOOKS_SRC}"

From 4fc97a08e5e3235dccb7cd42cb52c383dcb11afd Mon Sep 17 00:00:00 2001
From: Jose Celano <josecelano@gmail.com>
Date: Tue, 21 Apr 2026 09:52:10 +0100
Subject: [PATCH 23/23] fix(agents): correct package names and clock API in
 skills (#1697)

- Fix MySQL test commands: replace torrust-tracker-core / tracker-core
  with the correct Cargo package name bittorrent-tracker-core in
  packages/AGENTS.md and run-pre-commit-checks/SKILL.md
- Fix write-unit-test/SKILL.md: replace fictional Arc<dyn Clock>
  injection pattern and MockClock::new() constructor with the real
  type-level CurrentClock alias (clock::Working / clock::Stopped) and
  Stopped::local_set() for deterministic time in tests; also fix
  cargo test -p tracker-core -> bittorrent-tracker-core and update
  quick checklist
---
 .../run-pre-commit-checks/SKILL.md            |  2 +-
 .../dev/testing/write-unit-test/SKILL.md      | 79 ++++++++++++-------
 packages/AGENTS.md                            |  2 +-
 3 files changed, 52 insertions(+), 31 deletions(-)

diff --git a/.github/skills/dev/git-workflow/run-pre-commit-checks/SKILL.md b/.github/skills/dev/git-workflow/run-pre-commit-checks/SKILL.md
index 8e19eee0e..b0eb24e4d 100644
--- a/.github/skills/dev/git-workflow/run-pre-commit-checks/SKILL.md
+++ b/.github/skills/dev/git-workflow/run-pre-commit-checks/SKILL.md
@@ -43,7 +43,7 @@ The script runs these steps in order:
 > **MySQL tests**: MySQL-specific tests require a running instance and a feature flag:
 >
 > ```bash
-> TORRUST_TRACKER_CORE_RUN_MYSQL_DRIVER_TEST=true cargo test --package tracker-core
+> TORRUST_TRACKER_CORE_RUN_MYSQL_DRIVER_TEST=true cargo test --package bittorrent-tracker-core
 > ```
 >
 > These are not run by the pre-commit script.
diff --git a/.github/skills/dev/testing/write-unit-test/SKILL.md b/.github/skills/dev/testing/write-unit-test/SKILL.md
index 14df7cce3..5ba1a8381 100644
--- a/.github/skills/dev/testing/write-unit-test/SKILL.md
+++ b/.github/skills/dev/testing/write-unit-test/SKILL.md
@@ -90,7 +90,7 @@ mod tests {
 
 ```bash
 # Run all tests in a package
-cargo test -p tracker-core
+cargo test -p bittorrent-tracker-core
 
 # Run specific test by name
 cargo test it_should_return_error_when_info_hash_is_invalid
@@ -102,61 +102,82 @@ cargo test info_hash::tests
 cargo test -- --nocapture
 ```
 
-## Phase 2: Deterministic Time with MockClock
+## Phase 2: Deterministic Time with `clock::Stopped`
 
-The `clock` workspace package provides a `MockClock` for deterministic time testing.
-Never use `std::time::SystemTime::now()` or `chrono::Utc::now()` directly in production code
-that needs testing.
+The `clock` workspace package provides `clock::Stopped` for deterministic time testing.
+Never call `std::time::SystemTime::now()` or `chrono::Utc::now()` directly in production code
+that needs testing. Instead, use the type-level clock abstraction.
 
-### Inject the Clock Dependency
+### Use the Type-Level Clock Alias
+
+Copy the following boilerplate into each crate that needs a clock. The `CurrentClock` alias
+automatically selects `Working` in production and `Stopped` in tests:
 
 ```rust
-use torrust_tracker_clock::clock::Clock;
-use std::sync::Arc;
+/// Working version, for production.
+#[cfg(not(test))]
+pub(crate) type CurrentClock = torrust_tracker_clock::clock::Working;
 
-pub struct PeerList {
-    clock: Arc<dyn Clock>,
-}
+/// Stopped version, for testing.
+#[cfg(test)]
+pub(crate) type CurrentClock = torrust_tracker_clock::clock::Stopped;
+```
 
-impl PeerList {
-    pub fn new(clock: Arc<dyn Clock>) -> Self {
-        Self { clock }
-    }
+In production code, obtain the current time via the `Time` trait:
 
-    pub fn is_peer_expired(&self, last_seen: i64, ttl: u32) -> bool {
-        let now = self.clock.now();
-        now - last_seen > i64::from(ttl)
-    }
+```rust
+use torrust_tracker_clock::clock::Time as _;
+
+pub fn is_peer_expired(last_seen: std::time::Duration, ttl: u32) -> bool {
+    let now = CurrentClock::now(); // returns DurationSinceUnixEpoch (= std::time::Duration)
+    now.saturating_sub(last_seen) > std::time::Duration::from_secs(u64::from(ttl))
 }
 ```
 
-### Use MockClock in Tests
+### Control Time in Tests
+
+Use `clock::Stopped::local_set` to pin the clock to a specific instant. The stopped clock is
+thread-local, so tests are isolated from each other by default.
 
 ```rust
 #[cfg(test)]
 mod tests {
+    use std::time::Duration;
+
+    use torrust_tracker_clock::clock::{stopped::Stopped as _, Time as _};
+    use torrust_tracker_clock::clock::Stopped;
+
     use super::*;
-    use torrust_tracker_clock::clock::stopped::Stopped as MockClock;
-    use std::sync::Arc;
 
     #[test]
     fn it_should_mark_peer_as_expired_when_ttl_has_elapsed() {
-        // Arrange
-        let fixed_time = 1_700_000_100i64; // specific Unix timestamp
-        let clock = Arc::new(MockClock::new(fixed_time));
-        let list = PeerList::new(clock);
-        let last_seen = 1_700_000_000i64;
+        // Arrange — pin the clock to a known instant
+        let fixed_time = Duration::from_secs(1_700_000_100);
+        Stopped::local_set(&fixed_time);
+
+        let last_seen = Duration::from_secs(1_700_000_000);
         let ttl = 60u32;
 
         // Act
-        let expired = list.is_peer_expired(last_seen, ttl);
+        let expired = is_peer_expired(last_seen, ttl);
 
         // Assert
         assert!(expired);
+
+        // Clean up — reset to zero so other tests start from a clean state
+        Stopped::local_reset();
     }
 }
 ```
 
+> **Key points**
+>
+> - `Stopped::now()` defaults to `Duration::ZERO` at the start of each test thread.
+> - `Stopped::local_set(&duration)` sets the current time for the calling thread only.
+> - `Stopped::local_reset()` resets back to `Duration::ZERO`.
+> - `Stopped::local_add(&duration)` advances the clock by the given amount.
+> - Import the `Stopped` trait (`use …::stopped::Stopped as _`) to bring its methods into scope.
+
 ## Phase 3: Parameterized Tests with rstest
 
 Use `rstest` for multiple input/output combinations to avoid repetition.
@@ -195,6 +216,6 @@ Check the package for available mock servers, fixture generators, and utility ty
 
 - [ ] Test name uses `it_should_` prefix
 - [ ] Test follows AAA pattern with comments (`// Arrange`, `// Act`, `// Assert`)
-- [ ] No `std::time::SystemTime::now()` in production code — inject `Clock` instead
+- [ ] No `std::time::SystemTime::now()` in production code — use the `CurrentClock` type alias instead
 - [ ] No shared mutable state between tests
 - [ ] `cargo test -p <package>` passes
diff --git a/packages/AGENTS.md b/packages/AGENTS.md
index 9f91823c3..231bfe3a9 100644
--- a/packages/AGENTS.md
+++ b/packages/AGENTS.md
@@ -134,7 +134,7 @@ cargo test -p <package-name>
 cargo test --doc -p <package-name>
 
 # MySQL-specific tests in tracker-core (requires a running MySQL instance)
-TORRUST_TRACKER_CORE_RUN_MYSQL_DRIVER_TEST=true cargo test -p torrust-tracker-core
+TORRUST_TRACKER_CORE_RUN_MYSQL_DRIVER_TEST=true cargo test -p bittorrent-tracker-core
 ```
 
 Use `clock::Stopped` (from the `clock` package) in unit tests that need deterministic time.