Merge pull request 'feat(sso): App Links autoVerify callback + paired-host trust check' (#17) from feat/app-links into main

Reviewed-on: #17
Reviewed-by: Colby Whitlock <whitlocktech@gmail.com>

.gitea/workflows/release.yml

@@ -0,0 +1,194 @@
+# Automated release for the Runic Gateway Android app.
+#
+# Trigger: pushing a version tag `v*` (e.g. `v0.1.0`). Tag-driven on purpose — the
+# build never has to push to protected `main`; the tag *is* the release input.
+#
+# To cut a release:
+#   git tag v0.1.0 && git push origin v0.1.0
+#   (or create the tag from the Gitea UI). Re-build/re-release an existing tag via
+#   the workflow_dispatch input below.
+#
+# versionName = the tag without its leading `v`; versionCode = major*10000 +
+# minor*100 + patch (deterministic + monotonic, PLAN.md §10). Both are injected
+# into app/build.gradle.kts for the build only — nothing is committed back to main.
+#
+# Prerequisites (Settings -> Actions -> Secrets on RunicGateway/Android-app):
+#   REGISTRY_TOKEN  — Gitea access token with `write:repository` (create the release)
+#   ANDROID_KEYSTORE_BASE64    — base64 of the release .jks (single line)
+#   ANDROID_KEYSTORE_PASSWORD  — keystore password
+#   ANDROID_KEY_ALIAS          — key alias (e.g. runicgateway)
+#   ANDROID_KEY_PASSWORD       — key password (== store password for a PKCS12 keystore)
+#
+# Runner handling matches pr-checks.yml (self-hosted `ubuntu-latest`): the container
+# lacks git/curl/unzip and can't reach api.adoptium.net, so we apt-install the base
+# tools + JDK 17 (not actions/setup-java), install the exact SDK packages, and
+# `chmod +x ./gradlew` in-step (checkout drops the exec bit).
+
+name: Release APK
+
+on:
+  push:
+    tags:
+      - 'v*'
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: 'Existing v* tag to (re)build and release'
+        required: true
+
+concurrency:
+  group: release-apk-${{ github.event.inputs.tag || github.ref_name }}
+  cancel-in-progress: false
+
+env:
+  GITEA_HOST: gitea.whitlocktech.com
+  REPO: RunicGateway/Android-app
+  GRADLE_MODULE: app
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    # Fail fast on a genuinely wedged run (e.g. a stalled SDK/network download on
+    # the self-hosted runner) instead of hanging forever and — because concurrency
+    # is `cancel-in-progress: false` — blocking every later release behind it.
+    timeout-minutes: 30
+    steps:
+      - name: Install base tools + JDK 17
+        run: |
+          apt-get update
+          apt-get install -y git curl unzip jq openjdk-17-jdk-headless
+          echo "JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64" >> "$GITHUB_ENV"
+
+      - name: Check out the release tag (full history for the changelog)
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.inputs.tag || github.ref_name }}
+          fetch-depth: 0
+
+      # ── Derive version + changelog straight from the tag ─────────────────
+      - name: Plan the release (version + changelog from the tag)
+        id: plan
+        run: |
+          set -euo pipefail
+          mkdir -p dist
+          git fetch --tags --force >/dev/null 2>&1 || true
+
+          TAG="${{ github.event.inputs.tag || github.ref_name }}"
+          case "$TAG" in
+            v[0-9]*) : ;;
+            *) echo "::error::expected a v* version tag, got '$TAG'"; exit 1 ;;
+          esac
+          VERSION="${TAG#v}"
+
+          # versionCode: deterministic + monotonic from the semver (PLAN.md §10).
+          IFS=. read -r MA MI PA <<< "$VERSION"
+          : "${MA:=0}"; : "${MI:=0}"; : "${PA:=0}"
+          VERSION_CODE=$(( MA*10000 + MI*100 + PA ))
+
+          # Changelog: conventional-commit subjects since the previous v* tag.
+          PREV_TAG="$(git describe --tags --match 'v*' --abbrev=0 "${TAG}^" 2>/dev/null || true)"
+          if [ -n "$PREV_TAG" ]; then RANGE="${PREV_TAG}..${TAG}"; else RANGE="${TAG}"; fi
+          SUBJECTS="$(git log --no-merges --format='%s' $RANGE || true)"
+
+          {
+            echo "## Runic Gateway Android ${TAG}"
+            echo
+            FEATS="$(echo "$SUBJECTS" | grep -E '^feat'        || true)"
+            FIXES="$(echo "$SUBJECTS" | grep -E '^(fix|perf)'  || true)"
+            [ -n "$FEATS" ] && { echo "### Features";  echo "$FEATS" | sed 's/^/- /'; echo; }
+            [ -n "$FIXES" ] && { echo "### Fixes";     echo "$FIXES" | sed 's/^/- /'; echo; }
+            echo "### All changes"
+            if [ -n "$PREV_TAG" ]; then echo "Since ${PREV_TAG}:"; fi
+            echo "$SUBJECTS" | sed 's/^/- /'
+            echo
+            echo "---"
+            echo "Signed APK — sideload on Android 10+ (§10). The app self-configures its shard site on first run."
+          } > dist/CHANGELOG.md
+
+          echo "version=${VERSION}"          >> "$GITHUB_OUTPUT"
+          echo "versionCode=${VERSION_CODE}" >> "$GITHUB_OUTPUT"
+          echo "tag=${TAG}"                  >> "$GITHUB_OUTPUT"
+          echo "==> tag=${TAG} version=${VERSION} code=${VERSION_CODE} prev_tag=${PREV_TAG:-<none>}"
+
+      # ── SDK + signing keystore ───────────────────────────────────────────
+      - name: Set up Android SDK
+        uses: android-actions/setup-android@v3
+        with:
+          # Only put cmdline-tools on PATH. The action's default package set drags in
+          # the whole emulator + the legacy `tools` package (hundreds of MB, network-
+          # bound on this runner) that a headless APK build never uses. The next step
+          # installs exactly the packages we need.
+          packages: ''
+
+      - name: Install Android SDK packages
+        run: |
+          set +o pipefail
+          yes | sdkmanager "platform-tools" "platforms;android-35" "build-tools;35.0.0"
+
+      - name: Decode signing keystore
+        env:
+          ANDROID_KEYSTORE_BASE64: ${{ secrets.ANDROID_KEYSTORE_BASE64 }}
+        run: |
+          set -euo pipefail
+          if [ -z "${ANDROID_KEYSTORE_BASE64:-}" ]; then
+            echo "::error::ANDROID_KEYSTORE_BASE64 secret is not set — cannot build a signed release."
+            exit 1
+          fi
+          printf '%s' "$ANDROID_KEYSTORE_BASE64" | base64 -d > "${RUNNER_TEMP}/release.jks"
+          echo "ANDROID_KEYSTORE_FILE=${RUNNER_TEMP}/release.jks" >> "$GITHUB_ENV"
+
+      # ── Set the version, build the signed APK ────────────────────────────
+      - name: Set the app version to match the tag
+        run: |
+          set -euo pipefail
+          VERSION="${{ steps.plan.outputs.version }}"
+          VERSION_CODE="${{ steps.plan.outputs.versionCode }}"
+          # Replace only the version defaults (the `?: "x.y.z"` / `?: N` fallbacks).
+          sed -i -E "s/(\?: )\"[0-9]+\.[0-9]+\.[0-9]+\"/\1\"${VERSION}\"/" "${GRADLE_MODULE}/build.gradle.kts"
+          sed -i -E "s/(toIntOrNull\(\) \?: )[0-9]+/\1${VERSION_CODE}/"     "${GRADLE_MODULE}/build.gradle.kts"
+          grep -nE "versionCode = |versionName = " "${GRADLE_MODULE}/build.gradle.kts"
+
+      - name: Unit tests + signed release APK
+        env:
+          ANDROID_KEYSTORE_PASSWORD: ${{ secrets.ANDROID_KEYSTORE_PASSWORD }}
+          ANDROID_KEY_ALIAS: ${{ secrets.ANDROID_KEY_ALIAS }}
+          ANDROID_KEY_PASSWORD: ${{ secrets.ANDROID_KEY_PASSWORD }}
+        run: |
+          set -euo pipefail
+          chmod +x ./gradlew
+          ./gradlew --no-daemon :${GRADLE_MODULE}:testDebugUnitTest :${GRADLE_MODULE}:assembleRelease
+
+      - name: Package APK + SHA256SUMS
+        run: |
+          set -euo pipefail
+          SRC="${GRADLE_MODULE}/build/outputs/apk/release/app-release.apk"
+          test -f "$SRC" || { echo "::error::release APK not found at $SRC"; exit 1; }
+          cp "$SRC" "dist/runic-gateway-${{ steps.plan.outputs.version }}.apk"
+          ( cd dist && sha256sum "runic-gateway-${{ steps.plan.outputs.version }}.apk" > SHA256SUMS )
+          ls -l dist && cat dist/SHA256SUMS
+
+      # ── Create the Gitea release + upload assets (no push to main) ───────
+      - name: Create Gitea release and upload assets
+        env:
+          REGISTRY_TOKEN: ${{ secrets.REGISTRY_TOKEN }}
+        run: |
+          set -euo pipefail
+          TAG="${{ steps.plan.outputs.tag }}"
+          API="https://${GITEA_HOST}/api/v1/repos/${REPO}"
+          BODY="$(cat dist/CHANGELOG.md)"
+          CI_TOKEN="$(printf '%s' "${REGISTRY_TOKEN}" | tr -d '\r\n')"
+
+          REL_ID="$(curl -sSf -X POST "${API}/releases" \
+            -H "Authorization: token ${CI_TOKEN}" \
+            -H "Content-Type: application/json" \
+            -d "$(jq -n --arg tag "$TAG" --arg body "$BODY" \
+                   '{tag_name:$tag, name:$tag, body:$body, draft:false, prerelease:false}')" \
+            | jq -r '.id')"
+          echo "Created release ${TAG} (id=${REL_ID})"
+
+          for f in "runic-gateway-${{ steps.plan.outputs.version }}.apk" SHA256SUMS; do
+            curl -sSf -X POST "${API}/releases/${REL_ID}/assets?name=${f}" \
+              -H "Authorization: token ${CI_TOKEN}" \
+              -F "attachment=@dist/${f}" >/dev/null
+            echo "  uploaded ${f}"
+          done

app/build.gradle.kts

@@ -1,5 +1,8 @@
 // SPDX-License-Identifier: GPL-3.0-or-later
 
+import java.io.FileInputStream
+import java.util.Properties
+
 plugins {
     alias(libs.plugins.android.application)
     alias(libs.plugins.kotlin.android)
@@ -9,6 +12,25 @@ plugins {
     alias(libs.plugins.hilt)
 }
 
+// Release signing material (PLAN.md §12) is never committed. It is read from, in
+// order of precedence: a local gitignored `keystore.properties` at the repo root,
+// then environment variables (how CI injects the decoded keystore + secrets). When
+// none is present, the release build is simply left unsigned — `assembleDebug` and
+// the PR gate are unaffected, so contributors without the keystore can still build.
+val keystorePropsFile = rootProject.file("keystore.properties")
+val keystoreProps = Properties().apply {
+    if (keystorePropsFile.exists()) FileInputStream(keystorePropsFile).use { load(it) }
+}
+fun signingValue(propKey: String, envKey: String): String? =
+    keystoreProps.getProperty(propKey) ?: System.getenv(envKey)
+
+val ksStoreFilePath = signingValue("storeFile", "ANDROID_KEYSTORE_FILE")
+val ksStorePassword = signingValue("storePassword", "ANDROID_KEYSTORE_PASSWORD")
+val ksKeyAlias = signingValue("keyAlias", "ANDROID_KEY_ALIAS")
+val ksKeyPassword = signingValue("keyPassword", "ANDROID_KEY_PASSWORD")
+val hasReleaseSigning = ksStoreFilePath != null && ksStorePassword != null &&
+    ksKeyAlias != null && ksKeyPassword != null
+
 android {
     namespace = "com.runicgateway.app"
     compileSdk = 35
@@ -18,20 +40,59 @@ android {
         applicationId = "com.runicgateway.app"
         minSdk = 29
         targetSdk = 35
-        versionCode = 1
-        versionName = "0.1.0"
+        // These committed defaults are the version source of truth (PLAN.md §10).
+        // release.yml's conventional-commit engine bumps versionName here and commits
+        // it on release; versionCode is derived from it (major*10000+minor*100+patch)
+        // so it stays monotonic. Both remain overridable via -P for local/manual builds.
+        versionCode = (project.findProperty("versionCode") as String?)?.toIntOrNull() ?: 1
+        versionName = (project.findProperty("versionName") as String?)?.takeIf { it.isNotBlank() } ?: "0.1.0"
 
         testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
+
+        // Android App Links host (docs/android/APP_LINKS.md). autoVerify needs a
+        // *literal* host at build time, so a single multi-tenant APK cannot verify
+        // open-ended shard domains: App Links are a build-time opt-in. Left empty for
+        // the generic build (custom scheme only); a white-label/first-party build
+        // bakes one host with `-PappLinkHost=play.myshard.com`.
+        //   • BuildConfig.APP_LINK_HOST — SsoAuthManager reads it to pick the redirect.
+        //   • manifestPlaceholder appLinkHost — substituted into the intent-filter host;
+        //     empty falls back to the reserved `.invalid` sentinel so the autoVerify
+        //     filter is inert (matches no real link, never verifies).
+        val appLinkHost = (project.findProperty("appLinkHost") as String?)?.trim().orEmpty()
+        buildConfigField("String", "APP_LINK_HOST", "\"$appLinkHost\"")
+        manifestPlaceholders["appLinkHost"] = appLinkHost.ifBlank { "runic-gateway.invalid" }
+    }
+
+    signingConfigs {
+        if (hasReleaseSigning) {
+            create("release") {
+                storeFile = file(ksStoreFilePath!!)
+                storePassword = ksStorePassword
+                keyAlias = ksKeyAlias
+                keyPassword = ksKeyPassword
+                // Sign with both v1 (JAR) and v2 (APK) schemes for broad compatibility.
+                enableV1Signing = true
+                enableV2Signing = true
+            }
+        }
     }
 
     buildTypes {
         release {
-            // Signing/minification are wired at M6 (release hardening). Debug is auto-signed.
-            isMinifyEnabled = false
+            // R8 full-mode minify + resource shrink (§7: no offline cache, so a lean
+            // release APK). Keep rules live in proguard-rules.pro.
+            isMinifyEnabled = true
+            isShrinkResources = true
             proguardFiles(
                 getDefaultProguardFile("proguard-android-optimize.txt"),
                 "proguard-rules.pro",
             )
+            // Signed only when the keystore material is present (local or CI); an
+            // unsigned APK is produced otherwise. The direct-APK release (§10) runs
+            // through release.yml, which supplies the keystore from a Gitea secret.
+            if (hasReleaseSigning) {
+                signingConfig = signingConfigs.getByName("release")
+            }
         }
     }
 

app/licenses/Cinzel-OFL.txt

@@ -0,0 +1,93 @@
+Copyright 2020 The Cinzel Project Authors (https://github.com/NDISCOVER/Cinzel)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

app/proguard-rules.pro

@@ -1,3 +1,59 @@
-# Runic Gateway Android app — ProGuard/R8 rules.
-# Minification is disabled until M6 (release hardening); real keep rules for
-# kotlinx.serialization DTOs and Retrofit models are added there.
+# Runic Gateway Android app — ProGuard/R8 rules (release minify + resource shrink, M6).
+#
+# The dependency stack ships its own consumer rules that R8 applies automatically:
+# Retrofit 2.11, OkHttp 4.12, kotlinx.serialization 1.7 (core), Hilt/Dagger, Coil 2.7.
+# The rules below are defensive belt-and-suspenders for the areas full-mode R8 is
+# most likely to over-strip in this app: the kotlinx.serialization generated
+# serializers and our own @Serializable wire DTOs.
+
+# ── kotlinx.serialization (canonical keep rules) ────────────────────────────
+-keepattributes *Annotation*, InnerClasses
+-dontnote kotlinx.serialization.**
+
+# Keep the Companion of @Serializable classes so `.serializer()` resolves.
+-if @kotlinx.serialization.Serializable class **
+-keepclassmembers class <1> {
+    static <1>$Companion Companion;
+}
+-if @kotlinx.serialization.Serializable class ** {
+    static **$Companion Companion;
+}
+-keepclassmembers class <2>$Companion {
+    kotlinx.serialization.KSerializer serializer(...);
+}
+# Keep `INSTANCE.serializer()` of @Serializable objects.
+-if @kotlinx.serialization.Serializable class ** {
+    public static ** INSTANCE;
+}
+-keepclassmembers class <1> {
+    public static <1> INSTANCE;
+    kotlinx.serialization.KSerializer serializer(...);
+}
+# Keep the synthesized $$serializer classes and their descriptor field.
+-keepclassmembers class **$$serializer {
+    *** descriptor;
+}
+
+# ── Our wire DTOs ───────────────────────────────────────────────────────────
+# All request/response models decoded by kotlinx.serialization. Keeping them
+# (and their generated serializers) guarantees additive backend fields and
+# @SerialName mappings survive minification. DTOs are small, so keeping them
+# whole is cheap insurance against a full-mode strip.
+-keep @kotlinx.serialization.Serializable class com.runicgateway.app.** { *; }
+-keepclassmembers class com.runicgateway.app.data.api.dto.** { *; }
+
+# ── Retrofit service interfaces ─────────────────────────────────────────────
+# Retrofit reads method + parameter annotations reflectively; keep our API
+# interfaces' generic signatures so return types (suspend .../Call<T>) resolve.
+-keep,allowobfuscation interface com.runicgateway.app.data.api.*Api
+-keepattributes Signature, Exceptions
+
+# Kotlin metadata is needed for reflection over Kotlin types (serialization/Retrofit).
+-keep class kotlin.Metadata { *; }
+
+# ── Tink / EncryptedSharedPreferences (androidx.security-crypto) ─────────────
+# Tink references Error Prone compile-only annotations that are absent at runtime;
+# they are safe to ignore (they carry no runtime behaviour). Suppresses the R8
+# "Missing class com.google.errorprone.annotations.*" errors.
+-dontwarn com.google.errorprone.annotations.**
+

app/src/main/AndroidManifest.xml

@@ -6,6 +6,13 @@
     <uses-permission android:name="android.permission.INTERNET" />
     <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
 
+    <!-- Opt-in push notifications (M7): the runtime notification permission (API 33+)
+         and a foreground service that holds the persistent ntfy connection open — the
+         embedded UnifiedPush distributor, so no separate app is needed (PLAN.md §11). -->
+    <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
+    <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
+    <uses-permission android:name="android.permission.FOREGROUND_SERVICE_DATA_SYNC" />
+
     <application
         android:name=".RunicGatewayApp"
         android:allowBackup="true"
@@ -17,15 +24,56 @@
         android:supportsRtl="true"
         android:theme="@style/Theme.RunicGateway">
 
+        <!-- singleTop so the SSO Custom Tab returning via the deep link reuses the
+             running task (onNewIntent) instead of stacking a second activity. -->
         <activity
             android:name=".MainActivity"
             android:exported="true"
+            android:launchMode="singleTop"
             android:theme="@style/Theme.RunicGateway">
             <intent-filter>
                 <action android:name="android.intent.action.MAIN" />
                 <category android:name="android.intent.category.LAUNCHER" />
             </intent-filter>
+
+            <!-- Native SSO callback (M9, PLAN.md §4.2). The bridge deep-links the
+                 one-time authorization code back to this fixed, app-owned custom
+                 scheme; it must match SsoAuthManager.REDIRECT_URI and the backend's
+                 MOBILE_AUTH_REDIRECT_URIS allowlist exactly. This is the permanent
+                 fallback on every build (docs/android/APP_LINKS.md). -->
+            <intent-filter>
+                <action android:name="android.intent.action.VIEW" />
+                <category android:name="android.intent.category.DEFAULT" />
+                <category android:name="android.intent.category.BROWSABLE" />
+                <data
+                    android:scheme="runicgateway"
+                    android:host="auth"
+                    android:path="/callback" />
+            </intent-filter>
+
+            <!-- App Links hardening (docs/android/APP_LINKS.md): a verified https
+                 callback that only the domain's real owner can claim. autoVerify
+                 needs a literal host, so ${appLinkHost} is baked at build time
+                 (build.gradle.kts). The generic build leaves it as the reserved
+                 runic-gateway.invalid sentinel — the filter then matches no real
+                 link and never verifies. A white-label build sets -PappLinkHost. -->
+            <intent-filter android:autoVerify="true">
+                <action android:name="android.intent.action.VIEW" />
+                <category android:name="android.intent.category.DEFAULT" />
+                <category android:name="android.intent.category.BROWSABLE" />
+                <data
+                    android:scheme="https"
+                    android:host="${appLinkHost}"
+                    android:path="/mobile/callback" />
+            </intent-filter>
         </activity>
+
+        <!-- The embedded distributor's persistent ntfy connection (M7, PLAN.md §11).
+             dataSync foreground type; not exported — started only by PushManager. -->
+        <service
+            android:name=".core.push.PushService"
+            android:exported="false"
+            android:foregroundServiceType="dataSync" />
     </application>
 
 </manifest>

app/src/main/java/com/runicgateway/app/MainActivity.kt

@@ -3,16 +3,25 @@
  */
 package com.runicgateway.app
 
+import android.content.Intent
+import android.graphics.Color
+import android.net.Uri
 import android.os.Bundle
 import androidx.activity.ComponentActivity
+import androidx.activity.SystemBarStyle
 import androidx.activity.compose.setContent
 import androidx.activity.enableEdgeToEdge
+import androidx.lifecycle.lifecycleScope
 import androidx.compose.foundation.layout.fillMaxSize
 import androidx.compose.material3.MaterialTheme
 import androidx.compose.material3.Surface
 import androidx.compose.runtime.CompositionLocalProvider
 import androidx.compose.runtime.getValue
+import androidx.compose.runtime.mutableStateOf
+import androidx.compose.runtime.setValue
 import androidx.compose.ui.Modifier
+import com.runicgateway.app.core.auth.sso.SsoAuthManager
+import com.runicgateway.app.core.push.PushNotifier
 import androidx.hilt.navigation.compose.hiltViewModel
 import androidx.lifecycle.compose.collectAsStateWithLifecycle
 import com.runicgateway.app.ui.AppViewModel
@@ -24,6 +33,8 @@ import com.runicgateway.app.ui.connect.ConnectScreen
 import com.runicgateway.app.ui.theme.RunicGatewayTheme
 import com.runicgateway.app.ui.theme.parseBrandColor
 import dagger.hilt.android.AndroidEntryPoint
+import kotlinx.coroutines.launch
+import javax.inject.Inject
 
 /**
  * Single-activity host (PLAN.md §2). Gates on [AppViewModel]: the first-run
@@ -33,9 +44,27 @@ import dagger.hilt.android.AndroidEntryPoint
  */
 @AndroidEntryPoint
 class MainActivity : ComponentActivity() {
+
+    // Native SSO bridge — handles the runicgateway://auth/callback deep link (M9,
+    // §4.2). Field-injected because the callback can arrive independent of any
+    // ViewModel; a successful exchange flips the SessionManager the whole app
+    // observes, and the login screen consumes SsoAuthManager.outcome.
+    @Inject
+    lateinit var ssoAuthManager: SsoAuthManager
+
+    // The stream a tapped push notification wants to open (§11, M7 Part 2 item 7).
+    // Set from the launching intent and from onNewIntent (the activity is singleTop),
+    // consumed once by RunicApp which navigates to the stream's screen.
+    private var pendingStream by mutableStateOf<String?>(null)
+
     override fun onCreate(savedInstanceState: Bundle?) {
         super.onCreate(savedInstanceState)
-        enableEdgeToEdge()
+        pendingStream = intent?.getStringExtra(PushNotifier.EXTRA_STREAM)
+        handleSsoCallback(intent)
+        // Dark-only app (M5): force light system-bar icons over the transparent bars so
+        // they stay legible on the deep blue-black surfaces regardless of system theme.
+        val barStyle = SystemBarStyle.dark(Color.TRANSPARENT)
+        enableEdgeToEdge(statusBarStyle = barStyle, navigationBarStyle = barStyle)
         setContent {
             val appViewModel: AppViewModel = hiltViewModel()
             val state by appViewModel.state.collectAsStateWithLifecycle()
@@ -53,11 +82,47 @@ class MainActivity : ComponentActivity() {
                             AppState.NeedsConnection ->
                                 ConnectScreen(onConnected = appViewModel::onConnected)
                             is AppState.Ready ->
-                                RunicApp(brand = s.brand, onChangeServer = appViewModel::changeServer)
+                                RunicApp(
+                                    brand = s.brand,
+                                    onChangeServer = appViewModel::changeServer,
+                                    deepLinkStream = pendingStream,
+                                    onDeepLinkConsumed = { pendingStream = null },
+                                )
                         }
                     }
                 }
             }
         }
     }
+
+    /**
+     * A notification tap or an SSO callback arriving while the activity is already
+     * running (singleTop) — the common case, since the Custom Tab overlays the live
+     * app during sign-in.
+     */
+    override fun onNewIntent(intent: Intent) {
+        super.onNewIntent(intent)
+        setIntent(intent)
+        intent.getStringExtra(PushNotifier.EXTRA_STREAM)?.let { pendingStream = it }
+        handleSsoCallback(intent)
+    }
+
+    /**
+     * Route an SSO callback VIEW intent into the bridge (M9, §4.2): either the
+     * custom-scheme `runicgateway://auth/callback` (always) or the verified https
+     * App Link `https://<paired-host>/mobile/callback` (opt-in hardening —
+     * docs/android/APP_LINKS.md). Both feed the *same* exchange; the result surfaces
+     * on `SsoAuthManager.outcome` (success signs the session in; failure shows on the
+     * login screen). Non-callback intents are ignored.
+     */
+    private fun handleSsoCallback(intent: Intent?) {
+        val data: Uri = intent?.takeIf { it.action == Intent.ACTION_VIEW }?.data ?: return
+        val isCallback = ssoAuthManager.matchesCallback(data.scheme, data.host, data.path) ||
+            ssoAuthManager.matchesAppLinkCallback(data.scheme, data.host, data.path)
+        if (!isCallback) return
+        val state = data.getQueryParameter("state")
+        val code = data.getQueryParameter("code")
+        val error = data.getQueryParameter("error")
+        lifecycleScope.launch { ssoAuthManager.complete(state = state, code = code, error = error) }
+    }
 }

app/src/main/java/com/runicgateway/app/core/auth/sso/Pkce.kt

@@ -0,0 +1,50 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.core.auth.sso
+
+import java.security.MessageDigest
+import java.security.SecureRandom
+import java.util.Base64
+
+/**
+ * PKCE + CSRF-state primitives for the Mobile SSO Authorization Bridge — "Layer B"
+ * of the two PKCE layers (app ↔ website; PLAN.md §4.2, BACKEND_DESIGN "Two PKCE
+ * layers"). The app proves at `/exchange` that it holds the verifier for the
+ * challenge it registered at `/start`, so an intercepted callback code is useless
+ * to anyone but this app.
+ *
+ * Pure JVM (no Android framework types) so it unit-tests on the plain test runner.
+ * The encoding mirrors the backend exactly (RFC 7636 S256): the challenge is
+ * `base64url(SHA-256(verifier))` with no padding, matching Node's
+ * `crypto.createHash('sha256').update(verifier).digest('base64url')`.
+ */
+object Pkce {
+
+    private val random = SecureRandom()
+
+    // RFC 4648 §5 URL-safe base64 without padding — the base64url the backend uses.
+    private val encoder = Base64.getUrlEncoder().withoutPadding()
+
+    /**
+     * A fresh high-entropy `code_verifier`: 32 random bytes → 43 base64url chars,
+     * comfortably inside RFC 7636's 43–128 range and identical in form to the
+     * verifier the website generates for its own IdP layer.
+     */
+    fun newVerifier(): String = randomToken()
+
+    /** A fresh opaque CSRF `state` (same entropy/shape as a verifier). */
+    fun newState(): String = randomToken()
+
+    /** `code_challenge` for [verifier] using the S256 method. */
+    fun challengeOf(verifier: String): String {
+        val digest = MessageDigest.getInstance("SHA-256").digest(verifier.toByteArray(Charsets.US_ASCII))
+        return encoder.encodeToString(digest)
+    }
+
+    private fun randomToken(): String {
+        val bytes = ByteArray(32)
+        random.nextBytes(bytes)
+        return encoder.encodeToString(bytes)
+    }
+}

app/src/main/java/com/runicgateway/app/core/auth/sso/SsoAuthManager.kt

@@ -0,0 +1,238 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.core.auth.sso
+
+import com.runicgateway.app.BuildConfig
+import com.runicgateway.app.core.auth.SessionManager
+import com.runicgateway.app.core.net.BaseUrlHolder
+import com.runicgateway.app.data.api.SsoApi
+import com.runicgateway.app.data.api.dto.MobileSsoExchangeRequest
+import kotlinx.coroutines.CancellationException
+import kotlinx.coroutines.flow.MutableStateFlow
+import kotlinx.coroutines.flow.StateFlow
+import kotlinx.coroutines.flow.asStateFlow
+import java.io.IOException
+import java.util.concurrent.atomic.AtomicReference
+import javax.inject.Inject
+import javax.inject.Singleton
+
+/**
+ * Orchestrates the native "Sign in with Google/Discord" flow — the app half of the
+ * Mobile SSO Authorization Bridge (PLAN.md §4.2, BACKEND_DESIGN "Mobile SSO
+ * Authorization Bridge"). It never adds a parallel auth path: a successful exchange
+ * drives the *same* [SessionManager.onSignedIn] the password login uses, so the
+ * menu, push registration, and re-validation all react identically.
+ *
+ * The flow:
+ *  1. [buildStartUrl] mints PKCE (Layer B) + a CSRF `state`, stashes them, and
+ *     returns the `/auth/mobile/sso/start` URL the caller opens in a Custom Tab.
+ *  2. The website bounces through the IdP and deep-links back to
+ *     [REDIRECT_URI] with `?code&state` (success) or `?error&state` (failure).
+ *  3. [complete] verifies `state`, exchanges the `code` with the stashed verifier,
+ *     and signs the user in — publishing the result on [outcome]. `MainActivity`
+ *     parses the callback `Uri` (the Android edge) and hands the raw params here,
+ *     so this class stays free of framework types and unit-tests on the JVM.
+ *
+ * The pending `{state, verifier}` lives only in memory: if the process is killed
+ * while the Custom Tab is foreground it is lost and the exchange **fails closed**
+ * (the user simply retries) — never a security downgrade.
+ *
+ * Threading: [buildStartUrl] runs on the UI thread; [complete] runs on the
+ * activity's coroutine scope after a deep link. The pending holder is an
+ * [AtomicReference] and [outcome] a [StateFlow], so a ViewModel/activity recreation
+ * while the Custom Tab is open cannot drop a result.
+ */
+@Singleton
+class SsoAuthManager @Inject constructor(
+    private val ssoApi: SsoApi,
+    private val sessionManager: SessionManager,
+    private val baseUrlHolder: BaseUrlHolder,
+) {
+
+    /** Why an SSO attempt ended, for a friendly inline message on the login screen. */
+    enum class Failure {
+        /** The user cancelled or the IdP/website refused (e.g. no linked account). */
+        DENIED,
+
+        /** The callback `state` didn't match — CSRF guard, or the pending flow was lost. */
+        STATE_MISMATCH,
+
+        /** The one-time code was unknown / expired / already used, or PKCE failed. */
+        EXPIRED_CODE,
+
+        /** Offline / DNS / TLS / timeout during the exchange. */
+        NETWORK,
+
+        /** Any other server failure, or a missing base URL / malformed callback. */
+        SERVER,
+    }
+
+    /** The observable result of the most recent flow; the login screen consumes it. */
+    sealed interface Outcome {
+        data object Idle : Outcome
+        data object Success : Outcome
+        data class Failed(val reason: Failure) : Outcome
+    }
+
+    private data class Pending(val state: String, val verifier: String)
+
+    private val pending = AtomicReference<Pending?>(null)
+
+    /**
+     * The host this build baked an App Link intent-filter for (`BuildConfig.APP_LINK_HOST`,
+     * empty on the generic multi-tenant build — see docs/android/APP_LINKS.md).
+     * `internal var` only so unit tests can exercise the App Link path without a build
+     * flavor; production never reassigns it.
+     */
+    internal var appLinkHost: String = BuildConfig.APP_LINK_HOST
+
+    private val _outcome = MutableStateFlow<Outcome>(Outcome.Idle)
+    val outcome: StateFlow<Outcome> = _outcome.asStateFlow()
+
+    /** Ack a delivered [outcome] so it isn't re-handled after a recomposition. */
+    fun consumeOutcome() {
+        _outcome.value = Outcome.Idle
+    }
+
+    /**
+     * Build the `/auth/mobile/sso/start` URL for [providerId] and stash the pending
+     * PKCE verifier + CSRF state. Returns null when no shard site is configured yet
+     * (the caller then keeps the website hand-off fallback). Also resets [outcome]
+     * to [Outcome.Idle] so a stale prior result can't fire against the new attempt.
+     */
+    fun buildStartUrl(providerId: String): String? {
+        val base = baseUrlHolder.current ?: return null
+        val verifier = Pkce.newVerifier()
+        val challenge = Pkce.challengeOf(verifier)
+        val state = Pkce.newState()
+        pending.set(Pending(state = state, verifier = verifier))
+        _outcome.value = Outcome.Idle
+        return base.newBuilder()
+            .addPathSegments("api/v1/auth/mobile/sso/start")
+            .addQueryParameter("provider", providerId)
+            .addQueryParameter("code_challenge", challenge)
+            .addQueryParameter("state", state)
+            .addQueryParameter("redirect_uri", redirectUriFor(base.host))
+            .build()
+            .toString()
+    }
+
+    /**
+     * The `redirect_uri` to request for a shard on [pairedHost]: the verified https
+     * App Link callback **iff** this build baked an App Link host that matches the
+     * paired host (a white-label/first-party build for exactly this shard — which is
+     * also responsible for enabling `mobile_app_links_enabled` server-side); otherwise
+     * the fixed custom-scheme callback, which every build/shard always supports.
+     */
+    private fun redirectUriFor(pairedHost: String): String =
+        if (appLinkHost.isNotBlank() && appLinkHost.equals(pairedHost, ignoreCase = true)) {
+            "https://$pairedHost$APP_LINK_CALLBACK_PATH"
+        } else {
+            REDIRECT_URI
+        }
+
+    /** True if a deep link's scheme/host/path are our fixed custom-scheme SSO callback. */
+    fun matchesCallback(scheme: String?, host: String?, path: String?): Boolean =
+        scheme == CALLBACK_SCHEME && host == CALLBACK_HOST && path == CALLBACK_PATH
+
+    /**
+     * True if a deep link is a verified https App Link callback for the shard we are
+     * **currently paired to**. The `host == pairedHost` check is defense-in-depth:
+     * `autoVerify` already means only a real, opted-in shard domain can route here,
+     * but the app still refuses an https callback whose host isn't the paired shard.
+     * Returns false before a shard is configured (no paired host to trust).
+     */
+    fun matchesAppLinkCallback(scheme: String?, host: String?, path: String?): Boolean {
+        val pairedHost = baseUrlHolder.current?.host ?: return false
+        return scheme == "https" && path == APP_LINK_CALLBACK_PATH &&
+            host != null && host.equals(pairedHost, ignoreCase = true)
+    }
+
+    /**
+     * Handle the parsed callback params from a returned [REDIRECT_URI] deep link:
+     * verify `state`, map an `error`, else exchange the `code` and sign in.
+     * Publishes the result on [outcome]. Idempotent-safe: the pending is cleared on
+     * entry, so a duplicate delivery of the same callback finds no pending and fails
+     * as [Failure.STATE_MISMATCH] rather than double-exchanging (the backend also
+     * single-uses the code).
+     */
+    suspend fun complete(state: String?, code: String?, error: String?) {
+        val stashed = pending.getAndSet(null)
+
+        // CSRF: the callback must echo the exact state we generated at /start.
+        if (stashed == null || state.isNullOrEmpty() || state != stashed.state) {
+            _outcome.value = Outcome.Failed(Failure.STATE_MISMATCH)
+            return
+        }
+
+        // A website/IdP-side failure comes back as ?error=… (never with a code).
+        if (!error.isNullOrEmpty()) {
+            _outcome.value = Outcome.Failed(mapError(error))
+            return
+        }
+
+        if (code.isNullOrBlank()) {
+            _outcome.value = Outcome.Failed(Failure.SERVER)
+            return
+        }
+
+        val response = try {
+            ssoApi.exchange(MobileSsoExchangeRequest(code = code, codeVerifier = stashed.verifier))
+        } catch (e: CancellationException) {
+            throw e
+        } catch (_: IOException) {
+            _outcome.value = Outcome.Failed(Failure.NETWORK)
+            return
+        } catch (_: Exception) {
+            _outcome.value = Outcome.Failed(Failure.SERVER)
+            return
+        }
+
+        if (response.isSuccessful) {
+            val body = response.body()
+            if (body == null) {
+                _outcome.value = Outcome.Failed(Failure.SERVER)
+                return
+            }
+            sessionManager.onSignedIn(body.accessToken, body.refreshToken, body.user)
+            _outcome.value = Outcome.Success
+            return
+        }
+
+        _outcome.value = Outcome.Failed(if (response.code() == 401) Failure.EXPIRED_CODE else Failure.SERVER)
+    }
+
+    // The bridge's start + callback error codes → user-facing failure reasons.
+    // Start (mobileSso.controller): invalid_provider | provider_unavailable | server_error.
+    // Callback (sso.controller): not_linked | disabled | session_expired | error,
+    // plus a forwarded IdP access_denied.
+    private fun mapError(error: String): Failure = when (error) {
+        // Link-only policy refused, or the account is inactive, or the user declined.
+        "not_linked", "disabled", "access_denied" -> Failure.DENIED
+        // The bridge session aged out mid-flow — start over.
+        "session_expired" -> Failure.EXPIRED_CODE
+        // invalid_provider / provider_unavailable / server_error / error / anything else.
+        else -> Failure.SERVER
+    }
+
+    companion object {
+        const val CALLBACK_SCHEME = "runicgateway"
+        const val CALLBACK_HOST = "auth"
+        const val CALLBACK_PATH = "/callback"
+
+        /**
+         * The one fixed, application-owned callback the bridge redirects to. Must
+         * match the `MOBILE_AUTH_REDIRECT_URIS` allowlist entry on the backend and
+         * the intent-filter in `AndroidManifest.xml` exactly (PLAN.md §4.2).
+         */
+        const val REDIRECT_URI = "$CALLBACK_SCHEME://$CALLBACK_HOST$CALLBACK_PATH"
+
+        /**
+         * Path of the verified https App Link callback (`https://<shard-host>/mobile/callback`).
+         * Must match the app's `autoVerify` intent-filter in `AndroidManifest.xml` and the
+         * backend's self-origin allowlist entry (docs/android/APP_LINKS.md §3.2/§4.2).
+         */
+        const val APP_LINK_CALLBACK_PATH = "/mobile/callback"
+    }
+}

app/src/main/java/com/runicgateway/app/core/push/NtfyStreamClient.kt

@@ -0,0 +1,116 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.core.push
+
+import kotlinx.coroutines.CompletableDeferred
+import kotlinx.coroutines.delay
+import kotlinx.coroutines.flow.Flow
+import kotlinx.coroutines.flow.channelFlow
+import kotlinx.coroutines.isActive
+import kotlinx.serialization.json.Json
+import okhttp3.OkHttpClient
+import okhttp3.Request
+import okhttp3.Response
+import okhttp3.sse.EventSource
+import okhttp3.sse.EventSourceListener
+import okhttp3.sse.EventSources
+import java.util.concurrent.TimeUnit
+import java.util.concurrent.atomic.AtomicBoolean
+import javax.inject.Inject
+import javax.inject.Singleton
+
+/**
+ * The embedded distributor's transport (PLAN.md §11, M7 Part 2 work item 1/3):
+ * a persistent connection to the shard's self-hosted ntfy that subscribes to the
+ * app's own topic and re-emits each content-free tickle. It reuses the same
+ * OkHttp-SSE + reconnect/backoff shape as [com.runicgateway.app.core.net.ShardStreamClient],
+ * but on a **bare** client — no host-retargeting or bearer interceptors — because it
+ * talks straight to ntfy (`<ntfy>/<topic>/sse`), not the website API. Held open by
+ * [PushService]'s foreground service so tickles arrive in the background without
+ * Google Play Services.
+ */
+@Singleton
+class NtfyStreamClient @Inject constructor(
+    private val json: Json,
+) {
+    // A dedicated client with the read timeout disabled for the mostly-idle stream
+    // (ntfy sends keepalive frames); no interceptors so nothing rewrites the host or
+    // attaches a bearer to the relay.
+    private val client: OkHttpClient = OkHttpClient.Builder()
+        .readTimeout(0, TimeUnit.MILLISECONDS)
+        .retryOnConnectionFailure(true)
+        .build()
+
+    private val factory = EventSources.createFactory(client)
+
+    /** Connection lifecycle + decoded tickles for a subscribed topic. */
+    sealed interface Event {
+        data object Open : Event
+        data object Closed : Event
+        data class Message(val tickle: PushTickle) : Event
+    }
+
+    /**
+     * A cold flow subscribing to `<ntfyBaseUrl>/<topic>/sse`, reconnecting with
+     * backoff until the collector cancels. A dropped relay simply reconnects; a bad
+     * config (null URL) idles rather than spinning.
+     */
+    fun events(ntfyBaseUrl: String?, topic: String): Flow<Event> = channelFlow {
+        var backoffMs = INITIAL_BACKOFF_MS
+        while (isActive) {
+            val url = NtfyTopic.sseUrl(ntfyBaseUrl, topic)
+            if (url == null) {
+                trySend(Event.Closed)
+                delay(backoffMs)
+                backoffMs = grow(backoffMs)
+                continue
+            }
+
+            val request = Request.Builder()
+                .url(url)
+                .header("Accept", "text/event-stream")
+                .build()
+
+            val opened = AtomicBoolean(false)
+            val ended = CompletableDeferred<Unit>()
+            val listener = object : EventSourceListener() {
+                override fun onOpen(eventSource: EventSource, response: Response) {
+                    opened.set(true)
+                    trySend(Event.Open)
+                }
+
+                override fun onEvent(eventSource: EventSource, id: String?, type: String?, data: String) {
+                    parseNtfyTickle(json, data)?.let { trySend(Event.Message(it)) }
+                }
+
+                override fun onClosed(eventSource: EventSource) {
+                    trySend(Event.Closed)
+                    ended.complete(Unit)
+                }
+
+                override fun onFailure(eventSource: EventSource, t: Throwable?, response: Response?) {
+                    trySend(Event.Closed)
+                    ended.complete(Unit)
+                }
+            }
+
+            val source = factory.newEventSource(request, listener)
+            try {
+                ended.await()
+            } finally {
+                source.cancel()
+            }
+
+            backoffMs = if (opened.get()) INITIAL_BACKOFF_MS else grow(backoffMs)
+            delay(backoffMs)
+        }
+    }
+
+    private fun grow(current: Long): Long = (current * 2).coerceAtMost(MAX_BACKOFF_MS)
+
+    private companion object {
+        const val INITIAL_BACKOFF_MS = 2_000L
+        const val MAX_BACKOFF_MS = 30_000L
+    }
+}

app/src/main/java/com/runicgateway/app/core/push/NtfyTopic.kt

@@ -0,0 +1,48 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.core.push
+
+import java.security.SecureRandom
+
+/**
+ * The app's own ntfy topic — the heart of the embedded-distributor design
+ * (PLAN.md §11, M7 Part 2 work item 1). The app mints a **random, unguessable**
+ * topic and registers its public URL (`https://<ntfy-host>/<topic>`) as the device
+ * endpoint the backend POSTs tickles to; the app subscribes to the same topic's SSE
+ * stream to receive them. Security rests on the topic being unguessable plus the
+ * content-free tickle — a leaked topic name reveals nothing.
+ */
+object NtfyTopic {
+
+    // ntfy topic names allow [A-Za-z0-9_-]; keep to that set. The "up" prefix mirrors
+    // the UnifiedPush convention and makes topics recognizable in logs/relay.
+    private const val ALPHABET = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789"
+    private const val TOPIC_LEN = 24
+    private const val PREFIX = "up"
+
+    private val secureRandom by lazy { SecureRandom() }
+
+    /** Mint a fresh unguessable topic, e.g. "up7Qk3…" (≈143 bits of entropy). */
+    fun generate(random: java.util.Random = secureRandom): String {
+        val sb = StringBuilder(PREFIX.length + TOPIC_LEN)
+        sb.append(PREFIX)
+        repeat(TOPIC_LEN) { sb.append(ALPHABET[random.nextInt(ALPHABET.length)]) }
+        return sb.toString()
+    }
+
+    /**
+     * The endpoint URL the backend publishes to: `<ntfyBaseUrl>/<topic>`. [ntfyBaseUrl]
+     * is the client-facing base from `/public/settings.push.ntfyUrl`; a trailing slash
+     * is tolerated. Returns null for a blank base or topic.
+     */
+    fun endpointUrl(ntfyBaseUrl: String?, topic: String): String? {
+        val base = ntfyBaseUrl?.trim()?.trimEnd('/').orEmpty()
+        if (base.isEmpty() || topic.isBlank()) return null
+        return "$base/$topic"
+    }
+
+    /** The SSE subscribe URL the app connects to: `<ntfyBaseUrl>/<topic>/sse`. */
+    fun sseUrl(ntfyBaseUrl: String?, topic: String): String? =
+        endpointUrl(ntfyBaseUrl, topic)?.let { "$it/sse" }
+}

app/src/main/java/com/runicgateway/app/core/push/PushManager.kt

@@ -0,0 +1,156 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.core.push
+
+import android.content.Context
+import com.runicgateway.app.core.auth.Session
+import com.runicgateway.app.core.auth.SessionManager
+import com.runicgateway.app.core.result.ApiResult
+import com.runicgateway.app.data.repository.NotificationsRepository
+import dagger.hilt.android.qualifiers.ApplicationContext
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.SupervisorJob
+import kotlinx.coroutines.flow.Flow
+import kotlinx.coroutines.flow.map
+import kotlinx.coroutines.launch
+import javax.inject.Inject
+import javax.inject.Singleton
+
+/**
+ * Orchestrates the app's opt-in push lifecycle (PLAN.md §11, M7 Part 2 work item 5):
+ * mint/keep the ntfy topic, register/unregister the device endpoint with the backend,
+ * and start/stop the foreground [PushService] — all keyed to the user's opt-in and
+ * the session. The endpoint the app registers is its own topic URL on the shard's
+ * ntfy (the embedded-distributor design, work item 1).
+ *
+ * Lifecycle rules:
+ *  - register only when **signed in** and the shard advertises a relay (`ntfyUrl`);
+ *  - a **sign-out** stops the service and forgets the ephemeral registration but keeps
+ *    the opt-in intent, so push re-registers on the next sign-in (mirrors the M3 token
+ *    teardown, and covers logout / dead-refresh / server switch uniformly via the
+ *    session-state observer);
+ *  - a **relay/base-URL change** re-registers on the new host with a fresh topic.
+ */
+@Singleton
+class PushManager @Inject constructor(
+    @param:ApplicationContext private val context: Context,
+    private val prefs: PushPreferences,
+    private val notifications: NotificationsRepository,
+    private val sessionManager: SessionManager,
+) {
+    private val scope = CoroutineScope(SupervisorJob() + Dispatchers.IO)
+
+    /** Whether the user has push turned on (drives the Notifications screen). */
+    val enabled: Flow<Boolean> = prefs.enabled
+
+    /** Whether this shard advertises a push relay at all (null ntfyUrl → unsupported). */
+    val supported: Flow<Boolean> = prefs.ntfyUrl.map { !it.isNullOrBlank() }
+
+    init {
+        // Uniform teardown/resume across every auth transition: logout, dead-refresh
+        // sign-out, and server switch all land on SignedOut; a fresh login re-asserts.
+        scope.launch {
+            sessionManager.state.collect { s ->
+                when (s) {
+                    is Session.SignedOut -> localTeardown()
+                    is Session.SignedIn -> maybeResume()
+                }
+            }
+        }
+    }
+
+    /** Record the shard's client-facing ntfy base URL (from `/public/settings`). */
+    suspend fun setNtfyUrl(url: String?) {
+        val previous = prefs.snapshot().ntfyUrl
+        prefs.setNtfyUrl(url)
+        // The relay host arriving (or changing) is what unblocks a pending resume.
+        if (!url.isNullOrBlank() && url != previous) maybeResume()
+    }
+
+    /**
+     * Turn push on (idempotent): ensure a topic on the current relay, register its
+     * endpoint with the backend, persist, and start the foreground service. Called
+     * when the user opts into ≥1 stream.
+     */
+    suspend fun enable(): PushResult = register(setIntent = true)
+
+    /** Turn push off (user opted out of every stream): clear intent + deregister. */
+    suspend fun disable() {
+        prefs.setEnabled(false)
+        deregisterDevice()
+    }
+
+    /**
+     * Deregister this device on an explicit sign-out / server switch, while the bearer
+     * is still valid, so no orphan device row is left behind. Keeps the opt-in intent
+     * (and ntfyUrl) so push re-registers on the next sign-in. Call this *before* the
+     * session is torn down.
+     */
+    suspend fun deregisterDevice() {
+        val snap = prefs.snapshot()
+        snap.deviceId?.let { notifications.deleteDevice(it) } // best-effort
+        stopService()
+        prefs.clearRegistration()
+    }
+
+    /** Re-assert registration if the user is opted in and the shard supports push. */
+    private suspend fun maybeResume() {
+        val snap = prefs.snapshot()
+        if (snap.enabled && sessionManager.isSignedIn && !snap.ntfyUrl.isNullOrBlank()) {
+            register(setIntent = false)
+        }
+    }
+
+    private suspend fun register(setIntent: Boolean): PushResult {
+        if (!sessionManager.isSignedIn) return PushResult.NotSignedIn
+        val snap = prefs.snapshot()
+        val ntfyUrl = snap.ntfyUrl
+        if (ntfyUrl.isNullOrBlank()) return PushResult.Unsupported
+
+        // Reuse an existing topic only if its endpoint still sits on the current relay
+        // origin; otherwise (first run, or a server switch) mint a fresh unguessable one.
+        val base = ntfyUrl.trimEnd('/')
+        val topic = snap.topic?.takeIf { snap.endpoint?.startsWith("$base/") == true }
+            ?: NtfyTopic.generate()
+        val endpoint = NtfyTopic.endpointUrl(ntfyUrl, topic) ?: return PushResult.Unsupported
+
+        return when (val res = notifications.registerDevice(endpoint, PLATFORM)) {
+            is ApiResult.Ok -> {
+                prefs.setRegistration(topic, endpoint, res.data.id)
+                if (setIntent) prefs.setEnabled(true)
+                startService()
+                PushResult.Enabled
+            }
+            // 400 = endpoint origin isn't on the shard's ntfy allow-set (misconfigured relay).
+            is ApiResult.HttpError -> PushResult.Failed(res.status)
+            is ApiResult.NetworkError -> PushResult.Failed(null)
+        }
+    }
+
+    /** Local-only teardown on sign-out — no backend DELETE (the bearer may be dead). */
+    private suspend fun localTeardown() {
+        stopService()
+        prefs.clearRegistration()
+    }
+
+    private fun startService() = runCatching { PushService.start(context) }
+    private fun stopService() = runCatching { PushService.stop(context) }
+
+    /** The outcome of enabling push, surfaced to the Notifications screen. */
+    sealed interface PushResult {
+        data object Enabled : PushResult
+
+        /** This shard advertises no push relay (`/public/settings.push.ntfyUrl` is null). */
+        data object Unsupported : PushResult
+        data object NotSignedIn : PushResult
+
+        /** Registration failed — [status] 400 = relay off the allow-set; null = network. */
+        data class Failed(val status: Int?) : PushResult
+    }
+
+    private companion object {
+        const val PLATFORM = "android"
+    }
+}

app/src/main/java/com/runicgateway/app/core/push/PushNotifier.kt

@@ -0,0 +1,110 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.core.push
+
+import android.app.Notification
+import android.app.NotificationChannel
+import android.app.NotificationManager
+import android.app.PendingIntent
+import android.content.Context
+import android.content.Intent
+import androidx.core.app.NotificationCompat
+import androidx.core.app.NotificationManagerCompat
+import com.runicgateway.app.MainActivity
+import com.runicgateway.app.R
+import dagger.hilt.android.qualifiers.ApplicationContext
+import java.util.concurrent.atomic.AtomicInteger
+import javax.inject.Inject
+import javax.inject.Singleton
+
+/**
+ * Builds the notification channels and posts a notification for a received tickle
+ * (PLAN.md §11, M7 Part 2 work items 2/3/7). v1 shows a **generic per-stream**
+ * notification titled from the fixed [PushStreams] catalog — the content-free tickle
+ * carries nothing to render, so nothing is fetched to display the notification; tapping
+ * deep-links into [MainActivity] (which fetches fresh over the authenticated API).
+ */
+@Singleton
+class PushNotifier @Inject constructor(
+    @param:ApplicationContext private val context: Context,
+) {
+    private val manager = NotificationManagerCompat.from(context)
+    private val nextId = AtomicInteger(1)
+
+    /** Create both channels; safe to call repeatedly (creation is idempotent). */
+    fun ensureChannels() {
+        val system = context.getSystemService(NotificationManager::class.java) ?: return
+        system.createNotificationChannel(
+            NotificationChannel(
+                CHANNEL_MESSAGES,
+                context.getString(R.string.push_channel_messages),
+                NotificationManager.IMPORTANCE_DEFAULT,
+            ).apply { description = context.getString(R.string.push_channel_messages_desc) },
+        )
+        system.createNotificationChannel(
+            NotificationChannel(
+                CHANNEL_SERVICE,
+                context.getString(R.string.push_channel_service),
+                NotificationManager.IMPORTANCE_LOW,
+            ).apply {
+                description = context.getString(R.string.push_channel_service_desc)
+                setShowBadge(false)
+            },
+        )
+    }
+
+    /** The persistent low-importance notification the foreground service runs under. */
+    fun serviceNotification(): Notification =
+        NotificationCompat.Builder(context, CHANNEL_SERVICE)
+            .setContentTitle(context.getString(R.string.push_service_title))
+            .setContentText(context.getString(R.string.push_service_text))
+            .setSmallIcon(R.drawable.ic_stat_name)
+            .setOngoing(true)
+            .setPriority(NotificationCompat.PRIORITY_LOW)
+            .setContentIntent(deepLinkIntent(stream = null, ref = null))
+            .build()
+
+    /** Post a notification for a tickle, deep-linking to the stream's screen on tap. */
+    fun notify(tickle: PushTickle) {
+        if (!manager.areNotificationsEnabled()) return // POST_NOTIFICATIONS not granted
+        val title = context.getString(PushStreams.titleRes(tickle.stream))
+        val notification = NotificationCompat.Builder(context, CHANNEL_MESSAGES)
+            .setContentTitle(title)
+            .setSmallIcon(R.drawable.ic_stat_name)
+            .setAutoCancel(true)
+            .setPriority(NotificationCompat.PRIORITY_DEFAULT)
+            .setContentIntent(deepLinkIntent(tickle.stream, tickle.ref))
+            .build()
+        try {
+            manager.notify(nextId.getAndIncrement(), notification)
+        } catch (_: SecurityException) {
+            // Racing a permission revoke — drop silently rather than crash.
+        }
+    }
+
+    private fun deepLinkIntent(stream: String?, ref: String?): PendingIntent {
+        val intent = Intent(context, MainActivity::class.java).apply {
+            flags = Intent.FLAG_ACTIVITY_SINGLE_TOP or Intent.FLAG_ACTIVITY_CLEAR_TOP
+            if (stream != null) putExtra(EXTRA_STREAM, stream)
+            if (ref != null) putExtra(EXTRA_REF, ref)
+        }
+        // A distinct request code per stream so PendingIntents don't collapse into one.
+        val requestCode = stream?.hashCode() ?: 0
+        return PendingIntent.getActivity(
+            context,
+            requestCode,
+            intent,
+            PendingIntent.FLAG_IMMUTABLE or PendingIntent.FLAG_UPDATE_CURRENT,
+        )
+    }
+
+    companion object {
+        const val CHANNEL_MESSAGES = "push_messages"
+        const val CHANNEL_SERVICE = "push_service"
+
+        /** Intent extras a tapped notification carries into [MainActivity] (§7 deep-links). */
+        const val EXTRA_STREAM = "com.runicgateway.app.push.STREAM"
+        const val EXTRA_REF = "com.runicgateway.app.push.REF"
+    }
+}

app/src/main/java/com/runicgateway/app/core/push/PushPreferences.kt

@@ -0,0 +1,91 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.core.push
+
+import android.content.Context
+import androidx.datastore.core.DataStore
+import androidx.datastore.preferences.core.Preferences
+import androidx.datastore.preferences.core.booleanPreferencesKey
+import androidx.datastore.preferences.core.edit
+import androidx.datastore.preferences.core.longPreferencesKey
+import androidx.datastore.preferences.core.stringPreferencesKey
+import androidx.datastore.preferences.preferencesDataStore
+import dagger.hilt.android.qualifiers.ApplicationContext
+import kotlinx.coroutines.flow.Flow
+import kotlinx.coroutines.flow.first
+import kotlinx.coroutines.flow.map
+import javax.inject.Inject
+import javax.inject.Singleton
+
+private val Context.pushDataStore: DataStore<Preferences> by preferencesDataStore(name = "push")
+
+/**
+ * Persists the app's push state (PLAN.md §11, M7 Part 2 work item 5). None of it is
+ * secret — the ntfy topic/endpoint's protection is being unguessable plus the
+ * content-free tickle — so plain DataStore is fine (tokens stay in the encrypted
+ * store). Holds the shard's ntfy base URL (from `/public/settings`), the minted
+ * topic + its endpoint URL, the backend-assigned device id (to unregister), and the
+ * user's opt-in flag (the source of truth for "push should be running").
+ */
+@Singleton
+class PushPreferences @Inject constructor(
+    @param:ApplicationContext private val context: Context,
+) {
+    private val store = context.pushDataStore
+
+    val enabled: Flow<Boolean> = store.data.map { it[KEY_ENABLED] ?: false }
+    val ntfyUrl: Flow<String?> = store.data.map { it[KEY_NTFY_URL] }
+
+    suspend fun snapshot(): Snapshot {
+        val p = store.data.first()
+        return Snapshot(
+            enabled = p[KEY_ENABLED] ?: false,
+            ntfyUrl = p[KEY_NTFY_URL],
+            topic = p[KEY_TOPIC],
+            endpoint = p[KEY_ENDPOINT],
+            deviceId = p[KEY_DEVICE_ID],
+        )
+    }
+
+    suspend fun setNtfyUrl(url: String?) = store.edit {
+        if (url.isNullOrBlank()) it.remove(KEY_NTFY_URL) else it[KEY_NTFY_URL] = url
+    }
+
+    suspend fun setEnabled(value: Boolean) = store.edit { it[KEY_ENABLED] = value }
+
+    /** Record the minted topic + its endpoint URL and the assigned device id together. */
+    suspend fun setRegistration(topic: String, endpoint: String, deviceId: Long) = store.edit {
+        it[KEY_TOPIC] = topic
+        it[KEY_ENDPOINT] = endpoint
+        it[KEY_DEVICE_ID] = deviceId
+    }
+
+    /**
+     * Forget the ephemeral device registration (topic/endpoint/device id) — used on
+     * sign-out and on an explicit disable. Deliberately leaves [KEY_ENABLED] and
+     * [KEY_NTFY_URL] intact so the user's opt-in intent survives a sign-out and push
+     * re-registers on the next sign-in; an explicit disable also calls [setEnabled]`(false)`.
+     */
+    suspend fun clearRegistration() = store.edit {
+        it.remove(KEY_TOPIC)
+        it.remove(KEY_ENDPOINT)
+        it.remove(KEY_DEVICE_ID)
+    }
+
+    data class Snapshot(
+        val enabled: Boolean,
+        val ntfyUrl: String?,
+        val topic: String?,
+        val endpoint: String?,
+        val deviceId: Long?,
+    )
+
+    private companion object {
+        val KEY_ENABLED = booleanPreferencesKey("enabled")
+        val KEY_NTFY_URL = stringPreferencesKey("ntfy_url")
+        val KEY_TOPIC = stringPreferencesKey("topic")
+        val KEY_ENDPOINT = stringPreferencesKey("endpoint")
+        val KEY_DEVICE_ID = longPreferencesKey("device_id")
+    }
+}

app/src/main/java/com/runicgateway/app/core/push/PushService.kt

@@ -0,0 +1,95 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.core.push
+
+import android.app.Service
+import android.content.Context
+import android.content.Intent
+import android.content.pm.ServiceInfo
+import android.os.Build
+import android.os.IBinder
+import androidx.core.app.ServiceCompat
+import dagger.hilt.android.AndroidEntryPoint
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.Job
+import kotlinx.coroutines.SupervisorJob
+import kotlinx.coroutines.cancel
+import kotlinx.coroutines.flow.collectLatest
+import kotlinx.coroutines.launch
+import javax.inject.Inject
+
+/**
+ * The always-connected foreground service that IS the embedded distributor
+ * (PLAN.md §11, M7 Part 2 work item 1/3). It holds [NtfyStreamClient]'s persistent
+ * connection to the shard's ntfy open in the background — the price of Google-free,
+ * self-contained instant delivery — and posts a notification for each tickle. It runs
+ * under a low-importance ongoing notification and restarts sticky; [PushManager] starts
+ * and stops it as the user opts in/out or signs out.
+ */
+@AndroidEntryPoint
+class PushService : Service() {
+
+    @Inject lateinit var streamClient: NtfyStreamClient
+    @Inject lateinit var notifier: PushNotifier
+    @Inject lateinit var prefs: PushPreferences
+
+    private val scope = CoroutineScope(SupervisorJob() + Dispatchers.IO)
+    private var connectionJob: Job? = null
+
+    override fun onCreate() {
+        super.onCreate()
+        notifier.ensureChannels()
+    }
+
+    override fun onStartCommand(intent: Intent?, flags: Int, startId: Int): Int {
+        startAsForeground()
+        if (connectionJob == null) connectionJob = scope.launch { run() }
+        return START_STICKY
+    }
+
+    private fun startAsForeground() {
+        val type = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.UPSIDE_DOWN_CAKE) {
+            ServiceInfo.FOREGROUND_SERVICE_TYPE_DATA_SYNC
+        } else {
+            0
+        }
+        ServiceCompat.startForeground(this, NOTIFICATION_ID, notifier.serviceNotification(), type)
+    }
+
+    private suspend fun run() {
+        val snapshot = prefs.snapshot()
+        val topic = snapshot.topic
+        if (topic.isNullOrBlank() || snapshot.ntfyUrl.isNullOrBlank()) {
+            // Nothing to subscribe to (should not happen — PushManager starts us only
+            // once a topic exists) — stop rather than hold a dead connection open.
+            stopSelf()
+            return
+        }
+        streamClient.events(snapshot.ntfyUrl, topic).collectLatest { event ->
+            if (event is NtfyStreamClient.Event.Message) notifier.notify(event.tickle)
+        }
+    }
+
+    override fun onDestroy() {
+        connectionJob?.cancel()
+        scope.cancel()
+        super.onDestroy()
+    }
+
+    override fun onBind(intent: Intent?): IBinder? = null
+
+    companion object {
+        private const val NOTIFICATION_ID = 42
+
+        fun start(context: Context) {
+            val intent = Intent(context, PushService::class.java)
+            context.startForegroundService(intent)
+        }
+
+        fun stop(context: Context) {
+            context.stopService(Intent(context, PushService::class.java))
+        }
+    }
+}

app/src/main/java/com/runicgateway/app/core/push/PushStreams.kt

@@ -0,0 +1,39 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.core.push
+
+import androidx.annotation.StringRes
+import com.runicgateway.app.R
+
+/**
+ * The known push stream ids (mirrors the backend catalog in
+ * `config/notificationStreams.js`) and their localized notification titles.
+ * The subscribable catalog itself is fetched from
+ * `GET /auth/me/notifications/streams`; this fixed set is only what the receiver
+ * needs to title a content-free tickle without a network round-trip (§11).
+ */
+object PushStreams {
+    const val NEWS_POST = "news.post"
+    const val SERVER_STATUS = "server.status"
+    const val IDOC_WARNING = "idoc.warning"
+    const val CHAMP_START = "champ.start"
+    const val GOVERNOR_ELECTION = "governor.election"
+    const val VENDOR_SALE = "vendor.sale"
+    const val HOUSE_IDOC = "house.idoc"
+    const val ACCOUNT_LOGIN = "account.login"
+
+    /** A short, localized notification title for [streamId]; a generic fallback otherwise. */
+    @StringRes
+    fun titleRes(streamId: String): Int = when (streamId) {
+        NEWS_POST -> R.string.push_stream_news_post
+        SERVER_STATUS -> R.string.push_stream_server_status
+        IDOC_WARNING -> R.string.push_stream_idoc_warning
+        CHAMP_START -> R.string.push_stream_champ_start
+        GOVERNOR_ELECTION -> R.string.push_stream_governor_election
+        VENDOR_SALE -> R.string.push_stream_vendor_sale
+        HOUSE_IDOC -> R.string.push_stream_house_idoc
+        ACCOUNT_LOGIN -> R.string.push_stream_account_login
+        else -> R.string.push_stream_generic
+    }
+}

app/src/main/java/com/runicgateway/app/core/push/PushTickle.kt

@@ -0,0 +1,54 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.core.push
+
+import kotlinx.serialization.Serializable
+import kotlinx.serialization.json.Json
+import kotlinx.serialization.json.JsonNull
+import kotlinx.serialization.json.JsonObject
+import kotlinx.serialization.json.jsonPrimitive
+
+/**
+ * The content-free push tickle the backend publishes (PLAN.md §11): `{ stream, ref }`
+ * and nothing sensitive. [ref] is an opaque hint (a serial / city / timestamp) the
+ * app *could* use to pull real content over the authenticated API; v1 just deep-links
+ * to the stream's screen, so it is carried but not otherwise interpreted.
+ */
+@Serializable
+data class PushTickle(
+    val stream: String,
+    val ref: String? = null,
+)
+
+/**
+ * Parse a tickle out of an ntfy SSE `data:` frame. ntfy wraps our published body in
+ * its own envelope — `{ event, topic, message, … }` — where `message` is the exact
+ * string we POSTed (our `{ stream, ref }` JSON). Only `event == "message"` frames
+ * carry a payload; `open` / `keepalive` frames return null, as does any malformed or
+ * unrecognized body (dropped, never thrown — §7). Pure + `internal` for unit testing.
+ */
+internal fun parseNtfyTickle(json: Json, data: String): PushTickle? {
+    val trimmed = data.trim()
+    if (trimmed.isEmpty() || trimmed.startsWith(":")) return null
+    return try {
+        val envelope = json.parseToJsonElement(trimmed) as? JsonObject ?: return null
+        val event = envelope["event"]?.jsonPrimitive?.content
+        // ntfy lifecycle frames ("open", "keepalive", "poll_request") carry no message.
+        if (event != null && event != "message") return null
+        val messageEl = envelope["message"] ?: return null
+        if (messageEl is JsonNull) return null
+        val message = messageEl.jsonPrimitive.content
+        decodeTickle(json, message)
+    } catch (_: Exception) {
+        null
+    }
+}
+
+/** Decode our own `{ stream, ref }` body; a blank/missing stream is not a tickle. */
+internal fun decodeTickle(json: Json, body: String): PushTickle? = try {
+    val tickle = json.decodeFromString(PushTickle.serializer(), body.trim())
+    tickle.takeIf { it.stream.isNotBlank() }
+} catch (_: Exception) {
+    null
+}

app/src/main/java/com/runicgateway/app/data/api/MeApi.kt

@@ -0,0 +1,55 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.data.api
+
+import com.runicgateway.app.data.api.dto.ChangePasswordRequest
+import com.runicgateway.app.data.api.dto.ChangeUsernameRequest
+import com.runicgateway.app.data.api.dto.LinkedIdentityDto
+import com.runicgateway.app.data.api.dto.PlayerAccountDto
+import com.runicgateway.app.data.api.dto.TotpCodeRequest
+import com.runicgateway.app.data.api.dto.TotpSetupDto
+import com.runicgateway.app.data.api.dto.TotpStateDto
+import com.runicgateway.app.data.api.dto.UsernameResponse
+import retrofit2.http.Body
+import retrofit2.http.GET
+import retrofit2.http.HTTP
+import retrofit2.http.PATCH
+import retrofit2.http.POST
+import retrofit2.http.Path
+
+/**
+ * The role-agnostic self-service surface (PLAN.md §6.3, §6.4): account, credential
+ * changes, TOTP enrollment, and linked SSO identities under `/auth/me/account*`.
+ * The app calls these regardless of role and never touches `/admin`. Every call
+ * rides the main client, so [com.runicgateway.app.core.net.AuthInterceptor] attaches
+ * the bearer and [com.runicgateway.app.core.net.TokenAuthenticator] refreshes on 401.
+ */
+interface MeApi {
+
+    @GET("api/v1/auth/me/account")
+    suspend fun getAccount(): PlayerAccountDto
+
+    @PATCH("api/v1/auth/me/account/username")
+    suspend fun changeUsername(@Body body: ChangeUsernameRequest): UsernameResponse
+
+    @PATCH("api/v1/auth/me/account/password")
+    suspend fun changePassword(@Body body: ChangePasswordRequest): Unit
+
+    @POST("api/v1/auth/me/account/totp/setup")
+    suspend fun totpSetup(): TotpSetupDto
+
+    @POST("api/v1/auth/me/account/totp/enable")
+    suspend fun totpEnable(@Body body: TotpCodeRequest): TotpStateDto
+
+    @POST("api/v1/auth/me/account/totp/disable")
+    suspend fun totpDisable(@Body body: TotpCodeRequest): TotpStateDto
+
+    @GET("api/v1/auth/me/account/identities")
+    suspend fun identities(): List<LinkedIdentityDto>
+
+    // DELETE with no body — a plain @DELETE would suffice, but @HTTP keeps the
+    // path template explicit alongside the provider argument.
+    @HTTP(method = "DELETE", path = "api/v1/auth/me/account/identities/{provider}")
+    suspend fun unlinkIdentity(@Path("provider") provider: String): Unit
+}

app/src/main/java/com/runicgateway/app/data/api/NotificationsApi.kt

@@ -0,0 +1,43 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.data.api
+
+import com.runicgateway.app.data.api.dto.NotificationStreamsDto
+import com.runicgateway.app.data.api.dto.NotificationSubscriptionsDto
+import com.runicgateway.app.data.api.dto.PushDeviceDto
+import com.runicgateway.app.data.api.dto.RegisterDeviceRequest
+import retrofit2.http.Body
+import retrofit2.http.DELETE
+import retrofit2.http.GET
+import retrofit2.http.POST
+import retrofit2.http.PUT
+import retrofit2.http.Path
+
+/**
+ * The opt-in push surface under `/auth/me` (PLAN.md §11, M7 Part 2): device
+ * (endpoint) registration and per-user stream subscriptions. Every call rides the
+ * main client, so [com.runicgateway.app.core.net.AuthInterceptor] attaches the
+ * bearer and [com.runicgateway.app.core.net.TokenAuthenticator] refreshes on 401 —
+ * registration only ever succeeds while signed in.
+ */
+interface NotificationsApi {
+
+    @POST("api/v1/auth/me/devices")
+    suspend fun registerDevice(@Body body: RegisterDeviceRequest): PushDeviceDto
+
+    @GET("api/v1/auth/me/devices")
+    suspend fun listDevices(): List<PushDeviceDto>
+
+    @DELETE("api/v1/auth/me/devices/{id}")
+    suspend fun deleteDevice(@Path("id") id: Long): Unit
+
+    @GET("api/v1/auth/me/notifications/streams")
+    suspend fun streams(): NotificationStreamsDto
+
+    @GET("api/v1/auth/me/notifications/subscriptions")
+    suspend fun subscriptions(): NotificationSubscriptionsDto
+
+    @PUT("api/v1/auth/me/notifications/subscriptions")
+    suspend fun putSubscriptions(@Body body: NotificationSubscriptionsDto): NotificationSubscriptionsDto
+}

app/src/main/java/com/runicgateway/app/data/api/PlayerShardApi.kt

@@ -0,0 +1,59 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.data.api
+
+import com.runicgateway.app.data.api.dto.CharProfileDto
+import com.runicgateway.app.data.api.dto.CreateGameAccountRequest
+import com.runicgateway.app.data.api.dto.PlayerHouseDto
+import com.runicgateway.app.data.api.dto.RosterDto
+import com.runicgateway.app.data.api.dto.ShardLinkDto
+import com.runicgateway.app.data.api.dto.ShardLinkRequest
+import com.runicgateway.app.data.api.dto.ShardLinkResultDto
+import com.runicgateway.app.data.api.dto.VendorSaleDto
+import com.runicgateway.app.data.api.dto.VendorSnapshotDto
+import retrofit2.http.Body
+import retrofit2.http.GET
+import retrofit2.http.POST
+import retrofit2.http.Path
+
+/**
+ * A player's own game data + game-account linking (PLAN.md §6.3), over the
+ * bearer-gated `/player/shard/…` surface. Every read is ownership-checked
+ * server-side; a `503` means the shard/sidecar is down → the UI renders "offline,
+ * retry" (§7). All reads ride the main authed client (bearer + refresh-on-401).
+ */
+interface PlayerShardApi {
+
+    /** Confirm an in-game `[link` one-time code, tagging the game account to the user. */
+    @POST("api/v1/player/shard/link")
+    suspend fun link(@Body body: ShardLinkRequest): ShardLinkResultDto
+
+    /** Provision a game account (hybrid signup) and auto-link it to the caller. */
+    @POST("api/v1/player/shard/account")
+    suspend fun createAccount(@Body body: CreateGameAccountRequest): ShardLinkResultDto
+
+    /** The caller's linked game accounts. */
+    @GET("api/v1/player/shard/accounts")
+    suspend fun accounts(): List<ShardLinkDto>
+
+    /** Character roster for a linked account. */
+    @GET("api/v1/player/shard/roster/{account}")
+    suspend fun roster(@Path("account") account: String): RosterDto
+
+    /** A character sheet — only for a character on the caller's linked account. */
+    @GET("api/v1/player/shard/char/{serial}")
+    suspend fun char(@Path("serial") serial: String): CharProfileDto
+
+    /** Player vendors for a linked account. */
+    @GET("api/v1/player/shard/vendors/{account}")
+    suspend fun vendors(@Path("account") account: String): VendorSnapshotDto
+
+    /** Recent player-vendor sales across the caller's linked accounts. */
+    @GET("api/v1/player/shard/sales")
+    suspend fun sales(): List<VendorSaleDto>
+
+    /** The caller's own houses (home/decay status). */
+    @GET("api/v1/player/shard/houses")
+    suspend fun houses(): List<PlayerHouseDto>
+}

app/src/main/java/com/runicgateway/app/data/api/SsoApi.kt

@@ -0,0 +1,40 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.data.api
+
+import com.runicgateway.app.data.api.dto.MobileSsoExchangeRequest
+import com.runicgateway.app.data.api.dto.MobileTokenResponse
+import com.runicgateway.app.data.api.dto.SsoProviderDto
+import retrofit2.Response
+import retrofit2.http.Body
+import retrofit2.http.GET
+import retrofit2.http.Headers
+import retrofit2.http.POST
+
+/**
+ * The native SSO bridge surface (PLAN.md §4.2, M9). Discovery lists the shard's
+ * enabled providers; exchange trades a callback authorization code (+ its PKCE
+ * verifier) for the same bearer pair as `/auth/mobile/login`.
+ *
+ * The redirect leg (`/auth/mobile/sso/start`) is **not** here — it is opened in a
+ * Custom Tab as a URL (the browser follows the 302 through the IdP), not called as
+ * an XHR. See [com.runicgateway.app.core.auth.sso.SsoAuthManager].
+ *
+ * Exchange is tagged [com.runicgateway.app.core.net.Http.NO_SESSION_HEADER]: it
+ * carries no bearer (the user isn't signed in yet) and a `401` (bad/expired code or
+ * PKCE mismatch) must never be misread as an expired session or trip the refresh
+ * [com.runicgateway.app.core.net.TokenAuthenticator]. It returns a raw [Response]
+ * so the caller can distinguish `401` from other failures.
+ */
+interface SsoApi {
+
+    /** Public discovery — the enabled providers to render login buttons for. */
+    @GET("api/v1/auth/providers")
+    suspend fun providers(): List<SsoProviderDto>
+
+    // Literal header value required by Retrofit @Headers; matches Http.NO_SESSION_HEADER.
+    @Headers("X-Runic-No-Session: 1")
+    @POST("api/v1/auth/mobile/sso/exchange")
+    suspend fun exchange(@Body body: MobileSsoExchangeRequest): Response<MobileTokenResponse>
+}

app/src/main/java/com/runicgateway/app/data/api/dto/AccountDto.kt

@@ -0,0 +1,68 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.data.api.dto
+
+import kotlinx.serialization.Serializable
+
+/**
+ * The role-agnostic self-service ("me") wire shapes (PLAN.md §6.3, §6.4). Field
+ * names match the backend's `account.controller` handlers exactly, surfaced for
+ * the app under `/auth/me/account*`. Every DTO ignores unknown keys (NetworkModule's
+ * lenient Json), so additive backend fields are safe (recorded for M1).
+ */
+
+/** `GET /auth/me/account` — the current account (any role). */
+@Serializable
+data class PlayerAccountDto(
+    val id: Long = 0,
+    val username: String = "",
+    val role: String = "",
+    val email: String? = null,
+    val status: String? = null,
+    val totp_enabled: Boolean = false,
+    /** False for an SSO-provisioned account that has not set a password yet. */
+    val has_password: Boolean = false,
+)
+
+/** `PATCH /auth/me/account/username` body. */
+@Serializable
+data class ChangeUsernameRequest(val username: String)
+
+/** The `{ username }` returned by a successful username change. */
+@Serializable
+data class UsernameResponse(val username: String = "")
+
+/**
+ * `PATCH /auth/me/account/password` body. [currentPassword] is omitted only for an
+ * SSO-provisioned account setting its initial password (has_password == false).
+ */
+@Serializable
+data class ChangePasswordRequest(
+    val newPassword: String,
+    val currentPassword: String? = null,
+)
+
+/** Enrollment material from `POST /auth/me/account/totp/setup`. */
+@Serializable
+data class TotpSetupDto(
+    val otpauthUrl: String? = null,
+    /** QR code as a `data:image/png;base64,…` URL. */
+    val qr: String? = null,
+)
+
+/** `POST /auth/me/account/totp/enable|disable` body — a current authenticator code. */
+@Serializable
+data class TotpCodeRequest(val code: String)
+
+/** Result of enabling/disabling 2FA. */
+@Serializable
+data class TotpStateDto(val totp_enabled: Boolean = false)
+
+/** A linked external identity (`GET /auth/me/account/identities`). */
+@Serializable
+data class LinkedIdentityDto(
+    val provider: String = "",
+    val email: String? = null,
+    val linked_at: String? = null,
+)

app/src/main/java/com/runicgateway/app/data/api/dto/NotificationsDto.kt

@@ -0,0 +1,67 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.data.api.dto
+
+import kotlinx.serialization.Serializable
+
+/**
+ * Wire shapes for the opt-in push surface under `/auth/me` (PLAN.md §11, M7
+ * Part 2). Field names match the backend's `notifications.controller` /
+ * `pushDevices.model` exactly; every DTO ignores unknown keys (NetworkModule's
+ * lenient Json), so additive backend fields are safe (recorded for M1).
+ */
+
+/**
+ * `POST /auth/me/devices` body. [endpoint] is the ntfy topic URL the app's
+ * embedded distributor owns (`https://<ntfy-host>/<topic>`); the backend
+ * SSRF-validates it is HTTPS on the shard's allow-set before storing. [transport]
+ * is `unifiedpush` for the direct-ntfy relay (fcm reserved for a future flavor).
+ */
+@Serializable
+data class RegisterDeviceRequest(
+    val endpoint: String,
+    val transport: String = "unifiedpush",
+    val platform: String? = null,
+)
+
+/** `POST/GET /auth/me/devices` — one registered device (endpoint) for this user. */
+@Serializable
+data class PushDeviceDto(
+    val id: Long = 0,
+    val transport: String = "",
+    val endpoint: String = "",
+    val platform: String? = null,
+    val createdAt: String? = null,
+    val lastSeenAt: String? = null,
+)
+
+/**
+ * One subscribable stream from `GET /auth/me/notifications/streams`. A [personal]
+ * stream is delivered only to the owning user and [requiresLinkedAccount] — the app
+ * greys its toggle until a game account is linked (§11).
+ */
+@Serializable
+data class NotificationStreamDto(
+    val id: String = "",
+    val label: String = "",
+    val description: String = "",
+    val personal: Boolean = false,
+    val requiresLinkedAccount: Boolean = false,
+)
+
+/** `GET /auth/me/notifications/streams` — the catalog. */
+@Serializable
+data class NotificationStreamsDto(
+    val streams: List<NotificationStreamDto> = emptyList(),
+)
+
+/**
+ * `GET/PUT /auth/me/notifications/subscriptions` — the user's opted-in stream ids.
+ * PUT replaces the full set; unknown ids are dropped server-side and the stored set
+ * echoed back.
+ */
+@Serializable
+data class NotificationSubscriptionsDto(
+    val streams: List<String> = emptyList(),
+)

app/src/main/java/com/runicgateway/app/data/api/dto/PlayerShardDto.kt

@@ -0,0 +1,224 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.data.api.dto
+
+import kotlinx.serialization.Serializable
+import kotlinx.serialization.json.JsonObject
+
+/**
+ * DTOs for a player's OWN game data (PLAN.md §6.3), read over the bearer-gated
+ * `/player/shard/…` surface. The roster / char / vendor reads return the sidecar
+ * payload verbatim (a permissive object), so only the fields the app renders are
+ * modeled — unknown keys are ignored by the JSON parser (matching the website's
+ * `CharacterSheet.jsx` / `GameAccounts.jsx` and `docs/link/INTEGRATION.md` §5).
+ * Presentation is text-only for v1 (no item icons / paperdoll).
+ *
+ * In-game serials are hex strings (e.g. "0x24C"), unlike the numeric serials on
+ * the public boards — these are separate endpoints with separate shapes.
+ */
+
+// ── Game-account linking ─────────────────────────────────────────────────────
+
+/** `GET /player/shard/accounts` — a linked in-game account. */
+@Serializable
+data class ShardLinkDto(
+    val account: String = "",
+    val userId: Long? = null,
+    val charName: String? = null,
+    val linkedAt: String? = null,
+)
+
+/** `POST /player/shard/link` body — the one-time code shown by `[link` in game. */
+@Serializable
+data class ShardLinkRequest(val code: String)
+
+/** `POST /player/shard/link` result — the confirmed link. */
+@Serializable
+data class ShardLinkResultDto(
+    val linked: Boolean = false,
+    val account: String? = null,
+)
+
+/** `POST /player/shard/account` (hybrid signup) body. */
+@Serializable
+data class CreateGameAccountRequest(
+    val account: String,
+    val password: String,
+)
+
+// ── Character roster + sheet ─────────────────────────────────────────────────
+
+/** `GET /player/shard/roster/:account` — the account's characters (incl. offline). */
+@Serializable
+data class RosterDto(
+    val acct: String? = null,
+    val chars: List<RosterCharDto> = emptyList(),
+)
+
+/** One character in a roster; the picker fetches the full sheet on demand. */
+@Serializable
+data class RosterCharDto(
+    val slot: Int? = null,
+    val serial: String = "",
+    val name: String? = null,
+    val body: Int? = null,
+    val online: Boolean = false,
+)
+
+/**
+ * `GET /player/shard/char/:serial` — a character sheet. `guild` / `governorOf` are
+ * best-effort cross-links the backend decorates in (never fail the sheet).
+ */
+@Serializable
+data class CharProfileDto(
+    val serial: String? = null,
+    val name: String? = null,
+    val title: String? = null,
+    val online: Boolean = false,
+    val acct: String? = null,
+    val stats: CharStatsDto? = null,
+    val skills: List<SkillDto> = emptyList(),
+    val equipment: List<EquipmentDto> = emptyList(),
+    val titles: TitlesDto? = null,
+    val guild: GuildRefDto? = null,
+    val governorOf: List<String> = emptyList(),
+)
+
+@Serializable
+data class CharStatsDto(
+    val str: Int? = null,
+    val dex: Int? = null,
+    val int: Int? = null,
+    val hits: Int? = null,
+    val hitsMax: Int? = null,
+    val mana: Int? = null,
+    val manaMax: Int? = null,
+    val stam: Int? = null,
+    val stamMax: Int? = null,
+    val resist: ResistDto? = null,
+)
+
+@Serializable
+data class ResistDto(
+    val phys: Int? = null,
+    val fire: Int? = null,
+    val cold: Int? = null,
+    val pois: Int? = null,
+    val energy: Int? = null,
+)
+
+/**
+ * A skill line. `base` is the trained value, `value` includes item/temp bonuses,
+ * `cap` is the cap — do NOT assume base ≤ cap (GM chars exceed it). Doubles, as the
+ * shard reports tenths.
+ */
+@Serializable
+data class SkillDto(
+    val n: String? = null,
+    val base: Double? = null,
+    val value: Double? = null,
+    val cap: Double? = null,
+)
+
+/**
+ * An equipped item. Names are usually clilocs (numeric), not strings, and the app
+ * ships no cliloc table, so the text-only sheet renders layer + id + hue + mods.
+ * [mods] is a flattened map of non-zero AOS attributes (empty for plain items);
+ * kept as a raw object since values may be numbers or strings.
+ */
+@Serializable
+data class EquipmentDto(
+    val serial: String? = null,
+    val layer: String? = null,
+    val itemId: Int? = null,
+    val hue: Int? = null,
+    val mods: JsonObject? = null,
+)
+
+/**
+ * Display titles (Protocol 2.0). `selected` is the index into `reward` currently
+ * shown (-1 if none); `reward` entries may be a cliloc number-as-string or a
+ * literal — numeric ones are skipped without a cliloc table (as the website does).
+ */
+@Serializable
+data class TitlesDto(
+    val selected: Int? = null,
+    val reward: List<String> = emptyList(),
+    val fameKarma: String? = null,
+    val skill: String? = null,
+)
+
+/** The guild a character leads (cross-linked from board data). */
+@Serializable
+data class GuildRefDto(
+    val name: String? = null,
+    val abbr: String? = null,
+)
+
+// ── Player vendors + sales ───────────────────────────────────────────────────
+
+/** `GET /player/shard/vendors/:account` — every player vendor on the account. */
+@Serializable
+data class VendorSnapshotDto(
+    val acct: String? = null,
+    val vendors: List<VendorDto> = emptyList(),
+)
+
+@Serializable
+data class VendorDto(
+    val serial: String? = null,
+    val shopName: String? = null,
+    val holdGold: Long? = null,
+    val ownerSerial: String? = null,
+    val map: String? = null,
+    val x: Int? = null,
+    val y: Int? = null,
+    val listings: List<VendorListingDto> = emptyList(),
+)
+
+/** A single vendor listing. Item names are clilocs (see [EquipmentDto]); text-only. */
+@Serializable
+data class VendorListingDto(
+    val serial: String? = null,
+    val itemId: Int? = null,
+    val amount: Int? = null,
+    val price: Long? = null,
+    val forSale: Boolean = false,
+)
+
+/** `GET /player/shard/sales` — a player-vendor sale, visible only to the owner. */
+@Serializable
+data class VendorSaleDto(
+    /** Sale time, epoch ms. */
+    val t: Long? = null,
+    val itemType: String? = null,
+    val amount: Int? = null,
+    val price: Long? = null,
+    val commission: Int? = null,
+    val ownerAcct: String? = null,
+)
+
+// ── Player houses ────────────────────────────────────────────────────────────
+
+/**
+ * `GET /player/shard/houses` — the caller's OWN houses, with full decay/IDOC
+ * detail (their own property). Serial is a hex string here.
+ */
+@Serializable
+data class PlayerHouseDto(
+    val serial: String = "",
+    val stage: String? = null,
+    val map: String? = null,
+    val x: Int? = null,
+    val y: Int? = null,
+    val z: Int? = null,
+    val region: String? = null,
+    val name: String? = null,
+    val ownerSerial: String? = null,
+    val ownerAcct: String? = null,
+    val builtOn: String? = null,
+    val lastRefreshed: String? = null,
+    val isIdoc: Boolean = false,
+    val updatedAt: String? = null,
+)

app/src/main/java/com/runicgateway/app/data/api/dto/PublicDto.kt

@@ -55,6 +55,17 @@ data class RegistrationFlagsDto(
     val sso: Boolean = false,
 )
 
+/**
+ * Push-notification relay config (M7). [ntfyUrl] is the client-facing ntfy base
+ * URL the app's embedded distributor registers its device topic against; null (or
+ * absent, on an older backend) means push isn't configured for this shard and the
+ * Notifications screen shows it as unavailable.
+ */
+@Serializable
+data class PushConfigDto(
+    val ntfyUrl: String? = null,
+)
+
 /**
  * `GET /public/settings` — whitelisted settings + branding. Only the keys the
  * app consumes are modeled; other whitelisted keys are ignored.
@@ -67,4 +78,6 @@ data class SettingsDto(
     val registration: RegistrationFlagsDto = RegistrationFlagsDto(),
     val gameAccountSignup: Boolean = false,
     val brand: BrandDto = BrandDto(),
+    /** Push relay config (M7); default (null ntfyUrl) on a backend that predates it. */
+    val push: PushConfigDto = PushConfigDto(),
 )

app/src/main/java/com/runicgateway/app/data/api/dto/SsoDto.kt

@@ -0,0 +1,42 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.data.api.dto
+
+import kotlinx.serialization.SerialName
+import kotlinx.serialization.Serializable
+
+/**
+ * Wire shapes for the Mobile SSO Authorization Bridge (PLAN.md §4.2, M9). The
+ * success payload of `/auth/mobile/sso/exchange` is the shared [MobileTokenResponse]
+ * (same pair as `/auth/mobile/login`) — this file only adds the two shapes unique
+ * to the bridge. Every DTO ignores unknown keys (NetworkModule's lenient Json), so
+ * additive backend fields stay safe (§8).
+ */
+
+/**
+ * One entry of `GET /auth/providers` — public discovery, never secrets. [icon] is
+ * the provider kind (`google` | `discord` | `oidc` | `oauth2`); the app renders a
+ * button per provider from this list rather than hardcoding a set. [loginUrl] is
+ * the *website* start path (unused by the app, which builds its own
+ * `/auth/mobile/sso/start` URL); kept so the shape matches the backend exactly.
+ */
+@Serializable
+data class SsoProviderDto(
+    val id: String,
+    val name: String,
+    val icon: String? = null,
+    val loginUrl: String? = null,
+    val priority: Int? = null,
+)
+
+/**
+ * `POST /auth/mobile/sso/exchange` body — the one-time authorization code from the
+ * callback deep link plus the PKCE verifier stashed at `/start` (Layer B). Wire
+ * name is snake_case to match the backend's `{ code, code_verifier }`.
+ */
+@Serializable
+data class MobileSsoExchangeRequest(
+    val code: String,
+    @SerialName("code_verifier") val codeVerifier: String,
+)

app/src/main/java/com/runicgateway/app/data/repository/AccountRepository.kt

@@ -0,0 +1,51 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.data.repository
+
+import com.runicgateway.app.core.result.ApiResult
+import com.runicgateway.app.core.result.safeApiCall
+import com.runicgateway.app.data.api.MeApi
+import com.runicgateway.app.data.api.dto.ChangePasswordRequest
+import com.runicgateway.app.data.api.dto.ChangeUsernameRequest
+import com.runicgateway.app.data.api.dto.LinkedIdentityDto
+import com.runicgateway.app.data.api.dto.PlayerAccountDto
+import com.runicgateway.app.data.api.dto.TotpCodeRequest
+import com.runicgateway.app.data.api.dto.TotpSetupDto
+import com.runicgateway.app.data.api.dto.TotpStateDto
+import com.runicgateway.app.data.api.dto.UsernameResponse
+import javax.inject.Inject
+import javax.inject.Singleton
+
+/**
+ * Self-service account management over the role-agnostic `/auth/me/account*`
+ * surface (PLAN.md §6.3, §6.4). Every call returns a typed [ApiResult] so the
+ * screens can map known statuses (409 taken, 400 wrong password / invalid code,
+ * 429 rate-limited) to friendly copy without a repository ever throwing (§7).
+ */
+@Singleton
+class AccountRepository @Inject constructor(
+    private val api: MeApi,
+) {
+    suspend fun getAccount(): ApiResult<PlayerAccountDto> = safeApiCall { api.getAccount() }
+
+    suspend fun changeUsername(username: String): ApiResult<UsernameResponse> =
+        safeApiCall { api.changeUsername(ChangeUsernameRequest(username)) }
+
+    /** [currentPassword] is null only for an SSO account setting its first password. */
+    suspend fun changePassword(newPassword: String, currentPassword: String?): ApiResult<Unit> =
+        safeApiCall { api.changePassword(ChangePasswordRequest(newPassword, currentPassword)) }
+
+    suspend fun totpSetup(): ApiResult<TotpSetupDto> = safeApiCall { api.totpSetup() }
+
+    suspend fun totpEnable(code: String): ApiResult<TotpStateDto> =
+        safeApiCall { api.totpEnable(TotpCodeRequest(code)) }
+
+    suspend fun totpDisable(code: String): ApiResult<TotpStateDto> =
+        safeApiCall { api.totpDisable(TotpCodeRequest(code)) }
+
+    suspend fun identities(): ApiResult<List<LinkedIdentityDto>> = safeApiCall { api.identities() }
+
+    suspend fun unlinkIdentity(provider: String): ApiResult<Unit> =
+        safeApiCall { api.unlinkIdentity(provider) }
+}

app/src/main/java/com/runicgateway/app/data/repository/AuthRepository.kt

@@ -4,10 +4,13 @@
 package com.runicgateway.app.data.repository
 
 import com.runicgateway.app.core.auth.SessionManager
+import com.runicgateway.app.core.push.PushManager
 import com.runicgateway.app.data.api.AuthApi
+import com.runicgateway.app.data.api.SsoApi
 import com.runicgateway.app.data.api.dto.MobileLoginRequest
 import com.runicgateway.app.data.api.dto.MobileLogoutRequest
 import com.runicgateway.app.data.api.dto.MobileTokenResponse
+import com.runicgateway.app.data.api.dto.SsoProviderDto
 import com.runicgateway.app.data.api.dto.TotpRequiredError
 import kotlinx.coroutines.CancellationException
 import kotlinx.serialization.json.Json
@@ -25,10 +28,25 @@ import javax.inject.Singleton
 @Singleton
 class AuthRepository @Inject constructor(
     private val authApi: AuthApi,
+    private val ssoApi: SsoApi,
     private val sessionManager: SessionManager,
+    private val pushManager: PushManager,
     private val json: Json,
 ) {
 
+    /**
+     * The shard's enabled SSO providers for the native login buttons (§4.2). Public
+     * discovery, never secrets. Returns an empty list on any failure — the login
+     * screen then keeps the website hand-off fallback rather than showing nothing.
+     */
+    suspend fun ssoProviders(): List<SsoProviderDto> = try {
+        ssoApi.providers()
+    } catch (e: CancellationException) {
+        throw e
+    } catch (_: Exception) {
+        emptyList()
+    }
+
     /** Outcome of a login attempt (§4.1). */
     sealed interface LoginResult {
         data object Success : LoginResult
@@ -75,6 +93,16 @@ class AuthRepository @Inject constructor(
      * network call fails, so the user is always signed out locally.
      */
     suspend fun logout(allDevices: Boolean = false) {
+        // Deregister this device's push endpoint while the bearer is still valid, so
+        // no orphan device row is left behind (§11). Keeps the opt-in intent so push
+        // resumes on the next sign-in; best-effort, never blocks the logout.
+        try {
+            pushManager.deregisterDevice()
+        } catch (e: CancellationException) {
+            throw e
+        } catch (_: Exception) {
+            // Ignore — local session teardown proceeds regardless.
+        }
         val refreshToken = sessionManager.currentRefreshToken()
         try {
             authApi.logout(MobileLogoutRequest(refreshToken = refreshToken, all = allDevices))

app/src/main/java/com/runicgateway/app/data/repository/ConnectionRepository.kt

@@ -26,6 +26,7 @@ class ConnectionRepository @Inject constructor(
     private val prefs: ServerPreferences,
     private val baseUrlHolder: BaseUrlHolder,
     private val sessionManager: SessionManager,
+    private val pushManager: com.runicgateway.app.core.push.PushManager,
     private val config: com.runicgateway.app.core.AppConfig,
 ) {
 
@@ -36,6 +37,13 @@ class ConnectionRepository @Inject constructor(
 
         /** Reachable and 2xx, but not a Runic Gateway backend (wrong version identity). */
         data object NotRunicGateway : ProbeResult
+
+        /**
+         * A Runic Gateway backend, but speaking an API version this app build does
+         * not support (§3 version guard) — refuse rather than mis-render. [serverApi]
+         * is what the site reported; [supportedApi] is what this app speaks.
+         */
+        data class VersionMismatch(val serverApi: String, val supportedApi: String) : ProbeResult
         data class ServerError(val status: Int) : ProbeResult
         data class Unreachable(val cause: Throwable) : ProbeResult
     }
@@ -68,14 +76,15 @@ class ConnectionRepository @Inject constructor(
             ?: return ProbeResult.InvalidUrl(ServerUrl.Reason.MALFORMED)
 
         return when (val result = safeApiCall { api.probeStatus(statusUrl) }) {
-            is ApiResult.Ok -> {
-                if (!result.data.version.service.equals(RUNIC_SERVICE_ID, ignoreCase = true)) {
-                    ProbeResult.NotRunicGateway
-                } else {
+            is ApiResult.Ok -> when (val verdict = evaluateVersion(result.data.version)) {
+                is VersionVerdict.Ok -> {
                     prefs.setBaseUrl(normalized.toString())
                     baseUrlHolder.set(normalized)
                     ProbeResult.Success(result.data)
                 }
+                is VersionVerdict.NotRunicGateway -> ProbeResult.NotRunicGateway
+                is VersionVerdict.Mismatch ->
+                    ProbeResult.VersionMismatch(serverApi = verdict.serverApi, supportedApi = SUPPORTED_API)
             }
             is ApiResult.HttpError -> ProbeResult.ServerError(result.status)
             is ApiResult.NetworkError -> ProbeResult.Unreachable(result.cause)
@@ -88,12 +97,51 @@ class ConnectionRepository @Inject constructor(
      * signed-out state against the new host.
      */
     suspend fun disconnect() {
+        // Deregister the push endpoint on the current (old) host while still authed,
+        // then clear the shard's ntfy URL — the new host advertises its own (§11).
+        try {
+            pushManager.deregisterDevice()
+        } catch (_: Exception) {
+            // Best-effort; the reset proceeds regardless.
+        }
+        pushManager.setNtfyUrl(null)
         sessionManager.onSignedOut()
         prefs.clear()
         baseUrlHolder.set(null)
     }
 
-    private companion object {
+    /** The pure outcome of inspecting a probed site's [VersionDto] (§3 version guard). */
+    internal sealed interface VersionVerdict {
+        data object Ok : VersionVerdict
+        data object NotRunicGateway : VersionVerdict
+        data class Mismatch(val serverApi: String) : VersionVerdict
+    }
+
+    internal companion object {
         const val RUNIC_SERVICE_ID = "runic-gateway"
+
+        /** The backend API major version this app build speaks (matches `/public/version` `api`). */
+        const val SUPPORTED_API = "v1"
+
+        /**
+         * Decide whether a probed site is a Runic Gateway backend this app can talk
+         * to. Pure (no I/O) so it is unit-testable without a live site. Lenient on a
+         * blank `api` (an older backend that predates version surfacing); refuses only
+         * an API version we positively know we can't parse (e.g. a future `v2`).
+         */
+        fun evaluateVersion(
+            version: com.runicgateway.app.data.api.dto.VersionDto,
+            supportedApi: String = SUPPORTED_API,
+        ): VersionVerdict {
+            if (!version.service.trim().equals(RUNIC_SERVICE_ID, ignoreCase = true)) {
+                return VersionVerdict.NotRunicGateway
+            }
+            val serverApi = version.api.trim()
+            return when {
+                serverApi.isEmpty() -> VersionVerdict.Ok
+                serverApi.equals(supportedApi, ignoreCase = true) -> VersionVerdict.Ok
+                else -> VersionVerdict.Mismatch(serverApi)
+            }
+        }
     }
 }

app/src/main/java/com/runicgateway/app/data/repository/NotificationsRepository.kt

@@ -0,0 +1,40 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.data.repository
+
+import com.runicgateway.app.core.result.ApiResult
+import com.runicgateway.app.core.result.safeApiCall
+import com.runicgateway.app.data.api.NotificationsApi
+import com.runicgateway.app.data.api.dto.NotificationStreamsDto
+import com.runicgateway.app.data.api.dto.NotificationSubscriptionsDto
+import com.runicgateway.app.data.api.dto.PushDeviceDto
+import com.runicgateway.app.data.api.dto.RegisterDeviceRequest
+import javax.inject.Inject
+import javax.inject.Singleton
+
+/**
+ * Device registration + per-user stream subscriptions over the opt-in push surface
+ * (PLAN.md §11, M7 Part 2). Every call returns a typed [ApiResult] so the screen
+ * and the [com.runicgateway.app.core.push.PushManager] degrade gracefully — a `400`
+ * (endpoint off the shard's allow-set) or a down backend never throws (§7).
+ */
+@Singleton
+class NotificationsRepository @Inject constructor(
+    private val api: NotificationsApi,
+) {
+    suspend fun registerDevice(endpoint: String, platform: String?): ApiResult<PushDeviceDto> =
+        safeApiCall { api.registerDevice(RegisterDeviceRequest(endpoint = endpoint, platform = platform)) }
+
+    suspend fun listDevices(): ApiResult<List<PushDeviceDto>> = safeApiCall { api.listDevices() }
+
+    suspend fun deleteDevice(id: Long): ApiResult<Unit> = safeApiCall { api.deleteDevice(id) }
+
+    suspend fun streams(): ApiResult<NotificationStreamsDto> = safeApiCall { api.streams() }
+
+    suspend fun subscriptions(): ApiResult<NotificationSubscriptionsDto> =
+        safeApiCall { api.subscriptions() }
+
+    suspend fun setSubscriptions(streams: List<String>): ApiResult<NotificationSubscriptionsDto> =
+        safeApiCall { api.putSubscriptions(NotificationSubscriptionsDto(streams)) }
+}

app/src/main/java/com/runicgateway/app/data/repository/PlayerShardRepository.kt

@@ -0,0 +1,50 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.data.repository
+
+import com.runicgateway.app.core.result.ApiResult
+import com.runicgateway.app.core.result.safeApiCall
+import com.runicgateway.app.data.api.PlayerShardApi
+import com.runicgateway.app.data.api.dto.CharProfileDto
+import com.runicgateway.app.data.api.dto.CreateGameAccountRequest
+import com.runicgateway.app.data.api.dto.PlayerHouseDto
+import com.runicgateway.app.data.api.dto.RosterDto
+import com.runicgateway.app.data.api.dto.ShardLinkDto
+import com.runicgateway.app.data.api.dto.ShardLinkRequest
+import com.runicgateway.app.data.api.dto.ShardLinkResultDto
+import com.runicgateway.app.data.api.dto.VendorSaleDto
+import com.runicgateway.app.data.api.dto.VendorSnapshotDto
+import javax.inject.Inject
+import javax.inject.Singleton
+
+/**
+ * A player's own game data + game-account linking (PLAN.md §6.3), over the
+ * bearer-gated `/player/shard/…` surface. Every read returns a typed [ApiResult]
+ * so a down shard (`503`) renders as "offline, retry" and a not-linked account
+ * (`403`) is handled cleanly — the repository never throws for an expected
+ * failure (§7). Ownership is enforced server-side.
+ */
+@Singleton
+class PlayerShardRepository @Inject constructor(
+    private val api: PlayerShardApi,
+) {
+    suspend fun link(code: String): ApiResult<ShardLinkResultDto> =
+        safeApiCall { api.link(ShardLinkRequest(code)) }
+
+    suspend fun createAccount(account: String, password: String): ApiResult<ShardLinkResultDto> =
+        safeApiCall { api.createAccount(CreateGameAccountRequest(account, password)) }
+
+    suspend fun accounts(): ApiResult<List<ShardLinkDto>> = safeApiCall { api.accounts() }
+
+    suspend fun roster(account: String): ApiResult<RosterDto> = safeApiCall { api.roster(account) }
+
+    suspend fun char(serial: String): ApiResult<CharProfileDto> = safeApiCall { api.char(serial) }
+
+    suspend fun vendors(account: String): ApiResult<VendorSnapshotDto> =
+        safeApiCall { api.vendors(account) }
+
+    suspend fun sales(): ApiResult<List<VendorSaleDto>> = safeApiCall { api.sales() }
+
+    suspend fun houses(): ApiResult<List<PlayerHouseDto>> = safeApiCall { api.houses() }
+}

app/src/main/java/com/runicgateway/app/di/NetworkModule.kt

@@ -13,7 +13,11 @@ import com.runicgateway.app.core.net.TokenAuthenticator
 import com.runicgateway.app.core.net.UserAgentInterceptor
 import com.runicgateway.app.data.api.AuthApi
 import com.runicgateway.app.data.api.AuthRefreshApi
+import com.runicgateway.app.data.api.MeApi
+import com.runicgateway.app.data.api.NotificationsApi
+import com.runicgateway.app.data.api.PlayerShardApi
 import com.runicgateway.app.data.api.PublicApi
+import com.runicgateway.app.data.api.SsoApi
 import dagger.Module
 import dagger.Provides
 import dagger.hilt.InstallIn
@@ -93,6 +97,28 @@ object NetworkModule {
     @Singleton
     fun provideAuthApi(retrofit: Retrofit): AuthApi = retrofit.create(AuthApi::class.java)
 
+    /** Native SSO discovery + code exchange (§4.2, M9) — on the main client. */
+    @Provides
+    @Singleton
+    fun provideSsoApi(retrofit: Retrofit): SsoApi = retrofit.create(SsoApi::class.java)
+
+    /** Role-agnostic self-service (§6.4) — bearer-authed on the main client. */
+    @Provides
+    @Singleton
+    fun provideMeApi(retrofit: Retrofit): MeApi = retrofit.create(MeApi::class.java)
+
+    /** A player's own game data + linking (§6.3) — bearer-authed on the main client. */
+    @Provides
+    @Singleton
+    fun providePlayerShardApi(retrofit: Retrofit): PlayerShardApi =
+        retrofit.create(PlayerShardApi::class.java)
+
+    /** Opt-in push devices + subscriptions (§11, M7) — bearer-authed on the main client. */
+    @Provides
+    @Singleton
+    fun provideNotificationsApi(retrofit: Retrofit): NotificationsApi =
+        retrofit.create(NotificationsApi::class.java)
+
     /**
      * Token refresh runs on its own **bare** client — UA + host retargeting only,
      * no auth interceptor and no authenticator — so a refresh can never recurse

app/src/main/java/com/runicgateway/app/ui/AppViewModel.kt

@@ -6,6 +6,7 @@ package com.runicgateway.app.ui
 import androidx.lifecycle.ViewModel
 import androidx.lifecycle.viewModelScope
 import com.runicgateway.app.core.net.BaseUrlHolder
+import com.runicgateway.app.core.push.PushManager
 import com.runicgateway.app.core.result.ApiResult
 import com.runicgateway.app.data.api.dto.BrandDto
 import com.runicgateway.app.data.repository.ConnectionRepository
@@ -27,6 +28,7 @@ class AppViewModel @Inject constructor(
     private val connectionRepository: ConnectionRepository,
     private val settingsRepository: SettingsRepository,
     private val baseUrlHolder: BaseUrlHolder,
+    private val pushManager: PushManager,
 ) : ViewModel() {
 
     sealed interface AppState {
@@ -66,8 +68,16 @@ class AppViewModel @Inject constructor(
         }
     }
 
-    private suspend fun loadBrand(): BrandDto? =
-        (settingsRepository.getSettings() as? ApiResult.Ok)?.data?.brand
+    /**
+     * Load public settings for branding and feed the shard's push relay URL into the
+     * [PushManager] (§11) — its arrival is what lets push re-register after a restart
+     * or sign-in. Returns the brand block (null if settings couldn't be loaded).
+     */
+    private suspend fun loadBrand(): BrandDto? {
+        val settings = (settingsRepository.getSettings() as? ApiResult.Ok)?.data
+        pushManager.setNtfyUrl(settings?.push?.ntfyUrl)
+        return settings?.brand
+    }
 
     /**
      * Resolve a possibly site-relative asset path (branding logos, post images)

app/src/main/java/com/runicgateway/app/ui/RunicApp.kt

@@ -22,6 +22,7 @@ import androidx.compose.material3.NavigationDrawerItemDefaults
 import androidx.compose.material3.Scaffold
 import androidx.compose.material3.Text
 import androidx.compose.material3.TopAppBar
+import androidx.compose.material3.TopAppBarDefaults
 import androidx.compose.material3.rememberDrawerState
 import androidx.compose.runtime.Composable
 import androidx.compose.runtime.LaunchedEffect
@@ -29,7 +30,9 @@ import androidx.compose.runtime.getValue
 import androidx.compose.runtime.rememberCoroutineScope
 import androidx.compose.ui.Modifier
 import androidx.compose.ui.res.stringResource
+import androidx.compose.ui.text.style.TextOverflow
 import androidx.compose.ui.unit.dp
+import androidx.compose.ui.unit.sp
 import androidx.hilt.navigation.compose.hiltViewModel
 import androidx.lifecycle.compose.LifecycleResumeEffect
 import androidx.lifecycle.compose.collectAsStateWithLifecycle
@@ -53,7 +56,12 @@ import com.runicgateway.app.ui.navigation.Routes
 import com.runicgateway.app.ui.navigation.visibleEntries
 import com.runicgateway.app.ui.news.NewsScreen
 import com.runicgateway.app.ui.news.PostScreen
+import com.runicgateway.app.ui.notifications.NotificationsScreen
 import com.runicgateway.app.ui.page.PageScreen
+import com.runicgateway.app.ui.player.CharacterSheetScreen
+import com.runicgateway.app.ui.player.CharactersScreen
+import com.runicgateway.app.ui.player.MyHousesScreen
+import com.runicgateway.app.ui.player.VendorsScreen
 import com.runicgateway.app.ui.session.SessionViewModel
 import com.runicgateway.app.ui.shard.ChampsScreen
 import com.runicgateway.app.ui.shard.GovernorsScreen
@@ -68,6 +76,8 @@ import kotlinx.coroutines.launch
 /** Destinations that show the drawer (hamburger); others show a back arrow. */
 private val TOP_LEVEL_ROUTES = setOf(
     Routes.HOME, Routes.NEWS, Routes.WIKI, Routes.SHARD, Routes.CONTACT, Routes.PAGE, Routes.ACCOUNT,
+    Routes.NOTIFICATIONS,
+    Routes.PLAYER_CHARACTERS, Routes.PLAYER_VENDORS, Routes.PLAYER_HOUSES,
 )
 
 /**
@@ -83,6 +93,8 @@ fun RunicApp(
     brand: BrandDto?,
     onChangeServer: () -> Unit,
     modifier: Modifier = Modifier,
+    deepLinkStream: String? = null,
+    onDeepLinkConsumed: () -> Unit = {},
     sessionViewModel: SessionViewModel = hiltViewModel(),
 ) {
     val navController = rememberNavController()
@@ -97,6 +109,16 @@ fun RunicApp(
         onPauseOrDispose { }
     }
 
+    // A tapped push notification deep-links to its stream's screen (§11, item 7).
+    LaunchedEffect(deepLinkStream) {
+        val stream = deepLinkStream ?: return@LaunchedEffect
+        navController.navigate(Routes.forStream(stream)) {
+            popUpTo(Routes.HOME) { saveState = true }
+            launchSingleTop = true
+        }
+        onDeepLinkConsumed()
+    }
+
     val backStackEntry by navController.currentBackStackEntryAsState()
     val currentRoute = backStackEntry?.destination?.route
     val isTopLevel = currentRoute in TOP_LEVEL_ROUTES
@@ -106,11 +128,17 @@ fun RunicApp(
         drawerState = drawerState,
         gesturesEnabled = isTopLevel,
         drawerContent = {
-            ModalDrawerSheet {
+            ModalDrawerSheet(drawerContainerColor = MaterialTheme.colorScheme.surfaceVariant) {
+                val drawerItemColors = NavigationDrawerItemDefaults.colors(
+                    selectedContainerColor = MaterialTheme.colorScheme.secondaryContainer,
+                    selectedTextColor = MaterialTheme.colorScheme.onSecondaryContainer,
+                    unselectedTextColor = MaterialTheme.colorScheme.onSurface,
+                )
                 Spacer(Modifier.height(12.dp))
                 Text(
                     text = brand?.name?.takeIf { it.isNotBlank() } ?: stringResource(R.string.app_name),
                     style = MaterialTheme.typography.titleLarge,
+                    color = MaterialTheme.colorScheme.onSurface,
                     modifier = Modifier.padding(horizontal = 24.dp, vertical = 12.dp),
                 )
                 HorizontalDivider()
@@ -123,6 +151,7 @@ fun RunicApp(
                             scope.launch { drawerState.close() }
                             navController.navigateTopLevel(entry.route)
                         },
+                        colors = drawerItemColors,
                         modifier = Modifier.padding(NavigationDrawerItemDefaults.ItemPadding),
                     )
                 }
@@ -147,6 +176,7 @@ fun RunicApp(
                             navController.navigate(Routes.LOGIN)
                         }
                     },
+                    colors = drawerItemColors,
                     modifier = Modifier.padding(NavigationDrawerItemDefaults.ItemPadding),
                 )
                 NavigationDrawerItem(
@@ -156,6 +186,7 @@ fun RunicApp(
                         scope.launch { drawerState.close() }
                         onChangeServer()
                     },
+                    colors = drawerItemColors,
                     modifier = Modifier.padding(NavigationDrawerItemDefaults.ItemPadding),
                 )
             }
@@ -165,10 +196,19 @@ fun RunicApp(
             modifier = modifier,
             topBar = {
                 TopAppBar(
+                    colors = TopAppBarDefaults.topAppBarColors(
+                        containerColor = MaterialTheme.colorScheme.surfaceVariant,
+                        titleContentColor = MaterialTheme.colorScheme.onSurface,
+                        navigationIconContentColor = MaterialTheme.colorScheme.onSurface,
+                        actionIconContentColor = MaterialTheme.colorScheme.onSurface,
+                    ),
                     title = {
                         Text(
-                            brand?.name?.takeIf { it.isNotBlank() }
-                                ?: stringResource(R.string.app_name),
+                            text = (brand?.name?.takeIf { it.isNotBlank() }
+                                ?: stringResource(R.string.app_name)).uppercase(),
+                            style = MaterialTheme.typography.titleSmall.copy(letterSpacing = 1.2.sp),
+                            maxLines = 1,
+                            overflow = TextOverflow.Ellipsis,
                         )
                     },
                     navigationIcon = {
@@ -283,6 +323,53 @@ private fun RunicNavHost(
                 }
             }
         }
+        composable(Routes.NOTIFICATIONS) {
+            // Signed-in only; a sign-out (or demotion) sends the user home rather than
+            // leaving stale settings up. The backend gates every call regardless (§5).
+            when (session) {
+                is Session.SignedIn -> NotificationsScreen()
+                Session.SignedOut -> LaunchedEffect(Unit) { navController.navigateTopLevel(Routes.HOME) }
+            }
+        }
+
+        // ── Player game data (§6.3) — reached from the player-only menu groups.
+        // The server enforces the player gate on every call; these screens simply
+        // render 401/403/503 as clean states (§7).
+        composable(Routes.PLAYER_CHARACTERS) {
+            PlayerGate(session, navController) {
+                CharactersScreen(onOpenChar = { serial -> navController.navigate(Routes.playerChar(serial)) })
+            }
+        }
+        composable(
+            route = Routes.PLAYER_CHAR,
+            arguments = listOf(navArgument(Routes.Args.SERIAL) { type = NavType.StringType }),
+        ) {
+            CharacterSheetScreen()
+        }
+        composable(Routes.PLAYER_VENDORS) {
+            PlayerGate(session, navController) { VendorsScreen() }
+        }
+        composable(Routes.PLAYER_HOUSES) {
+            PlayerGate(session, navController) { MyHousesScreen() }
+        }
+    }
+}
+
+/**
+ * A UX guard for the player-only groups: while signed in, render [content]; if the
+ * session drops (sign-out, or a server-side demotion caught on resume, §4.3), send
+ * the user home instead of leaving a stale player screen up. The backend remains
+ * the authority — this only mirrors the menu's visibility rule.
+ */
+@Composable
+private fun PlayerGate(
+    session: Session,
+    navController: NavHostController,
+    content: @Composable () -> Unit,
+) {
+    when (session) {
+        is Session.SignedIn -> content()
+        Session.SignedOut -> LaunchedEffect(Unit) { navController.navigateTopLevel(Routes.HOME) }
     }
 }
 

app/src/main/java/com/runicgateway/app/ui/auth/AccountScreen.kt

@@ -3,30 +3,61 @@
  */
 package com.runicgateway.app.ui.auth
 
+import android.graphics.BitmapFactory
+import android.util.Base64
+import androidx.annotation.StringRes
+import androidx.compose.foundation.Image
 import androidx.compose.foundation.layout.Arrangement
 import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.Row
 import androidx.compose.foundation.layout.fillMaxSize
 import androidx.compose.foundation.layout.fillMaxWidth
 import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.layout.size
+import androidx.compose.foundation.rememberScrollState
+import androidx.compose.foundation.verticalScroll
+import androidx.compose.material3.Button
 import androidx.compose.material3.Card
+import androidx.compose.material3.HorizontalDivider
 import androidx.compose.material3.MaterialTheme
 import androidx.compose.material3.OutlinedButton
+import androidx.compose.material3.OutlinedTextField
 import androidx.compose.material3.Text
 import androidx.compose.material3.TextButton
 import androidx.compose.runtime.Composable
+import androidx.compose.runtime.getValue
+import androidx.compose.runtime.mutableStateOf
+import androidx.compose.runtime.remember
+import androidx.compose.runtime.saveable.rememberSaveable
+import androidx.compose.runtime.setValue
 import androidx.compose.ui.Alignment
 import androidx.compose.ui.Modifier
-import androidx.annotation.StringRes
+import androidx.compose.ui.graphics.asImageBitmap
 import androidx.compose.ui.res.stringResource
+import androidx.compose.ui.text.input.KeyboardType
+import androidx.compose.ui.text.input.PasswordVisualTransformation
 import androidx.compose.ui.unit.dp
+import androidx.compose.foundation.text.KeyboardOptions
+import androidx.compose.ui.graphics.ImageBitmap
+import androidx.hilt.navigation.compose.hiltViewModel
+import androidx.lifecycle.compose.collectAsStateWithLifecycle
 import com.runicgateway.app.R
 import com.runicgateway.app.core.auth.Role
+import com.runicgateway.app.data.api.dto.LinkedIdentityDto
+import com.runicgateway.app.data.api.dto.PlayerAccountDto
+import com.runicgateway.app.ui.UiState
+import com.runicgateway.app.ui.auth.AccountViewModel.Feedback
+import com.runicgateway.app.ui.auth.AccountViewModel.Section
+import com.runicgateway.app.ui.components.ErrorView
+import com.runicgateway.app.ui.components.LoadingView
+import com.runicgateway.app.ui.components.PillTone
+import com.runicgateway.app.ui.components.StatusPill
 
 /**
- * The signed-in account surface (PLAN.md §5, "My Account"). For the M3 functional
- * pass it shows the identity + role and the sign-out controls; full self-service
- * (change username/password, TOTP, linked identities via the `/auth/me` surface)
- * lands in M4 (§6.3).
+ * The signed-in account surface (PLAN.md §5, §6.3): identity + role, self-service
+ * over `/auth/me/account*` (change username/password, TOTP, linked identities),
+ * and the sign-out controls. Credential-provisioning flows (register / reset / SSO
+ * link) stay website hand-offs (§4.2) and are not rebuilt here.
  */
 @Composable
 fun AccountScreen(
@@ -35,49 +66,291 @@ fun AccountScreen(
     onSignOut: () -> Unit,
     onSignOutEverywhere: () -> Unit,
     modifier: Modifier = Modifier,
+    viewModel: AccountViewModel = hiltViewModel(),
 ) {
+    val state by viewModel.state.collectAsStateWithLifecycle()
+
     Column(
         modifier = modifier
             .fillMaxSize()
-            .padding(24.dp),
-        horizontalAlignment = Alignment.CenterHorizontally,
-        verticalArrangement = Arrangement.Top,
+            .verticalScroll(rememberScrollState())
+            .padding(16.dp),
     ) {
-        Card(modifier = Modifier.fillMaxWidth()) {
-            Column(Modifier.padding(20.dp)) {
-                Text(
-                    text = username,
-                    style = MaterialTheme.typography.titleLarge,
-                )
-                Text(
-                    text = roleLabel,
-                    style = MaterialTheme.typography.bodyMedium,
-                    color = MaterialTheme.colorScheme.onSurfaceVariant,
-                    modifier = Modifier.padding(top = 4.dp),
-                )
-            }
+        IdentityCard(username = username, roleLabel = roleLabel)
+
+        when (val account = state.account) {
+            is UiState.Loading -> LoadingView(Modifier.padding(top = 32.dp))
+            is UiState.Error -> ErrorView(account.kind, onRetry = viewModel::load, modifier = Modifier.padding(top = 32.dp))
+            is UiState.Success -> AccountSections(account.data, state, viewModel)
         }
 
-        OutlinedButton(
-            onClick = onSignOut,
-            modifier = Modifier
-                .fillMaxWidth()
-                .padding(top = 24.dp),
-        ) {
+        HorizontalDivider(Modifier.padding(vertical = 20.dp))
+
+        OutlinedButton(onClick = onSignOut, modifier = Modifier.fillMaxWidth()) {
             Text(stringResource(R.string.account_sign_out))
         }
-
         TextButton(
             onClick = onSignOutEverywhere,
-            modifier = Modifier
-                .fillMaxWidth()
-                .padding(top = 4.dp),
+            modifier = Modifier.fillMaxWidth().padding(top = 4.dp),
         ) {
             Text(stringResource(R.string.account_sign_out_all))
         }
     }
 }
 
+@Composable
+private fun IdentityCard(username: String, roleLabel: String) {
+    Card(Modifier.fillMaxWidth()) {
+        Column(Modifier.padding(20.dp)) {
+            Text(text = username, style = MaterialTheme.typography.titleLarge)
+            StatusPill(
+                text = roleLabel,
+                tone = PillTone.Info,
+                modifier = Modifier.padding(top = 8.dp),
+            )
+        }
+    }
+}
+
+@Composable
+private fun AccountSections(
+    account: PlayerAccountDto,
+    state: AccountViewModel.State,
+    viewModel: AccountViewModel,
+) {
+    UsernameSection(account, state, viewModel)
+    PasswordSection(account, state, viewModel)
+    TwoFactorSection(account, state, viewModel)
+    IdentitiesSection(state, viewModel)
+}
+
+@Composable
+private fun SectionCard(@StringRes titleRes: Int, content: @Composable () -> Unit) {
+    Card(Modifier.fillMaxWidth().padding(top = 12.dp)) {
+        Column(Modifier.padding(16.dp)) {
+            Text(stringResource(titleRes), style = MaterialTheme.typography.titleMedium)
+            content()
+        }
+    }
+}
+
+@Composable
+private fun UsernameSection(
+    account: PlayerAccountDto,
+    state: AccountViewModel.State,
+    viewModel: AccountViewModel,
+) {
+    var username by rememberSaveable(account.username) { mutableStateOf(account.username) }
+    SectionCard(R.string.account_username_title) {
+        OutlinedTextField(
+            value = username,
+            onValueChange = { username = it },
+            singleLine = true,
+            enabled = !state.busy,
+            label = { Text(stringResource(R.string.login_username)) },
+            modifier = Modifier.fillMaxWidth().padding(top = 12.dp),
+        )
+        Button(
+            onClick = { viewModel.changeUsername(username) },
+            enabled = !state.busy && username.trim() != account.username && username.trim().length >= 3,
+            modifier = Modifier.padding(top = 12.dp),
+        ) { Text(stringResource(R.string.account_username_action)) }
+        SectionFeedback(state.feedback, Section.USERNAME)
+    }
+}
+
+@Composable
+private fun PasswordSection(
+    account: PlayerAccountDto,
+    state: AccountViewModel.State,
+    viewModel: AccountViewModel,
+) {
+    val hasPassword = account.has_password
+    var current by rememberSaveable { mutableStateOf("") }
+    var next by rememberSaveable { mutableStateOf("") }
+    SectionCard(if (hasPassword) R.string.account_password_title else R.string.account_password_set_title) {
+        if (!hasPassword) {
+            Text(
+                stringResource(R.string.account_password_set_hint),
+                style = MaterialTheme.typography.bodySmall,
+                color = MaterialTheme.colorScheme.onSurfaceVariant,
+                modifier = Modifier.padding(top = 8.dp),
+            )
+        }
+        if (hasPassword) {
+            OutlinedTextField(
+                value = current,
+                onValueChange = { current = it },
+                singleLine = true,
+                enabled = !state.busy,
+                label = { Text(stringResource(R.string.account_password_current)) },
+                visualTransformation = PasswordVisualTransformation(),
+                keyboardOptions = KeyboardOptions(keyboardType = KeyboardType.Password),
+                modifier = Modifier.fillMaxWidth().padding(top = 12.dp),
+            )
+        }
+        OutlinedTextField(
+            value = next,
+            onValueChange = { next = it },
+            singleLine = true,
+            enabled = !state.busy,
+            label = { Text(stringResource(R.string.account_password_new)) },
+            visualTransformation = PasswordVisualTransformation(),
+            keyboardOptions = KeyboardOptions(keyboardType = KeyboardType.Password),
+            modifier = Modifier.fillMaxWidth().padding(top = 12.dp),
+        )
+        Button(
+            onClick = {
+                viewModel.changePassword(next, if (hasPassword) current else null)
+                current = ""
+                next = ""
+            },
+            enabled = !state.busy && next.length >= 8 && (!hasPassword || current.isNotBlank()),
+            modifier = Modifier.padding(top = 12.dp),
+        ) {
+            Text(stringResource(if (hasPassword) R.string.account_password_action else R.string.account_password_set_action))
+        }
+        SectionFeedback(state.feedback, Section.PASSWORD)
+    }
+}
+
+@Composable
+private fun TwoFactorSection(
+    account: PlayerAccountDto,
+    state: AccountViewModel.State,
+    viewModel: AccountViewModel,
+) {
+    var code by rememberSaveable { mutableStateOf("") }
+    SectionCard(R.string.account_totp_title) {
+        StatusPill(
+            text = stringResource(if (account.totp_enabled) R.string.account_totp_on else R.string.account_totp_off),
+            tone = if (account.totp_enabled) PillTone.Success else PillTone.Neutral,
+            modifier = Modifier.padding(top = 8.dp),
+        )
+
+        when {
+            // Enabled → offer disable via a current code.
+            account.totp_enabled -> {
+                CodeField(code, { code = it }, !state.busy)
+                Button(
+                    onClick = { viewModel.disableTotp(code); code = "" },
+                    enabled = !state.busy && code.isNotBlank(),
+                    modifier = Modifier.padding(top = 12.dp),
+                ) { Text(stringResource(R.string.account_totp_disable)) }
+            }
+            // Mid-enrollment → show QR + confirm.
+            state.totpSetup != null -> {
+                Text(
+                    stringResource(R.string.account_totp_scan),
+                    style = MaterialTheme.typography.bodySmall,
+                    color = MaterialTheme.colorScheme.onSurfaceVariant,
+                    modifier = Modifier.padding(top = 12.dp),
+                )
+                rememberQrBitmap(state.totpSetup.qr)?.let { bmp ->
+                    Image(
+                        bitmap = bmp,
+                        contentDescription = stringResource(R.string.account_totp_qr_desc),
+                        modifier = Modifier.padding(top = 12.dp).size(180.dp),
+                    )
+                }
+                CodeField(code, { code = it }, !state.busy)
+                Row(Modifier.padding(top = 12.dp), horizontalArrangement = Arrangement.spacedBy(8.dp)) {
+                    Button(
+                        onClick = { viewModel.enableTotp(code); code = "" },
+                        enabled = !state.busy && code.isNotBlank(),
+                    ) { Text(stringResource(R.string.account_totp_confirm)) }
+                    OutlinedButton(onClick = { viewModel.cancelTotp(); code = "" }, enabled = !state.busy) {
+                        Text(stringResource(R.string.account_totp_cancel))
+                    }
+                }
+            }
+            // Not enabled, not enrolling → start.
+            else -> {
+                Button(
+                    onClick = viewModel::beginTotp,
+                    enabled = !state.busy,
+                    modifier = Modifier.padding(top = 12.dp),
+                ) { Text(stringResource(R.string.account_totp_setup)) }
+            }
+        }
+        SectionFeedback(state.feedback, Section.TOTP)
+    }
+}
+
+@Composable
+private fun IdentitiesSection(state: AccountViewModel.State, viewModel: AccountViewModel) {
+    SectionCard(R.string.account_identities_title) {
+        if (state.identities.isEmpty()) {
+            Text(
+                stringResource(R.string.account_identities_empty),
+                style = MaterialTheme.typography.bodySmall,
+                color = MaterialTheme.colorScheme.onSurfaceVariant,
+                modifier = Modifier.padding(top = 8.dp),
+            )
+        } else {
+            state.identities.forEach { identity -> IdentityRow(identity, state.busy, viewModel) }
+        }
+        SectionFeedback(state.feedback, Section.IDENTITY)
+    }
+}
+
+@Composable
+private fun IdentityRow(identity: LinkedIdentityDto, busy: Boolean, viewModel: AccountViewModel) {
+    Row(
+        Modifier.fillMaxWidth().padding(top = 12.dp),
+        verticalAlignment = Alignment.CenterVertically,
+    ) {
+        Column(Modifier.weight(1f)) {
+            Text(
+                identity.provider.replaceFirstChar { it.uppercase() },
+                style = MaterialTheme.typography.bodyLarge,
+            )
+            identity.email?.let {
+                Text(it, style = MaterialTheme.typography.bodySmall, color = MaterialTheme.colorScheme.onSurfaceVariant)
+            }
+        }
+        TextButton(onClick = { viewModel.unlinkIdentity(identity.provider) }, enabled = !busy) {
+            Text(stringResource(R.string.account_identity_unlink))
+        }
+    }
+}
+
+@Composable
+private fun CodeField(code: String, onChange: (String) -> Unit, enabled: Boolean) {
+    OutlinedTextField(
+        value = code,
+        onValueChange = { onChange(it.filter(Char::isDigit).take(8)) },
+        singleLine = true,
+        enabled = enabled,
+        label = { Text(stringResource(R.string.login_totp_code)) },
+        keyboardOptions = KeyboardOptions(keyboardType = KeyboardType.NumberPassword),
+        modifier = Modifier.fillMaxWidth().padding(top = 12.dp),
+    )
+}
+
+@Composable
+private fun SectionFeedback(feedback: Feedback?, section: Section) {
+    if (feedback == null || feedback.section != section) return
+    Text(
+        text = stringResource(feedback.messageRes),
+        style = MaterialTheme.typography.bodySmall,
+        color = if (feedback.ok) MaterialTheme.colorScheme.primary else MaterialTheme.colorScheme.error,
+        modifier = Modifier.padding(top = 10.dp),
+    )
+}
+
+/** Decode a `data:image/png;base64,…` URL (the TOTP QR) into an [ImageBitmap]. */
+@Composable
+private fun rememberQrBitmap(dataUrl: String?): ImageBitmap? = remember(dataUrl) {
+    if (dataUrl.isNullOrBlank()) return@remember null
+    val comma = dataUrl.indexOf(',')
+    if (comma < 0) return@remember null
+    runCatching {
+        val bytes = Base64.decode(dataUrl.substring(comma + 1), Base64.DEFAULT)
+        BitmapFactory.decodeByteArray(bytes, 0, bytes.size)?.asImageBitmap()
+    }.getOrNull()
+}
+
 /** Human label for a role (advisory display only — §4.3). */
 @StringRes
 fun roleLabelRes(role: Role): Int = when (role) {

app/src/main/java/com/runicgateway/app/ui/auth/AccountViewModel.kt

@@ -0,0 +1,185 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.ui.auth
+
+import androidx.annotation.StringRes
+import androidx.lifecycle.ViewModel
+import androidx.lifecycle.viewModelScope
+import com.runicgateway.app.R
+import com.runicgateway.app.core.result.ApiResult
+import com.runicgateway.app.data.api.dto.LinkedIdentityDto
+import com.runicgateway.app.data.api.dto.PlayerAccountDto
+import com.runicgateway.app.data.api.dto.TotpSetupDto
+import com.runicgateway.app.data.repository.AccountRepository
+import com.runicgateway.app.data.repository.AuthRepository
+import com.runicgateway.app.ui.UiState
+import com.runicgateway.app.ui.toUiState
+import dagger.hilt.android.lifecycle.HiltViewModel
+import kotlinx.coroutines.flow.MutableStateFlow
+import kotlinx.coroutines.flow.StateFlow
+import kotlinx.coroutines.flow.asStateFlow
+import kotlinx.coroutines.flow.update
+import kotlinx.coroutines.launch
+import javax.inject.Inject
+
+/**
+ * Drives the signed-in self-service surface (PLAN.md §6.3, §6.4) over
+ * `/auth/me/account*`: change username/password, enroll/disable TOTP, and manage
+ * linked SSO identities. Each mutation folds its [ApiResult] into a section-scoped
+ * [Feedback] so the screen shows friendly, localized copy inline (§7). A username
+ * change also re-validates the session so the shell reflects the new name at once.
+ */
+@HiltViewModel
+class AccountViewModel @Inject constructor(
+    private val accountRepository: AccountRepository,
+    private val authRepository: AuthRepository,
+) : ViewModel() {
+
+    /** Which section an action's [Feedback] belongs to, so it renders in place. */
+    enum class Section { USERNAME, PASSWORD, TOTP, IDENTITY }
+
+    /** A one-shot result banner under a section. */
+    data class Feedback(val section: Section, val ok: Boolean, @param:StringRes val messageRes: Int)
+
+    data class State(
+        val account: UiState<PlayerAccountDto> = UiState.Loading,
+        val identities: List<LinkedIdentityDto> = emptyList(),
+        /** True while any mutation is in flight (disables that section's controls). */
+        val busy: Boolean = false,
+        /** The pending TOTP enrollment (QR shown) between setup and enable. */
+        val totpSetup: TotpSetupDto? = null,
+        val feedback: Feedback? = null,
+    )
+
+    private val _state = MutableStateFlow(State())
+    val state: StateFlow<State> = _state.asStateFlow()
+
+    init {
+        load()
+    }
+
+    fun load() {
+        _state.update { it.copy(account = UiState.Loading) }
+        viewModelScope.launch {
+            val account = accountRepository.getAccount()
+            _state.update { it.copy(account = account.toUiState()) }
+            // Identities are non-critical — an empty list on failure is fine.
+            when (val ids = accountRepository.identities()) {
+                is ApiResult.Ok -> _state.update { it.copy(identities = ids.data) }
+                else -> Unit
+            }
+        }
+    }
+
+    fun clearFeedback() = _state.update { it.copy(feedback = null) }
+
+    // ── Username ─────────────────────────────────────────────────────────
+    fun changeUsername(username: String) {
+        if (_state.value.busy) return
+        _state.update { it.copy(busy = true, feedback = null) }
+        viewModelScope.launch {
+            when (val result = accountRepository.changeUsername(username.trim())) {
+                is ApiResult.Ok -> {
+                    finish(Section.USERNAME, true, R.string.account_username_changed)
+                    // Reflect the new name in the shell + refresh the loaded account.
+                    authRepository.revalidate()
+                    reloadAccount()
+                }
+                else -> finish(Section.USERNAME, false, usernameErrorRes(result))
+            }
+        }
+    }
+
+    // ── Password ─────────────────────────────────────────────────────────
+    fun changePassword(newPassword: String, currentPassword: String?) {
+        if (_state.value.busy) return
+        _state.update { it.copy(busy = true, feedback = null) }
+        viewModelScope.launch {
+            when (accountRepository.changePassword(newPassword, currentPassword?.takeIf { it.isNotBlank() })) {
+                is ApiResult.Ok -> finish(Section.PASSWORD, true, R.string.account_password_changed)
+                is ApiResult.HttpError -> finish(Section.PASSWORD, false, R.string.account_password_error)
+                is ApiResult.NetworkError -> finish(Section.PASSWORD, false, R.string.error_network)
+            }
+        }
+    }
+
+    // ── TOTP ─────────────────────────────────────────────────────────────
+    fun beginTotp() {
+        if (_state.value.busy) return
+        _state.update { it.copy(busy = true, feedback = null) }
+        viewModelScope.launch {
+            when (val result = accountRepository.totpSetup()) {
+                is ApiResult.Ok -> _state.update { it.copy(busy = false, totpSetup = result.data) }
+                else -> finish(Section.TOTP, false, R.string.account_totp_setup_error)
+            }
+        }
+    }
+
+    fun cancelTotp() = _state.update { it.copy(totpSetup = null, feedback = null) }
+
+    fun enableTotp(code: String) {
+        if (_state.value.busy) return
+        _state.update { it.copy(busy = true, feedback = null) }
+        viewModelScope.launch {
+            when (accountRepository.totpEnable(code.trim())) {
+                is ApiResult.Ok -> {
+                    _state.update { it.copy(totpSetup = null) }
+                    finish(Section.TOTP, true, R.string.account_totp_enabled)
+                    reloadAccount()
+                }
+                is ApiResult.HttpError -> finish(Section.TOTP, false, R.string.account_totp_code_error)
+                is ApiResult.NetworkError -> finish(Section.TOTP, false, R.string.error_network)
+            }
+        }
+    }
+
+    fun disableTotp(code: String) {
+        if (_state.value.busy) return
+        _state.update { it.copy(busy = true, feedback = null) }
+        viewModelScope.launch {
+            when (accountRepository.totpDisable(code.trim())) {
+                is ApiResult.Ok -> {
+                    finish(Section.TOTP, true, R.string.account_totp_disabled)
+                    reloadAccount()
+                }
+                is ApiResult.HttpError -> finish(Section.TOTP, false, R.string.account_totp_code_error)
+                is ApiResult.NetworkError -> finish(Section.TOTP, false, R.string.error_network)
+            }
+        }
+    }
+
+    // ── Identities ───────────────────────────────────────────────────────
+    fun unlinkIdentity(provider: String) {
+        if (_state.value.busy) return
+        _state.update { it.copy(busy = true, feedback = null) }
+        viewModelScope.launch {
+            when (accountRepository.unlinkIdentity(provider)) {
+                is ApiResult.Ok -> {
+                    finish(Section.IDENTITY, true, R.string.account_identity_unlinked)
+                    when (val ids = accountRepository.identities()) {
+                        is ApiResult.Ok -> _state.update { it.copy(identities = ids.data) }
+                        else -> Unit
+                    }
+                }
+                else -> finish(Section.IDENTITY, false, R.string.account_identity_error)
+            }
+        }
+    }
+
+    private suspend fun reloadAccount() {
+        when (val account = accountRepository.getAccount()) {
+            is ApiResult.Ok -> _state.update { it.copy(account = UiState.Success(account.data)) }
+            else -> Unit
+        }
+    }
+
+    private fun finish(section: Section, ok: Boolean, @StringRes messageRes: Int) =
+        _state.update { it.copy(busy = false, feedback = Feedback(section, ok, messageRes)) }
+
+    private fun usernameErrorRes(result: ApiResult<*>): Int = when {
+        result is ApiResult.HttpError && result.status == 409 -> R.string.account_username_taken
+        result is ApiResult.NetworkError -> R.string.error_network
+        else -> R.string.account_username_error
+    }
+}

app/src/main/java/com/runicgateway/app/ui/auth/LoginScreen.kt

@@ -16,6 +16,7 @@ import androidx.compose.foundation.verticalScroll
 import androidx.compose.material3.Button
 import androidx.compose.material3.CircularProgressIndicator
 import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.OutlinedButton
 import androidx.compose.material3.OutlinedTextField
 import androidx.compose.material3.Text
 import androidx.compose.material3.TextButton
@@ -56,6 +57,13 @@ fun LoginScreen(
         if (state.signedIn) onSignedIn()
     }
 
+    // Open a freshly-minted SSO /start URL in a Custom Tab, exactly once (§4.2).
+    LaunchedEffect(state.ssoLaunchUrl) {
+        val url = state.ssoLaunchUrl ?: return@LaunchedEffect
+        WebHandoff.open(context, url)
+        viewModel.onSsoLaunchConsumed()
+    }
+
     Column(
         modifier = modifier
             .fillMaxSize()
@@ -155,6 +163,29 @@ fun LoginScreen(
             }
         }
 
+        // ── Native SSO (§4.2, M9): a button per enabled provider that opens the
+        // Custom-Tab bridge and returns the user signed in. Falls back to the
+        // website login hand-off when the shard exposes no providers.
+        if (state.ssoProviders.isNotEmpty()) {
+            state.ssoProviders.forEach { provider ->
+                OutlinedButton(
+                    onClick = { viewModel.onSsoProviderClick(provider) },
+                    enabled = !state.submitting,
+                    modifier = Modifier
+                        .fillMaxWidth()
+                        .padding(top = 12.dp),
+                ) {
+                    Text(stringResource(R.string.login_sso_provider, provider.name))
+                }
+            }
+        } else {
+            viewModel.ssoLoginUrl?.let { url ->
+                TextButton(onClick = { WebHandoff.open(context, url) }) {
+                    Text(stringResource(R.string.login_sso))
+                }
+            }
+        }
+
         // ── Website hand-offs (§4.2): open the site's own pages in a Custom Tab ──
         viewModel.registerUrl?.let { url ->
             TextButton(
@@ -167,11 +198,6 @@ fun LoginScreen(
                 Text(stringResource(R.string.login_forgot))
             }
         }
-        viewModel.ssoLoginUrl?.let { url ->
-            TextButton(onClick = { WebHandoff.open(context, url) }) {
-                Text(stringResource(R.string.login_sso))
-            }
-        }
     }
 }
 
@@ -181,4 +207,5 @@ private fun loginErrorRes(error: LoginError): Int = when (error) {
     LoginError.RATE_LIMITED -> R.string.login_error_rate_limited
     LoginError.SERVER -> R.string.login_error_server
     LoginError.NETWORK -> R.string.login_error_network
+    LoginError.SSO -> R.string.login_error_sso
 }

app/src/main/java/com/runicgateway/app/ui/auth/LoginViewModel.kt

@@ -5,7 +5,9 @@ package com.runicgateway.app.ui.auth
 
 import androidx.lifecycle.ViewModel
 import androidx.lifecycle.viewModelScope
+import com.runicgateway.app.core.auth.sso.SsoAuthManager
 import com.runicgateway.app.core.web.WebsiteUrls
+import com.runicgateway.app.data.api.dto.SsoProviderDto
 import com.runicgateway.app.data.repository.AuthRepository
 import com.runicgateway.app.data.repository.AuthRepository.LoginResult
 import dagger.hilt.android.lifecycle.HiltViewModel
@@ -25,11 +27,12 @@ import javax.inject.Inject
 @HiltViewModel
 class LoginViewModel @Inject constructor(
     private val authRepository: AuthRepository,
+    private val ssoAuthManager: SsoAuthManager,
     private val websiteUrls: WebsiteUrls,
 ) : ViewModel() {
 
     /** The transient error surfaced under the form after a failed attempt. */
-    enum class LoginError { INVALID_CREDENTIALS, BAD_CODE, RATE_LIMITED, SERVER, NETWORK }
+    enum class LoginError { INVALID_CREDENTIALS, BAD_CODE, RATE_LIMITED, SERVER, NETWORK, SSO }
 
     data class UiState(
         val username: String = "",
@@ -40,11 +43,40 @@ class LoginViewModel @Inject constructor(
         val submitting: Boolean = false,
         val error: LoginError? = null,
         val signedIn: Boolean = false,
+        /** The shard's enabled SSO providers (§4.2); empty → website hand-off fallback. */
+        val ssoProviders: List<SsoProviderDto> = emptyList(),
+        /** A `/auth/mobile/sso/start` URL the screen should open in a Custom Tab, once. */
+        val ssoLaunchUrl: String? = null,
     )
 
     private val _state = MutableStateFlow(UiState())
     val state: StateFlow<UiState> = _state.asStateFlow()
 
+    init {
+        // Discover the native SSO providers to render buttons for (§4.2).
+        viewModelScope.launch {
+            val providers = authRepository.ssoProviders()
+            if (providers.isNotEmpty()) _state.update { it.copy(ssoProviders = providers) }
+        }
+        // Consume the SSO bridge outcome: a returned callback completes here even if
+        // this ViewModel was recreated while the Custom Tab was foreground (§4.2).
+        viewModelScope.launch {
+            ssoAuthManager.outcome.collect { outcome ->
+                when (outcome) {
+                    SsoAuthManager.Outcome.Success -> {
+                        ssoAuthManager.consumeOutcome()
+                        _state.update { it.copy(submitting = false, signedIn = true) }
+                    }
+                    is SsoAuthManager.Outcome.Failed -> {
+                        ssoAuthManager.consumeOutcome()
+                        _state.update { it.copy(submitting = false, error = mapSsoError(outcome.reason)) }
+                    }
+                    SsoAuthManager.Outcome.Idle -> Unit
+                }
+            }
+        }
+    }
+
     fun onUsernameChange(value: String) = _state.update { it.copy(username = value, error = null) }
     fun onPasswordChange(value: String) = _state.update { it.copy(password = value, error = null) }
     fun onCodeChange(value: String) =
@@ -52,8 +84,33 @@ class LoginViewModel @Inject constructor(
 
     val registerUrl: String? get() = websiteUrls.register()
     val forgotPasswordUrl: String? get() = websiteUrls.forgotPassword()
+
+    /** Website login hand-off — the fallback when native SSO discovery is empty (§4.2). */
     val ssoLoginUrl: String? get() = websiteUrls.login()
 
+    /**
+     * Begin a native SSO flow for [provider]: mint PKCE + state and surface the
+     * `/start` URL for the screen to open in a Custom Tab. No-op (leaves a SERVER
+     * error) if the base URL isn't set yet — the website fallback still shows.
+     */
+    fun onSsoProviderClick(provider: SsoProviderDto) {
+        if (_state.value.submitting) return
+        val url = ssoAuthManager.buildStartUrl(provider.id)
+        if (url == null) {
+            _state.update { it.copy(error = LoginError.SSO) }
+            return
+        }
+        _state.update { it.copy(error = null, ssoLaunchUrl = url) }
+    }
+
+    /** The screen has opened the Custom Tab; clear so it isn't re-launched on recompose. */
+    fun onSsoLaunchConsumed() = _state.update { it.copy(ssoLaunchUrl = null) }
+
+    private fun mapSsoError(reason: SsoAuthManager.Failure): LoginError = when (reason) {
+        SsoAuthManager.Failure.NETWORK -> LoginError.NETWORK
+        else -> LoginError.SSO
+    }
+
     fun submit() {
         val s = _state.value
         if (s.submitting) return

app/src/main/java/com/runicgateway/app/ui/components/ThemeComponents.kt

@@ -0,0 +1,148 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.ui.components
+
+import androidx.compose.foundation.background
+import androidx.compose.foundation.border
+import androidx.compose.foundation.layout.Box
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.ColumnScope
+import androidx.compose.foundation.layout.fillMaxWidth
+import androidx.compose.foundation.layout.height
+import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.layout.size
+import androidx.compose.foundation.shape.CircleShape
+import androidx.compose.foundation.shape.RoundedCornerShape
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.Surface
+import androidx.compose.material3.Text
+import androidx.compose.runtime.Composable
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.draw.clip
+import androidx.compose.ui.graphics.Brush
+import androidx.compose.ui.graphics.Color
+import androidx.compose.ui.unit.dp
+import com.runicgateway.app.ui.theme.ShardCardBottom
+import com.runicgateway.app.ui.theme.ShardCardTop
+import com.runicgateway.app.ui.theme.ShardDanger
+import com.runicgateway.app.ui.theme.ShardDangerBg
+import com.runicgateway.app.ui.theme.ShardElevated
+import com.runicgateway.app.ui.theme.ShardFaint
+import com.runicgateway.app.ui.theme.ShardOutline
+import com.runicgateway.app.ui.theme.ShardPillBg
+import com.runicgateway.app.ui.theme.ShardPillFg
+import com.runicgateway.app.ui.theme.ShardSuccess
+import com.runicgateway.app.ui.theme.ShardSuccessBg
+import com.runicgateway.app.ui.theme.ShardSuccessDot
+import com.runicgateway.app.ui.theme.ShardWarning
+import com.runicgateway.app.ui.theme.ShardWarningBg
+
+/**
+ * Shared visual building blocks for the M5 shard-website design pass
+ * (docs/android/PLAN.md §M5): the recurring pill, section-label, feature-card,
+ * and stat-bar motifs the mockup repeats across screens. Pure presentation —
+ * no state, no data dependencies — so any screen can adopt them.
+ */
+
+/** Semantic tone for a [StatusPill] / [OnlineDot]. */
+enum class PillTone { Success, Warning, Danger, Neutral, Info }
+
+private data class PillColors(val fg: Color, val bg: Color)
+
+private fun toneColors(tone: PillTone): PillColors = when (tone) {
+    PillTone.Success -> PillColors(ShardSuccess, ShardSuccessBg)
+    PillTone.Warning -> PillColors(ShardWarning, ShardWarningBg)
+    PillTone.Danger -> PillColors(ShardDanger, ShardDangerBg)
+    PillTone.Neutral, PillTone.Info -> PillColors(ShardPillFg, ShardPillBg)
+}
+
+/**
+ * A small uppercase status chip — "Live", "Up", "Enabled", "IDOC", a role — with a
+ * rounded filled background tinted by [tone]. Mirrors the mockup's pill badges.
+ */
+@Composable
+fun StatusPill(text: String, tone: PillTone, modifier: Modifier = Modifier) {
+    val c = toneColors(tone)
+    Surface(color = c.bg, shape = CircleShape, modifier = modifier) {
+        Text(
+            text = text.uppercase(),
+            style = MaterialTheme.typography.labelSmall,
+            color = c.fg,
+            modifier = Modifier.padding(horizontal = 10.dp, vertical = 4.dp),
+        )
+    }
+}
+
+/** The small colored status dot (green when live), matched to a [PillTone]. */
+@Composable
+fun OnlineDot(tone: PillTone, modifier: Modifier = Modifier) {
+    val color = when (tone) {
+        PillTone.Success -> ShardSuccessDot
+        PillTone.Warning -> ShardWarning
+        PillTone.Danger -> ShardDanger
+        PillTone.Neutral, PillTone.Info -> ShardFaint
+    }
+    Box(modifier.size(8.dp).clip(CircleShape).background(color))
+}
+
+/**
+ * The muted, uppercase, letter-spaced section header the design uses above grouped
+ * content ("Attributes", "Vitals", "Password", "Linked accounts").
+ */
+@Composable
+fun SectionLabel(text: String, modifier: Modifier = Modifier) {
+    Text(
+        text = text.uppercase(),
+        style = MaterialTheme.typography.labelSmall,
+        color = ShardFaint,
+        modifier = modifier,
+    )
+}
+
+/**
+ * The elevated "feature" card: a vertical blue gradient with a hairline outline and
+ * soft shadow, used for the home status card, the shard-online banner, and the
+ * vendor card. [content] is laid out in a padded [Column].
+ */
+@Composable
+fun FeatureCard(
+    modifier: Modifier = Modifier,
+    contentPadding: Int = 18,
+    content: @Composable ColumnScope.() -> Unit,
+) {
+    Box(
+        modifier = modifier
+            .fillMaxWidth()
+            .clip(RoundedCornerShape(12.dp))
+            .background(Brush.verticalGradient(listOf(ShardCardTop, ShardCardBottom)))
+            .border(1.dp, ShardOutline, RoundedCornerShape(12.dp)),
+    ) {
+        Column(Modifier.padding(contentPadding.dp), content = content)
+    }
+}
+
+/**
+ * A slim rounded meter (vitals / skills). [fraction] is clamped to 0..1; the fill is
+ * the slate accent over a bordered dark track.
+ */
+@Composable
+fun StatBar(fraction: Float, modifier: Modifier = Modifier) {
+    val pct = fraction.coerceIn(0f, 1f)
+    Box(
+        modifier = modifier
+            .fillMaxWidth()
+            .height(6.dp)
+            .clip(RoundedCornerShape(3.dp))
+            .background(ShardElevated)
+            .border(1.dp, ShardOutline, RoundedCornerShape(3.dp)),
+    ) {
+        Box(
+            Modifier
+                .fillMaxWidth(pct)
+                .height(6.dp)
+                .clip(RoundedCornerShape(3.dp))
+                .background(MaterialTheme.colorScheme.secondary),
+        )
+    }
+}

app/src/main/java/com/runicgateway/app/ui/connect/ConnectScreen.kt

@@ -107,6 +107,7 @@ private fun errorMessage(error: ConnectError): String = when (error) {
     ConnectError.UnsupportedScheme -> stringResource(R.string.connect_error_scheme)
     ConnectError.Insecure -> stringResource(R.string.connect_error_insecure)
     ConnectError.NotRunicGateway -> stringResource(R.string.connect_error_not_runic)
+    is ConnectError.VersionMismatch -> stringResource(R.string.connect_error_version, error.serverApi)
     ConnectError.Unreachable -> stringResource(R.string.connect_error_unreachable)
     is ConnectError.Server -> stringResource(R.string.connect_error_server, error.status)
 }

app/src/main/java/com/runicgateway/app/ui/connect/ConnectViewModel.kt

@@ -32,6 +32,7 @@ class ConnectViewModel @Inject constructor(
         data object UnsupportedScheme : ConnectError
         data object Insecure : ConnectError
         data object NotRunicGateway : ConnectError
+        data class VersionMismatch(val serverApi: String) : ConnectError
         data object Unreachable : ConnectError
         data class Server(val status: Int) : ConnectError
     }
@@ -61,6 +62,7 @@ class ConnectViewModel @Inject constructor(
                 }
                 is ProbeResult.InvalidUrl -> fail(result.reason.toError())
                 ProbeResult.NotRunicGateway -> fail(ConnectError.NotRunicGateway)
+                is ProbeResult.VersionMismatch -> fail(ConnectError.VersionMismatch(result.serverApi))
                 is ProbeResult.Unreachable -> fail(ConnectError.Unreachable)
                 is ProbeResult.ServerError -> fail(ConnectError.Server(result.status))
             }

app/src/main/java/com/runicgateway/app/ui/home/HomeScreen.kt

@@ -4,19 +4,19 @@
 package com.runicgateway.app.ui.home
 
 import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.Row
 import androidx.compose.foundation.layout.Spacer
 import androidx.compose.foundation.layout.fillMaxSize
-import androidx.compose.foundation.layout.fillMaxWidth
 import androidx.compose.foundation.layout.height
 import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.layout.width
 import androidx.compose.foundation.rememberScrollState
 import androidx.compose.foundation.verticalScroll
-import androidx.compose.material3.Card
-import androidx.compose.material3.CardDefaults
 import androidx.compose.material3.MaterialTheme
 import androidx.compose.material3.Text
 import androidx.compose.runtime.Composable
 import androidx.compose.runtime.getValue
+import androidx.compose.ui.Alignment
 import androidx.compose.ui.Modifier
 import androidx.compose.ui.res.stringResource
 import androidx.compose.ui.unit.dp
@@ -27,7 +27,10 @@ import com.runicgateway.app.data.api.dto.BrandDto
 import com.runicgateway.app.data.api.dto.StatusDto
 import com.runicgateway.app.ui.UiState
 import com.runicgateway.app.ui.components.ErrorView
+import com.runicgateway.app.ui.components.FeatureCard
 import com.runicgateway.app.ui.components.LoadingView
+import com.runicgateway.app.ui.components.OnlineDot
+import com.runicgateway.app.ui.components.PillTone
 
 /**
  * Home / status (PLAN.md §6.1): the shard's name + tagline from branding, and a
@@ -83,40 +86,37 @@ private fun HomeContent(brand: BrandDto?, status: StatusDto, modifier: Modifier
 @Composable
 private fun StatusCard(status: StatusDto) {
     val online = !status.isMaintenance
-    val containerColor =
-        if (online) MaterialTheme.colorScheme.secondaryContainer
-        else MaterialTheme.colorScheme.errorContainer
 
-    Card(
-        modifier = Modifier.fillMaxWidth(),
-        colors = CardDefaults.cardColors(containerColor = containerColor),
-    ) {
-        Column(Modifier.padding(16.dp)) {
+    FeatureCard {
+        Row(verticalAlignment = Alignment.CenterVertically) {
+            OnlineDot(if (online) PillTone.Success else PillTone.Danger)
+            Spacer(Modifier.width(10.dp))
             Text(
                 text = stringResource(
                     if (online) R.string.home_status_live else R.string.home_status_maintenance,
                 ),
-                style = MaterialTheme.typography.titleLarge,
+                style = MaterialTheme.typography.titleMedium,
+                color = MaterialTheme.colorScheme.onSurface,
+            )
+        }
+        if (status.isMaintenance && status.statusMessage.isNotBlank()) {
+            Text(
+                text = status.statusMessage,
+                style = MaterialTheme.typography.bodyMedium,
+                modifier = Modifier.padding(top = 6.dp),
+            )
+        }
+        if (status.version.server.isNotBlank()) {
+            Text(
+                text = stringResource(
+                    R.string.home_server_version,
+                    status.version.server,
+                    status.version.api,
+                ),
+                style = MaterialTheme.typography.labelMedium,
+                color = MaterialTheme.colorScheme.onSurfaceVariant,
+                modifier = Modifier.padding(top = 10.dp),
             )
-            if (status.isMaintenance && status.statusMessage.isNotBlank()) {
-                Text(
-                    text = status.statusMessage,
-                    style = MaterialTheme.typography.bodyMedium,
-                    modifier = Modifier.padding(top = 6.dp),
-                )
-            }
-            if (status.version.server.isNotBlank()) {
-                Text(
-                    text = stringResource(
-                        R.string.home_server_version,
-                        status.version.server,
-                        status.version.api,
-                    ),
-                    style = MaterialTheme.typography.labelMedium,
-                    color = MaterialTheme.colorScheme.onSurfaceVariant,
-                    modifier = Modifier.padding(top = 10.dp),
-                )
-            }
         }
     }
 }

app/src/main/java/com/runicgateway/app/ui/navigation/Menu.kt

@@ -21,7 +21,7 @@ enum class MenuAccess {
     /** Visible to any signed-in account (§5, "My Account"). */
     SIGNED_IN,
 
-    /** Visible only to a player (linked game data lands in M4, §6.3). */
+    /** Visible only to a player — the linked game-data groups (§6.3). */
     PLAYER,
 }
 
@@ -33,7 +33,8 @@ data class MenuEntry(
 
 /**
  * The full menu, in display order. Public content first, then the signed-in
- * surfaces. Player game-data groups (My Characters / Vendors / Houses) join in M4.
+ * surfaces, then the player-only game-data groups (revealed once the session's
+ * role is `player`, §6.3).
  */
 val APP_MENU: List<MenuEntry> = listOf(
     MenuEntry(Routes.HOME, R.string.menu_home),
@@ -43,6 +44,10 @@ val APP_MENU: List<MenuEntry> = listOf(
     MenuEntry(Routes.page("about"), R.string.menu_about),
     MenuEntry(Routes.CONTACT, R.string.menu_contact),
     MenuEntry(Routes.ACCOUNT, R.string.menu_account, MenuAccess.SIGNED_IN),
+    MenuEntry(Routes.NOTIFICATIONS, R.string.menu_notifications, MenuAccess.SIGNED_IN),
+    MenuEntry(Routes.PLAYER_CHARACTERS, R.string.menu_my_characters, MenuAccess.PLAYER),
+    MenuEntry(Routes.PLAYER_VENDORS, R.string.menu_my_vendors, MenuAccess.PLAYER),
+    MenuEntry(Routes.PLAYER_HOUSES, R.string.menu_my_houses, MenuAccess.PLAYER),
 )
 
 /**

app/src/main/java/com/runicgateway/app/ui/navigation/Routes.kt

@@ -18,6 +18,9 @@ object Routes {
     const val LOGIN = "login"
     const val ACCOUNT = "account"
 
+    /** Opt-in push notification settings (§11, signed-in). */
+    const val NOTIFICATIONS = "notifications"
+
     /** Public shard hub (§6.2). */
     const val SHARD = "shard"
 
@@ -27,6 +30,14 @@ object Routes {
     const val SHARD_GOVERNORS = "shard/governors"
     const val SHARD_HOUSES = "shard/houses"
 
+    /** Player game-data groups (§6.3, player-only). Distinct from the public shard boards. */
+    const val PLAYER_CHARACTERS = "player/characters"
+    const val PLAYER_VENDORS = "player/vendors"
+    const val PLAYER_HOUSES = "player/houses"
+
+    /** A single character sheet by in-game (hex) serial. */
+    const val PLAYER_CHAR = "player/char/{serial}"
+
     /** CMS page by slug (e.g. the conventional "about" page, mirrored from the site nav). */
     const val PAGE = "page/{slug}"
 
@@ -40,9 +51,32 @@ object Routes {
         const val SLUG = "slug"
         const val CATEGORY = "category"
         const val ID_OR_SLUG = "idOrSlug"
+        const val SERIAL = "serial"
     }
 
     fun page(slug: String) = "page/$slug"
     fun post(categoryUrlSlug: String, idOrSlug: String) = "news/$categoryUrlSlug/$idOrSlug"
     fun wikiPage(slug: String) = "wiki/$slug"
+
+    /** The character-sheet route for an in-game serial (e.g. "0x24C"). */
+    fun playerChar(serial: String) = "player/char/$serial"
+
+    /**
+     * The in-app destination a tapped push notification deep-links to (§11, M7
+     * Part 2 work item 7). Maps a stream id to the screen that shows its content;
+     * unknown streams land on Home. Personal streams route to the player groups
+     * (a signed-out/demoted tap is caught by [com.runicgateway.app.ui.PlayerGate]).
+     */
+    fun forStream(streamId: String): String = when (streamId) {
+        com.runicgateway.app.core.push.PushStreams.NEWS_POST -> NEWS
+        com.runicgateway.app.core.push.PushStreams.SERVER_STATUS,
+        com.runicgateway.app.core.push.PushStreams.CHAMP_START,
+        com.runicgateway.app.core.push.PushStreams.IDOC_WARNING,
+        com.runicgateway.app.core.push.PushStreams.GOVERNOR_ELECTION,
+        -> SHARD
+        com.runicgateway.app.core.push.PushStreams.VENDOR_SALE -> PLAYER_VENDORS
+        com.runicgateway.app.core.push.PushStreams.HOUSE_IDOC -> PLAYER_HOUSES
+        com.runicgateway.app.core.push.PushStreams.ACCOUNT_LOGIN -> ACCOUNT
+        else -> HOME
+    }
 }

app/src/main/java/com/runicgateway/app/ui/notifications/NotificationsScreen.kt

@@ -0,0 +1,182 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.ui.notifications
+
+import android.Manifest
+import android.os.Build
+import androidx.activity.compose.rememberLauncherForActivityResult
+import androidx.activity.result.contract.ActivityResultContracts
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.Row
+import androidx.compose.foundation.layout.Spacer
+import androidx.compose.foundation.layout.fillMaxSize
+import androidx.compose.foundation.layout.fillMaxWidth
+import androidx.compose.foundation.layout.height
+import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.rememberScrollState
+import androidx.compose.foundation.verticalScroll
+import androidx.compose.material3.HorizontalDivider
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.Switch
+import androidx.compose.material3.Text
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.getValue
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.platform.LocalContext
+import androidx.compose.ui.res.stringResource
+import androidx.compose.ui.text.font.FontStyle
+import androidx.compose.ui.unit.dp
+import androidx.hilt.navigation.compose.hiltViewModel
+import androidx.lifecycle.compose.collectAsStateWithLifecycle
+import com.runicgateway.app.R
+import com.runicgateway.app.data.api.dto.NotificationStreamDto
+import com.runicgateway.app.ui.UiState
+import com.runicgateway.app.ui.components.EmptyView
+import com.runicgateway.app.ui.components.ErrorView
+import com.runicgateway.app.ui.components.LoadingView
+import com.runicgateway.app.ui.components.SectionLabel
+
+/**
+ * The Notifications settings screen (PLAN.md §11, M7 Part 2 work item 6): the
+ * subscribable catalog with per-stream toggles. Personal streams are greyed until a
+ * game account is linked; turning a stream on requests the POST_NOTIFICATIONS
+ * permission (API 33+) and registers the device, turning them all off unregisters it.
+ */
+@Composable
+fun NotificationsScreen(
+    modifier: Modifier = Modifier,
+    viewModel: NotificationsViewModel = hiltViewModel(),
+) {
+    val state by viewModel.state.collectAsStateWithLifecycle()
+    val context = LocalContext.current
+
+    // Ask once for POST_NOTIFICATIONS when the user first enables a stream (API 33+).
+    val permissionLauncher = rememberLauncherForActivityResult(
+        ActivityResultContracts.RequestPermission(),
+    ) { /* granted or not, the subscription is already saved server-side */ }
+
+    fun ensureNotificationPermission() {
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
+            permissionLauncher.launch(Manifest.permission.POST_NOTIFICATIONS)
+        }
+    }
+
+    Column(
+        modifier = modifier
+            .fillMaxSize()
+            .verticalScroll(rememberScrollState())
+            .padding(16.dp),
+    ) {
+        Text(
+            text = stringResource(R.string.notifications_title),
+            style = MaterialTheme.typography.titleLarge,
+        )
+        Spacer(Modifier.height(4.dp))
+        Text(
+            text = stringResource(R.string.notifications_subtitle),
+            style = MaterialTheme.typography.bodyMedium,
+            color = MaterialTheme.colorScheme.onSurfaceVariant,
+        )
+        Spacer(Modifier.height(16.dp))
+
+        if (!state.supported) {
+            EmptyView(message = stringResource(R.string.notifications_unsupported))
+            return@Column
+        }
+
+        state.feedback?.let { fb ->
+            Text(
+                text = stringResource(fb.messageRes),
+                style = MaterialTheme.typography.bodyMedium,
+                color = if (fb.ok) MaterialTheme.colorScheme.primary else MaterialTheme.colorScheme.error,
+                modifier = Modifier.padding(bottom = 12.dp),
+            )
+        }
+
+        when (val catalog = state.catalog) {
+            is UiState.Loading -> LoadingView()
+            is UiState.Error -> ErrorView(kind = catalog.kind, onRetry = viewModel::load)
+            is UiState.Success -> StreamList(
+                streams = catalog.data,
+                subscribed = state.subscribed,
+                hasLinkedAccount = state.hasLinkedAccount,
+                busy = state.busy,
+                onToggle = { stream, on ->
+                    if (on) ensureNotificationPermission()
+                    viewModel.setSubscribed(stream, on)
+                },
+            )
+        }
+    }
+}
+
+@Composable
+private fun StreamList(
+    streams: List<NotificationStreamDto>,
+    subscribed: Set<String>,
+    hasLinkedAccount: Boolean,
+    busy: Boolean,
+    onToggle: (NotificationStreamDto, Boolean) -> Unit,
+) {
+    if (streams.isEmpty()) {
+        EmptyView(message = stringResource(R.string.notifications_empty))
+        return
+    }
+    val (personal, general) = streams.partition { it.personal }
+
+    if (general.isNotEmpty()) {
+        SectionLabel(stringResource(R.string.notifications_section_general))
+        Spacer(Modifier.height(8.dp))
+        general.forEach { stream ->
+            StreamRow(stream, subscribed.contains(stream.id), enabled = !busy, hint = null) { on ->
+                onToggle(stream, on)
+            }
+            HorizontalDivider()
+        }
+        Spacer(Modifier.height(20.dp))
+    }
+
+    if (personal.isNotEmpty()) {
+        SectionLabel(stringResource(R.string.notifications_section_personal))
+        Spacer(Modifier.height(8.dp))
+        personal.forEach { stream ->
+            val selectable = streamSelectable(stream, hasLinkedAccount)
+            val hint = if (!selectable) stringResource(R.string.notifications_requires_link) else null
+            StreamRow(stream, subscribed.contains(stream.id) && selectable, enabled = !busy && selectable, hint = hint) { on ->
+                onToggle(stream, on)
+            }
+            HorizontalDivider()
+        }
+    }
+}
+
+@Composable
+private fun StreamRow(
+    stream: NotificationStreamDto,
+    checked: Boolean,
+    enabled: Boolean,
+    hint: String?,
+    onToggle: (Boolean) -> Unit,
+) {
+    Row(
+        modifier = Modifier.fillMaxWidth().padding(vertical = 12.dp),
+        verticalAlignment = Alignment.CenterVertically,
+    ) {
+        Column(modifier = Modifier.weight(1f).padding(end = 12.dp)) {
+            Text(
+                text = stream.label,
+                style = MaterialTheme.typography.bodyLarge,
+                color = if (enabled) MaterialTheme.colorScheme.onSurface else MaterialTheme.colorScheme.onSurfaceVariant,
+            )
+            Text(
+                text = hint ?: stream.description,
+                style = MaterialTheme.typography.bodySmall,
+                color = MaterialTheme.colorScheme.onSurfaceVariant,
+                fontStyle = if (hint != null) FontStyle.Italic else FontStyle.Normal,
+            )
+        }
+        Switch(checked = checked, onCheckedChange = onToggle, enabled = enabled)
+    }
+}

app/src/main/java/com/runicgateway/app/ui/notifications/NotificationsViewModel.kt

@@ -0,0 +1,135 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.ui.notifications
+
+import androidx.annotation.StringRes
+import androidx.lifecycle.ViewModel
+import androidx.lifecycle.viewModelScope
+import com.runicgateway.app.R
+import com.runicgateway.app.core.push.PushManager
+import com.runicgateway.app.core.result.ApiResult
+import com.runicgateway.app.data.api.dto.NotificationStreamDto
+import com.runicgateway.app.data.repository.NotificationsRepository
+import com.runicgateway.app.data.repository.PlayerShardRepository
+import com.runicgateway.app.ui.UiState
+import com.runicgateway.app.ui.toUiState
+import dagger.hilt.android.lifecycle.HiltViewModel
+import kotlinx.coroutines.flow.MutableStateFlow
+import kotlinx.coroutines.flow.StateFlow
+import kotlinx.coroutines.flow.asStateFlow
+import kotlinx.coroutines.flow.update
+import kotlinx.coroutines.launch
+import javax.inject.Inject
+
+/**
+ * Drives the Notifications settings screen (PLAN.md §11, M7 Part 2 work item 6):
+ * the stream catalog with per-stream toggles bound to
+ * `GET/PUT /auth/me/notifications/subscriptions`. A **personal** stream is greyed
+ * until the user has a linked game account (§11), and turning the opt-in set
+ * non-empty/empty drives the [PushManager] to register/unregister the device.
+ */
+@HiltViewModel
+class NotificationsViewModel @Inject constructor(
+    private val notifications: NotificationsRepository,
+    private val playerShard: PlayerShardRepository,
+    private val pushManager: PushManager,
+) : ViewModel() {
+
+    data class Feedback(val ok: Boolean, @param:StringRes val messageRes: Int)
+
+    data class State(
+        val catalog: UiState<List<NotificationStreamDto>> = UiState.Loading,
+        val subscribed: Set<String> = emptySet(),
+        /** Whether the user has ≥1 linked game account — personal streams need it. */
+        val hasLinkedAccount: Boolean = false,
+        /** Whether this shard advertises a push relay at all (else the screen says so). */
+        val supported: Boolean = true,
+        val busy: Boolean = false,
+        val feedback: Feedback? = null,
+    )
+
+    private val _state = MutableStateFlow(State())
+    val state: StateFlow<State> = _state.asStateFlow()
+
+    init {
+        viewModelScope.launch {
+            pushManager.supported.collect { supported -> _state.update { it.copy(supported = supported) } }
+        }
+        load()
+    }
+
+    fun load() {
+        _state.update { it.copy(catalog = UiState.Loading) }
+        viewModelScope.launch {
+            val catalog = notifications.streams().let { result ->
+                when (result) {
+                    is ApiResult.Ok -> ApiResult.Ok(result.data.streams)
+                    is ApiResult.HttpError -> result
+                    is ApiResult.NetworkError -> result
+                }
+            }
+            _state.update { it.copy(catalog = catalog.toUiState()) }
+
+            when (val subs = notifications.subscriptions()) {
+                is ApiResult.Ok -> _state.update { it.copy(subscribed = subs.data.streams.toSet()) }
+                else -> Unit
+            }
+            // A linked game account gates the personal streams; failure → treat as none.
+            val linked = (playerShard.accounts() as? ApiResult.Ok)?.data?.isNotEmpty() == true
+            _state.update { it.copy(hasLinkedAccount = linked) }
+        }
+    }
+
+    fun clearFeedback() = _state.update { it.copy(feedback = null) }
+
+    /** Toggle [stream]; refuses a personal stream with no linked account. */
+    fun setSubscribed(stream: NotificationStreamDto, on: Boolean) {
+        val s = _state.value
+        if (s.busy) return
+        if (on && !streamSelectable(stream, s.hasLinkedAccount)) return
+        val next = if (on) s.subscribed + stream.id else s.subscribed - stream.id
+
+        _state.update { it.copy(busy = true, feedback = null) }
+        viewModelScope.launch {
+            when (val result = notifications.setSubscriptions(next.toList())) {
+                is ApiResult.Ok -> {
+                    val stored = result.data.streams.toSet()
+                    _state.update { it.copy(subscribed = stored) }
+                    reconcilePush(stored)
+                }
+                is ApiResult.NetworkError -> finish(false, R.string.error_network)
+                is ApiResult.HttpError -> finish(false, R.string.notifications_save_error)
+            }
+        }
+    }
+
+    /**
+     * Register or unregister the device to match the opted-in set (PLAN.md §11:
+     * register when signed-in + subscribed, unregister when the set empties).
+     */
+    private suspend fun reconcilePush(subscribed: Set<String>) {
+        if (subscribed.isEmpty()) {
+            pushManager.disable()
+            finish(true, R.string.notifications_all_off)
+            return
+        }
+        when (val res = pushManager.enable()) {
+            is PushManager.PushResult.Enabled -> finish(true, R.string.notifications_saved)
+            is PushManager.PushResult.Unsupported -> finish(false, R.string.notifications_unsupported)
+            is PushManager.PushResult.NotSignedIn -> finish(false, R.string.notifications_save_error)
+            is PushManager.PushResult.Failed ->
+                finish(false, if (res.status == 400) R.string.notifications_relay_error else R.string.notifications_save_error)
+        }
+    }
+
+    private fun finish(ok: Boolean, @StringRes messageRes: Int) =
+        _state.update { it.copy(busy = false, feedback = Feedback(ok, messageRes)) }
+}
+
+/**
+ * Whether a stream's toggle is selectable for a user: a personal stream needs a
+ * linked game account (PLAN.md §11). Pure so the gating is unit-tested without Compose.
+ */
+fun streamSelectable(stream: NotificationStreamDto, hasLinkedAccount: Boolean): Boolean =
+    !stream.requiresLinkedAccount || hasLinkedAccount

app/src/main/java/com/runicgateway/app/ui/player/CharacterSheetScreen.kt

@@ -0,0 +1,288 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.ui.player
+
+import androidx.compose.foundation.layout.Arrangement
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.FlowRow
+import androidx.compose.foundation.layout.ExperimentalLayoutApi
+import androidx.compose.foundation.layout.Row
+import androidx.compose.foundation.layout.fillMaxSize
+import androidx.compose.foundation.layout.fillMaxWidth
+import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.rememberScrollState
+import androidx.compose.foundation.verticalScroll
+import androidx.compose.material3.Card
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.Surface
+import androidx.compose.material3.Text
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.getValue
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.res.stringResource
+import androidx.compose.ui.text.font.FontWeight
+import androidx.compose.ui.unit.dp
+import androidx.hilt.navigation.compose.hiltViewModel
+import androidx.lifecycle.compose.collectAsStateWithLifecycle
+import com.runicgateway.app.R
+import com.runicgateway.app.data.api.dto.CharProfileDto
+import com.runicgateway.app.data.api.dto.CharStatsDto
+import com.runicgateway.app.data.api.dto.EquipmentDto
+import com.runicgateway.app.data.api.dto.ResistDto
+import com.runicgateway.app.data.api.dto.SkillDto
+import com.runicgateway.app.data.api.dto.TitlesDto
+import com.runicgateway.app.ui.UiState
+import com.runicgateway.app.ui.components.ErrorView
+import com.runicgateway.app.ui.components.LoadingView
+import com.runicgateway.app.ui.components.SectionLabel
+import com.runicgateway.app.ui.components.StatBar
+import kotlinx.serialization.json.jsonPrimitive
+
+/**
+ * A text-only character sheet (PLAN.md §6.3): identity + standing, attributes and
+ * vitals, resistances, skills, and equipment. No item icons / paperdoll art — a
+ * richer view is a future enhancement pending the platform art work.
+ */
+@Composable
+fun CharacterSheetScreen(
+    modifier: Modifier = Modifier,
+    viewModel: CharacterViewModel = hiltViewModel(),
+) {
+    val state by viewModel.state.collectAsStateWithLifecycle()
+    when (val s = state) {
+        is UiState.Loading -> LoadingView(modifier)
+        is UiState.Error -> ErrorView(s.kind, onRetry = viewModel::load, modifier = modifier)
+        is UiState.Success -> CharacterSheet(s.data, modifier)
+    }
+}
+
+@Composable
+private fun CharacterSheet(char: CharProfileDto, modifier: Modifier = Modifier) {
+    Column(
+        modifier = modifier
+            .fillMaxSize()
+            .verticalScroll(rememberScrollState())
+            .padding(16.dp),
+        verticalArrangement = Arrangement.spacedBy(16.dp),
+    ) {
+        IdentityBlock(char)
+        StandingChips(char)
+        char.stats?.let { AttributesBlock(it) }
+        char.stats?.resist?.let { ResistancesBlock(it) }
+        SkillsBlock(char.skills)
+        EquipmentBlock(char.equipment)
+    }
+}
+
+@Composable
+private fun IdentityBlock(char: CharProfileDto) {
+    Column {
+        Text(
+            char.name ?: stringResource(R.string.player_char_unknown),
+            style = MaterialTheme.typography.headlineSmall,
+        )
+        char.title?.takeIf { it.isNotBlank() }?.let {
+            Text(it, style = MaterialTheme.typography.bodyMedium, color = MaterialTheme.colorScheme.onSurfaceVariant)
+        }
+        Row(Modifier.padding(top = 4.dp)) {
+            Text(
+                stringResource(if (char.online) R.string.player_char_online else R.string.player_char_offline),
+                style = MaterialTheme.typography.labelMedium,
+                color = if (char.online) MaterialTheme.colorScheme.primary else MaterialTheme.colorScheme.onSurfaceVariant,
+            )
+            char.serial?.let {
+                Text(
+                    "  ·  $it",
+                    style = MaterialTheme.typography.labelMedium,
+                    color = MaterialTheme.colorScheme.onSurfaceVariant,
+                )
+            }
+        }
+    }
+}
+
+@OptIn(ExperimentalLayoutApi::class)
+@Composable
+private fun StandingChips(char: CharProfileDto) {
+    val chips = buildList {
+        char.governorOf.forEach { add(stringResource(R.string.player_char_governor, it)) }
+        char.guild?.let { g ->
+            val abbr = g.abbr?.let { " [$it]" } ?: ""
+            add(stringResource(R.string.player_char_guildmaster, "${g.name.orEmpty()}$abbr"))
+        }
+        addAll(displayTitles(char.titles))
+    }
+    if (chips.isEmpty()) return
+    FlowRow(horizontalArrangement = Arrangement.spacedBy(8.dp)) {
+        chips.forEach { Chip(it) }
+    }
+}
+
+@Composable
+private fun Chip(text: String) {
+    Surface(
+        color = MaterialTheme.colorScheme.secondaryContainer,
+        shape = MaterialTheme.shapes.small,
+    ) {
+        Text(
+            text,
+            style = MaterialTheme.typography.labelMedium,
+            color = MaterialTheme.colorScheme.onSecondaryContainer,
+            modifier = Modifier.padding(horizontal = 10.dp, vertical = 4.dp),
+        )
+    }
+}
+
+@Composable
+private fun AttributesBlock(stats: CharStatsDto) {
+    SheetCard(R.string.player_char_attributes) {
+        Row(Modifier.fillMaxWidth(), horizontalArrangement = Arrangement.SpaceBetween) {
+            Stat(stringResource(R.string.player_char_str), stats.str)
+            Stat(stringResource(R.string.player_char_dex), stats.dex)
+            Stat(stringResource(R.string.player_char_int), stats.int)
+        }
+        Column(Modifier.padding(top = 16.dp)) {
+            SectionLabel(stringResource(R.string.player_char_vitals))
+            Column(Modifier.padding(top = 8.dp)) {
+                Vital(stringResource(R.string.player_char_hits), stats.hits, stats.hitsMax)
+                Vital(stringResource(R.string.player_char_mana), stats.mana, stats.manaMax)
+                Vital(stringResource(R.string.player_char_stam), stats.stam, stats.stamMax)
+            }
+        }
+    }
+}
+
+@Composable
+private fun Stat(label: String, value: Int?) {
+    Column {
+        Text("${value ?: "—"}", style = MaterialTheme.typography.titleLarge)
+        Text(label, style = MaterialTheme.typography.labelSmall, color = MaterialTheme.colorScheme.onSurfaceVariant)
+    }
+}
+
+@Composable
+private fun Vital(label: String, cur: Int?, max: Int?) {
+    Column(Modifier.padding(vertical = 5.dp)) {
+        Row(Modifier.fillMaxWidth().padding(bottom = 4.dp), horizontalArrangement = Arrangement.SpaceBetween) {
+            Text(label, style = MaterialTheme.typography.labelMedium, color = MaterialTheme.colorScheme.onSurfaceVariant)
+            Text("${cur ?: "—"} / ${max ?: "—"}", style = MaterialTheme.typography.labelMedium, color = MaterialTheme.colorScheme.onSurfaceVariant)
+        }
+        val fraction = if (max != null && max > 0 && cur != null) cur.toFloat() / max else 0f
+        StatBar(fraction)
+    }
+}
+
+@Composable
+private fun ResistancesBlock(resist: ResistDto) {
+    val rows = listOf(
+        stringResource(R.string.player_char_phys) to resist.phys,
+        stringResource(R.string.player_char_fire) to resist.fire,
+        stringResource(R.string.player_char_cold) to resist.cold,
+        stringResource(R.string.player_char_pois) to resist.pois,
+        stringResource(R.string.player_char_energy) to resist.energy,
+    )
+    if (rows.all { it.second == null }) return
+    SheetCard(R.string.player_char_resistances) {
+        Row(Modifier.fillMaxWidth().padding(top = 4.dp), horizontalArrangement = Arrangement.SpaceBetween) {
+            rows.forEach { (label, value) ->
+                Column {
+                    Text("${value ?: 0}", style = MaterialTheme.typography.titleMedium)
+                    Text(label, style = MaterialTheme.typography.labelSmall, color = MaterialTheme.colorScheme.onSurfaceVariant)
+                }
+            }
+        }
+    }
+}
+
+@Composable
+private fun SkillsBlock(skills: List<SkillDto>) {
+    val shown = skills
+        .filter { (it.value ?: it.base ?: 0.0) > 0.0 }
+        .sortedByDescending { it.value ?: 0.0 }
+    if (shown.isEmpty()) return
+    SheetCard(R.string.player_char_skills) {
+        shown.forEach { skill ->
+            val value = skill.value ?: 0.0
+            Column(Modifier.padding(vertical = 5.dp)) {
+                Row(Modifier.fillMaxWidth().padding(bottom = 4.dp), horizontalArrangement = Arrangement.SpaceBetween) {
+                    Text(skill.n ?: "—", style = MaterialTheme.typography.labelMedium, color = MaterialTheme.colorScheme.onSurfaceVariant)
+                    Text(formatSkill(value), style = MaterialTheme.typography.labelMedium, color = MaterialTheme.colorScheme.onSurfaceVariant, fontWeight = FontWeight.Medium)
+                }
+                StatBar((value / SKILL_CAP).toFloat())
+            }
+        }
+    }
+}
+
+@OptIn(ExperimentalLayoutApi::class)
+@Composable
+private fun EquipmentBlock(equipment: List<EquipmentDto>) {
+    if (equipment.isEmpty()) return
+    SheetCard(R.string.player_char_equipment) {
+        equipment.forEach { item ->
+            Column(Modifier.fillMaxWidth().padding(vertical = 6.dp)) {
+                Text(
+                    item.layer ?: stringResource(R.string.player_char_item),
+                    style = MaterialTheme.typography.bodyLarge,
+                )
+                val meta = listOfNotNull(
+                    item.itemId?.let { stringResource(R.string.player_char_item_id, it) },
+                    item.hue?.takeIf { it != 0 }?.let { stringResource(R.string.player_char_item_hue, it) },
+                ).joinToString("  ·  ")
+                if (meta.isNotBlank()) {
+                    Text(meta, style = MaterialTheme.typography.labelSmall, color = MaterialTheme.colorScheme.onSurfaceVariant)
+                }
+                val mods = item.mods.orEmpty()
+                if (mods.isNotEmpty()) {
+                    FlowRow(Modifier.padding(top = 4.dp), horizontalArrangement = Arrangement.spacedBy(6.dp)) {
+                        mods.forEach { (k, v) -> Chip("$k ${jsonText(v)}") }
+                    }
+                }
+            }
+        }
+    }
+}
+
+@Composable
+private fun SheetCard(titleRes: Int, content: @Composable () -> Unit) {
+    Card(Modifier.fillMaxWidth()) {
+        Column(Modifier.padding(16.dp)) {
+            Text(stringResource(titleRes), style = MaterialTheme.typography.titleMedium)
+            content()
+        }
+    }
+}
+
+// ── Pure helpers (unit-tested) ───────────────────────────────────────────────
+
+/** ServUO's default skill cap; used to scale the skill meter fill (0..1). */
+private const val SKILL_CAP = 120.0
+
+/** Format a skill value: drop the ".0" on whole numbers, else one decimal. */
+internal fun formatSkill(value: Double): String =
+    if (value % 1.0 == 0.0) value.toInt().toString() else "%.1f".format(value)
+
+/**
+ * The human-readable title chips for a [TitlesDto] (parity with the website's
+ * `CharacterSheet.jsx#displayTitles`): fame/karma, skill title, and the selected
+ * reward title — but only if it is a literal string, not a bare cliloc number
+ * (the app ships no cliloc table). De-duplicated, blanks dropped.
+ */
+internal fun displayTitles(titles: TitlesDto?): List<String> {
+    if (titles == null) return emptyList()
+    val out = mutableListOf<String>()
+    titles.fameKarma?.let { out.add(it) }
+    titles.skill?.let { out.add(it) }
+    val reward = titles.reward
+    val sel = titles.selected ?: -1
+    val candidate = when {
+        sel in reward.indices -> reward[sel]
+        else -> reward.firstOrNull { it.isNotBlank() && !it.all(Char::isDigit) }
+    }
+    if (candidate != null && candidate.isNotBlank() && !candidate.all(Char::isDigit)) out.add(candidate)
+    return out.filter { it.isNotBlank() }.distinct()
+}
+
+private fun jsonText(element: kotlinx.serialization.json.JsonElement): String =
+    runCatching { element.jsonPrimitive.content }.getOrElse { element.toString() }

app/src/main/java/com/runicgateway/app/ui/player/CharacterViewModel.kt

@@ -0,0 +1,48 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.ui.player
+
+import androidx.lifecycle.SavedStateHandle
+import androidx.lifecycle.ViewModel
+import androidx.lifecycle.viewModelScope
+import com.runicgateway.app.data.api.dto.CharProfileDto
+import com.runicgateway.app.data.repository.PlayerShardRepository
+import com.runicgateway.app.ui.UiState
+import com.runicgateway.app.ui.navigation.Routes
+import com.runicgateway.app.ui.toUiState
+import dagger.hilt.android.lifecycle.HiltViewModel
+import kotlinx.coroutines.flow.MutableStateFlow
+import kotlinx.coroutines.flow.StateFlow
+import kotlinx.coroutines.flow.asStateFlow
+import kotlinx.coroutines.launch
+import javax.inject.Inject
+
+/**
+ * A single character sheet (PLAN.md §6.3), read from `/player/shard/char/:serial`
+ * for a character on one of the caller's linked accounts (ownership-checked
+ * server-side). A `503` renders as offline/retry, a `403` as not-found (§7).
+ * Text-only presentation for v1.
+ */
+@HiltViewModel
+class CharacterViewModel @Inject constructor(
+    private val repository: PlayerShardRepository,
+    savedStateHandle: SavedStateHandle,
+) : ViewModel() {
+
+    private val serial: String = savedStateHandle.get<String>(Routes.Args.SERIAL).orEmpty()
+
+    private val _state = MutableStateFlow<UiState<CharProfileDto>>(UiState.Loading)
+    val state: StateFlow<UiState<CharProfileDto>> = _state.asStateFlow()
+
+    init {
+        load()
+    }
+
+    fun load() {
+        _state.value = UiState.Loading
+        viewModelScope.launch {
+            _state.value = repository.char(serial).toUiState()
+        }
+    }
+}

app/src/main/java/com/runicgateway/app/ui/player/CharactersScreen.kt

@@ -0,0 +1,243 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.ui.player
+
+import androidx.compose.foundation.clickable
+import androidx.compose.foundation.layout.Arrangement
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.Row
+import androidx.compose.foundation.layout.fillMaxSize
+import androidx.compose.foundation.layout.fillMaxWidth
+import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.rememberScrollState
+import androidx.compose.foundation.verticalScroll
+import androidx.compose.material3.Button
+import androidx.compose.material3.Card
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.OutlinedTextField
+import androidx.compose.material3.Text
+import androidx.compose.material3.TextButton
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.getValue
+import androidx.compose.runtime.mutableStateOf
+import androidx.compose.runtime.saveable.rememberSaveable
+import androidx.compose.runtime.setValue
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.res.stringResource
+import androidx.compose.ui.text.input.KeyboardType
+import androidx.compose.ui.text.input.PasswordVisualTransformation
+import androidx.compose.ui.unit.dp
+import androidx.compose.foundation.text.KeyboardOptions
+import androidx.hilt.navigation.compose.hiltViewModel
+import androidx.lifecycle.compose.collectAsStateWithLifecycle
+import com.runicgateway.app.R
+import com.runicgateway.app.data.api.dto.RosterCharDto
+import com.runicgateway.app.ui.ErrorKind
+import com.runicgateway.app.ui.UiState
+import com.runicgateway.app.ui.components.ErrorView
+import com.runicgateway.app.ui.components.LoadingView
+import com.runicgateway.app.ui.components.PillTone
+import com.runicgateway.app.ui.components.StatusPill
+
+/**
+ * The player's linked game accounts + character rosters (PLAN.md §6.3). Tapping a
+ * character opens its text-only sheet. Not-yet-linked players get the `[link` code
+ * prompt (and, when the shard offers it, a hybrid signup form).
+ */
+@Composable
+fun CharactersScreen(
+    onOpenChar: (String) -> Unit,
+    modifier: Modifier = Modifier,
+    viewModel: CharactersViewModel = hiltViewModel(),
+) {
+    val state by viewModel.state.collectAsStateWithLifecycle()
+
+    when (val accounts = state.accounts) {
+        is UiState.Loading -> LoadingView(modifier)
+        is UiState.Error -> ErrorView(accounts.kind, onRetry = viewModel::load, modifier = modifier)
+        is UiState.Success -> Column(
+            modifier = modifier
+                .fillMaxSize()
+                .verticalScroll(rememberScrollState())
+                .padding(16.dp),
+            verticalArrangement = Arrangement.spacedBy(12.dp),
+        ) {
+            LinkCard(state, viewModel)
+            if (state.signupEnabled) CreateAccountCard(state, viewModel)
+
+            if (accounts.data.isEmpty()) {
+                Text(
+                    stringResource(R.string.player_characters_empty),
+                    style = MaterialTheme.typography.bodyMedium,
+                    color = MaterialTheme.colorScheme.onSurfaceVariant,
+                )
+            } else {
+                accounts.data.forEach { account ->
+                    AccountRoster(
+                        account = account,
+                        roster = state.rosters[account] ?: UiState.Loading,
+                        onRetry = { viewModel.loadRoster(account) },
+                        onOpenChar = onOpenChar,
+                    )
+                }
+            }
+        }
+    }
+}
+
+@Composable
+private fun LinkCard(state: CharactersViewModel.State, viewModel: CharactersViewModel) {
+    var code by rememberSaveable { mutableStateOf("") }
+    Card(Modifier.fillMaxWidth()) {
+        Column(Modifier.padding(16.dp)) {
+            Text(stringResource(R.string.player_link_title), style = MaterialTheme.typography.titleMedium)
+            Text(
+                stringResource(R.string.player_link_hint),
+                style = MaterialTheme.typography.bodySmall,
+                color = MaterialTheme.colorScheme.onSurfaceVariant,
+                modifier = Modifier.padding(top = 6.dp),
+            )
+            OutlinedTextField(
+                value = code,
+                onValueChange = { code = it.uppercase() },
+                singleLine = true,
+                enabled = !state.busy,
+                label = { Text(stringResource(R.string.player_link_code)) },
+                modifier = Modifier.fillMaxWidth().padding(top = 12.dp),
+            )
+            Button(
+                onClick = { viewModel.link(code); code = "" },
+                enabled = !state.busy && code.isNotBlank(),
+                modifier = Modifier.padding(top = 12.dp),
+            ) { Text(stringResource(R.string.player_link_action)) }
+            FormFeedback(state.feedback)
+        }
+    }
+}
+
+@Composable
+private fun CreateAccountCard(state: CharactersViewModel.State, viewModel: CharactersViewModel) {
+    var account by rememberSaveable { mutableStateOf("") }
+    var password by rememberSaveable { mutableStateOf("") }
+    Card(Modifier.fillMaxWidth()) {
+        Column(Modifier.padding(16.dp)) {
+            Text(stringResource(R.string.player_create_title), style = MaterialTheme.typography.titleMedium)
+            OutlinedTextField(
+                value = account,
+                onValueChange = { account = it },
+                singleLine = true,
+                enabled = !state.busy,
+                label = { Text(stringResource(R.string.player_create_account)) },
+                modifier = Modifier.fillMaxWidth().padding(top = 12.dp),
+            )
+            OutlinedTextField(
+                value = password,
+                onValueChange = { password = it },
+                singleLine = true,
+                enabled = !state.busy,
+                label = { Text(stringResource(R.string.player_create_password)) },
+                visualTransformation = PasswordVisualTransformation(),
+                keyboardOptions = KeyboardOptions(keyboardType = KeyboardType.Password),
+                modifier = Modifier.fillMaxWidth().padding(top = 12.dp),
+            )
+            Button(
+                onClick = { viewModel.createAccount(account, password); password = "" },
+                enabled = !state.busy && account.isNotBlank() && password.length >= 8,
+                modifier = Modifier.padding(top = 12.dp),
+            ) { Text(stringResource(R.string.player_create_action)) }
+        }
+    }
+}
+
+@Composable
+private fun AccountRoster(
+    account: String,
+    roster: UiState<List<RosterCharDto>>,
+    onRetry: () -> Unit,
+    onOpenChar: (String) -> Unit,
+) {
+    Column {
+        Text(
+            account,
+            style = MaterialTheme.typography.titleSmall,
+            color = MaterialTheme.colorScheme.primary,
+            modifier = Modifier.padding(vertical = 8.dp),
+        )
+        when (roster) {
+            is UiState.Loading -> Text(
+                stringResource(R.string.player_roster_loading),
+                style = MaterialTheme.typography.bodySmall,
+                color = MaterialTheme.colorScheme.onSurfaceVariant,
+            )
+            is UiState.Error -> RosterError(roster.kind, onRetry)
+            is UiState.Success -> {
+                if (roster.data.isEmpty()) {
+                    Text(
+                        stringResource(R.string.player_roster_empty),
+                        style = MaterialTheme.typography.bodySmall,
+                        color = MaterialTheme.colorScheme.onSurfaceVariant,
+                    )
+                } else {
+                    roster.data.forEach { CharRow(it, onOpenChar) }
+                }
+            }
+        }
+    }
+}
+
+@Composable
+private fun RosterError(kind: ErrorKind, onRetry: () -> Unit) {
+    Row(verticalAlignment = Alignment.CenterVertically) {
+        Text(
+            stringResource(
+                if (kind == ErrorKind.SHARD_OFFLINE) R.string.error_shard_offline else R.string.error_server,
+            ),
+            style = MaterialTheme.typography.bodySmall,
+            color = MaterialTheme.colorScheme.onSurfaceVariant,
+            modifier = Modifier.weight(1f),
+        )
+        TextButton(onClick = onRetry) { Text(stringResource(R.string.action_retry)) }
+    }
+}
+
+@Composable
+private fun CharRow(char: RosterCharDto, onOpenChar: (String) -> Unit) {
+    Card(
+        Modifier
+            .fillMaxWidth()
+            .padding(vertical = 4.dp)
+            .clickable(enabled = char.serial.isNotBlank()) { onOpenChar(char.serial) },
+    ) {
+        Row(
+            Modifier.fillMaxWidth().padding(14.dp),
+            verticalAlignment = Alignment.CenterVertically,
+        ) {
+            Text(
+                char.name ?: stringResource(R.string.player_char_unknown),
+                style = MaterialTheme.typography.bodyLarge,
+                modifier = Modifier.weight(1f),
+            )
+            StatusPill(
+                text = stringResource(
+                    if (char.online) R.string.player_char_online else R.string.player_char_offline,
+                ),
+                tone = if (char.online) PillTone.Success else PillTone.Neutral,
+                modifier = Modifier.padding(end = 8.dp),
+            )
+            Text("›", style = MaterialTheme.typography.titleMedium, color = MaterialTheme.colorScheme.onSurfaceVariant)
+        }
+    }
+}
+
+@Composable
+private fun FormFeedback(feedback: CharactersViewModel.Feedback?) {
+    if (feedback == null) return
+    Text(
+        text = stringResource(feedback.messageRes),
+        style = MaterialTheme.typography.bodySmall,
+        color = if (feedback.ok) MaterialTheme.colorScheme.primary else MaterialTheme.colorScheme.error,
+        modifier = Modifier.padding(top = 10.dp),
+    )
+}

app/src/main/java/com/runicgateway/app/ui/player/CharactersViewModel.kt

@@ -0,0 +1,140 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.ui.player
+
+import androidx.annotation.StringRes
+import androidx.lifecycle.ViewModel
+import androidx.lifecycle.viewModelScope
+import com.runicgateway.app.R
+import com.runicgateway.app.core.result.ApiResult
+import com.runicgateway.app.core.result.map
+import com.runicgateway.app.data.api.dto.RosterCharDto
+import com.runicgateway.app.data.repository.PlayerShardRepository
+import com.runicgateway.app.data.repository.SettingsRepository
+import com.runicgateway.app.ui.UiState
+import com.runicgateway.app.ui.toUiState
+import dagger.hilt.android.lifecycle.HiltViewModel
+import kotlinx.coroutines.flow.MutableStateFlow
+import kotlinx.coroutines.flow.StateFlow
+import kotlinx.coroutines.flow.asStateFlow
+import kotlinx.coroutines.flow.update
+import kotlinx.coroutines.launch
+import javax.inject.Inject
+
+/**
+ * The player's linked game accounts + per-account character rosters (PLAN.md §6.3):
+ * link a game account with a `[link` one-time code (or, when the shard offers it,
+ * a hybrid signup), then browse characters and open a text-only sheet. A per-account
+ * roster carries its own load state so a down shard degrades that account to a
+ * retry without blocking the rest (§7).
+ */
+@HiltViewModel
+class CharactersViewModel @Inject constructor(
+    private val repository: PlayerShardRepository,
+    private val settingsRepository: SettingsRepository,
+) : ViewModel() {
+
+    /** A one-shot banner for the link / create-account forms. */
+    data class Feedback(val ok: Boolean, @param:StringRes val messageRes: Int)
+
+    data class State(
+        val accounts: UiState<List<String>> = UiState.Loading,
+        val rosters: Map<String, UiState<List<RosterCharDto>>> = emptyMap(),
+        /** Whether the shard currently offers hybrid game-account signup. */
+        val signupEnabled: Boolean = false,
+        val busy: Boolean = false,
+        val feedback: Feedback? = null,
+    )
+
+    private val _state = MutableStateFlow(State())
+    val state: StateFlow<State> = _state.asStateFlow()
+
+    init {
+        load()
+    }
+
+    fun load() {
+        _state.update { it.copy(accounts = UiState.Loading, rosters = emptyMap()) }
+        viewModelScope.launch {
+            when (val result = repository.accounts()) {
+                is ApiResult.Ok -> {
+                    val names = result.data.map { it.account }
+                    _state.update { it.copy(accounts = UiState.Success(names)) }
+                    names.forEach { loadRoster(it) }
+                }
+                else -> _state.update { it.copy(accounts = result.map { emptyList<String>() }.toUiState()) }
+            }
+        }
+        // Non-critical: whether hybrid signup is offered right now.
+        viewModelScope.launch {
+            when (val settings = settingsRepository.getSettings()) {
+                is ApiResult.Ok -> _state.update { it.copy(signupEnabled = settings.data.gameAccountSignup) }
+                else -> Unit
+            }
+        }
+    }
+
+    fun loadRoster(account: String) {
+        _state.update { it.copy(rosters = it.rosters + (account to UiState.Loading)) }
+        viewModelScope.launch {
+            val roster = repository.roster(account).map { it.chars }.toUiState()
+            _state.update { it.copy(rosters = it.rosters + (account to roster)) }
+        }
+    }
+
+    fun clearFeedback() = _state.update { it.copy(feedback = null) }
+
+    fun link(code: String) {
+        if (_state.value.busy || code.isBlank()) return
+        _state.update { it.copy(busy = true, feedback = null) }
+        viewModelScope.launch {
+            when (val result = repository.link(code.trim())) {
+                is ApiResult.Ok -> {
+                    _state.update { it.copy(busy = false, feedback = Feedback(true, R.string.player_link_ok)) }
+                    load()
+                }
+                is ApiResult.HttpError -> _state.update {
+                    it.copy(busy = false, feedback = Feedback(false, linkErrorRes(result.status)))
+                }
+                is ApiResult.NetworkError -> _state.update {
+                    it.copy(busy = false, feedback = Feedback(false, R.string.error_network))
+                }
+            }
+        }
+    }
+
+    fun createAccount(account: String, password: String) {
+        if (_state.value.busy || account.isBlank() || password.length < 8) return
+        _state.update { it.copy(busy = true, feedback = null) }
+        viewModelScope.launch {
+            when (val result = repository.createAccount(account.trim(), password)) {
+                is ApiResult.Ok -> {
+                    _state.update { it.copy(busy = false, feedback = Feedback(true, R.string.player_create_ok)) }
+                    load()
+                }
+                is ApiResult.HttpError -> _state.update {
+                    it.copy(busy = false, feedback = Feedback(false, createErrorRes(result.status)))
+                }
+                is ApiResult.NetworkError -> _state.update {
+                    it.copy(busy = false, feedback = Feedback(false, R.string.error_network))
+                }
+            }
+        }
+    }
+
+    private fun linkErrorRes(status: Int): Int = when (status) {
+        400 -> R.string.player_link_bad_code
+        503 -> R.string.error_shard_offline
+        else -> R.string.player_link_error
+    }
+
+    private fun createErrorRes(status: Int): Int = when (status) {
+        409 -> R.string.player_create_taken
+        429 -> R.string.player_create_capped
+        403 -> R.string.player_create_unavailable
+        400 -> R.string.player_create_rejected
+        503 -> R.string.error_shard_offline
+        else -> R.string.player_create_error
+    }
+}

app/src/main/java/com/runicgateway/app/ui/player/MyHousesScreen.kt

@@ -0,0 +1,106 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.ui.player
+
+import androidx.compose.foundation.layout.Arrangement
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.Row
+import androidx.compose.foundation.layout.fillMaxSize
+import androidx.compose.foundation.layout.fillMaxWidth
+import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.lazy.LazyColumn
+import androidx.compose.foundation.lazy.items
+import androidx.compose.material3.Card
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.Text
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.getValue
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.res.stringResource
+import androidx.compose.ui.text.style.TextOverflow
+import androidx.compose.ui.unit.dp
+import androidx.hilt.navigation.compose.hiltViewModel
+import androidx.lifecycle.compose.collectAsStateWithLifecycle
+import com.runicgateway.app.R
+import com.runicgateway.app.data.api.dto.PlayerHouseDto
+import com.runicgateway.app.ui.UiState
+import com.runicgateway.app.ui.components.EmptyView
+import com.runicgateway.app.ui.components.ErrorView
+import com.runicgateway.app.ui.components.LoadingView
+
+/**
+ * The player's own houses with home/decay status (PLAN.md §6.3), text-only. An
+ * IDOC house is flagged prominently. Only the caller's own property is ever shown.
+ */
+@Composable
+fun MyHousesScreen(
+    modifier: Modifier = Modifier,
+    viewModel: MyHousesViewModel = hiltViewModel(),
+) {
+    val state by viewModel.state.collectAsStateWithLifecycle()
+    when (val s = state) {
+        is UiState.Loading -> LoadingView(modifier)
+        is UiState.Error -> ErrorView(s.kind, onRetry = viewModel::load, modifier = modifier)
+        is UiState.Success -> {
+            if (s.data.isEmpty()) {
+                EmptyView(stringResource(R.string.player_houses_empty), modifier)
+            } else {
+                LazyColumn(
+                    modifier = modifier.fillMaxSize().padding(horizontal = 16.dp),
+                    verticalArrangement = Arrangement.spacedBy(8.dp),
+                    contentPadding = androidx.compose.foundation.layout.PaddingValues(vertical = 16.dp),
+                ) {
+                    items(s.data, key = { it.serial }) { house -> HouseCard(house) }
+                }
+            }
+        }
+    }
+}
+
+@Composable
+private fun HouseCard(house: PlayerHouseDto) {
+    Card(Modifier.fillMaxWidth()) {
+        Column(Modifier.padding(16.dp)) {
+            Row(Modifier.fillMaxWidth()) {
+                Text(
+                    text = house.name?.takeIf { it.isNotBlank() }
+                        ?: house.region
+                        ?: stringResource(R.string.player_house_fallback),
+                    style = MaterialTheme.typography.titleMedium,
+                    maxLines = 1,
+                    overflow = TextOverflow.Ellipsis,
+                    modifier = Modifier.weight(1f),
+                )
+                if (house.isIdoc) {
+                    Text(
+                        stringResource(R.string.houses_idoc_badge),
+                        style = MaterialTheme.typography.labelMedium,
+                        color = MaterialTheme.colorScheme.error,
+                    )
+                }
+            }
+            house.stage?.takeIf { it.isNotBlank() }?.let {
+                Text(
+                    stringResource(R.string.player_house_stage, it),
+                    style = MaterialTheme.typography.bodySmall,
+                    color = if (house.isIdoc) MaterialTheme.colorScheme.error else MaterialTheme.colorScheme.onSurfaceVariant,
+                    modifier = Modifier.padding(top = 6.dp),
+                )
+            }
+            val where = listOfNotNull(
+                house.region,
+                house.map,
+                house.x?.let { "(${house.x}, ${house.y})" },
+            ).joinToString("  ·  ")
+            if (where.isNotBlank()) {
+                Text(
+                    where,
+                    style = MaterialTheme.typography.bodySmall,
+                    color = MaterialTheme.colorScheme.onSurfaceVariant,
+                    modifier = Modifier.padding(top = 4.dp),
+                )
+            }
+        }
+    }
+}

app/src/main/java/com/runicgateway/app/ui/player/MyHousesViewModel.kt

@@ -0,0 +1,41 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.ui.player
+
+import androidx.lifecycle.ViewModel
+import androidx.lifecycle.viewModelScope
+import com.runicgateway.app.data.api.dto.PlayerHouseDto
+import com.runicgateway.app.data.repository.PlayerShardRepository
+import com.runicgateway.app.ui.UiState
+import com.runicgateway.app.ui.toUiState
+import dagger.hilt.android.lifecycle.HiltViewModel
+import kotlinx.coroutines.flow.MutableStateFlow
+import kotlinx.coroutines.flow.StateFlow
+import kotlinx.coroutines.flow.asStateFlow
+import kotlinx.coroutines.launch
+import javax.inject.Inject
+
+/**
+ * The player's OWN houses with decay/IDOC status (PLAN.md §6.3), read from
+ * `/player/shard/houses` — never anyone else's. A `503` renders as offline/retry (§7).
+ */
+@HiltViewModel
+class MyHousesViewModel @Inject constructor(
+    private val repository: PlayerShardRepository,
+) : ViewModel() {
+
+    private val _state = MutableStateFlow<UiState<List<PlayerHouseDto>>>(UiState.Loading)
+    val state: StateFlow<UiState<List<PlayerHouseDto>>> = _state.asStateFlow()
+
+    init {
+        load()
+    }
+
+    fun load() {
+        _state.value = UiState.Loading
+        viewModelScope.launch {
+            _state.value = repository.houses().toUiState()
+        }
+    }
+}

app/src/main/java/com/runicgateway/app/ui/player/VendorsScreen.kt

@@ -0,0 +1,229 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.ui.player
+
+import androidx.compose.foundation.layout.Arrangement
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.Row
+import androidx.compose.foundation.layout.fillMaxSize
+import androidx.compose.foundation.layout.fillMaxWidth
+import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.rememberScrollState
+import androidx.compose.foundation.verticalScroll
+import androidx.compose.material3.Card
+import androidx.compose.material3.HorizontalDivider
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.Text
+import androidx.compose.material3.TextButton
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.getValue
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.res.stringResource
+import androidx.compose.ui.unit.dp
+import androidx.hilt.navigation.compose.hiltViewModel
+import androidx.lifecycle.compose.collectAsStateWithLifecycle
+import com.runicgateway.app.R
+import com.runicgateway.app.data.api.dto.VendorDto
+import com.runicgateway.app.data.api.dto.VendorListingDto
+import com.runicgateway.app.data.api.dto.VendorSaleDto
+import com.runicgateway.app.ui.ErrorKind
+import com.runicgateway.app.ui.UiState
+import com.runicgateway.app.ui.components.ErrorView
+import com.runicgateway.app.ui.components.LoadingView
+import java.text.DateFormat
+import java.util.Date
+
+/**
+ * The player's own player-vendors + recent sales (PLAN.md §6.3), text-only. Vendor
+ * shops group under their game account; recent sales list across all linked
+ * accounts. A down shard degrades to a per-account retry (§7).
+ */
+@Composable
+fun VendorsScreen(
+    modifier: Modifier = Modifier,
+    viewModel: VendorsViewModel = hiltViewModel(),
+) {
+    val state by viewModel.state.collectAsStateWithLifecycle()
+
+    when (val accounts = state.accounts) {
+        is UiState.Loading -> LoadingView(modifier)
+        is UiState.Error -> ErrorView(accounts.kind, onRetry = viewModel::load, modifier = modifier)
+        is UiState.Success -> Column(
+            modifier = modifier
+                .fillMaxSize()
+                .verticalScroll(rememberScrollState())
+                .padding(16.dp),
+            verticalArrangement = Arrangement.spacedBy(12.dp),
+        ) {
+            SalesCard(state.sales)
+
+            if (accounts.data.isEmpty()) {
+                Text(
+                    stringResource(R.string.player_vendors_no_accounts),
+                    style = MaterialTheme.typography.bodyMedium,
+                    color = MaterialTheme.colorScheme.onSurfaceVariant,
+                )
+            } else {
+                accounts.data.forEach { account ->
+                    AccountVendors(
+                        account = account,
+                        vendors = state.vendors[account] ?: UiState.Loading,
+                        onRetry = { viewModel.loadVendors(account) },
+                    )
+                }
+            }
+        }
+    }
+}
+
+@Composable
+private fun SalesCard(sales: UiState<List<VendorSaleDto>>) {
+    Card(Modifier.fillMaxWidth()) {
+        Column(Modifier.padding(16.dp)) {
+            Text(stringResource(R.string.player_sales_title), style = MaterialTheme.typography.titleMedium)
+            when (sales) {
+                is UiState.Loading -> Text(
+                    stringResource(R.string.player_roster_loading),
+                    style = MaterialTheme.typography.bodySmall,
+                    color = MaterialTheme.colorScheme.onSurfaceVariant,
+                    modifier = Modifier.padding(top = 8.dp),
+                )
+                is UiState.Error -> Text(
+                    stringResource(R.string.error_server),
+                    style = MaterialTheme.typography.bodySmall,
+                    color = MaterialTheme.colorScheme.onSurfaceVariant,
+                    modifier = Modifier.padding(top = 8.dp),
+                )
+                is UiState.Success -> {
+                    if (sales.data.isEmpty()) {
+                        Text(
+                            stringResource(R.string.player_sales_empty),
+                            style = MaterialTheme.typography.bodySmall,
+                            color = MaterialTheme.colorScheme.onSurfaceVariant,
+                            modifier = Modifier.padding(top = 8.dp),
+                        )
+                    } else {
+                        sales.data.forEach { SaleRow(it) }
+                    }
+                }
+            }
+        }
+    }
+}
+
+@Composable
+private fun SaleRow(sale: VendorSaleDto) {
+    Row(Modifier.fillMaxWidth().padding(top = 10.dp), horizontalArrangement = Arrangement.SpaceBetween) {
+        Column(Modifier.padding(end = 12.dp)) {
+            Text(
+                sale.itemType ?: stringResource(R.string.player_char_item),
+                style = MaterialTheme.typography.bodyMedium,
+            )
+            sale.t?.let {
+                Text(
+                    DateFormat.getDateTimeInstance(DateFormat.MEDIUM, DateFormat.SHORT).format(Date(it)),
+                    style = MaterialTheme.typography.labelSmall,
+                    color = MaterialTheme.colorScheme.onSurfaceVariant,
+                )
+            }
+        }
+        Text(
+            stringResource(R.string.player_gold_amount, "%,d".format(sale.price ?: 0L)),
+            style = MaterialTheme.typography.bodyMedium,
+        )
+    }
+}
+
+@Composable
+private fun AccountVendors(
+    account: String,
+    vendors: UiState<List<VendorDto>>,
+    onRetry: () -> Unit,
+) {
+    Column {
+        Text(
+            account,
+            style = MaterialTheme.typography.titleSmall,
+            color = MaterialTheme.colorScheme.primary,
+            modifier = Modifier.padding(vertical = 8.dp),
+        )
+        when (vendors) {
+            is UiState.Loading -> Text(
+                stringResource(R.string.player_roster_loading),
+                style = MaterialTheme.typography.bodySmall,
+                color = MaterialTheme.colorScheme.onSurfaceVariant,
+            )
+            is UiState.Error -> VendorError(vendors.kind, onRetry)
+            is UiState.Success -> {
+                if (vendors.data.isEmpty()) {
+                    Text(
+                        stringResource(R.string.player_vendors_empty),
+                        style = MaterialTheme.typography.bodySmall,
+                        color = MaterialTheme.colorScheme.onSurfaceVariant,
+                    )
+                } else {
+                    vendors.data.forEach { VendorCard(it) }
+                }
+            }
+        }
+    }
+}
+
+@Composable
+private fun VendorError(kind: ErrorKind, onRetry: () -> Unit) {
+    Row {
+        Text(
+            stringResource(if (kind == ErrorKind.SHARD_OFFLINE) R.string.error_shard_offline else R.string.error_server),
+            style = MaterialTheme.typography.bodySmall,
+            color = MaterialTheme.colorScheme.onSurfaceVariant,
+            modifier = Modifier.weight(1f),
+        )
+        TextButton(onClick = onRetry) { Text(stringResource(R.string.action_retry)) }
+    }
+}
+
+@Composable
+private fun VendorCard(vendor: VendorDto) {
+    Card(Modifier.fillMaxWidth().padding(vertical = 4.dp)) {
+        Column(Modifier.padding(16.dp)) {
+            Text(
+                vendor.shopName ?: stringResource(R.string.player_vendor_fallback),
+                style = MaterialTheme.typography.titleMedium,
+            )
+            val meta = listOfNotNull(
+                vendor.holdGold?.let { stringResource(R.string.player_vendor_hold, "%,d".format(it)) },
+                vendor.map,
+            ).joinToString("  ·  ")
+            if (meta.isNotBlank()) {
+                Text(meta, style = MaterialTheme.typography.labelSmall, color = MaterialTheme.colorScheme.onSurfaceVariant, modifier = Modifier.padding(top = 2.dp))
+            }
+            if (vendor.listings.isNotEmpty()) {
+                HorizontalDivider(Modifier.padding(vertical = 8.dp))
+                vendor.listings.forEach { ListingRow(it) }
+            } else {
+                Text(
+                    stringResource(R.string.player_vendor_no_listings),
+                    style = MaterialTheme.typography.bodySmall,
+                    color = MaterialTheme.colorScheme.onSurfaceVariant,
+                    modifier = Modifier.padding(top = 8.dp),
+                )
+            }
+        }
+    }
+}
+
+@Composable
+private fun ListingRow(listing: VendorListingDto) {
+    Row(Modifier.fillMaxWidth().padding(vertical = 3.dp), horizontalArrangement = Arrangement.SpaceBetween) {
+        Text(
+            stringResource(R.string.player_listing_item, listing.itemId ?: 0, listing.amount ?: 1),
+            style = MaterialTheme.typography.bodySmall,
+            modifier = Modifier.weight(1f),
+        )
+        Text(
+            stringResource(R.string.player_gold_amount, "%,d".format(listing.price ?: 0L)),
+            style = MaterialTheme.typography.bodySmall,
+        )
+    }
+}

app/src/main/java/com/runicgateway/app/ui/player/VendorsViewModel.kt

@@ -0,0 +1,72 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.ui.player
+
+import androidx.lifecycle.ViewModel
+import androidx.lifecycle.viewModelScope
+import com.runicgateway.app.core.result.ApiResult
+import com.runicgateway.app.core.result.map
+import com.runicgateway.app.data.api.dto.VendorDto
+import com.runicgateway.app.data.api.dto.VendorSaleDto
+import com.runicgateway.app.data.repository.PlayerShardRepository
+import com.runicgateway.app.ui.UiState
+import com.runicgateway.app.ui.toUiState
+import dagger.hilt.android.lifecycle.HiltViewModel
+import kotlinx.coroutines.flow.MutableStateFlow
+import kotlinx.coroutines.flow.StateFlow
+import kotlinx.coroutines.flow.asStateFlow
+import kotlinx.coroutines.flow.update
+import kotlinx.coroutines.launch
+import javax.inject.Inject
+
+/**
+ * The player's own player-vendors and recent vendor sales (PLAN.md §6.3): a
+ * per-account vendor snapshot (shops + listings) over `/player/shard/vendors/:account`
+ * plus the recent-sales log over `/player/shard/sales`. Each account's snapshot
+ * carries its own load state so a down shard degrades one account to a retry (§7).
+ * Text-only listings — item names are clilocs the app has no table for.
+ */
+@HiltViewModel
+class VendorsViewModel @Inject constructor(
+    private val repository: PlayerShardRepository,
+) : ViewModel() {
+
+    data class State(
+        val accounts: UiState<List<String>> = UiState.Loading,
+        val vendors: Map<String, UiState<List<VendorDto>>> = emptyMap(),
+        val sales: UiState<List<VendorSaleDto>> = UiState.Loading,
+    )
+
+    private val _state = MutableStateFlow(State())
+    val state: StateFlow<State> = _state.asStateFlow()
+
+    init {
+        load()
+    }
+
+    fun load() {
+        _state.update { it.copy(accounts = UiState.Loading, vendors = emptyMap(), sales = UiState.Loading) }
+        viewModelScope.launch {
+            when (val result = repository.accounts()) {
+                is ApiResult.Ok -> {
+                    val names = result.data.map { it.account }
+                    _state.update { it.copy(accounts = UiState.Success(names)) }
+                    names.forEach { loadVendors(it) }
+                }
+                else -> _state.update { it.copy(accounts = result.map { emptyList<String>() }.toUiState()) }
+            }
+        }
+        viewModelScope.launch {
+            _state.update { it.copy(sales = repository.sales().toUiState()) }
+        }
+    }
+
+    fun loadVendors(account: String) {
+        _state.update { it.copy(vendors = it.vendors + (account to UiState.Loading)) }
+        viewModelScope.launch {
+            val vendors = repository.vendors(account).map { it.vendors }.toUiState()
+            _state.update { it.copy(vendors = it.vendors + (account to vendors)) }
+        }
+    }
+}

app/src/main/java/com/runicgateway/app/ui/shard/ChampsScreen.kt

@@ -20,6 +20,8 @@ import androidx.hilt.navigation.compose.hiltViewModel
 import androidx.lifecycle.compose.collectAsStateWithLifecycle
 import com.runicgateway.app.R
 import com.runicgateway.app.data.api.dto.ChampDto
+import com.runicgateway.app.ui.components.PillTone
+import com.runicgateway.app.ui.components.StatusPill
 
 /** The champion-spawn board (PLAN.md §6.2), live via SSE deltas. */
 @Composable
@@ -53,11 +55,7 @@ private fun ChampCard(champ: ChampDto) {
                     modifier = Modifier.weight(1f),
                 )
                 champ.status?.let {
-                    Text(
-                        text = it.replaceFirstChar { c -> c.uppercase() },
-                        style = MaterialTheme.typography.labelMedium,
-                        color = MaterialTheme.colorScheme.primary,
-                    )
+                    StatusPill(text = it, tone = champStatusTone(it))
                 }
             }
             val detail = champDetail(champ)
@@ -82,6 +80,13 @@ private fun ChampCard(champ: ChampDto) {
     }
 }
 
+/** Map a champ status to a pill tone: live spawns read green, cooldowns amber. */
+private fun champStatusTone(status: String): PillTone = when (status.lowercase()) {
+    "active", "up", "spawned" -> PillTone.Success
+    "cooldown", "restarting", "advancing" -> PillTone.Warning
+    else -> PillTone.Neutral
+}
+
 /** A short category-specific status line, mirroring the website's champ detail. */
 @Composable
 private fun champDetail(champ: ChampDto): String = when (champ.category) {

app/src/main/java/com/runicgateway/app/ui/shard/HousesScreen.kt

@@ -20,6 +20,8 @@ import androidx.hilt.navigation.compose.hiltViewModel
 import androidx.lifecycle.compose.collectAsStateWithLifecycle
 import com.runicgateway.app.R
 import com.runicgateway.app.data.api.dto.HouseDto
+import com.runicgateway.app.ui.components.PillTone
+import com.runicgateway.app.ui.components.StatusPill
 
 /** The public "falling houses" (IDOC) board (PLAN.md §6.2), live via `house.decay`. */
 @Composable
@@ -54,10 +56,9 @@ private fun HouseCard(house: HouseDto) {
                     overflow = TextOverflow.Ellipsis,
                     modifier = Modifier.weight(1f),
                 )
-                Text(
+                StatusPill(
                     text = stringResource(R.string.houses_idoc_badge),
-                    style = MaterialTheme.typography.labelMedium,
-                    color = MaterialTheme.colorScheme.error,
+                    tone = PillTone.Danger,
                 )
             }
             val where = listOfNotNull(

app/src/main/java/com/runicgateway/app/ui/shard/ShardComponents.kt

@@ -27,6 +27,8 @@ import com.runicgateway.app.ui.UiState
 import com.runicgateway.app.ui.components.EmptyView
 import com.runicgateway.app.ui.components.ErrorView
 import com.runicgateway.app.ui.components.LoadingView
+import com.runicgateway.app.ui.theme.ShardSuccess
+import com.runicgateway.app.ui.theme.ShardSuccessDot
 
 /**
  * A small "Live / Offline" indicator for the shard screens (PLAN.md §6.2): a dot +
@@ -34,22 +36,19 @@ import com.runicgateway.app.ui.components.LoadingView
  */
 @Composable
 fun LiveChip(connected: Boolean, modifier: Modifier = Modifier) {
-    val color = if (connected) {
-        MaterialTheme.colorScheme.primary
-    } else {
-        MaterialTheme.colorScheme.onSurfaceVariant
-    }
+    val dotColor = if (connected) ShardSuccessDot else MaterialTheme.colorScheme.onSurfaceVariant
+    val textColor = if (connected) ShardSuccess else MaterialTheme.colorScheme.onSurfaceVariant
     Row(modifier = modifier, verticalAlignment = Alignment.CenterVertically) {
         androidx.compose.foundation.layout.Box(
             Modifier
                 .size(8.dp)
                 .clip(CircleShape)
-                .background(color),
+                .background(dotColor),
         )
         Text(
             text = stringResource(if (connected) R.string.shard_live else R.string.shard_offline),
             style = MaterialTheme.typography.labelMedium,
-            color = color,
+            color = textColor,
             modifier = Modifier.padding(start = 6.dp),
         )
     }

app/src/main/java/com/runicgateway/app/ui/shard/ShardScreen.kt

@@ -30,7 +30,11 @@ import com.runicgateway.app.data.api.dto.OnlineStaffDto
 import com.runicgateway.app.data.api.dto.ShardStatusDto
 import com.runicgateway.app.ui.UiState
 import com.runicgateway.app.ui.components.ErrorView
+import com.runicgateway.app.ui.components.FeatureCard
 import com.runicgateway.app.ui.components.LoadingView
+import com.runicgateway.app.ui.components.PillTone
+import com.runicgateway.app.ui.components.SectionLabel
+import com.runicgateway.app.ui.components.StatusPill
 
 /** Board destinations reachable from the hub. */
 enum class ShardBoard { CHAMPS, GUILDS, GOVERNORS, HOUSES }
@@ -114,29 +118,42 @@ private fun HubContent(
 
 @Composable
 private fun StatusCard(status: ShardStatusDto, presenceCount: Int?) {
-    Card(Modifier.fillMaxWidth()) {
-        Column(Modifier.padding(16.dp)) {
-            Text(
-                text = stringResource(
-                    if (status.isOnline) R.string.shard_status_online else R.string.shard_status_offline,
-                ),
-                style = MaterialTheme.typography.titleMedium,
-                color = if (status.isOnline) MaterialTheme.colorScheme.primary else MaterialTheme.colorScheme.onSurfaceVariant,
-            )
-            val online = presenceCount ?: status.onlineCount
-            Text(
-                text = stringResource(R.string.shard_online_count, online),
-                style = MaterialTheme.typography.bodyMedium,
-                modifier = Modifier.padding(top = 6.dp),
-            )
-            status.economy?.gold?.let { gold ->
+    FeatureCard {
+        Row(
+            Modifier.fillMaxWidth(),
+            horizontalArrangement = Arrangement.SpaceBetween,
+            verticalAlignment = Alignment.CenterVertically,
+        ) {
+            Column(Modifier.weight(1f)) {
                 Text(
-                    text = stringResource(R.string.shard_economy_gold, "%,.0f".format(gold)),
-                    style = MaterialTheme.typography.bodySmall,
-                    color = MaterialTheme.colorScheme.onSurfaceVariant,
-                    modifier = Modifier.padding(top = 2.dp),
+                    text = stringResource(
+                        if (status.isOnline) R.string.shard_status_online else R.string.shard_status_offline,
+                    ),
+                    style = MaterialTheme.typography.titleMedium,
+                    color = MaterialTheme.colorScheme.onSurface,
                 )
+                val online = presenceCount ?: status.onlineCount
+                Text(
+                    text = stringResource(R.string.shard_online_count, online),
+                    style = MaterialTheme.typography.labelMedium,
+                    color = MaterialTheme.colorScheme.onSurfaceVariant,
+                    modifier = Modifier.padding(top = 6.dp),
+                )
+                status.economy?.gold?.let { gold ->
+                    Text(
+                        text = stringResource(R.string.shard_economy_gold, "%,.0f".format(gold)),
+                        style = MaterialTheme.typography.bodySmall,
+                        color = MaterialTheme.colorScheme.onSurfaceVariant,
+                        modifier = Modifier.padding(top = 2.dp),
+                    )
+                }
             }
+            StatusPill(
+                text = stringResource(
+                    if (status.isOnline) R.string.shard_live else R.string.shard_offline,
+                ),
+                tone = if (status.isOnline) PillTone.Success else PillTone.Neutral,
+            )
         }
     }
 }
@@ -168,11 +185,7 @@ private fun BoardsCard(onOpenBoard: (ShardBoard) -> Unit) {
 
 @Composable
 private fun SectionHeader(text: String) {
-    Text(
-        text = text,
-        style = MaterialTheme.typography.titleSmall,
-        modifier = Modifier.padding(top = 4.dp),
-    )
+    SectionLabel(text = text, modifier = Modifier.padding(top = 4.dp))
 }
 
 @Composable

app/src/main/java/com/runicgateway/app/ui/theme/Color.kt

@@ -5,12 +5,44 @@ package com.runicgateway.app.ui.theme
 
 import androidx.compose.ui.graphics.Color
 
-// Placeholder palette for the M0 skeleton. The M5 design pass replaces this and
-// derives Material 3 colors from each shard's per-install branding (PLAN.md §3, §5).
-val Purple80 = Color(0xFFD0BCFF)
-val PurpleGrey80 = Color(0xFFCCC2DC)
-val Pink80 = Color(0xFFEFB8C8)
+// ─────────────────────────────────────────────────────────────────────────────
+// Shard-website palette (M5 design pass, docs/android/PLAN.md §M5). Deep blue-black
+// surfaces, a slate-blue accent, parchment serif text, and a light CTA fill —
+// mirrored from the "Runic Gateway Screens" design. Dark-only by design.
+// ─────────────────────────────────────────────────────────────────────────────
 
-val Purple40 = Color(0xFF6650A4)
-val PurpleGrey40 = Color(0xFF625B71)
-val Pink40 = Color(0xFF7D5260)
+// Surfaces
+val ShardPage = Color(0xFF0B0F14)       // app/page background
+val ShardSurface = Color(0xFF0E1318)     // screen background
+val ShardElevated = Color(0xFF11161D)    // top bar, inputs, drawer, list tracks
+val ShardCardTop = Color(0xFF192231)     // feature-card gradient (top)
+val ShardCardBottom = Color(0xFF141A21)  // feature-card gradient (bottom)
+
+// Lines
+val ShardOutline = Color(0xFF2A3544)     // borders / input outlines
+val ShardDivider = Color(0xFF1D2733)     // hairline row dividers
+
+// Text
+val ShardHeading = Color(0xFFEEF3F8)     // brightest headings
+val ShardHeadingDim = Color(0xFFE6EDF6)  // heading on surface
+val ShardBody = Color(0xFFC4CDD8)        // body copy
+val ShardMuted = Color(0xFFAEB8C4)       // secondary text
+val ShardFaint = Color(0xFF6F7D8E)       // meta / faint labels
+
+// Accent + CTA
+val ShardAccent = Color(0xFF7F99BD)      // links, secondary highlights
+val ShardCta = Color(0xFFCDD9E8)         // filled button surface
+val ShardOnCta = Color(0xFF0B0F14)       // text on the filled button
+
+// Neutral / info pill
+val ShardPillBg = Color(0xFF13243C)
+val ShardPillFg = Color(0xFFCDD9E8)
+
+// Semantic (status pills + dots)
+val ShardSuccess = Color(0xFF7FD0A4)
+val ShardSuccessBg = Color(0x295FB98A)   // rgba(95,185,138,0.16)
+val ShardSuccessDot = Color(0xFF5FB98A)
+val ShardWarning = Color(0xFFE6C26A)
+val ShardWarningBg = Color(0x2EE6C26A)   // rgba(230,194,106,0.18)
+val ShardDanger = Color(0xFFD98B84)
+val ShardDangerBg = Color(0x29D98B84)    // rgba(217,139,132,0.16)

app/src/main/java/com/runicgateway/app/ui/theme/Font.kt

@@ -0,0 +1,40 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.ui.theme
+
+import androidx.compose.ui.text.ExperimentalTextApi
+import androidx.compose.ui.text.font.Font
+import androidx.compose.ui.text.font.FontFamily
+import androidx.compose.ui.text.font.FontVariation
+import androidx.compose.ui.text.font.FontWeight
+import com.runicgateway.app.R
+
+/**
+ * Type families for the M5 shard-website design pass (docs/android/PLAN.md §M5).
+ *
+ * - [Cinzel] — the engraved serif display face used for headings, screen titles,
+ *   and the top-bar title. Shipped as a single weight-axis **variable** font
+ *   (`res/font/cinzel_variable.ttf`, SIL OFL — see `app/licenses/Cinzel-OFL.txt`);
+ *   the 500/600/700 instances the design uses are pinned via [FontVariation]
+ *   (supported on API 26+, and our minSdk is 29).
+ * - [AppSerif] — the parchment body face. Android's platform serif is Noto Serif,
+ *   which reads as the design's Georgia body copy without bundling another binary.
+ * - [AppSans] — the label/meta/button face (the design's "Helvetica Neue" runs).
+ */
+@OptIn(ExperimentalTextApi::class)
+private fun cinzel(weight: FontWeight) =
+    Font(
+        R.font.cinzel_variable,
+        weight = weight,
+        variationSettings = FontVariation.Settings(FontVariation.weight(weight.weight)),
+    )
+
+val Cinzel = FontFamily(
+    cinzel(FontWeight.Medium),   // 500
+    cinzel(FontWeight.SemiBold), // 600
+    cinzel(FontWeight.Bold),     // 700
+)
+
+val AppSerif = FontFamily.Serif
+val AppSans = FontFamily.SansSerif

app/src/main/java/com/runicgateway/app/ui/theme/Theme.kt

@@ -3,54 +3,78 @@
  */
 package com.runicgateway.app.ui.theme
 
-import androidx.compose.foundation.isSystemInDarkTheme
+import androidx.compose.foundation.shape.RoundedCornerShape
 import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.Shapes
 import androidx.compose.material3.darkColorScheme
-import androidx.compose.material3.lightColorScheme
 import androidx.compose.runtime.Composable
 import androidx.compose.ui.graphics.Color
+import androidx.compose.ui.unit.dp
 
-private val DarkColorScheme = darkColorScheme(
-    primary = Purple80,
-    secondary = PurpleGrey80,
-    tertiary = Pink80,
+/**
+ * The shard-website color scheme (M5 design pass). The app is **dark-only** — the
+ * design is a single deep blue-black theme, so there is no light variant and the
+ * system light/dark setting is intentionally ignored. Material roles are mapped
+ * onto the palette in [ui/theme/Color.kt] so the ~20 token-based screens take on
+ * the theme without per-screen color work.
+ */
+private val ShardColorScheme = darkColorScheme(
+    primary = ShardCta,               // filled CTA buttons
+    onPrimary = ShardOnCta,
+    secondary = ShardAccent,          // links / secondary highlights
+    onSecondary = ShardOnCta,
+    tertiary = ShardAccent,
+    onTertiary = ShardOnCta,
+    background = ShardPage,
+    onBackground = ShardBody,
+    surface = ShardSurface,
+    onSurface = ShardBody,
+    surfaceVariant = ShardElevated,
+    onSurfaceVariant = ShardMuted,
+    surfaceContainer = ShardElevated,
+    surfaceContainerHigh = ShardElevated,
+    surfaceContainerLow = ShardSurface,
+    outline = ShardOutline,
+    outlineVariant = ShardDivider,
+    secondaryContainer = ShardPillBg, // neutral chips / selected drawer item
+    onSecondaryContainer = ShardPillFg,
+    error = ShardDanger,
+    onError = ShardOnCta,
+    errorContainer = ShardDangerBg,
+    onErrorContainer = ShardDanger,
 )
 
-private val LightColorScheme = lightColorScheme(
-    primary = Purple40,
-    secondary = PurpleGrey40,
-    tertiary = Pink40,
+/** 8dp inputs/chips, 12dp cards, 16dp large surfaces — matching the mockup radii. */
+private val ShardShapes = Shapes(
+    extraSmall = RoundedCornerShape(8.dp),
+    small = RoundedCornerShape(8.dp),
+    medium = RoundedCornerShape(12.dp),
+    large = RoundedCornerShape(16.dp),
+    extraLarge = RoundedCornerShape(24.dp),
 )
 
 /**
- * App theme for the functional pass. The color scheme is seeded from the
- * per-shard brand accent (PLAN.md §3: the app themes itself from the site's
- * branding) when one is available, so the app takes on each shard's color; it
- * falls back to a neutral placeholder scheme before connect or when a site
- * publishes no accent.
- *
- * This is deliberately a minimal seeding — a single-color override on the
- * default Material 3 schemes. The M5 design pass replaces it with a full,
- * designed color system (§2.1, §5); nothing here is meant to be the final look.
+ * App theme. The color scheme is the fixed shard-website dark palette; when a shard
+ * publishes a brand accent (PLAN.md §3), it seeds the [MaterialTheme]'s primary and
+ * secondary roles so buttons and highlights carry that shard's color while the rest
+ * of the deep blue-black system stays intact. With no accent, the slate default is
+ * used.
  */
 @Composable
 fun RunicGatewayTheme(
     accent: Color? = null,
-    darkTheme: Boolean = isSystemInDarkTheme(),
     content: @Composable () -> Unit,
 ) {
-    val base = if (darkTheme) DarkColorScheme else LightColorScheme
     val colorScheme = if (accent != null) {
-        // Brand consistency across a shard wins over device dynamic color: seed
-        // the primary role from the accent so buttons/highlights carry the brand.
-        base.copy(primary = accent, secondary = accent)
+        ShardColorScheme.copy(primary = accent, secondary = accent, tertiary = accent)
     } else {
-        base
+        ShardColorScheme
     }
 
     MaterialTheme(
         colorScheme = colorScheme,
         typography = Typography,
+        shapes = ShardShapes,
         content = content,
     )
 }

app/src/main/java/com/runicgateway/app/ui/theme/Type.kt

@@ -5,17 +5,77 @@ package com.runicgateway.app.ui.theme
 
 import androidx.compose.material3.Typography
 import androidx.compose.ui.text.TextStyle
-import androidx.compose.ui.text.font.FontFamily
 import androidx.compose.ui.text.font.FontWeight
 import androidx.compose.ui.unit.sp
 
-// Default Material 3 type scale for the skeleton; refined in the M5 design pass.
+/**
+ * The M5 type scale. Three families carry the design (see [ui/theme/Font.kt]):
+ * [Cinzel] for the engraved display/headline/title roles, [AppSerif] (Noto Serif)
+ * for parchment body copy, and [AppSans] for the letter-spaced label/meta/button
+ * roles. Sizes and tracking mirror the "Runic Gateway Screens" mockup.
+ */
 val Typography = Typography(
+    // Display / headline / title — Cinzel engraved serif
+    displayLarge = TextStyle(
+        fontFamily = Cinzel, fontWeight = FontWeight.SemiBold,
+        fontSize = 40.sp, lineHeight = 46.sp, letterSpacing = 0.4.sp,
+    ),
+    displayMedium = TextStyle(
+        fontFamily = Cinzel, fontWeight = FontWeight.SemiBold,
+        fontSize = 32.sp, lineHeight = 40.sp, letterSpacing = 0.3.sp,
+    ),
+    displaySmall = TextStyle(
+        fontFamily = Cinzel, fontWeight = FontWeight.SemiBold,
+        fontSize = 28.sp, lineHeight = 36.sp, letterSpacing = 0.2.sp,
+    ),
+    headlineLarge = TextStyle(
+        fontFamily = Cinzel, fontWeight = FontWeight.SemiBold,
+        fontSize = 26.sp, lineHeight = 34.sp, letterSpacing = 0.2.sp,
+    ),
+    headlineMedium = TextStyle(
+        fontFamily = Cinzel, fontWeight = FontWeight.SemiBold,
+        fontSize = 24.sp, lineHeight = 32.sp, letterSpacing = 0.2.sp,
+    ),
+    headlineSmall = TextStyle(
+        fontFamily = Cinzel, fontWeight = FontWeight.SemiBold,
+        fontSize = 22.sp, lineHeight = 28.sp, letterSpacing = 0.2.sp,
+    ),
+    titleLarge = TextStyle(
+        fontFamily = Cinzel, fontWeight = FontWeight.SemiBold,
+        fontSize = 20.sp, lineHeight = 26.sp, letterSpacing = 0.2.sp,
+    ),
+    titleMedium = TextStyle(
+        fontFamily = Cinzel, fontWeight = FontWeight.SemiBold,
+        fontSize = 17.sp, lineHeight = 24.sp, letterSpacing = 0.15.sp,
+    ),
+    titleSmall = TextStyle(
+        fontFamily = Cinzel, fontWeight = FontWeight.SemiBold,
+        fontSize = 15.sp, lineHeight = 22.sp, letterSpacing = 0.1.sp,
+    ),
+    // Body — parchment serif
     bodyLarge = TextStyle(
-        fontFamily = FontFamily.Default,
-        fontWeight = FontWeight.Normal,
-        fontSize = 16.sp,
-        lineHeight = 24.sp,
-        letterSpacing = 0.5.sp,
+        fontFamily = AppSerif, fontWeight = FontWeight.Normal,
+        fontSize = 16.sp, lineHeight = 26.sp, letterSpacing = 0.15.sp,
+    ),
+    bodyMedium = TextStyle(
+        fontFamily = AppSerif, fontWeight = FontWeight.Normal,
+        fontSize = 15.sp, lineHeight = 24.sp, letterSpacing = 0.15.sp,
+    ),
+    bodySmall = TextStyle(
+        fontFamily = AppSerif, fontWeight = FontWeight.Normal,
+        fontSize = 13.sp, lineHeight = 20.sp, letterSpacing = 0.2.sp,
+    ),
+    // Labels / meta / buttons — sans, letter-spaced
+    labelLarge = TextStyle(
+        fontFamily = AppSans, fontWeight = FontWeight.Bold,
+        fontSize = 14.sp, lineHeight = 18.sp, letterSpacing = 0.45.sp,
+    ),
+    labelMedium = TextStyle(
+        fontFamily = AppSans, fontWeight = FontWeight.Medium,
+        fontSize = 12.sp, lineHeight = 16.sp, letterSpacing = 0.4.sp,
+    ),
+    labelSmall = TextStyle(
+        fontFamily = AppSans, fontWeight = FontWeight.Medium,
+        fontSize = 11.sp, lineHeight = 15.sp, letterSpacing = 0.5.sp,
     ),
 )

app/src/main/res/drawable-anydpi/ic_stat_name.xml

@@ -0,0 +1,19 @@
+<?xml version="1.0" encoding="utf-8"?>
+<vector xmlns:android="http://schemas.android.com/apk/res/android"
+    android:width="24dp"
+    android:height="24dp"
+    android:viewportWidth="172"
+    android:viewportHeight="218.95209"
+    android:tint="#FFFFFF">
+  <group android:scaleX="0.7227152"
+      android:scaleY="0.92"
+      android:translateX="23.846495"
+      android:translateY="8.758083">
+    <group android:translateY="154.51205">
+      <path android:pathData="M9.28125,-0L9.28125,-103.109375L42.265625,-103.109375Q53.140625,-103.109375,60.984375,-99.25Q68.828125,-95.40625,73.109375,-88.203125Q77.40625,-81,77.40625,-71.203125L77.40625,-70.0625Q77.40625,-60.1875,73.109375,-53.015625Q68.828125,-45.859375,60.9375,-41.96875Q53.0625,-38.09375,42.265625,-38.09375L20.296875,-38.09375L20.296875,-54.5L41.828125,-54.5Q49.46875,-54.5,53.75,-58.390625Q58.03125,-62.28125,58.03125,-69.125L58.03125,-70.984375Q58.03125,-77.828125,53.75,-81.71875Q49.46875,-85.609375,41.828125,-85.609375L28.4375,-85.609375L28.4375,-0L9.28125,-0ZM61.78125,-0L35.5625,-45.359375L56.65625,-45.359375L83.453125,-0L61.78125,-0Z"
+          android:fillColor="#000000"/>
+      <path android:pathData="M132.65625,2.375Q119.765625,2.375,110.40625,-3.921875Q101.046875,-10.21875,96.046875,-21.953125Q91.046875,-33.703125,91.046875,-49.96875L91.046875,-52.625Q91.046875,-69.046875,96.046875,-80.890625Q101.046875,-92.734375,110.296875,-99.109375Q119.546875,-105.484375,132.375,-105.484375Q145.25,-105.484375,153.96875,-99.109375Q162.6875,-92.734375,166.5625,-80.5L149.21875,-74.09375Q147.125,-81,143.04688,-84.234375Q138.98438,-87.484375,132.57812,-87.484375Q121.859375,-87.484375,116.125,-78.546875Q110.40625,-69.625,110.40625,-52.984375L110.40625,-49.609375Q110.40625,-32.96875,116.15625,-24.21875Q121.921875,-15.484375,132.79688,-15.484375Q141.57812,-15.484375,146.35938,-21.453125Q151.15625,-27.4375,151.15625,-38.453125L151.15625,-41.828125L129.84375,-41.828125L129.84375,-57.890625L169.09375,-57.890625L169.09375,-41.90625Q169.09375,-20.734375,159.57812,-9.171875Q150.07812,2.375,132.65625,2.375Z"
+          android:fillColor="#000000"/>
+    </group>
+  </group>
+</vector>

app/src/main/res/drawable/ic_launcher_background.xml

@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- SPDX-License-Identifier: GPL-3.0-or-later -->
+<!--
+  Adaptive-icon background layer (M6): a solid deep-indigo fill behind the
+  transparent gateway-medallion foreground. Replaces the Image Asset wizard's
+  default green grid. Sourced from @color/ic_launcher_background so the launcher
+  background stays a single source of truth.
+-->
+<vector xmlns:android="http://schemas.android.com/apk/res/android"
+    android:width="108dp"
+    android:height="108dp"
+    android:viewportWidth="108"
+    android:viewportHeight="108">
+    <path
+        android:fillColor="@color/ic_launcher_background"
+        android:pathData="M0,0h108v108h-108z" />
+</vector>

app/src/main/res/drawable/ic_launcher_foreground.xml

@@ -1,15 +0,0 @@
-<?xml version="1.0" encoding="utf-8"?>
-<!-- SPDX-License-Identifier: GPL-3.0-or-later -->
-<!-- Placeholder launcher glyph: a stylized gateway arch. Replaced in the M5 design pass. -->
-<vector xmlns:android="http://schemas.android.com/apk/res/android"
-    android:width="108dp"
-    android:height="108dp"
-    android:viewportWidth="108"
-    android:viewportHeight="108">
-    <path
-        android:fillColor="#D0BCFF"
-        android:pathData="M38,74 L38,50 A16,16 0 0,1 70,50 L70,74 L62,74 L62,50 A8,8 0 0,0 46,50 L46,74 Z" />
-    <path
-        android:fillColor="#EFB8C8"
-        android:pathData="M52,34 L56,34 L56,40 L52,40 Z M50,40 L58,40 L58,44 L50,44 Z" />
-</vector>

app/src/main/res/mipmap-anydpi-v26/ic_launcher.xml

@@ -1,7 +1,13 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- SPDX-License-Identifier: GPL-3.0-or-later -->
+<!--
+  Adaptive launcher icon (API 26+, which is every target device at minSdk 29):
+  the gateway-medallion foreground (transparent PNG, all densities) over the
+  deep-indigo background. No <monochrome> layer: the medallion is a full-colour
+  mark that does not reduce to a clean single-tone silhouette, so themed-icon
+  mode falls back to this standard icon rather than a tinted blob.
+-->
 <adaptive-icon xmlns:android="http://schemas.android.com/apk/res/android">
-    <background android:drawable="@color/ic_launcher_background" />
-    <foreground android:drawable="@drawable/ic_launcher_foreground" />
-    <monochrome android:drawable="@drawable/ic_launcher_foreground" />
+    <background android:drawable="@drawable/ic_launcher_background" />
+    <foreground android:drawable="@mipmap/ic_launcher_foreground" />
 </adaptive-icon>

app/src/main/res/mipmap-anydpi-v26/ic_launcher_round.xml

@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- SPDX-License-Identifier: GPL-3.0-or-later -->
+<!-- Round adaptive launcher icon — same layers as ic_launcher.xml. -->
 <adaptive-icon xmlns:android="http://schemas.android.com/apk/res/android">
-    <background android:drawable="@color/ic_launcher_background" />
-    <foreground android:drawable="@drawable/ic_launcher_foreground" />
-    <monochrome android:drawable="@drawable/ic_launcher_foreground" />
+    <background android:drawable="@drawable/ic_launcher_background" />
+    <foreground android:drawable="@mipmap/ic_launcher_foreground" />
 </adaptive-icon>

app/src/main/res/values/colors.xml

@@ -2,4 +2,7 @@
 <!-- SPDX-License-Identifier: GPL-3.0-or-later -->
 <resources>
     <color name="ic_launcher_background">#1B1033</color>
+    <!-- M5 design pass: the shard-website page color, used as the launch window
+         background so the first frame matches the dark Compose theme (no white flash). -->
+    <color name="launch_background">#0B0F14</color>
 </resources>

app/src/main/res/values/strings.xml

@@ -30,6 +30,7 @@
     <string name="connect_error_scheme">Only http and https addresses are supported.</string>
     <string name="connect_error_insecure">A secure https address is required.</string>
     <string name="connect_error_not_runic">That site isn\'t a Runic Gateway shard.</string>
+    <string name="connect_error_version">This app is out of date for that site (it speaks API %1$s). Update the app and try again.</string>
     <string name="connect_error_unreachable">Couldn\'t reach that site. Check the address and your connection.</string>
     <string name="connect_error_server">The site responded with an error (%1$d). Try again shortly.</string>
 
@@ -42,6 +43,9 @@
     <string name="menu_about">About</string>
     <string name="menu_contact">Contact</string>
     <string name="menu_account">My account</string>
+    <string name="menu_my_characters">My characters</string>
+    <string name="menu_my_vendors">My vendors</string>
+    <string name="menu_my_houses">My houses</string>
     <string name="menu_sign_in">Sign in</string>
     <string name="menu_sign_out">Sign out</string>
     <string name="menu_change_server">Change server</string>
@@ -57,16 +61,126 @@
     <string name="login_register">Create an account</string>
     <string name="login_forgot">Forgot your password?</string>
     <string name="login_sso">Sign in with Google or Discord (on the website)</string>
+    <!-- %1$s is the provider name, e.g. "Google" or "Discord" (native SSO, M9). -->
+    <string name="login_sso_provider">Sign in with %1$s</string>
     <string name="login_error_credentials">Incorrect username or password.</string>
     <string name="login_error_code">That code didn\'t match. Try the current code.</string>
     <string name="login_error_rate_limited">Too many attempts. Please try again shortly.</string>
     <string name="login_error_server">Something went wrong. Please try again.</string>
     <string name="login_error_network">Can\'t reach the site. Check your connection and try again.</string>
+    <string name="login_error_sso">Couldn\'t complete that sign-in. Please try again.</string>
 
     <!-- ── Auth: account (§5, §6.3) ────────────────────────────────────── -->
     <string name="account_title">My account</string>
     <string name="account_sign_out">Sign out</string>
     <string name="account_sign_out_all">Sign out on all devices</string>
+
+    <!-- Username -->
+    <string name="account_username_title">Username</string>
+    <string name="account_username_action">Change username</string>
+    <string name="account_username_changed">Username updated.</string>
+    <string name="account_username_taken">That username is already taken.</string>
+    <string name="account_username_error">Couldn\'t change your username.</string>
+
+    <!-- Password -->
+    <string name="account_password_title">Password</string>
+    <string name="account_password_set_title">Set a password</string>
+    <string name="account_password_set_hint">Your account was created through a linked provider and has no password yet. Set one to also sign in with a username and password.</string>
+    <string name="account_password_current">Current password</string>
+    <string name="account_password_new">New password</string>
+    <string name="account_password_action">Change password</string>
+    <string name="account_password_set_action">Set password</string>
+    <string name="account_password_changed">Password changed.</string>
+    <string name="account_password_error">Couldn\'t change your password. Check your current password and try again.</string>
+
+    <!-- Two-factor -->
+    <string name="account_totp_title">Two-factor authentication</string>
+    <string name="account_totp_on">Enabled</string>
+    <string name="account_totp_off">Not enabled</string>
+    <string name="account_totp_scan">Scan this code with your authenticator app, then enter the current code.</string>
+    <string name="account_totp_qr_desc">Two-factor QR code</string>
+    <string name="account_totp_setup">Set up two-factor</string>
+    <string name="account_totp_confirm">Confirm &amp; enable</string>
+    <string name="account_totp_cancel">Cancel</string>
+    <string name="account_totp_disable">Disable two-factor</string>
+    <string name="account_totp_enabled">Two-factor is now enabled.</string>
+    <string name="account_totp_disabled">Two-factor has been disabled.</string>
+    <string name="account_totp_code_error">That code isn\'t valid. Try the current code.</string>
+    <string name="account_totp_setup_error">Couldn\'t start two-factor setup.</string>
+
+    <!-- Linked identities -->
+    <string name="account_identities_title">Linked accounts</string>
+    <string name="account_identities_empty">No linked sign-in providers.</string>
+    <string name="account_identity_unlink">Unlink</string>
+    <string name="account_identity_unlinked">Account unlinked.</string>
+    <string name="account_identity_error">Couldn\'t unlink that account.</string>
+
+    <!-- ── Player: game-account linking (§6.3) ─────────────────────────── -->
+    <string name="player_link_title">Link your game account</string>
+    <string name="player_link_hint">In game, type [link to get a one-time code, then enter it here to see your characters, vendors and houses.</string>
+    <string name="player_link_code">Link code</string>
+    <string name="player_link_action">Link account</string>
+    <string name="player_link_ok">Account linked.</string>
+    <string name="player_link_bad_code">That code is unknown or has expired. Run [link in game for a new one.</string>
+    <string name="player_link_error">Couldn\'t link that code. Please try again.</string>
+
+    <string name="player_create_title">Create a game account</string>
+    <string name="player_create_account">Account name</string>
+    <string name="player_create_password">Password</string>
+    <string name="player_create_action">Create account</string>
+    <string name="player_create_ok">Game account created and linked.</string>
+    <string name="player_create_taken">That account name is already taken.</string>
+    <string name="player_create_capped">The account limit for your network has been reached.</string>
+    <string name="player_create_unavailable">Game-account signup isn\'t available right now.</string>
+    <string name="player_create_rejected">That account name or password wasn\'t accepted.</string>
+    <string name="player_create_error">Couldn\'t create that account. Please try again.</string>
+
+    <!-- ── Player: characters (§6.3) ───────────────────────────────────── -->
+    <string name="player_characters_empty">Link a game account above to see your characters.</string>
+    <string name="player_roster_loading">Loading…</string>
+    <string name="player_roster_empty">No characters on this account.</string>
+    <string name="player_char_unknown">Unknown</string>
+    <string name="player_char_online">Online</string>
+    <string name="player_char_offline">Offline</string>
+
+    <!-- Character sheet -->
+    <string name="player_char_governor">Governor of %1$s</string>
+    <string name="player_char_guildmaster">Guildmaster, %1$s</string>
+    <string name="player_char_attributes">Attributes</string>
+    <string name="player_char_vitals">Vitals</string>
+    <string name="player_char_str">STR</string>
+    <string name="player_char_dex">DEX</string>
+    <string name="player_char_int">INT</string>
+    <string name="player_char_hits">Hits</string>
+    <string name="player_char_mana">Mana</string>
+    <string name="player_char_stam">Stamina</string>
+    <string name="player_char_resistances">Resistances</string>
+    <string name="player_char_phys">Physical</string>
+    <string name="player_char_fire">Fire</string>
+    <string name="player_char_cold">Cold</string>
+    <string name="player_char_pois">Poison</string>
+    <string name="player_char_energy">Energy</string>
+    <string name="player_char_skills">Skills</string>
+    <string name="player_char_equipment">Equipment</string>
+    <string name="player_char_item">Item</string>
+    <string name="player_char_item_id">id %1$d</string>
+    <string name="player_char_item_hue">hue %1$d</string>
+
+    <!-- ── Player: vendors &amp; sales (§6.3) ──────────────────────────── -->
+    <string name="player_sales_title">Recent sales</string>
+    <string name="player_sales_empty">No recent sales.</string>
+    <string name="player_gold_amount">%1$s gp</string>
+    <string name="player_vendors_no_accounts">Link a game account to see your vendors.</string>
+    <string name="player_vendors_empty">No vendors on this account.</string>
+    <string name="player_vendor_fallback">Player vendor</string>
+    <string name="player_vendor_hold">Holding %1$s gp</string>
+    <string name="player_vendor_no_listings">No items listed.</string>
+    <string name="player_listing_item">Item %1$d ×%2$d</string>
+
+    <!-- ── Player: houses (§6.3) ───────────────────────────────────────── -->
+    <string name="player_houses_empty">You don\'t have any houses on your linked accounts.</string>
+    <string name="player_house_fallback">A house</string>
+    <string name="player_house_stage">Status: %1$s</string>
     <string name="role_player">Player</string>
     <string name="role_moderator">Moderator</string>
     <string name="role_editor">Editor</string>
@@ -146,4 +260,37 @@
     <string name="houses_empty">No houses are in danger right now.</string>
     <string name="houses_fallback_name">A house</string>
     <string name="houses_idoc_badge">IDOC</string>
+
+    <!-- ── Push notifications (§11, M7 Part 2) ─────────────────────────── -->
+    <string name="menu_notifications">Notifications</string>
+    <string name="notifications_title">Notifications</string>
+    <string name="notifications_subtitle">Choose what this shard notifies you about. Nothing is sent unless you turn it on.</string>
+    <string name="notifications_section_general">General</string>
+    <string name="notifications_section_personal">Your game account</string>
+    <string name="notifications_requires_link">Link a game account to enable this.</string>
+    <string name="notifications_empty">This shard offers no notification streams yet.</string>
+    <string name="notifications_unsupported">This shard hasn\'t set up push notifications yet.</string>
+    <string name="notifications_saved">Notification settings saved.</string>
+    <string name="notifications_all_off">Notifications turned off.</string>
+    <string name="notifications_save_error">Couldn\'t save your notification settings. Try again.</string>
+    <string name="notifications_relay_error">This shard\'s push relay isn\'t reachable right now.</string>
+
+    <!-- Notification channels + the ongoing foreground-service notification. -->
+    <string name="push_channel_messages">Shard notifications</string>
+    <string name="push_channel_messages_desc">Alerts you opted into from this shard.</string>
+    <string name="push_channel_service">Background connection</string>
+    <string name="push_channel_service_desc">Keeps the connection open to deliver notifications.</string>
+    <string name="push_service_title">Notifications active</string>
+    <string name="push_service_text">Listening for shard notifications.</string>
+
+    <!-- Per-stream notification titles (content-free tickle → generic title, §11). -->
+    <string name="push_stream_news_post">New post</string>
+    <string name="push_stream_server_status">Shard status changed</string>
+    <string name="push_stream_idoc_warning">A house is falling (IDOC)</string>
+    <string name="push_stream_champ_start">Champion spawn started</string>
+    <string name="push_stream_governor_election">New governor elected</string>
+    <string name="push_stream_vendor_sale">Your vendor made a sale</string>
+    <string name="push_stream_house_idoc">Your house entered IDOC</string>
+    <string name="push_stream_account_login">Login to your account</string>
+    <string name="push_stream_generic">New notification</string>
 </resources>

app/src/main/res/values/themes.xml

@@ -6,5 +6,11 @@
   background / status-bar behavior for launch.
 -->
 <resources>
-    <style name="Theme.RunicGateway" parent="android:Theme.Material.Light.NoActionBar" />
+    <!-- Dark launch theme (the app is dark-only, M5). Sets the window background to the
+         page color so the pre-Compose frame matches; Compose owns the live UI theme. -->
+    <style name="Theme.RunicGateway" parent="android:Theme.Material.NoActionBar">
+        <item name="android:windowBackground">@color/launch_background</item>
+        <item name="android:statusBarColor">@android:color/transparent</item>
+        <item name="android:navigationBarColor">@android:color/transparent</item>
+    </style>
 </resources>

app/src/test/java/com/runicgateway/app/core/auth/sso/PkceTest.kt

@@ -0,0 +1,49 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.core.auth.sso
+
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertNotEquals
+import org.junit.Assert.assertTrue
+import org.junit.Test
+
+/**
+ * PKCE Layer B primitives (PLAN.md §4.2). The challenge encoding must match the
+ * backend byte-for-byte (`base64url(SHA-256(verifier))`, no padding) or `/exchange`
+ * rejects every code — so it is pinned against the RFC 7636 test vector.
+ */
+class PkceTest {
+
+    // RFC 4648 §5 URL-safe base64 alphabet, no padding.
+    private val base64UrlNoPad = Regex("^[A-Za-z0-9_-]+$")
+
+    @Test fun `challenge matches the RFC 7636 vector`() {
+        // RFC 7636 Appendix B.
+        val verifier = "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk"
+        assertEquals("E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM", Pkce.challengeOf(verifier))
+    }
+
+    @Test fun `verifier is url-safe base64 without padding`() {
+        val verifier = Pkce.newVerifier()
+        assertTrue("verifier charset: $verifier", base64UrlNoPad.matches(verifier))
+        // 32 random bytes → 43 base64 chars (no padding), inside RFC 7636's 43–128.
+        assertEquals(43, verifier.length)
+    }
+
+    @Test fun `challenge is url-safe base64 without padding`() {
+        val challenge = Pkce.challengeOf(Pkce.newVerifier())
+        assertTrue("challenge charset: $challenge", base64UrlNoPad.matches(challenge))
+        // SHA-256 (32 bytes) → 43 base64 chars, no '=' padding.
+        assertEquals(43, challenge.length)
+    }
+
+    @Test fun `verifiers and states are unique per call`() {
+        assertNotEquals(Pkce.newVerifier(), Pkce.newVerifier())
+        assertNotEquals(Pkce.newState(), Pkce.newState())
+    }
+
+    @Test fun `state is url-safe base64 without padding`() {
+        assertTrue(base64UrlNoPad.matches(Pkce.newState()))
+    }
+}

app/src/test/java/com/runicgateway/app/core/auth/sso/SsoAuthManagerTest.kt

@@ -0,0 +1,223 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.core.auth.sso
+
+import com.runicgateway.app.core.auth.Session
+import com.runicgateway.app.core.auth.SessionManager
+import com.runicgateway.app.core.auth.StoredSession
+import com.runicgateway.app.core.auth.TokenStore
+import com.runicgateway.app.core.net.BaseUrlHolder
+import com.runicgateway.app.data.api.SsoApi
+import com.runicgateway.app.data.api.dto.MobileSsoExchangeRequest
+import com.runicgateway.app.data.api.dto.MobileTokenResponse
+import com.runicgateway.app.data.api.dto.SafeUserDto
+import com.runicgateway.app.data.api.dto.SsoProviderDto
+import kotlinx.coroutines.test.runTest
+import okhttp3.HttpUrl.Companion.toHttpUrl
+import okhttp3.MediaType.Companion.toMediaTypeOrNull
+import okhttp3.ResponseBody.Companion.toResponseBody
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertNull
+import org.junit.Assert.assertTrue
+import org.junit.Test
+import retrofit2.Response
+
+/**
+ * The native SSO bridge orchestration (PLAN.md §4.2, M9): start-URL building, the
+ * CSRF/state guard, the code→token exchange, and that a success drives the *same*
+ * [SessionManager] the password login uses. Runs over a fake [SsoApi] + a real
+ * [SessionManager] on a fake [TokenStore]; no Android framework types are touched.
+ */
+class SsoAuthManagerTest {
+
+    private class FakeTokenStore(var stored: StoredSession? = null) : TokenStore {
+        override fun load(): StoredSession? = stored
+        override fun save(session: StoredSession) { stored = session }
+        override fun clear() { stored = null }
+    }
+
+    /** Records the exchange it was called with and returns a scripted response. */
+    private class FakeSsoApi(
+        private val exchangeResult: () -> Response<MobileTokenResponse>,
+    ) : SsoApi {
+        var exchangeCalls = 0
+        var lastRequest: MobileSsoExchangeRequest? = null
+
+        override suspend fun providers(): List<SsoProviderDto> = emptyList()
+
+        override suspend fun exchange(body: MobileSsoExchangeRequest): Response<MobileTokenResponse> {
+            exchangeCalls++
+            lastRequest = body
+            return exchangeResult()
+        }
+    }
+
+    private fun tokenPair() = MobileTokenResponse(
+        accessToken = "access-A",
+        refreshToken = "refresh-A",
+        expiresIn = "15m",
+        user = SafeUserDto(id = 7, username = "alice", role = "player"),
+    )
+
+    private fun error(code: Int): Response<MobileTokenResponse> =
+        Response.error(code, "".toResponseBody("application/json".toMediaTypeOrNull()))
+
+    private fun managerWith(
+        api: SsoApi,
+        session: SessionManager,
+        base: String? = "https://shard.example.com/",
+    ): SsoAuthManager {
+        val holder = BaseUrlHolder()
+        if (base != null) holder.set(base.toHttpUrl())
+        return SsoAuthManager(api, session, holder)
+    }
+
+    /** Build a start URL and pull the generated `state` back out of it. */
+    private fun startAndState(mgr: SsoAuthManager, provider: String = "google"): String {
+        val url = mgr.buildStartUrl(SsoProviderDto(id = provider, name = "Google").id)!!
+        return url.toHttpUrl().queryParameter("state")!!
+    }
+
+    @Test fun `buildStartUrl carries provider, challenge, state and the fixed redirect`() {
+        val mgr = managerWith(FakeSsoApi { tokenPair().let { Response.success(it) } }, SessionManager(FakeTokenStore()))
+        val url = mgr.buildStartUrl("google")!!
+        val http = url.toHttpUrl()
+
+        assertTrue(url.startsWith("https://shard.example.com/api/v1/auth/mobile/sso/start"))
+        assertEquals("google", http.queryParameter("provider"))
+        assertEquals(SsoAuthManager.REDIRECT_URI, http.queryParameter("redirect_uri"))
+        assertTrue(!http.queryParameter("code_challenge").isNullOrBlank())
+        assertTrue(!http.queryParameter("state").isNullOrBlank())
+    }
+
+    @Test fun `buildStartUrl returns null when no base url is set`() {
+        val mgr = managerWith(FakeSsoApi { Response.success(tokenPair()) }, SessionManager(FakeTokenStore()), base = null)
+        assertNull(mgr.buildStartUrl("google"))
+    }
+
+    @Test fun `successful callback exchanges and signs in`() = runTest {
+        val api = FakeSsoApi { Response.success(tokenPair()) }
+        val session = SessionManager(FakeTokenStore())
+        val mgr = managerWith(api, session)
+
+        val state = startAndState(mgr)
+        mgr.complete(state = state, code = "auth-code-1", error = null)
+
+        assertEquals(1, api.exchangeCalls)
+        assertEquals("auth-code-1", api.lastRequest?.code)
+        assertTrue(session.state.value is Session.SignedIn)
+        assertEquals("access-A", session.currentAccessToken())
+        assertEquals(SsoAuthManager.Outcome.Success, mgr.outcome.value)
+    }
+
+    @Test fun `state mismatch fails without exchanging`() = runTest {
+        val api = FakeSsoApi { Response.success(tokenPair()) }
+        val session = SessionManager(FakeTokenStore())
+        val mgr = managerWith(api, session)
+
+        startAndState(mgr) // establishes a pending with a different state
+        mgr.complete(state = "not-the-state", code = "auth-code-1", error = null)
+
+        assertEquals(0, api.exchangeCalls)
+        assertTrue(session.state.value is Session.SignedOut)
+        assertEquals(SsoAuthManager.Outcome.Failed(SsoAuthManager.Failure.STATE_MISMATCH), mgr.outcome.value)
+    }
+
+    @Test fun `missing pending flow (process death) fails closed`() = runTest {
+        val api = FakeSsoApi { Response.success(tokenPair()) }
+        val mgr = managerWith(api, SessionManager(FakeTokenStore()))
+
+        // No buildStartUrl → nothing stashed; a callback can't be trusted.
+        mgr.complete(state = "anything", code = "auth-code-1", error = null)
+
+        assertEquals(0, api.exchangeCalls)
+        assertEquals(SsoAuthManager.Outcome.Failed(SsoAuthManager.Failure.STATE_MISMATCH), mgr.outcome.value)
+    }
+
+    @Test fun `error callback maps to a declined sign-in and does not exchange`() = runTest {
+        val api = FakeSsoApi { Response.success(tokenPair()) }
+        val mgr = managerWith(api, SessionManager(FakeTokenStore()))
+
+        val state = startAndState(mgr)
+        mgr.complete(state = state, code = null, error = "access_denied")
+
+        assertEquals(0, api.exchangeCalls)
+        assertEquals(SsoAuthManager.Outcome.Failed(SsoAuthManager.Failure.DENIED), mgr.outcome.value)
+    }
+
+    @Test fun `401 exchange maps to expired code`() = runTest {
+        val api = FakeSsoApi { error(401) }
+        val session = SessionManager(FakeTokenStore())
+        val mgr = managerWith(api, session)
+
+        val state = startAndState(mgr)
+        mgr.complete(state = state, code = "stale-code", error = null)
+
+        assertEquals(1, api.exchangeCalls)
+        assertTrue(session.state.value is Session.SignedOut)
+        assertEquals(SsoAuthManager.Outcome.Failed(SsoAuthManager.Failure.EXPIRED_CODE), mgr.outcome.value)
+    }
+
+    @Test fun `a second delivery of the same callback finds no pending`() = runTest {
+        val api = FakeSsoApi { Response.success(tokenPair()) }
+        val mgr = managerWith(api, SessionManager(FakeTokenStore()))
+
+        val state = startAndState(mgr)
+        mgr.complete(state = state, code = "auth-code-1", error = null)
+        mgr.complete(state = state, code = "auth-code-1", error = null) // replay
+
+        // Only the first delivery exchanged; the replay fails the state guard.
+        assertEquals(1, api.exchangeCalls)
+        assertEquals(SsoAuthManager.Outcome.Failed(SsoAuthManager.Failure.STATE_MISMATCH), mgr.outcome.value)
+    }
+
+    @Test fun `matchesCallback only accepts the fixed scheme host and path`() {
+        val mgr = managerWith(FakeSsoApi { Response.success(tokenPair()) }, SessionManager(FakeTokenStore()))
+        assertTrue(mgr.matchesCallback("runicgateway", "auth", "/callback"))
+        assertTrue(!mgr.matchesCallback("https", "auth", "/callback"))
+        assertTrue(!mgr.matchesCallback("runicgateway", "auth", "/other"))
+        assertTrue(!mgr.matchesCallback("runicgateway", "evil", "/callback"))
+    }
+
+    // ── App Links (docs/android/APP_LINKS.md) ────────────────────────────────
+
+    @Test fun `matchesAppLinkCallback accepts only https, the app-link path, and the paired host`() {
+        val mgr = managerWith(FakeSsoApi { Response.success(tokenPair()) }, SessionManager(FakeTokenStore()))
+        // Paired to shard.example.com (managerWith default base).
+        assertTrue(mgr.matchesAppLinkCallback("https", "shard.example.com", "/mobile/callback"))
+        // Host-trust: a foreign host is refused even over https + right path.
+        assertTrue(!mgr.matchesAppLinkCallback("https", "evil.example.com", "/mobile/callback"))
+        // Wrong scheme / wrong path.
+        assertTrue(!mgr.matchesAppLinkCallback("http", "shard.example.com", "/mobile/callback"))
+        assertTrue(!mgr.matchesAppLinkCallback("https", "shard.example.com", "/callback"))
+        // Host match is case-insensitive.
+        assertTrue(mgr.matchesAppLinkCallback("https", "SHARD.EXAMPLE.COM", "/mobile/callback"))
+    }
+
+    @Test fun `matchesAppLinkCallback is false before a shard is paired`() {
+        val mgr = managerWith(FakeSsoApi { Response.success(tokenPair()) }, SessionManager(FakeTokenStore()), base = null)
+        assertTrue(!mgr.matchesAppLinkCallback("https", "shard.example.com", "/mobile/callback"))
+    }
+
+    @Test fun `buildStartUrl requests the custom scheme when no app-link host is baked`() {
+        val mgr = managerWith(FakeSsoApi { Response.success(tokenPair()) }, SessionManager(FakeTokenStore()))
+        // Generic build: appLinkHost defaults to BuildConfig.APP_LINK_HOST ("" in tests).
+        val redirect = mgr.buildStartUrl("google")!!.toHttpUrl().queryParameter("redirect_uri")
+        assertEquals(SsoAuthManager.REDIRECT_URI, redirect)
+    }
+
+    @Test fun `buildStartUrl requests the https app-link callback when the baked host matches the paired host`() {
+        val mgr = managerWith(FakeSsoApi { Response.success(tokenPair()) }, SessionManager(FakeTokenStore()))
+        mgr.appLinkHost = "shard.example.com" // white-label build baked this shard's host
+        val redirect = mgr.buildStartUrl("google")!!.toHttpUrl().queryParameter("redirect_uri")
+        assertEquals("https://shard.example.com/mobile/callback", redirect)
+    }
+
+    @Test fun `buildStartUrl falls back to the custom scheme when the baked host does not match the paired shard`() {
+        val mgr = managerWith(FakeSsoApi { Response.success(tokenPair()) }, SessionManager(FakeTokenStore()))
+        mgr.appLinkHost = "other-shard.example.com" // built for a different shard than the paired one
+        val redirect = mgr.buildStartUrl("google")!!.toHttpUrl().queryParameter("redirect_uri")
+        assertEquals(SsoAuthManager.REDIRECT_URI, redirect)
+    }
+}

app/src/test/java/com/runicgateway/app/core/push/NtfyTopicTest.kt

@@ -0,0 +1,42 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.core.push
+
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertNotEquals
+import org.junit.Assert.assertNull
+import org.junit.Assert.assertTrue
+import org.junit.Test
+
+/**
+ * Tests for the app's own ntfy topic + endpoint URL building (PLAN.md §11, work
+ * item 1) — the heart of the embedded-distributor design.
+ */
+class NtfyTopicTest {
+
+    @Test fun generatesUnguessableTopicsInTheAllowedCharset() {
+        val a = NtfyTopic.generate()
+        val b = NtfyTopic.generate()
+        assertNotEquals(a, b)
+        assertTrue("prefixed", a.startsWith("up"))
+        assertTrue("length", a.length >= 24)
+        assertTrue("charset", a.all { it.isLetterOrDigit() })
+    }
+
+    @Test fun buildsEndpointAndSseUrls() {
+        assertEquals("https://ntfy.tld/up7", NtfyTopic.endpointUrl("https://ntfy.tld", "up7"))
+        assertEquals("https://ntfy.tld/up7/sse", NtfyTopic.sseUrl("https://ntfy.tld", "up7"))
+    }
+
+    @Test fun toleratesTrailingSlashOnBase() {
+        assertEquals("https://ntfy.tld/up7", NtfyTopic.endpointUrl("https://ntfy.tld/", "up7"))
+    }
+
+    @Test fun nullOrBlankInputsYieldNull() {
+        assertNull(NtfyTopic.endpointUrl(null, "up7"))
+        assertNull(NtfyTopic.endpointUrl("", "up7"))
+        assertNull(NtfyTopic.endpointUrl("https://ntfy.tld", " "))
+        assertNull(NtfyTopic.sseUrl(null, "up7"))
+    }
+}

app/src/test/java/com/runicgateway/app/core/push/PushTickleTest.kt

@@ -0,0 +1,52 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.core.push
+
+import kotlinx.serialization.json.Json
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertNull
+import org.junit.Test
+
+/**
+ * Parsing tests for the content-free push tickle over ntfy's SSE envelope
+ * (PLAN.md §11). A `message` frame yields `{ stream, ref }`; lifecycle frames and
+ * malformed bodies are dropped (never thrown, §7).
+ */
+class PushTickleTest {
+
+    private val json = Json { ignoreUnknownKeys = true }
+
+    @Test fun parsesMessageFrame() {
+        // ntfy wraps our POSTed body in { event:"message", message:"<our json>" }.
+        val data = """{"id":"x","time":1,"event":"message","topic":"up1","message":"{\"stream\":\"vendor.sale\",\"ref\":\"0x40001\"}"}"""
+        val tickle = parseNtfyTickle(json, data)
+        assertEquals(PushTickle("vendor.sale", "0x40001"), tickle)
+    }
+
+    @Test fun parsesMessageWithoutRef() {
+        val data = """{"event":"message","message":"{\"stream\":\"server.status\"}"}"""
+        val tickle = parseNtfyTickle(json, data)
+        assertEquals("server.status", tickle?.stream)
+        assertNull(tickle?.ref)
+    }
+
+    @Test fun dropsOpenAndKeepaliveFrames() {
+        assertNull(parseNtfyTickle(json, """{"event":"open","topic":"up1"}"""))
+        assertNull(parseNtfyTickle(json, """{"event":"keepalive","topic":"up1"}"""))
+    }
+
+    @Test fun dropsMalformedOrEmpty() {
+        assertNull(parseNtfyTickle(json, ""))
+        assertNull(parseNtfyTickle(json, ": keepalive comment"))
+        assertNull(parseNtfyTickle(json, "not json"))
+        // A message whose inner body isn't our shape → no stream → dropped.
+        assertNull(parseNtfyTickle(json, """{"event":"message","message":"{}"}"""))
+        assertNull(parseNtfyTickle(json, """{"event":"message","message":"garbage"}"""))
+    }
+
+    @Test fun decodeTickleRejectsBlankStream() {
+        assertNull(decodeTickle(json, """{"stream":"","ref":"x"}"""))
+        assertEquals(PushTickle("news.post"), decodeTickle(json, """{"stream":"news.post"}"""))
+    }
+}

app/src/test/java/com/runicgateway/app/data/api/dto/AccountDtoTest.kt

@@ -0,0 +1,64 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.data.api.dto
+
+import kotlinx.serialization.json.Json
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertTrue
+import org.junit.Test
+
+/**
+ * Decoding tests for the self-service ("me") account DTOs (PLAN.md §6.3, §6.4).
+ * Shapes come from the website's `account.controller` handlers surfaced under
+ * `/auth/me/account*`; unknown keys are ignored (additive fields, §8).
+ */
+class AccountDtoTest {
+
+    private val json = Json {
+        ignoreUnknownKeys = true
+        explicitNulls = false
+        coerceInputValues = true
+    }
+
+    @Test fun accountDecodesSecurityFlags() {
+        val dto = json.decodeFromString<PlayerAccountDto>(
+            """{"id":42,"username":"newplayer","role":"player","email":"p@example.com",
+               "status":"active","totp_enabled":false,"has_password":true}""",
+        )
+        assertEquals(42L, dto.id)
+        assertEquals("newplayer", dto.username)
+        assertTrue(dto.has_password)
+        assertFalse(dto.totp_enabled)
+    }
+
+    @Test fun ssoAccountHasNoPassword() {
+        // An SSO-provisioned account omits email and reports has_password=false.
+        val dto = json.decodeFromString<PlayerAccountDto>(
+            """{"id":7,"username":"ssouser","role":"player","email":null,
+               "status":"active","totp_enabled":true,"has_password":false}""",
+        )
+        assertFalse(dto.has_password)
+        assertTrue(dto.totp_enabled)
+    }
+
+    @Test fun totpSetupDecodesQr() {
+        val dto = json.decodeFromString<TotpSetupDto>(
+            """{"otpauthUrl":"otpauth://totp/Runic:admin?secret=ABC","qr":"data:image/png;base64,iVBORw0KGgo="}""",
+        )
+        assertTrue(dto.qr!!.startsWith("data:image/png;base64,"))
+    }
+
+    @Test fun totpStateDecodes() {
+        assertTrue(json.decodeFromString<TotpStateDto>("""{"totp_enabled":true}""").totp_enabled)
+    }
+
+    @Test fun linkedIdentityDecodes() {
+        val dto = json.decodeFromString<LinkedIdentityDto>(
+            """{"provider":"discord","email":"u@example.com","linked_at":"2026-07-19T22:00:00Z"}""",
+        )
+        assertEquals("discord", dto.provider)
+        assertEquals("u@example.com", dto.email)
+    }
+}

app/src/test/java/com/runicgateway/app/data/api/dto/NotificationsDtoTest.kt

@@ -0,0 +1,75 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.data.api.dto
+
+import kotlinx.serialization.json.Json
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertNull
+import org.junit.Assert.assertTrue
+import org.junit.Test
+
+/**
+ * Decoding tests for the opt-in push DTOs (PLAN.md §11, M7 Part 2). Shapes come
+ * from the merged backend (`notifications.controller` / `pushDevices.model`);
+ * unknown keys are ignored (additive fields, §8).
+ */
+class NotificationsDtoTest {
+
+    private val json = Json {
+        ignoreUnknownKeys = true
+        explicitNulls = false
+        coerceInputValues = true
+    }
+
+    @Test fun pushDeviceDecodes() {
+        val dto = json.decodeFromString<PushDeviceDto>(
+            """{"id":9,"transport":"unifiedpush","endpoint":"https://ntfy.example.com/up123",
+               "platform":"android","createdAt":"2026-07-20T00:00:00Z","lastSeenAt":null}""",
+        )
+        assertEquals(9L, dto.id)
+        assertEquals("unifiedpush", dto.transport)
+        assertEquals("https://ntfy.example.com/up123", dto.endpoint)
+        assertEquals("android", dto.platform)
+        assertNull(dto.lastSeenAt)
+    }
+
+    @Test fun streamCatalogDecodesPersonalFlags() {
+        val dto = json.decodeFromString<NotificationStreamsDto>(
+            """{"streams":[
+                 {"id":"news.post","label":"News posts","description":"New posts.","personal":false,"requiresLinkedAccount":false},
+                 {"id":"vendor.sale","label":"Your vendor sold","description":"A sale.","personal":true,"requiresLinkedAccount":true}
+               ]}""",
+        )
+        assertEquals(2, dto.streams.size)
+        val news = dto.streams.first { it.id == "news.post" }
+        assertFalse(news.personal)
+        assertFalse(news.requiresLinkedAccount)
+        val vendor = dto.streams.first { it.id == "vendor.sale" }
+        assertTrue(vendor.personal)
+        assertTrue(vendor.requiresLinkedAccount)
+    }
+
+    @Test fun subscriptionsDecode() {
+        val dto = json.decodeFromString<NotificationSubscriptionsDto>(
+            """{"streams":["news.post","champ.start"]}""",
+        )
+        assertEquals(listOf("news.post", "champ.start"), dto.streams)
+    }
+
+    @Test fun settingsPushBlockDecodes() {
+        val dto = json.decodeFromString<SettingsDto>(
+            """{"site_title":"Shard","brand":{"name":"Shard"},"push":{"ntfyUrl":"https://ntfy.shard.tld"}}""",
+        )
+        assertEquals("https://ntfy.shard.tld", dto.push.ntfyUrl)
+    }
+
+    @Test fun settingsPushDefaultsNullOnOlderBackend() {
+        // A backend predating M7 omits `push` entirely — the app must still decode.
+        val dto = json.decodeFromString<SettingsDto>(
+            """{"site_title":"Shard","brand":{"name":"Shard"}}""",
+        )
+        assertNull(dto.push.ntfyUrl)
+    }
+}

app/src/test/java/com/runicgateway/app/data/api/dto/PlayerShardDtoTest.kt

@@ -0,0 +1,102 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.data.api.dto
+
+import kotlinx.serialization.json.Json
+import kotlinx.serialization.json.jsonPrimitive
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertNotNull
+import org.junit.Assert.assertTrue
+import org.junit.Test
+
+/**
+ * Decoding tests for a player's own game-data DTOs (PLAN.md §6.3). Shapes come from
+ * the website's `player/shard.controller.js` + `docs/link/INTEGRATION.md` §5. The
+ * roster / char / vendor reads are permissive objects, so the parser must ignore
+ * unknown keys (additive fields, §8) and tolerate hex-string serials.
+ */
+class PlayerShardDtoTest {
+
+    private val json = Json {
+        ignoreUnknownKeys = true
+        explicitNulls = false
+        coerceInputValues = true
+    }
+
+    @Test fun rosterDecodesCharsIncludingOffline() {
+        val dto = json.decodeFromString<RosterDto>(
+            """{"kind":"account.roster","acct":"whitlocktech",
+               "chars":[{"slot":0,"serial":"0x24C","name":"Darrow","body":400,"online":false}]}""",
+        )
+        assertEquals("whitlocktech", dto.acct)
+        assertEquals(1, dto.chars.size)
+        assertEquals("0x24C", dto.chars[0].serial)
+        assertEquals("Darrow", dto.chars[0].name)
+    }
+
+    @Test fun charProfileDecodesStatsSkillsEquipmentAndTitles() {
+        val dto = json.decodeFromString<CharProfileDto>(
+            """{"kind":"char.profile","serial":"0x24C","name":"Darrow","online":true,"acct":"wt",
+               "stats":{"str":100,"dex":90,"int":75,"hits":100,"hitsMax":110,
+                        "resist":{"phys":70,"fire":68,"cold":60,"pois":55,"energy":50}},
+               "skills":[{"n":"Swordsmanship","base":100.0,"value":120.0,"cap":120.0},
+                         {"n":"Anatomy","base":0.0,"value":0.0,"cap":100.0}],
+               "equipment":[{"serial":"0x40","layer":"OneHanded","itemId":5040,"hue":1153,
+                             "mods":{"DamageIncrease":50,"HitLightning":30}}],
+               "titles":{"selected":0,"reward":["Knight"],"fameKarma":"The Great"},
+               "guild":{"name":"Knights","abbr":"KNT"},"governorOf":["Britain"]}""",
+        )
+        assertEquals("Darrow", dto.name)
+        assertTrue(dto.online)
+        assertEquals(100, dto.stats?.str)
+        assertEquals(70, dto.stats?.resist?.phys)
+        assertEquals(2, dto.skills.size)
+        assertEquals(120.0, dto.skills[0].value!!, 0.0)
+        val mods = dto.equipment[0].mods
+        assertNotNull(mods)
+        assertEquals("50", mods!!["DamageIncrease"]!!.jsonPrimitive.content)
+        assertEquals("KNT", dto.guild?.abbr)
+        assertEquals(listOf("Britain"), dto.governorOf)
+    }
+
+    @Test fun vendorSnapshotDecodesListings() {
+        val dto = json.decodeFromString<VendorSnapshotDto>(
+            """{"kind":"vendor.snapshot","acct":"seed_000",
+               "vendors":[{"serial":"0x2C0","shopName":"Seed Shop","holdGold":24186,
+                 "ownerSerial":"0x1F5","map":"Felucca","x":1402,"y":1604,
+                 "listings":[{"serial":"0x4001440F","itemId":3937,"amount":1,"price":69819,"forSale":true}]}]}""",
+        )
+        assertEquals(1, dto.vendors.size)
+        assertEquals(24186L, dto.vendors[0].holdGold)
+        assertEquals(69819L, dto.vendors[0].listings[0].price)
+        assertTrue(dto.vendors[0].listings[0].forSale)
+    }
+
+    @Test fun vendorSaleDecodes() {
+        val dto = json.decodeFromString<VendorSaleDto>(
+            """{"t":1783720195626,"itemType":"Longsword","amount":1,"price":100,
+               "commission":5,"ownerAcct":"whitlocktech"}""",
+        )
+        assertEquals(1783720195626L, dto.t)
+        assertEquals("Longsword", dto.itemType)
+        assertEquals(100L, dto.price)
+    }
+
+    @Test fun playerHouseDecodesHexSerialAndIdoc() {
+        val dto = json.decodeFromString<PlayerHouseDto>(
+            """{"serial":"0x4004705F","stage":"IDOC","map":"Trammel","x":1,"y":2,"z":3,
+               "region":"Britain","name":"An Unnamed House","isIdoc":true,
+               "ownerAcct":"wt","updatedAt":"2026-07-19T22:00:00Z"}""",
+        )
+        assertEquals("0x4004705F", dto.serial)
+        assertEquals("IDOC", dto.stage)
+        assertTrue(dto.isIdoc)
+    }
+
+    @Test fun linkResultDecodes() {
+        val dto = json.decodeFromString<ShardLinkResultDto>("""{"linked":true,"account":"whitlocktech"}""")
+        assertTrue(dto.linked)
+        assertEquals("whitlocktech", dto.account)
+    }
+}

app/src/test/java/com/runicgateway/app/data/repository/ConnectionVersionGuardTest.kt

@@ -0,0 +1,51 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.data.repository
+
+import com.runicgateway.app.data.api.dto.VersionDto
+import com.runicgateway.app.data.repository.ConnectionRepository.Companion.evaluateVersion
+import com.runicgateway.app.data.repository.ConnectionRepository.VersionVerdict
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertTrue
+import org.junit.Test
+
+/**
+ * The connect-probe version guard (§3): a Runic Gateway backend on the app's
+ * supported API is accepted; a wrong service identity or an unsupported API
+ * version is refused clearly rather than mis-rendered.
+ */
+class ConnectionVersionGuardTest {
+
+    @Test
+    fun `matching service and api is Ok`() {
+        val v = VersionDto(service = "runic-gateway", api = "v1", server = "1.2.3")
+        assertEquals(VersionVerdict.Ok, evaluateVersion(v))
+    }
+
+    @Test
+    fun `service id is case-insensitive and trimmed`() {
+        val v = VersionDto(service = "  Runic-Gateway  ", api = "V1", server = "x")
+        assertEquals(VersionVerdict.Ok, evaluateVersion(v))
+    }
+
+    @Test
+    fun `wrong service is NotRunicGateway`() {
+        val v = VersionDto(service = "some-other-app", api = "v1", server = "x")
+        assertEquals(VersionVerdict.NotRunicGateway, evaluateVersion(v))
+    }
+
+    @Test
+    fun `blank api is lenient (older backend) and accepted`() {
+        val v = VersionDto(service = "runic-gateway", api = "", server = "x")
+        assertEquals(VersionVerdict.Ok, evaluateVersion(v))
+    }
+
+    @Test
+    fun `future api version is a mismatch carrying the server value`() {
+        val v = VersionDto(service = "runic-gateway", api = "v2", server = "x")
+        val verdict = evaluateVersion(v)
+        assertTrue(verdict is VersionVerdict.Mismatch)
+        assertEquals("v2", (verdict as VersionVerdict.Mismatch).serverApi)
+    }
+}

app/src/test/java/com/runicgateway/app/ui/navigation/MenuAccessTest.kt

@@ -40,7 +40,7 @@ class MenuAccessTest {
     @Test fun staffSeeAccountButNoPlayerOnlyGroups() {
         val visible = routes(signedIn(Role.EDITOR))
         assertTrue(visible.contains(Routes.ACCOUNT))
-        // No PLAYER-access entry leaks to staff (none exist yet in M3; guard the rule).
+        // No PLAYER-access entry (the M4 game-data groups) leaks to staff.
         val playerOnly = APP_MENU.filter { it.access == MenuAccess.PLAYER }.map { it.route }
         assertTrue(playerOnly.none { visible.contains(it) })
     }

app/src/test/java/com/runicgateway/app/ui/notifications/NotificationRoutingTest.kt

@@ -0,0 +1,45 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.ui.notifications
+
+import com.runicgateway.app.core.push.PushStreams
+import com.runicgateway.app.data.api.dto.NotificationStreamDto
+import com.runicgateway.app.ui.navigation.Routes
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertTrue
+import org.junit.Test
+
+/**
+ * Tests the pure push helpers: the stream → deep-link route map (PLAN.md §11 work
+ * item 7) and the personal-stream gating (a personal stream needs a linked account).
+ */
+class NotificationRoutingTest {
+
+    @Test fun deepLinkRoutesMapEachStreamToItsScreen() {
+        assertEquals(Routes.NEWS, Routes.forStream(PushStreams.NEWS_POST))
+        assertEquals(Routes.SHARD, Routes.forStream(PushStreams.SERVER_STATUS))
+        assertEquals(Routes.SHARD, Routes.forStream(PushStreams.CHAMP_START))
+        assertEquals(Routes.SHARD, Routes.forStream(PushStreams.IDOC_WARNING))
+        assertEquals(Routes.SHARD, Routes.forStream(PushStreams.GOVERNOR_ELECTION))
+        assertEquals(Routes.PLAYER_VENDORS, Routes.forStream(PushStreams.VENDOR_SALE))
+        assertEquals(Routes.PLAYER_HOUSES, Routes.forStream(PushStreams.HOUSE_IDOC))
+        assertEquals(Routes.ACCOUNT, Routes.forStream(PushStreams.ACCOUNT_LOGIN))
+    }
+
+    @Test fun unknownStreamFallsBackToHome() {
+        assertEquals(Routes.HOME, Routes.forStream("something.new"))
+    }
+
+    @Test fun personalStreamNeedsLinkedAccount() {
+        val personal = NotificationStreamDto(id = "vendor.sale", personal = true, requiresLinkedAccount = true)
+        assertFalse(streamSelectable(personal, hasLinkedAccount = false))
+        assertTrue(streamSelectable(personal, hasLinkedAccount = true))
+    }
+
+    @Test fun generalStreamIsAlwaysSelectable() {
+        val general = NotificationStreamDto(id = "news.post", personal = false, requiresLinkedAccount = false)
+        assertTrue(streamSelectable(general, hasLinkedAccount = false))
+    }
+}