@@ -77,23 +77,29 @@ web/
 ├── api/handlers/         JSON API: one file per topic, _register.php wires them
 ├── pages/                Page handlers (procedural .php, included by build())
 │   └── core/             header / navbar / title / footer chrome
-├── includes/             Library code (PSR-4 Sbpp\ at this prefix)
-│   ├── Database.php          PDO wrapper + :prefix_ table-name substitution
-│   ├── Config.php            DB-backed settings key/value cache
-│   ├── Log.php               Audit + error log (writes to sb_log)
-│   ├── Api.php / ApiError.php  JSON dispatcher + structured errors
-│   ├── CUserManager.php      Current admin + permission checks
-│   ├── AdminTabs.php         Render Pattern A admin sub-section nav (vertical sidebar via core/admin_sidebar.tpl, or back-link strip via core/admin_tabs.tpl when $tabs is empty)
-│   ├── page-builder.php      route() + build() (the page router)
-│   ├── system-functions.php  Legacy helpers shared across pages
-│   ├── SmartyCustomFunctions.php  {help_icon} / {csrf_field} / {load_template}
-│   ├── View/                 Typed Smarty view-model DTOs
-│   ├── Markup/               Admin-authored Markdown -> safe HTML (IntroRenderer)
-│   ├── auth/                 JWT cookie auth + Steam OpenID + login handlers
-│   ├── security/             CSRF + Crypto helpers
-│   ├── Mail/                 Symfony Mailer wrapper + email templates
+├── includes/             Library code (PSR-4 Sbpp\ at this prefix; #1290 phase B)
+│   ├── Db/Database.php       Sbpp\Db\Database — PDO wrapper + :prefix_ substitution
+│   ├── Config.php            Sbpp\Config — DB-backed settings key/value cache
+│   ├── Log.php               Sbpp\Log — audit + error log (writes to sb_log)
+│   ├── Api/Api.php           Sbpp\Api\Api — JSON dispatcher
+│   ├── Api/ApiError.php      Sbpp\Api\ApiError — structured API error
+│   ├── Auth/UserManager.php  Sbpp\Auth\UserManager (was CUserManager) — current admin + perms
+│   ├── Auth/Auth.php         Sbpp\Auth\Auth — login flow / cookie issue
+│   ├── Auth/JWT.php          Sbpp\Auth\JWT — token encode/decode
+│   ├── Auth/Host.php         Sbpp\Auth\Host — hostname helper
+│   ├── Auth/Handler/         Sbpp\Auth\Handler\{Normal,Steam}AuthHandler — login handlers
+│   ├── Auth/openid.php       LightOpenID — third-party, intentionally global ns
+│   ├── Security/CSRF.php     Sbpp\Security\CSRF — token helpers
+│   ├── Security/Crypto.php   Sbpp\Security\Crypto — password / token crypto
+│   ├── View/AdminTabs.php    Sbpp\View\AdminTabs — Pattern A admin sub-section nav
+│   ├── View/                 Sbpp\View\* — typed Smarty view-model DTOs
+│   ├── Markup/               Sbpp\Markup\IntroRenderer — admin Markdown -> safe HTML
+│   ├── Mail/                 Sbpp\Mail\{Mail,Mailer,EmailType} — Symfony Mailer wrapper + enum
 │   ├── SteamID/              SteamID parsing / vanity-URL resolution
-│   ├── PHPStan/              Custom PHPStan rules (Smarty + SQL prefix)
+│   ├── PHPStan/              Sbpp\PHPStan\* — custom PHPStan rules (Smarty + SQL prefix)
+│   ├── page-builder.php      route() + build() (the page router; procedural)
+│   ├── system-functions.php  Legacy helpers shared across pages (procedural)
+│   ├── SmartyCustomFunctions.php  {help_icon} / {csrf_field} / {load_template}
 │   └── vendor/               Composer artifacts (gitignored)
 ├── scripts/              Browser JS (// @ts-check + JSDoc, no bundler)
 │   ├── sb.js                 DOM helpers + sb namespace
@@ -137,8 +143,17 @@ Both scripts include `init.php` first, which performs identical bootstrap.
 2. Bails if `config.php` is missing or if the `install/` or `updater/`
    directories are present and the host isn't `localhost`.
 3. Loads Composer autoload (`includes/vendor/autoload.php`).
-4. Manually requires the auth + security + Database modules (they aren't
-   PSR-4 namespaced) and initialises them.
+4. Manually requires the auth + security + Database modules and
+   initialises them. The classes themselves ARE PSR-4 namespaced
+   (`Sbpp\Db\Database`, `Sbpp\Auth\UserManager`, `Sbpp\Security\CSRF`, …
+   — see `AGENTS.md` "Namespacing"), but the explicit `require_once`
+   chain stays in place so each file's `class_alias(\Sbpp\…\X::class,
+   'X')` runs eagerly. Without that, procedural call sites that say
+   `new Database()` would trigger an autoload lookup for global
+   `Database`, find nothing (the autoloader resolves the namespaced
+   name, not the alias), and die. The chain becomes optional only
+   after the follow-up #1290 PR burns every legacy global-name call
+   site.
 5. Resolves the panel version via `Sbpp\Version::resolve()` — three-tier
    fallback (release tarball's `configs/version.json` → `git describe`
    → the `'dev'` sentinel) and `define()`s `SB_VERSION` / `SB_GITREV`
@@ -158,8 +173,10 @@ Both scripts include `init.php` first, which performs identical bootstrap.
    them available.
 
 After `init.php` returns, callers may rely on these globals:
-`$GLOBALS['PDO']` (the `Database` wrapper), `$userbank` (`CUserManager`),
-`$theme` (`Smarty`), the permission constants, and `SB_VERSION`/`SB_GITREV`.
+`$GLOBALS['PDO']` (a `Sbpp\Db\Database` instance, also reachable as the
+`Database` alias), `$userbank` (`Sbpp\Auth\UserManager`, also `CUserManager`
+via alias), `$theme` (`Smarty`), the permission constants, and
+`SB_VERSION`/`SB_GITREV`.
 
 ### Page request lifecycle
 
@@ -260,21 +277,26 @@ drawer's admin-only Notes tab; `bans.player_history` and
 `comms.player_history` (live in their existing topic files) feed the
 drawer's History and Comms tabs.
 
-### Auth (`includes/auth/`)
+### Auth (`includes/Auth/` — `Sbpp\Auth\*`)
 
-- `Auth::login(aid, maxlife)` mints a JWT and stores it in the `sbpp_auth`
-  cookie (HttpOnly, SameSite=Lax). `Auth::verify()` returns the parsed
-  token (or `null`). `Auth::logout()` clears the cookie.
-- The token's only meaningful claim is `aid` (admin id). `CUserManager`
-  reads the row from `sb_admins` and exposes `is_logged_in()`,
-  `is_admin()`, `HasAccess(flags)`, and `GetProperty(name)`.
+- `Sbpp\Auth\Auth::login(aid, maxlife)` mints a JWT and stores it in
+  the `sbpp_auth` cookie (HttpOnly, SameSite=Lax). `Auth::verify()`
+  returns the parsed token (or `null`). `Auth::logout()` clears the
+  cookie.
+- The token's only meaningful claim is `aid` (admin id).
+  `Sbpp\Auth\UserManager` (legacy `CUserManager` alias) reads the row
+  from `sb_admins` and exposes `is_logged_in()`, `is_admin()`,
+  `HasAccess(flags)`, and `GetProperty(name)`.
 - Two login back-ends:
-  - `NormalAuthHandler` — username + bcrypt password, with attempt
-    counter and 10-minute lockout after 5 failures (#1081 hardening).
-  - `SteamAuthHandler` — OpenID via `includes/auth/openid.php` (legacy
-    LightOpenID).
-- `JWT::validate()` rejects expired or tampered tokens. `Auth::gc()`
-  garbage-collects `sb_login_tokens` rows older than 30 days.
+  - `Sbpp\Auth\Handler\NormalAuthHandler` — username + bcrypt password,
+    with attempt counter and 10-minute lockout after 5 failures (#1081
+    hardening).
+  - `Sbpp\Auth\Handler\SteamAuthHandler` — OpenID via the third-party
+    `includes/Auth/openid.php` (LightOpenID, intentionally kept in
+    the global namespace).
+- `Sbpp\Auth\JWT::validate()` rejects expired or tampered tokens.
+  `Auth::gc()` garbage-collects `sb_login_tokens` rows older than 30
+  days.
 
 ### Permissions
 
@@ -285,13 +307,14 @@ Two parallel permission systems:
   defined globally in `init.php` (`ADMIN_OWNER`, `ADMIN_ADD_BAN`, …).
   Mirrored to JS as `Perms.*` in the autogenerated `api-contract.js`.
 - **SourceMod flags** (`configs/permissions/sourcemod.json`) — character
-  string (e.g. `'mz'`). `CUserManager::HasAccess()` accepts either form;
-  `Api::register()` forwards whichever the registration declared.
+  string (e.g. `'mz'`). `Sbpp\Auth\UserManager::HasAccess()` accepts
+  either form; `Sbpp\Api\Api::register()` forwards whichever the
+  registration declared.
 
 `ADMIN_OWNER` (1<<24) is the implicit super-user bit; nearly every
 registration ORs it in. `ALL_WEB` is the union mask used for `is_admin()`.
 
-### CSRF (`includes/security/CSRF.php`)
+### CSRF (`includes/Security/CSRF.php` — `Sbpp\Security\CSRF`)
 
 - `CSRF::init()` (called from `init.php`) starts the session and lazily
   generates a 256-bit hex token bound to `$_SESSION['csrf_token']`.
@@ -302,7 +325,7 @@ registration ORs it in. `ALL_WEB` is the union mask used for `is_admin()`.
 - Page POST handlers call `CSRF::rejectIfInvalid()` (also invoked
   centrally by `route()`).
 
-### Database (`includes/Database.php`)
+### Database (`includes/Db/Database.php` — `Sbpp\Db\Database`)
 
 A thin PDO wrapper. Two things to know:
 
@@ -331,7 +354,7 @@ into `struc.sql`. The older `utf8` alias is a 3-byte subset and will
 reject supplementary-plane characters (emoji, some CJK), so do not
 downgrade the default.
 
-### Config (`includes/Config.php`)
+### Config (`includes/Config.php` — `Sbpp\Config`)
 
 - Settings live in `sb_settings` as a flat key/value table.
 - `Config::init($PDO)` loads them all into a static array on bootstrap.
@@ -766,7 +789,7 @@ sets `DBA_REQUIRE=1` so credential drift fails loudly.
 `phpstan.neon` with `phpVersion: 80500` so the analyser flags the
 PHP 8.1 null-into-scalar deprecation surface (`strlen($null)`,
 `trim($null)`, `substr($null, ...)`, `preg_match($null, ...)`, …)
-before it bites us on the PHP 9 bump. `web/includes/auth/openid.php`
+before it bites us on the PHP 9 bump. `web/includes/Auth/openid.php`
 is excluded from PHPStan, so the same surface there is gated by the
 runtime smoke test in `web/tests/integration/Php82DeprecationsTest.php`
 (per-process `set_error_handler` that promotes `E_DEPRECATED` to a
 
@@ -53,7 +53,11 @@
 
 include_once __DIR__ . '/init.php';
 require_once INCLUDES_PATH . '/system-functions.php';
-require_once INCLUDES_PATH . '/Api.php';
+// Api / ApiError are eagerly required by init.php (#1290 phase B) so the
+// `Api` / `ApiError` global aliases register before any procedural code
+// references them. The require_once below is a defensive no-op kept so
+// the file path stays self-documenting.
+require_once INCLUDES_PATH . '/Api/Api.php';
 
 Api::bootstrap();
 Api::dispatch();
@@ -11,6 +11,14 @@
 work.  If not, see <http://creativecommons.org/licenses/by-nc-sa/3.0/>.
 *************************************************************************/
 
+namespace Sbpp\Api;
+
+use LogType;
+use Sbpp\Auth\UserManager;
+use Sbpp\Log;
+use Sbpp\Security\CSRF;
+use Throwable;
+
 require_once __DIR__ . '/ApiError.php';
 
 /**
@@ -72,7 +80,7 @@ public static function bootstrap(): void
         if (self::$bootstrapped) {
             return;
         }
-        require_once __DIR__ . '/../api/handlers/_register.php';
+        require_once __DIR__ . '/../../api/handlers/_register.php';
         self::$bootstrapped = true;
     }
 
@@ -153,12 +161,12 @@ private static function logHackingAttempt(string $action, string $why): void
         if (!class_exists('Log', false)) {
             return;
         }
-        $who = ($userbank instanceof CUserManager && $userbank->is_logged_in())
+        $who = ($userbank instanceof UserManager && $userbank->is_logged_in())
             ? (string)$userbank->GetProperty('user')
             : ($_SERVER['REMOTE_ADDR'] ?? 'anonymous');
         try {
             Log::add(LogType::Warning, 'Hacking Attempt', "$who tried to call $action ($why).");
-        } catch (\Throwable $e) {
+        } catch (Throwable $e) {
             // Logging must never block the auth response.
         }
     }
@@ -251,7 +259,7 @@ public static function handle(string $method, string $rawBody, string $headerTok
                 $err['field'] = $e->field;
             }
             return [$e->httpStatus, ['ok' => false, 'error' => $err]];
-        } catch (\Throwable $e) {
+        } catch (Throwable $e) {
             $msg = (defined('DEBUG_MODE') && DEBUG_MODE)
                 ? $e->getMessage() . ' @ ' . $e->getFile() . ':' . $e->getLine()
                 : 'An unexpected error occurred. See server logs for details.';
@@ -260,3 +268,10 @@ public static function handle(string $method, string $rawBody, string $headerTok
         }
     }
 }
+
+// Issue #1290 phase B: legacy global-name shim. The api/handlers/*.php
+// files still call `Api::register(...)`, `Api::actions(...)`,
+// `Api::invoke(...)`, `Api::dispatch()`, etc. — same for the test
+// harness in web/tests/api/. The alias keeps every site working until
+// the call-site sweep PR.
+class_alias(\Sbpp\Api\Api::class, 'Api');
@@ -11,6 +11,10 @@
 work.  If not, see <http://creativecommons.org/licenses/by-nc-sa/3.0/>.
 *************************************************************************/
 
+namespace Sbpp\Api;
+
+use RuntimeException;
+
 /**
  * Throwable raised by API handlers to short-circuit dispatch with a
  * structured error envelope. The dispatcher serialises any ApiError as
@@ -20,7 +24,7 @@
  * Optional $field carries a form-field id so the client can scope the
  * error to a specific input (matching legacy xajax addAssign("field.msg")).
  */
-final class ApiError extends \RuntimeException
+final class ApiError extends RuntimeException
 {
     public function __construct(
         public readonly string $errorCode,
@@ -31,3 +35,8 @@ public function __construct(
         parent::__construct($message);
     }
 }
+
+// Issue #1290 phase B: legacy global-name shim. The api/handlers/*.php
+// files still throw `new ApiError(...)`; this alias keeps them working
+// until the call-site sweep PR.
+class_alias(\Sbpp\Api\ApiError::class, 'ApiError');
@@ -1,6 +1,11 @@
 <?php
 
+namespace Sbpp\Auth;
+
 use Lcobucci\JWT\Token;
+use PDO;
+use Sbpp\Db\Database;
+use Sbpp\Security\Crypto;
 
 /**
  * Class Auth
@@ -9,7 +14,7 @@ final class Auth
 {
     private static ?Database $dbs = null;
 
-    public static function init(\Database $dbs): void
+    public static function init(Database $dbs): void
     {
         self::$dbs = $dbs;
     }
@@ -140,3 +145,7 @@ private static function getJWTFromCookie(): string
         return is_string($_COOKIE['sbpp_auth'] ?? null) ? $_COOKIE['sbpp_auth'] : '';
     }
 }
+
+// Issue #1290 phase B: legacy global-name shim. Procedural code keeps
+// using `\Auth` until the call-site sweep PR.
+class_alias(\Sbpp\Auth\Auth::class, 'Auth');
@@ -1,5 +1,11 @@
 <?php
 
+namespace Sbpp\Auth\Handler;
+
+use Sbpp\Auth\Auth;
+use Sbpp\Config;
+use Sbpp\Db\Database;
+
 final class NormalAuthHandler
 {
     private bool $result = false;
@@ -63,3 +69,7 @@ private function getInfosFromDatabase(string $username): mixed
         return $this->dbs->single();
     }
 }
+
+// Issue #1290 phase B: legacy global-name shim. Procedural code keeps
+// using `\NormalAuthHandler` until the call-site sweep PR.
+class_alias(\Sbpp\Auth\Handler\NormalAuthHandler::class, 'NormalAuthHandler');
@@ -1,10 +1,18 @@
 <?php
 
+namespace Sbpp\Auth\Handler;
+
+use LightOpenID;
+use Sbpp\Auth\Auth;
+use Sbpp\Auth\Host;
+use Sbpp\Config;
+use Sbpp\Db\Database;
+
 final class SteamAuthHandler
 {
     public function __construct(
-        private \LightOpenID $openid,
-        private \Database $dbs
+        private LightOpenID $openid,
+        private Database $dbs
     ) {
         if ($this->openid->validate()) {
             $steamid = $this->validate();
@@ -56,3 +64,7 @@ private function check(string $steamid): void
         header("Location: ".Host::complete()."/index.php?p=login&m=steam_failed");
     }
 }
+
+// Issue #1290 phase B: legacy global-name shim. Procedural code keeps
+// using `\SteamAuthHandler` until the call-site sweep PR.
+class_alias(\Sbpp\Auth\Handler\SteamAuthHandler::class, 'SteamAuthHandler');
@@ -1,5 +1,7 @@
 <?php
 
+namespace Sbpp\Auth;
+
 /**
  * Class Host
  */
@@ -56,3 +58,7 @@ public static function complete(bool $withoutRequest = false): string
         return self::protocol().self::domain() . ($withoutRequest ? '' : "/$request");
     }
 }
+
+// Issue #1290 phase B: legacy global-name shim. Procedural code keeps
+// using `\Host` until the call-site sweep PR.
+class_alias(\Sbpp\Auth\Host::class, 'Host');
@@ -1,5 +1,8 @@
 <?php
 
+namespace Sbpp\Auth;
+
+use DateTimeImmutable;
 use Lcobucci\JWT\Builder;
 use Lcobucci\JWT\Configuration;
 use Lcobucci\JWT\Signer\Hmac\Sha256;
@@ -56,3 +59,7 @@ private static function getConfig(): Configuration
         return Configuration::forSymmetricSigner(new Sha256(), InMemory::base64Encoded(SB_SECRET_KEY));
     }
 }
+
+// Issue #1290 phase B: legacy global-name shim. Procedural code keeps
+// using `\JWT` until the call-site sweep PR.
+class_alias(\Sbpp\Auth\JWT::class, 'JWT');
Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,11 @@`
`1`	`1`	`<?php`
`2`	`2`
	`3`	`+namespace Sbpp\Auth;`
	`4`	`+`
`3`	`5`	`use Lcobucci\JWT\Token;`
	`6`	`+use PDO;`
	`7`	`+use Sbpp\Db\Database;`
	`8`	`+use Sbpp\Security\Crypto;`
`4`	`9`
`5`	`10`	`/**`
`6`	`11`	`* Class Auth`
`@@ -9,7 +14,7 @@ final class Auth`
`9`	`14`	`{`
`10`	`15`	`private static ?Database $dbs = null;`
`11`	`16`
`12`		`- public static function init(\Database $dbs): void`
	`17`	`+ public static function init(Database $dbs): void`
`13`	`18`	`{`
`14`	`19`	`self::$dbs = $dbs;`
`15`	`20`	`}`
`@@ -140,3 +145,7 @@ private static function getJWTFromCookie(): string`
`140`	`145`	`return is_string($_COOKIE['sbpp_auth'] ?? null) ? $_COOKIE['sbpp_auth'] : '';`
`141`	`146`	`}`
`142`	`147`	`}`
	`148`	`+`
	`149`	`+// Issue #1290 phase B: legacy global-name shim. Procedural code keeps`
	`150`	+// using `\Auth` until the call-site sweep PR.
	`151`	`+class_alias(\Sbpp\Auth\Auth::class, 'Auth');`
Original file line number	Diff line number	Diff line change
`@@ -1,5 +1,11 @@`
`1`	`1`	`<?php`
`2`	`2`
	`3`	`+namespace Sbpp\Auth\Handler;`
	`4`	`+`
	`5`	`+use Sbpp\Auth\Auth;`
	`6`	`+use Sbpp\Config;`
	`7`	`+use Sbpp\Db\Database;`
	`8`	`+`
`3`	`9`	`final class NormalAuthHandler`
`4`	`10`	`{`
`5`	`11`	`private bool $result = false;`
`@@ -63,3 +69,7 @@ private function getInfosFromDatabase(string $username): mixed`
`63`	`69`	`return $this->dbs->single();`
`64`	`70`	`}`
`65`	`71`	`}`
	`72`	`+`
	`73`	`+// Issue #1290 phase B: legacy global-name shim. Procedural code keeps`
	`74`	+// using `\NormalAuthHandler` until the call-site sweep PR.
	`75`	`+class_alias(\Sbpp\Auth\Handler\NormalAuthHandler::class, 'NormalAuthHandler');`
Original file line number	Diff line number	Diff line change
`@@ -1,5 +1,7 @@`
`1`	`1`	`<?php`
`2`	`2`
	`3`	`+namespace Sbpp\Auth;`
	`4`	`+`
`3`	`5`	`/**`
`4`	`6`	`* Class Host`
`5`	`7`	`*/`
`@@ -56,3 +58,7 @@ public static function complete(bool $withoutRequest = false): string`
`56`	`58`	`return self::protocol().self::domain() . ($withoutRequest ? '' : "/$request");`
`57`	`59`	`}`
`58`	`60`	`}`
	`61`	`+`
	`62`	`+// Issue #1290 phase B: legacy global-name shim. Procedural code keeps`
	`63`	+// using `\Host` until the call-site sweep PR.
	`64`	`+class_alias(\Sbpp\Auth\Host::class, 'Host');`