docs: add top speed server design

docs/superpowers/specs/2026-04-16-top-speed-server-design.md

@@ -0,0 +1,98 @@
+# Top Speed Server Design
+
+## Goal
+
+Add a server-style Top Speed setup flow that installs the latest arm64 server release dynamically, runs it as an unprivileged `topspeed` user from a standard server layout, manages it with systemd, and provides a console attach option through `tmux`.
+
+## Scope
+
+This change covers:
+
+- Adding `Top Speed Server` and `Top Speed Console` menu entries.
+- Installing required packages for download, archive extraction, JSON parsing, and console management.
+- Reusing the existing GitHub release metadata pattern from `linux-game-manager` to locate the latest arm64 server download without hard-coding a versioned URL.
+- Creating a locked-down `topspeed` service account with no password and no sudo access.
+- Installing Top Speed under `/var/lib/topspeed`.
+- Writing and enabling a systemd service that launches the server in a named tmux session.
+- Offering firewall setup for the documented default Top Speed ports when `ufw` is present.
+
+This change does not cover:
+
+- Custom Top Speed port configuration.
+- Automatic editing of Top Speed configuration files.
+- Disabling or changing the server's own automatic update behavior.
+- Automatic upgrade workflows after initial install.
+
+## Layout
+
+- Top Speed service account:
+  - user: `topspeed`
+  - home: `/var/lib/topspeed`
+  - shell: non-login shell
+- Installation root:
+  - `/var/lib/topspeed/server`
+- Temporary downloads:
+  - handled in a temporary directory and removed after extraction
+- Systemd unit:
+  - `/etc/systemd/system/topspeed.service`
+
+This keeps the install server-like and predictable for experienced admins while staying simple enough for new users to inspect.
+
+## Download Strategy
+
+The installer will query the GitHub releases API and select the newest arm64 server asset using `jq`, following the same basic approach already used for Top Speed in `linux-game-manager`.
+
+- Repository: `diamondStar35/top_speed`
+- Release metadata endpoint: GitHub releases API
+- Asset selection:
+  - match the arm64 server archive name pattern
+  - reject missing or ambiguous matches
+
+If `jq` is missing, the script will install it first. If `curl` is missing, the script will install it first as well.
+
+## Service Model
+
+The Top Speed server runs in the foreground and accepts console input, so the systemd service should not run the binary directly. Instead:
+
+- systemd starts a named `tmux` session as the `topspeed` user
+- the Top Speed server runs inside that `tmux` session
+- the service restarts on failure
+
+This provides both automatic startup and an attachable live console.
+
+## Console Access
+
+The `Top Speed Console` menu entry will:
+
+- verify that the `topspeed` tmux session exists
+- temporarily leave the dialog UI
+- attach to the tmux session
+- return to the menu after the user detaches
+
+If the service is not installed or the tmux session is not active, the script should show a clear message instead of failing noisily.
+
+## Firewall Rules
+
+If `ufw` is installed, the setup flow will offer to add rules for the documented default Top Speed ports:
+
+- server port `28630`
+- discovery port `28631`
+
+For this helper, the firewall setup will assume defaults only. If a user later customizes Top Speed ports, they are responsible for matching firewall rules manually.
+
+## Error Handling
+
+- If the GitHub metadata query fails, show a clear error and stop.
+- If no matching arm64 server asset is found, show a clear error and stop.
+- If user creation, directory creation, extraction, or service installation fails, stop with a clear message.
+- If firewall setup is declined or `ufw` is absent, continue without treating that as fatal.
+- If console attach is requested while the session is not running, show a message and return to the menu.
+
+## Verification
+
+Verification for this change will be limited in this environment to:
+
+- `bash -n` on edited shell scripts
+- `shellcheck` on edited shell scripts
+
+The Top Speed service itself, tmux session behavior, download flow, and firewall behavior will not be claimed as runtime-verified here because this machine is not the deployment target.