Merge pull request 'fix(shard): decode the atlas places objects and render them' (#32) from fix/atlas-places-decode into feat/protocol-3-visibility

Reviewed-on: #32

.gitea/scripts/gen_tree.py

@@ -0,0 +1,54 @@
+#!/usr/bin/env python3
+"""Render an ASCII tree of tracked files, read from stdin (one path per line).
+
+Used by the `sync-project-tree` workflow to regenerate this repo's PROJECT_TREE.md
+snapshot in the RunicGateway/docs repo. Feed it `git ls-files`:
+
+    git ls-files | python3 .gitea/scripts/gen_tree.py <root-label>
+
+Deterministic ordering: directories before files, each group sorted
+case-insensitively with the raw name as a tiebreak. Output uses the classic
+`tree(1)` box-drawing style so the result is stable across runs and platforms.
+"""
+import sys
+
+
+def build(paths):
+    root = {}
+    for p in paths:
+        p = p.strip().replace("\\", "/")
+        if not p:
+            continue
+        node = root
+        for part in p.split("/"):
+            node = node.setdefault(part, {})
+    return root
+
+
+def render(node, prefix, lines):
+    entries = list(node.items())
+    # directories (non-empty children dict) before files, then case-insensitive name
+    entries.sort(key=lambda kv: (0 if kv[1] else 1, kv[0].lower(), kv[0]))
+    for i, (name, child) in enumerate(entries):
+        last = i == len(entries) - 1
+        branch = "└── " if last else "├── "
+        suffix = "/" if child else ""
+        lines.append(f"{prefix}{branch}{name}{suffix}")
+        if child:
+            render(child, prefix + ("    " if last else "│   "), lines)
+
+
+def main():
+    try:
+        sys.stdout.reconfigure(encoding="utf-8", newline="\n")
+    except AttributeError:
+        pass
+    root_label = sys.argv[1] if len(sys.argv) > 1 else "."
+    tree = build(sys.stdin.read().splitlines())
+    lines = [f"{root_label}/"]
+    render(tree, "", lines)
+    sys.stdout.write("\n".join(lines) + "\n")
+
+
+if __name__ == "__main__":
+    main()

.gitea/workflows/sonarqube.yml

@@ -18,11 +18,12 @@
 # SonarQube Quality Gate, so a failing gate does not fail this job — check the
 # dashboard when you want to.
 #
-# Scope: this analyses the Kotlin source directly (the Sonar scanner reads
-# sonar-project.properties). It does NOT run a Gradle build, so no Android SDK /
-# JDK install is needed — the Kotlin analyzer is source-based. See the "Optional
-# enrichment" note in sonar-project.properties for wiring in Android Lint /
-# coverage reports later.
+# Scope: the Sonar scanner reads sonar-project.properties and analyses the Kotlin
+# source directly. Before the scan we run the JVM unit tests + JaCoCo so SonarQube
+# receives real coverage (sonar.coverage.jacoco.xmlReportPaths) — otherwise it
+# reports 0% and the coverage gate fails despite the test suite existing. That
+# Gradle step needs JDK 17 + the Android SDK (same toolchain as pr-checks.yml);
+# the runner container is bare, so base tools are apt-installed first.
 
 name: SonarQube
 
@@ -40,6 +41,16 @@ jobs:
   analysis:
     runs-on: ubuntu-latest
     steps:
+      # The bare runner container lacks git/curl/unzip (checkout + sdkmanager need
+      # them) and we install JDK 17 from the Ubuntu archive rather than
+      # actions/setup-java (this runner can't reach api.adoptium.net). Mirrors
+      # pr-checks.yml — see its header note.
+      - name: Install base tools + JDK 17
+        run: |
+          apt-get update
+          apt-get install -y git curl unzip openjdk-17-jdk-headless
+          echo "JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64" >> "$GITHUB_ENV"
+
       - name: Check out (full history for accurate new-code + blame)
         uses: actions/checkout@v4
         with:
@@ -47,6 +58,31 @@ jobs:
           # compute "new code". A shallow clone degrades both.
           fetch-depth: 0
 
+      - name: Set up Android SDK
+        uses: android-actions/setup-android@v3
+
+      - name: Install Android SDK packages
+        run: |
+          set +o pipefail
+          yes | sdkmanager "platform-tools" "platforms;android-35" "build-tools;35.0.0"
+
+      - name: Cache Gradle
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.gradle/caches
+            ~/.gradle/wrapper
+          key: gradle-${{ runner.os }}-${{ hashFiles('**/*.gradle.kts', 'gradle/libs.versions.toml', 'gradle/wrapper/gradle-wrapper.properties') }}
+          restore-keys: |
+            gradle-${{ runner.os }}-
+
+      # Produce the JaCoCo XML the scan reports as coverage. Scoped to the debug
+      # variant (matches enableUnitTestCoverage) to keep peak memory down.
+      - name: Unit tests + JaCoCo coverage
+        run: |
+          chmod +x ./gradlew
+          ./gradlew --no-daemon testDebugUnitTest jacocoTestReport
+
       - name: Run SonarQube scan
         uses: sonarsource/sonarqube-scan-action@v4
         env:

.gitea/workflows/sync-project-tree.yml

@@ -0,0 +1,111 @@
+name: sync-project-tree
+
+# Keeps this repo's file-layout snapshot (docs/android/PROJECT_TREE.md in the
+# RunicGateway/docs repo) current. On every push to `main` it regenerates the
+# tree from tracked files and, if it changed, opens (or force-updates) a pull
+# request against the docs repo. It never writes to the docs repo's `main`
+# directly. Auth reuses the same REGISTRY_USER / REGISTRY_TOKEN secrets the
+# other workflows use (the token needs repo read/write on RunicGateway/docs).
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch: {}
+
+concurrency:
+  group: sync-project-tree
+  cancel-in-progress: true
+
+env:
+  GITEA_HOST: gitea.whitlocktech.com
+  DOCS_REPO: RunicGateway/docs
+  SELF_REPO: RunicGateway/Android-app
+  DOCS_PATH: android/PROJECT_TREE.md
+  TREE_TITLE: Android App
+  ROOT_LABEL: android-app
+  PR_BRANCH: chore/sync-android-tree
+
+jobs:
+  sync:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out this repo
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - name: Ensure python3 is available
+        run: |
+          set -euo pipefail
+          command -v python3 >/dev/null 2>&1 || { sudo apt-get update -qq && sudo apt-get install -y -qq python3; }
+
+      - name: Render PROJECT_TREE.md from tracked files
+        run: |
+          set -euo pipefail
+          mkdir -p _sync
+          {
+            printf '# %s — Project Tree\n\n' "${TREE_TITLE}"
+            printf '> **Auto-generated.** This file is maintained by the `sync-project-tree` CI workflow in\n'
+            printf '> the [`%s`](https://%s/%s) repository, which\n' "${SELF_REPO}" "${GITEA_HOST}" "${SELF_REPO}"
+            printf '> opens a pull request here whenever the tracked file layout on `main` changes. Do not edit\n'
+            printf '> by hand — changes will be overwritten by the next sync.\n\n'
+            printf 'A snapshot of the tracked files in the repository (build output, dependencies, and other\n'
+            printf 'git-ignored paths are excluded).\n\n'
+            printf '```text\n'
+            git ls-files | python3 .gitea/scripts/gen_tree.py "${ROOT_LABEL}"
+            printf '```\n'
+          } > _sync/PROJECT_TREE.md
+          echo "----- generated ${DOCS_PATH} -----"
+          cat _sync/PROJECT_TREE.md
+
+      - name: Open or update the docs PR if the tree changed
+        env:
+          REGISTRY_USER: ${{ secrets.REGISTRY_USER }}
+          REGISTRY_TOKEN: ${{ secrets.REGISTRY_TOKEN }}
+        run: |
+          set -euo pipefail
+          # Secrets can carry a trailing CR/LF depending on how they were pasted;
+          # strip line breaks before they land in a URL or Authorization header.
+          CI_USER="$(printf '%s' "${REGISTRY_USER}" | tr -d '\r\n')"
+          CI_TOKEN="$(printf '%s' "${REGISTRY_TOKEN}" | tr -d '\r\n')"
+          API="https://${GITEA_HOST}/api/v1/repos/${DOCS_REPO}"
+          REMOTE="https://${CI_USER}:${CI_TOKEN}@${GITEA_HOST}/${DOCS_REPO}.git"
+
+          git clone --depth 1 "${REMOTE}" docs_repo
+          cd docs_repo
+          git config user.name  "runic-docs-bot"
+          git config user.email "ci@whitlocktech.com"
+
+          mkdir -p "$(dirname "${DOCS_PATH}")"
+          cp ../_sync/PROJECT_TREE.md "${DOCS_PATH}"
+          git add "${DOCS_PATH}"
+          if git diff --cached --quiet; then
+            echo "PROJECT_TREE.md already up to date — nothing to sync."
+            exit 0
+          fi
+
+          SHORT_SHA="$(echo "${GITHUB_SHA:-local}" | cut -c1-7)"
+          git checkout -B "${PR_BRANCH}"
+          git commit -m "docs(tree): sync ${DOCS_PATH} from ${SELF_REPO}@${SHORT_SHA} [skip ci]"
+          git push --force "${REMOTE}" "HEAD:${PR_BRANCH}"
+
+          # Open a PR only if one isn't already open for this branch (a force-push
+          # to an existing open PR's head updates it in place).
+          OPEN="$(curl -sSf -H "Authorization: token ${CI_TOKEN}" \
+            "${API}/pulls?state=open&limit=50" \
+            | jq --arg b "${PR_BRANCH}" '[.[] | select(.head.ref == $b)] | length')"
+          if [ "${OPEN}" = "0" ]; then
+            curl -sSf -X POST "${API}/pulls" \
+              -H "Authorization: token ${CI_TOKEN}" \
+              -H "Content-Type: application/json" \
+              -d "$(jq -n \
+                    --arg head "${PR_BRANCH}" \
+                    --arg base "main" \
+                    --arg title "docs(tree): sync ${DOCS_PATH}" \
+                    --arg body "Automated project-tree sync from [\`${SELF_REPO}\`](https://${GITEA_HOST}/${SELF_REPO}), regenerated from tracked files on \`main\`. Merge once the layout looks right; the workflow will keep this branch current until then." \
+                    '{head: $head, base: $base, title: $title, body: $body}')" \
+              >/dev/null
+            echo "Opened a new docs PR for ${PR_BRANCH}."
+          else
+            echo "Existing open docs PR for ${PR_BRANCH} was updated via force-push."
+          fi

app/build.gradle.kts

@@ -10,6 +10,11 @@ plugins {
     alias(libs.plugins.kotlin.serialization)
     alias(libs.plugins.ksp)
     alias(libs.plugins.hilt)
+    jacoco
+}
+
+jacoco {
+    toolVersion = "0.8.12"
 }
 
 // Release signing material (PLAN.md §12) is never committed. It is read from, in
@@ -78,6 +83,11 @@ android {
     }
 
     buildTypes {
+        debug {
+            // Produce a JaCoCo .exec from JVM unit tests so SonarQube receives real
+            // coverage (§12.1). Debug-only: the scan analyses the debug variant.
+            enableUnitTestCoverage = true
+        }
         release {
             // R8 full-mode minify + resource shrink (§7: no offline cache, so a lean
             // release APK). Keep rules live in proguard-rules.pro.
@@ -170,3 +180,35 @@ dependencies {
     androidTestImplementation(platform(libs.androidx.compose.bom))
     androidTestImplementation(libs.androidx.compose.ui.test.junit4)
 }
+
+// JaCoCo XML coverage from the JVM unit tests, consumed by SonarQube (§12.1). Generated,
+// DI (Hilt), and Compose-scaffold classes are excluded so they don't dilute the number;
+// pure-@Composable UI is excluded on the Sonar side (sonar.coverage.exclusions) because
+// JVM unit tests can't execute composable bodies without Robolectric.
+tasks.register<JacocoReport>("jacocoTestReport") {
+    dependsOn("testDebugUnitTest")
+    group = "verification"
+    description = "Generates JaCoCo XML/HTML coverage for the debug unit tests."
+
+    reports {
+        xml.required.set(true)
+        html.required.set(true)
+    }
+
+    val coverageExcludes = listOf(
+        "**/R.class", "**/R$*.class", "**/BuildConfig.*", "**/Manifest*.*",
+        "**/*_Hilt*.*", "**/Hilt_*.*", "**/*_Factory*.*", "**/*_MembersInjector*.*",
+        "**/*_Impl*.*", "**/di/**", "**/*Module.*", "**/*Module$*.*",
+        "**/*ComposableSingletons*.*", "**/ComposableSingletons$*.*",
+    )
+    val buildDirFile = layout.buildDirectory.get().asFile
+    classDirectories.setFrom(
+        fileTree("$buildDirFile/tmp/kotlin-classes/debug") { exclude(coverageExcludes) },
+    )
+    sourceDirectories.setFrom(files("src/main/java", "src/main/kotlin"))
+    executionData.setFrom(
+        fileTree(buildDirFile) {
+            include("outputs/unit_test_code_coverage/debugUnitTest/testDebugUnitTest.exec")
+        },
+    )
+}

app/src/main/java/com/runicgateway/app/core/auth/DeviceNameProvider.kt

@@ -0,0 +1,34 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.core.auth
+
+import android.os.Build
+import javax.inject.Inject
+import javax.inject.Singleton
+
+/**
+ * Supplies a friendly label for this device, sent as `device_name` at login so a
+ * trusted-device / active-session row is recognizable in the account lists
+ * (TRUSTED_DEVICES_MFA.md). Behind an interface so the auth repository stays free of
+ * `android.os.Build` and unit-testable on the JVM.
+ */
+fun interface DeviceNameProvider {
+    /** A human label like "Google Pixel 8", or null if nothing meaningful is available. */
+    fun deviceName(): String?
+}
+
+/** Production impl: manufacturer + model from [Build] (e.g. "Samsung SM-S918B"). */
+@Singleton
+class BuildDeviceNameProvider @Inject constructor() : DeviceNameProvider {
+    override fun deviceName(): String? {
+        val manufacturer = Build.MANUFACTURER?.trim().orEmpty()
+        val model = Build.MODEL?.trim().orEmpty()
+        val label = when {
+            model.isEmpty() -> manufacturer
+            manufacturer.isEmpty() || model.startsWith(manufacturer, ignoreCase = true) -> model
+            else -> "$manufacturer $model"
+        }.replaceFirstChar { if (it.isLowerCase()) it.titlecase() else it.toString() }
+        return label.take(100).ifBlank { null }
+    }
+}

app/src/main/java/com/runicgateway/app/core/auth/EncryptedTrustTokenStore.kt

@@ -0,0 +1,65 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.core.auth
+
+import android.content.Context
+import android.content.SharedPreferences
+import androidx.security.crypto.EncryptedSharedPreferences
+import androidx.security.crypto.MasterKey
+import dagger.hilt.android.qualifiers.ApplicationContext
+import javax.inject.Inject
+import javax.inject.Singleton
+
+/**
+ * [TrustTokenStore] backed by its **own** EncryptedSharedPreferences file
+ * (Tink/AES-256-GCM), distinct from the session store so it is never wiped by
+ * [SessionManager.onSignedOut] — the trust token must outlive a logout to do its
+ * job (TRUSTED_DEVICES_MFA.md). The token is stored alongside the username it was
+ * minted for so [tokenFor] only returns it for a matching login.
+ *
+ * The prefs handle is lazy so a device that never trusts pays the keystore cost
+ * only if a token is actually stored or read.
+ */
+@Singleton
+class EncryptedTrustTokenStore @Inject constructor(
+    @param:ApplicationContext private val context: Context,
+) : TrustTokenStore {
+
+    private val prefs: SharedPreferences by lazy {
+        val masterKey = MasterKey.Builder(context)
+            .setKeyScheme(MasterKey.KeyScheme.AES256_GCM)
+            .build()
+        EncryptedSharedPreferences.create(
+            context,
+            PREFS_NAME,
+            masterKey,
+            EncryptedSharedPreferences.PrefKeyEncryptionScheme.AES256_SIV,
+            EncryptedSharedPreferences.PrefValueEncryptionScheme.AES256_GCM,
+        )
+    }
+
+    override fun tokenFor(username: String): String? {
+        val token = prefs.getString(KEY_TOKEN, null) ?: return null
+        val owner = prefs.getString(KEY_USERNAME, null) ?: return null
+        // Case-insensitive: usernames are matched case-insensitively server-side.
+        return if (owner.equals(username, ignoreCase = true)) token else null
+    }
+
+    override fun save(username: String, token: String) {
+        prefs.edit()
+            .putString(KEY_TOKEN, token)
+            .putString(KEY_USERNAME, username)
+            .apply()
+    }
+
+    override fun clear() {
+        prefs.edit().clear().apply()
+    }
+
+    private companion object {
+        const val PREFS_NAME = "runic_trust"
+        const val KEY_TOKEN = "trust_token"
+        const val KEY_USERNAME = "trust_username"
+    }
+}

app/src/main/java/com/runicgateway/app/core/auth/TrustTokenStore.kt

@@ -0,0 +1,31 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.core.auth
+
+/**
+ * At-rest home for the opaque trusted-device token (TRUSTED_DEVICES_MFA.md). It is
+ * the native analogue of the web `rg_trust` cookie: a device that holds a valid
+ * token skips the TOTP step on its next login (never the password).
+ *
+ * Deliberately **separate** from [TokenStore] and untouched by session teardown —
+ * the token must **survive logout and a dead-refresh sign-out**, because it is only
+ * ever consulted at a *fresh* login (exactly the moment after the session is gone).
+ * Clearing it there would make the feature a no-op. It is scoped to the username it
+ * was minted for so it is never replayed for a different account on a shared device,
+ * and is cleared only by an explicit untrust, a Settings → Server switch, or a
+ * server-side revocation (password change/reset, TOTP disable) that renders it dead.
+ *
+ * Tokens are sensitive, so the production impl uses EncryptedSharedPreferences —
+ * never plain prefs or logs. Kept behind an interface for an in-memory test fake.
+ */
+interface TrustTokenStore {
+    /** The stored trust token for [username], or null if this device isn't trusted for them. */
+    fun tokenFor(username: String): String?
+
+    /** Persist [token] as the trust token for [username] (overwrites any prior one). */
+    fun save(username: String, token: String)
+
+    /** Drop the trust token — untrust-all and the Settings → Server hard reset. */
+    fun clear()
+}

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

@@ -5,6 +5,7 @@ package com.runicgateway.app.core.auth.sso
 
 import com.runicgateway.app.BuildConfig
 import com.runicgateway.app.core.auth.SessionManager
+import com.runicgateway.app.core.auth.TrustTokenStore
 import com.runicgateway.app.core.net.BaseUrlHolder
 import com.runicgateway.app.data.api.SsoApi
 import com.runicgateway.app.data.api.dto.MobileSsoExchangeRequest
@@ -49,6 +50,7 @@ class SsoAuthManager @Inject constructor(
     private val sessionManager: SessionManager,
     private val baseUrlHolder: BaseUrlHolder,
     private val pendingStore: PendingSsoStore,
+    private val trustTokenStore: TrustTokenStore,
 ) {
 
     /** Why an SSO attempt ended, for a friendly inline message on the login screen. */
@@ -193,6 +195,14 @@ class SsoAuthManager @Inject constructor(
                 _outcome.value = Outcome.Failed(Failure.SERVER)
                 return
             }
+            // The user ticked "trust this device" on the TOTP form inside the Custom
+            // Tab. That tab's cookie already covers future SSO sign-ins; persisting
+            // the token the exchange handed back is what lets a native PASSWORD login
+            // on this device skip the code too (TRUSTED_DEVICES_MFA.md). Scoped to the
+            // username exactly like the password path, so it is never replayed for a
+            // different account on a shared device. Saved BEFORE onSignedIn so a
+            // process death mid-callback can't lose it.
+            body.trustToken?.let { trustTokenStore.save(body.user.username, it) }
             sessionManager.onSignedIn(body.accessToken, body.refreshToken, body.user)
             _outcome.value = Outcome.Success
             return

app/src/main/java/com/runicgateway/app/core/net/ShardStream.kt

@@ -0,0 +1,16 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.core.net
+
+import kotlinx.coroutines.flow.Flow
+
+/**
+ * The live shard SSE feed as a cold flow of lifecycle + frame events (PLAN.md §6.2,
+ * §7). Extracted as an interface so consumers (e.g. [com.runicgateway.app.data.repository.ShardRepository])
+ * depend on the capability, not the OkHttp-backed [ShardStreamClient] — the boards
+ * can then be unit-tested against a fake stream instead of a real network connection.
+ */
+interface ShardStream {
+    fun events(): Flow<ShardStreamEvent>
+}

app/src/main/java/com/runicgateway/app/core/net/ShardStreamClient.kt

@@ -40,7 +40,7 @@ class ShardStreamClient @Inject constructor(
     baseClient: OkHttpClient,
     private val baseUrlHolder: BaseUrlHolder,
     private val json: Json,
-) {
+) : ShardStream {
     // SSE is a long-lived, mostly-idle connection (keepalive comments every ~25s),
     // so the read timeout must be disabled or the idle stream would be killed.
     private val sseClient: OkHttpClient = baseClient.newBuilder()
@@ -56,7 +56,7 @@ class ShardStreamClient @Inject constructor(
      * drive a live/offline indicator; [ShardStreamEvent.Frame] carries a decoded
      * `{ kind, … }` payload the boards merge in place.
      */
-    fun events(): Flow<ShardStreamEvent> = channelFlow {
+    override fun events(): Flow<ShardStreamEvent> = channelFlow {
         var backoffMs = INITIAL_BACKOFF_MS
         while (isActive) {
             val url = baseUrlHolder.current?.resolve(STREAM_PATH)

app/src/main/java/com/runicgateway/app/core/result/ApiResult.kt

@@ -4,6 +4,7 @@
 package com.runicgateway.app.core.result
 
 import kotlinx.coroutines.CancellationException
+import kotlinx.serialization.SerializationException
 import retrofit2.HttpException
 import java.io.IOException
 
@@ -37,6 +38,16 @@ inline fun <T, R> ApiResult<T>.map(transform: (T) -> R): ApiResult<R> = when (th
  * Run a suspending Retrofit call and normalize every outcome into an [ApiResult].
  * Coroutine cancellation is rethrown so structured concurrency still works — it
  * is control flow, not a network failure.
+ *
+ * A body the app can't decode (a field whose type/shape doesn't match its DTO, e.g.
+ * a live-shaped `guild.update` snapshot carrying an unexpected value) throws a
+ * [SerializationException] out of the Retrofit converter. That is a broken contract
+ * with the backend, not a bug to crash on: the request completed but the response is
+ * unusable — an invalid upstream response — so it is surfaced as a server-side error
+ * (`502` → [ErrorKind.SERVER]) the screen renders as "something went wrong, retry",
+ * exactly the graceful-degradation the layer promises (never throw for an expected
+ * failure). Without this catch the exception escapes the collecting coroutine and
+ * takes down the whole app.
  */
 suspend fun <T> safeApiCall(block: suspend () -> T): ApiResult<T> = try {
     ApiResult.Ok(block())
@@ -46,4 +57,9 @@ suspend fun <T> safeApiCall(block: suspend () -> T): ApiResult<T> = try {
     ApiResult.HttpError(e.code(), e.message())
 } catch (e: IOException) {
     ApiResult.NetworkError(e)
+} catch (e: SerializationException) {
+    ApiResult.HttpError(MALFORMED_RESPONSE_STATUS, e.message)
 }
+
+/** Synthetic status for a 2xx body the app couldn't decode — an invalid upstream response. */
+private const val MALFORMED_RESPONSE_STATUS = 502

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

@@ -10,6 +10,7 @@ import com.runicgateway.app.data.api.dto.MobileTokenResponse
 import retrofit2.Response
 import retrofit2.http.Body
 import retrofit2.http.GET
+import retrofit2.http.Header
 import retrofit2.http.Headers
 import retrofit2.http.POST
 
@@ -27,9 +28,15 @@ import retrofit2.http.POST
 interface AuthApi {
 
     // Literal header value required by Retrofit @Headers; matches Http.NO_SESSION_HEADER.
+    // [trustToken] rides the `X-Trust-Token` header (TRUSTED_DEVICES_MFA.md): a valid
+    // token bound to this user lets the server skip the TOTP step. Retrofit omits the
+    // header entirely when it is null, so an untrusted device sends nothing.
     @Headers("X-Runic-No-Session: 1")
     @POST("api/v1/auth/mobile/login")
-    suspend fun login(@Body body: MobileLoginRequest): Response<MobileTokenResponse>
+    suspend fun login(
+        @Body body: MobileLoginRequest,
+        @Header("X-Trust-Token") trustToken: String? = null,
+    ): Response<MobileTokenResponse>
 
     @POST("api/v1/auth/mobile/logout")
     suspend fun logout(@Body body: MobileLogoutRequest): Response<Unit>

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

@@ -7,11 +7,21 @@ 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.RecoveryCodesDto
+import com.runicgateway.app.data.api.dto.RecoveryGenerateRequest
+import com.runicgateway.app.data.api.dto.RecoveryStatusDto
+import com.runicgateway.app.data.api.dto.RevokedCountDto
+import com.runicgateway.app.data.api.dto.RevokedFlagDto
 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.TrustDeviceRequest
+import com.runicgateway.app.data.api.dto.TrustDeviceResultDto
+import com.runicgateway.app.data.api.dto.TrustedDeviceDto
 import com.runicgateway.app.data.api.dto.UsernameResponse
+import retrofit2.Response
 import retrofit2.http.Body
+import retrofit2.http.DELETE
 import retrofit2.http.GET
 import retrofit2.http.HTTP
 import retrofit2.http.PATCH
@@ -52,4 +62,28 @@ interface MeApi {
     // 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
+
+    // ── Trusted devices (TRUSTED_DEVICES_MFA.md) — devices allowed to skip TOTP ──
+
+    @GET("api/v1/auth/me/trusted-devices")
+    suspend fun trustedDevices(): List<TrustedDeviceDto>
+
+    // Raw [Response] so the caller can read the `409 { error, devices }` cap body,
+    // which a thrown HttpException would discard.
+    @POST("api/v1/auth/me/trusted-devices")
+    suspend fun trustThisDevice(@Body body: TrustDeviceRequest): Response<TrustDeviceResultDto>
+
+    @DELETE("api/v1/auth/me/trusted-devices/{id}")
+    suspend fun revokeTrustedDevice(@Path("id") id: Long): RevokedFlagDto
+
+    @DELETE("api/v1/auth/me/trusted-devices")
+    suspend fun revokeAllTrustedDevices(): RevokedCountDto
+
+    // ── Recovery (backup) codes ──────────────────────────────────────────────
+
+    @GET("api/v1/auth/me/account/recovery-codes/status")
+    suspend fun recoveryCodesStatus(): RecoveryStatusDto
+
+    @POST("api/v1/auth/me/account/recovery-codes/generate")
+    suspend fun generateRecoveryCodes(@Body body: RecoveryGenerateRequest): RecoveryCodesDto
 }

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

@@ -3,6 +3,9 @@
  */
 package com.runicgateway.app.data.api
 
+import com.runicgateway.app.data.api.dto.AtlasCreatureDto
+import com.runicgateway.app.data.api.dto.AtlasCreaturePageDto
+import com.runicgateway.app.data.api.dto.AtlasMetaDto
 import com.runicgateway.app.data.api.dto.ChampDto
 import com.runicgateway.app.data.api.dto.ContactRequest
 import com.runicgateway.app.data.api.dto.ContactResponse
@@ -12,11 +15,17 @@ import com.runicgateway.app.data.api.dto.GovernorDto
 import com.runicgateway.app.data.api.dto.GovernorTermDto
 import com.runicgateway.app.data.api.dto.GuildDto
 import com.runicgateway.app.data.api.dto.HouseDto
+import com.runicgateway.app.data.api.dto.MarketMetaDto
+import com.runicgateway.app.data.api.dto.MarketPageDto
+import com.runicgateway.app.data.api.dto.MarketVendorDto
 import com.runicgateway.app.data.api.dto.OnlineStaffDto
 import com.runicgateway.app.data.api.dto.PageDto
+import com.runicgateway.app.data.api.dto.PointsBoardDto
 import com.runicgateway.app.data.api.dto.PostDto
 import com.runicgateway.app.data.api.dto.PresenceDto
+import com.runicgateway.app.data.api.dto.RulesetDto
 import com.runicgateway.app.data.api.dto.SettingsDto
+import com.runicgateway.app.data.api.dto.ShardFeaturesDto
 import com.runicgateway.app.data.api.dto.ShardStatusDto
 import com.runicgateway.app.data.api.dto.StatusDto
 import com.runicgateway.app.data.api.dto.WikiCategoryDto
@@ -93,6 +102,14 @@ interface PublicApi {
     suspend fun postContact(@Body body: ContactRequest): ContactResponse
 
     // ── Public shard widgets (§6.2) ──────────────────────────────────────
+    /**
+     * Which shard features this caller may reach, so the menu hides entries instead
+     * of rendering links that 404/403 (§5, M11). Answered per-viewer: an anonymous
+     * call and a signed-in one can differ.
+     */
+    @GET("api/v1/public/shard/features")
+    suspend fun getShardFeatures(): ShardFeaturesDto
+
     @GET("api/v1/public/shard/status")
     suspend fun getShardStatus(): ShardStatusDto
 
@@ -128,4 +145,65 @@ interface PublicApi {
 
     @GET("api/v1/public/shard/houses")
     suspend fun getShardHouses(): List<HouseDto>
+
+    // ── Protocol 3.0 shard content (§9 M11) ──────────────────────────────
+    //
+    // Each of these sits behind the website's `requireFeature` gate: a 404 means the
+    // shard doesn't publish it and a 403 means this viewer is below its audience rung,
+    // which `toShardUiState()` folds into one "not available here" state.
+
+    /** The shard's configured ruleset. A `null` body means "not published yet". */
+    @GET("api/v1/public/shard/ruleset")
+    suspend fun getShardRuleset(): RulesetDto?
+
+    /** Every points/loyalty leaderboard the shard publishes. */
+    @GET("api/v1/public/shard/points")
+    suspend fun getShardPoints(): List<PointsBoardDto>
+
+    @GET("api/v1/public/shard/points/{system}")
+    suspend fun getShardPointsBoard(@Path("system") system: String): PointsBoardDto
+
+    /**
+     * Search the player-vendor index. **Rate-limited** — the first genuinely expensive
+     * public endpoint on the site, so handle `429` (`ErrorKind.RATE_LIMITED`).
+     */
+    @GET("api/v1/public/shard/market")
+    suspend fun getShardMarket(
+        @Query("q") query: String? = null,
+        @Query("minPrice") minPrice: Long? = null,
+        @Query("maxPrice") maxPrice: Long? = null,
+        @Query("map") map: String? = null,
+        @Query("region") region: String? = null,
+        @Query("sort") sort: String? = null,
+        @Query("limit") limit: Int? = null,
+        @Query("offset") offset: Int? = null,
+    ): MarketPageDto
+
+    /** Index size, staleness, and which facets/regions actually hold vendors. */
+    @GET("api/v1/public/shard/market/meta")
+    suspend fun getShardMarketMeta(): MarketMetaDto
+
+    @GET("api/v1/public/shard/market/vendors/{serial}")
+    suspend fun getShardMarketVendor(
+        @Path("serial") serial: String,
+        @Query("limit") limit: Int? = null,
+        @Query("offset") offset: Int? = null,
+    ): MarketVendorDto
+
+    // The atlas lives under /public/atlas, NOT /public/shard: it is static shard
+    // content parsed from the server's data files, so it stays readable while the
+    // shard is down — but it IS site-mode gated, unlike the shard routes.
+    @GET("api/v1/public/atlas/creatures")
+    suspend fun getAtlasCreatures(
+        @Query("q") query: String? = null,
+        @Query("facet") facet: String? = null,
+        @Query("limit") limit: Int? = null,
+        @Query("offset") offset: Int? = null,
+    ): AtlasCreaturePageDto
+
+    @GET("api/v1/public/atlas/creatures/{slug}")
+    suspend fun getAtlasCreature(@Path("slug") slug: String): AtlasCreatureDto
+
+    @GET("api/v1/public/atlas/meta")
+    suspend fun getAtlasMeta(): AtlasMetaDto
 }

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

@@ -55,9 +55,78 @@ data class TotpSetupDto(
 @Serializable
 data class TotpCodeRequest(val code: String)
 
-/** Result of enabling/disabling 2FA. */
+/**
+ * Result of enabling/disabling 2FA. Enabling also returns the freshly generated
+ * single-use [recoveryCodes] **once** (null on disable and for older backends) — the
+ * app shows them for the user to save and never persists them.
+ */
 @Serializable
-data class TotpStateDto(val totp_enabled: Boolean = false)
+data class TotpStateDto(
+    val totp_enabled: Boolean = false,
+    val recoveryCodes: List<String>? = null,
+)
+
+// ── Trusted devices & recovery codes (TRUSTED_DEVICES_MFA.md) ───────────────
+
+/**
+ * An active trusted device (`GET /auth/me/trusted-devices`): a browser/app allowed
+ * to skip the TOTP step at login. Never carries the token. Timestamps are ISO-8601
+ * strings shown as-is (advisory display).
+ */
+@Serializable
+data class TrustedDeviceDto(
+    val id: Long = 0,
+    val platform: String? = null,
+    val deviceName: String? = null,
+    val userAgent: String? = null,
+    val createdAt: String? = null,
+    val lastUsedAt: String? = null,
+    val expiresAt: String? = null,
+)
+
+/** `POST /auth/me/trusted-devices` body — an optional friendly label. */
+@Serializable
+data class TrustDeviceRequest(val deviceName: String? = null)
+
+/**
+ * `POST /auth/me/trusted-devices` success (native): the opaque [trustToken] to store
+ * and replay via `X-Trust-Token`. Web receives the token as a cookie and no body token.
+ */
+@Serializable
+data class TrustDeviceResultDto(
+    val trusted: Boolean = false,
+    val trustToken: String? = null,
+)
+
+/**
+ * `409 { error: "trusted_device_limit", devices }` from a trust attempt at the cap —
+ * the app lists [devices] and asks the user to revoke one, then retry.
+ */
+@Serializable
+data class TrustedDeviceLimitDto(
+    val error: String? = null,
+    val devices: List<TrustedDeviceDto> = emptyList(),
+)
+
+/** `DELETE /auth/me/trusted-devices/:id` — idempotent single-revoke result. */
+@Serializable
+data class RevokedFlagDto(val revoked: Boolean = false)
+
+/** `DELETE /auth/me/trusted-devices` — count of devices untrusted ("untrust all"). */
+@Serializable
+data class RevokedCountDto(val revoked: Int = 0)
+
+/** `GET /auth/me/account/recovery-codes/status` — remaining unused count only. */
+@Serializable
+data class RecoveryStatusDto(val remaining: Int = 0)
+
+/** `POST /auth/me/account/recovery-codes/generate` body — password step-up. */
+@Serializable
+data class RecoveryGenerateRequest(val currentPassword: String? = null)
+
+/** A fresh single-use recovery-code batch, returned **once** (generate + totp enable). */
+@Serializable
+data class RecoveryCodesDto(val recoveryCodes: List<String> = emptyList())
 
 /** A linked external identity (`GET /auth/me/account/identities`). */
 @Serializable

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

@@ -12,12 +12,23 @@ import kotlinx.serialization.Serializable
  * safe (§8, recorded for M1).
  */
 
-/** `POST /auth/mobile/login` body. [code] is only sent on the 2FA retry. */
+/**
+ * `POST /auth/mobile/login` body (trusted-devices contract, TRUSTED_DEVICES_MFA.md).
+ * [code] is only sent on the 2FA retry; [recoveryCode] is its single-use fallback
+ * (sent instead of [code]). [trustDevice] asks the server to remember this device so
+ * future logins skip the second factor — on success the response carries a
+ * [MobileTokenResponse.trustToken] the app stores and replays via `X-Trust-Token`.
+ * [device_name] labels the resulting trusted-device / session row (snake_case to
+ * match the backend field exactly).
+ */
 @Serializable
 data class MobileLoginRequest(
     val username: String,
     val password: String,
     val code: String? = null,
+    val recoveryCode: String? = null,
+    val trustDevice: Boolean? = null,
+    val device_name: String? = null,
 )
 
 /** `POST /auth/mobile/refresh` body. */
@@ -34,6 +45,11 @@ data class MobileLogoutRequest(
 /**
  * Success payload from login and refresh: the token pair, the access lifetime
  * (a zeit/ms duration string, e.g. "15m"), and the safe (secret-stripped) user.
+ *
+ * Login additionally carries the trusted-device outcome when `trustDevice` was set:
+ * [trustToken] is the opaque token to persist + replay (present only when the trust
+ * was accepted), or [trustLimitReached] + [devices] when the per-user cap blocked it
+ * (the login itself still succeeded). Refresh never sets these.
  */
 @Serializable
 data class MobileTokenResponse(
@@ -41,6 +57,9 @@ data class MobileTokenResponse(
     val refreshToken: String,
     val expiresIn: String? = null,
     val user: SafeUserDto,
+    val trustToken: String? = null,
+    val trustLimitReached: Boolean = false,
+    val devices: List<TrustedDeviceDto> = emptyList(),
 )
 
 /** The minimal, non-sensitive user the app needs to render + gate the menu (§5). */

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

@@ -60,8 +60,15 @@ data class NotificationStreamsDto(
  * `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.
+ *
+ * [streams] intentionally has NO default: this DTO doubles as the PUT body, and the
+ * backend validator requires the `streams` field (`body('streams').isArray()`).
+ * kotlinx omits a property equal to its default (encodeDefaults=false), so a default
+ * of `emptyList()` would drop the field when the user clears their LAST subscription,
+ * sending `{}` → 400 "Validation failed" (the "can't turn off the last one" bug). With
+ * no default the empty list always serializes as `{"streams":[]}`. Do not re-add a default.
  */
 @Serializable
 data class NotificationSubscriptionsDto(
-    val streams: List<String> = emptyList(),
+    val streams: List<String>,
 )

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

@@ -14,8 +14,8 @@ import kotlinx.serialization.json.JsonObject
  * `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.
+ * In-game serials are hex strings (e.g. "0x24C"), the same opaque-key form used on
+ * the public boards (`ShardDto.ActorDto`/`ChampDto`/`HouseDto`) — never numbers.
  */
 
 // ── Game-account linking ─────────────────────────────────────────────────────
@@ -83,8 +83,47 @@ data class CharProfileDto(
     val titles: TitlesDto? = null,
     val guild: GuildRefDto? = null,
     val governorOf: List<String> = emptyList(),
+    /**
+     * Loyalty / points standings (Protocol 3.0 §7.3). Empty for a character that has
+     * earned nothing anywhere — the shard omits systems the character has no entry in
+     * — and empty on a shard whose plugin predates 3.0.
+     *
+     * Served **ungated**: a character's own standings are self-service data on
+     * `/player/shard/char/:serial` and do not depend on the public `leaderboards`
+     * feature being visible. Don't re-gate them app-side.
+     */
+    val points: List<CharPointsDto> = emptyList(),
 )
 
+/**
+ * One point system a character holds a score in (Protocol 3.0 §7.3).
+ *
+ * Three shapes here are counter-intuitive, and all three are what a REAL shard sends
+ * (`docs/link/v3.md` §7.5 — a fake shard emits whatever the spec says it should):
+ *
+ *  - **[maxPoints] `0` means UNCAPPED, and is the common case**, not an edge case.
+ *    ServUO's idiom for an uncapped system is `double.MaxValue`, which the plugin
+ *    normalises to `0` because the C# cast is unchecked and yielded `long.MinValue`.
+ *    Nothing may divide by it, and a full-width progress bar for an uncapped score
+ *    would imply a completion that doesn't exist.
+ *  - **[nameString] is usually `null`.** Most systems name themselves with a cliloc
+ *    rather than a literal, so humanising [system] (`QueensLoyalty` → "Queens
+ *    Loyalty") is the PRIMARY display path, not a defensive fallback.
+ *  - **[rank] is absent unless the shard runs `Bridge.cfg PointsProfileRank=true`.**
+ *    Absent and "unranked" are different answers, so it renders only when sent.
+ */
+@Serializable
+data class CharPointsDto(
+    val system: String? = null,
+    val nameString: String? = null,
+    val points: Long? = null,
+    val maxPoints: Long? = null,
+    val rank: Int? = null,
+) {
+    /** The cap, or null when the system is uncapped (see [maxPoints]). */
+    val cap: Long? get() = maxPoints?.takeIf { it > 0 }
+}
+
 @Serializable
 data class CharStatsDto(
     val str: Int? = null,
@@ -134,17 +173,45 @@ data class EquipmentDto(
     val itemId: Int? = null,
     val hue: Int? = null,
     val mods: JsonObject? = null,
-)
+    /**
+     * A player-given name — set for the minority of items someone has renamed, null
+     * for almost everything else. The shard sends the plain `Item.Name` field; it
+     * never builds a display name (that call is a packet builder, not a field read).
+     */
+    val name: String? = null,
+    /**
+     * The item's type name, resolved from its cliloc id **by the website** against
+     * its own table (`docs/website/CLILOCS.md`). Null on a shard that has no cliloc
+     * table configured, which is fully supported — the sheet then falls back to the
+     * layer, exactly as it did before the table existed.
+     */
+    val clilocName: String? = null,
+) {
+    /**
+     * What to call this item.
+     *
+     * A player-given [name] outranks the resolved type name — "Bob's lucky axe" must
+     * not be relabelled "hatchet" — and the server applies the same precedence, so
+     * this only re-states it for an item that arrived with both.
+     */
+    val label: String? get() = name ?: clilocName ?: layer
+}
 
 /**
- * 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).
+ * 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.
+ *
+ * [rewardResolved] is the website's **parallel array** with the numeric entries turned
+ * into words against its cliloc table — same length and order as [reward], with a null
+ * where an id resolved to nothing. It is absent entirely when no entry was numeric or
+ * the shard has no cliloc table, so read it positionally and tolerate it being short.
+ * See `displayTitles` in the character sheet.
  */
 @Serializable
 data class TitlesDto(
     val selected: Int? = null,
     val reward: List<String> = emptyList(),
+    val rewardResolved: List<String?> = emptyList(),
     val fameKarma: String? = null,
     val skill: String? = null,
 )

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

@@ -0,0 +1,367 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.data.api.dto
+
+import kotlinx.serialization.Serializable
+
+/**
+ * DTOs for the four shard-content surfaces Protocol 3.0 added (PLAN.md §9 M11):
+ * the ruleset, the points leaderboards, the player-vendor marketplace, and the spawn
+ * atlas. Shapes mirror the website's `public/shard.controller.js` + `public/atlas.
+ * controller.js` responses; see `docs/link/v3.md` §5–§8.
+ *
+ * Every field is nullable-with-a-default, which is load-bearing rather than merely
+ * defensive here: an admin can gate individual fields away per audience rung
+ * (`ownerName`, `location`, a board's `name`), so a response legitimately arrives
+ * with them missing and must still decode.
+ */
+
+// ── Ruleset (§5) ────────────────────────────────────────────────────────────
+
+/**
+ * `GET /public/shard/ruleset` — what this shard's world is configured to do.
+ *
+ * Every block is optional and omitted when its system is off, so a null block means
+ * "not applicable here", not "unknown". A `null` BODY (rather than an empty object)
+ * means the shard has never published a ruleset — distinct from the feature being
+ * switched off, which is a 404.
+ */
+@Serializable
+data class RulesetDto(
+    val shard: String? = null,
+    val expansion: String? = null,
+    /**
+     * The public connect address, published only when the operator set one. It is
+     * also the ruleset's one admin-configurable field, so it can be present for a
+     * signed-in viewer and absent for an anonymous one.
+     */
+    val connect: String? = null,
+    /** A flat bag of on/off flags — `cityLoyalty`, `vvv`, `siege`, `chat`, … */
+    val systems: Map<String, Boolean> = emptyMap(),
+    val caps: RulesetCapsDto? = null,
+    val accounts: RulesetAccountsDto? = null,
+    val housing: RulesetHousingDto? = null,
+    val vetRewards: RulesetVetRewardsDto? = null,
+    val vendors: RulesetVendorsDto? = null,
+    val vvv: RulesetVvvDto? = null,
+    val store: RulesetStoreDto? = null,
+    val schedule: RulesetScheduleDto? = null,
+    val updatedAt: String? = null,
+)
+
+/**
+ * Skill and stat caps.
+ *
+ * **[skill] and [totalSkill] are in TENTHS** — 1000 is 100.0 — the way ServUO stores
+ * them, and the raw number is actively misleading rather than merely unhelpful (a
+ * "1000 skill cap" reads as a shard with ten times the usual limit). Use [skillCap]
+ * and [totalSkillCap]. The stat caps below them are plain values.
+ */
+@Serializable
+data class RulesetCapsDto(
+    val skill: Int? = null,
+    val totalSkill: Int? = null,
+    val stat: Int? = null,
+    val str: Int? = null,
+    val dex: Int? = null,
+    val int: Int? = null,
+    val strMax: Int? = null,
+    val dexMax: Int? = null,
+    val intMax: Int? = null,
+) {
+    val skillCap: Double? get() = skill?.let { it / 10.0 }
+    val totalSkillCap: Double? get() = totalSkill?.let { it / 10.0 }
+}
+
+@Serializable
+data class RulesetAccountsDto(
+    val perIp: Int? = null,
+    val charSlots: Int? = null,
+    val autoCreate: Boolean? = null,
+)
+
+@Serializable
+data class RulesetHousingDto(val accountHouseLimit: Int? = null)
+
+@Serializable
+data class RulesetVetRewardsDto(
+    val enabled: Boolean? = null,
+    val rewardIntervalDays: Int? = null,
+)
+
+@Serializable
+data class RulesetVendorsDto(
+    val restockDelayMinutes: Int? = null,
+    val maxSell: Int? = null,
+    val economyStockAmount: Int? = null,
+)
+
+@Serializable
+data class RulesetVvvDto(
+    val enabled: Boolean? = null,
+    val startSilver: Int? = null,
+    val enhancedRules: Boolean? = null,
+)
+
+@Serializable
+data class RulesetStoreDto(
+    val enabled: Boolean? = null,
+    val currencyName: String? = null,
+)
+
+@Serializable
+data class RulesetScheduleDto(
+    val autoSaveFrequencyMinutes: Int? = null,
+    val autoRestartEnabled: Boolean? = null,
+    val autoRestartHour: Int? = null,
+    val autoRestartMinute: Int? = null,
+)
+
+// ── Leaderboards (§7) ───────────────────────────────────────────────────────
+
+/**
+ * One point system's board (`GET /public/shard/points`, `/points/:system`).
+ *
+ * [maxPoints] `0` means **uncapped** and is the common case, and [nameString] is
+ * usually null because most systems name themselves with a cliloc — the same two
+ * traps as [CharPointsDto], documented in full there.
+ *
+ * [players] counts players actually *holding* points, not the entry count: ten of the
+ * shard's systems auto-add a zero-point row for every character ever created, so the
+ * raw count would report the whole census as one system's participants.
+ */
+@Serializable
+data class PointsBoardDto(
+    val system: String? = null,
+    val nameString: String? = null,
+    val nameNumber: Int? = null,
+    val maxPoints: Long? = null,
+    val players: Int? = null,
+    val showOnGump: Boolean = true,
+    val top: List<PointsEntryDto> = emptyList(),
+    val t: Long? = null,
+    val updatedAt: String? = null,
+) {
+    /** The cap, or null when the system is uncapped. */
+    val cap: Long? get() = maxPoints?.takeIf { it > 0 }
+}
+
+/**
+ * A ranked character on a board. [name] is admin-configurable (the `leaderboards`
+ * feature's one field rule), so a shard can publish standings without naming who
+ * holds them — a rank with no name is a valid row, not a broken one.
+ */
+@Serializable
+data class PointsEntryDto(
+    val rank: Int? = null,
+    val serial: String? = null,
+    val name: String? = null,
+    val points: Long? = null,
+)
+
+// ── Marketplace (§8) ────────────────────────────────────────────────────────
+
+/**
+ * Where a shop stands. **Nested, not flattened**, on the wire and in the read model
+ * alike, so that ONE admin rule hides the facet, the coordinates, the region and the
+ * house together — five flat keys would be five rules that drift apart (`v3.md` §8.8).
+ * A null location means an admin gated it away; render that as an answer, not a blank.
+ */
+@Serializable
+data class MarketLocationDto(
+    val map: String? = null,
+    val x: Int? = null,
+    val y: Int? = null,
+    val z: Int? = null,
+    val region: String? = null,
+    val house: String? = null,
+)
+
+/** The shop a listing belongs to, as embedded in a search result. */
+@Serializable
+data class MarketVendorRefDto(
+    val serial: String? = null,
+    val shopName: String? = null,
+    val ownerName: String? = null,
+    val location: MarketLocationDto? = null,
+)
+
+/**
+ * One item for sale. [displayName] is resolved server-side against the site's cliloc
+ * table, preferring a player-set [name]; a shard with no cliloc table configured sends
+ * neither and the item renders by id.
+ *
+ * [child] marks an item priced by an enclosing container rather than itself, exactly
+ * as the in-game Vendor Search reports it.
+ */
+@Serializable
+data class MarketListingDto(
+    val serial: String? = null,
+    val itemId: Int? = null,
+    val hue: Int? = null,
+    val amount: Int? = null,
+    val price: Long? = null,
+    val name: String? = null,
+    val cliloc: Int? = null,
+    val displayName: String? = null,
+    val child: Boolean = false,
+    val vendor: MarketVendorRefDto? = null,
+) {
+    /** What to call this item; null when the shard publishes no name for it. */
+    val label: String? get() = name ?: displayName
+}
+
+/**
+ * A page of search results (`GET /public/shard/market`).
+ *
+ * Returns **listings, not vendors**: "who sells a vanquishing kryss and for how much"
+ * is the question, and a vendor-shaped result would make every caller flatten the
+ * shops back out.
+ *
+ * [staleAt] is the oldest vendor timestamp in the index and **must be surfaced**. The
+ * shard sweeps vendors round-robin, so a listing can legitimately be a full cycle old;
+ * a page implying live prices sends someone to an item that sold twenty minutes ago.
+ */
+@Serializable
+data class MarketPageDto(
+    val listings: List<MarketListingDto> = emptyList(),
+    val total: Int = 0,
+    val limit: Int? = null,
+    val offset: Int? = null,
+    val vendors: Int? = null,
+    val staleAt: String? = null,
+)
+
+/**
+ * One shop and its stock (`GET /public/shard/market/vendors/:serial`).
+ *
+ * [truncated] means the shard publishes only the first `MarketMaxListings` of a larger
+ * inventory — [count] is what is published, [total] what the shop holds. Saying so is
+ * the point of this screen: a search result list cannot express it.
+ */
+@Serializable
+data class MarketVendorDto(
+    val serial: String? = null,
+    val shopName: String? = null,
+    val ownerSerial: String? = null,
+    val ownerName: String? = null,
+    val location: MarketLocationDto? = null,
+    val count: Int? = null,
+    val total: Int? = null,
+    val truncated: Boolean = false,
+    val updatedAt: String? = null,
+    val items: List<MarketListingDto> = emptyList(),
+)
+
+/** Index size, staleness and the filter options that actually hold vendors. */
+@Serializable
+data class MarketMetaDto(
+    val vendors: Int = 0,
+    val items: Int = 0,
+    val staleAt: String? = null,
+    val freshAt: String? = null,
+    val maps: List<String> = emptyList(),
+    val regions: List<String> = emptyList(),
+)
+
+// ── Spawn atlas (§6) ────────────────────────────────────────────────────────
+
+/**
+ * A creature in the bestiary. Served from `/public/atlas`, **not** `/public/shard`:
+ * the atlas is static shard *content* parsed from the server's own data files, not
+ * live shard *state*, so it does not go offline with the sidecar — but unlike the
+ * shard routes it IS site-mode gated, like posts and the wiki.
+ *
+ * [points] is a **count** of spawners; [spawners] is the list, and only the
+ * single-creature route sends it. The two names are one letter apart in meaning and
+ * were deliberately separated (`v3.md` §6.3) — do not reuse one for the other.
+ */
+@Serializable
+data class AtlasCreatureDto(
+    val slug: String? = null,
+    val name: String? = null,
+    /** How many can be alive at once, summed across every spawner. */
+    val total: Int? = null,
+    /** How many spawners mention this creature. */
+    val points: Int? = null,
+    /** Spawner count per facet. */
+    val facets: Map<String, Int> = emptyMap(),
+    /**
+     * Where it appears, aggregated per named place — the detail route only, and the
+     * answer the whole screen exists to give. **Objects, not strings:** the server
+     * sends `{facet, label, spawners, maxAlive}`, and typing this `List<String>`
+     * made the detail route fail to decode entirely.
+     */
+    val places: List<AtlasPlaceDto> = emptyList(),
+    /**
+     * Operator-supplied sprite file name under `/uploads/atlas/`, or null — which is
+     * the normal state, since no artwork ships. Neither client renders it yet; the
+     * field is carried so a decode never depends on that staying true.
+     */
+    val art: String? = null,
+    val spawners: List<AtlasSpawnerDto> = emptyList(),
+    val spawnersTruncated: Boolean = false,
+    /** Creatures sharing its spawners — the detail route only. */
+    val alsoHere: List<AtlasCreatureDto> = emptyList(),
+)
+
+/**
+ * One named place a creature spawns in, already aggregated across its spawners.
+ *
+ * [label] is the server's point-in-rect resolution of raw coordinates ("Shrines",
+ * "Isamu-Jima", "Yew"), falling back to the nearest landmark and finally
+ * "Wilderness" — turning a list of coordinates into an answer.
+ */
+@Serializable
+data class AtlasPlaceDto(
+    val facet: String? = null,
+    val label: String? = null,
+    /** Spawners in this place. */
+    val spawners: Int? = null,
+    /** How many can be alive at once here, summed across those spawners. */
+    val maxAlive: Int? = null,
+)
+
+/**
+ * One spawn point.
+ *
+ * **[minDelay] / [maxDelay] are SECONDS**, normalised by the server's parser.
+ * XmlSpawner writes them in minutes *except* when a delay doesn't divide into whole
+ * minutes, flagging that per record — so the raw file has `5` meaning five minutes on
+ * one spawner and five seconds on the next, both plausible. The API and this client
+ * carry seconds throughout.
+ */
+@Serializable
+data class AtlasSpawnerDto(
+    val id: Long? = null,
+    val facet: String? = null,
+    val name: String? = null,
+    val x: Int? = null,
+    val y: Int? = null,
+    val maxCount: Int? = null,
+    val minDelay: Int? = null,
+    val maxDelay: Int? = null,
+    val region: String? = null,
+    val landmark: String? = null,
+    /** The server's own "Despise, Felucca" style placement label. */
+    val label: String? = null,
+)
+
+/** A page of creature search results (`GET /public/atlas/creatures`). */
+@Serializable
+data class AtlasCreaturePageDto(
+    val creatures: List<AtlasCreatureDto> = emptyList(),
+    val total: Int = 0,
+    val limit: Int? = null,
+    val offset: Int? = null,
+)
+
+/** When the atlas was last derived from the shard's data files, and what it holds. */
+@Serializable
+data class AtlasMetaDto(
+    val importedAt: String? = null,
+    val generatedAt: String? = null,
+    val counts: Map<String, Int> = emptyMap(),
+    val facets: List<String> = emptyList(),
+)

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

@@ -15,13 +15,43 @@ import kotlinx.serialization.json.JsonObject
  * `*.update` frames on `/public/shard/stream` decode into these same DTOs.
  */
 
-/** A game actor (player/leader/governor) as embedded in board payloads. */
+/**
+ * Which shard surfaces this caller may reach (`GET /public/shard/features`), plus
+ * the audience rung they resolved to.
+ *
+ * Every shard-derived feature is admin-configurable — it can be switched off or
+ * raised to a higher rung — so the menu cannot be a static list (PLAN.md §5, M11).
+ * [level] is the SERVER's answer on the `anonymous → logged_in → player → staff →
+ * admin` ladder and is authoritative: don't re-derive a rung from the session role,
+ * since `player` means *a linked game account* and staff always satisfy it.
+ *
+ * The response reports only what the caller can see, so the list itself never
+ * discloses a feature they're gated out of.
+ */
+@Serializable
+data class ShardFeaturesDto(
+    val level: String? = null,
+    val features: List<String> = emptyList(),
+)
+
+/**
+ * A game actor (player/leader/governor) as embedded in board payloads. Per the wire
+ * spec (`docs/link/INTEGRATION.md` §1), in-game [serial]s are opaque hex-string keys
+ * (e.g. `"0x1A2B"`), never numbers.
+ *
+ * [acct] and [webId] are **locked to the admin rung** by the visibility framework
+ * (`docs/link/v3.md` §3.4 rule 1) — a game account name and a linked site-user id are
+ * not in-game-visible the way a character name is, so they are stripped from every
+ * response below `admin` and no admin setting can loosen that. The fields stay
+ * declared because an admin session does receive them; nothing below one should
+ * expect a value.
+ */
 @Serializable
 data class ActorDto(
-    val serial: Long? = null,
+    val serial: String? = null,
     val name: String? = null,
     val acct: String? = null,
-    val webId: Long? = null,
+    val webId: String? = null,
 ) {
     /** Best display label for this actor. */
     val label: String get() = name ?: acct ?: "Someone"
@@ -73,7 +103,7 @@ data class FeedEventDto(
  */
 @Serializable
 data class OnlineStaffDto(
-    val serial: Long? = null,
+    val serial: String? = null,
     val name: String? = null,
     val map: String? = null,
     val x: Int? = null,
@@ -87,7 +117,7 @@ data class OnlineStaffDto(
  */
 @Serializable
 data class HouseDto(
-    val serial: Long = 0,
+    val serial: String = "",
     val name: String? = null,
     val region: String? = null,
     val map: String? = null,
@@ -104,7 +134,7 @@ data class HouseDto(
  */
 @Serializable
 data class ChampDto(
-    val serial: Long = 0,
+    val serial: String = "",
     val category: String? = null,
     val type: String? = null,
     val name: String? = null,

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

@@ -10,10 +10,19 @@ 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.RecoveryCodesDto
+import com.runicgateway.app.data.api.dto.RecoveryGenerateRequest
+import com.runicgateway.app.data.api.dto.RecoveryStatusDto
 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.TrustDeviceRequest
+import com.runicgateway.app.data.api.dto.TrustedDeviceDto
+import com.runicgateway.app.data.api.dto.TrustedDeviceLimitDto
 import com.runicgateway.app.data.api.dto.UsernameResponse
+import kotlinx.coroutines.CancellationException
+import kotlinx.serialization.json.Json
+import java.io.IOException
 import javax.inject.Inject
 import javax.inject.Singleton
 
@@ -26,6 +35,7 @@ import javax.inject.Singleton
 @Singleton
 class AccountRepository @Inject constructor(
     private val api: MeApi,
+    private val json: Json,
 ) {
     suspend fun getAccount(): ApiResult<PlayerAccountDto> = safeApiCall { api.getAccount() }
 
@@ -48,4 +58,63 @@ class AccountRepository @Inject constructor(
 
     suspend fun unlinkIdentity(provider: String): ApiResult<Unit> =
         safeApiCall { api.unlinkIdentity(provider) }
+
+    // ── Trusted devices (TRUSTED_DEVICES_MFA.md) ───────────────────────────
+
+    suspend fun trustedDevices(): ApiResult<List<TrustedDeviceDto>> =
+        safeApiCall { api.trustedDevices() }
+
+    /** The distinct outcomes of trusting the current device — the cap is a first-class case. */
+    sealed interface TrustOutcome {
+        /** Trusted; [trustToken] is the opaque token to persist (native). */
+        data class Trusted(val trustToken: String?) : TrustOutcome
+
+        /** At the per-user cap — [devices] must be pruned before retrying. */
+        data class LimitReached(val devices: List<TrustedDeviceDto>) : TrustOutcome
+        data object NetworkError : TrustOutcome
+        data object ServerError : TrustOutcome
+    }
+
+    /**
+     * Trust the current device. Reads the raw response so the `409 { error, devices }`
+     * cap body survives (a thrown [retrofit2.HttpException] would discard it).
+     */
+    suspend fun trustThisDevice(deviceName: String? = null): TrustOutcome {
+        val response = try {
+            api.trustThisDevice(TrustDeviceRequest(deviceName))
+        } catch (e: CancellationException) {
+            throw e
+        } catch (_: IOException) {
+            return TrustOutcome.NetworkError
+        } catch (_: Exception) {
+            return TrustOutcome.ServerError
+        }
+        if (response.isSuccessful) {
+            return TrustOutcome.Trusted(response.body()?.trustToken)
+        }
+        if (response.code() == 409) {
+            val devices = runCatching {
+                val raw = response.errorBody()?.string()
+                if (raw.isNullOrBlank()) emptyList()
+                else json.decodeFromString<TrustedDeviceLimitDto>(raw).devices
+            }.getOrDefault(emptyList())
+            return TrustOutcome.LimitReached(devices)
+        }
+        return TrustOutcome.ServerError
+    }
+
+    suspend fun revokeTrustedDevice(id: Long): ApiResult<Boolean> =
+        safeApiCall { api.revokeTrustedDevice(id).revoked }
+
+    suspend fun revokeAllTrustedDevices(): ApiResult<Int> =
+        safeApiCall { api.revokeAllTrustedDevices().revoked }
+
+    // ── Recovery (backup) codes ────────────────────────────────────────────
+
+    suspend fun recoveryCodesStatus(): ApiResult<RecoveryStatusDto> =
+        safeApiCall { api.recoveryCodesStatus() }
+
+    /** Regenerate the single-use codes (password step-up). Returned once — never stored. */
+    suspend fun generateRecoveryCodes(currentPassword: String?): ApiResult<RecoveryCodesDto> =
+        safeApiCall { api.generateRecoveryCodes(RecoveryGenerateRequest(currentPassword)) }
 }

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

@@ -3,7 +3,9 @@
  */
 package com.runicgateway.app.data.repository
 
+import com.runicgateway.app.core.auth.DeviceNameProvider
 import com.runicgateway.app.core.auth.SessionManager
+import com.runicgateway.app.core.auth.TrustTokenStore
 import com.runicgateway.app.core.push.PushManager
 import com.runicgateway.app.data.api.AuthApi
 import com.runicgateway.app.data.api.SsoApi
@@ -12,6 +14,7 @@ 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 com.runicgateway.app.data.api.dto.TrustedDeviceDto
 import kotlinx.coroutines.CancellationException
 import kotlinx.coroutines.delay
 import kotlinx.serialization.json.Json
@@ -32,6 +35,8 @@ class AuthRepository @Inject constructor(
     private val ssoApi: SsoApi,
     private val sessionManager: SessionManager,
     private val pushManager: PushManager,
+    private val trustTokenStore: TrustTokenStore,
+    private val deviceNameProvider: DeviceNameProvider,
     private val json: Json,
 ) {
 
@@ -73,7 +78,15 @@ class AuthRepository @Inject constructor(
 
     /** Outcome of a login attempt (§4.1). */
     sealed interface LoginResult {
-        data object Success : LoginResult
+        /**
+         * Signed in. [trustLimitReached] is true when "trust this device" was asked
+         * for but the per-user cap blocked it (the login still succeeded, but no trust
+         * token was issued); [devices] then lists the trusted devices to manage.
+         */
+        data class Success(
+            val trustLimitReached: Boolean = false,
+            val devices: List<TrustedDeviceDto> = emptyList(),
+        ) : LoginResult
 
         /** The account has 2FA on — reveal the code field and resubmit with a code. */
         data object TotpRequired : LoginResult
@@ -89,9 +102,32 @@ class AuthRepository @Inject constructor(
         data object NetworkError : LoginResult
     }
 
-    suspend fun login(username: String, password: String, code: String? = null): LoginResult {
+    /**
+     * Native login (TRUSTED_DEVICES_MFA.md). A stored trust token bound to [username]
+     * rides the `X-Trust-Token` header so a trusted device skips the TOTP step. A
+     * second factor is either a [code] (TOTP) or a single-use [recoveryCode]. With
+     * [trustDevice], the server may return a fresh trust token to persist for next time.
+     */
+    suspend fun login(
+        username: String,
+        password: String,
+        code: String? = null,
+        recoveryCode: String? = null,
+        trustDevice: Boolean = false,
+    ): LoginResult {
+        val storedTrustToken = trustTokenStore.tokenFor(username)
         val response: Response<MobileTokenResponse> = try {
-            authApi.login(MobileLoginRequest(username = username, password = password, code = code))
+            authApi.login(
+                MobileLoginRequest(
+                    username = username,
+                    password = password,
+                    code = code,
+                    recoveryCode = recoveryCode,
+                    trustDevice = trustDevice.takeIf { it },
+                    device_name = if (trustDevice) deviceNameProvider.deviceName() else null,
+                ),
+                trustToken = storedTrustToken,
+            )
         } catch (e: CancellationException) {
             throw e
         } catch (_: IOException) {
@@ -100,8 +136,14 @@ class AuthRepository @Inject constructor(
 
         if (response.isSuccessful) {
             val body = response.body() ?: return LoginResult.ServerError
+            // Persist a freshly minted trust token (scoped to this account) so the next
+            // login skips the second factor — it deliberately outlives logout.
+            body.trustToken?.let { trustTokenStore.save(username, it) }
             sessionManager.onSignedIn(body.accessToken, body.refreshToken, body.user)
-            return LoginResult.Success
+            return LoginResult.Success(
+                trustLimitReached = body.trustLimitReached,
+                devices = body.devices,
+            )
         }
 
         return when (response.code()) {
@@ -111,6 +153,20 @@ class AuthRepository @Inject constructor(
         }
     }
 
+    /**
+     * Persist a trust token minted by the self-service "trust this device" action
+     * (Account → Trusted Devices), scoped to [username] exactly like the login path.
+     */
+    fun saveTrustToken(username: String, token: String) = trustTokenStore.save(username, token)
+
+    /**
+     * Drop the locally stored trust token so this device stops skipping the TOTP step
+     * (used after "untrust all" and on a Settings → Server switch). Server-side
+     * revocation makes any surviving token inert anyway — the next login just prompts
+     * for the code — so this is a client-side cleanliness step, never load-bearing.
+     */
+    fun clearTrustToken() = trustTokenStore.clear()
+
     /**
      * Revoke this session (or, with [allDevices], every session) and clear local
      * tokens (§4.3). Best-effort: the local session is torn down even if the

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

@@ -4,6 +4,7 @@
 package com.runicgateway.app.data.repository
 
 import com.runicgateway.app.core.auth.SessionManager
+import com.runicgateway.app.core.auth.TrustTokenStore
 import com.runicgateway.app.core.net.BaseUrlHolder
 import com.runicgateway.app.core.net.ServerUrl
 import com.runicgateway.app.core.prefs.ServerPreferences
@@ -26,6 +27,8 @@ class ConnectionRepository @Inject constructor(
     private val prefs: ServerPreferences,
     private val baseUrlHolder: BaseUrlHolder,
     private val sessionManager: SessionManager,
+    private val trustTokenStore: TrustTokenStore,
+    private val shardFeaturesRepository: ShardFeaturesRepository,
     private val pushManager: com.runicgateway.app.core.push.PushManager,
     private val config: com.runicgateway.app.core.AppConfig,
 ) {
@@ -106,6 +109,13 @@ class ConnectionRepository @Inject constructor(
         }
         pushManager.setNtfyUrl(null)
         sessionManager.onSignedOut()
+        // The trust token is bound to the old host — drop it so we don't replay it
+        // against a different shard (it survives a plain logout, but not a host switch).
+        trustTokenStore.clear()
+        // Shard visibility is the OLD host's answer. Sign-out alone would not clear it:
+        // a switch between two signed-out hosts changes no session, so nothing else
+        // invalidates the cache and the new shard would inherit the old one's menu.
+        shardFeaturesRepository.invalidate()
         prefs.clear()
         baseUrlHolder.set(null)
     }

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

@@ -0,0 +1,111 @@
+/*
+ * 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.PublicApi
+import kotlinx.coroutines.flow.MutableStateFlow
+import kotlinx.coroutines.flow.StateFlow
+import kotlinx.coroutines.flow.asStateFlow
+import kotlinx.coroutines.sync.Mutex
+import kotlinx.coroutines.sync.withLock
+import javax.inject.Inject
+import javax.inject.Singleton
+
+/**
+ * Which shard surfaces the current viewer may reach, from
+ * `GET /public/shard/features` (PLAN.md §5, §9 M11).
+ *
+ * Every shard-derived feature is admin-configurable — it can be switched off, or its
+ * audience raised above the caller's rung — so shard navigation can no longer be a
+ * static list gated on the session role alone. [level] is the server's own answer on
+ * the `anonymous → logged_in → player → staff → admin` ladder; the app does not
+ * re-derive it.
+ *
+ * **This is presentation only.** The gate is server-side: a disabled feature `404`s
+ * and an out-of-rung one `403`s whether or not the entry was rendered. That is why an
+ * unknown answer deliberately **fails open** — see [ShardFeatures] and [canSee].
+ */
+@Singleton
+class ShardFeaturesRepository @Inject constructor(
+    private val api: PublicApi,
+) {
+    private val _features = MutableStateFlow<ShardFeatures?>(null)
+
+    /** The current answer, or `null` while it is unknown (in flight, or the lookup failed). */
+    val features: StateFlow<ShardFeatures?> = _features.asStateFlow()
+
+    // Serializes concurrent refreshes: the shell refreshes on every session change,
+    // and two overlapping loads would race to publish.
+    private val mutex = Mutex()
+
+    /**
+     * Re-resolve the visible set. Called on every session change (sign-in, sign-out,
+     * a role revalidation that actually changed the user), because the answer is
+     * per-viewer.
+     *
+     * A failed lookup clears the cache rather than keeping a stale one: falling back
+     * to "show everything" is the safe direction here, since the server still gates
+     * every call.
+     */
+    suspend fun refresh() = mutex.withLock {
+        _features.value = when (val result = safeApiCall { api.getShardFeatures() }) {
+            is ApiResult.Ok -> ShardFeatures(
+                level = result.data.level,
+                visible = result.data.features.toSet(),
+            )
+            // Includes the 404 an older, pre-Protocol-3.0 website returns for this
+            // route — that site has no visibility framework, so "unknown" is exactly
+            // the right answer and the menu behaves as it did before M11.
+            else -> null
+        }
+    }
+
+    /**
+     * Drop the cached answer. Called on a Settings → Server switch: the features
+     * belong to the host that reported them, and a switch between two signed-out
+     * hosts changes no session, so nothing else would invalidate them.
+     */
+    fun invalidate() {
+        _features.value = null
+    }
+}
+
+/**
+ * The resolved visibility answer for one viewer: the rung the server placed them on
+ * and the shard features they may reach.
+ */
+data class ShardFeatures(
+    val level: String?,
+    val visible: Set<String>,
+)
+
+/**
+ * True when [feature] may be shown — **or when the answer isn't known yet**.
+ *
+ * The fail-open default is deliberate and matches the web client (`lib/useShardFeatures.js`):
+ * the server gates every call regardless, so the cost of guessing wrong is a link that
+ * briefly `403`s, while the cost of guessing the other way is a navigation drawer that
+ * flickers its entries in on every cold start.
+ */
+fun canSee(features: ShardFeatures?, feature: String): Boolean =
+    features == null || feature in features.visible
+
+/** Feature names as the website's `shardVisibility.js` `FEATURES` map spells them. */
+object ShardFeature {
+    const val STATUS = "status"
+    const val ACTIVITY = "activity"
+    const val CHAMPS = "champs"
+    const val GUILDS = "guilds"
+    const val GOVERNORS = "governors"
+    const val HOUSES = "houses"
+    const val PRESENCE = "presence"
+
+    // Added by Protocol 3.0.
+    const val RULESET = "ruleset"
+    const val ATLAS = "atlas"
+    const val LEADERBOARDS = "leaderboards"
+    const val MARKET = "market"
+}

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

@@ -3,11 +3,13 @@
  */
 package com.runicgateway.app.data.repository
 
-import com.runicgateway.app.core.net.ShardStreamClient
+import com.runicgateway.app.core.net.ShardStream
 import com.runicgateway.app.core.net.ShardStreamEvent
 import com.runicgateway.app.core.result.ApiResult
 import com.runicgateway.app.core.result.safeApiCall
 import com.runicgateway.app.data.api.PublicApi
+import com.runicgateway.app.data.api.dto.AtlasCreatureDto
+import com.runicgateway.app.data.api.dto.AtlasCreaturePageDto
 import com.runicgateway.app.data.api.dto.ChampDto
 import com.runicgateway.app.data.api.dto.EconomySampleDto
 import com.runicgateway.app.data.api.dto.FeedEventDto
@@ -15,8 +17,13 @@ import com.runicgateway.app.data.api.dto.GovernorDto
 import com.runicgateway.app.data.api.dto.GovernorTermDto
 import com.runicgateway.app.data.api.dto.GuildDto
 import com.runicgateway.app.data.api.dto.HouseDto
+import com.runicgateway.app.data.api.dto.MarketMetaDto
+import com.runicgateway.app.data.api.dto.MarketPageDto
+import com.runicgateway.app.data.api.dto.MarketVendorDto
 import com.runicgateway.app.data.api.dto.OnlineStaffDto
+import com.runicgateway.app.data.api.dto.PointsBoardDto
 import com.runicgateway.app.data.api.dto.PresenceDto
+import com.runicgateway.app.data.api.dto.RulesetDto
 import com.runicgateway.app.data.api.dto.ShardStatusDto
 import kotlinx.coroutines.flow.Flow
 import kotlinx.serialization.KSerializer
@@ -35,7 +42,7 @@ import javax.inject.Singleton
 @Singleton
 class ShardRepository @Inject constructor(
     private val api: PublicApi,
-    private val stream: ShardStreamClient,
+    private val stream: ShardStream,
     private val json: Json,
 ) {
     // ── Snapshots ────────────────────────────────────────────────────────
@@ -62,6 +69,59 @@ class ShardRepository @Inject constructor(
 
     suspend fun houses(): ApiResult<List<HouseDto>> = safeApiCall { api.getShardHouses() }
 
+    // ── Protocol 3.0 shard content (§9 M11) ──────────────────────────────
+    //
+    // All four sit behind `requireFeature`, so a 404/403 here is "this shard doesn't
+    // publish it" rather than a fault — see `toShardUiState()`.
+
+    /** The shard ruleset, or `Ok(null)` when the shard has never published one. */
+    suspend fun ruleset(): ApiResult<RulesetDto?> = safeApiCall { api.getShardRuleset() }
+
+    suspend fun pointsBoards(): ApiResult<List<PointsBoardDto>> = safeApiCall { api.getShardPoints() }
+
+    suspend fun pointsBoard(system: String): ApiResult<PointsBoardDto> =
+        safeApiCall { api.getShardPointsBoard(system) }
+
+    suspend fun market(
+        query: String? = null,
+        map: String? = null,
+        region: String? = null,
+        sort: String = SORT_PRICE_ASC,
+        limit: Int = MARKET_PAGE,
+        offset: Int = 0,
+    ): ApiResult<MarketPageDto> = safeApiCall {
+        api.getShardMarket(
+            query = query?.takeIf { it.isNotBlank() },
+            map = map?.takeIf { it.isNotBlank() },
+            region = region?.takeIf { it.isNotBlank() },
+            sort = sort,
+            limit = limit,
+            offset = offset,
+        )
+    }
+
+    suspend fun marketMeta(): ApiResult<MarketMetaDto> = safeApiCall { api.getShardMarketMeta() }
+
+    suspend fun marketVendor(serial: String): ApiResult<MarketVendorDto> =
+        safeApiCall { api.getShardMarketVendor(serial) }
+
+    suspend fun atlasCreatures(
+        query: String? = null,
+        facet: String? = null,
+        limit: Int = ATLAS_PAGE,
+        offset: Int = 0,
+    ): ApiResult<AtlasCreaturePageDto> = safeApiCall {
+        api.getAtlasCreatures(
+            query = query?.takeIf { it.isNotBlank() },
+            facet = facet?.takeIf { it.isNotBlank() },
+            limit = limit,
+            offset = offset,
+        )
+    }
+
+    suspend fun atlasCreature(slug: String): ApiResult<AtlasCreatureDto> =
+        safeApiCall { api.getAtlasCreature(slug) }
+
     // ── Live stream ──────────────────────────────────────────────────────
     /** The shared public SSE feed (safe kinds only), reconnecting with backoff (§7). */
     fun liveEvents(): Flow<ShardStreamEvent> = stream.events()
@@ -73,9 +133,27 @@ class ShardRepository @Inject constructor(
     fun governorFrame(obj: JsonObject): GovernorDto? = decode(obj, GovernorDto.serializer())
     fun presenceFrame(obj: JsonObject): PresenceDto? = decode(obj, PresenceDto.serializer())
 
+    // Protocol 3.0 frames. `world.ruleset` and `points.board` ride the public stream by
+    // default; `vendor.listing` does NOT — the market feature ships with its SSE fan-out
+    // disabled (a live firehose of vendor inventories would be the site's biggest
+    // bandwidth consumer), so the market screen is a plain paginated read and must never
+    // wait on a frame.
+    fun rulesetFrame(obj: JsonObject): RulesetDto? = decode(obj, RulesetDto.serializer())
+    fun pointsBoardFrame(obj: JsonObject): PointsBoardDto? = decode(obj, PointsBoardDto.serializer())
+
     private fun <T> decode(obj: JsonObject, serializer: KSerializer<T>): T? = try {
         json.decodeFromJsonElement(serializer, obj)
     } catch (_: Exception) {
         null
     }
+
+    companion object {
+        const val SORT_PRICE_ASC = "price_asc"
+        const val SORT_PRICE_DESC = "price_desc"
+        const val SORT_RECENT = "recent"
+
+        /** The server caps `limit` at 100; stay well under it on a phone. */
+        const val MARKET_PAGE = 50
+        const val ATLAS_PAGE = 50
+    }
 }

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

@@ -9,6 +9,8 @@ import com.runicgateway.app.BuildConfig
 import com.runicgateway.app.core.net.AuthInterceptor
 import com.runicgateway.app.core.net.BaseUrlHolder
 import com.runicgateway.app.core.net.HostSelectionInterceptor
+import com.runicgateway.app.core.net.ShardStream
+import com.runicgateway.app.core.net.ShardStreamClient
 import com.runicgateway.app.core.net.TokenAuthenticator
 import com.runicgateway.app.core.net.UserAgentInterceptor
 import com.runicgateway.app.data.api.AuthApi
@@ -94,6 +96,12 @@ object NetworkModule {
     @Singleton
     fun providePublicApi(retrofit: Retrofit): PublicApi = retrofit.create(PublicApi::class.java)
 
+    /** Expose the live SSE feed as the [ShardStream] capability so repositories depend
+     *  on the interface (unit-testable against a fake), not the OkHttp-backed client. */
+    @Provides
+    @Singleton
+    fun provideShardStream(client: ShardStreamClient): ShardStream = client
+
     @Provides
     @Singleton
     fun provideAuthApi(retrofit: Retrofit): AuthApi = retrofit.create(AuthApi::class.java)

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

@@ -3,8 +3,12 @@
  */
 package com.runicgateway.app.di
 
+import com.runicgateway.app.core.auth.BuildDeviceNameProvider
+import com.runicgateway.app.core.auth.DeviceNameProvider
 import com.runicgateway.app.core.auth.EncryptedTokenStore
+import com.runicgateway.app.core.auth.EncryptedTrustTokenStore
 import com.runicgateway.app.core.auth.TokenStore
+import com.runicgateway.app.core.auth.TrustTokenStore
 import com.runicgateway.app.core.auth.sso.EncryptedPendingSsoStore
 import com.runicgateway.app.core.auth.sso.PendingSsoStore
 import dagger.Binds
@@ -25,4 +29,13 @@ abstract class StorageModule {
     @Binds
     @Singleton
     abstract fun bindPendingSsoStore(impl: EncryptedPendingSsoStore): PendingSsoStore
+
+    /** The trusted-device token store — its own encrypted file, outlives session teardown. */
+    @Binds
+    @Singleton
+    abstract fun bindTrustTokenStore(impl: EncryptedTrustTokenStore): TrustTokenStore
+
+    @Binds
+    @Singleton
+    abstract fun bindDeviceNameProvider(impl: BuildDeviceNameProvider): DeviceNameProvider
 }

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

@@ -51,6 +51,8 @@ import com.runicgateway.app.core.auth.Session
 import com.runicgateway.app.data.api.dto.BrandDto
 import com.runicgateway.app.ui.auth.AccountScreen
 import com.runicgateway.app.ui.auth.LoginScreen
+import com.runicgateway.app.ui.auth.RecoveryCodesScreen
+import com.runicgateway.app.ui.auth.TrustedDevicesScreen
 import com.runicgateway.app.ui.auth.roleLabelRes
 import com.runicgateway.app.ui.contact.ContactScreen
 import com.runicgateway.app.ui.home.HomeScreen
@@ -70,10 +72,16 @@ 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.AtlasCreatureScreen
+import com.runicgateway.app.ui.shard.AtlasScreen
 import com.runicgateway.app.ui.shard.ChampsScreen
 import com.runicgateway.app.ui.shard.GovernorsScreen
 import com.runicgateway.app.ui.shard.GuildsScreen
 import com.runicgateway.app.ui.shard.HousesScreen
+import com.runicgateway.app.ui.shard.LeaderboardsScreen
+import com.runicgateway.app.ui.shard.MarketScreen
+import com.runicgateway.app.ui.shard.MarketVendorScreen
+import com.runicgateway.app.ui.shard.RulesScreen
 import com.runicgateway.app.ui.shard.ShardBoard
 import com.runicgateway.app.ui.shard.ShardScreen
 import com.runicgateway.app.ui.wiki.WikiPageScreen
@@ -83,6 +91,9 @@ 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,
+    // Protocol 3.0 content screens are drawer destinations, so the drawer gesture works
+    // on them too (M11).
+    Routes.SHARD_RULES, Routes.SHARD_LEADERBOARDS, Routes.SHARD_MARKET, Routes.ATLAS,
     Routes.NOTIFICATIONS,
     Routes.PLAYER_CHARACTERS, Routes.PLAYER_VENDORS, Routes.PLAYER_HOUSES,
     Routes.ADMIN_DASHBOARD, Routes.ADMIN_CONTENT, Routes.ADMIN_MODERATION, Routes.ADMIN_SUPPORT,
@@ -110,6 +121,8 @@ fun RunicApp(
     val scope = rememberCoroutineScope()
 
     val session by sessionViewModel.session.collectAsStateWithLifecycle()
+    // What this shard publishes, independently of who the caller is (§5, M11).
+    val shardFeatures by sessionViewModel.shardFeatures.collectAsStateWithLifecycle()
 
     // Re-validate the cached role each time the app returns to the foreground (§4.3).
     LifecycleResumeEffect(Unit) {
@@ -130,7 +143,7 @@ fun RunicApp(
     val backStackEntry by navController.currentBackStackEntryAsState()
     val currentRoute = backStackEntry?.destination?.route
     val isTopLevel = currentRoute in TOP_LEVEL_ROUTES
-    val entries = visibleEntries(APP_MENU, session)
+    val entries = visibleEntries(APP_MENU, session, shardFeatures)
 
     ModalNavigationDrawer(
         drawerState = drawerState,
@@ -301,6 +314,30 @@ private fun RunicNavHost(
         composable(Routes.SHARD_GUILDS) { GuildsScreen() }
         composable(Routes.SHARD_GOVERNORS) { GovernorsScreen() }
         composable(Routes.SHARD_HOUSES) { HousesScreen() }
+
+        // Protocol 3.0 shard content (M11). Each screen self-reports "not published
+        // here" from its own 404/403, so a deep link to a gated feature still lands on
+        // an honest answer even though the menu hides the entry.
+        composable(Routes.SHARD_RULES) { RulesScreen() }
+        composable(Routes.SHARD_LEADERBOARDS) { LeaderboardsScreen(brand = brand) }
+        composable(Routes.SHARD_MARKET) {
+            MarketScreen(onOpenVendor = { serial -> navController.navigate(Routes.marketVendor(serial)) })
+        }
+        composable(
+            route = Routes.SHARD_MARKET_VENDOR,
+            arguments = listOf(navArgument(Routes.Args.SERIAL) { type = NavType.StringType }),
+        ) { entry ->
+            MarketVendorScreen(serial = entry.arguments?.getString(Routes.Args.SERIAL).orEmpty())
+        }
+        composable(Routes.ATLAS) {
+            AtlasScreen(onOpenCreature = { slug -> navController.navigate(Routes.atlasCreature(slug)) })
+        }
+        composable(
+            route = Routes.ATLAS_CREATURE,
+            arguments = listOf(navArgument(Routes.Args.SLUG) { type = NavType.StringType }),
+        ) { entry ->
+            AtlasCreatureScreen(slug = entry.arguments?.getString(Routes.Args.SLUG).orEmpty())
+        }
         composable(Routes.WIKI) {
             WikiScreen(onOpenPage = { slug -> navController.navigate(Routes.wikiPage(slug)) })
         }
@@ -339,12 +376,27 @@ private fun RunicNavHost(
                     roleLabel = stringResource(roleLabelRes(s.user.role)),
                     onSignOut = onSignOut,
                     onSignOutEverywhere = onSignOutEverywhere,
+                    onOpenTrustedDevices = { navController.navigate(Routes.ACCOUNT_TRUSTED_DEVICES) },
+                    onOpenRecoveryCodes = { navController.navigate(Routes.ACCOUNT_RECOVERY_CODES) },
                 )
                 Session.SignedOut -> LaunchedEffect(Unit) {
                     navController.navigateTopLevel(Routes.HOME)
                 }
             }
         }
+        composable(Routes.ACCOUNT_TRUSTED_DEVICES) {
+            // Signed-in only; a drop (sign-out/demotion) sends the user home (§4.3).
+            when (session) {
+                is Session.SignedIn -> TrustedDevicesScreen()
+                Session.SignedOut -> LaunchedEffect(Unit) { navController.navigateTopLevel(Routes.HOME) }
+            }
+        }
+        composable(Routes.ACCOUNT_RECOVERY_CODES) {
+            when (session) {
+                is Session.SignedIn -> RecoveryCodesScreen()
+                Session.SignedOut -> LaunchedEffect(Unit) { navController.navigateTopLevel(Routes.HOME) }
+            }
+        }
         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).

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

@@ -34,6 +34,13 @@ enum class ErrorKind {
     /** Shard/sidecar down (503) — shard reads only; render as offline (§6.3). */
     SHARD_OFFLINE,
 
+    /**
+     * This shard doesn't publish the surface, or doesn't publish it to this viewer
+     * (M11). Distinct from [NOT_FOUND] and [SHARD_OFFLINE]: the site is up, the shard
+     * may well be up, and retrying changes nothing — an admin decides this.
+     */
+    FEATURE_UNAVAILABLE,
+
     /** Any other non-2xx server response. */
     SERVER,
 }
@@ -52,3 +59,27 @@ fun <T> ApiResult<T>.toUiState(): UiState<T> = when (this) {
         httpStatus = status,
     )
 }
+
+/**
+ * [toUiState] for a **shard-derived** read, where `404` carries a second meaning.
+ *
+ * The website's `requireFeature` gate answers `404` when a feature is switched off —
+ * deliberately, so the response doesn't disclose that the surface exists — and `403`
+ * when it's on but the caller is below its audience rung (`docs/link/v3.md` §3.6).
+ * On these routes a `404` therefore almost never means "no such thing"; it means this
+ * shard doesn't publish it. Rendering "couldn't be found" with a retry button would
+ * invite the user to retry something an admin controls.
+ *
+ * Kept as a separate mapper rather than folded into [toUiState] because both statuses
+ * mean something else off the shard surface: `404` is a genuinely missing item (a
+ * deleted post, an unknown wiki slug) and `403` is an ownership or role refusal on a
+ * player or admin route, which is not an admin's visibility setting.
+ */
+fun <T> ApiResult<T>.toShardUiState(): UiState<T> = when (this) {
+    is ApiResult.HttpError -> if (status == 403 || status == 404) {
+        UiState.Error(ErrorKind.FEATURE_UNAVAILABLE, httpStatus = status)
+    } else {
+        toUiState()
+    }
+    else -> toUiState()
+}

app/src/main/java/com/runicgateway/app/ui/admin/AdminContentScreen.kt

@@ -30,7 +30,6 @@ import androidx.compose.runtime.Composable
 import androidx.compose.runtime.getValue
 import androidx.compose.runtime.mutableIntStateOf
 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

app/src/main/java/com/runicgateway/app/ui/admin/AdminSupportScreen.kt

@@ -84,7 +84,6 @@ fun AdminSupportScreen(
 
     replyTo?.let { page ->
         RespondDialog(
-            page = page,
             onDismiss = { replyTo = null },
             onSend = { message, close ->
                 viewModel.respond(page.pageId, message, close)
@@ -122,7 +121,6 @@ private fun SupportPageCard(
 
 @Composable
 private fun RespondDialog(
-    page: SupportPageDto,
     onDismiss: () -> Unit,
     onSend: (message: String, close: Boolean) -> Unit,
 ) {

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

@@ -65,6 +65,8 @@ fun AccountScreen(
     roleLabel: String,
     onSignOut: () -> Unit,
     onSignOutEverywhere: () -> Unit,
+    onOpenTrustedDevices: () -> Unit,
+    onOpenRecoveryCodes: () -> Unit,
     modifier: Modifier = Modifier,
     viewModel: AccountViewModel = hiltViewModel(),
 ) {
@@ -78,10 +80,15 @@ fun AccountScreen(
     ) {
         IdentityCard(username = username, roleLabel = roleLabel)
 
+        // One-time recovery codes surfaced right after enabling 2FA — save them now.
+        state.recoveryCodesOnce?.let { codes ->
+            RecoveryCodesShowOnceCard(codes, onDismiss = viewModel::dismissRecoveryCodes)
+        }
+
         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)
+            is UiState.Success -> AccountSections(account.data, state, viewModel, onOpenTrustedDevices, onOpenRecoveryCodes)
         }
 
         HorizontalDivider(Modifier.padding(vertical = 20.dp))
@@ -117,13 +124,34 @@ private fun AccountSections(
     account: PlayerAccountDto,
     state: AccountViewModel.State,
     viewModel: AccountViewModel,
+    onOpenTrustedDevices: () -> Unit,
+    onOpenRecoveryCodes: () -> Unit,
 ) {
     UsernameSection(account, state, viewModel)
     PasswordSection(account, state, viewModel)
     TwoFactorSection(account, state, viewModel)
+    SecuritySection(onOpenTrustedDevices, onOpenRecoveryCodes)
     IdentitiesSection(state, viewModel)
 }
 
+/**
+ * Links to the dedicated trusted-device and recovery-code screens
+ * (TRUSTED_DEVICES_MFA.md). Kept simple — the management UX lives on those screens.
+ */
+@Composable
+private fun SecuritySection(onOpenTrustedDevices: () -> Unit, onOpenRecoveryCodes: () -> Unit) {
+    SectionCard(R.string.account_security_title) {
+        OutlinedButton(
+            onClick = onOpenTrustedDevices,
+            modifier = Modifier.fillMaxWidth().padding(top = 12.dp),
+        ) { Text(stringResource(R.string.account_security_trusted_devices)) }
+        OutlinedButton(
+            onClick = onOpenRecoveryCodes,
+            modifier = Modifier.fillMaxWidth().padding(top = 8.dp),
+        ) { Text(stringResource(R.string.account_security_recovery_codes)) }
+    }
+}
+
 @Composable
 private fun SectionCard(@StringRes titleRes: Int, content: @Composable () -> Unit) {
     Card(Modifier.fillMaxWidth().padding(top = 12.dp)) {

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

@@ -49,6 +49,8 @@ class AccountViewModel @Inject constructor(
         val busy: Boolean = false,
         /** The pending TOTP enrollment (QR shown) between setup and enable. */
         val totpSetup: TotpSetupDto? = null,
+        /** The single-use recovery codes returned once when 2FA was just enabled. */
+        val recoveryCodesOnce: List<String>? = null,
         val feedback: Feedback? = null,
     )
 
@@ -122,9 +124,12 @@ class AccountViewModel @Inject constructor(
         if (_state.value.busy) return
         _state.update { it.copy(busy = true, feedback = null) }
         viewModelScope.launch {
-            when (accountRepository.totpEnable(code.trim())) {
+            when (val result = accountRepository.totpEnable(code.trim())) {
                 is ApiResult.Ok -> {
-                    _state.update { it.copy(totpSetup = null) }
+                    // 2FA enable returns the fresh recovery-code batch once — surface it.
+                    _state.update {
+                        it.copy(totpSetup = null, recoveryCodesOnce = result.data.recoveryCodes?.takeIf(List<String>::isNotEmpty))
+                    }
                     finish(Section.TOTP, true, R.string.account_totp_enabled)
                     reloadAccount()
                 }
@@ -134,6 +139,9 @@ class AccountViewModel @Inject constructor(
         }
     }
 
+    /** Dismiss the one-time recovery-code batch shown after enabling 2FA. */
+    fun dismissRecoveryCodes() = _state.update { it.copy(recoveryCodesOnce = null) }
+
     fun disableTotp(code: String) {
         if (_state.value.busy) return
         _state.update { it.copy(busy = true, feedback = null) }

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

@@ -5,6 +5,7 @@ package com.runicgateway.app.ui.auth
 
 import androidx.compose.foundation.layout.Arrangement
 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
@@ -16,6 +17,7 @@ import androidx.compose.foundation.text.KeyboardActions
 import androidx.compose.foundation.text.KeyboardOptions
 import androidx.compose.foundation.verticalScroll
 import androidx.compose.material3.Button
+import androidx.compose.material3.Checkbox
 import androidx.compose.material3.CircularProgressIndicator
 import androidx.compose.material3.ExperimentalMaterial3Api
 import androidx.compose.material3.MaterialTheme
@@ -123,22 +125,73 @@ fun LoginScreen(
         )
 
         if (state.totpRequired) {
-            OutlinedTextField(
-                value = state.code,
-                onValueChange = viewModel::onCodeChange,
-                singleLine = true,
+            if (state.useRecoveryCode) {
+                OutlinedTextField(
+                    value = state.recoveryCode,
+                    onValueChange = viewModel::onRecoveryCodeChange,
+                    singleLine = true,
+                    enabled = !state.submitting,
+                    label = { Text(stringResource(R.string.login_recovery_code)) },
+                    supportingText = { Text(stringResource(R.string.login_recovery_hint)) },
+                    keyboardOptions = KeyboardOptions(
+                        keyboardType = KeyboardType.Password,
+                        imeAction = ImeAction.Go,
+                    ),
+                    keyboardActions = KeyboardActions(onGo = { viewModel.submit() }),
+                    modifier = Modifier
+                        .fillMaxWidth()
+                        .padding(top = 12.dp),
+                )
+            } else {
+                OutlinedTextField(
+                    value = state.code,
+                    onValueChange = viewModel::onCodeChange,
+                    singleLine = true,
+                    enabled = !state.submitting,
+                    label = { Text(stringResource(R.string.login_totp_code)) },
+                    supportingText = { Text(stringResource(R.string.login_totp_hint)) },
+                    keyboardOptions = KeyboardOptions(
+                        keyboardType = KeyboardType.NumberPassword,
+                        imeAction = ImeAction.Go,
+                    ),
+                    keyboardActions = KeyboardActions(onGo = { viewModel.submit() }),
+                    modifier = Modifier
+                        .fillMaxWidth()
+                        .padding(top = 12.dp),
+                )
+            }
+
+            // Toggle between authenticator code and a single-use recovery code.
+            TextButton(
+                onClick = { viewModel.onUseRecoveryCodeChange(!state.useRecoveryCode) },
                 enabled = !state.submitting,
-                label = { Text(stringResource(R.string.login_totp_code)) },
-                supportingText = { Text(stringResource(R.string.login_totp_hint)) },
-                keyboardOptions = KeyboardOptions(
-                    keyboardType = KeyboardType.NumberPassword,
-                    imeAction = ImeAction.Go,
-                ),
-                keyboardActions = KeyboardActions(onGo = { viewModel.submit() }),
+                modifier = Modifier.align(Alignment.Start),
+            ) {
+                Text(
+                    stringResource(
+                        if (state.useRecoveryCode) R.string.login_use_totp_instead
+                        else R.string.login_use_recovery_instead,
+                    ),
+                )
+            }
+
+            // "Trust this device" → skip the 2FA step on future logins here.
+            Row(
+                verticalAlignment = Alignment.CenterVertically,
                 modifier = Modifier
                     .fillMaxWidth()
-                    .padding(top = 12.dp),
-            )
+                    .padding(top = 4.dp),
+            ) {
+                Checkbox(
+                    checked = state.trustDevice,
+                    onCheckedChange = viewModel::onTrustDeviceChange,
+                    enabled = !state.submitting,
+                )
+                Text(
+                    text = stringResource(R.string.login_trust_device),
+                    style = MaterialTheme.typography.bodyMedium,
+                )
+            }
         }
 
         state.error?.let { err ->

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

@@ -39,8 +39,14 @@ class LoginViewModel @Inject constructor(
         val username: String = "",
         val password: String = "",
         val code: String = "",
+        /** A single-use recovery code, entered instead of [code] when [useRecoveryCode]. */
+        val recoveryCode: String = "",
         /** True once the account is known to have 2FA on — reveal the code field. */
         val totpRequired: Boolean = false,
+        /** "Enter a recovery code instead" — swap the TOTP field for the recovery field. */
+        val useRecoveryCode: Boolean = false,
+        /** "Trust this device" — skip the 2FA step on future logins (TRUSTED_DEVICES_MFA.md). */
+        val trustDevice: Boolean = false,
         val submitting: Boolean = false,
         val error: LoginError? = null,
         val signedIn: Boolean = false,
@@ -83,6 +89,16 @@ class LoginViewModel @Inject constructor(
     fun onCodeChange(value: String) =
         _state.update { it.copy(code = value.filter(Char::isDigit).take(8), error = null) }
 
+    /** Recovery codes are alphanumeric; keep it permissive, just trim length + noise. */
+    fun onRecoveryCodeChange(value: String) =
+        _state.update { it.copy(recoveryCode = value.filterNot(Char::isWhitespace).take(32), error = null) }
+
+    fun onTrustDeviceChange(value: Boolean) = _state.update { it.copy(trustDevice = value) }
+
+    /** Toggle between the TOTP field and the recovery-code field on the 2FA step. */
+    fun onUseRecoveryCodeChange(value: Boolean) =
+        _state.update { it.copy(useRecoveryCode = value, error = null) }
+
     val registerUrl: String? get() = websiteUrls.register()
     val forgotPasswordUrl: String? get() = websiteUrls.forgotPassword()
 
@@ -137,45 +153,68 @@ class LoginViewModel @Inject constructor(
     fun submit() {
         val s = _state.value
         if (s.submitting) return
-        if (s.username.isBlank() || s.password.isBlank()) {
-            _state.update { it.copy(error = LoginError.INVALID_CREDENTIALS) }
-            return
-        }
-        // If 2FA is being requested, a code must accompany the resubmit.
-        if (s.totpRequired && s.code.isBlank()) {
-            _state.update { it.copy(error = LoginError.BAD_CODE) }
+        val validationError = validateForSubmit(s)
+        if (validationError != null) {
+            _state.update { it.copy(error = validationError) }
             return
         }
 
         _state.update { it.copy(submitting = true, error = null) }
         viewModelScope.launch {
-            val code = s.code.trim().takeIf { it.isNotBlank() }
-            when (authRepository.login(s.username.trim(), s.password, code)) {
-                LoginResult.Success ->
-                    _state.update { it.copy(submitting = false, signedIn = true) }
-
-                LoginResult.TotpRequired ->
-                    // Reveal the code field; a wrong code re-lands here as BAD_CODE.
-                    _state.update {
-                        it.copy(
-                            submitting = false,
-                            totpRequired = true,
-                            error = if (it.code.isNotBlank()) LoginError.BAD_CODE else null,
-                        )
-                    }
-
-                LoginResult.InvalidCredentials ->
-                    _state.update { it.copy(submitting = false, error = LoginError.INVALID_CREDENTIALS) }
-
-                LoginResult.RateLimited ->
-                    _state.update { it.copy(submitting = false, error = LoginError.RATE_LIMITED) }
-
-                LoginResult.ServerError ->
-                    _state.update { it.copy(submitting = false, error = LoginError.SERVER) }
-
-                LoginResult.NetworkError ->
-                    _state.update { it.copy(submitting = false, error = LoginError.NETWORK) }
-            }
+            // Only one second factor is sent; the recovery toggle picks which.
+            val code = s.code.trim().takeIf { it.isNotBlank() && !s.useRecoveryCode }
+            val recoveryCode = s.recoveryCode.trim().takeIf { it.isNotBlank() && s.useRecoveryCode }
+            val result = authRepository.login(
+                username = s.username.trim(),
+                password = s.password,
+                code = code,
+                recoveryCode = recoveryCode,
+                trustDevice = s.trustDevice,
+            )
+            applyLoginResult(result)
         }
     }
+
+    /** Pre-flight form checks for [submit]; returns the error to surface, or null if ready to send. */
+    private fun validateForSubmit(s: UiState): LoginError? {
+        if (s.username.isBlank() || s.password.isBlank()) return LoginError.INVALID_CREDENTIALS
+        // If 2FA is being requested, the chosen second factor must accompany the resubmit.
+        if (s.totpRequired) {
+            val factor = if (s.useRecoveryCode) s.recoveryCode else s.code
+            if (factor.isBlank()) return LoginError.BAD_CODE
+        }
+        return null
+    }
+
+    /** Folds a [LoginResult] back into the UI state (clears [UiState.submitting] on every path). */
+    private fun applyLoginResult(result: LoginResult) = when (result) {
+        is LoginResult.Success ->
+            // The trusted-device cap (result.trustLimitReached) is an edge case:
+            // login succeeded but the device wasn't remembered. It's surfaced +
+            // managed on the Trusted Devices screen rather than blocking sign-in.
+            _state.update { it.copy(submitting = false, signedIn = true) }
+
+        LoginResult.TotpRequired ->
+            // Reveal the 2FA fields; a wrong code/recovery code re-lands here as BAD_CODE.
+            _state.update {
+                val hadFactor = if (it.useRecoveryCode) it.recoveryCode.isNotBlank() else it.code.isNotBlank()
+                it.copy(
+                    submitting = false,
+                    totpRequired = true,
+                    error = if (hadFactor) LoginError.BAD_CODE else null,
+                )
+            }
+
+        LoginResult.InvalidCredentials ->
+            _state.update { it.copy(submitting = false, error = LoginError.INVALID_CREDENTIALS) }
+
+        LoginResult.RateLimited ->
+            _state.update { it.copy(submitting = false, error = LoginError.RATE_LIMITED) }
+
+        LoginResult.ServerError ->
+            _state.update { it.copy(submitting = false, error = LoginError.SERVER) }
+
+        LoginResult.NetworkError ->
+            _state.update { it.copy(submitting = false, error = LoginError.NETWORK) }
+    }
 }

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

@@ -0,0 +1,153 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.ui.auth
+
+import android.content.Intent
+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.text.KeyboardOptions
+import androidx.compose.foundation.verticalScroll
+import androidx.compose.material3.Button
+import androidx.compose.material3.Card
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.OutlinedButton
+import androidx.compose.material3.OutlinedTextField
+import androidx.compose.material3.Text
+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.Modifier
+import androidx.compose.ui.platform.LocalClipboardManager
+import androidx.compose.ui.platform.LocalContext
+import androidx.compose.ui.res.stringResource
+import androidx.compose.ui.text.AnnotatedString
+import androidx.compose.ui.text.font.FontFamily
+import androidx.compose.ui.text.input.KeyboardType
+import androidx.compose.ui.text.input.PasswordVisualTransformation
+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.ui.UiState
+
+/**
+ * Account → Recovery Codes (TRUSTED_DEVICES_MFA.md): shows the remaining count and a
+ * password-stepped regenerate that reveals a fresh single-use batch **once**. The
+ * codes are shown only in memory — copy or share them before leaving; they are never
+ * stored on the device.
+ */
+@Composable
+fun RecoveryCodesScreen(
+    modifier: Modifier = Modifier,
+    viewModel: RecoveryCodesViewModel = hiltViewModel(),
+) {
+    val state by viewModel.state.collectAsStateWithLifecycle()
+    var currentPassword by rememberSaveable { mutableStateOf("") }
+
+    Column(
+        modifier = modifier
+            .fillMaxSize()
+            .verticalScroll(rememberScrollState())
+            .padding(16.dp),
+    ) {
+        Text(stringResource(R.string.recovery_codes_title), style = MaterialTheme.typography.titleLarge)
+        Text(
+            stringResource(R.string.recovery_codes_subtitle),
+            style = MaterialTheme.typography.bodyMedium,
+            color = MaterialTheme.colorScheme.onSurfaceVariant,
+            modifier = Modifier.padding(top = 4.dp),
+        )
+
+        val remainingText = when (val r = state.remaining) {
+            is UiState.Success -> stringResource(R.string.recovery_codes_remaining, r.data)
+            is UiState.Error -> stringResource(R.string.recovery_codes_remaining_unknown)
+            UiState.Loading -> stringResource(R.string.recovery_codes_remaining_loading)
+        }
+        Text(remainingText, style = MaterialTheme.typography.bodyLarge, modifier = Modifier.padding(top = 16.dp))
+
+        state.freshCodes?.let { codes ->
+            RecoveryCodesShowOnceCard(codes, onDismiss = { viewModel.dismissFreshCodes(); currentPassword = "" })
+        }
+
+        OutlinedTextField(
+            value = currentPassword,
+            onValueChange = { currentPassword = it },
+            singleLine = true,
+            enabled = !state.busy,
+            label = { Text(stringResource(R.string.account_password_current)) },
+            supportingText = { Text(stringResource(R.string.recovery_codes_password_hint)) },
+            visualTransformation = PasswordVisualTransformation(),
+            keyboardOptions = KeyboardOptions(keyboardType = KeyboardType.Password),
+            modifier = Modifier.fillMaxWidth().padding(top = 20.dp),
+        )
+
+        state.error?.let { err ->
+            Text(
+                text = stringResource(err),
+                color = MaterialTheme.colorScheme.error,
+                style = MaterialTheme.typography.bodyMedium,
+                modifier = Modifier.padding(top = 12.dp),
+            )
+        }
+
+        Button(
+            onClick = { viewModel.regenerate(currentPassword) },
+            enabled = !state.busy,
+            modifier = Modifier.fillMaxWidth().padding(top = 16.dp),
+        ) { Text(stringResource(R.string.recovery_codes_regenerate)) }
+    }
+}
+
+/**
+ * A show-once display of a freshly generated recovery-code batch, with copy/share and
+ * a dismiss. Shared by this screen and the "2FA just enabled" surface on AccountScreen.
+ */
+@Composable
+fun RecoveryCodesShowOnceCard(codes: List<String>, onDismiss: () -> Unit) {
+    val context = LocalContext.current
+    val clipboard = LocalClipboardManager.current
+    val joined = remember(codes) { codes.joinToString("\n") }
+
+    Card(Modifier.fillMaxWidth().padding(top = 16.dp)) {
+        Column(Modifier.padding(16.dp)) {
+            Text(stringResource(R.string.recovery_codes_new_title), style = MaterialTheme.typography.titleMedium)
+            Text(
+                stringResource(R.string.recovery_codes_new_hint),
+                style = MaterialTheme.typography.bodySmall,
+                color = MaterialTheme.colorScheme.onSurfaceVariant,
+                modifier = Modifier.padding(top = 4.dp),
+            )
+            codes.forEach { code ->
+                Text(
+                    code,
+                    style = MaterialTheme.typography.bodyLarge.copy(fontFamily = FontFamily.Monospace),
+                    modifier = Modifier.padding(top = 8.dp),
+                )
+            }
+            Row(Modifier.fillMaxWidth().padding(top = 16.dp), horizontalArrangement = Arrangement.spacedBy(8.dp)) {
+                OutlinedButton(
+                    onClick = { clipboard.setText(AnnotatedString(joined)) },
+                ) { Text(stringResource(R.string.recovery_codes_copy)) }
+                OutlinedButton(
+                    onClick = {
+                        val send = Intent(Intent.ACTION_SEND).apply {
+                            type = "text/plain"
+                            putExtra(Intent.EXTRA_TEXT, joined)
+                        }
+                        context.startActivity(Intent.createChooser(send, null))
+                    },
+                ) { Text(stringResource(R.string.recovery_codes_share)) }
+                Button(onClick = onDismiss) { Text(stringResource(R.string.recovery_codes_done)) }
+            }
+        }
+    }
+}

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

@@ -0,0 +1,84 @@
+/*
+ * 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.repository.AccountRepository
+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 Account → Recovery Codes (TRUSTED_DEVICES_MFA.md): the remaining-count
+ * status and a password-stepped regenerate that surfaces a fresh single-use batch
+ * **once** (never persisted). The freshly generated codes live only in memory until
+ * the user leaves the screen or dismisses them.
+ */
+@HiltViewModel
+class RecoveryCodesViewModel @Inject constructor(
+    private val accountRepository: AccountRepository,
+) : ViewModel() {
+
+    data class State(
+        /** Remaining unused codes (the status endpoint). */
+        val remaining: UiState<Int> = UiState.Loading,
+        /** A just-generated batch to show once, or null. Cleared on dismiss/leave. */
+        val freshCodes: List<String>? = null,
+        val busy: Boolean = false,
+        @param:StringRes val error: Int? = null,
+    )
+
+    private val _state = MutableStateFlow(State())
+    val state: StateFlow<State> = _state.asStateFlow()
+
+    init {
+        load()
+    }
+
+    fun load() {
+        _state.update { it.copy(remaining = UiState.Loading) }
+        viewModelScope.launch {
+            _state.update { it.copy(remaining = accountRepository.recoveryCodesStatus().toUiState().map { s -> s.remaining }) }
+        }
+    }
+
+    /** Regenerate the codes; [currentPassword] is required for accounts that have one. */
+    fun regenerate(currentPassword: String?) {
+        if (_state.value.busy) return
+        _state.update { it.copy(busy = true, error = null, freshCodes = null) }
+        viewModelScope.launch {
+            when (val result = accountRepository.generateRecoveryCodes(currentPassword?.takeIf { it.isNotBlank() })) {
+                is ApiResult.Ok -> {
+                    _state.update { it.copy(busy = false, freshCodes = result.data.recoveryCodes) }
+                    // Refresh the remaining count to reflect the new batch.
+                    _state.update { it.copy(remaining = accountRepository.recoveryCodesStatus().toUiState().map { s -> s.remaining }) }
+                }
+                is ApiResult.HttpError ->
+                    _state.update { it.copy(busy = false, error = R.string.recovery_codes_error) }
+                is ApiResult.NetworkError ->
+                    _state.update { it.copy(busy = false, error = R.string.error_network) }
+            }
+        }
+    }
+
+    /** Drop the shown-once batch from memory (user saved them / navigated away). */
+    fun dismissFreshCodes() = _state.update { it.copy(freshCodes = null) }
+}
+
+/** Map an [UiState] success value (local helper mirroring ApiResult.map). */
+private inline fun <T, R> UiState<T>.map(transform: (T) -> R): UiState<R> = when (this) {
+    is UiState.Success -> UiState.Success(transform(data))
+    is UiState.Loading -> UiState.Loading
+    is UiState.Error -> this
+}

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

@@ -0,0 +1,136 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.ui.auth
+
+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.HorizontalDivider
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.OutlinedButton
+import androidx.compose.material3.Text
+import androidx.compose.material3.TextButton
+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
+import androidx.hilt.navigation.compose.hiltViewModel
+import androidx.lifecycle.compose.collectAsStateWithLifecycle
+import com.runicgateway.app.R
+import com.runicgateway.app.data.api.dto.TrustedDeviceDto
+import com.runicgateway.app.ui.UiState
+import com.runicgateway.app.ui.components.ErrorView
+import com.runicgateway.app.ui.components.LoadingView
+
+/**
+ * Account → Trusted Devices (TRUSTED_DEVICES_MFA.md): the devices allowed to skip
+ * the TOTP step at login. Trust the current device, revoke one, or untrust all. The
+ * server re-checks ownership on every call; this screen just renders the outcomes.
+ */
+@Composable
+fun TrustedDevicesScreen(
+    modifier: Modifier = Modifier,
+    viewModel: TrustedDevicesViewModel = hiltViewModel(),
+) {
+    val state by viewModel.state.collectAsStateWithLifecycle()
+
+    Column(
+        modifier = modifier
+            .fillMaxSize()
+            .verticalScroll(rememberScrollState())
+            .padding(16.dp),
+    ) {
+        Text(
+            stringResource(R.string.trusted_devices_title),
+            style = MaterialTheme.typography.titleLarge,
+        )
+        Text(
+            stringResource(R.string.trusted_devices_subtitle),
+            style = MaterialTheme.typography.bodyMedium,
+            color = MaterialTheme.colorScheme.onSurfaceVariant,
+            modifier = Modifier.padding(top = 4.dp),
+        )
+
+        state.feedback?.let { fb ->
+            Text(
+                text = stringResource(fb.messageRes),
+                color = if (fb.ok) MaterialTheme.colorScheme.primary else MaterialTheme.colorScheme.error,
+                style = MaterialTheme.typography.bodyMedium,
+                modifier = Modifier.padding(top = 12.dp),
+            )
+        }
+
+        when (val devices = state.devices) {
+            is UiState.Loading -> LoadingView(Modifier.padding(top = 32.dp))
+            is UiState.Error -> ErrorView(devices.kind, onRetry = viewModel::load, modifier = Modifier.padding(top = 32.dp))
+            is UiState.Success -> {
+                if (devices.data.isEmpty()) {
+                    Text(
+                        stringResource(R.string.trusted_devices_empty),
+                        style = MaterialTheme.typography.bodyMedium,
+                        color = MaterialTheme.colorScheme.onSurfaceVariant,
+                        modifier = Modifier.padding(top = 24.dp),
+                    )
+                } else {
+                    devices.data.forEach { device ->
+                        TrustedDeviceRow(device, state.busy, onRevoke = { viewModel.revoke(device.id) })
+                    }
+                }
+
+                HorizontalDivider(Modifier.padding(vertical = 20.dp))
+
+                Button(
+                    onClick = viewModel::trustThisDevice,
+                    enabled = !state.busy,
+                    modifier = Modifier.fillMaxWidth(),
+                ) { Text(stringResource(R.string.trusted_devices_trust_this)) }
+
+                if (devices.data.isNotEmpty()) {
+                    OutlinedButton(
+                        onClick = viewModel::revokeAll,
+                        enabled = !state.busy,
+                        modifier = Modifier.fillMaxWidth().padding(top = 8.dp),
+                    ) { Text(stringResource(R.string.trusted_devices_untrust_all)) }
+                }
+            }
+        }
+    }
+}
+
+@Composable
+private fun TrustedDeviceRow(device: TrustedDeviceDto, busy: Boolean, onRevoke: () -> Unit) {
+    Card(Modifier.fillMaxWidth().padding(top = 12.dp)) {
+        Row(
+            Modifier.fillMaxWidth().padding(16.dp),
+            verticalAlignment = Alignment.CenterVertically,
+        ) {
+            Column(Modifier.weight(1f)) {
+                Text(
+                    text = device.deviceName?.takeIf { it.isNotBlank() }
+                        ?: device.platform?.replaceFirstChar { it.uppercase() }
+                        ?: stringResource(R.string.trusted_devices_unknown),
+                    style = MaterialTheme.typography.bodyLarge,
+                )
+                device.lastUsedAt?.let {
+                    Text(
+                        stringResource(R.string.trusted_devices_last_used, it),
+                        style = MaterialTheme.typography.bodySmall,
+                        color = MaterialTheme.colorScheme.onSurfaceVariant,
+                    )
+                }
+            }
+            TextButton(onClick = onRevoke, enabled = !busy) {
+                Text(stringResource(R.string.trusted_devices_revoke))
+            }
+        }
+    }
+}

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

@@ -0,0 +1,125 @@
+/*
+ * 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.auth.DeviceNameProvider
+import com.runicgateway.app.core.result.ApiResult
+import com.runicgateway.app.data.api.dto.TrustedDeviceDto
+import com.runicgateway.app.data.repository.AccountRepository
+import com.runicgateway.app.data.repository.AccountRepository.TrustOutcome
+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 Trusted Devices screen (TRUSTED_DEVICES_MFA.md): list the devices
+ * allowed to skip the TOTP step, trust the current one (persisting the returned
+ * token via [AuthRepository]), revoke one, and untrust all. The trust action folds
+ * the `409` cap into a first-class [Feedback] telling the user to revoke one first.
+ */
+@HiltViewModel
+class TrustedDevicesViewModel @Inject constructor(
+    private val accountRepository: AccountRepository,
+    private val authRepository: AuthRepository,
+    private val sessionManager: com.runicgateway.app.core.auth.SessionManager,
+    private val deviceNameProvider: DeviceNameProvider,
+) : ViewModel() {
+
+    /** A one-shot result banner shown above the list. */
+    data class Feedback(val ok: Boolean, @param:StringRes val messageRes: Int)
+
+    data class State(
+        val devices: UiState<List<TrustedDeviceDto>> = UiState.Loading,
+        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(devices = UiState.Loading) }
+        viewModelScope.launch {
+            _state.update { it.copy(devices = accountRepository.trustedDevices().toUiState()) }
+        }
+    }
+
+    /** Trust the current device; persist the returned token so future logins skip 2FA. */
+    fun trustThisDevice() {
+        if (_state.value.busy) return
+        _state.update { it.copy(busy = true, feedback = null) }
+        viewModelScope.launch {
+            when (val outcome = accountRepository.trustThisDevice(deviceNameProvider.deviceName())) {
+                is TrustOutcome.Trusted -> {
+                    // Bind the fresh token to the signed-in username (mirrors the login path).
+                    val username = sessionManager.state.value.let {
+                        (it as? com.runicgateway.app.core.auth.Session.SignedIn)?.user?.username
+                    }
+                    if (outcome.trustToken != null && username != null) {
+                        authRepository.saveTrustToken(username, outcome.trustToken)
+                    }
+                    finish(true, R.string.trusted_devices_trusted)
+                    reload()
+                }
+                is TrustOutcome.LimitReached -> finish(false, R.string.trusted_devices_limit)
+                TrustOutcome.NetworkError -> finish(false, R.string.error_network)
+                TrustOutcome.ServerError -> finish(false, R.string.trusted_devices_error)
+            }
+        }
+    }
+
+    fun revoke(id: Long) {
+        if (_state.value.busy) return
+        _state.update { it.copy(busy = true, feedback = null) }
+        viewModelScope.launch {
+            when (accountRepository.revokeTrustedDevice(id)) {
+                is ApiResult.Ok -> {
+                    finish(true, R.string.trusted_devices_revoked)
+                    reload()
+                }
+                else -> finish(false, R.string.trusted_devices_error)
+            }
+        }
+    }
+
+    fun revokeAll() {
+        if (_state.value.busy) return
+        _state.update { it.copy(busy = true, feedback = null) }
+        viewModelScope.launch {
+            when (accountRepository.revokeAllTrustedDevices()) {
+                is ApiResult.Ok -> {
+                    // Every device is untrusted now, including this one — drop the local token.
+                    authRepository.clearTrustToken()
+                    finish(true, R.string.trusted_devices_revoked_all)
+                    reload()
+                }
+                else -> finish(false, R.string.trusted_devices_error)
+            }
+        }
+    }
+
+    fun clearFeedback() = _state.update { it.copy(feedback = null) }
+
+    private suspend fun reload() {
+        _state.update { it.copy(devices = accountRepository.trustedDevices().toUiState()) }
+    }
+
+    private fun finish(ok: Boolean, @StringRes messageRes: Int) =
+        _state.update { it.copy(busy = false, feedback = Feedback(ok, messageRes)) }
+}

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

@@ -36,6 +36,10 @@ fun LoadingView(modifier: Modifier = Modifier) {
 /**
  * Whole-screen error state with a friendly, kind-specific message and a Retry
  * button (§7). Copy is resolved from string resources so it stays localizable.
+ *
+ * [ErrorKind.FEATURE_UNAVAILABLE] renders **without** the button: an admin decides
+ * whether the shard publishes that surface, so retrying cannot change the answer and
+ * offering it would read as a transient failure the user could wait out (M11).
  */
 @Composable
 fun ErrorView(
@@ -53,15 +57,20 @@ fun ErrorView(
             style = MaterialTheme.typography.bodyLarge,
             textAlign = TextAlign.Center,
         )
-        Button(
-            onClick = onRetry,
-            modifier = Modifier.padding(top = 16.dp).width(160.dp),
-        ) {
-            Text(stringResource(R.string.action_retry))
+        if (isRetryable(kind)) {
+            Button(
+                onClick = onRetry,
+                modifier = Modifier.padding(top = 16.dp).width(160.dp),
+            ) {
+                Text(stringResource(R.string.action_retry))
+            }
         }
     }
 }
 
+/** Whether retrying this failure could plausibly succeed. Pure, so it is unit-tested. */
+fun isRetryable(kind: ErrorKind): Boolean = kind != ErrorKind.FEATURE_UNAVAILABLE
+
 /** Centered informational message for an empty list (§7). */
 @Composable
 fun EmptyView(message: String, modifier: Modifier = Modifier) {
@@ -83,5 +92,6 @@ private fun errorMessageRes(kind: ErrorKind): Int = when (kind) {
     ErrorKind.NOT_FOUND -> R.string.error_not_found
     ErrorKind.RATE_LIMITED -> R.string.error_rate_limited
     ErrorKind.SHARD_OFFLINE -> R.string.error_shard_offline
+    ErrorKind.FEATURE_UNAVAILABLE -> R.string.error_feature_unavailable
     ErrorKind.SERVER -> R.string.error_server
 }

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

@@ -6,6 +6,9 @@ package com.runicgateway.app.ui.navigation
 import androidx.annotation.StringRes
 import com.runicgateway.app.R
 import com.runicgateway.app.core.auth.Session
+import com.runicgateway.app.data.repository.ShardFeature
+import com.runicgateway.app.data.repository.ShardFeatures
+import com.runicgateway.app.data.repository.canSee
 
 /**
  * One shared, declarative, access-level navigation definition (PLAN.md §5): a
@@ -21,7 +24,12 @@ enum class MenuAccess {
     /** Visible to any signed-in account (§5, "My Account"). */
     SIGNED_IN,
 
-    /** Visible only to a player — the linked game-data groups (§6.3). */
+    /**
+     * The linked game-data groups (§6.3). Visible to any player **or** staff:
+     * staff are a superset of players (all player abilities plus their staff
+     * tools), and the backend's player self-service surface is role-agnostic, so
+     * a signed-in admin/editor/moderator sees + uses their own characters too.
+     */
     PLAYER,
 
     /** Visible to any staff role (admin/editor/moderator) — the M10 staff surface (§1). */
@@ -35,6 +43,15 @@ data class MenuEntry(
     val route: String,
     @param:StringRes val labelRes: Int,
     val access: MenuAccess = MenuAccess.PUBLIC,
+    /**
+     * For a shard-derived surface, the visibility feature it belongs to (M11).
+     *
+     * Session role is not the only gate on these: an admin can switch a feature off
+     * or raise its audience above the caller's rung, so the entry is filtered by
+     * `GET /public/shard/features` as well as by [access]. `null` means the entry
+     * isn't shard-derived and only [access] applies.
+     */
+    val feature: String? = null,
 )
 
 /**
@@ -46,7 +63,13 @@ val APP_MENU: List<MenuEntry> = listOf(
     MenuEntry(Routes.HOME, R.string.menu_home),
     MenuEntry(Routes.NEWS, R.string.menu_news),
     MenuEntry(Routes.WIKI, R.string.menu_wiki),
-    MenuEntry(Routes.SHARD, R.string.menu_shard),
+    MenuEntry(Routes.SHARD, R.string.menu_shard, feature = ShardFeature.STATUS),
+    // Protocol 3.0 shard content (M11). Each hides when the shard doesn't publish it,
+    // which for a brand-new install is every one of them until the plugin has swept.
+    MenuEntry(Routes.SHARD_RULES, R.string.menu_rules, feature = ShardFeature.RULESET),
+    MenuEntry(Routes.ATLAS, R.string.menu_atlas, feature = ShardFeature.ATLAS),
+    MenuEntry(Routes.SHARD_LEADERBOARDS, R.string.menu_leaderboards, feature = ShardFeature.LEADERBOARDS),
+    MenuEntry(Routes.SHARD_MARKET, R.string.menu_market, feature = ShardFeature.MARKET),
     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),
@@ -62,16 +85,28 @@ val APP_MENU: List<MenuEntry> = listOf(
 )
 
 /**
- * The entries the given [session] may see. Pure + side-effect-free so the access
- * gating is unit-tested without Compose.
+ * The entries the given [session] may see, given the shard [features] it may reach.
+ * Pure + side-effect-free so the gating is unit-tested without Compose.
+ *
+ * Two independent filters, and both must pass:
+ *
+ *  - [MenuEntry.access] against the session — who the caller is.
+ *  - [MenuEntry.feature] against the shard's live visibility config — what this shard
+ *    publishes at all (M11). `null` [features] means the answer isn't known yet and
+ *    every shard entry shows; see [canSee] for why that direction is deliberate.
  */
-fun visibleEntries(entries: List<MenuEntry>, session: Session): List<MenuEntry> =
+fun visibleEntries(
+    entries: List<MenuEntry>,
+    session: Session,
+    features: ShardFeatures? = null,
+): List<MenuEntry> =
     entries.filter { entry ->
-        when (entry.access) {
+        val allowedByRole = when (entry.access) {
             MenuAccess.PUBLIC -> true
             MenuAccess.SIGNED_IN -> session is Session.SignedIn
-            MenuAccess.PLAYER -> session is Session.SignedIn && session.user.isPlayer
+            MenuAccess.PLAYER -> session is Session.SignedIn && (session.user.isPlayer || session.user.isStaff)
             MenuAccess.STAFF -> session is Session.SignedIn && session.user.isStaff
             MenuAccess.MODERATOR -> session is Session.SignedIn && session.user.isModerator
         }
+        allowedByRole && (entry.feature == null || canSee(features, entry.feature))
     }

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

@@ -18,6 +18,10 @@ object Routes {
     const val LOGIN = "login"
     const val ACCOUNT = "account"
 
+    /** MFA management, reached from Account (TRUSTED_DEVICES_MFA.md). Signed-in only. */
+    const val ACCOUNT_TRUSTED_DEVICES = "account/trusted-devices"
+    const val ACCOUNT_RECOVERY_CODES = "account/recovery-codes"
+
     /** Opt-in push notification settings (§11, signed-in). */
     const val NOTIFICATIONS = "notifications"
 
@@ -30,6 +34,18 @@ object Routes {
     const val SHARD_GOVERNORS = "shard/governors"
     const val SHARD_HOUSES = "shard/houses"
 
+    /**
+     * Protocol 3.0 shard content (M11), each gated by its own visibility feature. The
+     * atlas is not under `shard/` on the wire (`/public/atlas`) because it is static
+     * content rather than live state, but it is a peer of these in the app's nav.
+     */
+    const val SHARD_RULES = "shard/rules"
+    const val SHARD_LEADERBOARDS = "shard/leaderboards"
+    const val SHARD_MARKET = "shard/market"
+    const val SHARD_MARKET_VENDOR = "shard/market/{serial}"
+    const val ATLAS = "atlas"
+    const val ATLAS_CREATURE = "atlas/{slug}"
+
     /** 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"
@@ -68,6 +84,12 @@ object Routes {
     /** The character-sheet route for an in-game serial (e.g. "0x24C"). */
     fun playerChar(serial: String) = "player/char/$serial"
 
+    /** One player vendor's shop, by in-game (hex) serial. */
+    fun marketVendor(serial: String) = "shard/market/$serial"
+
+    /** One creature's atlas page, by slug. */
+    fun atlasCreature(slug: String) = "atlas/$slug"
+
     /**
      * 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;

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

@@ -26,6 +26,7 @@ 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.CharPointsDto
 import com.runicgateway.app.data.api.dto.CharProfileDto
 import com.runicgateway.app.data.api.dto.CharStatsDto
 import com.runicgateway.app.data.api.dto.EquipmentDto
@@ -71,6 +72,7 @@ private fun CharacterSheet(char: CharProfileDto, modifier: Modifier = Modifier)
         char.stats?.let { AttributesBlock(it) }
         char.stats?.resist?.let { ResistancesBlock(it) }
         SkillsBlock(char.skills)
+        PointsBlock(displayPoints(char))
         EquipmentBlock(char.equipment)
     }
 }
@@ -215,6 +217,47 @@ private fun SkillsBlock(skills: List<SkillDto>) {
     }
 }
 
+/**
+ * Loyalty & points standings (Protocol 3.0 §7.3). Renders nothing at all for a
+ * character that has earned nothing anywhere, which is a normal state.
+ *
+ * Only a system with a real cap gets a meter: an uncapped score
+ * ([CharPointsDto.maxPoints] `0`, the common case on a real shard) has nothing to be
+ * a fraction of, and a full-width bar would imply a completion that doesn't exist.
+ */
+@Composable
+private fun PointsBlock(points: List<CharPointsDto>) {
+    if (points.isEmpty()) return
+    SheetCard(R.string.player_char_points) {
+        points.forEach { entry ->
+            val cap = entry.cap
+            val score = entry.points ?: 0L
+            Column(Modifier.padding(vertical = 5.dp)) {
+                Row(
+                    Modifier.fillMaxWidth().padding(bottom = 4.dp),
+                    horizontalArrangement = Arrangement.SpaceBetween,
+                ) {
+                    Text(
+                        // `rank` is absent unless the shard opts in; absent and
+                        // "unranked" are different, so the suffix only appears when sent.
+                        entry.rank?.let { stringResource(R.string.player_char_points_ranked, pointsLabel(entry), it) }
+                            ?: pointsLabel(entry),
+                        style = MaterialTheme.typography.labelMedium,
+                        color = MaterialTheme.colorScheme.onSurfaceVariant,
+                    )
+                    Text(
+                        cap?.let { stringResource(R.string.player_char_points_of, score, it) } ?: score.toString(),
+                        style = MaterialTheme.typography.labelMedium,
+                        color = MaterialTheme.colorScheme.onSurfaceVariant,
+                        fontWeight = FontWeight.Medium,
+                    )
+                }
+                if (cap != null) StatBar((score.toDouble() / cap).coerceIn(0.0, 1.0).toFloat())
+            }
+        }
+    }
+}
+
 @OptIn(ExperimentalLayoutApi::class)
 @Composable
 private fun EquipmentBlock(equipment: List<EquipmentDto>) {
@@ -223,7 +266,7 @@ private fun EquipmentBlock(equipment: List<EquipmentDto>) {
         equipment.forEach { item ->
             Column(Modifier.fillMaxWidth().padding(vertical = 6.dp)) {
                 Text(
-                    item.layer ?: stringResource(R.string.player_char_item),
+                    item.label ?: stringResource(R.string.player_char_item),
                     style = MaterialTheme.typography.bodyLarge,
                 )
                 val meta = listOfNotNull(
@@ -266,23 +309,58 @@ internal fun formatSkill(value: Double): String =
 /**
  * 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.
+ * reward title.
+ *
+ * Reward entries arrive as either a literal or a cliloc number in string form. The
+ * server now resolves the numeric ones into `rewardResolved`, a **parallel** array
+ * (see `docs/website/CLILOCS.md`), so the mapping below is index-preserving: an entry
+ * that didn't resolve becomes null and is skipped, but must not shift the `selected`
+ * index onto its neighbour. A number with no resolution is still skipped rather than
+ * rendered as a raw id, which is also the whole behavior on a shard that configures
+ * no cliloc table.
+ *
+ * Falling back to the first title that resolved (rather than showing nothing) matters
+ * when the *selected* one is the unresolved entry. 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) }
+    val reward = titles.reward.mapIndexed { i, raw ->
+        titles.rewardResolved.getOrNull(i)
+            ?: raw.takeUnless { it.isBlank() || it.all(Char::isDigit) }
     }
-    if (candidate != null && candidate.isNotBlank() && !candidate.all(Char::isDigit)) out.add(candidate)
+    val candidate = reward.getOrNull(titles.selected ?: -1) ?: reward.firstNotNullOfOrNull { it }
+    if (!candidate.isNullOrBlank()) out.add(candidate)
     return out.filter { it.isNotBlank() }.distinct()
 }
 
+/**
+ * A point system's display name: the shard's own [CharPointsDto.nameString] when it
+ * has one, else the humanised `PointsType` key.
+ *
+ * The fallback is the PRIMARY path, not a defensive nicety — most systems name
+ * themselves with a cliloc, so `nameString` comes back null for four of five boards
+ * on a real shard (`docs/link/v3.md` §7.5). Parity with the website's
+ * `humanisePoints`.
+ */
+internal fun pointsLabel(entry: CharPointsDto): String {
+    entry.nameString?.takeIf { it.isNotBlank() }?.let { return it }
+    val key = entry.system.orEmpty()
+    return key
+        .replace(Regex("([a-z0-9])([A-Z])"), "$1 $2")
+        .replaceFirstChar { it.uppercaseChar() }
+}
+
+/**
+ * The points block, best standing first, dropping systems the character has no score
+ * in. Guarded for an older shard plugin that sends no `points` block at all.
+ */
+internal fun displayPoints(char: CharProfileDto): List<CharPointsDto> =
+    char.points
+        .filter { (it.points ?: 0L) > 0L }
+        .sortedByDescending { it.points ?: 0L }
+
 private fun jsonText(element: kotlinx.serialization.json.JsonElement): String =
     runCatching { element.jsonPrimitive.content }.getOrElse { element.toString() }

app/src/main/java/com/runicgateway/app/ui/session/SessionViewModel.kt

@@ -8,6 +8,8 @@ import androidx.lifecycle.viewModelScope
 import com.runicgateway.app.core.auth.Session
 import com.runicgateway.app.core.auth.SessionManager
 import com.runicgateway.app.data.repository.AuthRepository
+import com.runicgateway.app.data.repository.ShardFeatures
+import com.runicgateway.app.data.repository.ShardFeaturesRepository
 import dagger.hilt.android.lifecycle.HiltViewModel
 import kotlinx.coroutines.flow.StateFlow
 import kotlinx.coroutines.launch
@@ -23,10 +25,28 @@ import javax.inject.Inject
 class SessionViewModel @Inject constructor(
     sessionManager: SessionManager,
     private val authRepository: AuthRepository,
+    shardFeaturesRepository: ShardFeaturesRepository,
 ) : ViewModel() {
 
     val session: StateFlow<Session> = sessionManager.state
 
+    /**
+     * Which shard features this viewer may reach (M11). Held here beside [session]
+     * because it answers the same question for the same consumer: what the shared
+     * menu reveals. Role and feature config are independent gates — see
+     * [com.runicgateway.app.ui.navigation.visibleEntries].
+     */
+    val shardFeatures: StateFlow<ShardFeatures?> = shardFeaturesRepository.features
+
+    init {
+        // The answer is per-viewer, so it is re-resolved on every session change.
+        // A StateFlow conflates equal values, so a resume revalidation that returns
+        // the same user does not refetch — only a real sign-in/out/role change does.
+        viewModelScope.launch {
+            session.collect { shardFeaturesRepository.refresh() }
+        }
+    }
+
     /** Re-validate the cached role against the backend on app resume. */
     fun revalidate() {
         viewModelScope.launch { authRepository.revalidate() }

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

@@ -0,0 +1,301 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.ui.shard
+
+import androidx.compose.foundation.clickable
+import androidx.compose.foundation.layout.Arrangement
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.ExperimentalLayoutApi
+import androidx.compose.foundation.layout.FlowRow
+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.foundation.text.KeyboardActions
+import androidx.compose.foundation.text.KeyboardOptions
+import androidx.compose.material3.Card
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.OutlinedTextField
+import androidx.compose.material3.Text
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.LaunchedEffect
+import androidx.compose.runtime.getValue
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.res.pluralStringResource
+import androidx.compose.ui.res.stringResource
+import androidx.compose.ui.text.input.ImeAction
+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.AtlasCreatureDto
+import com.runicgateway.app.data.api.dto.AtlasPlaceDto
+import com.runicgateway.app.data.api.dto.AtlasSpawnerDto
+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.PillTone
+import com.runicgateway.app.ui.components.SectionLabel
+import com.runicgateway.app.ui.components.StatusPill
+
+/**
+ * The spawn atlas / bestiary (PLAN.md §9 M11): "where do I find X".
+ *
+ * The whole point of the feature is the placement transform the server does — a spawn
+ * at 5411,1234 becomes *"Despise, Felucca"* — so a row leads with where a creature is
+ * found, not with coordinates.
+ */
+@Composable
+fun AtlasScreen(
+    onOpenCreature: (String) -> Unit,
+    modifier: Modifier = Modifier,
+    viewModel: AtlasViewModel = hiltViewModel(),
+) {
+    val state by viewModel.state.collectAsStateWithLifecycle()
+    val query by viewModel.query.collectAsStateWithLifecycle()
+
+    Column(modifier.fillMaxSize()) {
+        OutlinedTextField(
+            value = query,
+            onValueChange = viewModel::onQueryChange,
+            label = { Text(stringResource(R.string.atlas_search_label)) },
+            singleLine = true,
+            keyboardOptions = KeyboardOptions(imeAction = ImeAction.Search),
+            keyboardActions = KeyboardActions(onSearch = { viewModel.search() }),
+            modifier = Modifier.fillMaxWidth().padding(horizontal = 16.dp, vertical = 8.dp),
+        )
+
+        when (val s = state) {
+            is UiState.Loading -> LoadingView()
+            is UiState.Error -> ErrorView(s.kind, onRetry = viewModel::load)
+            is UiState.Success -> {
+                if (s.data.creatures.isEmpty()) {
+                    EmptyView(stringResource(R.string.atlas_empty))
+                } else {
+                    LazyColumn(
+                        modifier = Modifier.fillMaxSize().padding(horizontal = 16.dp),
+                        verticalArrangement = Arrangement.spacedBy(8.dp),
+                        contentPadding = androidx.compose.foundation.layout.PaddingValues(bottom = 16.dp),
+                    ) {
+                        items(s.data.creatures, key = { it.slug.orEmpty() }) { creature ->
+                            CreatureCard(creature, onOpenCreature)
+                        }
+                    }
+                }
+            }
+        }
+    }
+}
+
+@Composable
+private fun CreatureCard(creature: AtlasCreatureDto, onOpenCreature: (String) -> Unit) {
+    val slug = creature.slug
+    Card(
+        Modifier
+            .fillMaxWidth()
+            .then(if (slug != null) Modifier.clickable { onOpenCreature(slug) } else Modifier),
+    ) {
+        Column(Modifier.padding(16.dp)) {
+            Row(Modifier.fillMaxWidth(), horizontalArrangement = Arrangement.SpaceBetween) {
+                Text(
+                    text = creature.name ?: slug.orEmpty(),
+                    style = MaterialTheme.typography.titleSmall,
+                    maxLines = 1,
+                    overflow = TextOverflow.Ellipsis,
+                    modifier = Modifier.weight(1f),
+                )
+                // `points` is a COUNT of spawners on this route; `spawners` is the list,
+                // and only the detail route sends it.
+                creature.points?.let {
+                    Text(
+                        text = pluralStringResource(R.plurals.atlas_spawner_count, it, it),
+                        style = MaterialTheme.typography.labelSmall,
+                        color = MaterialTheme.colorScheme.onSurfaceVariant,
+                    )
+                }
+            }
+            facetSummary(creature)?.let {
+                Text(
+                    text = it,
+                    style = MaterialTheme.typography.bodySmall,
+                    color = MaterialTheme.colorScheme.onSurfaceVariant,
+                )
+            }
+        }
+    }
+}
+
+/** One creature: every spawner, where it stands, and what shares its spawns. */
+@OptIn(ExperimentalLayoutApi::class)
+@Composable
+fun AtlasCreatureScreen(
+    slug: String,
+    modifier: Modifier = Modifier,
+    viewModel: AtlasCreatureViewModel = hiltViewModel(),
+) {
+    LaunchedEffect(slug) { viewModel.load(slug) }
+    val state by viewModel.state.collectAsStateWithLifecycle()
+
+    when (val s = state) {
+        is UiState.Loading -> LoadingView(modifier)
+        is UiState.Error -> ErrorView(s.kind, onRetry = viewModel::retry, modifier = modifier)
+        is UiState.Success -> {
+            val creature = s.data
+            LazyColumn(
+                modifier = modifier.fillMaxSize().padding(horizontal = 16.dp),
+                verticalArrangement = Arrangement.spacedBy(8.dp),
+                contentPadding = androidx.compose.foundation.layout.PaddingValues(vertical = 16.dp),
+            ) {
+                item {
+                    Column {
+                        Text(
+                            creature.name ?: creature.slug.orEmpty(),
+                            style = MaterialTheme.typography.titleLarge,
+                        )
+                        creature.total?.let {
+                            Text(
+                                stringResource(R.string.atlas_total_alive, it),
+                                style = MaterialTheme.typography.bodyMedium,
+                                color = MaterialTheme.colorScheme.onSurfaceVariant,
+                            )
+                        }
+                        if (creature.facets.isNotEmpty()) {
+                            FlowRow(
+                                Modifier.padding(top = 8.dp),
+                                horizontalArrangement = Arrangement.spacedBy(6.dp),
+                                verticalArrangement = Arrangement.spacedBy(6.dp),
+                            ) {
+                                creature.facets.entries.sortedBy { it.key }.forEach { (facet, count) ->
+                                    StatusPill(
+                                        text = stringResource(R.string.atlas_facet_count, facet, count),
+                                        tone = PillTone.Neutral,
+                                    )
+                                }
+                            }
+                        }
+                    }
+                }
+                // The aggregate comes first: "where is it" is the question, and the
+                // individual coordinates below are the follow-up. Same ordering as web.
+                if (creature.places.isNotEmpty()) {
+                    item { SectionLabel(stringResource(R.string.atlas_section_places)) }
+                    items(
+                        creature.places,
+                        key = { "${it.facet.orEmpty()}:${it.label.orEmpty()}" },
+                    ) { place ->
+                        PlaceRow(place)
+                    }
+                }
+                if (creature.spawners.isNotEmpty()) {
+                    item { SectionLabel(stringResource(R.string.atlas_section_spawners)) }
+                    items(creature.spawners, key = { it.id ?: it.hashCode().toLong() }) { spawner ->
+                        SpawnerRow(spawner)
+                    }
+                    if (creature.spawnersTruncated) {
+                        item {
+                            Text(
+                                stringResource(R.string.atlas_spawners_truncated),
+                                style = MaterialTheme.typography.labelSmall,
+                                color = MaterialTheme.colorScheme.onSurfaceVariant,
+                            )
+                        }
+                    }
+                }
+                if (creature.alsoHere.isNotEmpty()) {
+                    item { SectionLabel(stringResource(R.string.atlas_section_also_here)) }
+                    item {
+                        Text(
+                            creature.alsoHere.mapNotNull { it.name ?: it.slug }.joinToString(", "),
+                            style = MaterialTheme.typography.bodySmall,
+                            color = MaterialTheme.colorScheme.onSurfaceVariant,
+                        )
+                    }
+                }
+            }
+        }
+    }
+}
+
+@Composable
+private fun PlaceRow(place: AtlasPlaceDto) {
+    Column(Modifier.fillMaxWidth().padding(vertical = 4.dp)) {
+        Text(
+            text = placeLabel(place),
+            style = MaterialTheme.typography.bodyMedium,
+        )
+        val meta = listOfNotNull(
+            place.facet,
+            place.spawners?.let { pluralStringResource(R.plurals.atlas_spawner_count, it, it) },
+            place.maxAlive?.let { stringResource(R.string.atlas_place_max_alive, it) },
+        ).joinToString("  ·  ")
+        if (meta.isNotBlank()) {
+            Text(meta, style = MaterialTheme.typography.labelSmall, color = MaterialTheme.colorScheme.onSurfaceVariant)
+        }
+    }
+}
+
+@Composable
+private fun SpawnerRow(spawner: AtlasSpawnerDto) {
+    Column(Modifier.fillMaxWidth().padding(vertical = 4.dp)) {
+        Text(
+            text = spawnerPlace(spawner),
+            style = MaterialTheme.typography.bodyMedium,
+        )
+        val meta = listOfNotNull(
+            spawner.maxCount?.let { stringResource(R.string.atlas_max_count, it) },
+            // Seconds, normalised server-side — the raw XmlSpawner values are minutes
+            // OR seconds per record.
+            formatRespawn(spawner.minDelay, spawner.maxDelay)
+                ?.let { stringResource(R.string.atlas_respawn, it) },
+        ).joinToString("  ·  ")
+        if (meta.isNotBlank()) {
+            Text(meta, style = MaterialTheme.typography.labelSmall, color = MaterialTheme.colorScheme.onSurfaceVariant)
+        }
+    }
+}
+
+// ── Pure helpers (unit-tested) ───────────────────────────────────────────────
+
+/**
+ * Where a spawner stands, preferring the server's own placement label — the
+ * point-in-rect transform is what turns a coordinate into "Despise, Felucca" and is
+ * the reason this feature exists. Falls back through region, landmark, and finally the
+ * raw coordinates, which is honest rather than useless for the ~17% of spawns that
+ * resolve to no named place.
+ */
+internal fun spawnerPlace(spawner: AtlasSpawnerDto): String {
+    spawner.label?.takeIf { it.isNotBlank() }?.let { return it }
+    val place = spawner.region ?: spawner.landmark
+    val facet = spawner.facet
+    return when {
+        place != null && facet != null -> "$place, $facet"
+        place != null -> place
+        spawner.x != null && spawner.y != null ->
+            listOfNotNull(facet, "${spawner.x}, ${spawner.y}").joinToString(" ")
+        else -> facet.orEmpty()
+    }
+}
+
+/**
+ * The name of an aggregated place. [AtlasPlaceDto.label] is already the server's
+ * resolved answer and falls back to "Wilderness" there, so the only case left here is
+ * a place that carried no label at all — then the facet is better than nothing.
+ */
+internal fun placeLabel(place: AtlasPlaceDto): String =
+    place.label?.takeIf { it.isNotBlank() } ?: place.facet.orEmpty()
+
+/**
+ * A creature's facets as one line, most spawners first — "where is it *mostly*" is the
+ * question a search result answers.
+ */
+internal fun facetSummary(creature: AtlasCreatureDto): String? {
+    if (creature.facets.isEmpty()) return null
+    return creature.facets.entries
+        .sortedByDescending { it.value }
+        .joinToString(", ") { it.key }
+}

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

@@ -0,0 +1,125 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.ui.shard
+
+import androidx.lifecycle.ViewModel
+import androidx.lifecycle.viewModelScope
+import com.runicgateway.app.core.result.ApiResult
+import com.runicgateway.app.data.api.dto.AtlasCreatureDto
+import com.runicgateway.app.data.api.dto.AtlasCreaturePageDto
+import com.runicgateway.app.data.repository.ShardRepository
+import com.runicgateway.app.ui.UiState
+import com.runicgateway.app.ui.toShardUiState
+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 spawn atlas / bestiary (PLAN.md §9 M11, `docs/link/v3.md` §6): where each
+ * creature spawns, derived server-side from the shard's own data files.
+ *
+ * Static shard **content**, not live state — it does not go offline with the sidecar,
+ * and it lives under `/public/atlas`, not `/public/shard`. Unlike the shard routes it
+ * IS site-mode gated, so a site in maintenance withholds it independently.
+ */
+@HiltViewModel
+class AtlasViewModel @Inject constructor(
+    private val repository: ShardRepository,
+) : ViewModel() {
+
+    private val _state = MutableStateFlow<UiState<AtlasCreaturePageDto>>(UiState.Loading)
+    val state: StateFlow<UiState<AtlasCreaturePageDto>> = _state.asStateFlow()
+
+    private val _query = MutableStateFlow("")
+    val query: StateFlow<String> = _query.asStateFlow()
+
+    private val _facet = MutableStateFlow<String?>(null)
+    val facet: StateFlow<String?> = _facet.asStateFlow()
+
+    /**
+     * The facets this shard actually has. Discovered from the atlas itself — a shard
+     * may add, replace or rename facets when its maps change, so nothing here may name
+     * one (`v3.md` §6.1 R2).
+     */
+    private val _facets = MutableStateFlow<List<String>>(emptyList())
+    val facets: StateFlow<List<String>> = _facets.asStateFlow()
+
+    init {
+        load()
+    }
+
+    fun onQueryChange(value: String) {
+        _query.value = value
+    }
+
+    fun onFacetChange(value: String?) {
+        if (value == _facet.value) return
+        _facet.value = value
+        search()
+    }
+
+    fun search() = load()
+
+    fun load() {
+        _state.value = UiState.Loading
+        viewModelScope.launch {
+            val page = repository.atlasCreatures(query = _query.value, facet = _facet.value)
+            if (page is ApiResult.Ok && _facets.value.isEmpty()) {
+                // Only the first successful page needs to establish the filter options;
+                // a filtered page would otherwise narrow them to its own results.
+                _facets.value = page.data.creatures
+                    .flatMap { it.facets.keys }
+                    .distinct()
+                    .sorted()
+            }
+            _state.value = page.toShardUiState()
+        }
+    }
+}
+
+/** One creature's detail page: every spawner, and what else shares them. */
+@HiltViewModel
+class AtlasCreatureViewModel @Inject constructor(
+    private val repository: ShardRepository,
+) : ViewModel() {
+
+    private val _state = MutableStateFlow<UiState<AtlasCreatureDto>>(UiState.Loading)
+    val state: StateFlow<UiState<AtlasCreatureDto>> = _state.asStateFlow()
+
+    private var slug: String? = null
+
+    fun load(slug: String) {
+        this.slug = slug
+        _state.value = UiState.Loading
+        viewModelScope.launch {
+            _state.value = repository.atlasCreature(slug).toShardUiState()
+        }
+    }
+
+    fun retry() {
+        slug?.let { load(it) }
+    }
+}
+
+/**
+ * A respawn delay as text. **The API carries SECONDS** — XmlSpawner stores minutes
+ * except when a delay doesn't divide into whole minutes, and the server's parser
+ * normalises the two spellings so a `5` is never ambiguous here (`v3.md` §6.3).
+ *
+ * Pure, so the unit conversion is unit-tested rather than eyeballed on a page.
+ */
+internal fun formatRespawn(minSeconds: Int?, maxSeconds: Int?): String? {
+    val lo = minSeconds ?: maxSeconds ?: return null
+    val hi = maxSeconds ?: minSeconds ?: return null
+    return if (lo == hi) humaniseSeconds(lo) else "${humaniseSeconds(lo)}–${humaniseSeconds(hi)}"
+}
+
+private fun humaniseSeconds(seconds: Int): String = when {
+    seconds < 60 -> "${seconds}s"
+    seconds % 60 == 0 -> "${seconds / 60}m"
+    else -> "${seconds / 60}m ${seconds % 60}s"
+}

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

@@ -10,7 +10,7 @@ import com.runicgateway.app.core.result.ApiResult
 import com.runicgateway.app.data.api.dto.ChampDto
 import com.runicgateway.app.data.repository.ShardRepository
 import com.runicgateway.app.ui.UiState
-import com.runicgateway.app.ui.toUiState
+import com.runicgateway.app.ui.toShardUiState
 import dagger.hilt.android.lifecycle.HiltViewModel
 import kotlinx.coroutines.flow.MutableStateFlow
 import kotlinx.coroutines.flow.StateFlow
@@ -49,7 +49,7 @@ class ChampsViewModel @Inject constructor(
                     board.seed(result.data)
                     publish()
                 }
-                else -> _state.value = result.toUiState()
+                else -> _state.value = result.toShardUiState()
             }
         }
     }
@@ -69,7 +69,9 @@ class ChampsViewModel @Inject constructor(
     private fun applyFrame(frame: ShardStreamEvent.Frame) {
         when (frame.kind) {
             "champ.update" -> repository.champFrame(frame.data)?.let { board.upsert(it) }
-            "champ.remove" -> FrameFields.longField(frame.data, "serial")?.let { board.remove(it.toString()) }
+            // Serial is an opaque hex-string key ("0x…"), not a number — read as a
+            // string (reading it as a Long silently dropped every champ.remove).
+            "champ.remove" -> FrameFields.stringField(frame.data, "serial")?.let { board.remove(it) }
             else -> return
         }
         // Only republish when the board actually changed (Success state only).

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

@@ -11,7 +11,7 @@ import com.runicgateway.app.data.api.dto.GovernorDto
 import com.runicgateway.app.data.api.dto.GovernorTermDto
 import com.runicgateway.app.data.repository.ShardRepository
 import com.runicgateway.app.ui.UiState
-import com.runicgateway.app.ui.toUiState
+import com.runicgateway.app.ui.toShardUiState
 import dagger.hilt.android.lifecycle.HiltViewModel
 import kotlinx.coroutines.flow.MutableStateFlow
 import kotlinx.coroutines.flow.StateFlow
@@ -55,7 +55,7 @@ class GovernorsViewModel @Inject constructor(
                     board.seed(result.data)
                     publish()
                 }
-                else -> _state.value = result.toUiState()
+                else -> _state.value = result.toShardUiState()
             }
         }
     }

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

@@ -10,7 +10,7 @@ import com.runicgateway.app.core.result.ApiResult
 import com.runicgateway.app.data.api.dto.GuildDto
 import com.runicgateway.app.data.repository.ShardRepository
 import com.runicgateway.app.ui.UiState
-import com.runicgateway.app.ui.toUiState
+import com.runicgateway.app.ui.toShardUiState
 import dagger.hilt.android.lifecycle.HiltViewModel
 import kotlinx.coroutines.flow.MutableStateFlow
 import kotlinx.coroutines.flow.StateFlow
@@ -50,7 +50,7 @@ class GuildsViewModel @Inject constructor(
                     board.seed(result.data)
                     publish()
                 }
-                else -> _state.value = result.toUiState()
+                else -> _state.value = result.toShardUiState()
             }
         }
     }

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

@@ -10,7 +10,7 @@ import com.runicgateway.app.core.result.ApiResult
 import com.runicgateway.app.data.api.dto.HouseDto
 import com.runicgateway.app.data.repository.ShardRepository
 import com.runicgateway.app.ui.UiState
-import com.runicgateway.app.ui.toUiState
+import com.runicgateway.app.ui.toShardUiState
 import dagger.hilt.android.lifecycle.HiltViewModel
 import kotlinx.coroutines.flow.MutableStateFlow
 import kotlinx.coroutines.flow.StateFlow
@@ -50,7 +50,7 @@ class HousesViewModel @Inject constructor(
                     board.seed(result.data)
                     publish()
                 }
-                else -> _state.value = result.toUiState()
+                else -> _state.value = result.toShardUiState()
             }
         }
     }
@@ -69,7 +69,9 @@ class HousesViewModel @Inject constructor(
 
     private fun applyFrame(frame: ShardStreamEvent.Frame) {
         if (frame.kind != "house.decay") return
-        val serial = FrameFields.longField(frame.data, "serial") ?: return
+        // Serials are opaque hex-string keys ("0x…"), not numbers — read as a string
+        // (reading it as a Long silently dropped every live IDOC update).
+        val serial = FrameFields.stringField(frame.data, "serial") ?: return
         // `to` is the new decay stage; only IDOC belongs on the public board.
         val stage = FrameFields.stringField(frame.data, "to")
             ?: FrameFields.stringField(frame.data, "stage")

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

@@ -0,0 +1,169 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.ui.shard
+
+import androidx.compose.foundation.layout.Arrangement
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.Row
+import androidx.compose.foundation.layout.fillMaxWidth
+import androidx.compose.foundation.layout.padding
+import androidx.compose.material3.Card
+import androidx.compose.material3.HorizontalDivider
+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.font.FontWeight
+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.BrandDto
+import com.runicgateway.app.data.api.dto.PointsBoardDto
+import com.runicgateway.app.data.api.dto.PointsEntryDto
+import com.runicgateway.app.ui.components.SectionLabel
+
+/**
+ * The points/loyalty leaderboards (PLAN.md §9 M11), one card per system, live via
+ * `points.board` frames.
+ */
+@Composable
+fun LeaderboardsScreen(
+    brand: BrandDto? = null,
+    modifier: Modifier = Modifier,
+    viewModel: LeaderboardsViewModel = hiltViewModel(),
+) {
+    val state by viewModel.state.collectAsStateWithLifecycle()
+    val connected by viewModel.connected.collectAsStateWithLifecycle()
+
+    LiveBoardScreen(
+        emptyMessage = stringResource(R.string.leaderboards_empty),
+        state = state,
+        connected = connected,
+        onRetry = viewModel::load,
+        key = { it.system.orEmpty() },
+        modifier = modifier,
+    ) { board -> BoardCard(board, placeholderName(brand)) }
+}
+
+@Composable
+private fun BoardCard(board: PointsBoardDto, placeholderName: String) {
+    Card(Modifier.fillMaxWidth()) {
+        Column(Modifier.padding(16.dp), verticalArrangement = Arrangement.spacedBy(2.dp)) {
+            Row(Modifier.fillMaxWidth(), horizontalArrangement = Arrangement.SpaceBetween) {
+                Text(
+                    text = boardLabel(board),
+                    style = MaterialTheme.typography.titleMedium,
+                    maxLines = 1,
+                    overflow = TextOverflow.Ellipsis,
+                    modifier = Modifier.weight(1f),
+                )
+                board.players?.let {
+                    Text(
+                        text = stringResource(R.string.leaderboards_players, it),
+                        style = MaterialTheme.typography.labelSmall,
+                        color = MaterialTheme.colorScheme.onSurfaceVariant,
+                    )
+                }
+            }
+            // A cap is worth stating only when there is one; most systems on a real
+            // shard are uncapped (maxPoints 0), and "/ 0" would be nonsense.
+            board.cap?.let {
+                SectionLabel(stringResource(R.string.leaderboards_cap, it))
+            }
+
+            if (board.top.isEmpty()) {
+                // A board nobody has scored on still gets a row, so the page reads as a
+                // set of standings waiting to be filled rather than a stack of blanks.
+                // It is deliberately NOT shaped like an entry — no rank, no score, the
+                // instance's own name — because a placeholder that looked like a real
+                // standing would be a fabricated one. The first real entry replaces it.
+                HorizontalDivider(Modifier.padding(vertical = 8.dp))
+                Row(
+                    Modifier.fillMaxWidth().padding(vertical = 3.dp),
+                    horizontalArrangement = Arrangement.SpaceBetween,
+                ) {
+                    Text(
+                        text = placeholderName,
+                        style = MaterialTheme.typography.bodyMedium,
+                        color = MaterialTheme.colorScheme.onSurfaceVariant,
+                        maxLines = 1,
+                        overflow = TextOverflow.Ellipsis,
+                        modifier = Modifier.weight(1f),
+                    )
+                    Text(
+                        text = stringResource(R.string.leaderboards_no_score),
+                        style = MaterialTheme.typography.bodyMedium,
+                        color = MaterialTheme.colorScheme.onSurfaceVariant,
+                    )
+                }
+                Text(
+                    stringResource(R.string.leaderboards_board_empty),
+                    style = MaterialTheme.typography.labelSmall,
+                    color = MaterialTheme.colorScheme.onSurfaceVariant,
+                    modifier = Modifier.padding(top = 6.dp),
+                )
+            } else {
+                HorizontalDivider(Modifier.padding(vertical = 8.dp))
+                board.top.forEach { entry -> EntryRow(entry) }
+            }
+        }
+    }
+}
+
+@Composable
+private fun EntryRow(entry: PointsEntryDto) {
+    Row(
+        Modifier.fillMaxWidth().padding(vertical = 3.dp),
+        horizontalArrangement = Arrangement.SpaceBetween,
+    ) {
+        Text(
+            text = stringResource(
+                R.string.leaderboards_rank_name,
+                entry.rank ?: 0,
+                // The character name is admin-configurable — a shard can publish
+                // standings without naming who holds them, so a nameless rank is a
+                // valid row rather than a broken one.
+                entry.name ?: stringResource(R.string.leaderboards_hidden_name),
+            ),
+            style = MaterialTheme.typography.bodyMedium,
+            maxLines = 1,
+            overflow = TextOverflow.Ellipsis,
+            modifier = Modifier.weight(1f),
+        )
+        Text(
+            text = (entry.points ?: 0L).toString(),
+            style = MaterialTheme.typography.bodyMedium,
+            fontWeight = FontWeight.Medium,
+            color = MaterialTheme.colorScheme.onSurfaceVariant,
+        )
+    }
+}
+
+/**
+ * A board's display name: the shard's own literal when it has one, else the humanised
+ * `PointsType` key. The fallback is the PRIMARY path — four of five boards on a real
+ * shard name themselves with a cliloc and send `nameString: null`.
+ */
+internal fun boardLabel(board: PointsBoardDto): String {
+    board.nameString?.takeIf { it.isNotBlank() }?.let { return it }
+    return board.system.orEmpty()
+        .replace(Regex("([a-z0-9])([A-Z])"), "$1 $2")
+        .replaceFirstChar { it.uppercaseChar() }
+}
+
+/**
+ * The name to stand in for an empty board: this instance's, falling back to the app
+ * name — the same resolution the app bar uses, so a shard that publishes no branding
+ * still reads as *something* rather than as a blank row.
+ *
+ * Pure and separate so the fallback order is testable; [BrandDto.name] can be present
+ * but blank, which is a shard that set the key and left it empty.
+ */
+@Composable
+internal fun placeholderName(brand: BrandDto?): String =
+    brand?.name?.takeIf { it.isNotBlank() } ?: stringResource(R.string.app_name)

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

@@ -0,0 +1,101 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.ui.shard
+
+import androidx.lifecycle.ViewModel
+import androidx.lifecycle.viewModelScope
+import com.runicgateway.app.core.net.ShardStreamEvent
+import com.runicgateway.app.core.result.ApiResult
+import com.runicgateway.app.data.api.dto.PointsBoardDto
+import com.runicgateway.app.data.repository.ShardRepository
+import com.runicgateway.app.ui.UiState
+import com.runicgateway.app.ui.toShardUiState
+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 points/loyalty leaderboards (PLAN.md §9 M11, `docs/link/v3.md` §7): one board
+ * per point currency the shard publishes, each with its top ranks.
+ *
+ * Served from the website's own store, so the page renders while the shard is down —
+ * which matters more here than for live state: these are standings accumulated over
+ * months, and blanking them during a restart would look like data loss.
+ *
+ * Kept live by `points.board` frames, one per system, merged in place by [LiveBoard].
+ */
+@HiltViewModel
+class LeaderboardsViewModel @Inject constructor(
+    private val repository: ShardRepository,
+) : ViewModel() {
+
+    private val board = LiveBoard<PointsBoardDto> { it.system.orEmpty() }
+
+    private val _state = MutableStateFlow<UiState<List<PointsBoardDto>>>(UiState.Loading)
+    val state: StateFlow<UiState<List<PointsBoardDto>>> = _state.asStateFlow()
+
+    private val _connected = MutableStateFlow(false)
+    val connected: StateFlow<Boolean> = _connected.asStateFlow()
+
+    init {
+        load()
+        collectLive()
+    }
+
+    fun load() {
+        _state.value = UiState.Loading
+        viewModelScope.launch {
+            when (val result = repository.pointsBoards()) {
+                is ApiResult.Ok -> {
+                    board.seed(result.data)
+                    publish()
+                }
+                else -> _state.value = result.toShardUiState()
+            }
+        }
+    }
+
+    private fun collectLive() {
+        viewModelScope.launch {
+            repository.liveEvents().collect { event ->
+                when (event) {
+                    is ShardStreamEvent.Open -> _connected.value = true
+                    is ShardStreamEvent.Closed -> _connected.value = false
+                    is ShardStreamEvent.Frame -> applyFrame(event)
+                }
+            }
+        }
+    }
+
+    private fun applyFrame(frame: ShardStreamEvent.Frame) {
+        // There is deliberately no `points.remove` on the wire: the system set is fixed
+        // for a given shard build, the same argument `city.update` makes.
+        if (frame.kind != "points.board") return
+        repository.pointsBoardFrame(frame.data)?.let { board.upsert(it) }
+        if (_state.value is UiState.Success) publish()
+    }
+
+    private fun publish() {
+        _state.value = UiState.Success(orderBoards(board.values()))
+    }
+}
+
+/**
+ * Board display order: most-contested first, then by name, so the boards people
+ * actually compete on lead. Pure, so the ordering is unit-tested.
+ *
+ * Boards the shard flags as not player-facing (`showOnGump = false`) are dropped —
+ * that is the shard's own "is this for players?" signal and the plugin already filters
+ * on it, so this only guards a shard configured to publish extras.
+ */
+internal fun orderBoards(boards: Collection<PointsBoardDto>): List<PointsBoardDto> =
+    boards
+        .filter { it.showOnGump }
+        .sortedWith(
+            compareByDescending<PointsBoardDto> { it.players ?: 0 }
+                .thenBy { (it.nameString ?: it.system).orEmpty().lowercase() },
+        )

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

@@ -0,0 +1,260 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.ui.shard
+
+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.lazy.LazyColumn
+import androidx.compose.foundation.lazy.items
+import androidx.compose.foundation.text.KeyboardActions
+import androidx.compose.foundation.text.KeyboardOptions
+import androidx.compose.material3.Card
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.OutlinedTextField
+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.text.input.ImeAction
+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.MarketListingDto
+import com.runicgateway.app.data.api.dto.MarketLocationDto
+import com.runicgateway.app.data.api.dto.MarketVendorDto
+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 shard-wide marketplace (PLAN.md §9 M11): search every player vendor's stock.
+ *
+ * The staleness line under the search box is required, not decoration — see
+ * [MarketViewModel]. Results are listings, so a row names both the item and the shop
+ * that sells it, and tapping it opens that shop.
+ */
+@Composable
+fun MarketScreen(
+    onOpenVendor: (String) -> Unit,
+    modifier: Modifier = Modifier,
+    viewModel: MarketViewModel = hiltViewModel(),
+) {
+    val state by viewModel.state.collectAsStateWithLifecycle()
+    val meta by viewModel.meta.collectAsStateWithLifecycle()
+    val query by viewModel.query.collectAsStateWithLifecycle()
+
+    Column(modifier.fillMaxSize()) {
+        OutlinedTextField(
+            value = query,
+            onValueChange = viewModel::onQueryChange,
+            label = { Text(stringResource(R.string.market_search_label)) },
+            singleLine = true,
+            // Searched on submit rather than per keystroke: this is the site's first
+            // rate-limited public endpoint.
+            keyboardOptions = KeyboardOptions(imeAction = ImeAction.Search),
+            keyboardActions = KeyboardActions(onSearch = { viewModel.search() }),
+            modifier = Modifier.fillMaxWidth().padding(horizontal = 16.dp, vertical = 8.dp),
+        )
+        meta?.staleAt?.let {
+            SectionLabel(
+                text = stringResource(R.string.market_staleness),
+                modifier = Modifier.padding(horizontal = 16.dp),
+            )
+        }
+
+        when (val s = state) {
+            is UiState.Loading -> LoadingView()
+            is UiState.Error -> ErrorView(s.kind, onRetry = viewModel::load)
+            is UiState.Success -> {
+                if (s.data.listings.isEmpty()) {
+                    EmptyView(stringResource(R.string.market_empty))
+                } else {
+                    LazyColumn(
+                        modifier = Modifier.fillMaxSize().padding(horizontal = 16.dp),
+                        verticalArrangement = Arrangement.spacedBy(8.dp),
+                        contentPadding = androidx.compose.foundation.layout.PaddingValues(bottom = 16.dp),
+                    ) {
+                        items(s.data.listings, key = { it.serial ?: it.hashCode().toString() }) { listing ->
+                            ListingCard(listing, onOpenVendor)
+                        }
+                    }
+                }
+            }
+        }
+    }
+}
+
+@Composable
+private fun ListingCard(listing: MarketListingDto, onOpenVendor: (String) -> Unit) {
+    val vendorSerial = listing.vendor?.serial
+    Card(
+        Modifier
+            .fillMaxWidth()
+            .then(if (vendorSerial != null) Modifier.clickable { onOpenVendor(vendorSerial) } else Modifier),
+    ) {
+        Column(Modifier.padding(16.dp)) {
+            Row(Modifier.fillMaxWidth(), horizontalArrangement = Arrangement.SpaceBetween) {
+                Text(
+                    text = listingTitle(listing)
+                        ?: stringResource(R.string.market_unnamed_item, listing.itemId ?: 0),
+                    style = MaterialTheme.typography.titleSmall,
+                    maxLines = 1,
+                    overflow = TextOverflow.Ellipsis,
+                    modifier = Modifier.weight(1f),
+                )
+                Text(
+                    text = stringResource(R.string.market_price, listing.price ?: 0L),
+                    style = MaterialTheme.typography.titleSmall,
+                    fontWeight = FontWeight.Medium,
+                )
+            }
+            val shop = listing.vendor?.shopName ?: listing.vendor?.ownerName
+            if (shop != null) {
+                Text(
+                    text = shop,
+                    style = MaterialTheme.typography.bodySmall,
+                    color = MaterialTheme.colorScheme.onSurfaceVariant,
+                    maxLines = 1,
+                    overflow = TextOverflow.Ellipsis,
+                )
+            }
+            locationLine(listing.vendor?.location)?.let {
+                Text(
+                    text = it,
+                    style = MaterialTheme.typography.labelSmall,
+                    color = MaterialTheme.colorScheme.onSurfaceVariant,
+                )
+            }
+        }
+    }
+}
+
+/**
+ * One shop and its stock. The only surface that can answer the two questions a result
+ * list can't: how much of a truncated shop is published, and where a shop is when the
+ * shard doesn't say.
+ */
+@Composable
+fun MarketVendorScreen(
+    serial: String,
+    modifier: Modifier = Modifier,
+    viewModel: MarketVendorViewModel = hiltViewModel(),
+) {
+    androidx.compose.runtime.LaunchedEffect(serial) { viewModel.load(serial) }
+    val state by viewModel.state.collectAsStateWithLifecycle()
+
+    when (val s = state) {
+        is UiState.Loading -> LoadingView(modifier)
+        is UiState.Error -> ErrorView(s.kind, onRetry = viewModel::retry, modifier = modifier)
+        is UiState.Success -> VendorContent(s.data, modifier)
+    }
+}
+
+@Composable
+private fun VendorContent(vendor: MarketVendorDto, modifier: Modifier = Modifier) {
+    LazyColumn(
+        modifier = modifier.fillMaxSize().padding(horizontal = 16.dp),
+        verticalArrangement = Arrangement.spacedBy(8.dp),
+        contentPadding = androidx.compose.foundation.layout.PaddingValues(vertical = 16.dp),
+    ) {
+        item {
+            Column {
+                Text(
+                    vendor.shopName ?: stringResource(R.string.market_unnamed_shop),
+                    style = MaterialTheme.typography.titleLarge,
+                )
+                vendor.ownerName?.let {
+                    Text(
+                        stringResource(R.string.market_owner, it),
+                        style = MaterialTheme.typography.bodyMedium,
+                        color = MaterialTheme.colorScheme.onSurfaceVariant,
+                    )
+                }
+                Text(
+                    // A gated location is a real answer, not a blank: the shard has
+                    // this shop, it just doesn't publish where it stands.
+                    text = locationLine(vendor.location) ?: stringResource(R.string.market_location_hidden),
+                    style = MaterialTheme.typography.bodySmall,
+                    color = MaterialTheme.colorScheme.onSurfaceVariant,
+                )
+                if (vendor.truncated) {
+                    Text(
+                        text = stringResource(
+                            R.string.market_truncated,
+                            vendor.count ?: vendor.items.size,
+                            vendor.total ?: 0,
+                        ),
+                        style = MaterialTheme.typography.labelSmall,
+                        color = MaterialTheme.colorScheme.onSurfaceVariant,
+                        modifier = Modifier.padding(top = 6.dp),
+                    )
+                }
+            }
+        }
+        if (vendor.items.isEmpty()) {
+            item { Text(stringResource(R.string.market_shop_empty), style = MaterialTheme.typography.bodyMedium) }
+        } else {
+            items(vendor.items, key = { it.serial ?: it.hashCode().toString() }) { item ->
+                Row(Modifier.fillMaxWidth().padding(vertical = 4.dp), horizontalArrangement = Arrangement.SpaceBetween) {
+                    Text(
+                        text = listingTitle(item) ?: stringResource(R.string.market_unnamed_item, item.itemId ?: 0),
+                        style = MaterialTheme.typography.bodyMedium,
+                        maxLines = 1,
+                        overflow = TextOverflow.Ellipsis,
+                        modifier = Modifier.weight(1f),
+                    )
+                    Text(
+                        text = stringResource(R.string.market_price, item.price ?: 0L),
+                        style = MaterialTheme.typography.bodyMedium,
+                        color = MaterialTheme.colorScheme.onSurfaceVariant,
+                    )
+                }
+            }
+        }
+    }
+}
+
+// ── Pure helpers (unit-tested) ───────────────────────────────────────────────
+
+/**
+ * What to call a listing: a player-set name, else the server-resolved cliloc name,
+ * else null so the caller can fall back to the item id. A shard with no cliloc table
+ * configured legitimately publishes neither.
+ *
+ * A stack shows its count, since "12 × ingot" and "ingot" at the same price are very
+ * different offers.
+ */
+internal fun listingTitle(listing: MarketListingDto): String? {
+    val base = listing.label ?: return null
+    val amount = listing.amount ?: 1
+    return if (amount > 1) "$amount × $base" else base
+}
+
+/**
+ * A shop's whereabouts as one line, or null when the shard publishes no location —
+ * which happens both because an admin gated the field and because the nesting means
+ * the WHOLE block goes at once, never a half-populated one.
+ */
+internal fun locationLine(location: MarketLocationDto?): String? {
+    if (location == null) return null
+    val place = location.house ?: location.region
+    val facet = location.map
+    return when {
+        place != null && facet != null -> "$place, $facet"
+        place != null -> place
+        facet != null -> facet
+        else -> null
+    }
+}

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

@@ -0,0 +1,118 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.ui.shard
+
+import androidx.lifecycle.ViewModel
+import androidx.lifecycle.viewModelScope
+import com.runicgateway.app.core.result.ApiResult
+import com.runicgateway.app.data.api.dto.MarketMetaDto
+import com.runicgateway.app.data.api.dto.MarketPageDto
+import com.runicgateway.app.data.api.dto.MarketVendorDto
+import com.runicgateway.app.data.repository.ShardRepository
+import com.runicgateway.app.ui.UiState
+import com.runicgateway.app.ui.toShardUiState
+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 shard-wide player-vendor marketplace (PLAN.md §9 M11, `docs/link/v3.md` §8):
+ * search every shop's stock at once.
+ *
+ * **Not live, on purpose.** The `market` feature ships with its SSE fan-out disabled —
+ * a firehose of full vendor inventories would be the site's biggest bandwidth consumer
+ * and no screen needs it live — so this is a plain paginated read. It is also the
+ * first genuinely **rate-limited** public endpoint, which is why the query is applied
+ * on submit rather than on every keystroke.
+ *
+ * The staleness stamp from [meta] is not decoration: the shard sweeps vendors
+ * round-robin, so a listing can legitimately be a full cycle behind, and a screen that
+ * implied live prices would send someone to an item that sold twenty minutes ago.
+ */
+@HiltViewModel
+class MarketViewModel @Inject constructor(
+    private val repository: ShardRepository,
+) : ViewModel() {
+
+    private val _state = MutableStateFlow<UiState<MarketPageDto>>(UiState.Loading)
+    val state: StateFlow<UiState<MarketPageDto>> = _state.asStateFlow()
+
+    private val _meta = MutableStateFlow<MarketMetaDto?>(null)
+    val meta: StateFlow<MarketMetaDto?> = _meta.asStateFlow()
+
+    private val _query = MutableStateFlow("")
+    val query: StateFlow<String> = _query.asStateFlow()
+
+    private val _sort = MutableStateFlow(ShardRepository.SORT_PRICE_ASC)
+    val sort: StateFlow<String> = _sort.asStateFlow()
+
+    init {
+        load()
+    }
+
+    fun onQueryChange(value: String) {
+        // Bounded to what the server accepts, so an over-long query is trimmed here
+        // rather than bounced as a 400.
+        _query.value = value.take(MAX_QUERY)
+    }
+
+    fun onSortChange(value: String) {
+        if (value == _sort.value) return
+        _sort.value = value
+        search()
+    }
+
+    /** Run the current query. Called on submit, not per keystroke — this endpoint is rate-limited. */
+    fun search() = load()
+
+    fun load() {
+        _state.value = UiState.Loading
+        viewModelScope.launch {
+            // Meta is secondary: the staleness banner and filter options are worth
+            // having, but a failure there must not blank the results.
+            _meta.value = (repository.marketMeta() as? ApiResult.Ok)?.data
+            _state.value = repository.market(
+                query = _query.value,
+                sort = _sort.value,
+            ).toShardUiState()
+        }
+    }
+
+    companion object {
+        /** The server rejects a longer `q`. */
+        const val MAX_QUERY = 60
+    }
+}
+
+/**
+ * One shop and its stock. The only surface that can render the two states a result
+ * list cannot: a [MarketVendorDto.truncated] shop, and a location an admin has gated
+ * away — which is a real answer ("the shard doesn't publish where this is") rather
+ * than an empty coordinate.
+ */
+@HiltViewModel
+class MarketVendorViewModel @Inject constructor(
+    private val repository: ShardRepository,
+) : ViewModel() {
+
+    private val _state = MutableStateFlow<UiState<MarketVendorDto>>(UiState.Loading)
+    val state: StateFlow<UiState<MarketVendorDto>> = _state.asStateFlow()
+
+    private var serial: String? = null
+
+    fun load(serial: String) {
+        this.serial = serial
+        _state.value = UiState.Loading
+        viewModelScope.launch {
+            _state.value = repository.marketVendor(serial).toShardUiState()
+        }
+    }
+
+    fun retry() {
+        serial?.let { load(it) }
+    }
+}

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

@@ -0,0 +1,207 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.ui.shard
+
+import androidx.compose.foundation.layout.Arrangement
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.ExperimentalLayoutApi
+import androidx.compose.foundation.layout.FlowRow
+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.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.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.RulesetCapsDto
+import com.runicgateway.app.data.api.dto.RulesetDto
+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.PillTone
+import com.runicgateway.app.ui.components.StatusPill
+
+/**
+ * The shard ruleset (PLAN.md §9 M11): what this world is configured to do.
+ *
+ * Every block renders only when the shard published it — an omitted block means the
+ * system is off, not that the value is unknown, so an empty section would assert
+ * something false.
+ */
+@Composable
+fun RulesScreen(
+    modifier: Modifier = Modifier,
+    viewModel: RulesViewModel = 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 -> {
+            val ruleset = s.data
+            // A null body is a successful read of a shard that has never published its
+            // ruleset — distinct from the feature being switched off, which is an error
+            // state above.
+            if (ruleset == null) {
+                EmptyView(stringResource(R.string.rules_unpublished), modifier)
+            } else {
+                RulesetContent(ruleset, modifier)
+            }
+        }
+    }
+}
+
+@Composable
+private fun RulesetContent(ruleset: RulesetDto, modifier: Modifier = Modifier) {
+    LazyColumn(
+        modifier = modifier.fillMaxSize().padding(horizontal = 16.dp),
+        verticalArrangement = Arrangement.spacedBy(12.dp),
+        contentPadding = androidx.compose.foundation.layout.PaddingValues(vertical = 16.dp),
+    ) {
+        item {
+            RuleCard(stringResource(R.string.rules_section_shard)) {
+                RuleRow(stringResource(R.string.rules_name), ruleset.shard)
+                RuleRow(stringResource(R.string.rules_expansion), ruleset.expansion)
+                // `connect` is the ruleset's one admin-configurable field: an operator
+                // who published an address may still want it behind a login, so its
+                // absence here is a setting, not a missing value.
+                RuleRow(stringResource(R.string.rules_connect), ruleset.connect)
+            }
+        }
+        if (ruleset.systems.isNotEmpty()) {
+            item { SystemsCard(ruleset.systems) }
+        }
+        ruleset.caps?.let { caps -> item { CapsCard(caps) } }
+        item {
+            val accounts = ruleset.accounts
+            val housing = ruleset.housing
+            if (accounts != null || housing != null) {
+                RuleCard(stringResource(R.string.rules_section_accounts)) {
+                    RuleRow(stringResource(R.string.rules_char_slots), accounts?.charSlots?.toString())
+                    RuleRow(stringResource(R.string.rules_per_ip), accounts?.perIp?.toString())
+                    RuleRow(
+                        stringResource(R.string.rules_house_limit),
+                        housing?.accountHouseLimit?.toString(),
+                    )
+                }
+            }
+        }
+        ruleset.vendors?.let { vendors ->
+            item {
+                RuleCard(stringResource(R.string.rules_section_vendors)) {
+                    RuleRow(
+                        stringResource(R.string.rules_restock_delay),
+                        vendors.restockDelayMinutes?.let { stringResource(R.string.rules_minutes, it) },
+                    )
+                    RuleRow(stringResource(R.string.rules_max_sell), vendors.maxSell?.toString())
+                }
+            }
+        }
+        ruleset.schedule?.let { schedule ->
+            item {
+                RuleCard(stringResource(R.string.rules_section_schedule)) {
+                    RuleRow(
+                        stringResource(R.string.rules_autosave),
+                        schedule.autoSaveFrequencyMinutes?.let { stringResource(R.string.rules_minutes, it) },
+                    )
+                    RuleRow(
+                        stringResource(R.string.rules_autorestart),
+                        formatRestart(
+                            schedule.autoRestartEnabled,
+                            schedule.autoRestartHour,
+                            schedule.autoRestartMinute,
+                        ),
+                    )
+                }
+            }
+        }
+    }
+}
+
+@OptIn(ExperimentalLayoutApi::class)
+@Composable
+private fun SystemsCard(systems: Map<String, Boolean>) {
+    RuleCard(stringResource(R.string.rules_section_systems)) {
+        FlowRow(
+            Modifier.padding(top = 6.dp),
+            horizontalArrangement = Arrangement.spacedBy(6.dp),
+            verticalArrangement = Arrangement.spacedBy(6.dp),
+        ) {
+            // Sorted so the list is stable across reloads; the wire order is a config
+            // read order and carries no meaning.
+            systems.entries.sortedBy { it.key }.forEach { (key, on) ->
+                StatusPill(
+                    text = humaniseSystem(key),
+                    tone = if (on) PillTone.Success else PillTone.Neutral,
+                )
+            }
+        }
+    }
+}
+
+@Composable
+private fun CapsCard(caps: RulesetCapsDto) {
+    RuleCard(stringResource(R.string.rules_section_caps)) {
+        // Skill caps arrive in TENTHS (1000 = 100.0). Showing the raw number would read
+        // as a shard with ten times the usual limit.
+        RuleRow(stringResource(R.string.rules_skill_cap), caps.skillCap?.let { formatSkillCap(it) })
+        RuleRow(stringResource(R.string.rules_total_skill_cap), caps.totalSkillCap?.let { formatSkillCap(it) })
+        RuleRow(stringResource(R.string.rules_stat_cap), caps.stat?.toString())
+        RuleRow(stringResource(R.string.rules_str_cap), caps.str?.toString())
+        RuleRow(stringResource(R.string.rules_dex_cap), caps.dex?.toString())
+        RuleRow(stringResource(R.string.rules_int_cap), caps.int?.toString())
+    }
+}
+
+@Composable
+private fun RuleCard(title: String, content: @Composable () -> Unit) {
+    Card(Modifier.fillMaxWidth()) {
+        Column(Modifier.padding(16.dp)) {
+            Text(title, style = MaterialTheme.typography.titleMedium)
+            content()
+        }
+    }
+}
+
+/** One label/value line. Renders nothing when the shard published no value. */
+@Composable
+private fun RuleRow(label: String, value: String?) {
+    if (value.isNullOrBlank()) return
+    Row(
+        Modifier.fillMaxWidth().padding(top = 6.dp),
+        horizontalArrangement = Arrangement.SpaceBetween,
+    ) {
+        Text(label, style = MaterialTheme.typography.bodyMedium, color = MaterialTheme.colorScheme.onSurfaceVariant)
+        Text(value, style = MaterialTheme.typography.bodyMedium)
+    }
+}
+
+// ── Pure helpers (unit-tested) ───────────────────────────────────────────────
+
+/** `cityLoyalty` → "City loyalty". The systems block is a flat bag of config keys. */
+internal fun humaniseSystem(key: String): String = key
+    .replace(Regex("([a-z0-9])([A-Z])"), "$1 $2")
+    .replaceFirstChar { it.uppercaseChar() }
+
+/** A skill cap already converted out of tenths: drop the ".0" on whole values. */
+internal fun formatSkillCap(value: Double): String =
+    if (value % 1.0 == 0.0) value.toInt().toString() else "%.1f".format(value)
+
+/** The auto-restart schedule, or null when the shard doesn't run one. */
+internal fun formatRestart(enabled: Boolean?, hour: Int?, minute: Int?): String? {
+    if (enabled != true) return null
+    if (hour == null) return null
+    return "%02d:%02d".format(hour, minute ?: 0)
+}

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

@@ -0,0 +1,63 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.ui.shard
+
+import androidx.lifecycle.ViewModel
+import androidx.lifecycle.viewModelScope
+import com.runicgateway.app.core.net.ShardStreamEvent
+import com.runicgateway.app.data.api.dto.RulesetDto
+import com.runicgateway.app.data.repository.ShardRepository
+import com.runicgateway.app.ui.UiState
+import com.runicgateway.app.ui.toShardUiState
+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 shard ruleset (PLAN.md §9 M11, `docs/link/v3.md` §5): what this world is
+ * configured to do — systems on/off, caps, account and housing limits, the champion
+ * and Felucca tables, the save/restart schedule.
+ *
+ * Two states the screen must tell apart, which is why the success type is nullable:
+ * a `null` body means the shard has **never published** a ruleset (the plugin is old,
+ * or `RulesetEnabled=false`), while the feature being switched off is a 404 folded
+ * into `ErrorKind.FEATURE_UNAVAILABLE`.
+ *
+ * Kept live by the `world.ruleset` frame, which the shard re-emits on every sidecar
+ * reconnect — so a shard that restarts with edited config updates the open screen.
+ */
+@HiltViewModel
+class RulesViewModel @Inject constructor(
+    private val repository: ShardRepository,
+) : ViewModel() {
+
+    private val _state = MutableStateFlow<UiState<RulesetDto?>>(UiState.Loading)
+    val state: StateFlow<UiState<RulesetDto?>> = _state.asStateFlow()
+
+    init {
+        load()
+        collectLive()
+    }
+
+    fun load() {
+        _state.value = UiState.Loading
+        viewModelScope.launch {
+            _state.value = repository.ruleset().toShardUiState()
+        }
+    }
+
+    private fun collectLive() {
+        viewModelScope.launch {
+            repository.liveEvents().collect { event ->
+                if (event !is ShardStreamEvent.Frame || event.kind != "world.ruleset") return@collect
+                // The frame IS the whole ruleset — replace rather than merge. A frame the
+                // app can't decode is skipped, leaving the loaded copy in place.
+                repository.rulesetFrame(event.data)?.let { _state.value = UiState.Success(it) }
+            }
+        }
+    }
+}

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

@@ -32,12 +32,33 @@ 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.data.repository.ShardFeature
+import com.runicgateway.app.data.repository.ShardFeatures
+import com.runicgateway.app.data.repository.canSee
 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 }
+/**
+ * Board destinations reachable from the hub, each tagged with the visibility feature
+ * that governs it (M11). An admin can switch any of these off or raise its audience,
+ * so the hub's board list is filtered the same way the drawer is — a tile whose
+ * feature the caller can't see would only lead to a `404`/`403`.
+ */
+enum class ShardBoard(val feature: String) {
+    CHAMPS(ShardFeature.CHAMPS),
+    GUILDS(ShardFeature.GUILDS),
+    GOVERNORS(ShardFeature.GOVERNORS),
+    HOUSES(ShardFeature.HOUSES),
+}
+
+/**
+ * The boards this viewer may reach. Pure + side-effect-free so the gating is
+ * unit-tested without Compose, exactly like `visibleEntries` for the drawer. An
+ * unknown answer shows every board — the server gates regardless (see [canSee]).
+ */
+fun visibleBoards(features: ShardFeatures?): List<ShardBoard> =
+    ShardBoard.entries.filter { canSee(features, it.feature) }
 
 /**
  * The Shard hub (PLAN.md §6.2): live connection status, online count + latest
@@ -54,6 +75,7 @@ fun ShardScreen(
     val state by viewModel.state.collectAsStateWithLifecycle()
     val feed by viewModel.feed.collectAsStateWithLifecycle()
     val connected by viewModel.connected.collectAsStateWithLifecycle()
+    val features by viewModel.shardFeatures.collectAsStateWithLifecycle()
 
     when (val s = state) {
         is UiState.Loading -> LoadingView(modifier)
@@ -62,6 +84,7 @@ fun ShardScreen(
             hub = s.data,
             feed = feed,
             connected = connected,
+            features = features,
             onOpenBoard = onOpenBoard,
             modifier = modifier,
         )
@@ -73,6 +96,7 @@ private fun HubContent(
     hub: ShardHub,
     feed: List<FeedLine>,
     connected: Boolean,
+    features: ShardFeatures?,
     onOpenBoard: (ShardBoard) -> Unit,
     modifier: Modifier = Modifier,
 ) {
@@ -82,7 +106,7 @@ private fun HubContent(
         contentPadding = androidx.compose.foundation.layout.PaddingValues(vertical = 16.dp),
     ) {
         item { StatusCard(hub.status, hub.presence?.count) }
-        item { BoardsCard(onOpenBoard) }
+        item { BoardsCard(features, onOpenBoard) }
 
         if (hub.online.isNotEmpty()) {
             item { SectionHeader(stringResource(R.string.shard_section_staff)) }
@@ -159,13 +183,16 @@ private fun StatusCard(status: ShardStatusDto, presenceCount: Int?) {
 }
 
 @Composable
-private fun BoardsCard(onOpenBoard: (ShardBoard) -> Unit) {
-    val boards = listOf(
-        ShardBoard.CHAMPS to R.string.shard_nav_champs,
-        ShardBoard.GUILDS to R.string.shard_nav_guilds,
-        ShardBoard.GOVERNORS to R.string.shard_nav_governors,
-        ShardBoard.HOUSES to R.string.shard_nav_houses,
-    )
+private fun BoardsCard(features: ShardFeatures?, onOpenBoard: (ShardBoard) -> Unit) {
+    val boards = visibleBoards(features).map { board ->
+        board to when (board) {
+            ShardBoard.CHAMPS -> R.string.shard_nav_champs
+            ShardBoard.GUILDS -> R.string.shard_nav_guilds
+            ShardBoard.GOVERNORS -> R.string.shard_nav_governors
+            ShardBoard.HOUSES -> R.string.shard_nav_houses
+        }
+    }
+    if (boards.isEmpty()) return
     Card(Modifier.fillMaxWidth()) {
         Column {
             boards.forEachIndexed { index, (board, labelRes) ->

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

@@ -10,9 +10,11 @@ import com.runicgateway.app.core.result.ApiResult
 import com.runicgateway.app.data.api.dto.OnlineStaffDto
 import com.runicgateway.app.data.api.dto.PresenceDto
 import com.runicgateway.app.data.api.dto.ShardStatusDto
+import com.runicgateway.app.data.repository.ShardFeatures
+import com.runicgateway.app.data.repository.ShardFeaturesRepository
 import com.runicgateway.app.data.repository.ShardRepository
 import com.runicgateway.app.ui.UiState
-import com.runicgateway.app.ui.toUiState
+import com.runicgateway.app.ui.toShardUiState
 import dagger.hilt.android.lifecycle.HiltViewModel
 import kotlinx.coroutines.flow.MutableStateFlow
 import kotlinx.coroutines.flow.StateFlow
@@ -39,11 +41,18 @@ data class ShardHub(
 @HiltViewModel
 class ShardViewModel @Inject constructor(
     private val repository: ShardRepository,
+    shardFeaturesRepository: ShardFeaturesRepository,
 ) : ViewModel() {
 
     private val _state = MutableStateFlow<UiState<ShardHub>>(UiState.Loading)
     val state: StateFlow<UiState<ShardHub>> = _state.asStateFlow()
 
+    /**
+     * Which boards to offer (M11). Read-only here — the app shell refreshes this on
+     * every session change, and the hub only filters its tiles with it.
+     */
+    val shardFeatures: StateFlow<ShardFeatures?> = shardFeaturesRepository.features
+
     private val _feed = MutableStateFlow<List<FeedLine>>(emptyList())
     val feed: StateFlow<List<FeedLine>> = _feed.asStateFlow()
 
@@ -69,8 +78,8 @@ class ShardViewModel @Inject constructor(
                     seedFeed()
                 }
                 // Both error variants are ApiResult<Nothing>, so their UiState is Nothing-typed.
-                is ApiResult.HttpError -> _state.value = status.toUiState()
-                is ApiResult.NetworkError -> _state.value = status.toUiState()
+                is ApiResult.HttpError -> _state.value = status.toShardUiState()
+                is ApiResult.NetworkError -> _state.value = status.toShardUiState()
             }
         }
     }

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

@@ -16,6 +16,7 @@
     <string name="error_not_found">This content couldn\'t be found.</string>
     <string name="error_rate_limited">Too many requests. Please try again in a moment.</string>
     <string name="error_shard_offline">The shard is offline right now.</string>
+    <string name="error_feature_unavailable">This shard doesn\'t publish this here.</string>
     <string name="error_server">Something went wrong on the server. Please try again.</string>
 
     <!-- ── First-run connect (§3) ──────────────────────────────────────── -->
@@ -40,6 +41,10 @@
     <string name="menu_news">News</string>
     <string name="menu_wiki">Wiki</string>
     <string name="menu_shard">Shard</string>
+    <string name="menu_rules">Rules</string>
+    <string name="menu_atlas">Atlas</string>
+    <string name="menu_leaderboards">Leaderboards</string>
+    <string name="menu_market">Market</string>
     <string name="menu_about">About</string>
     <string name="menu_contact">Contact</string>
     <string name="menu_account">My account</string>
@@ -201,6 +206,49 @@
     <string name="account_identity_unlinked">Account unlinked.</string>
     <string name="account_identity_error">Couldn\'t unlink that account.</string>
 
+    <!-- ── Trusted devices & recovery codes (TRUSTED_DEVICES_MFA.md) ─────── -->
+    <!-- Login 2FA step -->
+    <string name="login_recovery_code">Recovery code</string>
+    <string name="login_recovery_hint">Enter one of your single-use backup codes.</string>
+    <string name="login_use_recovery_instead">Use a recovery code instead</string>
+    <string name="login_use_totp_instead">Use your authenticator code instead</string>
+    <string name="login_trust_device">Trust this device (skip codes for 30 days)</string>
+
+    <!-- Account: security section -->
+    <string name="account_security_title">Security</string>
+    <string name="account_security_trusted_devices">Trusted devices</string>
+    <string name="account_security_recovery_codes">Recovery codes</string>
+
+    <!-- Trusted devices screen -->
+    <string name="trusted_devices_title">Trusted devices</string>
+    <string name="trusted_devices_subtitle">These devices can skip the authentication code at sign-in for 30 days.</string>
+    <string name="trusted_devices_empty">No trusted devices yet.</string>
+    <string name="trusted_devices_unknown">Unknown device</string>
+    <string name="trusted_devices_last_used">Last used %1$s</string>
+    <string name="trusted_devices_revoke">Revoke</string>
+    <string name="trusted_devices_trust_this">Trust this device</string>
+    <string name="trusted_devices_untrust_all">Untrust all devices</string>
+    <string name="trusted_devices_trusted">This device is now trusted.</string>
+    <string name="trusted_devices_revoked">Device revoked.</string>
+    <string name="trusted_devices_revoked_all">All devices untrusted.</string>
+    <string name="trusted_devices_limit">You\'ve reached the trusted-device limit. Revoke one, then try again.</string>
+    <string name="trusted_devices_error">Something went wrong. Please try again.</string>
+
+    <!-- Recovery codes screen -->
+    <string name="recovery_codes_title">Recovery codes</string>
+    <string name="recovery_codes_subtitle">Single-use backup codes let you sign in if you lose your authenticator.</string>
+    <string name="recovery_codes_remaining">%1$d codes remaining</string>
+    <string name="recovery_codes_remaining_loading">Checking remaining codes…</string>
+    <string name="recovery_codes_remaining_unknown">Couldn\'t load the remaining count.</string>
+    <string name="recovery_codes_password_hint">Enter your current password to generate a new set.</string>
+    <string name="recovery_codes_regenerate">Generate new codes</string>
+    <string name="recovery_codes_error">Couldn\'t generate codes. Check your password and that two-factor is on.</string>
+    <string name="recovery_codes_new_title">Your new recovery codes</string>
+    <string name="recovery_codes_new_hint">Save these now — they\'re shown only once and each works a single time.</string>
+    <string name="recovery_codes_copy">Copy</string>
+    <string name="recovery_codes_share">Share</string>
+    <string name="recovery_codes_done">Done</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>
@@ -247,6 +295,11 @@
     <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_points">Loyalty &amp; Points</string>
+    <!-- A point system's name followed by the character's rank on that board, e.g. "Queens Loyalty · #3". -->
+    <string name="player_char_points_ranked">%1$s · #%2$d</string>
+    <!-- A score against its cap. Only shown for capped systems; an uncapped score shows the number alone. -->
+    <string name="player_char_points_of">%1$d / %2$d</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>
@@ -333,6 +386,85 @@
     <string name="guilds_leader">Led by %1$s</string>
     <string name="guilds_alliance">Alliance: %1$s</string>
 
+    <!-- ── Rules / ruleset (Protocol 3.0 §5, M11) ──────────────────────── -->
+    <!-- A successful read of a shard that has never published its ruleset — NOT the same
+         as the feature being switched off, which renders as an error state. -->
+    <string name="rules_unpublished">This shard hasn\'t published its ruleset yet.</string>
+    <string name="rules_section_shard">Shard</string>
+    <string name="rules_section_systems">Systems</string>
+    <string name="rules_section_caps">Skill &amp; stat caps</string>
+    <string name="rules_section_accounts">Accounts &amp; housing</string>
+    <string name="rules_section_vendors">Vendors</string>
+    <string name="rules_section_schedule">Saves &amp; restarts</string>
+    <string name="rules_name">Name</string>
+    <string name="rules_expansion">Expansion</string>
+    <string name="rules_connect">Connect</string>
+    <string name="rules_skill_cap">Individual skill cap</string>
+    <string name="rules_total_skill_cap">Total skill cap</string>
+    <string name="rules_stat_cap">Total stat cap</string>
+    <string name="rules_str_cap">Strength cap</string>
+    <string name="rules_dex_cap">Dexterity cap</string>
+    <string name="rules_int_cap">Intelligence cap</string>
+    <string name="rules_char_slots">Character slots</string>
+    <string name="rules_per_ip">Accounts per IP</string>
+    <string name="rules_house_limit">Houses per account</string>
+    <string name="rules_restock_delay">Vendor restock delay</string>
+    <string name="rules_max_sell">Max sell quantity</string>
+    <string name="rules_autosave">Auto-save every</string>
+    <string name="rules_autorestart">Auto-restart at</string>
+    <string name="rules_minutes">%1$d min</string>
+
+    <!-- ── Leaderboards (Protocol 3.0 §7, M11) ─────────────────────────── -->
+    <string name="leaderboards_empty">This shard isn\'t publishing any leaderboards yet.</string>
+    <string name="leaderboards_board_empty">Nobody has scored here yet.</string>
+    <!-- Where a score would sit on the placeholder row of an unscored board. An em
+         dash, not "0" — nobody has scored zero, nobody has scored at all. -->
+    <string name="leaderboards_no_score">—</string>
+    <string name="leaderboards_players">%1$d players</string>
+    <!-- Only shown for capped systems; most systems on a real shard are uncapped. -->
+    <string name="leaderboards_cap">Cap: %1$d</string>
+    <string name="leaderboards_rank_name">#%1$d  %2$s</string>
+    <!-- A shard may publish standings without naming who holds them (the board's one
+         admin-configurable field). -->
+    <string name="leaderboards_hidden_name">Someone</string>
+
+    <!-- ── Market (Protocol 3.0 §8, M11) ───────────────────────────────── -->
+    <string name="market_search_label">Search every shop</string>
+    <string name="market_empty">No listings match that search.</string>
+    <string name="market_shop_empty">This shop has nothing for sale.</string>
+    <!-- Required, not decoration: the shard sweeps vendors round-robin, so a price can
+         legitimately be a full cycle old. -->
+    <string name="market_staleness">Prices are refreshed in rotation and may be out of date.</string>
+    <string name="market_price">%1$d gp</string>
+    <string name="market_unnamed_item">Item %1$d</string>
+    <string name="market_unnamed_shop">A shop</string>
+    <string name="market_owner">Kept by %1$s</string>
+    <!-- A gated location is a real answer: the shop exists, the shard just doesn't say
+         where it stands. -->
+    <string name="market_location_hidden">This shard doesn\'t publish shop locations.</string>
+    <string name="market_truncated">Showing %1$d of %2$d — this shop holds more than the shard publishes.</string>
+
+    <!-- ── Spawn atlas (Protocol 3.0 §6, M11) ──────────────────────────── -->
+    <string name="atlas_search_label">Search creatures</string>
+    <string name="atlas_empty">No creatures match that search.</string>
+    <!-- A place can legitimately hold a single spawner, and the aggregate list is full
+         of them — "1 spawners" on every other row is worth a plural for. -->
+    <plurals name="atlas_spawner_count">
+        <item quantity="one">%1$d spawner</item>
+        <item quantity="other">%1$d spawners</item>
+    </plurals>
+    <string name="atlas_total_alive">Up to %1$d alive at once</string>
+    <string name="atlas_facet_count">%1$s (%2$d)</string>
+    <!-- The aggregate: "where is it", as opposed to the raw coordinates below it. -->
+    <string name="atlas_section_places">Where it spawns</string>
+    <string name="atlas_place_max_alive">up to %1$d at once</string>
+    <string name="atlas_section_spawners">Spawn points</string>
+    <string name="atlas_section_also_here">Also spawns here</string>
+    <string name="atlas_spawners_truncated">More spawn points than shown.</string>
+    <string name="atlas_max_count">Up to %1$d</string>
+    <!-- The delay is already in seconds; the server normalizes XmlSpawner's mixed units. -->
+    <string name="atlas_respawn">Respawn %1$s</string>
+
     <!-- ── Governors (§6.2) ────────────────────────────────────────────── -->
     <string name="governors_empty">No governors — this shard may not run the City Loyalty system.</string>
     <string name="governor_current">Governed by %1$s</string>

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

@@ -7,6 +7,7 @@ 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.auth.TrustTokenStore
 import com.runicgateway.app.core.net.BaseUrlHolder
 import com.runicgateway.app.data.api.SsoApi
 import com.runicgateway.app.data.api.dto.MobileSsoExchangeRequest
@@ -45,6 +46,17 @@ class SsoAuthManagerTest {
         override fun clear() { pending = null }
     }
 
+    /** In-memory stand-in for the encrypted trust-token store, scoped by username
+     *  the same way the production impl is. */
+    private class FakeTrustTokenStore : TrustTokenStore {
+        var owner: String? = null
+        var token: String? = null
+        override fun tokenFor(username: String): String? =
+            if (owner.equals(username, ignoreCase = true)) token else null
+        override fun save(username: String, token: String) { owner = username; this.token = token }
+        override fun clear() { owner = null; token = null }
+    }
+
     /** Records the exchange it was called with and returns a scripted response. */
     private class FakeSsoApi(
         private val exchangeResult: () -> Response<MobileTokenResponse>,
@@ -76,10 +88,11 @@ class SsoAuthManagerTest {
         session: SessionManager,
         base: String? = "https://shard.example.com/",
         store: PendingSsoStore = FakePendingSsoStore(),
+        trust: TrustTokenStore = FakeTrustTokenStore(),
     ): SsoAuthManager {
         val holder = BaseUrlHolder()
         if (base != null) holder.set(base.toHttpUrl())
-        return SsoAuthManager(api, session, holder, store)
+        return SsoAuthManager(api, session, holder, store, trust)
     }
 
     /** Build a start URL and pull the generated `state` back out of it. */
@@ -120,6 +133,38 @@ class SsoAuthManagerTest {
         assertEquals(SsoAuthManager.Outcome.Success, mgr.outcome.value)
     }
 
+    // Trusted devices over SSO (TRUSTED_DEVICES_MFA.md). Ticking "trust this device"
+    // on the TOTP form inside the Custom Tab trusts that browser via cookie; the
+    // exchange additionally hands the APP its own token so a native password login
+    // on this device skips the code too. Before this, SSO ignored trust entirely.
+    @Test fun `a trustToken on the exchange response is persisted for the signed-in user`() = runTest {
+        val api = FakeSsoApi { Response.success(tokenPair().copy(trustToken = "opaque-trust")) }
+        val session = SessionManager(FakeTokenStore())
+        val trust = FakeTrustTokenStore()
+        val mgr = managerWith(api, session, trust = trust)
+
+        val state = startAndState(mgr)
+        mgr.complete(state = state, code = "auth-code-1", error = null)
+
+        assertEquals(SsoAuthManager.Outcome.Success, mgr.outcome.value)
+        assertEquals("opaque-trust", trust.tokenFor("alice"))
+        // Scoped to the account that minted it — never replayed for someone else.
+        assertNull(trust.tokenFor("mallory"))
+    }
+
+    @Test fun `no trustToken on the response leaves the store untouched`() = runTest {
+        val api = FakeSsoApi { Response.success(tokenPair()) }
+        val session = SessionManager(FakeTokenStore())
+        val trust = FakeTrustTokenStore()
+        val mgr = managerWith(api, session, trust = trust)
+
+        val state = startAndState(mgr)
+        mgr.complete(state = state, code = "auth-code-1", error = null)
+
+        assertEquals(SsoAuthManager.Outcome.Success, mgr.outcome.value)
+        assertNull(trust.tokenFor("alice"))
+    }
+
     @Test fun `state mismatch fails without exchanging`() = runTest {
         val api = FakeSsoApi { Response.success(tokenPair()) }
         val session = SessionManager(FakeTokenStore())

app/src/test/java/com/runicgateway/app/core/result/ApiResultExtrasTest.kt

@@ -0,0 +1,41 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.core.result
+
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertSame
+import org.junit.Assert.assertTrue
+import org.junit.Test
+
+/**
+ * The [ApiResult] helpers: [map] transforms an [ApiResult.Ok] and passes the two
+ * failure variants through unchanged; [isShardUnavailable] is the 503 "shard down"
+ * signal the player screens render as offline.
+ */
+class ApiResultExtrasTest {
+
+    @Test fun mapTransformsOkBody() {
+        val mapped = ApiResult.Ok(listOf(1, 2, 3)).map { it.size }
+        assertEquals(ApiResult.Ok(3), mapped)
+    }
+
+    @Test fun mapPassesFailuresThroughUnchanged() {
+        val http: ApiResult<Int> = ApiResult.HttpError(500, "boom")
+        assertSame(http, http.map { it + 1 })
+
+        val cause = RuntimeException("offline")
+        val network: ApiResult<Int> = ApiResult.NetworkError(cause)
+        val out = network.map { it + 1 }
+        assertTrue(out is ApiResult.NetworkError)
+        assertSame(cause, (out as ApiResult.NetworkError).cause)
+    }
+
+    @Test fun isShardUnavailableOnlyForHttp503() {
+        assertTrue(ApiResult.HttpError(503).isShardUnavailable())
+        assertFalse(ApiResult.HttpError(500).isShardUnavailable())
+        assertFalse(ApiResult.Ok(Unit).isShardUnavailable())
+        assertFalse(ApiResult.NetworkError(RuntimeException()).isShardUnavailable())
+    }
+}

app/src/test/java/com/runicgateway/app/core/result/ApiResultTest.kt

@@ -35,6 +35,20 @@ class ApiResultTest {
         assertTrue(result is ApiResult.NetworkError)
     }
 
+    /**
+     * A body the app can't decode (a field whose type doesn't match its DTO) throws a
+     * [SerializationException] out of the Retrofit converter. It must degrade to a
+     * server-side error the UI renders, not escape and crash the app — the guild-board
+     * crash this fixes. `502` folds to [ui.ErrorKind.SERVER] via `toUiState`.
+     */
+    @Test fun serializationExceptionBecomesServerError() = runTest {
+        val result = safeApiCall {
+            throw kotlinx.serialization.SerializationException("Unexpected symbol 'm' at path: \$[0].members")
+        }
+        assertTrue(result is ApiResult.HttpError)
+        assertEquals(502, (result as ApiResult.HttpError).status)
+    }
+
     @Test fun cancellationIsRethrown() = runTest {
         assertThrows(CancellationException::class.java) {
             kotlinx.coroutines.runBlocking {

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

@@ -54,6 +54,66 @@ class AccountDtoTest {
         assertTrue(json.decodeFromString<TotpStateDto>("""{"totp_enabled":true}""").totp_enabled)
     }
 
+    @Test fun totpEnableCarriesOneTimeRecoveryCodes() {
+        // Enabling 2FA now returns the fresh single-use batch once (TRUSTED_DEVICES_MFA.md).
+        val dto = json.decodeFromString<TotpStateDto>(
+            """{"totp_enabled":true,"recoveryCodes":["aaaa-1111","bbbb-2222"]}""",
+        )
+        assertTrue(dto.totp_enabled)
+        assertEquals(listOf("aaaa-1111", "bbbb-2222"), dto.recoveryCodes)
+    }
+
+    @Test fun totpStateDisableHasNoRecoveryCodes() {
+        // Disable (and older backends) omit the field — must decode to null, not crash.
+        val dto = json.decodeFromString<TotpStateDto>("""{"totp_enabled":false}""")
+        assertFalse(dto.totp_enabled)
+        assertEquals(null, dto.recoveryCodes)
+    }
+
+    @Test fun trustedDeviceDecodes() {
+        val dto = json.decodeFromString<TrustedDeviceDto>(
+            """{"id":5,"platform":"mobile","deviceName":"Pixel 8","userAgent":"RunicGatewayApp/1.0",
+               "createdAt":"2026-07-20T10:00:00Z","lastUsedAt":"2026-07-22T09:00:00Z",
+               "expiresAt":"2026-08-19T10:00:00Z"}""",
+        )
+        assertEquals(5L, dto.id)
+        assertEquals("mobile", dto.platform)
+        assertEquals("Pixel 8", dto.deviceName)
+        assertEquals("2026-07-22T09:00:00Z", dto.lastUsedAt)
+    }
+
+    @Test fun trustDeviceResultCarriesNativeToken() {
+        val dto = json.decodeFromString<TrustDeviceResultDto>(
+            """{"trusted":true,"trustToken":"opaque-token-abc"}""",
+        )
+        assertTrue(dto.trusted)
+        assertEquals("opaque-token-abc", dto.trustToken)
+    }
+
+    @Test fun trustedDeviceLimitDecodesDevices() {
+        val dto = json.decodeFromString<TrustedDeviceLimitDto>(
+            """{"error":"trusted_device_limit","devices":[
+                 {"id":1,"platform":"web","deviceName":"Firefox"},
+                 {"id":2,"platform":"mobile","deviceName":"Pixel"}]}""",
+        )
+        assertEquals("trusted_device_limit", dto.error)
+        assertEquals(2, dto.devices.size)
+        assertEquals(2L, dto.devices[1].id)
+    }
+
+    @Test fun recoveryStatusAndCodesDecode() {
+        assertEquals(7, json.decodeFromString<RecoveryStatusDto>("""{"remaining":7}""").remaining)
+        val codes = json.decodeFromString<RecoveryCodesDto>(
+            """{"recoveryCodes":["c1","c2","c3"]}""",
+        )
+        assertEquals(3, codes.recoveryCodes.size)
+    }
+
+    @Test fun revokedResultsDecode() {
+        assertTrue(json.decodeFromString<RevokedFlagDto>("""{"revoked":true}""").revoked)
+        assertEquals(4, json.decodeFromString<RevokedCountDto>("""{"revoked":4}""").revoked)
+    }
+
     @Test fun linkedIdentityDecodes() {
         val dto = json.decodeFromString<LinkedIdentityDto>(
             """{"provider":"discord","email":"u@example.com","linked_at":"2026-07-19T22:00:00Z"}""",

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

@@ -0,0 +1,127 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.data.api.dto
+
+import kotlinx.serialization.encodeToString
+import kotlinx.serialization.json.Json
+import kotlinx.serialization.json.int
+import kotlinx.serialization.json.jsonObject
+import kotlinx.serialization.json.jsonPrimitive
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertNull
+import org.junit.Assert.assertTrue
+import org.junit.Test
+
+/**
+ * Decode/encode tests for the staff-operations DTOs (`/admin/…`, PLAN.md §6.4).
+ * Covers the snake_case `@SerialName` mappings, the `AdminPostDto.isPublished`
+ * tinyint bridge, nested dashboard shapes, and the request bodies the app encodes.
+ */
+class AdminDtoTest {
+
+    private val json = Json {
+        ignoreUnknownKeys = true
+        explicitNulls = false
+        coerceInputValues = true
+    }
+
+    @Test fun dashboardDecodesNestedCountsAndActivity() {
+        val dto = json.decodeFromString<AdminDashboardDto>(
+            """{
+                "site_mode":"maintenance",
+                "last_change":{"at":"2026-07-20T10:00:00Z","by":"admin"},
+                "counts":{"posts":{"news":4,"newsletter":1},"users":37},
+                "recent_activity":[
+                    {"id":9,"username":"mod","action":"post.publish",
+                     "detail":{"postId":12},"created_at":"2026-07-22T09:00:00Z"}
+                ]
+            }""",
+        )
+        assertEquals("maintenance", dto.siteMode)
+        assertEquals("admin", dto.lastChange.by)
+        assertEquals(4, dto.counts.posts["news"])
+        assertEquals(37, dto.counts.users)
+        assertEquals(1, dto.recentActivity.size)
+        assertEquals("post.publish", dto.recentActivity[0].action)
+        // `detail` is provider-shaped JSON kept as a raw element.
+        assertEquals(12, dto.recentActivity[0].detail!!.jsonObject["postId"]!!.jsonPrimitive.int)
+    }
+
+    @Test fun dashboardDefaultsWhenKeysAbsent() {
+        val dto = json.decodeFromString<AdminDashboardDto>("{}")
+        assertEquals("live", dto.siteMode)
+        assertTrue(dto.counts.posts.isEmpty())
+        assertTrue(dto.recentActivity.isEmpty())
+    }
+
+    @Test fun adminPostBridgesPublishedTinyintToBoolean() {
+        val published = json.decodeFromString<AdminPostDto>(
+            """{"id":1,"category":"news","title":"Hi","published":1,"published_at":"2026-07-21T00:00:00Z"}""",
+        )
+        assertTrue(published.isPublished)
+        assertEquals("2026-07-21T00:00:00Z", published.publishedAt)
+
+        val draft = json.decodeFromString<AdminPostDto>("""{"id":2,"title":"Draft","published":0}""")
+        assertFalse(draft.isPublished)
+    }
+
+    @Test fun adminWikiCategoryAndTagDecodeCounts() {
+        val cat = json.decodeFromString<AdminWikiCategoryDto>(
+            """{"id":3,"slug":"lore","title":"Lore","sort_order":2,"page_count":5,"published_count":4}""",
+        )
+        assertEquals(2, cat.sortOrder)
+        assertEquals(5, cat.pageCount)
+        assertEquals(4, cat.publishedCount)
+
+        val tag = json.decodeFromString<AdminWikiTagDto>("""{"id":8,"slug":"pvp","label":"PvP","published_count":11}""")
+        assertEquals("PvP", tag.label)
+        assertEquals(11, tag.publishedCount)
+    }
+
+    @Test fun supportPageDecodesSenderActor() {
+        val dto = json.decodeFromString<SupportPageDto>(
+            """{"pageId":"0x1A2B","type":"other","message":"stuck",
+                "handled":false,"sender":{"name":"Gwen","account":"gwen01"}}""",
+        )
+        assertEquals("0x1A2B", dto.pageId)
+        assertEquals("Gwen", dto.sender?.name)
+        assertEquals("gwen01", dto.sender?.account)
+        assertEquals(false, dto.handled)
+    }
+
+    @Test fun supportPageToleratesMissingSender() {
+        val dto = json.decodeFromString<SupportPageDto>("""{"pageId":"0x01"}""")
+        assertNull(dto.sender)
+        assertNull(dto.type)
+    }
+
+    @Test fun siteModeStateDecodesAudit() {
+        val dto = json.decodeFromString<SiteModeStateDto>(
+            """{"site_mode":"maintenance","changed_at":"2026-07-22T08:00:00Z","changed_by":"admin"}""",
+        )
+        assertEquals("maintenance", dto.siteMode)
+        assertEquals("admin", dto.changedBy)
+    }
+
+    @Test fun requestBodiesEncodeWithSnakeCaseKeys() {
+        assertTrue(json.encodeToString(SiteModeRequest("maintenance")).contains("\"mode\":\"maintenance\""))
+        assertTrue(json.encodeToString(PublishRequest(true)).contains("\"published\":true"))
+        assertTrue(json.encodeToString(UnbanRequest("gwen01")).contains("\"account\":\"gwen01\""))
+        assertTrue(json.encodeToString(BroadcastRequest("hello", hue = 33)).contains("\"hue\":33"))
+        assertTrue(json.encodeToString(PageRespondRequest("done", close = true)).contains("\"close\":true"))
+        assertTrue(json.encodeToString(WikiCategoryRequest(slug = "lore", title = "Lore", sortOrder = 1))
+            .contains("\"sort_order\":1"))
+
+        val post = json.encodeToString(PostCreateRequest(category = "news", title = "T", imageUrl = "/img.png"))
+        assertTrue(post.contains("\"image_url\":\"/img.png\""))
+        assertTrue(post.contains("\"category\":\"news\""))
+
+        val ban = json.encodeToString(BanRequest(account = "x", durationSec = 3600, reason = "afk"))
+        assertTrue(ban.contains("\"durationSec\":3600"))
+
+        val kick = json.encodeToString(KickRequest(serial = "0xFF"))
+        assertTrue(kick.contains("\"serial\":\"0xFF\""))
+    }
+}

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

@@ -68,4 +68,35 @@ class AuthDtoTest {
         assertNull(dto.expiresIn)
         assertEquals("admin", dto.user.role)
     }
+
+    @Test fun loginCarriesTrustTokenWhenDeviceTrusted() {
+        // trustDevice accepted → an opaque token to persist + replay (TRUSTED_DEVICES_MFA.md).
+        val dto = json.decodeFromString<MobileTokenResponse>(
+            """{"accessToken":"a","refreshToken":"r","user":{"id":3,"username":"c","role":"player"},
+               "trustToken":"opaque-abc"}""",
+        )
+        assertEquals("opaque-abc", dto.trustToken)
+        assertFalse(dto.trustLimitReached)
+    }
+
+    @Test fun loginSignalsTrustLimitWithDevices() {
+        // At the cap: login still succeeds, but no token; the device list is returned.
+        val dto = json.decodeFromString<MobileTokenResponse>(
+            """{"accessToken":"a","refreshToken":"r","user":{"id":3,"username":"c","role":"player"},
+               "trustLimitReached":true,"devices":[{"id":1,"platform":"mobile","deviceName":"Old"}]}""",
+        )
+        assertNull(dto.trustToken)
+        assertTrue(dto.trustLimitReached)
+        assertEquals(1, dto.devices.size)
+    }
+
+    @Test fun loginWithoutTrustFieldsDefaultsCleanly() {
+        // A normal (no-trust) login omits every trust field — must not crash or mis-flag.
+        val dto = json.decodeFromString<MobileTokenResponse>(
+            """{"accessToken":"a","refreshToken":"r","user":{"id":4,"username":"d","role":"player"}}""",
+        )
+        assertNull(dto.trustToken)
+        assertFalse(dto.trustLimitReached)
+        assertTrue(dto.devices.isEmpty())
+    }
 }

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

@@ -0,0 +1,68 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.data.api.dto
+
+import kotlinx.serialization.encodeToString
+import kotlinx.serialization.json.Json
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertTrue
+import org.junit.Test
+
+/**
+ * Encode/decode tests for the mobile bearer-auth request bodies (`/auth/mobile/…`)
+ * and the token pair — the snake_case `device_name`, the omit-nulls behaviour, and
+ * the trusted-device outcome fields on the login response.
+ */
+class AuthRequestDtoTest {
+
+    private val json = Json {
+        ignoreUnknownKeys = true
+        explicitNulls = false
+        coerceInputValues = true
+    }
+
+    @Test fun loginRequestEncodesSnakeCaseDeviceNameAndOmitsNulls() {
+        val body = json.encodeToString(
+            MobileLoginRequest(username = "gwen", password = "pw", trustDevice = true, device_name = "Pixel 8"),
+        )
+        assertTrue(body.contains("\"username\":\"gwen\""))
+        assertTrue(body.contains("\"device_name\":\"Pixel 8\""))
+        assertTrue(body.contains("\"trustDevice\":true"))
+        assertFalse(body.contains("\"code\"")) // null omitted (explicitNulls = false)
+    }
+
+    @Test fun loginRequestCarriesSecondFactorOnRetry() {
+        val withCode = json.encodeToString(MobileLoginRequest("u", "p", code = "123456"))
+        assertTrue(withCode.contains("\"code\":\"123456\""))
+        val withRecovery = json.encodeToString(MobileLoginRequest("u", "p", recoveryCode = "aaaa-1111"))
+        assertTrue(withRecovery.contains("\"recoveryCode\":\"aaaa-1111\""))
+    }
+
+    @Test fun refreshAndLogoutBodiesEncode() {
+        assertTrue(json.encodeToString(MobileRefreshRequest("rt")).contains("\"refreshToken\":\"rt\""))
+        assertTrue(json.encodeToString(MobileLogoutRequest(all = true)).contains("\"all\":true"))
+    }
+
+    @Test fun tokenResponseDecodesTrustOutcome() {
+        val dto = json.decodeFromString<MobileTokenResponse>(
+            """{"accessToken":"a","refreshToken":"r","expiresIn":"15m",
+                "user":{"id":1,"username":"gwen","role":"player"},
+                "trustToken":"opaque"}""",
+        )
+        assertEquals("a", dto.accessToken)
+        assertEquals("opaque", dto.trustToken)
+        assertFalse(dto.trustLimitReached)
+        assertEquals("gwen", dto.user.username)
+    }
+
+    @Test fun tokenResponseDecodesTrustLimitReached() {
+        val dto = json.decodeFromString<MobileTokenResponse>(
+            """{"accessToken":"a","refreshToken":"r","user":{"id":1,"username":"g","role":"player"},
+                "trustLimitReached":true,"devices":[{"id":1,"platform":"web","deviceName":"FF"}]}""",
+        )
+        assertTrue(dto.trustLimitReached)
+        assertEquals(1, dto.devices.size)
+    }
+}

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

@@ -0,0 +1,82 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.data.api.dto
+
+import kotlinx.serialization.encodeToString
+import kotlinx.serialization.json.Json
+import kotlinx.serialization.json.jsonPrimitive
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertNull
+import org.junit.Assert.assertTrue
+import org.junit.Test
+
+/**
+ * Decode tests for the news post + CMS page + contact DTOs (`/public/posts…`,
+ * `/public/pages/:slug`, `/public/contact`). One [PostDto] shape serves both the
+ * list (no body) and detail (with body); a [PageDto] keeps block props as raw JSON.
+ */
+class ContentDtoTest {
+
+    private val json = Json {
+        ignoreUnknownKeys = true
+        explicitNulls = false
+        coerceInputValues = true
+    }
+
+    @Test fun postDetailDecodesBodyAndImage() {
+        val dto = json.decodeFromString<PostDto>(
+            """{"id":10,"category":"news","title":"Update","slug":"update",
+                "excerpt":"e","body":"<p>full</p>","image_url":"/i.png",
+                "published_at":"2026-07-21T00:00:00Z","created_at":"2026-07-20T00:00:00Z"}""",
+        )
+        assertEquals(10L, dto.id)
+        assertEquals("<p>full</p>", dto.body)
+        assertEquals("/i.png", dto.imageUrl)
+        assertEquals("2026-07-21T00:00:00Z", dto.publishedAt)
+    }
+
+    @Test fun postListRowToleratesMissingBody() {
+        val dto = json.decodeFromString<PostDto>("""{"id":11,"category":"newsletter","title":"N"}""")
+        assertNull(dto.body)
+        assertNull(dto.imageUrl)
+    }
+
+    @Test fun pageDecodesBlocksWithRawProps() {
+        val dto = json.decodeFromString<PageDto>(
+            """{
+                "id":3,"slug":"about","title":"About","status":"published",
+                "blocks":[
+                    {"type":"heading","props":{"text":"Welcome","level":1},"visible":true},
+                    {"type":"divider","props":{}}
+                ],
+                "publishedAt":"2026-07-01T00:00:00Z"
+            }""",
+        )
+        assertEquals("about", dto.slug)
+        assertEquals(2, dto.blocks.size)
+        assertEquals("heading", dto.blocks[0].type)
+        // props stay a raw JSON object the renderer reads by key.
+        assertEquals("Welcome", dto.blocks[0].props["text"]!!.jsonPrimitive.content)
+        assertTrue(dto.blocks[1].visible) // default true when absent
+    }
+
+    @Test fun contactResponseSentAndFallbackVariants() {
+        val sent = json.decodeFromString<ContactResponse>("""{"sent":true}""")
+        assertTrue(sent.sent)
+        assertNull(sent.fallback)
+
+        val fallback = json.decodeFromString<ContactResponse>(
+            """{"sent":false,"fallback":"mailto","email":"a@b.c"}""",
+        )
+        assertEquals("mailto", fallback.fallback)
+        assertEquals("a@b.c", fallback.email)
+    }
+
+    @Test fun contactRequestEncodesAllFields() {
+        val body = json.encodeToString(ContactRequest(name = "Gwen", email = "g@x.c", message = "hi"))
+        assertTrue(body.contains("\"name\":\"Gwen\""))
+        assertTrue(body.contains("\"email\":\"g@x.c\""))
+        assertTrue(body.contains("\"message\":\"hi\""))
+    }
+}

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

@@ -3,6 +3,7 @@
  */
 package com.runicgateway.app.data.api.dto
 
+import kotlinx.serialization.encodeToString
 import kotlinx.serialization.json.Json
 import org.junit.Assert.assertEquals
 import org.junit.Assert.assertFalse
@@ -58,6 +59,15 @@ class NotificationsDtoTest {
         assertEquals(listOf("news.post", "champ.start"), dto.streams)
     }
 
+    @Test fun emptySubscriptionsStillSerializeStreamsField() {
+        // Regression: clearing the LAST subscription sends an empty set. The backend
+        // validator requires `streams`, so it must be present as `[]`, not omitted.
+        // Uses the production Json config (no encodeDefaults) to prove the field is
+        // always emitted because the DTO field has no default.
+        val body = json.encodeToString(NotificationSubscriptionsDto(emptyList()))
+        assertEquals("""{"streams":[]}""", body)
+    }
+
     @Test fun settingsPushBlockDecodes() {
         val dto = json.decodeFromString<SettingsDto>(
             """{"site_title":"Shard","brand":{"name":"Shard"},"push":{"ntfyUrl":"https://ntfy.shard.tld"}}""",

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

@@ -0,0 +1,115 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.data.api.dto
+
+import kotlinx.serialization.encodeToString
+import kotlinx.serialization.json.Json
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertTrue
+import org.junit.Test
+
+/**
+ * Decode/encode tests for the player self-service game-data DTOs
+ * (`/player/shard/…`): account linking, roster, the full character sheet, vendors,
+ * sales, and own-houses. Only the fields the text-only v1 renders are asserted.
+ */
+class PlayerGameDataDtoTest {
+
+    private val json = Json {
+        ignoreUnknownKeys = true
+        explicitNulls = false
+        coerceInputValues = true
+    }
+
+    @Test fun linkRequestAndResultRoundTrip() {
+        assertTrue(json.encodeToString(ShardLinkRequest("ABC123")).contains("\"code\":\"ABC123\""))
+        val result = json.decodeFromString<ShardLinkResultDto>("""{"linked":true,"account":"acct1"}""")
+        assertTrue(result.linked)
+        assertEquals("acct1", result.account)
+        assertTrue(json.encodeToString(CreateGameAccountRequest("acct1", "pw")).contains("\"account\":\"acct1\""))
+    }
+
+    @Test fun linkedAccountDecodes() {
+        val dto = json.decodeFromString<ShardLinkDto>(
+            """{"account":"acct1","userId":42,"charName":"Gwen","linkedAt":"2026-07-20T00:00:00Z"}""",
+        )
+        assertEquals("acct1", dto.account)
+        assertEquals(42L, dto.userId)
+    }
+
+    @Test fun rosterDecodesCharacters() {
+        val dto = json.decodeFromString<RosterDto>(
+            """{"acct":"acct1","chars":[
+                {"slot":0,"serial":"0x24C","name":"Gwen","body":401,"online":true},
+                {"slot":1,"serial":"0x24D","name":"Alt","online":false}]}""",
+        )
+        assertEquals(2, dto.chars.size)
+        assertTrue(dto.chars[0].online)
+        assertEquals("0x24C", dto.chars[0].serial)
+    }
+
+    @Test fun charSheetDecodesStatsSkillsEquipmentTitlesGuild() {
+        val dto = json.decodeFromString<CharProfileDto>(
+            """{
+                "serial":"0x24C","name":"Gwen","title":"the Brave","online":true,"acct":"acct1",
+                "stats":{"str":100,"dex":90,"int":80,"hits":95,"hitsMax":100,
+                         "resist":{"phys":70,"fire":50,"cold":45,"pois":40,"energy":35}},
+                "skills":[{"n":"Swords","base":100.0,"value":110.0,"cap":120.0}],
+                "equipment":[{"serial":"0x9","layer":"OneHanded","itemId":5044,"hue":0}],
+                "titles":{"selected":0,"reward":["1049643"],"fameKarma":"Glorious"},
+                "guild":{"name":"Knights","abbr":"KoT"},
+                "governorOf":["Britain"]
+            }""",
+        )
+        assertEquals("Gwen", dto.name)
+        assertEquals(100, dto.stats!!.str)
+        assertEquals(70, dto.stats!!.resist!!.phys)
+        assertEquals(110.0, dto.skills.first().value!!, 0.0)
+        assertEquals("OneHanded", dto.equipment.first().layer)
+        assertEquals("Glorious", dto.titles!!.fameKarma)
+        assertEquals("Knights", dto.guild!!.name)
+        assertEquals(listOf("Britain"), dto.governorOf)
+    }
+
+    @Test fun charSheetToleratesMinimalPayload() {
+        val dto = json.decodeFromString<CharProfileDto>("""{"serial":"0x1","name":"Bare"}""")
+        assertEquals(null, dto.stats)
+        assertTrue(dto.skills.isEmpty())
+        assertTrue(dto.equipment.isEmpty())
+        assertFalse(dto.online)
+    }
+
+    @Test fun vendorSnapshotAndListingsDecode() {
+        val dto = json.decodeFromString<VendorSnapshotDto>(
+            """{"acct":"acct1","vendors":[
+                {"serial":"0x9","shopName":"Wares","holdGold":5000,"map":"Felucca","x":1,"y":2,
+                 "listings":[{"serial":"0xA","itemId":3862,"amount":5,"price":250,"forSale":true}]}]}""",
+        )
+        val vendor = dto.vendors.first()
+        assertEquals("Wares", vendor.shopName)
+        assertEquals(5000L, vendor.holdGold)
+        val listing = vendor.listings.first()
+        assertEquals(250L, listing.price)
+        assertTrue(listing.forSale)
+    }
+
+    @Test fun vendorSaleDecodes() {
+        val dto = json.decodeFromString<VendorSaleDto>(
+            """{"t":1700000000000,"itemType":"katana","amount":1,"price":1000,"commission":50,"ownerAcct":"acct1"}""",
+        )
+        assertEquals(1000L, dto.price)
+        assertEquals(50, dto.commission)
+    }
+
+    @Test fun playerHouseDecodesDecayFields() {
+        val dto = json.decodeFromString<PlayerHouseDto>(
+            """{"serial":"0x40001","stage":"LikeNew","region":"Britain","name":"Keep",
+                "isIdoc":false,"builtOn":"2026-01-01T00:00:00Z","lastRefreshed":"2026-07-22T00:00:00Z"}""",
+        )
+        assertEquals("LikeNew", dto.stage)
+        assertEquals("Keep", dto.name)
+        assertFalse(dto.isIdoc)
+    }
+}

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

@@ -7,6 +7,7 @@ import kotlinx.serialization.json.Json
 import kotlinx.serialization.json.jsonPrimitive
 import org.junit.Assert.assertEquals
 import org.junit.Assert.assertNotNull
+import org.junit.Assert.assertNull
 import org.junit.Assert.assertTrue
 import org.junit.Test
 
@@ -99,4 +100,57 @@ class PlayerShardDtoTest {
         assertTrue(dto.linked)
         assertEquals("whitlocktech", dto.account)
     }
+
+    // ── Protocol 3.0 additions to char.profile ───────────────────────────
+
+    @Test fun charProfileDecodesThePointsBlock() {
+        // Shaped like a real shard's reply: an uncapped board (maxPoints 0), a
+        // cliloc-named board (nameString null), and no `rank` unless opted in.
+        val dto = json.decodeFromString<CharProfileDto>(
+            """{"serial":"0x24C","name":"Darrow",
+               "points":[{"system":"QueensLoyalty","nameString":"Queen's Loyalty",
+                          "points":29500,"maxPoints":30000,"rank":3},
+                         {"system":"VoidPool","nameString":null,"points":180,"maxPoints":0}]}""",
+        )
+        assertEquals(2, dto.points.size)
+        val queens = dto.points[0]
+        assertEquals("Queen's Loyalty", queens.nameString)
+        assertEquals(29500L, queens.points)
+        assertEquals(30000L, queens.cap)
+        assertEquals(3, queens.rank)
+
+        val voidPool = dto.points[1]
+        assertNull("maxPoints 0 means uncapped, not a zero cap", voidPool.cap)
+        assertNull("rank is absent unless the shard opts in", voidPool.rank)
+        assertNull(voidPool.nameString)
+    }
+
+    @Test fun charProfileWithoutAPointsBlockDecodesToEmpty() {
+        // A shard plugin that predates Protocol 3.0 sends no `points` key at all.
+        val dto = json.decodeFromString<CharProfileDto>("""{"serial":"0x24C","name":"Darrow"}""")
+        assertEquals(emptyList<CharPointsDto>(), dto.points)
+    }
+
+    @Test fun equipmentDecodesTheServerResolvedClilocName() {
+        val dto = json.decodeFromString<CharProfileDto>(
+            """{"serial":"0x24C",
+               "equipment":[{"serial":"0x40","layer":"OneHanded","itemId":5040,"cliloc":1023721,
+                             "clilocName":"hatchet"},
+                            {"serial":"0x41","layer":"Shirt","name":"Bob's lucky shirt",
+                             "clilocName":"fancy shirt"}]}""",
+        )
+        assertEquals("hatchet", dto.equipment[0].label)
+        assertEquals("Bob's lucky shirt", dto.equipment[1].label)
+    }
+
+    @Test fun titlesDecodeTheParallelResolvedArrayIncludingItsNulls() {
+        // rewardResolved carries a null where the cliloc table had nothing; the array
+        // must stay positionally aligned with `reward`.
+        val dto = json.decodeFromString<TitlesDto>(
+            """{"selected":1,"reward":["1049565","1049566"],
+               "rewardResolved":[null,"Knight of Trinsic"]}""",
+        )
+        assertEquals(listOf("1049565", "1049566"), dto.reward)
+        assertEquals(listOf(null, "Knight of Trinsic"), dto.rewardResolved)
+    }
 }

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

@@ -0,0 +1,73 @@
+/*
+ * 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
+
+/**
+ * Decode tests for the public site/identity DTOs (`/public/status`,
+ * `/public/settings`). Covers the `StatusDto.isMaintenance` derivation, nested
+ * branding/registration/push blocks, and the additive-field tolerance.
+ */
+class PublicDtoTest {
+
+    private val json = Json {
+        ignoreUnknownKeys = true
+        explicitNulls = false
+        coerceInputValues = true
+    }
+
+    @Test fun statusDecodesVersionAndMaintenanceFlag() {
+        val dto = json.decodeFromString<StatusDto>(
+            """{"mode":"MAINTENANCE","status_message":"back soon",
+                "version":{"service":"web","api":"v1","server":"1.2.3"}}""",
+        )
+        assertTrue(dto.isMaintenance) // case-insensitive
+        assertEquals("back soon", dto.statusMessage)
+        assertEquals("1.2.3", dto.version.server)
+    }
+
+    @Test fun liveStatusIsNotMaintenance() {
+        assertFalse(json.decodeFromString<StatusDto>("""{"mode":"live"}""").isMaintenance)
+    }
+
+    @Test fun statusDefaultsWhenEmpty() {
+        val dto = json.decodeFromString<StatusDto>("{}")
+        assertEquals("live", dto.mode)
+        assertFalse(dto.isMaintenance)
+        assertEquals("", dto.version.api)
+    }
+
+    @Test fun settingsDecodesBrandRegistrationAndPush() {
+        val dto = json.decodeFromString<SettingsDto>(
+            """{
+                "site_title":"UOMysticmoon","status_message":"welcome",
+                "registration":{"password":true,"sso":false},
+                "gameAccountSignup":true,
+                "brand":{"name":"UOMysticmoon","shortName":"UOM","accent":"#7f99bd",
+                         "logo":"/logo.png","hero":"/hero.png","contactEmail":"a@b.c","url":"https://x"},
+                "push":{"ntfyUrl":"https://ntfy.example.com"}
+            }""",
+        )
+        assertEquals("UOMysticmoon", dto.siteTitle)
+        assertTrue(dto.registration.password)
+        assertFalse(dto.registration.sso)
+        assertTrue(dto.gameAccountSignup)
+        assertEquals("#7f99bd", dto.brand.accent)
+        assertEquals("/logo.png", dto.brand.logo)
+        assertEquals("https://ntfy.example.com", dto.push.ntfyUrl)
+    }
+
+    @Test fun settingsDefaultsOnOlderBackend() {
+        // A backend that predates push/branding: nested blocks fall back to defaults.
+        val dto = json.decodeFromString<SettingsDto>("""{"site_title":"Bare"}""")
+        assertFalse(dto.registration.password)
+        assertEquals("", dto.brand.name)
+        assertEquals(null, dto.push.ntfyUrl)
+    }
+}

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

@@ -0,0 +1,104 @@
+/*
+ * 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
+
+/**
+ * Decode tests for the public shard board DTOs (`/public/shard/…`), covering the
+ * computed helpers ([ActorDto.label], [ShardStatusDto.isOnline]) and the
+ * permissive board payloads (champ/guild/governor/house/presence).
+ */
+class ShardBoardDtoTest {
+
+    private val json = Json {
+        ignoreUnknownKeys = true
+        explicitNulls = false
+        coerceInputValues = true
+    }
+
+    @Test fun actorLabelPrefersNameThenAcctThenFallback() {
+        assertEquals("Gwen", json.decodeFromString<ActorDto>("""{"name":"Gwen","acct":"g01"}""").label)
+        assertEquals("g01", json.decodeFromString<ActorDto>("""{"acct":"g01"}""").label)
+        assertEquals("Someone", json.decodeFromString<ActorDto>("{}").label)
+    }
+
+    @Test fun shardStatusIsOnlineOnlyWhenEnabledAndPluginConnected() {
+        val online = json.decodeFromString<ShardStatusDto>(
+            """{"enabled":true,"pluginConnected":true,"onlineCount":42,
+                "economy":{"accounts":10,"gold":123456.0,"t":1000}}""",
+        )
+        assertTrue(online.isOnline)
+        assertEquals(42, online.onlineCount)
+        assertEquals(123456.0, online.economy!!.gold!!, 0.0)
+
+        assertFalse(json.decodeFromString<ShardStatusDto>("""{"enabled":true,"pluginConnected":false}""").isOnline)
+        assertFalse(json.decodeFromString<ShardStatusDto>("{}").isOnline)
+    }
+
+    @Test fun champDecodesBossAndProgressFields() {
+        val dto = json.decodeFromString<ChampDto>(
+            """{"serial":"0x1","category":"champion","name":"Rikktor","active":true,
+                "bossUp":true,"boss":"Rikktor","level":3,"maxLevel":16,"kills":10,"maxKills":100,
+                "hits":5000,"hitsMax":9000,"map":"Felucca","x":1,"y":2,"z":0}""",
+        )
+        assertTrue(dto.active)
+        assertTrue(dto.bossUp)
+        assertEquals(16, dto.maxLevel)
+        assertEquals(5000L, dto.hits)
+    }
+
+    @Test fun guildDecodesLeaderActor() {
+        val dto = json.decodeFromString<GuildDto>(
+            """{"id":7,"name":"Knights","abbr":"KoT","members":12,"online":3,
+                "leader":{"name":"Arthur","webId":"9931"}}""",
+        )
+        assertEquals("Knights", dto.name)
+        assertEquals("Arthur", dto.leader!!.label)
+        assertEquals("9931", dto.leader!!.webId)
+    }
+
+    @Test fun governorAndTermDecode() {
+        val gov = json.decodeFromString<GovernorDto>(
+            """{"city":"Britain","governor":{"name":"Dawn"},"electionPhase":"campaign"}""",
+        )
+        assertEquals("Britain", gov.city)
+        assertEquals("Dawn", gov.governor!!.label)
+
+        val term = json.decodeFromString<GovernorTermDto>(
+            """{"city":"Britain","governor":{"name":"Dawn"},"startedAt":1000,"endedAt":2000,"votes":50}""",
+        )
+        assertEquals(50, term.votes)
+        assertEquals(2000L, term.endedAt)
+    }
+
+    @Test fun houseAndPresenceAndStaffDecode() {
+        val house = json.decodeFromString<HouseDto>(
+            """{"serial":"0x40","name":"Tower","region":"Britain","isIdoc":true,"x":5,"y":6}""",
+        )
+        assertTrue(house.isIdoc)
+        assertEquals("Tower", house.name)
+
+        val presence = json.decodeFromString<PresenceDto>(
+            """{"count":30,"byFacet":{"Felucca":10,"Trammel":20},"byRegion":{"Britain":5}}""",
+        )
+        assertEquals(30, presence.count)
+        assertEquals(10, presence.byFacet["Felucca"])
+
+        val staff = json.decodeFromString<OnlineStaffDto>("""{"serial":"0x2","name":"GM Bob","map":"Felucca","x":1,"y":2,"z":0}""")
+        assertEquals("GM Bob", staff.name)
+    }
+
+    @Test fun feedEventDecodesPayloadObject() {
+        val ev = json.decodeFromString<FeedEventDto>(
+            """{"id":9,"kind":"champ.spawn","t":1234,"payload":{"name":"Rikktor"},"createdAt":"2026-07-22T00:00:00Z"}""",
+        )
+        assertEquals("champ.spawn", ev.kind)
+        assertTrue(ev.payload!!.containsKey("name"))
+    }
+}

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

@@ -0,0 +1,153 @@
+/*
+ * 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.assertNull
+import org.junit.Assert.assertTrue
+import org.junit.Test
+
+/**
+ * Decode tests for the four Protocol 3.0 content DTOs, against payloads captured from a
+ * **live** server rather than hand-written to match the Kotlin types.
+ *
+ * These exist because the fakes in `data/api/fake/` construct DTOs directly, so no test
+ * in the suite ever fed one real JSON — and `AtlasCreatureDto.places` shipped typed
+ * `List<String>` while the server sends objects. That decodes to an exception, the
+ * screen renders "something went wrong on the server", and 336 green tests say nothing.
+ * Nullable-with-defaults protects against a *missing* field, never a *wrong type*.
+ */
+class ShardContentDtoTest {
+
+    private val json = Json {
+        ignoreUnknownKeys = true
+        explicitNulls = false
+        coerceInputValues = true
+    }
+
+    // ── Spawn atlas (§6) ─────────────────────────────────────────────────
+
+    /** Trimmed from `GET /api/v1/public/atlas/creatures/seaserpent` on a real shard. */
+    private val seaSerpent = """
+        {"slug":"seaserpent","name":"SeaSerpent","total":6048,"points":477,
+         "facets":{"Felucca":237,"Trammel":240},"art":"seaserpent.png",
+         "places":[{"facet":"Felucca","label":"Wilderness","spawners":91,"maxAlive":1194},
+                   {"facet":"Trammel","label":"Britain","spawners":12,"maxAlive":96}],
+         "spawners":[{"id":1617,"facet":"Felucca","name":"SeaLife#68","x":1691,"y":1623,
+                      "width":350,"height":350,"range":175,"maxCount":15,"minDelay":300,
+                      "maxDelay":600,"todStart":0,"todEnd":0,"todMode":0,
+                      "region":"Britain","landmark":null,"label":"Britain"}],
+         "spawnersTruncated":true,
+         "alsoHere":[{"slug":"waterelemental","name":"WaterElemental","shared":242}]}
+    """.trimIndent()
+
+    @Test fun atlasCreatureDetailDecodesTheRealPayload() {
+        val creature = json.decodeFromString<AtlasCreatureDto>(seaSerpent)
+
+        assertEquals("seaserpent", creature.slug)
+        assertEquals(6048, creature.total)
+        assertEquals(477, creature.points)
+        assertEquals(240, creature.facets["Trammel"])
+        assertTrue(creature.spawnersTruncated)
+        assertEquals("seaserpent.png", creature.art)
+    }
+
+    @Test fun atlasPlacesAreObjectsNotStrings() {
+        // The regression. `places` is the aggregate the screen exists to show, and it
+        // arrives as {facet,label,spawners,maxAlive} — never as a bare place name.
+        val places = json.decodeFromString<AtlasCreatureDto>(seaSerpent).places
+
+        assertEquals(2, places.size)
+        assertEquals("Wilderness", places[0].label)
+        assertEquals("Felucca", places[0].facet)
+        assertEquals(91, places[0].spawners)
+        assertEquals(1194, places[0].maxAlive)
+    }
+
+    @Test fun atlasCreatureSurvivesAProjectedOrEmptyPayload() {
+        // The search route sends no `places`/`spawners`/`art`, and the visibility
+        // framework can drop any field from any of them.
+        val lean = json.decodeFromString<AtlasCreatureDto>("""{"slug":"orc"}""")
+        assertEquals("orc", lean.slug)
+        assertTrue(lean.places.isEmpty())
+        assertTrue(lean.spawners.isEmpty())
+        assertNull(lean.art)
+
+        val bare = json.decodeFromString<AtlasCreatureDto>("""{"places":[{}]}""")
+        assertNull(bare.places[0].label)
+        assertNull(bare.places[0].spawners)
+    }
+
+    // ── Market (§8) ──────────────────────────────────────────────────────
+
+    @Test fun marketListingDecodesWithItsNestedVendorAndLocation() {
+        // `location` nests on the wire so one visibility rule covers map/x/y/region/house.
+        val listing = json.decodeFromString<MarketListingDto>(
+            """{"serial":"0x40014A57","itemId":3937,"hue":1878,"amount":1,"price":115,
+                "name":null,"cliloc":1023937,"displayName":"longsword","child":false,
+                "vendor":{"serial":"0x2CB","shopName":"Seed Shop 225","ownerSerial":"0x201",
+                          "ownerName":"Seed004A",
+                          "location":{"map":"Felucca","x":1562,"y":1604,"z":0,
+                                      "region":"Britain","house":"Seed House 4"}}}""",
+        )
+
+        assertEquals("longsword", listing.displayName)
+        assertEquals(115L, listing.price)
+        assertEquals("Seed Shop 225", listing.vendor?.shopName)
+        assertEquals("Felucca", listing.vendor?.location?.map)
+    }
+
+    @Test fun marketListingSurvivesTheFieldsAVisitorMayNotSee() {
+        // Below the `staff` rung the server omits ownerName/ownerSerial, and below
+        // `player` the whole nested location. Neither may break the decode.
+        val projected = json.decodeFromString<MarketListingDto>(
+            """{"serial":"0x40014A57","price":115,"displayName":"longsword",
+                "vendor":{"serial":"0x2CB","shopName":"Seed Shop 225"}}""",
+        )
+
+        assertEquals("Seed Shop 225", projected.vendor?.shopName)
+        assertNull(projected.vendor?.ownerName)
+        assertNull(projected.vendor?.location)
+    }
+
+    // ── Points boards (§7) ───────────────────────────────────────────────
+
+    @Test fun pointsBoardDecodesAnEmptyBoardAndItsCap() {
+        // A shard with nothing scored yet is the common case, not an error, and
+        // maxPoints 0 is the "uncapped" sentinel rather than a cap of zero.
+        val board = json.decodeFromString<PointsBoardDto>(
+            """{"kind":"points.board","system":"QueensLoyalty","nameNumber":1095163,
+                "nameString":null,"players":0,"maxPoints":15000,"showOnGump":true,
+                "top":[],"t":1785556444154,"updatedAt":"2026-08-01T03:54:04.000Z"}""",
+        )
+
+        assertEquals("QueensLoyalty", board.system)
+        assertEquals(15000L, board.maxPoints)
+        assertNull(board.nameString)
+        assertTrue(board.top.isEmpty())
+    }
+
+    // ── Ruleset (§5) ─────────────────────────────────────────────────────
+
+    @Test fun rulesetDecodesTheNestedSectionsAndTolerantlySkipsUnknownOnes() {
+        // The frame is built from an allowlist that grows with the shard's config; a
+        // key this client has never heard of must not break the rules page.
+        val ruleset = json.decodeFromString<RulesetDto>(
+            """{"kind":"world.ruleset","shard":"My Shard","expansion":"EJ",
+                "caps":{"skill":1000,"totalSkill":7000,"stat":225,"str":125},
+                "systems":{"factions":false,"vvv":true,"siege":false},
+                "accounts":{"charSlots":7,"perIp":3},
+                "somethingAddedLater":{"nested":true}}""",
+        )
+
+        assertEquals("My Shard", ruleset.shard)
+        assertEquals("EJ", ruleset.expansion)
+        // Caps arrive in tenths; the DTO's computed property is what the screen shows.
+        assertEquals(7000, ruleset.caps?.totalSkill)
+        assertEquals(700.0, ruleset.caps?.totalSkillCap!!, 0.0)
+        assertEquals(false, ruleset.systems["factions"])
+        assertEquals(true, ruleset.systems["vvv"])
+    }
+}

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

@@ -43,25 +43,31 @@ class ShardDtoTest {
     }
 
     @Test fun champUpdateFrameDecodesWithKindAndExtras() {
-        // A live champ.update frame: has `kind`, `serial`, and category extras. The
-        // `kind` field is ignored (not on the DTO) and the extras decode.
+        // A live champ.update frame: has `kind`, a hex-string `serial` (INTEGRATION.md
+        // §1 — serials are opaque hex keys, never numbers), and category extras. The
+        // `kind`/`rank`/`autoRestart` fields are ignored (not on the DTO); extras decode.
         val dto = json.decodeFromString<ChampDto>(
-            """{"kind":"champ.update","serial":12345,"category":"champion","name":"Barracoon",
-               "status":"active","active":true,"level":10,"maxKills":250,"kills":120,
-               "bossUp":false,"map":"Felucca","x":5571,"y":1379,"z":0,"t":1721426400000}""",
+            """{"kind":"champ.update","serial":"0x40012345","category":"champion","name":"Barracoon",
+               "status":"active","active":true,"level":10,"rank":3,"maxKills":250,"kills":120,
+               "autoRestart":true,"bossUp":false,"map":"Felucca","x":5571,"y":1379,"z":0,"t":1721426400000}""",
         )
-        assertEquals(12345L, dto.serial)
+        assertEquals("0x40012345", dto.serial)
         assertEquals("champion", dto.category)
         assertEquals(120, dto.kills)
         assertTrue(dto.active)
     }
 
     @Test fun guildFrameDecodesLeaderActor() {
+        // The leader actor carries a hex-string serial and a string webId (the linked
+        // site-user id) — the exact wire shape from INTEGRATION.md §7.
         val dto = json.decodeFromString<GuildDto>(
             """{"kind":"guild.update","id":7,"name":"Knights","abbr":"KNT","members":12,
-               "online":3,"alliance":"Light","leader":{"serial":1,"name":"Arthur","acct":"art"}}""",
+               "online":3,"alliance":"Light",
+               "leader":{"serial":"0x1A2B","name":"Arthur","acct":"art","webId":"9931","player":true}}""",
         )
         assertEquals(7L, dto.id)
+        assertEquals("0x1A2B", dto.leader?.serial)
+        assertEquals("9931", dto.leader?.webId)
         assertEquals("Arthur", dto.leader?.label)
         assertEquals(12, dto.members)
     }
@@ -86,15 +92,49 @@ class ShardDtoTest {
 
     @Test fun houseDecodesPublicIdocShape() {
         val dto = json.decodeFromString<HouseDto>(
-            """{"serial":999,"name":"Tower","region":"Britain","map":"Felucca",
+            """{"serial":"0x40001234","name":"Tower","region":"Britain","map":"Felucca",
                "x":1,"y":2,"z":3,"isIdoc":true}""",
         )
-        assertEquals(999L, dto.serial)
+        assertEquals("0x40001234", dto.serial)
         assertTrue(dto.isIdoc)
     }
 
+    @Test fun onlineStaffDecodesHexSerial() {
+        val dto = json.decodeFromString<OnlineStaffDto>(
+            """{"serial":"0x24C","name":"Darrow"}""",
+        )
+        assertEquals("0x24C", dto.serial)
+        assertEquals("Darrow", dto.name)
+    }
+
     @Test fun actorLabelFallsBackToAcctThenSomeone() {
         assertEquals("bob", ActorDto(acct = "bob").label)
         assertEquals("Someone", ActorDto().label)
     }
+
+    @Test fun actorArrivesWithoutAcctOrWebIdBelowTheAdminRung() {
+        // Those two fields are locked to `admin` by the visibility framework and are
+        // stripped from every response below it — the app must decode their absence,
+        // not depend on them (docs/link/v3.md §3.4 rule 1).
+        val dto = json.decodeFromString<ActorDto>("""{"serial":"0x24C","name":"Darrow","player":true}""")
+        assertEquals("Darrow", dto.label)
+        assertNull(dto.acct)
+        assertNull(dto.webId)
+    }
+
+    @Test fun shardFeaturesDecodesTheRungAndVisibleSet() {
+        val dto = json.decodeFromString<ShardFeaturesDto>(
+            """{"level":"player","features":["status","champs","guilds","market"]}""",
+        )
+        assertEquals("player", dto.level)
+        assertTrue(dto.features.contains("market"))
+        assertEquals(4, dto.features.size)
+    }
+
+    @Test fun shardFeaturesDecodesAnEmptySet() {
+        // A fully-gated shard: every feature switched off for this viewer. Distinct
+        // from the lookup failing, which the repository represents as null.
+        val dto = json.decodeFromString<ShardFeaturesDto>("""{"level":"anonymous","features":[]}""")
+        assertEquals(emptyList<String>(), dto.features)
+    }
 }

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

@@ -0,0 +1,46 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.data.api.dto
+
+import kotlinx.serialization.encodeToString
+import kotlinx.serialization.json.Json
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertNull
+import org.junit.Assert.assertTrue
+import org.junit.Test
+
+/**
+ * Decode/encode tests for the Mobile SSO bridge DTOs (PLAN.md §4.2). Provider
+ * discovery is public (never secrets); the exchange body uses snake_case
+ * `code_verifier` to match the backend.
+ */
+class SsoDtoTest {
+
+    private val json = Json {
+        ignoreUnknownKeys = true
+        explicitNulls = false
+        coerceInputValues = true
+    }
+
+    @Test fun providerDecodesWithOptionalFields() {
+        val dto = json.decodeFromString<SsoProviderDto>(
+            """{"id":"discord","name":"Discord","icon":"discord","loginUrl":"/auth/discord","priority":2}""",
+        )
+        assertEquals("discord", dto.id)
+        assertEquals("Discord", dto.name)
+        assertEquals(2, dto.priority)
+    }
+
+    @Test fun providerToleratesMissingOptionals() {
+        val dto = json.decodeFromString<SsoProviderDto>("""{"id":"oidc","name":"Corp SSO"}""")
+        assertNull(dto.icon)
+        assertNull(dto.priority)
+    }
+
+    @Test fun exchangeRequestEncodesSnakeCaseVerifier() {
+        val body = json.encodeToString(MobileSsoExchangeRequest(code = "abc123", codeVerifier = "v-e-r-i-f-i-e-r"))
+        assertTrue(body.contains("\"code\":\"abc123\""))
+        assertTrue(body.contains("\"code_verifier\":\"v-e-r-i-f-i-e-r\""))
+    }
+}

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

@@ -0,0 +1,66 @@
+/*
+ * 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.assertTrue
+import org.junit.Test
+
+/**
+ * Decode tests for the wiki DTOs (`/public/wiki*`). Summary rows omit the body;
+ * the detail page carries tags, backlinks, and unresolved ("red") link targets.
+ */
+class WikiDtoTest {
+
+    private val json = Json {
+        ignoreUnknownKeys = true
+        explicitNulls = false
+        coerceInputValues = true
+    }
+
+    @Test fun summaryRowDecodesWithCategory() {
+        val dto = json.decodeFromString<WikiSummaryDto>(
+            """{"id":5,"slug":"pvp","title":"PvP","excerpt":"combat",
+                "category_slug":"systems","category_title":"Systems","updated_at":"2026-07-20T00:00:00Z"}""",
+        )
+        assertEquals(5L, dto.id)
+        assertEquals("systems", dto.categorySlug)
+        assertEquals("Systems", dto.categoryTitle)
+        assertEquals("combat", dto.excerpt)
+    }
+
+    @Test fun pageDecodesTagsBacklinksAndMissingLinks() {
+        val dto = json.decodeFromString<WikiPageDto>(
+            """{
+                "id":9,"slug":"housing","title":"Housing","body":"<p>text</p>",
+                "category_slug":"systems","category_title":"Systems",
+                "tags":[{"slug":"idoc","label":"IDOC"}],
+                "backlinks":[{"slug":"pvp","title":"PvP"}],
+                "missing_links":["nonexistent-page"]
+            }""",
+        )
+        assertEquals("<p>text</p>", dto.body)
+        assertEquals(1, dto.tags.size)
+        assertEquals("IDOC", dto.tags[0].label)
+        assertEquals("pvp", dto.backlinks[0].slug)
+        assertEquals(listOf("nonexistent-page"), dto.missingLinks)
+    }
+
+    @Test fun pageDefaultsCollectionsWhenAbsent() {
+        val dto = json.decodeFromString<WikiPageDto>("""{"id":1,"slug":"x","title":"X"}""")
+        assertTrue(dto.tags.isEmpty())
+        assertTrue(dto.backlinks.isEmpty())
+        assertTrue(dto.missingLinks.isEmpty())
+    }
+
+    @Test fun categoryAndTagDecodePublishedCounts() {
+        val cat = json.decodeFromString<WikiCategoryDto>(
+            """{"id":2,"slug":"systems","title":"Systems","description":"d","published_count":12}""",
+        )
+        assertEquals(12L, cat.publishedCount)
+        val tag = json.decodeFromString<WikiTagDto>("""{"id":4,"slug":"idoc","label":"IDOC","published_count":3}""")
+        assertEquals(3L, tag.publishedCount)
+    }
+}

app/src/test/java/com/runicgateway/app/data/api/fake/FakeAdminApi.kt

@@ -0,0 +1,88 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.data.api.fake
+
+import com.runicgateway.app.data.api.AdminApi
+import com.runicgateway.app.data.api.dto.AdminDashboardDto
+import com.runicgateway.app.data.api.dto.AdminPostDto
+import com.runicgateway.app.data.api.dto.AdminWikiCategoryDto
+import com.runicgateway.app.data.api.dto.AdminWikiTagDto
+import com.runicgateway.app.data.api.dto.BanRequest
+import com.runicgateway.app.data.api.dto.BroadcastRequest
+import com.runicgateway.app.data.api.dto.KickRequest
+import com.runicgateway.app.data.api.dto.PageRespondRequest
+import com.runicgateway.app.data.api.dto.PostCreateRequest
+import com.runicgateway.app.data.api.dto.PublishRequest
+import com.runicgateway.app.data.api.dto.SiteModeRequest
+import com.runicgateway.app.data.api.dto.SiteModeStateDto
+import com.runicgateway.app.data.api.dto.SupportPageDto
+import com.runicgateway.app.data.api.dto.UnbanRequest
+import com.runicgateway.app.data.api.dto.WikiCategoryRequest
+import com.runicgateway.app.util.okUnit
+import retrofit2.Response
+
+/**
+ * A configurable fake of [AdminApi] for the staff-ops repository/ViewModel tests.
+ * Read endpoints return their `var`; write endpoints returning `Response<Unit>`
+ * return [unitResponse] (default 200) so a test can drive the 200 / 403 / 503 copy
+ * branches. Set [error] to throw from every call (network / decode failure paths).
+ */
+class FakeAdminApi : AdminApi {
+
+    var error: Throwable? = null
+
+    var dashboard: AdminDashboardDto = AdminDashboardDto()
+    var siteMode: SiteModeStateDto = SiteModeStateDto()
+    var posts: List<AdminPostDto> = emptyList()
+    var createdPost: AdminPostDto = AdminPostDto(id = 0)
+    var publishedPost: AdminPostDto = AdminPostDto(id = 0)
+    var wikiCategories: List<AdminWikiCategoryDto> = emptyList()
+    var createdCategory: AdminWikiCategoryDto = AdminWikiCategoryDto(id = 0)
+    var wikiTags: List<AdminWikiTagDto> = emptyList()
+    var supportPages: List<SupportPageDto> = emptyList()
+
+    /** Response returned by the bodyless write endpoints (kick/ban/delete/respond/…). */
+    var unitResponse: Response<Unit> = okUnit()
+
+    /** Bodies seen by write calls, so a test can assert what was sent. */
+    var lastPostCreate: PostCreateRequest? = null
+    var lastBan: BanRequest? = null
+    var lastRespond: Pair<String, PageRespondRequest>? = null
+
+    private fun <T> reply(value: T): T {
+        error?.let { throw it }
+        return value
+    }
+
+    override suspend fun dashboard(): AdminDashboardDto = reply(dashboard)
+    override suspend fun setSiteMode(body: SiteModeRequest): SiteModeStateDto = reply(siteMode)
+
+    override suspend fun posts(): List<AdminPostDto> = reply(posts)
+    override suspend fun createPost(body: PostCreateRequest): AdminPostDto {
+        lastPostCreate = body
+        return reply(createdPost)
+    }
+    override suspend fun publishPost(id: Long, body: PublishRequest): AdminPostDto = reply(publishedPost)
+    override suspend fun deletePost(id: Long): Response<Unit> = reply(unitResponse)
+
+    override suspend fun wikiCategories(): List<AdminWikiCategoryDto> = reply(wikiCategories)
+    override suspend fun createWikiCategory(body: WikiCategoryRequest): AdminWikiCategoryDto = reply(createdCategory)
+    override suspend fun deleteWikiCategory(id: Long): Response<Unit> = reply(unitResponse)
+    override suspend fun wikiTags(): List<AdminWikiTagDto> = reply(wikiTags)
+
+    override suspend fun kick(body: KickRequest): Response<Unit> = reply(unitResponse)
+    override suspend fun ban(body: BanRequest): Response<Unit> {
+        lastBan = body
+        return reply(unitResponse)
+    }
+    override suspend fun unban(body: UnbanRequest): Response<Unit> = reply(unitResponse)
+    override suspend fun broadcast(body: BroadcastRequest): Response<Unit> = reply(unitResponse)
+
+    override suspend fun supportPages(): List<SupportPageDto> = reply(supportPages)
+    override suspend fun respondPage(id: String, body: PageRespondRequest): Response<Unit> {
+        lastRespond = id to body
+        return reply(unitResponse)
+    }
+    override suspend fun closePage(id: String): Response<Unit> = reply(unitResponse)
+}

app/src/test/java/com/runicgateway/app/data/api/fake/FakePlayerShardApi.kt

@@ -0,0 +1,47 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.data.api.fake
+
+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
+
+/**
+ * A configurable fake of [PlayerShardApi] for the player self-service repository /
+ * ViewModel tests. Set the relevant `var`; set [error] to throw from every call
+ * (drives the `503 shard offline` / `403 not-linked` / network paths).
+ */
+class FakePlayerShardApi : PlayerShardApi {
+
+    var error: Throwable? = null
+
+    var linkResult: ShardLinkResultDto = ShardLinkResultDto()
+    var accounts: List<ShardLinkDto> = emptyList()
+    var roster: RosterDto = RosterDto()
+    var char: CharProfileDto = CharProfileDto()
+    var vendors: VendorSnapshotDto = VendorSnapshotDto()
+    var sales: List<VendorSaleDto> = emptyList()
+    var houses: List<PlayerHouseDto> = emptyList()
+
+    private fun <T> reply(value: T): T {
+        error?.let { throw it }
+        return value
+    }
+
+    override suspend fun link(body: ShardLinkRequest): ShardLinkResultDto = reply(linkResult)
+    override suspend fun createAccount(body: CreateGameAccountRequest): ShardLinkResultDto = reply(linkResult)
+    override suspend fun accounts(): List<ShardLinkDto> = reply(accounts)
+    override suspend fun roster(account: String): RosterDto = reply(roster)
+    override suspend fun char(serial: String): CharProfileDto = reply(char)
+    override suspend fun vendors(account: String): VendorSnapshotDto = reply(vendors)
+    override suspend fun sales(): List<VendorSaleDto> = reply(sales)
+    override suspend fun houses(): List<PlayerHouseDto> = reply(houses)
+}

app/src/test/java/com/runicgateway/app/data/api/fake/FakePublicApi.kt

@@ -0,0 +1,161 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.data.api.fake
+
+import com.runicgateway.app.data.api.PublicApi
+import com.runicgateway.app.data.api.dto.ChampDto
+import com.runicgateway.app.data.api.dto.ContactRequest
+import com.runicgateway.app.data.api.dto.ContactResponse
+import com.runicgateway.app.data.api.dto.EconomySampleDto
+import com.runicgateway.app.data.api.dto.FeedEventDto
+import com.runicgateway.app.data.api.dto.GovernorDto
+import com.runicgateway.app.data.api.dto.GovernorTermDto
+import com.runicgateway.app.data.api.dto.GuildDto
+import com.runicgateway.app.data.api.dto.HouseDto
+import com.runicgateway.app.data.api.dto.OnlineStaffDto
+import com.runicgateway.app.data.api.dto.PageDto
+import com.runicgateway.app.data.api.dto.PostDto
+import com.runicgateway.app.data.api.dto.PresenceDto
+import com.runicgateway.app.data.api.dto.SettingsDto
+import com.runicgateway.app.data.api.dto.AtlasCreatureDto
+import com.runicgateway.app.data.api.dto.AtlasCreaturePageDto
+import com.runicgateway.app.data.api.dto.AtlasMetaDto
+import com.runicgateway.app.data.api.dto.MarketMetaDto
+import com.runicgateway.app.data.api.dto.MarketPageDto
+import com.runicgateway.app.data.api.dto.MarketVendorDto
+import com.runicgateway.app.data.api.dto.PointsBoardDto
+import com.runicgateway.app.data.api.dto.RulesetDto
+import com.runicgateway.app.data.api.dto.ShardFeaturesDto
+import com.runicgateway.app.data.api.dto.ShardStatusDto
+import com.runicgateway.app.data.api.dto.StatusDto
+import com.runicgateway.app.data.api.dto.WikiCategoryDto
+import com.runicgateway.app.data.api.dto.WikiPageDto
+import com.runicgateway.app.data.api.dto.WikiSummaryDto
+import com.runicgateway.app.data.api.dto.WikiTagDto
+
+/**
+ * A configurable fake of [PublicApi] for repository/ViewModel tests. Set the
+ * relevant `var` to the body a call should return; set [error] to make every call
+ * throw (drives the `ApiResult.HttpError` / `NetworkError` paths). Defaults are
+ * empty/neutral so a call an assertion doesn't care about never crashes.
+ */
+class FakePublicApi : PublicApi {
+
+    /** When non-null, every call throws this (use `httpError(code)` or an IOException). */
+    var error: Throwable? = null
+
+    var status: StatusDto = StatusDto()
+    var settings: SettingsDto = SettingsDto()
+    var posts: List<PostDto> = emptyList()
+    var post: PostDto = PostDto(id = 0)
+    var page: PageDto = PageDto(id = 0)
+    var wikiPages: List<WikiSummaryDto> = emptyList()
+    var wikiCategories: List<WikiCategoryDto> = emptyList()
+    var wikiTags: List<WikiTagDto> = emptyList()
+    var wikiPage: WikiPageDto = WikiPageDto(id = 0)
+    var contactResponse: ContactResponse = ContactResponse(sent = true)
+    var shardStatus: ShardStatusDto = ShardStatusDto()
+    var shardFeed: List<FeedEventDto> = emptyList()
+    var shardEconomy: List<EconomySampleDto> = emptyList()
+    var shardOnline: List<OnlineStaffDto> = emptyList()
+    var shardPresence: PresenceDto = PresenceDto()
+    var champs: List<ChampDto> = emptyList()
+    var guilds: List<GuildDto> = emptyList()
+    var governors: List<GovernorDto> = emptyList()
+    var governorHistory: List<GovernorTermDto> = emptyList()
+    var houses: List<HouseDto> = emptyList()
+    var shardFeatures: ShardFeaturesDto = ShardFeaturesDto()
+
+    // Protocol 3.0 content (M11). `ruleset` is nullable on the wire: null means the
+    // shard has never published one, which is a success, not a failure.
+    var ruleset: RulesetDto? = null
+    var pointsBoards: List<PointsBoardDto> = emptyList()
+    var pointsBoard: PointsBoardDto = PointsBoardDto()
+    var market: MarketPageDto = MarketPageDto()
+    var marketMeta: MarketMetaDto = MarketMetaDto()
+    var marketVendor: MarketVendorDto = MarketVendorDto()
+    var atlasCreatures: AtlasCreaturePageDto = AtlasCreaturePageDto()
+    var atlasCreature: AtlasCreatureDto = AtlasCreatureDto()
+    var atlasMeta: AtlasMetaDto = AtlasMetaDto()
+
+    /** Last market query seen, so a test can assert blanks were dropped. */
+    var lastMarketQuery: String? = null
+
+    /** Last atlas facet filter seen. */
+    var lastAtlasFacet: String? = null
+
+    /** Last contact request body seen (so a test can assert it was trimmed/forwarded). */
+    var lastContact: ContactRequest? = null
+
+    private fun <T> reply(value: T): T {
+        error?.let { throw it }
+        return value
+    }
+
+    override suspend fun probeStatus(absoluteStatusUrl: String): StatusDto = reply(status)
+    override suspend fun getStatus(): StatusDto = reply(status)
+    override suspend fun getSettings(): SettingsDto = reply(settings)
+
+    override suspend fun getPosts(category: String): List<PostDto> = reply(posts)
+    override suspend fun getPost(category: String, idOrSlug: String): PostDto = reply(post)
+    override suspend fun getPage(slug: String): PageDto = reply(page)
+
+    override suspend fun getWikiPages(query: String?, category: String?, tag: String?): List<WikiSummaryDto> =
+        reply(wikiPages)
+    override suspend fun getWikiCategories(): List<WikiCategoryDto> = reply(wikiCategories)
+    override suspend fun getWikiTags(): List<WikiTagDto> = reply(wikiTags)
+    override suspend fun getWikiPage(slug: String): WikiPageDto = reply(wikiPage)
+
+    override suspend fun postContact(body: ContactRequest): ContactResponse {
+        lastContact = body
+        return reply(contactResponse)
+    }
+
+    override suspend fun getShardFeatures(): ShardFeaturesDto = reply(shardFeatures)
+    override suspend fun getShardRuleset(): RulesetDto? = reply(ruleset)
+    override suspend fun getShardPoints(): List<PointsBoardDto> = reply(pointsBoards)
+    override suspend fun getShardPointsBoard(system: String): PointsBoardDto = reply(pointsBoard)
+
+    override suspend fun getShardMarket(
+        query: String?,
+        minPrice: Long?,
+        maxPrice: Long?,
+        map: String?,
+        region: String?,
+        sort: String?,
+        limit: Int?,
+        offset: Int?,
+    ): MarketPageDto {
+        lastMarketQuery = query
+        return reply(market)
+    }
+
+    override suspend fun getShardMarketMeta(): MarketMetaDto = reply(marketMeta)
+    override suspend fun getShardMarketVendor(serial: String, limit: Int?, offset: Int?): MarketVendorDto =
+        reply(marketVendor)
+
+    override suspend fun getAtlasCreatures(
+        query: String?,
+        facet: String?,
+        limit: Int?,
+        offset: Int?,
+    ): AtlasCreaturePageDto {
+        lastAtlasFacet = facet
+        return reply(atlasCreatures)
+    }
+
+    override suspend fun getAtlasCreature(slug: String): AtlasCreatureDto = reply(atlasCreature)
+    override suspend fun getAtlasMeta(): AtlasMetaDto = reply(atlasMeta)
+    override suspend fun getShardStatus(): ShardStatusDto = reply(shardStatus)
+    override suspend fun getShardFeed(kind: String?, limit: Int?): List<FeedEventDto> = reply(shardFeed)
+    override suspend fun getShardEconomy(limit: Int?): List<EconomySampleDto> = reply(shardEconomy)
+    override suspend fun getShardOnline(): List<OnlineStaffDto> = reply(shardOnline)
+    override suspend fun getShardPresence(): PresenceDto = reply(shardPresence)
+    override suspend fun getShardChamps(): List<ChampDto> = reply(champs)
+    override suspend fun getShardGuilds(): List<GuildDto> = reply(guilds)
+    override suspend fun getShardGovernors(): List<GovernorDto> = reply(governors)
+    override suspend fun getShardGovernorHistory(city: String, limit: Int?): List<GovernorTermDto> =
+        reply(governorHistory)
+    override suspend fun getShardHouses(): List<HouseDto> = reply(houses)
+}

app/src/test/java/com/runicgateway/app/data/api/fake/FakeShardStream.kt

@@ -0,0 +1,19 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.data.api.fake
+
+import com.runicgateway.app.core.net.ShardStream
+import com.runicgateway.app.core.net.ShardStreamEvent
+import kotlinx.coroutines.flow.Flow
+import kotlinx.coroutines.flow.flowOf
+
+/**
+ * A finite fake of the live [ShardStream] for board-ViewModel tests: it emits the
+ * given [events] once and completes, so the ViewModel's `collectLive()` finishes
+ * immediately (no perpetual reconnect loop) and any live-frame handling it triggers
+ * is exercised deterministically.
+ */
+class FakeShardStream(private val events: List<ShardStreamEvent> = emptyList()) : ShardStream {
+    override fun events(): Flow<ShardStreamEvent> = flowOf(*events.toTypedArray())
+}

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

@@ -0,0 +1,120 @@
+/*
+ * 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.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.RecoveryCodesDto
+import com.runicgateway.app.data.api.dto.RecoveryGenerateRequest
+import com.runicgateway.app.data.api.dto.RecoveryStatusDto
+import com.runicgateway.app.data.api.dto.RevokedCountDto
+import com.runicgateway.app.data.api.dto.RevokedFlagDto
+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.TrustDeviceRequest
+import com.runicgateway.app.data.api.dto.TrustDeviceResultDto
+import com.runicgateway.app.data.api.dto.TrustedDeviceDto
+import com.runicgateway.app.data.api.dto.UsernameResponse
+import com.runicgateway.app.data.repository.AccountRepository.TrustOutcome
+import kotlinx.coroutines.test.runTest
+import kotlinx.serialization.json.Json
+import okhttp3.MediaType.Companion.toMediaTypeOrNull
+import okhttp3.ResponseBody.Companion.toResponseBody
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertTrue
+import org.junit.Test
+import retrofit2.Response
+
+/**
+ * [AccountRepository] trusted-device + recovery logic (TRUSTED_DEVICES_MFA.md) over a
+ * fake [MeApi]. The interesting case is the `409` cap: the device list must survive
+ * into a typed [TrustOutcome.LimitReached] rather than being lost as a bare error.
+ */
+class AccountTrustedDevicesTest {
+
+    private val json = Json {
+        ignoreUnknownKeys = true
+        explicitNulls = false
+        coerceInputValues = true
+    }
+
+    /** A fake MeApi; only the trusted-device/recovery methods under test are wired. */
+    private open class FakeMeApi(
+        var trustResponse: Response<TrustDeviceResultDto>? = null,
+        var devices: List<TrustedDeviceDto> = emptyList(),
+        var revokeFlag: Boolean = true,
+        var revokeCount: Int = 0,
+        var remaining: Int = 0,
+        var generated: List<String> = emptyList(),
+    ) : MeApi {
+        override suspend fun trustedDevices(): List<TrustedDeviceDto> = devices
+        override suspend fun trustThisDevice(body: TrustDeviceRequest): Response<TrustDeviceResultDto> =
+            trustResponse ?: Response.success(TrustDeviceResultDto(trusted = true, trustToken = "t"))
+        override suspend fun revokeTrustedDevice(id: Long): RevokedFlagDto = RevokedFlagDto(revokeFlag)
+        override suspend fun revokeAllTrustedDevices(): RevokedCountDto = RevokedCountDto(revokeCount)
+        override suspend fun recoveryCodesStatus(): RecoveryStatusDto = RecoveryStatusDto(remaining)
+        override suspend fun generateRecoveryCodes(body: RecoveryGenerateRequest): RecoveryCodesDto =
+            RecoveryCodesDto(generated)
+
+        // Unused by these tests.
+        override suspend fun getAccount(): PlayerAccountDto = PlayerAccountDto()
+        override suspend fun changeUsername(body: ChangeUsernameRequest): UsernameResponse = UsernameResponse()
+        override suspend fun changePassword(body: ChangePasswordRequest) = Unit
+        override suspend fun totpSetup(): TotpSetupDto = TotpSetupDto()
+        override suspend fun totpEnable(body: TotpCodeRequest): TotpStateDto = TotpStateDto()
+        override suspend fun totpDisable(body: TotpCodeRequest): TotpStateDto = TotpStateDto()
+        override suspend fun identities(): List<LinkedIdentityDto> = emptyList()
+        override suspend fun unlinkIdentity(provider: String) = Unit
+    }
+
+    private fun repo(api: MeApi) = AccountRepository(api, json)
+
+    @Test fun trustThisDeviceReturnsToken() = runTest {
+        val api = FakeMeApi(trustResponse = Response.success(TrustDeviceResultDto(true, "opaque-xyz")))
+        val outcome = repo(api).trustThisDevice("Pixel")
+        assertTrue(outcome is TrustOutcome.Trusted)
+        assertEquals("opaque-xyz", (outcome as TrustOutcome.Trusted).trustToken)
+    }
+
+    @Test fun trustThisDeviceParsesCapDevicesFrom409() = runTest {
+        val body = """{"error":"trusted_device_limit","devices":[
+            {"id":1,"platform":"web","deviceName":"Firefox"},
+            {"id":2,"platform":"mobile","deviceName":"Pixel"}]}"""
+            .toResponseBody("application/json".toMediaTypeOrNull())
+        val api = FakeMeApi(trustResponse = Response.error(409, body))
+        val outcome = repo(api).trustThisDevice(null)
+        assertTrue(outcome is TrustOutcome.LimitReached)
+        val devices = (outcome as TrustOutcome.LimitReached).devices
+        assertEquals(2, devices.size)
+        assertEquals("Pixel", devices[1].deviceName)
+    }
+
+    @Test fun trustThisDeviceOtherErrorIsServerError() = runTest {
+        val body = """{"message":"boom"}""".toResponseBody("application/json".toMediaTypeOrNull())
+        val api = FakeMeApi(trustResponse = Response.error(500, body))
+        assertTrue(repo(api).trustThisDevice(null) is TrustOutcome.ServerError)
+    }
+
+    @Test fun revokeMapsFlagAndCount() = runTest {
+        val revoked = repo(FakeMeApi(revokeFlag = true)).revokeTrustedDevice(9)
+        assertTrue(revoked is ApiResult.Ok && revoked.data)
+
+        val all = repo(FakeMeApi(revokeCount = 3)).revokeAllTrustedDevices()
+        assertTrue(all is ApiResult.Ok && all.data == 3)
+    }
+
+    @Test fun recoveryStatusAndGenerateMap() = runTest {
+        val status = repo(FakeMeApi(remaining = 6)).recoveryCodesStatus()
+        assertTrue(status is ApiResult.Ok && status.data.remaining == 6)
+
+        val gen = repo(FakeMeApi(generated = listOf("a", "b"))).generateRecoveryCodes("pw")
+        assertTrue(gen is ApiResult.Ok)
+        assertEquals(listOf("a", "b"), (gen as ApiResult.Ok).data.recoveryCodes)
+    }
+}

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

@@ -0,0 +1,104 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.data.repository
+
+import com.runicgateway.app.data.api.dto.ShardFeaturesDto
+import com.runicgateway.app.data.api.fake.FakePublicApi
+import com.runicgateway.app.util.httpError
+import kotlinx.coroutines.test.runTest
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertNull
+import org.junit.Assert.assertTrue
+import org.junit.Test
+import java.io.IOException
+
+/**
+ * The shard-visibility lookup (PLAN.md §9 M11). The behavior worth pinning is the
+ * FAIL-OPEN direction: an unknown answer must show every entry, because the server
+ * gates every call regardless and the alternative is a menu that flickers in.
+ */
+class ShardFeaturesRepositoryTest {
+
+    private val api = FakePublicApi()
+    private val repository = ShardFeaturesRepository(api)
+
+    @Test fun refreshPublishesTheVisibleSetAndTheServersRung() = runTest {
+        api.shardFeatures = ShardFeaturesDto(
+            level = "player",
+            features = listOf("status", "champs", "market"),
+        )
+
+        repository.refresh()
+
+        val features = repository.features.value
+        assertEquals("player", features?.level)
+        assertEquals(setOf("status", "champs", "market"), features?.visible)
+    }
+
+    @Test fun aFeatureTheServerOmittedIsNotVisible() = runTest {
+        api.shardFeatures = ShardFeaturesDto(level = "anonymous", features = listOf("status"))
+
+        repository.refresh()
+
+        assertTrue(canSee(repository.features.value, ShardFeature.STATUS))
+        assertFalse(canSee(repository.features.value, ShardFeature.MARKET))
+    }
+
+    @Test fun aFailedLookupFallsBackToUnknownRatherThanEmpty() = runTest {
+        // Empty and unknown are opposite answers: empty hides everything, unknown
+        // shows everything. A failure must never be read as "this shard publishes
+        // nothing".
+        api.error = IOException("offline")
+
+        repository.refresh()
+
+        assertNull(repository.features.value)
+        assertTrue(canSee(repository.features.value, ShardFeature.MARKET))
+    }
+
+    @Test fun aPreProtocol3WebsiteIs404AndReadsAsUnknown() = runTest {
+        // The route does not exist before Protocol 3.0. That site has no visibility
+        // framework at all, so "unknown" is exactly right and the menu behaves as it
+        // did before M11.
+        api.error = httpError(404)
+
+        repository.refresh()
+
+        assertNull(repository.features.value)
+        assertTrue(canSee(repository.features.value, ShardFeature.CHAMPS))
+    }
+
+    @Test fun aFailedRefreshClearsAPreviouslyGoodAnswer() = runTest {
+        api.shardFeatures = ShardFeaturesDto(level = "admin", features = listOf("status"))
+        repository.refresh()
+        assertEquals(setOf("status"), repository.features.value?.visible)
+
+        // Signing out and failing to re-resolve must not leave the previous viewer's
+        // (possibly wider) answer in place.
+        api.error = httpError(500)
+        repository.refresh()
+
+        assertNull(repository.features.value)
+    }
+
+    @Test fun invalidateDropsTheCachedAnswer() = runTest {
+        api.shardFeatures = ShardFeaturesDto(level = "staff", features = listOf("houses"))
+        repository.refresh()
+        assertEquals("staff", repository.features.value?.level)
+
+        // A Settings → Server switch: the answer belonged to the old host.
+        repository.invalidate()
+
+        assertNull(repository.features.value)
+    }
+
+    @Test fun canSeeTreatsUnknownAsVisibleAndEmptyAsHidden() {
+        assertTrue("unknown must fail open", canSee(null, ShardFeature.RULESET))
+        assertFalse(
+            "an explicit empty set hides everything",
+            canSee(ShardFeatures(level = "anonymous", visible = emptySet()), ShardFeature.RULESET),
+        )
+    }
+}

app/src/test/java/com/runicgateway/app/ui/ContentViewModelTest.kt

@@ -0,0 +1,120 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.ui
+
+import androidx.lifecycle.SavedStateHandle
+import com.runicgateway.app.data.api.dto.PageDto
+import com.runicgateway.app.data.api.dto.PostDto
+import com.runicgateway.app.data.api.dto.StatusDto
+import com.runicgateway.app.data.api.dto.WikiPageDto
+import com.runicgateway.app.data.api.dto.WikiSummaryDto
+import com.runicgateway.app.data.api.fake.FakePublicApi
+import com.runicgateway.app.data.repository.ContentRepository
+import com.runicgateway.app.data.repository.SettingsRepository
+import com.runicgateway.app.data.repository.WikiRepository
+import com.runicgateway.app.ui.home.HomeViewModel
+import com.runicgateway.app.ui.navigation.Routes
+import com.runicgateway.app.ui.news.NewsViewModel
+import com.runicgateway.app.ui.news.PostViewModel
+import com.runicgateway.app.ui.page.PageViewModel
+import com.runicgateway.app.ui.wiki.WikiPageViewModel
+import com.runicgateway.app.ui.wiki.WikiViewModel
+import com.runicgateway.app.util.MainDispatcherRule
+import com.runicgateway.app.util.httpError
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertTrue
+import org.junit.Rule
+import org.junit.Test
+
+/** ViewModels over the public content APIs (news, CMS pages, wiki, home status). */
+class ContentViewModelTest {
+
+    @get:Rule val mainDispatcher = MainDispatcherRule()
+
+    private val api = FakePublicApi()
+    private val content = ContentRepository(api)
+    private val wiki = WikiRepository(api)
+    private val settings = SettingsRepository(api)
+
+    // ── News hub ──────────────────────────────────────────────────────────
+    @Test fun newsLoadsSelectedCategory() {
+        api.posts = listOf(PostDto(id = 1, category = "news", title = "Hi"))
+        val vm = NewsViewModel(content)
+        assertTrue(vm.state.value is UiState.Success)
+        assertEquals(1, (vm.state.value as UiState.Success).data.size)
+    }
+
+    @Test fun newsSelectCategoryReloads() {
+        val vm = NewsViewModel(content)
+        api.posts = listOf(PostDto(id = 2, category = "newsletter", title = "N"))
+        vm.selectCategory(ContentRepository.PostCategory.NEWSLETTER)
+        assertEquals(ContentRepository.PostCategory.NEWSLETTER, vm.category.value)
+        assertEquals(1, (vm.state.value as UiState.Success).data.size)
+    }
+
+    @Test fun newsServerErrorIsUiError() {
+        api.error = httpError(500)
+        assertTrue(NewsViewModel(content).state.value is UiState.Error)
+    }
+
+    // ── Post detail (SavedStateHandle args) ─────────────────────────────────
+    @Test fun postDetailLoadsForKnownCategory() {
+        api.post = PostDto(id = 7, category = "news", title = "Update", body = "<p>x</p>")
+        val handle = SavedStateHandle(
+            mapOf(Routes.Args.CATEGORY to "news", Routes.Args.ID_OR_SLUG to "update"),
+        )
+        val vm = PostViewModel(content, handle)
+        assertEquals("Update", (vm.state.value as UiState.Success).data.title)
+    }
+
+    @Test fun postDetailUnknownCategoryIsNotFoundWithoutApiCall() {
+        val handle = SavedStateHandle(
+            mapOf(Routes.Args.CATEGORY to "bogus", Routes.Args.ID_OR_SLUG to "x"),
+        )
+        val state = PostViewModel(content, handle).state.value
+        assertTrue(state is UiState.Error)
+        assertEquals(ErrorKind.NOT_FOUND, (state as UiState.Error).kind)
+    }
+
+    // ── CMS page ────────────────────────────────────────────────────────────
+    @Test fun pageLoadsBySlug() {
+        api.page = PageDto(id = 3, slug = "about", title = "About")
+        val vm = PageViewModel(content, SavedStateHandle(mapOf(Routes.Args.SLUG to "about")))
+        assertEquals("About", (vm.state.value as UiState.Success).data.title)
+    }
+
+    @Test fun pageNotFoundIsUiError() {
+        api.error = httpError(404)
+        val vm = PageViewModel(content, SavedStateHandle(mapOf(Routes.Args.SLUG to "missing")))
+        assertEquals(ErrorKind.NOT_FOUND, (vm.state.value as UiState.Error).kind)
+    }
+
+    // ── Wiki index + detail ─────────────────────────────────────────────────
+    @Test fun wikiIndexLoadsAndTracksQuery() {
+        api.wikiPages = listOf(WikiSummaryDto(id = 1, slug = "pvp", title = "PvP"))
+        val vm = WikiViewModel(wiki)
+        assertTrue(vm.state.value is UiState.Success)
+        vm.onQueryChange("housing")
+        assertEquals("housing", vm.query.value)
+    }
+
+    @Test fun wikiPageLoadsBySlug() {
+        api.wikiPage = WikiPageDto(id = 9, slug = "housing", title = "Housing", body = "b")
+        val vm = WikiPageViewModel(wiki, SavedStateHandle(mapOf(Routes.Args.SLUG to "housing")))
+        assertEquals("Housing", (vm.state.value as UiState.Success).data.title)
+    }
+
+    // ── Home status ─────────────────────────────────────────────────────────
+    @Test fun homeLoadsStatus() {
+        api.status = StatusDto(mode = "maintenance")
+        val vm = HomeViewModel(settings)
+        assertTrue((vm.state.value as UiState.Success).data.isMaintenance)
+    }
+
+    @Test fun homeNetworkErrorIsUiError() {
+        api.error = java.io.IOException("offline")
+        val state = HomeViewModel(settings).state.value
+        assertEquals(ErrorKind.NETWORK, (state as UiState.Error).kind)
+    }
+}

app/src/test/java/com/runicgateway/app/ui/UiStateTest.kt

@@ -4,7 +4,9 @@
 package com.runicgateway.app.ui
 
 import com.runicgateway.app.core.result.ApiResult
+import com.runicgateway.app.ui.components.isRetryable
 import org.junit.Assert.assertEquals
+import org.junit.Assert.assertFalse
 import org.junit.Assert.assertTrue
 import org.junit.Test
 import java.io.IOException
@@ -34,6 +36,44 @@ class UiStateTest {
         assertTrue(ApiResult.HttpError(503).let { it.status == 503 })
     }
 
+    // ── Shard reads: 404/403 mean "this shard doesn't publish it" (M11) ──
+
+    @Test fun shardReadsTreat404And403AsFeatureUnavailable() {
+        // requireFeature answers 404 for a disabled feature (deliberately not
+        // disclosing that it exists) and 403 for a viewer below its audience rung.
+        assertEquals(ErrorKind.FEATURE_UNAVAILABLE, shardKindOf(404))
+        assertEquals(ErrorKind.FEATURE_UNAVAILABLE, shardKindOf(403))
+    }
+
+    @Test fun shardReadsLeaveEveryOtherStatusAlone() {
+        assertEquals(ErrorKind.SHARD_OFFLINE, shardKindOf(503))
+        assertEquals(ErrorKind.RATE_LIMITED, shardKindOf(429))
+        assertEquals(ErrorKind.SERVER, shardKindOf(500))
+        assertEquals(
+            ErrorKind.NETWORK,
+            (ApiResult.NetworkError(IOException()).toShardUiState() as UiState.Error).kind,
+        )
+        assertEquals(UiState.Success("hi"), ApiResult.Ok("hi").toShardUiState())
+    }
+
+    @Test fun nonShardReadsKeep404AsNotFound() {
+        // The remap is scoped to shard routes on purpose: off them, a 404 is still a
+        // deleted post or an unknown wiki slug.
+        assertEquals(ErrorKind.NOT_FOUND, kindOf(404))
+    }
+
+    @Test fun anUnavailableFeatureIsNotRetryable() {
+        // An admin controls this, so a retry button would read as a transient failure
+        // the user could wait out.
+        assertFalse(isRetryable(ErrorKind.FEATURE_UNAVAILABLE))
+        for (kind in ErrorKind.entries.filter { it != ErrorKind.FEATURE_UNAVAILABLE }) {
+            assertTrue("$kind should offer a retry", isRetryable(kind))
+        }
+    }
+
     private fun kindOf(status: Int): ErrorKind =
         (ApiResult.HttpError(status).toUiState() as UiState.Error).kind
+
+    private fun shardKindOf(status: Int): ErrorKind =
+        (ApiResult.HttpError(status).toShardUiState() as UiState.Error).kind
 }

app/src/test/java/com/runicgateway/app/ui/admin/AdminContentViewModelTest.kt

@@ -0,0 +1,78 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.ui.admin
+
+import com.runicgateway.app.R
+import com.runicgateway.app.data.api.dto.AdminPostDto
+import com.runicgateway.app.data.api.dto.AdminWikiCategoryDto
+import com.runicgateway.app.data.api.dto.AdminWikiTagDto
+import com.runicgateway.app.data.api.fake.FakeAdminApi
+import com.runicgateway.app.data.repository.AdminRepository
+import com.runicgateway.app.ui.UiState
+import com.runicgateway.app.util.MainDispatcherRule
+import com.runicgateway.app.util.errorUnit
+import com.runicgateway.app.util.httpError
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertTrue
+import org.junit.Rule
+import org.junit.Test
+
+class AdminContentViewModelTest {
+
+    @get:Rule val mainDispatcher = MainDispatcherRule()
+
+    private val api = FakeAdminApi()
+    private fun viewModel() = AdminContentViewModel(AdminRepository(api))
+
+    @Test fun loadsPostsAndWikiOnInit() {
+        api.posts = listOf(AdminPostDto(id = 1, title = "A", published = 1))
+        api.wikiCategories = listOf(AdminWikiCategoryDto(id = 2, slug = "lore", title = "Lore"))
+        api.wikiTags = listOf(AdminWikiTagDto(id = 3, slug = "pvp", label = "PvP"))
+        val vm = viewModel()
+        assertTrue(vm.state.value.posts is UiState.Success)
+        assertEquals(1, (vm.state.value.posts as UiState.Success).data.size)
+        assertEquals(1, vm.state.value.tags.size)
+    }
+
+    @Test fun createPostRejectsBlankTitleWithoutCallingApi() {
+        val vm = viewModel()
+        vm.createPost(category = "news", title = "  ", excerpt = "", body = "", published = false)
+        assertFalse(vm.state.value.feedback!!.ok)
+        assertEquals(R.string.admin_content_title_required, vm.state.value.feedback!!.messageRes)
+        assertEquals(null, api.lastPostCreate) // never reached the API
+    }
+
+    @Test fun createPostTrimsAndNullsBlanksThenReloads() {
+        val vm = viewModel()
+        vm.createPost(category = "news", title = "  Hello ", excerpt = "", body = "b", published = true)
+        val sent = api.lastPostCreate!!
+        assertEquals("Hello", sent.title)
+        assertEquals(null, sent.excerpt) // blank -> null
+        assertEquals("b", sent.body)
+        assertTrue(vm.state.value.feedback!!.ok)
+        assertFalse(vm.state.value.busy)
+    }
+
+    @Test fun togglePublishForbiddenSurfacesForbiddenCopy() {
+        api.unitResponse = errorUnit(403)
+        api.error = httpError(403)
+        val vm = viewModel()
+        vm.togglePublish(AdminPostDto(id = 5, title = "x", published = 1))
+        assertEquals(R.string.admin_forbidden, vm.state.value.feedback!!.messageRes)
+    }
+
+    @Test fun createCategoryRejectsBlankFields() {
+        val vm = viewModel()
+        vm.createCategory(slug = "", title = "", description = "", sortOrder = null)
+        assertEquals(R.string.admin_content_cat_fields_required, vm.state.value.feedback!!.messageRes)
+    }
+
+    @Test fun deletePostNetworkErrorShowsNetworkCopy() {
+        api.error = java.io.IOException("offline")
+        val vm = viewModel()
+        vm.deletePost(9)
+        assertEquals(R.string.error_network, vm.state.value.feedback!!.messageRes)
+    }
+}

app/src/test/java/com/runicgateway/app/ui/admin/AdminDashboardViewModelTest.kt

@@ -0,0 +1,70 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.ui.admin
+
+import com.runicgateway.app.R
+import com.runicgateway.app.data.api.dto.AdminCountsDto
+import com.runicgateway.app.data.api.dto.AdminDashboardDto
+import com.runicgateway.app.data.api.dto.SiteModeStateDto
+import com.runicgateway.app.data.api.fake.FakeAdminApi
+import com.runicgateway.app.data.repository.AdminRepository
+import com.runicgateway.app.ui.UiState
+import com.runicgateway.app.util.MainDispatcherRule
+import com.runicgateway.app.util.httpError
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertTrue
+import org.junit.Rule
+import org.junit.Test
+
+class AdminDashboardViewModelTest {
+
+    @get:Rule val mainDispatcher = MainDispatcherRule()
+
+    private val api = FakeAdminApi()
+    private fun viewModel() = AdminDashboardViewModel(AdminRepository(api))
+
+    @Test fun loadsDashboardOnInit() {
+        api.dashboard = AdminDashboardDto(siteMode = "live", counts = AdminCountsDto(users = 12))
+        val vm = viewModel()
+        val state = vm.state.value.dashboard
+        assertTrue(state is UiState.Success)
+        assertEquals(12, (state as UiState.Success).data.counts.users)
+    }
+
+    @Test fun loadSurfacesServerErrorAsUiError() {
+        api.error = httpError(500)
+        val vm = viewModel()
+        assertTrue(vm.state.value.dashboard is UiState.Error)
+    }
+
+    @Test fun setSiteModeSuccessUpdatesModeAndClearsSwitching() {
+        api.dashboard = AdminDashboardDto(siteMode = "live")
+        api.siteMode = SiteModeStateDto(siteMode = "maintenance")
+        val vm = viewModel()
+        vm.setSiteMode("maintenance")
+        val s = vm.state.value
+        assertFalse(s.switching)
+        assertTrue(s.feedback!!.ok)
+        assertEquals(R.string.admin_site_mode_updated, s.feedback!!.messageRes)
+    }
+
+    @Test fun setSiteModeForbiddenShowsForbiddenCopy() {
+        api.dashboard = AdminDashboardDto()
+        api.error = httpError(403)
+        val vm = viewModel()
+        vm.setSiteMode("maintenance")
+        val fb = vm.state.value.feedback!!
+        assertFalse(fb.ok)
+        assertEquals(R.string.admin_forbidden, fb.messageRes)
+    }
+
+    @Test fun clearFeedbackResetsBanner() {
+        api.error = httpError(500)
+        val vm = viewModel()
+        vm.setSiteMode("live")
+        vm.clearFeedback()
+        assertEquals(null, vm.state.value.feedback)
+    }
+}

app/src/test/java/com/runicgateway/app/ui/admin/AdminModerationViewModelTest.kt

@@ -0,0 +1,63 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.ui.admin
+
+import com.runicgateway.app.R
+import com.runicgateway.app.data.api.fake.FakeAdminApi
+import com.runicgateway.app.data.repository.AdminRepository
+import com.runicgateway.app.util.MainDispatcherRule
+import com.runicgateway.app.util.errorUnit
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertNull
+import org.junit.Assert.assertTrue
+import org.junit.Rule
+import org.junit.Test
+
+class AdminModerationViewModelTest {
+
+    @get:Rule val mainDispatcher = MainDispatcherRule()
+
+    private val api = FakeAdminApi()
+    private fun viewModel() = AdminModerationViewModel(AdminRepository(api))
+
+    @Test fun kickWithNoTargetShowsTargetRequired() {
+        val vm = viewModel()
+        vm.kick(account = "", serial = "")
+        assertEquals(R.string.admin_mod_target_required, vm.state.value.feedback!!.messageRes)
+    }
+
+    @Test fun banForwardsFieldsAndSucceeds() {
+        val vm = viewModel()
+        vm.ban(account = "gwen", serial = "", durationSec = 3600, reason = "afk")
+        assertEquals("gwen", api.lastBan!!.account)
+        assertNull(api.lastBan!!.serial) // blank -> null
+        assertEquals(3600L, api.lastBan!!.durationSec)
+        assertEquals("afk", api.lastBan!!.reason)
+        val fb = vm.state.value.feedback!!
+        assertTrue(fb.ok)
+        assertEquals(R.string.admin_mod_banned, fb.messageRes)
+        assertFalse(vm.state.value.busy)
+    }
+
+    @Test fun shardOfflineMapsTo503Copy() {
+        api.unitResponse = errorUnit(503)
+        val vm = viewModel()
+        vm.kick(account = "x", serial = "")
+        assertEquals(R.string.admin_mod_shard_offline, vm.state.value.feedback!!.messageRes)
+    }
+
+    @Test fun broadcastRejectsBlankText() {
+        val vm = viewModel()
+        vm.broadcast(text = "  ", hue = null)
+        assertEquals(R.string.admin_mod_text_required, vm.state.value.feedback!!.messageRes)
+    }
+
+    @Test fun unbanForbiddenMapsTo403Copy() {
+        api.unitResponse = errorUnit(403)
+        val vm = viewModel()
+        vm.unban("gwen")
+        assertEquals(R.string.admin_forbidden, vm.state.value.feedback!!.messageRes)
+    }
+}

app/src/test/java/com/runicgateway/app/ui/admin/AdminSupportViewModelTest.kt

@@ -0,0 +1,61 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.ui.admin
+
+import com.runicgateway.app.R
+import com.runicgateway.app.data.api.dto.SupportPageDto
+import com.runicgateway.app.data.api.fake.FakeAdminApi
+import com.runicgateway.app.data.repository.AdminRepository
+import com.runicgateway.app.ui.UiState
+import com.runicgateway.app.util.MainDispatcherRule
+import com.runicgateway.app.util.errorUnit
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertTrue
+import org.junit.Rule
+import org.junit.Test
+
+class AdminSupportViewModelTest {
+
+    @get:Rule val mainDispatcher = MainDispatcherRule()
+
+    private val api = FakeAdminApi()
+    private fun viewModel() = AdminSupportViewModel(AdminRepository(api))
+
+    @Test fun loadsOpenPagesOnInit() {
+        api.supportPages = listOf(SupportPageDto(pageId = "0x1", message = "help"))
+        val vm = viewModel()
+        val pages = vm.state.value.pages
+        assertTrue(pages is UiState.Success)
+        assertEquals("0x1", (pages as UiState.Success).data.first().pageId)
+    }
+
+    @Test fun respondRejectsBlankMessage() {
+        val vm = viewModel()
+        vm.respond(id = "0x1", message = "   ", close = true)
+        assertEquals(R.string.admin_support_message_required, vm.state.value.feedback!!.messageRes)
+        assertEquals(null, api.lastRespond)
+    }
+
+    @Test fun respondTrimsMessageAndReloadsOnSuccess() {
+        api.supportPages = listOf(SupportPageDto(pageId = "0x1"))
+        val vm = viewModel()
+        vm.respond(id = "0x1", message = "  on it ", close = false)
+        assertEquals("on it", api.lastRespond!!.second.message)
+        assertTrue(vm.state.value.feedback!!.ok)
+    }
+
+    @Test fun respondUnknownPageMapsTo404Copy() {
+        api.unitResponse = errorUnit(404)
+        val vm = viewModel()
+        vm.respond(id = "0xZ", message = "hi", close = false)
+        assertEquals(R.string.admin_support_unknown_page, vm.state.value.feedback!!.messageRes)
+    }
+
+    @Test fun closeShardOfflineMapsTo503Copy() {
+        api.unitResponse = errorUnit(503)
+        val vm = viewModel()
+        vm.close("0x1")
+        assertEquals(R.string.admin_mod_shard_offline, vm.state.value.feedback!!.messageRes)
+    }
+}

app/src/test/java/com/runicgateway/app/ui/contact/ContactViewModelTest.kt

@@ -0,0 +1,67 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.ui.contact
+
+import com.runicgateway.app.data.api.dto.ContactResponse
+import com.runicgateway.app.data.api.fake.FakePublicApi
+import com.runicgateway.app.data.repository.ContactRepository
+import com.runicgateway.app.ui.ErrorKind
+import com.runicgateway.app.util.MainDispatcherRule
+import com.runicgateway.app.util.httpError
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertTrue
+import org.junit.Rule
+import org.junit.Test
+
+class ContactViewModelTest {
+
+    @get:Rule val mainDispatcher = MainDispatcherRule()
+
+    private val api = FakePublicApi()
+    private fun viewModel() = ContactViewModel(ContactRepository(api))
+
+    @Test fun blankFieldsProduceValidationError() {
+        val vm = viewModel()
+        vm.onNameChange("Gwen")
+        vm.send() // email + message still blank
+        assertEquals(ContactViewModel.Result.ValidationError, vm.state.value.result)
+        assertEquals(null, api.lastContact) // never hit the API
+    }
+
+    @Test fun successfulSendClearsFieldsAndReportsSent() {
+        api.contactResponse = ContactResponse(sent = true)
+        val vm = viewModel()
+        vm.onNameChange(" Gwen ")
+        vm.onEmailChange(" g@x.c ")
+        vm.onMessageChange(" hello ")
+        vm.send()
+        assertEquals(ContactViewModel.Result.Sent, vm.state.value.result)
+        assertEquals("", vm.state.value.name) // fields cleared on success
+        // Repository trims before sending.
+        assertEquals("Gwen", api.lastContact!!.name)
+        assertEquals("g@x.c", api.lastContact!!.email)
+    }
+
+    @Test fun mailerFallbackSurfacesEmail() {
+        api.contactResponse = ContactResponse(sent = false, fallback = "mailto", email = "team@shard.gg")
+        val vm = viewModel()
+        vm.onNameChange("A"); vm.onEmailChange("a@b.c"); vm.onMessageChange("m")
+        vm.send()
+        val result = vm.state.value.result
+        assertTrue(result is ContactViewModel.Result.Fallback)
+        assertEquals("team@shard.gg", (result as ContactViewModel.Result.Fallback).email)
+        // Fields kept (not a clean send) so the user can retry.
+        assertEquals("A", vm.state.value.name)
+    }
+
+    @Test fun serverErrorSurfacesFailedWithKind() {
+        api.error = httpError(500)
+        val vm = viewModel()
+        vm.onNameChange("A"); vm.onEmailChange("a@b.c"); vm.onMessageChange("m")
+        vm.send()
+        val result = vm.state.value.result
+        assertTrue(result is ContactViewModel.Result.Failed)
+        assertEquals(ErrorKind.SERVER, (result as ContactViewModel.Result.Failed).kind)
+    }
+}

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

@@ -37,12 +37,16 @@ class MenuAccessTest {
         assertTrue(visible.contains(Routes.HOME))
     }
 
-    @Test fun staffSeeAccountButNoPlayerOnlyGroups() {
-        val visible = routes(signedIn(Role.EDITOR))
-        assertTrue(visible.contains(Routes.ACCOUNT))
-        // 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) })
+    @Test fun staffSeeThePlayerGameDataGroups() {
+        // Staff are a superset of players: every staff role sees the PLAYER-access
+        // game-data groups too (their own linked characters, via the role-agnostic
+        // /player self-service surface), on top of their staff entries.
+        val playerGroups = APP_MENU.filter { it.access == MenuAccess.PLAYER }.map { it.route }
+        for (role in listOf(Role.ADMIN, Role.EDITOR, Role.MODERATOR)) {
+            val visible = routes(signedIn(role))
+            assertTrue("$role should see Account", visible.contains(Routes.ACCOUNT))
+            assertTrue("$role should see the player game-data groups", playerGroups.all { visible.contains(it) })
+        }
     }
 
     @Test fun publicEntryCountIsStableAcrossSessions() {
@@ -58,10 +62,13 @@ class MenuAccessTest {
     }
 
     @Test fun playerAccessGatedFunction() {
-        // A synthetic PLAYER-gated entry is visible to a player, hidden from staff/anon.
+        // A PLAYER-gated entry is visible to a player AND to every staff role
+        // (staff superset), hidden only from an unrecognized role and anon.
         val entries = listOf(MenuEntry("game", 0, MenuAccess.PLAYER))
-        assertTrue(visibleEntries(entries, signedIn(Role.PLAYER)).isNotEmpty())
-        assertTrue(visibleEntries(entries, signedIn(Role.ADMIN)).isEmpty())
+        for (role in listOf(Role.PLAYER, Role.ADMIN, Role.EDITOR, Role.MODERATOR)) {
+            assertTrue("$role should see a PLAYER entry", visibleEntries(entries, signedIn(role)).isNotEmpty())
+        }
+        assertTrue(visibleEntries(entries, signedIn(Role.UNKNOWN)).isEmpty())
         assertTrue(visibleEntries(entries, Session.SignedOut).isEmpty())
     }
 

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

@@ -0,0 +1,108 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.ui.navigation
+
+import com.runicgateway.app.core.auth.Role
+import com.runicgateway.app.core.auth.Session
+import com.runicgateway.app.core.auth.SessionUser
+import com.runicgateway.app.data.repository.ShardFeature
+import com.runicgateway.app.data.repository.ShardFeatures
+import com.runicgateway.app.ui.shard.ShardBoard
+import com.runicgateway.app.ui.shard.visibleBoards
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertTrue
+import org.junit.Test
+
+/**
+ * The second gate on a shard entry (PLAN.md §5, §9 M11): the shard's admin-configured
+ * visibility, independent of the session role. A signed-in admin still doesn't see a
+ * board the shard doesn't publish, and an anonymous visitor still doesn't see a
+ * signed-in entry however wide the feature config is.
+ */
+class MenuFeatureGatingTest {
+
+    private fun signedIn(role: Role) =
+        Session.SignedIn(SessionUser(id = 1, username = "u", role = role))
+
+    private fun features(vararg visible: String) =
+        ShardFeatures(level = "anonymous", visible = visible.toSet())
+
+    private val shardEntry = MenuEntry("shard", 0, MenuAccess.PUBLIC, feature = ShardFeature.STATUS)
+    private val plainEntry = MenuEntry("news", 0, MenuAccess.PUBLIC)
+
+    @Test fun aShardEntryHidesWhenItsFeatureIsNotVisible() {
+        val entries = listOf(plainEntry, shardEntry)
+
+        val visible = visibleEntries(entries, Session.SignedOut, features("champs")).map { it.route }
+
+        assertEquals(listOf("news"), visible)
+    }
+
+    @Test fun aShardEntryShowsWhenItsFeatureIsVisible() {
+        val entries = listOf(plainEntry, shardEntry)
+
+        val visible = visibleEntries(entries, Session.SignedOut, features("status")).map { it.route }
+
+        assertEquals(listOf("news", "shard"), visible)
+    }
+
+    @Test fun unknownFeaturesShowEverythingTheRoleAllows() {
+        // Fail open while the lookup is in flight or has failed — the server gates
+        // regardless, so a link that briefly 403s beats a nav that flickers in.
+        val entries = listOf(plainEntry, shardEntry)
+
+        val visible = visibleEntries(entries, Session.SignedOut, features = null).map { it.route }
+
+        assertEquals(listOf("news", "shard"), visible)
+    }
+
+    @Test fun theTwoGatesAreIndependent() {
+        val staffShardEntry = MenuEntry("s", 0, MenuAccess.STAFF, feature = ShardFeature.HOUSES)
+        val entries = listOf(staffShardEntry)
+
+        // Right role, feature switched off → hidden.
+        assertTrue(visibleEntries(entries, signedIn(Role.ADMIN), features("champs")).isEmpty())
+        // Feature on, wrong role → hidden.
+        assertTrue(visibleEntries(entries, signedIn(Role.PLAYER), features("houses")).isEmpty())
+        // Both → shown.
+        assertFalse(visibleEntries(entries, signedIn(Role.ADMIN), features("houses")).isEmpty())
+    }
+
+    @Test fun anAdminDoesNotBypassAFeatureGate() {
+        // The rung the server placed the caller on is what /features already accounts
+        // for. A staff role is not a licence to render a link to a disabled feature —
+        // a disabled feature 404s for everyone.
+        val entries = listOf(shardEntry)
+
+        assertTrue(visibleEntries(entries, signedIn(Role.ADMIN), features()).isEmpty())
+    }
+
+    @Test fun everyShardMenuEntryDeclaresAFeature() {
+        // A shard-derived entry with no feature name silently skips the gate. The app
+        // menu's only such entry today is the Shard hub; this fails if one is added
+        // without one.
+        val shardRoutes = APP_MENU.filter { it.route == Routes.SHARD }
+        assertTrue(shardRoutes.isNotEmpty())
+        assertTrue(shardRoutes.all { it.feature != null })
+    }
+
+    // ── The hub's board tiles use the same gate ──────────────────────────
+    @Test fun hubBoardsAreFilteredByFeature() {
+        val visible = visibleBoards(features("champs", "houses"))
+
+        assertEquals(listOf(ShardBoard.CHAMPS, ShardBoard.HOUSES), visible)
+    }
+
+    @Test fun hubBoardsShowAllWhenTheAnswerIsUnknown() {
+        assertEquals(ShardBoard.entries.toList(), visibleBoards(null))
+    }
+
+    @Test fun eachBoardMapsToItsOwnFeature() {
+        assertEquals(ShardFeature.CHAMPS, ShardBoard.CHAMPS.feature)
+        assertEquals(ShardFeature.GUILDS, ShardBoard.GUILDS.feature)
+        assertEquals(ShardFeature.GOVERNORS, ShardBoard.GOVERNORS.feature)
+        assertEquals(ShardFeature.HOUSES, ShardBoard.HOUSES.feature)
+    }
+}

app/src/test/java/com/runicgateway/app/ui/player/CharacterSheetHelpersTest.kt

@@ -3,14 +3,18 @@
  */
 package com.runicgateway.app.ui.player
 
+import com.runicgateway.app.data.api.dto.CharPointsDto
+import com.runicgateway.app.data.api.dto.CharProfileDto
+import com.runicgateway.app.data.api.dto.EquipmentDto
 import com.runicgateway.app.data.api.dto.TitlesDto
 import org.junit.Assert.assertEquals
+import org.junit.Assert.assertNull
 import org.junit.Test
 
 /**
  * Unit tests for the character-sheet display helpers (PLAN.md §6.3), mirroring the
- * website's `CharacterSheet.jsx#displayTitles`: fame/karma + skill + a *literal*
- * selected reward title, dropping bare cliloc numbers the app can't resolve.
+ * website's `CharacterSheet.jsx`: title selection over the server's cliloc-resolved
+ * parallel array, item naming precedence, and the Protocol 3.0 points block.
  */
 class CharacterSheetHelpersTest {
 
@@ -51,4 +55,100 @@ class CharacterSheetHelpersTest {
         val titles = TitlesDto(selected = 0, reward = listOf("The Great"), fameKarma = "The Great")
         assertEquals(listOf("The Great"), displayTitles(titles))
     }
+
+    // ── Cliloc-resolved titles (Protocol 3.0 §8.6) ───────────────────────
+
+    @Test fun displayTitlesPrefersTheServerResolvedRewardName() {
+        // The website resolves the numeric entries against its own cliloc table and
+        // sends a parallel array; the raw number is no longer the only thing we have.
+        val titles = TitlesDto(
+            selected = 0,
+            reward = listOf("1049565"),
+            rewardResolved = listOf("Knight of Trinsic"),
+        )
+        assertEquals(listOf("Knight of Trinsic"), displayTitles(titles))
+    }
+
+    @Test fun displayTitlesKeepsSelectedAlignedWhenAnEntryDoesNotResolve() {
+        // rewardResolved is POSITIONAL. An entry the table had nothing for is null and
+        // must be skipped WITHOUT shifting `selected` onto its neighbour — otherwise
+        // the sheet confidently shows the wrong title.
+        val titles = TitlesDto(
+            selected = 1,
+            reward = listOf("1049565", "1049566"),
+            rewardResolved = listOf(null, "Knight of Trinsic"),
+        )
+        assertEquals(listOf("Knight of Trinsic"), displayTitles(titles))
+    }
+
+    @Test fun displayTitlesFallsBackWhenTheSelectedTitleDidNotResolve() {
+        val titles = TitlesDto(
+            selected = 0,
+            reward = listOf("1049565", "1049566"),
+            rewardResolved = listOf(null, "Bane of Dragons"),
+        )
+        assertEquals(listOf("Bane of Dragons"), displayTitles(titles))
+    }
+
+    @Test fun displayTitlesStillSkipsNumbersWhenNothingResolved() {
+        // A shard that configures no cliloc table sends no rewardResolved at all —
+        // the pre-3.0 behavior, unchanged.
+        val titles = TitlesDto(selected = 0, reward = listOf("1049565"), rewardResolved = emptyList())
+        assertEquals(emptyList<String>(), displayTitles(titles))
+    }
+
+    // ── Equipment names ──────────────────────────────────────────────────
+
+    @Test fun itemLabelPrefersAPlayerGivenNameOverTheResolvedTypeName() {
+        // "Bob's lucky axe" must not be relabelled "hatchet".
+        val item = EquipmentDto(layer = "OneHanded", name = "Bob's lucky axe", clilocName = "hatchet")
+        assertEquals("Bob's lucky axe", item.label)
+    }
+
+    @Test fun itemLabelFallsBackThroughClilocNameThenLayer() {
+        assertEquals("hatchet", EquipmentDto(layer = "OneHanded", clilocName = "hatchet").label)
+        assertEquals("OneHanded", EquipmentDto(layer = "OneHanded").label)
+        assertNull(EquipmentDto().label)
+    }
+
+    // ── Loyalty & points (Protocol 3.0 §7.3) ─────────────────────────────
+
+    @Test fun pointsLabelUsesTheHumanisedKeyWhenTheNameIsACliloc() {
+        // The PRIMARY path on a real shard: most systems name themselves with a
+        // cliloc, so nameString comes back null.
+        assertEquals("Queens Loyalty", pointsLabel(CharPointsDto(system = "QueensLoyalty")))
+        assertEquals("Clean Up Britannia", pointsLabel(CharPointsDto(system = "CleanUpBritannia")))
+        assertEquals("Void Pool", pointsLabel(CharPointsDto(system = "VoidPool")))
+    }
+
+    @Test fun pointsLabelPrefersTheShardsOwnNameWhenItHasOne() {
+        val entry = CharPointsDto(system = "QueensLoyalty", nameString = "Queen's Loyalty")
+        assertEquals("Queen's Loyalty", pointsLabel(entry))
+    }
+
+    @Test fun anUncappedSystemReportsNoCap() {
+        // maxPoints 0 means UNCAPPED and is the common case — three of five live
+        // boards on a real shard. Nothing may divide by it.
+        assertNull(CharPointsDto(points = 900, maxPoints = 0).cap)
+        assertNull(CharPointsDto(points = 900, maxPoints = null).cap)
+        assertEquals(30000L, CharPointsDto(points = 900, maxPoints = 30000).cap)
+    }
+
+    @Test fun displayPointsDropsZeroesAndSortsByStandingDescending() {
+        val char = CharProfileDto(
+            points = listOf(
+                CharPointsDto(system = "A", points = 10),
+                CharPointsDto(system = "Zero", points = 0),
+                CharPointsDto(system = "B", points = 500),
+                CharPointsDto(system = "Null", points = null),
+            ),
+        )
+        assertEquals(listOf("B", "A"), displayPoints(char).map { it.system })
+    }
+
+    @Test fun displayPointsIsEmptyForAProfileWithNoPointsBlock() {
+        // A pre-3.0 shard plugin sends none, and a new character has earned nothing —
+        // both render as nothing at all rather than an empty card.
+        assertEquals(emptyList<CharPointsDto>(), displayPoints(CharProfileDto()))
+    }
 }

app/src/test/java/com/runicgateway/app/ui/player/CharactersViewModelTest.kt

@@ -0,0 +1,89 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.ui.player
+
+import com.runicgateway.app.R
+import com.runicgateway.app.data.api.dto.RosterCharDto
+import com.runicgateway.app.data.api.dto.RosterDto
+import com.runicgateway.app.data.api.dto.SettingsDto
+import com.runicgateway.app.data.api.dto.ShardLinkDto
+import com.runicgateway.app.data.api.dto.ShardLinkResultDto
+import com.runicgateway.app.data.api.fake.FakePlayerShardApi
+import com.runicgateway.app.data.api.fake.FakePublicApi
+import com.runicgateway.app.data.repository.PlayerShardRepository
+import com.runicgateway.app.data.repository.SettingsRepository
+import com.runicgateway.app.ui.UiState
+import com.runicgateway.app.util.MainDispatcherRule
+import com.runicgateway.app.util.httpError
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertTrue
+import org.junit.Rule
+import org.junit.Test
+
+class CharactersViewModelTest {
+
+    @get:Rule val mainDispatcher = MainDispatcherRule()
+
+    private val playerApi = FakePlayerShardApi()
+    private val publicApi = FakePublicApi()
+    private fun viewModel() = CharactersViewModel(
+        PlayerShardRepository(playerApi),
+        SettingsRepository(publicApi),
+    )
+
+    @Test fun loadsAccountsRostersAndSignupFlag() {
+        playerApi.accounts = listOf(ShardLinkDto(account = "acct1"))
+        playerApi.roster = RosterDto(acct = "acct1", chars = listOf(RosterCharDto(serial = "0x24C", name = "Gwen")))
+        publicApi.settings = SettingsDto(gameAccountSignup = true)
+        val vm = viewModel()
+
+        assertEquals(listOf("acct1"), (vm.state.value.accounts as UiState.Success).data)
+        val roster = vm.state.value.rosters["acct1"]
+        assertTrue(roster is UiState.Success)
+        assertEquals("Gwen", (roster as UiState.Success).data.first().name)
+        assertTrue(vm.state.value.signupEnabled)
+    }
+
+    @Test fun accountsErrorSurfacesError() {
+        playerApi.error = httpError(503)
+        assertTrue(viewModel().state.value.accounts is UiState.Error)
+    }
+
+    @Test fun linkBlankCodeIsIgnored() {
+        val vm = viewModel()
+        vm.link("   ")
+        assertEquals(null, vm.state.value.feedback)
+    }
+
+    @Test fun linkSuccessShowsOkAndReloads() {
+        playerApi.linkResult = ShardLinkResultDto(linked = true, account = "acct1")
+        val vm = viewModel()
+        vm.link("CODE1")
+        val fb = vm.state.value.feedback!!
+        assertTrue(fb.ok)
+        assertEquals(R.string.player_link_ok, fb.messageRes)
+        assertFalse(vm.state.value.busy)
+    }
+
+    @Test fun linkBadCodeMapsTo400Copy() {
+        playerApi.error = httpError(400)
+        val vm = viewModel()
+        vm.link("BAD")
+        assertEquals(R.string.player_link_bad_code, vm.state.value.feedback!!.messageRes)
+    }
+
+    @Test fun createAccountRejectsShortPasswordWithoutApiCall() {
+        val vm = viewModel()
+        vm.createAccount(account = "acct1", password = "short") // < 8 chars
+        assertEquals(null, vm.state.value.feedback) // guarded before any call/feedback
+    }
+
+    @Test fun createAccountTakenMapsTo409Copy() {
+        playerApi.error = httpError(409)
+        val vm = viewModel()
+        vm.createAccount(account = "acct1", password = "longenough")
+        assertEquals(R.string.player_create_taken, vm.state.value.feedback!!.messageRes)
+    }
+}

app/src/test/java/com/runicgateway/app/ui/player/PlayerViewModelTest.kt

@@ -0,0 +1,83 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.ui.player
+
+import androidx.lifecycle.SavedStateHandle
+import com.runicgateway.app.data.api.dto.CharProfileDto
+import com.runicgateway.app.data.api.dto.PlayerHouseDto
+import com.runicgateway.app.data.api.dto.ShardLinkDto
+import com.runicgateway.app.data.api.dto.VendorDto
+import com.runicgateway.app.data.api.dto.VendorSaleDto
+import com.runicgateway.app.data.api.dto.VendorSnapshotDto
+import com.runicgateway.app.data.api.fake.FakePlayerShardApi
+import com.runicgateway.app.data.repository.PlayerShardRepository
+import com.runicgateway.app.ui.ErrorKind
+import com.runicgateway.app.ui.UiState
+import com.runicgateway.app.ui.navigation.Routes
+import com.runicgateway.app.util.MainDispatcherRule
+import com.runicgateway.app.util.httpError
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertTrue
+import org.junit.Rule
+import org.junit.Test
+
+/** ViewModels over the player self-service game-data API (own chars, vendors, houses). */
+class PlayerViewModelTest {
+
+    @get:Rule val mainDispatcher = MainDispatcherRule()
+
+    private val api = FakePlayerShardApi()
+    private val repository = PlayerShardRepository(api)
+
+    // ── My houses ───────────────────────────────────────────────────────────
+    @Test fun myHousesLoadsOwnHouses() {
+        api.houses = listOf(PlayerHouseDto(serial = "0x40001", name = "Keep", isIdoc = false))
+        val vm = MyHousesViewModel(repository)
+        assertEquals("Keep", (vm.state.value as UiState.Success).data.first().name)
+    }
+
+    @Test fun myHousesShardOfflineIsShardOfflineError() {
+        api.error = httpError(503)
+        val state = MyHousesViewModel(repository).state.value
+        assertEquals(ErrorKind.SHARD_OFFLINE, (state as UiState.Error).kind)
+    }
+
+    // ── Character sheet (SavedStateHandle serial) ─────────────────────────────
+    @Test fun characterLoadsBySerial() {
+        api.char = CharProfileDto(serial = "0x24C", name = "Gwen", online = true)
+        val vm = CharacterViewModel(repository, SavedStateHandle(mapOf(Routes.Args.SERIAL to "0x24C")))
+        assertEquals("Gwen", (vm.state.value as UiState.Success).data.name)
+    }
+
+    @Test fun characterForbiddenIsNotFound() {
+        api.error = httpError(403)
+        val vm = CharacterViewModel(repository, SavedStateHandle(mapOf(Routes.Args.SERIAL to "0x1")))
+        // 403 isn't a mapped status -> SERVER bucket (only 404/429/503 are special-cased).
+        assertTrue(vm.state.value is UiState.Error)
+    }
+
+    // ── Vendors (per-account snapshots + sales) ───────────────────────────────
+    @Test fun vendorsLoadsAccountsThenPerAccountSnapshots() {
+        api.accounts = listOf(ShardLinkDto(account = "acct1"))
+        api.vendors = VendorSnapshotDto(acct = "acct1", vendors = listOf(VendorDto(serial = "0x9", shopName = "Wares")))
+        api.sales = listOf(VendorSaleDto(itemType = "sword", price = 100))
+        val vm = VendorsViewModel(repository)
+
+        val accounts = vm.state.value.accounts
+        assertTrue(accounts is UiState.Success)
+        assertEquals(listOf("acct1"), (accounts as UiState.Success).data)
+        // Each account's vendors loaded into the per-account map.
+        val perAccount = vm.state.value.vendors["acct1"]
+        assertTrue(perAccount is UiState.Success)
+        assertEquals("Wares", (perAccount as UiState.Success).data.first().shopName)
+        assertTrue(vm.state.value.sales is UiState.Success)
+    }
+
+    @Test fun vendorsAccountsErrorSurfacesError() {
+        api.error = java.io.IOException("offline")
+        val vm = VendorsViewModel(repository)
+        assertTrue(vm.state.value.accounts is UiState.Error)
+        assertTrue(vm.state.value.sales is UiState.Error)
+    }
+}

app/src/test/java/com/runicgateway/app/ui/shard/FrameFieldsTest.kt

@@ -0,0 +1,44 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.ui.shard
+
+import kotlinx.serialization.json.JsonNull
+import kotlinx.serialization.json.JsonObject
+import kotlinx.serialization.json.JsonPrimitive
+import kotlinx.serialization.json.buildJsonObject
+import kotlinx.serialization.json.put
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertNull
+import org.junit.Test
+
+/**
+ * [FrameFields] does minimal typed reads from a raw SSE frame object for the
+ * fields a `*.remove` / `*.decay` delta needs; it must return null (not crash) on
+ * a missing or ill-typed field so a malformed frame is skipped.
+ */
+class FrameFieldsTest {
+
+    @Test fun longFieldParsesNumericPrimitive() {
+        val obj = buildJsonObject { put("serial", "12345") }
+        assertEquals(12345L, FrameFields.longField(obj, "serial"))
+    }
+
+    @Test fun longFieldReturnsNullOnMissingOrNonNumeric() {
+        val obj = buildJsonObject { put("serial", "0xNaN") }
+        assertNull(FrameFields.longField(obj, "serial"))     // not a Long
+        assertNull(FrameFields.longField(obj, "absent"))     // missing key
+    }
+
+    @Test fun longFieldReturnsNullOnJsonNullOrObject() {
+        val obj = JsonObject(mapOf("a" to JsonNull, "b" to JsonObject(emptyMap())))
+        assertNull(FrameFields.longField(obj, "a"))
+        assertNull(FrameFields.longField(obj, "b"))
+    }
+
+    @Test fun stringFieldReadsPrimitiveContent() {
+        val obj = JsonObject(mapOf("kind" to JsonPrimitive("champ.remove")))
+        assertEquals("champ.remove", FrameFields.stringField(obj, "kind"))
+        assertNull(FrameFields.stringField(obj, "missing"))
+    }
+}

app/src/test/java/com/runicgateway/app/ui/shard/ShardBoardViewModelTest.kt

@@ -0,0 +1,128 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.ui.shard
+
+import com.runicgateway.app.core.net.ShardStreamEvent
+import com.runicgateway.app.data.api.dto.ChampDto
+import com.runicgateway.app.data.api.dto.GovernorDto
+import com.runicgateway.app.data.api.dto.GuildDto
+import com.runicgateway.app.data.api.dto.HouseDto
+import com.runicgateway.app.data.api.dto.PresenceDto
+import com.runicgateway.app.data.api.dto.ShardStatusDto
+import com.runicgateway.app.data.api.fake.FakePublicApi
+import com.runicgateway.app.data.api.fake.FakeShardStream
+import com.runicgateway.app.data.repository.ShardFeaturesRepository
+import com.runicgateway.app.data.repository.ShardRepository
+import com.runicgateway.app.ui.UiState
+import com.runicgateway.app.util.MainDispatcherRule
+import com.runicgateway.app.util.httpError
+import kotlinx.serialization.json.Json
+import kotlinx.serialization.json.buildJsonObject
+import kotlinx.serialization.json.put
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertTrue
+import org.junit.Rule
+import org.junit.Test
+
+/**
+ * The live-board ViewModels (§6.2): a snapshot load kept live by merging SSE
+ * frames. Tests use a [FakeShardStream] that emits a fixed script and completes,
+ * so both the snapshot path and the frame-merge path are covered deterministically.
+ */
+class ShardBoardViewModelTest {
+
+    @get:Rule val mainDispatcher = MainDispatcherRule()
+
+    private val api = FakePublicApi()
+    private val json = Json { ignoreUnknownKeys = true; explicitNulls = false; coerceInputValues = true }
+
+    private fun repo(stream: FakeShardStream = FakeShardStream()) = ShardRepository(api, stream, json)
+
+    // The hub reads the feature set only to filter its board tiles; these tests
+    // exercise loading, so the answer stays at its "unknown" default (show all).
+    private fun features() = ShardFeaturesRepository(api)
+
+    // ── Champs: snapshot + live upsert/remove ─────────────────────────────
+    @Test fun champsSeedsSnapshotAndMergesLiveFrames() {
+        api.champs = listOf(ChampDto(serial = "0x1", category = "champion", name = "Rikktor"))
+        val stream = FakeShardStream(
+            listOf(
+                ShardStreamEvent.Open,
+                ShardStreamEvent.Frame(
+                    "champ.update",
+                    buildJsonObject { put("serial", "0x2"); put("category", "mini"); put("name", "Barracoon") },
+                ),
+                ShardStreamEvent.Frame("champ.remove", buildJsonObject { put("serial", "0x1") }),
+            ),
+        )
+        val vm = ChampsViewModel(repo(stream))
+        val rows = (vm.state.value as UiState.Success).data
+        // 0x1 removed, 0x2 upserted.
+        assertEquals(listOf("0x2"), rows.map { it.serial })
+        assertTrue(vm.connected.value) // Open was seen
+    }
+
+    @Test fun champsServerErrorIsUiError() {
+        api.error = httpError(503)
+        assertTrue(ChampsViewModel(repo()).state.value is UiState.Error)
+    }
+
+    // ── Guilds ────────────────────────────────────────────────────────────
+    @Test fun guildsSnapshotThenLiveUpdate() {
+        api.guilds = listOf(GuildDto(id = 1, name = "Knights"))
+        val stream = FakeShardStream(
+            listOf(ShardStreamEvent.Frame("guild.update", buildJsonObject { put("id", 2); put("name", "Mages") })),
+        )
+        val vm = GuildsViewModel(repo(stream))
+        val names = (vm.state.value as UiState.Success).data.map { it.name }
+        assertTrue(names.contains("Knights"))
+        assertTrue(names.contains("Mages"))
+    }
+
+    // ── Governors (+ history) ─────────────────────────────────────────────
+    @Test fun governorsSnapshotAndHistory() {
+        api.governors = listOf(GovernorDto(city = "Britain"))
+        api.governorHistory = listOf() // empty is fine
+        val vm = GovernorsViewModel(repo())
+        assertTrue(vm.state.value is UiState.Success)
+        vm.loadHistory("Britain")
+        assertTrue(vm.history.value.containsKey("Britain"))
+    }
+
+    // ── Houses (IDOC board) ───────────────────────────────────────────────
+    @Test fun housesSnapshotLoads() {
+        api.houses = listOf(HouseDto(serial = "0x40", name = "Tower", isIdoc = true))
+        val vm = HousesViewModel(repo())
+        assertEquals("Tower", (vm.state.value as UiState.Success).data.first().name)
+    }
+
+    @Test fun housesNetworkErrorIsUiError() {
+        api.error = java.io.IOException("offline")
+        assertTrue(HousesViewModel(repo()).state.value is UiState.Error)
+    }
+
+    // ── Shard hub (status primary, presence/online best-effort, live feed) ─
+    @Test fun shardHubLoadsStatusPresenceOnlineAndSeedsFeed() {
+        api.shardStatus = ShardStatusDto(enabled = true, pluginConnected = true, onlineCount = 5)
+        api.shardPresence = PresenceDto(count = 5)
+        val stream = FakeShardStream(
+            listOf(
+                ShardStreamEvent.Closed,
+                ShardStreamEvent.Frame("presence.online", buildJsonObject { put("count", 9) }),
+            ),
+        )
+        val vm = ShardViewModel(repo(stream), features())
+        val hub = (vm.state.value as UiState.Success).data
+        assertTrue(hub.status.isOnline)
+        // presence.online frame patched the count in place.
+        assertEquals(9, hub.presence!!.count)
+        assertFalse(vm.connected.value) // last lifecycle event was Closed
+    }
+
+    @Test fun shardHubStatusErrorIsUiError() {
+        api.error = httpError(503)
+        assertTrue(ShardViewModel(repo(), features()).state.value is UiState.Error)
+    }
+}

app/src/test/java/com/runicgateway/app/ui/shard/ShardContentHelpersTest.kt

@@ -0,0 +1,184 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.ui.shard
+
+import com.runicgateway.app.data.api.dto.AtlasCreatureDto
+import com.runicgateway.app.data.api.dto.AtlasPlaceDto
+import com.runicgateway.app.data.api.dto.AtlasSpawnerDto
+import com.runicgateway.app.data.api.dto.MarketListingDto
+import com.runicgateway.app.data.api.dto.MarketLocationDto
+import com.runicgateway.app.data.api.dto.PointsBoardDto
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertNull
+import org.junit.Test
+
+/**
+ * The pure display helpers behind the four Protocol 3.0 screens (PLAN.md §9 M11).
+ * Each one exists because the raw wire value would be wrong or misleading on screen —
+ * units in tenths, delays in seconds, an "uncapped" cap of zero, a gated field.
+ */
+class ShardContentHelpersTest {
+
+    // ── Rules (§5) ───────────────────────────────────────────────────────
+
+    @Test fun skillCapsConvertOutOfTenths() {
+        // 1000 is 100.0. Showing the raw number reads as a shard with ten times the
+        // usual limit, which is worse than showing nothing.
+        assertEquals("100", formatSkillCap(1000 / 10.0))
+        assertEquals("72.5", formatSkillCap(725 / 10.0))
+    }
+
+    @Test fun systemKeysHumanise() {
+        // Word boundaries become spaces and the inner capital is kept, matching the
+        // website's `humanise` — "City Loyalty" is the system's actual name.
+        assertEquals("City Loyalty", humaniseSystem("cityLoyalty"))
+        assertEquals("Vvv", humaniseSystem("vvv"))
+        assertEquals("Treasure Maps", humaniseSystem("treasureMaps"))
+    }
+
+    @Test fun theRestartScheduleOnlyShowsWhenTheShardRunsOne() {
+        assertEquals("04:30", formatRestart(enabled = true, hour = 4, minute = 30))
+        assertEquals("04:00", formatRestart(enabled = true, hour = 4, minute = null))
+        assertNull(formatRestart(enabled = false, hour = 4, minute = 30))
+        assertNull(formatRestart(enabled = true, hour = null, minute = 30))
+    }
+
+    // ── Leaderboards (§7) ────────────────────────────────────────────────
+
+    @Test fun boardLabelFallsBackToTheHumanisedKey() {
+        // The PRIMARY path: four of five boards on a real shard name themselves with a
+        // cliloc and send nameString null.
+        assertEquals("Queens Loyalty", boardLabel(PointsBoardDto(system = "QueensLoyalty")))
+        assertEquals(
+            "Queen's Loyalty",
+            boardLabel(PointsBoardDto(system = "QueensLoyalty", nameString = "Queen's Loyalty")),
+        )
+        assertEquals("Clean Up Britannia", boardLabel(PointsBoardDto(system = "CleanUpBritannia", nameString = "  ")))
+    }
+
+    @Test fun anUncappedBoardReportsNoCap() {
+        assertNull(PointsBoardDto(maxPoints = 0).cap)
+        assertEquals(30000L, PointsBoardDto(maxPoints = 30000).cap)
+    }
+
+    @Test fun boardsOrderByContestedThenName() {
+        val boards = listOf(
+            PointsBoardDto(system = "Quiet", players = 2),
+            PointsBoardDto(system = "Busy", players = 900),
+            PointsBoardDto(system = "AlsoQuiet", players = 2),
+        )
+        assertEquals(listOf("Busy", "Also Quiet", "Quiet"), orderBoards(boards).map { boardLabel(it) })
+    }
+
+    @Test fun boardsTheShardHidesFromItsOwnGumpAreDropped() {
+        // `showOnGump` is the shard's own "is this player-facing?" signal.
+        val boards = listOf(
+            PointsBoardDto(system = "Shown", players = 1, showOnGump = true),
+            PointsBoardDto(system = "Internal", players = 99, showOnGump = false),
+        )
+        assertEquals(listOf("Shown"), orderBoards(boards).map { it.system })
+    }
+
+    // ── Market (§8) ──────────────────────────────────────────────────────
+
+    @Test fun listingTitlePrefersAPlayerNameThenTheResolvedOne() {
+        assertEquals("Bob's axe", listingTitle(MarketListingDto(name = "Bob's axe", displayName = "hatchet")))
+        assertEquals("hatchet", listingTitle(MarketListingDto(displayName = "hatchet")))
+    }
+
+    @Test fun listingTitleIsNullWithoutAnyName() {
+        // A shard with no cliloc table configured publishes neither, and the screen
+        // falls back to the item id rather than inventing a label.
+        assertNull(listingTitle(MarketListingDto(itemId = 3922)))
+    }
+
+    @Test fun aStackShowsItsCount() {
+        // "12 × ingot" and "ingot" at the same price are very different offers.
+        assertEquals("12 × ingot", listingTitle(MarketListingDto(displayName = "ingot", amount = 12)))
+        assertEquals("ingot", listingTitle(MarketListingDto(displayName = "ingot", amount = 1)))
+        assertEquals("ingot", listingTitle(MarketListingDto(displayName = "ingot", amount = null)))
+    }
+
+    @Test fun locationPrefersTheHouseThenTheRegion() {
+        assertEquals(
+            "Darrow's Tower, Felucca",
+            locationLine(MarketLocationDto(map = "Felucca", region = "Britain", house = "Darrow's Tower")),
+        )
+        assertEquals("Britain, Felucca", locationLine(MarketLocationDto(map = "Felucca", region = "Britain")))
+        assertEquals("Felucca", locationLine(MarketLocationDto(map = "Felucca")))
+    }
+
+    @Test fun aGatedLocationIsNullRatherThanAHalfAnswer() {
+        // The block is nested precisely so one admin rule takes the facet, the
+        // coordinates, the region and the house together — there is no partial state
+        // to render.
+        assertNull(locationLine(null))
+        assertNull(locationLine(MarketLocationDto(x = 100, y = 200)))
+    }
+
+    // ── Atlas (§6) ───────────────────────────────────────────────────────
+
+    @Test fun respawnDelaysAreReadAsSeconds() {
+        // The API normalises XmlSpawner's mixed minutes/seconds, so these ARE seconds.
+        assertEquals("30s", formatRespawn(30, 30))
+        assertEquals("5m", formatRespawn(300, 300))
+        assertEquals("5m–10m", formatRespawn(300, 600))
+        assertEquals("1m 30s", formatRespawn(90, 90))
+    }
+
+    @Test fun aHalfSpecifiedRespawnStillReads() {
+        assertEquals("5m", formatRespawn(300, null))
+        assertEquals("5m", formatRespawn(null, 300))
+        assertNull(formatRespawn(null, null))
+    }
+
+    @Test fun spawnerPlacePrefersTheServersPlacementLabel() {
+        // The point-in-rect transform is the reason this feature exists: it turns
+        // "5411,1234" into "Despise, Felucca".
+        val spawner = AtlasSpawnerDto(
+            label = "Despise, Felucca",
+            region = "Despise",
+            facet = "Felucca",
+            x = 5411,
+            y = 1234,
+        )
+        assertEquals("Despise, Felucca", spawnerPlace(spawner))
+    }
+
+    @Test fun spawnerPlaceFallsBackThroughRegionLandmarkThenCoordinates() {
+        assertEquals(
+            "Despise, Felucca",
+            spawnerPlace(AtlasSpawnerDto(region = "Despise", facet = "Felucca")),
+        )
+        assertEquals(
+            "Yew Crossroads, Trammel",
+            spawnerPlace(AtlasSpawnerDto(landmark = "Yew Crossroads", facet = "Trammel")),
+        )
+        // ~17% of stock spawns resolve to no named place; coordinates are honest there.
+        assertEquals(
+            "Felucca 5411, 1234",
+            spawnerPlace(AtlasSpawnerDto(facet = "Felucca", x = 5411, y = 1234)),
+        )
+    }
+
+    @Test fun placeLabelUsesTheServersResolvedNameAndFallsBackToTheFacet() {
+        assertEquals(
+            "Isamu-Jima",
+            placeLabel(AtlasPlaceDto(facet = "Tokuno", label = "Isamu-Jima", spawners = 4)),
+        )
+        // The server already falls back to "Wilderness", so a label-less place is the
+        // degenerate case; the facet still says something, an empty row does not.
+        assertEquals("Tokuno", placeLabel(AtlasPlaceDto(facet = "Tokuno")))
+        assertEquals("Tokuno", placeLabel(AtlasPlaceDto(facet = "Tokuno", label = "  ")))
+    }
+
+    @Test fun facetSummaryLeadsWithWhereItMostlyIs() {
+        val creature = AtlasCreatureDto(
+            slug = "lizardman",
+            facets = mapOf("Trammel" to 4, "Felucca" to 30, "Ilshenar" to 12),
+        )
+        assertEquals("Felucca, Ilshenar, Trammel", facetSummary(creature))
+        assertNull(facetSummary(AtlasCreatureDto(slug = "unique")))
+    }
+}

app/src/test/java/com/runicgateway/app/ui/shard/ShardContentViewModelTest.kt

@@ -0,0 +1,223 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.ui.shard
+
+import com.runicgateway.app.core.net.ShardStreamEvent
+import com.runicgateway.app.data.api.dto.AtlasCreatureDto
+import com.runicgateway.app.data.api.dto.AtlasCreaturePageDto
+import com.runicgateway.app.data.api.dto.MarketListingDto
+import com.runicgateway.app.data.api.dto.MarketPageDto
+import com.runicgateway.app.data.api.dto.MarketVendorDto
+import com.runicgateway.app.data.api.dto.PointsBoardDto
+import com.runicgateway.app.data.api.dto.RulesetDto
+import com.runicgateway.app.data.api.fake.FakePublicApi
+import com.runicgateway.app.data.api.fake.FakeShardStream
+import com.runicgateway.app.data.repository.ShardRepository
+import com.runicgateway.app.ui.ErrorKind
+import com.runicgateway.app.ui.UiState
+import com.runicgateway.app.util.MainDispatcherRule
+import com.runicgateway.app.util.httpError
+import kotlinx.serialization.json.Json
+import kotlinx.serialization.json.buildJsonObject
+import kotlinx.serialization.json.put
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertNull
+import org.junit.Assert.assertTrue
+import org.junit.Rule
+import org.junit.Test
+
+/**
+ * The four Protocol 3.0 content screens (PLAN.md §9 M11): loading, the live merge, and
+ * the states that are easy to get wrong — "published nothing" vs "switched off", and a
+ * gated feature reading as unavailable rather than as a fault.
+ */
+class ShardContentViewModelTest {
+
+    @get:Rule val mainDispatcherRule = MainDispatcherRule()
+
+    private val api = FakePublicApi()
+    private val json = Json { ignoreUnknownKeys = true; explicitNulls = false; coerceInputValues = true }
+
+    private fun repo(stream: FakeShardStream = FakeShardStream()) = ShardRepository(api, stream, json)
+
+    // ── Rules ────────────────────────────────────────────────────────────
+
+    @Test fun rulesLoadTheRuleset() {
+        api.ruleset = RulesetDto(shard = "UOMysticmoon", expansion = "EJ")
+
+        val state = RulesViewModel(repo()).state.value
+
+        assertEquals("UOMysticmoon", (state as UiState.Success).data?.shard)
+    }
+
+    @Test fun anUnpublishedRulesetIsASuccessWithNoBody() {
+        // Distinct from the feature being switched off: the shard is reachable and
+        // simply hasn't emitted world.ruleset yet.
+        api.ruleset = null
+
+        val state = RulesViewModel(repo()).state.value
+
+        assertTrue(state is UiState.Success)
+        assertNull((state as UiState.Success).data)
+    }
+
+    @Test fun aGatedRulesetFeatureReadsAsUnavailableNotAsAFault() {
+        api.error = httpError(404)
+
+        val state = RulesViewModel(repo()).state.value
+
+        assertEquals(ErrorKind.FEATURE_UNAVAILABLE, (state as UiState.Error).kind)
+    }
+
+    @Test fun aLiveRulesetFrameReplacesTheLoadedCopy() {
+        // The frame IS the whole ruleset — the shard re-emits it on every reconnect, so
+        // a restart with edited config updates an open screen.
+        api.ruleset = RulesetDto(shard = "Old", expansion = "EJ")
+        val stream = FakeShardStream(
+            listOf(
+                ShardStreamEvent.Frame(
+                    "world.ruleset",
+                    buildJsonObject { put("shard", "New"); put("expansion", "EJ") },
+                ),
+            ),
+        )
+
+        val state = RulesViewModel(repo(stream)).state.value
+
+        assertEquals("New", (state as UiState.Success).data?.shard)
+    }
+
+    // ── Leaderboards ─────────────────────────────────────────────────────
+
+    @Test fun leaderboardsSeedAndMergeLiveBoards() {
+        api.pointsBoards = listOf(
+            PointsBoardDto(system = "QueensLoyalty", players = 800),
+            PointsBoardDto(system = "VoidPool", players = 10),
+        )
+        val stream = FakeShardStream(
+            listOf(
+                ShardStreamEvent.Frame(
+                    "points.board",
+                    buildJsonObject { put("system", "VoidPool"); put("players", 999) },
+                ),
+            ),
+        )
+
+        val boards = (LeaderboardsViewModel(repo(stream)).state.value as UiState.Success).data
+
+        // The merged board overtook the seeded one on the contested ordering.
+        assertEquals(listOf("VoidPool", "QueensLoyalty"), boards.map { it.system })
+    }
+
+    @Test fun aGatedLeaderboardsFeatureReadsAsUnavailable() {
+        api.error = httpError(403)
+
+        val state = LeaderboardsViewModel(repo()).state.value
+
+        assertEquals(ErrorKind.FEATURE_UNAVAILABLE, (state as UiState.Error).kind)
+    }
+
+    // ── Market ───────────────────────────────────────────────────────────
+
+    @Test fun marketLoadsListingsAndMeta() {
+        api.market = MarketPageDto(
+            listings = listOf(MarketListingDto(serial = "0x1", displayName = "hatchet", price = 250)),
+            total = 1,
+        )
+
+        val vm = MarketViewModel(repo())
+
+        assertEquals(1, (vm.state.value as UiState.Success).data.listings.size)
+    }
+
+    @Test fun aBlankMarketQueryIsNotSentAsAnEmptyFilter() {
+        MarketViewModel(repo())
+        assertNull(api.lastMarketQuery)
+    }
+
+    @Test fun theMarketQueryIsBoundedToWhatTheServerAccepts() {
+        // Trimmed here rather than bounced as a 400.
+        val vm = MarketViewModel(repo())
+        vm.onQueryChange("x".repeat(200))
+        assertEquals(MarketViewModel.MAX_QUERY, vm.query.value.length)
+    }
+
+    @Test fun aFailedMetaLookupDoesNotBlankTheResults() {
+        // Meta drives the staleness banner and the filter options; it is secondary.
+        api.market = MarketPageDto(listings = listOf(MarketListingDto(serial = "0x1")), total = 1)
+
+        val vm = MarketViewModel(repo())
+
+        assertTrue(vm.state.value is UiState.Success)
+    }
+
+    @Test fun aVendorLoadsBySerialAndKeepsItForRetry() {
+        api.marketVendor = MarketVendorDto(serial = "0x40001234", shopName = "Darrow's Wares", truncated = true)
+
+        val vm = MarketVendorViewModel(repo())
+        vm.load("0x40001234")
+
+        val vendor = (vm.state.value as UiState.Success).data
+        assertEquals("Darrow's Wares", vendor.shopName)
+        assertTrue(vendor.truncated)
+
+        // Retry re-uses the serial rather than needing it passed again.
+        api.error = httpError(500)
+        vm.retry()
+        assertTrue(vm.state.value is UiState.Error)
+    }
+
+    // ── Atlas ────────────────────────────────────────────────────────────
+
+    @Test fun atlasLoadsCreaturesAndDiscoversTheShardsFacets() {
+        // Nothing may NAME a facet — a shard can add, replace or rename them, so the
+        // filter options come from the shard's own data.
+        api.atlasCreatures = AtlasCreaturePageDto(
+            creatures = listOf(
+                AtlasCreatureDto(slug = "lizardman", facets = mapOf("Felucca" to 30, "Sosaria" to 2)),
+                AtlasCreatureDto(slug = "orc", facets = mapOf("Underdark" to 5)),
+            ),
+            total = 2,
+        )
+
+        val vm = AtlasViewModel(repo())
+
+        assertEquals(2, (vm.state.value as UiState.Success).data.creatures.size)
+        assertEquals(listOf("Felucca", "Sosaria", "Underdark"), vm.facets.value)
+    }
+
+    @Test fun aFilteredPageDoesNotNarrowTheFacetOptions() {
+        api.atlasCreatures = AtlasCreaturePageDto(
+            creatures = listOf(AtlasCreatureDto(slug = "a", facets = mapOf("Felucca" to 1, "Trammel" to 1))),
+        )
+        val vm = AtlasViewModel(repo())
+        assertEquals(listOf("Felucca", "Trammel"), vm.facets.value)
+
+        // Filtering to one facet must not leave the picker with only that option.
+        api.atlasCreatures = AtlasCreaturePageDto(
+            creatures = listOf(AtlasCreatureDto(slug = "a", facets = mapOf("Felucca" to 1))),
+        )
+        vm.onFacetChange("Felucca")
+
+        assertEquals(listOf("Felucca", "Trammel"), vm.facets.value)
+        assertEquals("Felucca", api.lastAtlasFacet)
+    }
+
+    @Test fun aGatedAtlasReadsAsUnavailable() {
+        api.error = httpError(404)
+
+        val state = AtlasViewModel(repo()).state.value
+
+        assertEquals(ErrorKind.FEATURE_UNAVAILABLE, (state as UiState.Error).kind)
+    }
+
+    @Test fun aCreatureLoadsBySlug() {
+        api.atlasCreature = AtlasCreatureDto(slug = "lizardman", name = "Lizardman", total = 214)
+
+        val vm = AtlasCreatureViewModel(repo())
+        vm.load("lizardman")
+
+        assertEquals(214, (vm.state.value as UiState.Success).data.total)
+    }
+}

app/src/test/java/com/runicgateway/app/util/FakeApiSupport.kt

@@ -0,0 +1,27 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.util
+
+import okhttp3.MediaType.Companion.toMediaTypeOrNull
+import okhttp3.ResponseBody.Companion.toResponseBody
+import retrofit2.HttpException
+import retrofit2.Response
+
+/**
+ * Test doubles emulate Retrofit's error contract: a suspend API method throws
+ * [HttpException] on a non-2xx and an [java.io.IOException] on a transport failure,
+ * exactly what `safeApiCall` folds into `ApiResult.HttpError` / `NetworkError`.
+ */
+
+private val JSON = "application/json".toMediaTypeOrNull()
+
+/** An [HttpException] carrying [code] — what a fake API throws to drive an HTTP-error path. */
+fun httpError(code: Int): HttpException =
+    HttpException(Response.error<Any>(code, "{}".toResponseBody(JSON)))
+
+/** A successful bodyless [Response] (for `@DELETE`/moderation endpoints returning `Response<Unit>`). */
+fun okUnit(): Response<Unit> = Response.success(Unit)
+
+/** A non-2xx bodyless [Response] with [code]. */
+fun errorUnit(code: Int): Response<Unit> = Response.error(code, "{}".toResponseBody(JSON))

app/src/test/java/com/runicgateway/app/util/MainDispatcherRule.kt

@@ -0,0 +1,31 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.util
+
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.ExperimentalCoroutinesApi
+import kotlinx.coroutines.test.TestDispatcher
+import kotlinx.coroutines.test.UnconfinedTestDispatcher
+import kotlinx.coroutines.test.resetMain
+import kotlinx.coroutines.test.setMain
+import org.junit.rules.TestWatcher
+import org.junit.runner.Description
+
+/**
+ * Swaps `Dispatchers.Main` (which `viewModelScope` dispatches on) for a test
+ * dispatcher for the duration of a test, so ViewModel coroutines run on the test
+ * scheduler instead of a real Android main looper.
+ *
+ * Defaults to an [UnconfinedTestDispatcher] so work launched from a ViewModel's
+ * `init {}` runs eagerly to its first real suspension — with fakes that never
+ * truly suspend, that means the final state is settled by the time the constructor
+ * returns, and a test can assert `state.value` directly without advancing time.
+ */
+@OptIn(ExperimentalCoroutinesApi::class)
+class MainDispatcherRule(
+    val dispatcher: TestDispatcher = UnconfinedTestDispatcher(),
+) : TestWatcher() {
+    override fun starting(description: Description) = Dispatchers.setMain(dispatcher)
+    override fun finished(description: Description) = Dispatchers.resetMain()
+}