Merge pull request 'feat(theme): make the app a full consumer of the shard's admin theming and nav (M12 cutover)' (#41) from edge into main

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

.gitattributes

@@ -0,0 +1,22 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+# Deterministic line endings across contributor platforms.
+
+# Default: normalize to LF in the repo.
+* text=auto eol=lf
+
+# The Gradle wrapper POSIX script MUST stay LF (runs on the Linux CI runner).
+gradlew text eol=lf
+
+# Windows batch files must be CRLF.
+*.bat text eol=crlf
+
+# Binary assets — never touch line endings.
+*.jar binary
+*.keystore binary
+*.jks binary
+*.png binary
+*.webp binary
+*.ico binary
+# Bundled type families (res/font). `text=auto` already detects these as binary,
+# but a font is too easy to corrupt silently to leave to a heuristic.
+*.ttf binary

.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/pr-checks.yml

@@ -0,0 +1,75 @@
+# Gate every pull request into `main` on lint + unit tests + a debug build, so a
+# broken build can't reach the deployable branch. Debug builds are auto-signed,
+# so this gate needs no secrets. The signed *release* APK + Gitea release come
+# later (release.yml, M6). See docs/android/PLAN.md §12.
+#
+# Enforcement (one-time, in the Gitea UI):
+#   Repository Settings -> Branches -> Branch Protection (rule for `main`)
+#     * Enable Status Check
+#     * Status check patterns:  PR Checks / *
+#
+# Runner: the org's self-hosted `ubuntu-latest`. The container lacks
+# git/curl/unzip (needed by checkout + sdkmanager), so the first step installs
+# them. It also installs JDK 17 from the Ubuntu archive rather than using
+# actions/setup-java, because this runner can't resolve api.adoptium.net (that
+# download fails with EAI_AGAIN) while the Ubuntu mirrors are reachable.
+# (Faster later: switch to a prebuilt Android-SDK+JDK container image so nothing
+# installs per-run.)
+
+name: PR Checks
+
+on:
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: pr-checks-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  android-build:
+    runs-on: ubuntu-latest
+    steps:
+      # Install the tools checkout + the SDK installer need, plus JDK 17 (see the
+      # header note on why we avoid actions/setup-java on this runner).
+      - 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"
+
+      - uses: actions/checkout@v4
+
+      - name: Set up Android SDK
+        uses: android-actions/setup-android@v3
+
+      # Install exactly what the build targets so it never depends on AGP's
+      # build-time auto-download. `yes |` accepts any license prompts; `set
+      # +o pipefail` so `yes` dying with SIGPIPE (exit 141) once sdkmanager
+      # closes the pipe doesn't fail the step -- sdkmanager's own exit, last in
+      # the pipeline, still gates success.
+      - 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 }}-
+
+      # chmod defensively: this runner's checkout doesn't preserve the git
+      # executable bit, so `./gradlew` alone fails with "Permission denied".
+      # Debug-variant-only gate: unit tests, lint, and the debug APK. Scoping to
+      # the debug variant (vs. the aggregate `test`/`lint`) avoids compiling and
+      # linting the release variant in parallel, which halves peak memory on the
+      # runner and keeps lint's report phase from GC-thrashing (see gradle.properties).
+      - name: Lint, test, assemble debug
+        run: |
+          chmod +x ./gradlew
+          ./gradlew --no-daemon testDebugUnitTest lintDebug assembleDebug

.gitea/workflows/release.yml

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

.gitea/workflows/sonarqube.yml

@@ -0,0 +1,90 @@
+# Run SonarQube static analysis against the code that just landed on `main` and
+# report the results to the self-hosted SonarQube server for review. This is
+# intentionally NON-BLOCKING: it triggers on push to main (i.e. AFTER merge),
+# not on pull_request, so it never gates a PR. It complements pr-checks.yml
+# (which gates PRs) and release.yml (which ships the APK) — this one only feeds
+# the dashboard.
+#
+# Prerequisites (one-time, in the Gitea UI — Repo → Settings → Actions):
+#   • Secret   SONAR_TOKEN     — a SonarQube "Analysis" token generated at
+#                                My Account → Security in SonarQube for the
+#                                Runic-Gateway-Android-app project (or a global one).
+#   • Variable SONAR_HOST_URL  — the SonarQube base URL on your LAN, e.g.
+#                                http://192.168.0.56:9000
+#     (kept as a variable, not committed, so the internal address stays out of git.)
+#
+# The runner (self-hosted `ubuntu-latest`, same as the other workflows) must be
+# able to reach SONAR_HOST_URL on your network. Nothing here waits on the
+# SonarQube Quality Gate, so a failing gate does not fail this job — check the
+# dashboard when you want to.
+#
+# 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
+
+on:
+  push:
+    branches: [main]
+  # Allow re-running the analysis on demand from the Actions tab.
+  workflow_dispatch: {}
+
+concurrency:
+  group: sonarqube-${{ github.ref }}
+  cancel-in-progress: true
+
+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:
+          # SonarQube uses git history to attribute issues to authors and to
+          # 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:
+          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
+          SONAR_HOST_URL: ${{ vars.SONAR_HOST_URL }}

.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

.gitignore

@@ -0,0 +1,30 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+# Android / Gradle / IDE ignores.
+
+# Built output
+/build/
+/app/build/
+*.apk
+*.aab
+*.ap_
+*.dex
+
+# Gradle
+.gradle/
+local.properties
+
+# Keystores / signing material — never commit (release keystore is a CI secret, PLAN.md §12)
+*.jks
+*.keystore
+keystore.properties
+
+# Android Studio / IntelliJ
+.idea/
+*.iml
+.DS_Store
+captures/
+.externalNativeBuild/
+.cxx/
+
+# Kotlin
+.kotlin/

README.md

@@ -0,0 +1,70 @@
+<!-- SPDX-License-Identifier: GPL-3.0-or-later -->
+# Runic Gateway — Android app
+
+A native Android client for a Runic Gateway shard's **public site + player self-service**. It is
+**purely an API client of the website backend** — it never talks to the `link/` sidecar or the game
+shard directly, and it ships none of the shard/sidecar wiring. It surfaces the same content and
+player features as the website's browser client, **minus every administrative/management console**.
+
+The authoritative design contract is [`docs/android/PLAN.md`](https://gitea.whitlocktech.com/RunicGateway/docs)
+in the `RunicGateway/docs` repo. The authoritative API reference is the committed OpenAPI spec at
+`website/server/swagger/swagger-output.json`.
+
+## Status
+
+**M0 — repo scaffold.** Gradle + Compose + Hilt skeleton with CI (lint + unit test + debug build).
+The functional Kotlin pass (M1–M4) and the design pass (M5) follow — see the plan's milestones (§9).
+
+## Stack
+
+| Concern | Choice |
+|---|---|
+| Language / UI | Kotlin + Jetpack Compose (Material 3) |
+| Navigation | Navigation-Compose, single-activity |
+| HTTP | Retrofit + OkHttp, `kotlinx.serialization` |
+| Async | Coroutines + Flow |
+| DI | Hilt |
+| Prefs / base URL | Jetpack DataStore |
+| Tokens at rest | EncryptedSharedPreferences |
+| Images | Coil |
+| Min SDK | Android 10 (API 29) |
+| Target / compile SDK | 35 |
+
+Dependency and plugin versions are pinned in [`gradle/libs.versions.toml`](gradle/libs.versions.toml).
+
+## Build
+
+Requires **JDK 17** and the Android SDK (`ANDROID_HOME` / `local.properties`).
+
+```bash
+./gradlew assembleDebug     # build a debug APK -> app/build/outputs/apk/debug/
+./gradlew test              # JVM unit tests
+./gradlew lint              # Android lint
+./gradlew installDebug      # install on a connected device/emulator
+```
+
+The app self-configures its server URL on first run (PLAN.md §3), so a single build works against
+any shard's website — there is no compiled-in API host.
+
+## CI
+
+`.gitea/workflows/pr-checks.yml` gates PRs into `main` with `./gradlew lint test assembleDebug` on the
+org's self-hosted runner (JDK 17 + Android SDK). Debug builds are auto-signed, so the gate needs no
+secrets. **This pipeline is verified green end-to-end on the runner** (M0). A signed **release** APK
+attached to a Gitea release comes at M6.
+
+The workflow carries a few runner-specific accommodations (each explained in comments in the file),
+because this self-hosted runner differs from a stock GitHub runner:
+
+- **JDK 17 is installed via `apt`** (not `actions/setup-java`) — the runner can't resolve
+  `api.adoptium.net`, while the Ubuntu mirrors are reachable.
+- **SDK packages are installed explicitly** via `sdkmanager`, with `set +o pipefail` so `yes` dying of
+  `SIGPIPE` doesn't fail the step.
+- **`gradlew` is `chmod +x`'d in the run step** — the runner's checkout does not preserve the git
+  executable bit, so `./gradlew` alone fails with "Permission denied".
+
+## Contributing
+
+See [`CONTRIBUTING.md`](CONTRIBUTING.md). **AI-assisted contributions must be disclosed** (org
+policy): tick the PR box naming the tool and add a `Co-Authored-By` trailer to AI-authored commits.
+Licensed **GPL-3.0-or-later**.

app/build.gradle.kts

@@ -0,0 +1,214 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+import java.io.FileInputStream
+import java.util.Properties
+
+plugins {
+    alias(libs.plugins.android.application)
+    alias(libs.plugins.kotlin.android)
+    alias(libs.plugins.kotlin.compose)
+    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
+// order of precedence: a local gitignored `keystore.properties` at the repo root,
+// then environment variables (how CI injects the decoded keystore + secrets). When
+// none is present, the release build is simply left unsigned — `assembleDebug` and
+// the PR gate are unaffected, so contributors without the keystore can still build.
+val keystorePropsFile = rootProject.file("keystore.properties")
+val keystoreProps = Properties().apply {
+    if (keystorePropsFile.exists()) FileInputStream(keystorePropsFile).use { load(it) }
+}
+fun signingValue(propKey: String, envKey: String): String? =
+    keystoreProps.getProperty(propKey) ?: System.getenv(envKey)
+
+val ksStoreFilePath = signingValue("storeFile", "ANDROID_KEYSTORE_FILE")
+val ksStorePassword = signingValue("storePassword", "ANDROID_KEYSTORE_PASSWORD")
+val ksKeyAlias = signingValue("keyAlias", "ANDROID_KEY_ALIAS")
+val ksKeyPassword = signingValue("keyPassword", "ANDROID_KEY_PASSWORD")
+val hasReleaseSigning = ksStoreFilePath != null && ksStorePassword != null &&
+    ksKeyAlias != null && ksKeyPassword != null
+
+android {
+    namespace = "com.runicgateway.app"
+    compileSdk = 35
+
+    defaultConfig {
+        // Target application id per docs/android/PLAN.md §13 (pending runicgateway.app domain).
+        applicationId = "com.runicgateway.app"
+        minSdk = 29
+        targetSdk = 35
+        // These committed defaults are the version source of truth (PLAN.md §10).
+        // release.yml's conventional-commit engine bumps versionName here and commits
+        // it on release; versionCode is derived from it (major*10000+minor*100+patch)
+        // so it stays monotonic. Both remain overridable via -P for local/manual builds.
+        versionCode = (project.findProperty("versionCode") as String?)?.toIntOrNull() ?: 1
+        versionName = (project.findProperty("versionName") as String?)?.takeIf { it.isNotBlank() } ?: "0.1.0"
+
+        testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
+
+        // Android App Links host (docs/android/APP_LINKS.md). autoVerify needs a
+        // *literal* host at build time, so a single multi-tenant APK cannot verify
+        // open-ended shard domains: App Links are a build-time opt-in. Left empty for
+        // the generic build (custom scheme only); a white-label/first-party build
+        // bakes one host with `-PappLinkHost=play.myshard.com`.
+        //   • BuildConfig.APP_LINK_HOST — SsoAuthManager reads it to pick the redirect.
+        //   • manifestPlaceholder appLinkHost — substituted into the intent-filter host;
+        //     empty falls back to the reserved `.invalid` sentinel so the autoVerify
+        //     filter is inert (matches no real link, never verifies).
+        val appLinkHost = (project.findProperty("appLinkHost") as String?)?.trim().orEmpty()
+        buildConfigField("String", "APP_LINK_HOST", "\"$appLinkHost\"")
+        manifestPlaceholders["appLinkHost"] = appLinkHost.ifBlank { "runic-gateway.invalid" }
+    }
+
+    signingConfigs {
+        if (hasReleaseSigning) {
+            create("release") {
+                storeFile = file(ksStoreFilePath!!)
+                storePassword = ksStorePassword
+                keyAlias = ksKeyAlias
+                keyPassword = ksKeyPassword
+                // Sign with both v1 (JAR) and v2 (APK) schemes for broad compatibility.
+                enableV1Signing = true
+                enableV2Signing = true
+            }
+        }
+    }
+
+    buildTypes {
+        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.
+            isMinifyEnabled = true
+            isShrinkResources = true
+            proguardFiles(
+                getDefaultProguardFile("proguard-android-optimize.txt"),
+                "proguard-rules.pro",
+            )
+            // Signed only when the keystore material is present (local or CI); an
+            // unsigned APK is produced otherwise. The direct-APK release (§10) runs
+            // through release.yml, which supplies the keystore from a Gitea secret.
+            if (hasReleaseSigning) {
+                signingConfig = signingConfigs.getByName("release")
+            }
+        }
+    }
+
+    compileOptions {
+        sourceCompatibility = JavaVersion.VERSION_17
+        targetCompatibility = JavaVersion.VERSION_17
+    }
+
+    kotlinOptions {
+        jvmTarget = "17"
+    }
+
+    buildFeatures {
+        compose = true
+        buildConfig = true
+    }
+
+    packaging {
+        resources {
+            excludes += "/META-INF/{AL2.0,LGPL2.1}"
+        }
+    }
+}
+
+dependencies {
+    // Core / lifecycle / activity
+    implementation(libs.androidx.core.ktx)
+    implementation(libs.androidx.lifecycle.runtime.ktx)
+    implementation(libs.androidx.lifecycle.runtime.compose)
+    implementation(libs.androidx.lifecycle.viewmodel.compose)
+    implementation(libs.androidx.activity.compose)
+
+    // Compose (BOM-managed versions)
+    implementation(platform(libs.androidx.compose.bom))
+    implementation(libs.androidx.compose.ui)
+    implementation(libs.androidx.compose.ui.graphics)
+    implementation(libs.androidx.compose.ui.tooling.preview)
+    implementation(libs.androidx.compose.material3)
+    implementation(libs.androidx.compose.material.icons.core)
+    implementation(libs.androidx.navigation.compose)
+    debugImplementation(libs.androidx.compose.ui.tooling)
+    debugImplementation(libs.androidx.compose.ui.test.manifest)
+
+    // DI
+    implementation(libs.hilt.android)
+    ksp(libs.hilt.compiler)
+    implementation(libs.androidx.hilt.navigation.compose)
+
+    // Networking (wired for M1+; declared now so the stack resolves)
+    implementation(libs.retrofit)
+    implementation(platform(libs.okhttp.bom))
+    implementation(libs.okhttp)
+    implementation(libs.okhttp.logging.interceptor)
+    implementation(libs.okhttp.sse)
+    implementation(libs.kotlinx.serialization.json)
+    implementation(libs.retrofit.kotlinx.serialization.converter)
+
+    // Storage
+    implementation(libs.androidx.datastore.preferences)
+    implementation(libs.androidx.security.crypto)
+
+    // Web hand-off (Chrome Custom Tabs) for register / invite / reset / SSO (§4.2)
+    implementation(libs.androidx.browser)
+
+    // Images
+    implementation(libs.coil.compose)
+
+    // Unit tests
+    testImplementation(libs.junit)
+    testImplementation(libs.kotlinx.coroutines.test)
+
+    // Instrumented tests
+    androidTestImplementation(libs.androidx.test.ext.junit)
+    androidTestImplementation(libs.androidx.espresso.core)
+    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/licenses/Cinzel-OFL.txt

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

app/licenses/EBGaramond-OFL.txt

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

app/licenses/IMFellEnglish-OFL.txt

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

app/licenses/Inter-OFL.txt

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

app/licenses/Merriweather-OFL.txt

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

app/licenses/PlayfairDisplay-OFL.txt

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

app/licenses/SourceSans3-OFL.txt

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

app/licenses/WorkSans-OFL.txt

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

app/proguard-rules.pro

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

app/src/debug/res/xml/network_security_config.xml

@@ -0,0 +1,20 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- SPDX-License-Identifier: GPL-3.0-or-later -->
+<!--
+  Debug-only override of the main network_security_config.xml. Keeps the secure
+  base posture (no cleartext) but re-permits cleartext to loopback so debug builds
+  can reach a local website backend at http://127.0.0.1:3000 / http://localhost:3000
+  (ServerUrl allows plain HTTP only when allowInsecureHttp = BuildConfig.DEBUG).
+  Because the platform default already blocks cleartext at targetSdk 28+, this
+  domain-config is what actually makes the debug local-dev path work at runtime.
+
+  This file is compiled only into debug builds; release builds use the main
+  source set's config and permit no cleartext at all.
+-->
+<network-security-config>
+    <base-config cleartextTrafficPermitted="false" />
+    <domain-config cleartextTrafficPermitted="true">
+        <domain includeSubdomains="false">127.0.0.1</domain>
+        <domain includeSubdomains="false">localhost</domain>
+    </domain-config>
+</network-security-config>

app/src/main/AndroidManifest.xml

@@ -0,0 +1,80 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- SPDX-License-Identifier: GPL-3.0-or-later -->
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+
+    <!-- The app is purely an HTTPS API client of a shard's website backend. -->
+    <uses-permission android:name="android.permission.INTERNET" />
+    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
+
+    <!-- Opt-in push notifications (M7): the runtime notification permission (API 33+)
+         and a foreground service that holds the persistent ntfy connection open — the
+         embedded UnifiedPush distributor, so no separate app is needed (PLAN.md §11). -->
+    <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
+    <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
+    <uses-permission android:name="android.permission.FOREGROUND_SERVICE_DATA_SYNC" />
+
+    <application
+        android:name=".RunicGatewayApp"
+        android:allowBackup="true"
+        android:dataExtractionRules="@xml/data_extraction_rules"
+        android:fullBackupContent="@xml/backup_rules"
+        android:icon="@mipmap/ic_launcher"
+        android:label="@string/app_name"
+        android:networkSecurityConfig="@xml/network_security_config"
+        android:roundIcon="@mipmap/ic_launcher_round"
+        android:supportsRtl="true"
+        android:theme="@style/Theme.RunicGateway">
+
+        <!-- singleTop so the SSO Custom Tab returning via the deep link reuses the
+             running task (onNewIntent) instead of stacking a second activity. -->
+        <activity
+            android:name=".MainActivity"
+            android:exported="true"
+            android:launchMode="singleTop"
+            android:theme="@style/Theme.RunicGateway">
+            <intent-filter>
+                <action android:name="android.intent.action.MAIN" />
+                <category android:name="android.intent.category.LAUNCHER" />
+            </intent-filter>
+
+            <!-- Native SSO callback (M9, PLAN.md §4.2). The bridge deep-links the
+                 one-time authorization code back to this fixed, app-owned custom
+                 scheme; it must match SsoAuthManager.REDIRECT_URI and the backend's
+                 MOBILE_AUTH_REDIRECT_URIS allowlist exactly. This is the permanent
+                 fallback on every build (docs/android/APP_LINKS.md). -->
+            <intent-filter>
+                <action android:name="android.intent.action.VIEW" />
+                <category android:name="android.intent.category.DEFAULT" />
+                <category android:name="android.intent.category.BROWSABLE" />
+                <data
+                    android:scheme="runicgateway"
+                    android:host="auth"
+                    android:path="/callback" />
+            </intent-filter>
+
+            <!-- App Links hardening (docs/android/APP_LINKS.md): a verified https
+                 callback that only the domain's real owner can claim. autoVerify
+                 needs a literal host, so ${appLinkHost} is baked at build time
+                 (build.gradle.kts). The generic build leaves it as the reserved
+                 runic-gateway.invalid sentinel — the filter then matches no real
+                 link and never verifies. A white-label build sets -PappLinkHost. -->
+            <intent-filter android:autoVerify="true">
+                <action android:name="android.intent.action.VIEW" />
+                <category android:name="android.intent.category.DEFAULT" />
+                <category android:name="android.intent.category.BROWSABLE" />
+                <data
+                    android:scheme="https"
+                    android:host="${appLinkHost}"
+                    android:path="/mobile/callback" />
+            </intent-filter>
+        </activity>
+
+        <!-- The embedded distributor's persistent ntfy connection (M7, PLAN.md §11).
+             dataSync foreground type; not exported — started only by PushManager. -->
+        <service
+            android:name=".core.push.PushService"
+            android:exported="false"
+            android:foregroundServiceType="dataSync" />
+    </application>
+
+</manifest>

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

@@ -0,0 +1,141 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app
+
+import android.content.Intent
+import android.graphics.Color
+import android.net.Uri
+import android.os.Bundle
+import androidx.activity.ComponentActivity
+import androidx.activity.SystemBarStyle
+import androidx.activity.compose.setContent
+import androidx.activity.enableEdgeToEdge
+import androidx.lifecycle.lifecycleScope
+import androidx.compose.foundation.layout.fillMaxSize
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.Surface
+import androidx.compose.runtime.CompositionLocalProvider
+import androidx.compose.runtime.getValue
+import androidx.compose.runtime.mutableStateOf
+import androidx.compose.runtime.setValue
+import androidx.compose.ui.Modifier
+import com.runicgateway.app.core.auth.sso.SsoAuthManager
+import com.runicgateway.app.core.push.PushNotifier
+import androidx.hilt.navigation.compose.hiltViewModel
+import androidx.lifecycle.compose.LifecycleResumeEffect
+import androidx.lifecycle.compose.collectAsStateWithLifecycle
+import com.runicgateway.app.ui.AppViewModel
+import com.runicgateway.app.ui.AppViewModel.AppState
+import com.runicgateway.app.ui.LocalAssetResolver
+import com.runicgateway.app.ui.RunicApp
+import com.runicgateway.app.ui.components.LoadingView
+import com.runicgateway.app.ui.connect.ConnectScreen
+import com.runicgateway.app.data.appearance.SiteAppearance
+import com.runicgateway.app.ui.theme.RunicGatewayTheme
+import dagger.hilt.android.AndroidEntryPoint
+import kotlinx.coroutines.launch
+import javax.inject.Inject
+
+/**
+ * Single-activity host (PLAN.md §2). Gates on [AppViewModel]: the first-run
+ * connect screen until a shard site is configured (§3), then the main app.
+ * The Material theme is resolved from the shard's published appearance (M12),
+ * and asset-path resolution is provided to the whole tree.
+ */
+@AndroidEntryPoint
+class MainActivity : ComponentActivity() {
+
+    // Native SSO bridge — handles the runicgateway://auth/callback deep link (M9,
+    // §4.2). Field-injected because the callback can arrive independent of any
+    // ViewModel; a successful exchange flips the SessionManager the whole app
+    // observes, and the login screen consumes SsoAuthManager.outcome.
+    @Inject
+    lateinit var ssoAuthManager: SsoAuthManager
+
+    // The stream a tapped push notification wants to open (§11, M7 Part 2 item 7).
+    // Set from the launching intent and from onNewIntent (the activity is singleTop),
+    // consumed once by RunicApp which navigates to the stream's screen.
+    private var pendingStream by mutableStateOf<String?>(null)
+
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+        pendingStream = intent?.getStringExtra(PushNotifier.EXTRA_STREAM)
+        handleSsoCallback(intent)
+        // Dark-only app (M5): force light system-bar icons over the transparent bars so
+        // they stay legible on the deep blue-black surfaces regardless of system theme.
+        val barStyle = SystemBarStyle.dark(Color.TRANSPARENT)
+        enableEdgeToEdge(statusBarStyle = barStyle, navigationBarStyle = barStyle)
+        setContent {
+            val appViewModel: AppViewModel = hiltViewModel()
+            val state by appViewModel.state.collectAsStateWithLifecycle()
+
+            // The whole theme, not just the accent (THEMING_AND_NAV.md §5.1): the
+            // resolved token map is applied field by field over the shipped palette,
+            // so NONE — before the site is connected, or when settings can't be
+            // read — is the app exactly as it shipped.
+            val appearance = (state as? AppState.Ready)?.appearance ?: SiteAppearance.NONE
+
+            // The admin's theme and nav can change while the app is backgrounded
+            // (THEMING_AND_NAV.md §5.5). Re-read them on resume, beside the session
+            // re-validation RunicApp already does. Best-effort and silent.
+            LifecycleResumeEffect(Unit) {
+                appViewModel.refreshAppearance()
+                onPauseOrDispose { }
+            }
+
+            RunicGatewayTheme(appearance = appearance) {
+                CompositionLocalProvider(LocalAssetResolver provides appViewModel::resolveAsset) {
+                    Surface(
+                        modifier = Modifier.fillMaxSize(),
+                        color = MaterialTheme.colorScheme.background,
+                    ) {
+                        when (val s = state) {
+                            AppState.Loading -> LoadingView()
+                            AppState.NeedsConnection ->
+                                ConnectScreen(onConnected = appViewModel::onConnected)
+                            is AppState.Ready ->
+                                RunicApp(
+                                    appearance = s.appearance,
+                                    onChangeServer = appViewModel::changeServer,
+                                    deepLinkStream = pendingStream,
+                                    onDeepLinkConsumed = { pendingStream = null },
+                                )
+                        }
+                    }
+                }
+            }
+        }
+    }
+
+    /**
+     * A notification tap or an SSO callback arriving while the activity is already
+     * running (singleTop) — the common case, since the Custom Tab overlays the live
+     * app during sign-in.
+     */
+    override fun onNewIntent(intent: Intent) {
+        super.onNewIntent(intent)
+        setIntent(intent)
+        intent.getStringExtra(PushNotifier.EXTRA_STREAM)?.let { pendingStream = it }
+        handleSsoCallback(intent)
+    }
+
+    /**
+     * Route an SSO callback VIEW intent into the bridge (M9, §4.2): either the
+     * custom-scheme `runicgateway://auth/callback` (always) or the verified https
+     * App Link `https://<paired-host>/mobile/callback` (opt-in hardening —
+     * docs/android/APP_LINKS.md). Both feed the *same* exchange; the result surfaces
+     * on `SsoAuthManager.outcome` (success signs the session in; failure shows on the
+     * login screen). Non-callback intents are ignored.
+     */
+    private fun handleSsoCallback(intent: Intent?) {
+        val data: Uri = intent?.takeIf { it.action == Intent.ACTION_VIEW }?.data ?: return
+        val isCallback = ssoAuthManager.matchesCallback(data.scheme, data.host, data.path) ||
+            ssoAuthManager.matchesAppLinkCallback(data.scheme, data.host, data.path)
+        if (!isCallback) return
+        val state = data.getQueryParameter("state")
+        val code = data.getQueryParameter("code")
+        val error = data.getQueryParameter("error")
+        lifecycleScope.launch { ssoAuthManager.complete(state = state, code = code, error = error) }
+    }
+}

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

@@ -0,0 +1,15 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ * Runic Gateway — native Android client of a shard's website API.
+ */
+package com.runicgateway.app
+
+import android.app.Application
+import dagger.hilt.android.HiltAndroidApp
+
+/**
+ * Application entry point. Annotated for Hilt so the DI graph is available
+ * to activities, view models, and (from M1) repositories / API services.
+ */
+@HiltAndroidApp
+class RunicGatewayApp : Application()

app/src/main/java/com/runicgateway/app/core/AppConfig.kt

@@ -0,0 +1,14 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.core
+
+/**
+ * Build-derived flags, injected rather than read from `BuildConfig` directly so
+ * the logic that consumes them (URL validation, etc.) stays plain and unit-testable.
+ */
+data class AppConfig(
+    /** Allow plain HTTP base URLs. Debug-only (local dev); release requires HTTPS (§3). */
+    val allowInsecureHttp: Boolean,
+    val versionName: String,
+)

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/EncryptedTokenStore.kt

@@ -0,0 +1,73 @@
+/*
+ * 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
+
+/**
+ * [TokenStore] backed by Jetpack Security's [EncryptedSharedPreferences]
+ * (Tink/AES-256-GCM), so the token pair is encrypted at rest (PLAN.md §2, §4.3).
+ * The base URL stays in plain DataStore ([com.runicgateway.app.core.prefs.ServerPreferences]);
+ * only tokens live here.
+ *
+ * The prefs handle is created lazily so a first-launch device (no session yet)
+ * pays the keystore cost only once a user actually signs in.
+ */
+@Singleton
+class EncryptedTokenStore @Inject constructor(
+    @param:ApplicationContext private val context: Context,
+) : TokenStore {
+
+    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 load(): StoredSession? {
+        val access = prefs.getString(KEY_ACCESS, null) ?: return null
+        val refresh = prefs.getString(KEY_REFRESH, null) ?: return null
+        val username = prefs.getString(KEY_USERNAME, null) ?: return null
+        val role = prefs.getString(KEY_ROLE, null) ?: return null
+        val id = prefs.getLong(KEY_USER_ID, -1L)
+        if (id < 0) return null
+        return StoredSession(access, refresh, id, username, role)
+    }
+
+    override fun save(session: StoredSession) {
+        prefs.edit()
+            .putString(KEY_ACCESS, session.accessToken)
+            .putString(KEY_REFRESH, session.refreshToken)
+            .putLong(KEY_USER_ID, session.userId)
+            .putString(KEY_USERNAME, session.username)
+            .putString(KEY_ROLE, session.role)
+            .apply()
+    }
+
+    override fun clear() {
+        prefs.edit().clear().apply()
+    }
+
+    private companion object {
+        const val PREFS_NAME = "runic_session"
+        const val KEY_ACCESS = "access_token"
+        const val KEY_REFRESH = "refresh_token"
+        const val KEY_USER_ID = "user_id"
+        const val KEY_USERNAME = "username"
+        const val KEY_ROLE = "role"
+    }
+}

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/Session.kt

@@ -0,0 +1,69 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.core.auth
+
+import com.runicgateway.app.data.api.dto.SafeUserDto
+
+/**
+ * The signed-in identity the app carries (PLAN.md §4.3, §5). Role is *advisory*
+ * for menu rendering only — the backend re-checks every gated call, so the app
+ * treats a 403 as authoritative and never assumes access from this value.
+ */
+data class SessionUser(
+    val id: Long,
+    val username: String,
+    val role: Role,
+) {
+    val isPlayer: Boolean get() = role == Role.PLAYER
+
+    /** Any staff role (moderator/editor/admin) — the staff-operations surface (§1, M10). */
+    val isStaff: Boolean get() = role.isStaff
+
+    /** Admin or moderator — moderation actions + the support queue (`modAccess`). */
+    val isModerator: Boolean get() = role == Role.ADMIN || role == Role.MODERATOR
+
+    /** Admin only — site-mode and other `adminOnly` controls. */
+    val isAdmin: Boolean get() = role == Role.ADMIN
+}
+
+/**
+ * The account roles the backend issues. The three staff roles are gated by
+ * capability, not rank (PLAN.md §5); [UNKNOWN] absorbs any future role so an
+ * additive backend change never crashes the menu.
+ */
+enum class Role(val wire: String) {
+    PLAYER("player"),
+    MODERATOR("moderator"),
+    EDITOR("editor"),
+    ADMIN("admin"),
+    UNKNOWN("");
+
+    val isStaff: Boolean get() = this == MODERATOR || this == EDITOR || this == ADMIN
+
+    companion object {
+        fun fromWire(value: String?): Role =
+            entries.firstOrNull { it.wire.equals(value, ignoreCase = true) } ?: UNKNOWN
+    }
+}
+
+/** The two auth states the UI observes. */
+sealed interface Session {
+    data object SignedOut : Session
+    data class SignedIn(val user: SessionUser) : Session
+}
+
+internal fun SafeUserDto.toSessionUser(): SessionUser =
+    SessionUser(id = id, username = username, role = Role.fromWire(role))
+
+internal fun SafeUserDto.toStored(accessToken: String, refreshToken: String): StoredSession =
+    StoredSession(
+        accessToken = accessToken,
+        refreshToken = refreshToken,
+        userId = id,
+        username = username,
+        role = role,
+    )
+
+internal fun StoredSession.toSessionUser(): SessionUser =
+    SessionUser(id = userId, username = username, role = Role.fromWire(role))

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

@@ -0,0 +1,99 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.core.auth
+
+import com.runicgateway.app.data.api.dto.SafeUserDto
+import kotlinx.coroutines.flow.MutableStateFlow
+import kotlinx.coroutines.flow.StateFlow
+import kotlinx.coroutines.flow.asStateFlow
+import java.util.concurrent.atomic.AtomicReference
+import javax.inject.Inject
+import javax.inject.Singleton
+
+/**
+ * The single source of truth for the current session (PLAN.md §4.3). It holds the
+ * in-memory token pair the network layer reads on every call, mirrors the
+ * signed-in identity into an observable [state] the UI + menu react to, and keeps
+ * the encrypted [TokenStore] in sync.
+ *
+ * Threading: [state] and the token holders are read from the UI thread and
+ * written from both coroutines (login/logout) and the OkHttp
+ * [com.runicgateway.app.core.net.TokenAuthenticator] dispatcher thread (silent
+ * refresh), so tokens live in [AtomicReference]s and the mutators are
+ * `@Synchronized` to keep the token pair and [state] consistent with each other.
+ */
+@Singleton
+class SessionManager @Inject constructor(
+    private val store: TokenStore,
+) {
+    private val accessRef = AtomicReference<String?>(null)
+    private val refreshRef = AtomicReference<String?>(null)
+
+    private val _state: MutableStateFlow<Session>
+    val state: StateFlow<Session>
+
+    init {
+        val restored = store.load()
+        if (restored != null) {
+            accessRef.set(restored.accessToken)
+            refreshRef.set(restored.refreshToken)
+            _state = MutableStateFlow(Session.SignedIn(restored.toSessionUser()))
+        } else {
+            _state = MutableStateFlow(Session.SignedOut)
+        }
+        state = _state.asStateFlow()
+    }
+
+    /** The bearer for the current request, or null when signed out. */
+    fun currentAccessToken(): String? = accessRef.get()
+
+    /** The refresh token the authenticator rotates, or null when signed out. */
+    fun currentRefreshToken(): String? = refreshRef.get()
+
+    val isSignedIn: Boolean get() = _state.value is Session.SignedIn
+
+    /** Establish a session from a successful login (§4.1). */
+    @Synchronized
+    fun onSignedIn(accessToken: String, refreshToken: String, user: SafeUserDto) {
+        accessRef.set(accessToken)
+        refreshRef.set(refreshToken)
+        store.save(user.toStored(accessToken, refreshToken))
+        _state.value = Session.SignedIn(user.toSessionUser())
+    }
+
+    /**
+     * Store a rotated token pair after a silent refresh (§4.3). Keeps the current
+     * user; if somehow signed out already, it is a no-op (the refresh raced a
+     * logout and must not resurrect the session).
+     */
+    @Synchronized
+    fun onRefreshed(accessToken: String, refreshToken: String, user: SafeUserDto) {
+        if (_state.value !is Session.SignedIn) return
+        accessRef.set(accessToken)
+        refreshRef.set(refreshToken)
+        store.save(user.toStored(accessToken, refreshToken))
+        // Refresh may carry an updated role — reflect it so the menu stays honest.
+        _state.value = Session.SignedIn(user.toSessionUser())
+    }
+
+    /** Refresh the cached identity from a `/auth/me` re-validation (§4.3). */
+    @Synchronized
+    fun onUserRefreshed(user: SafeUserDto) {
+        val current = _state.value
+        if (current !is Session.SignedIn) return
+        val access = accessRef.get() ?: return
+        val refresh = refreshRef.get() ?: return
+        store.save(user.toStored(access, refresh))
+        _state.value = Session.SignedIn(user.toSessionUser())
+    }
+
+    /** Tear the session down — user logout, dead refresh, or a server switch (§3). */
+    @Synchronized
+    fun onSignedOut() {
+        accessRef.set(null)
+        refreshRef.set(null)
+        store.clear()
+        _state.value = Session.SignedOut
+    }
+}

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

@@ -0,0 +1,31 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.core.auth
+
+/**
+ * The at-rest home for a signed-in session (PLAN.md §4.3): the access + refresh
+ * tokens plus the cached safe-user. Tokens are sensitive, so the production
+ * implementation stores them in EncryptedSharedPreferences — never plain
+ * DataStore or logs. Kept behind an interface so [SessionManager] is unit-testable
+ * against an in-memory fake.
+ */
+interface TokenStore {
+    /** The persisted session restored on launch, or null when signed out. */
+    fun load(): StoredSession?
+
+    /** Persist (overwrite) the current session atomically. */
+    fun save(session: StoredSession)
+
+    /** Wipe every stored token — sign-out and the Settings → Server hard reset (§3). */
+    fun clear()
+}
+
+/** A persisted session: the token pair and the non-sensitive user it belongs to. */
+data class StoredSession(
+    val accessToken: String,
+    val refreshToken: String,
+    val userId: Long,
+    val username: String,
+    val role: String,
+)

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/EncryptedPendingSsoStore.kt

@@ -0,0 +1,61 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.core.auth.sso
+
+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
+
+/**
+ * [PendingSsoStore] backed by Jetpack Security's [EncryptedSharedPreferences]
+ * (Tink/AES-256-GCM), so the PKCE verifier is encrypted at rest for the brief
+ * window a flow is in progress. Separate prefs file from the session token store —
+ * this holds only the transient SSO handshake, cleared as soon as the callback is
+ * consumed. Lazy, so a device that never signs in via SSO pays no keystore cost.
+ */
+@Singleton
+class EncryptedPendingSsoStore @Inject constructor(
+    @param:ApplicationContext private val context: Context,
+) : PendingSsoStore {
+
+    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 save(state: String, verifier: String) {
+        prefs.edit()
+            .putString(KEY_STATE, state)
+            .putString(KEY_VERIFIER, verifier)
+            .apply()
+    }
+
+    override fun load(): PendingSso? {
+        val state = prefs.getString(KEY_STATE, null) ?: return null
+        val verifier = prefs.getString(KEY_VERIFIER, null) ?: return null
+        return PendingSso(state = state, verifier = verifier)
+    }
+
+    override fun clear() {
+        prefs.edit().clear().apply()
+    }
+
+    private companion object {
+        const val PREFS_NAME = "runic_sso_pending"
+        const val KEY_STATE = "state"
+        const val KEY_VERIFIER = "verifier"
+    }
+}

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

@@ -0,0 +1,24 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.core.auth.sso
+
+/**
+ * Persists the in-flight SSO `{state, verifier}` (PKCE Layer B + CSRF state) across
+ * the Custom-Tab round trip so the exchange survives process death — a low-memory
+ * device can evict the app while the Custom Tab is foreground, and the callback then
+ * returns to a fresh process (PLAN.md §4.2). Kept behind an interface so
+ * [SsoAuthManager] stays framework-free and unit-tests on the JVM with a fake.
+ *
+ * Exactly one flow is pending at a time; [save] overwrites any prior. The verifier
+ * is a bearer-equivalent secret for the one-time code, so the production impl
+ * ([EncryptedPendingSsoStore]) encrypts it at rest, mirroring the token store.
+ */
+interface PendingSsoStore {
+    fun save(state: String, verifier: String)
+    fun load(): PendingSso?
+    fun clear()
+}
+
+/** The stashed CSRF state + PKCE verifier for the current SSO attempt. */
+data class PendingSso(val state: String, val verifier: String)

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

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

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

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

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

@@ -0,0 +1,39 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.core.net
+
+import com.runicgateway.app.core.auth.SessionManager
+import okhttp3.Interceptor
+import okhttp3.Response
+import javax.inject.Inject
+import javax.inject.Singleton
+
+/**
+ * Attaches the current bearer access token to outbound calls (PLAN.md §4.1).
+ * Public endpoints simply carry a token the backend ignores; the credential
+ * endpoints (login/refresh) tag themselves [Http.NO_SESSION_HEADER] and are left
+ * bare so a credential `401` is never mistaken for an expired session. A request
+ * that already set its own Authorization (the authenticator's retry) is untouched.
+ */
+@Singleton
+class AuthInterceptor @Inject constructor(
+    private val sessionManager: SessionManager,
+) : Interceptor {
+
+    override fun intercept(chain: Interceptor.Chain): Response {
+        val request = chain.request()
+        if (request.header(Http.NO_SESSION_HEADER) != null) {
+            return chain.proceed(request)
+        }
+        if (request.header(Http.AUTHORIZATION) != null) {
+            return chain.proceed(request)
+        }
+        val token = sessionManager.currentAccessToken()
+            ?: return chain.proceed(request)
+        val authed = request.newBuilder()
+            .header(Http.AUTHORIZATION, Http.bearer(token))
+            .build()
+        return chain.proceed(authed)
+    }
+}

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

@@ -0,0 +1,40 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.core.net
+
+import okhttp3.HttpUrl
+import java.util.concurrent.atomic.AtomicReference
+import javax.inject.Inject
+import javax.inject.Singleton
+
+/**
+ * Holds the currently-selected shard website base URL (PLAN.md §3). The API host
+ * is not compiled in: it is chosen on first run, may be changed later under
+ * Settings → Server, and every outbound API request is retargeted onto it by
+ * [HostSelectionInterceptor].
+ *
+ * Threading: the value is read on every network call and written from the
+ * connect/settings flows, so it lives in an [AtomicReference].
+ */
+@Singleton
+class BaseUrlHolder @Inject constructor() {
+    private val ref = AtomicReference<HttpUrl?>(null)
+
+    /** The configured base, or null before first-run connect completes. */
+    val current: HttpUrl? get() = ref.get()
+
+    fun set(url: HttpUrl?) = ref.set(url)
+
+    companion object {
+        /**
+         * Sentinel host used as Retrofit's compile-time `baseUrl`. Relative
+         * endpoint paths resolve against it; [HostSelectionInterceptor] rewrites
+         * exactly these requests onto [current]. Absolute-URL probe requests use
+         * a real host and are left untouched. `.invalid` is reserved (RFC 6761)
+         * so it can never accidentally resolve on a network.
+         */
+        const val PLACEHOLDER_HOST = "runic-gateway.invalid"
+        const val PLACEHOLDER_BASE_URL = "https://$PLACEHOLDER_HOST/"
+    }
+}

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

@@ -0,0 +1,53 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.core.net
+
+import okhttp3.HttpUrl
+import okhttp3.Interceptor
+import okhttp3.Response
+import java.io.IOException
+import javax.inject.Inject
+import javax.inject.Singleton
+
+/**
+ * Retargets each relative API request onto the runtime-selected base URL
+ * (PLAN.md §3). Retrofit is built with a sentinel base host
+ * ([BaseUrlHolder.PLACEHOLDER_HOST]); this interceptor swaps the scheme/host/port
+ * for the configured shard site and prefixes any base path the user included
+ * (`https://host/base`). Absolute-URL requests (the connect probe via `@Url`)
+ * carry a real host and pass through untouched.
+ */
+@Singleton
+class HostSelectionInterceptor @Inject constructor(
+    private val baseUrlHolder: BaseUrlHolder,
+) : Interceptor {
+
+    override fun intercept(chain: Interceptor.Chain): Response {
+        val request = chain.request()
+        if (request.url.host != BaseUrlHolder.PLACEHOLDER_HOST) {
+            return chain.proceed(request)
+        }
+
+        val base = baseUrlHolder.current
+            ?: throw IOException("No shard website is configured yet.")
+
+        val rewritten = rewriteOntoBase(base, request.url)
+        return chain.proceed(request.newBuilder().url(rewritten).build())
+    }
+}
+
+/**
+ * Resolve the sentinel-hosted [requestUrl] against [base] the way a browser
+ * resolves a relative link. [base] is guaranteed to end in "/"
+ * (ServerUrl.normalize), so `https://host/base/` + `api/v1/x` yields
+ * `https://host/base/api/v1/x` — the base path prefix is preserved and no double
+ * slash appears. Extracted as a pure function for unit testing.
+ */
+fun rewriteOntoBase(base: HttpUrl, requestUrl: HttpUrl): HttpUrl {
+    val relative = buildString {
+        append(requestUrl.encodedPath.removePrefix("/"))
+        requestUrl.encodedQuery?.let { append('?').append(it) }
+    }
+    return base.resolve(relative) ?: base
+}

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

@@ -0,0 +1,19 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.core.net
+
+/** Shared HTTP constants for the auth layer (PLAN.md §4). */
+object Http {
+    /**
+     * Marks the credential endpoints (login, refresh) that must run *without* a
+     * bearer and must never trigger the refresh-on-401 [TokenAuthenticator].
+     * [AuthInterceptor] sees it and skips attaching a token; the authenticator
+     * sees it on the failed request and declines to refresh. It is a harmless
+     * unknown header to the backend.
+     */
+    const val NO_SESSION_HEADER = "X-Runic-No-Session"
+    const val AUTHORIZATION = "Authorization"
+
+    fun bearer(token: String): String = "Bearer $token"
+}

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

@@ -0,0 +1,78 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.core.net
+
+import okhttp3.HttpUrl
+import okhttp3.HttpUrl.Companion.toHttpUrlOrNull
+
+/**
+ * Parses and normalizes the base URL a user types on the first-run "Connect to
+ * your shard's website" screen (PLAN.md §3). Pure, dependency-light logic so it
+ * is exercised directly in JVM unit tests.
+ *
+ * Rules:
+ *  - accept `https://host[/base]`; a bare `host[/base]` gets an implicit scheme
+ *    (`https` normally, so users needn't type it);
+ *  - trim surrounding whitespace;
+ *  - require HTTPS unless [allowInsecureHttp] (release builds forbid HTTP; debug
+ *    allows it for local dev against `127.0.0.1:3000`);
+ *  - drop any query/fragment and guarantee a trailing slash on the path so the
+ *    stored value composes cleanly with relative endpoint paths.
+ */
+object ServerUrl {
+
+    sealed interface Result {
+        data class Valid(val url: HttpUrl) : Result
+        data class Invalid(val reason: Reason) : Result
+    }
+
+    enum class Reason {
+        /** Empty or whitespace-only input. */
+        BLANK,
+
+        /** Not a parseable http(s) URL (bad host, illegal characters, …). */
+        MALFORMED,
+
+        /** A scheme other than http/https (e.g. ftp://, ws://). */
+        UNSUPPORTED_SCHEME,
+
+        /** Plain HTTP where the build requires HTTPS. */
+        INSECURE,
+    }
+
+    fun normalize(raw: String, allowInsecureHttp: Boolean): Result {
+        val trimmed = raw.trim()
+        if (trimmed.isEmpty()) return Result.Invalid(Reason.BLANK)
+
+        // Give a scheme-less entry an implicit, secure default so users can type
+        // just "shard.example.com". An explicit but unsupported scheme is rejected.
+        val hasScheme = SCHEME_RE.containsMatchIn(trimmed)
+        val candidate = if (hasScheme) trimmed else "https://$trimmed"
+
+        val lowerScheme = candidate.substringBefore("://", "").lowercase()
+        if (hasScheme && lowerScheme != "http" && lowerScheme != "https") {
+            return Result.Invalid(Reason.UNSUPPORTED_SCHEME)
+        }
+
+        val parsed = candidate.toHttpUrlOrNull() ?: return Result.Invalid(Reason.MALFORMED)
+        if (parsed.host.isBlank()) return Result.Invalid(Reason.MALFORMED)
+
+        if (parsed.scheme == "http" && !allowInsecureHttp) {
+            return Result.Invalid(Reason.INSECURE)
+        }
+
+        // Rebuild without query/fragment and force a trailing slash so
+        // HttpUrl.resolve()/addPathSegments compose predictably later.
+        val path = parsed.encodedPath.trimEnd('/')
+        val normalized = parsed.newBuilder()
+            .encodedPath(if (path.isEmpty()) "/" else "$path/")
+            .query(null)
+            .fragment(null)
+            .build()
+
+        return Result.Valid(normalized)
+    }
+
+    private val SCHEME_RE = Regex("^[a-zA-Z][a-zA-Z0-9+.-]*://")
+}

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

@@ -0,0 +1,151 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.core.net
+
+import kotlinx.coroutines.CompletableDeferred
+import kotlinx.coroutines.delay
+import kotlinx.coroutines.flow.Flow
+import kotlinx.coroutines.flow.channelFlow
+import kotlinx.coroutines.isActive
+import kotlinx.serialization.json.Json
+import kotlinx.serialization.json.JsonNull
+import kotlinx.serialization.json.JsonObject
+import kotlinx.serialization.json.jsonObject
+import kotlinx.serialization.json.jsonPrimitive
+import okhttp3.OkHttpClient
+import okhttp3.Request
+import okhttp3.Response
+import okhttp3.sse.EventSource
+import okhttp3.sse.EventSourceListener
+import okhttp3.sse.EventSources
+import java.util.concurrent.TimeUnit
+import java.util.concurrent.atomic.AtomicBoolean
+import javax.inject.Inject
+import javax.inject.Singleton
+
+/**
+ * Consumes the public live-event SSE stream (`GET /public/shard/stream`, safe kinds
+ * only) and re-emits each frame as a [ShardStreamEvent] (PLAN.md §6.2, §7).
+ *
+ * Unlike the browser's `EventSource`, OkHttp's does **not** auto-reconnect, so the
+ * reconnect/backoff loop lives here: on any disconnect the connection is torn down
+ * and re-opened after a growing delay (reset once a connection opens), and while no
+ * shard site is configured yet the flow simply idles. The stream is exposed as a
+ * cold [Flow]; a `viewModelScope` collect opens it and cancellation closes it, so a
+ * dropped feed degrades to "offline" rather than crashing.
+ */
+@Singleton
+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()
+        .readTimeout(0, TimeUnit.MILLISECONDS)
+        .retryOnConnectionFailure(true)
+        .build()
+
+    private val factory = EventSources.createFactory(sseClient)
+
+    /**
+     * A cold flow of stream lifecycle + frame events, reconnecting with backoff
+     * until the collector cancels. [ShardStreamEvent.Open] / [ShardStreamEvent.Closed]
+     * drive a live/offline indicator; [ShardStreamEvent.Frame] carries a decoded
+     * `{ kind, … }` payload the boards merge in place.
+     */
+    override fun events(): Flow<ShardStreamEvent> = channelFlow {
+        var backoffMs = INITIAL_BACKOFF_MS
+        while (isActive) {
+            val url = baseUrlHolder.current?.resolve(STREAM_PATH)
+            if (url == null) {
+                // No shard site configured (or an unresolvable base) — idle, don't spin.
+                trySend(ShardStreamEvent.Closed)
+                delay(backoffMs)
+                backoffMs = grow(backoffMs)
+                continue
+            }
+
+            val request = Request.Builder()
+                .url(url)
+                .header("Accept", "text/event-stream")
+                .build()
+
+            val opened = AtomicBoolean(false)
+            val ended = CompletableDeferred<Unit>()
+            val listener = object : EventSourceListener() {
+                override fun onOpen(eventSource: EventSource, response: Response) {
+                    opened.set(true)
+                    trySend(ShardStreamEvent.Open)
+                }
+
+                override fun onEvent(
+                    eventSource: EventSource,
+                    id: String?,
+                    type: String?,
+                    data: String,
+                ) {
+                    parseFrame(data)?.let { (kind, obj) ->
+                        trySend(ShardStreamEvent.Frame(kind, obj))
+                    }
+                }
+
+                override fun onClosed(eventSource: EventSource) {
+                    trySend(ShardStreamEvent.Closed)
+                    ended.complete(Unit)
+                }
+
+                override fun onFailure(
+                    eventSource: EventSource,
+                    t: Throwable?,
+                    response: Response?,
+                ) {
+                    trySend(ShardStreamEvent.Closed)
+                    ended.complete(Unit)
+                }
+            }
+
+            val source = factory.newEventSource(request, listener)
+            try {
+                // Park until this connection ends; collector cancellation propagates
+                // out of await() and is handled by the finally + the while guard.
+                ended.await()
+            } finally {
+                source.cancel()
+            }
+
+            // A connection that opened before dropping reconnects promptly; a run of
+            // failures that never opened backs off further to avoid hammering a down site.
+            backoffMs = if (opened.get()) INITIAL_BACKOFF_MS else grow(backoffMs)
+            delay(backoffMs)
+        }
+    }
+
+    /**
+     * Parse an SSE `data:` line into `(kind, object)`, dropping keepalive comments
+     * and any frame without a string `kind`. Kept internal + pure for unit testing.
+     */
+    internal fun parseFrame(data: String): Pair<String, JsonObject>? {
+        val trimmed = data.trim()
+        if (trimmed.isEmpty() || trimmed.startsWith(":")) return null
+        return try {
+            val obj = json.parseToJsonElement(trimmed).jsonObject
+            val kindEl = obj["kind"] ?: return null
+            if (kindEl is JsonNull) return null
+            val kind = kindEl.jsonPrimitive.content
+            if (kind.isEmpty()) null else kind to obj
+        } catch (_: Exception) {
+            null
+        }
+    }
+
+    private fun grow(current: Long): Long = (current * 2).coerceAtMost(MAX_BACKOFF_MS)
+
+    private companion object {
+        const val STREAM_PATH = "api/v1/public/shard/stream"
+        const val INITIAL_BACKOFF_MS = 2_000L
+        const val MAX_BACKOFF_MS = 30_000L
+    }
+}

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

@@ -0,0 +1,21 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.core.net
+
+import kotlinx.serialization.json.JsonObject
+
+/**
+ * A lifecycle or data event from the public shard SSE stream (PLAN.md §6.2).
+ *
+ *  - [Open]   — a connection was established (drive the live indicator on).
+ *  - [Closed] — the connection dropped or none is available (indicator off);
+ *               [ShardStreamClient] will reconnect with backoff.
+ *  - [Frame]  — a live event: its `kind` plus the raw JSON object, which the
+ *               boards decode into their DTO (`champ.update` → `ChampDto`, …).
+ */
+sealed interface ShardStreamEvent {
+    data object Open : ShardStreamEvent
+    data object Closed : ShardStreamEvent
+    data class Frame(val kind: String, val data: JsonObject) : ShardStreamEvent
+}

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

@@ -0,0 +1,86 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.core.net
+
+import com.runicgateway.app.core.auth.SessionManager
+import com.runicgateway.app.data.api.AuthRefreshApi
+import com.runicgateway.app.data.api.dto.MobileRefreshRequest
+import okhttp3.Authenticator
+import okhttp3.Request
+import okhttp3.Response
+import okhttp3.Route
+import java.io.IOException
+import javax.inject.Inject
+import javax.inject.Singleton
+
+/**
+ * Transparently refreshes an expired access token on a bearer `401` and replays
+ * the request (PLAN.md §4.1, §4.3). Refresh tokens are single-use and rotated, so
+ * this is serialized behind a mutex: concurrent 401s trigger exactly one refresh
+ * and the losers reuse its result. A refresh that comes back `401` means the
+ * session is truly dead → sign out; a network error leaves the session intact so
+ * a later call can retry.
+ *
+ * The refresh call runs on [AuthRefreshApi] (its own bare client with no
+ * authenticator), so it can never recurse back into here.
+ */
+@Singleton
+class TokenAuthenticator @Inject constructor(
+    private val sessionManager: SessionManager,
+    private val refreshApi: AuthRefreshApi,
+) : Authenticator {
+
+    private val lock = Any()
+
+    override fun authenticate(route: Route?, response: Response): Request? {
+        val failed = response.request
+        // Credential endpoints (login/refresh) must never be "refreshed".
+        if (failed.header(Http.NO_SESSION_HEADER) != null) return null
+        // Give up after a single refresh+replay to avoid an auth loop.
+        if (priorResponseCount(response) >= 2) return null
+
+        val attemptedAuth = failed.header(Http.AUTHORIZATION)
+
+        synchronized(lock) {
+            // Another thread may have already refreshed while we waited on the lock.
+            val current = sessionManager.currentAccessToken()
+            if (current != null && Http.bearer(current) != attemptedAuth) {
+                return failed.retryWith(current)
+            }
+
+            val refreshToken = sessionManager.currentRefreshToken()
+                ?: return null // already signed out
+
+            val refreshed = try {
+                refreshApi.refresh(MobileRefreshRequest(refreshToken)).execute()
+            } catch (_: IOException) {
+                // Transient — surface the original 401 but keep the session.
+                return null
+            }
+
+            val body = refreshed.body()
+            if (!refreshed.isSuccessful || body == null) {
+                // The refresh token is dead (401/expired/revoked) → session is over.
+                sessionManager.onSignedOut()
+                return null
+            }
+
+            sessionManager.onRefreshed(body.accessToken, body.refreshToken, body.user)
+            return failed.retryWith(body.accessToken)
+        }
+    }
+
+    private fun Request.retryWith(accessToken: String): Request =
+        newBuilder().header(Http.AUTHORIZATION, Http.bearer(accessToken)).build()
+
+    private fun priorResponseCount(response: Response): Int {
+        var count = 1
+        var prior = response.priorResponse
+        while (prior != null) {
+            count++
+            prior = prior.priorResponse
+        }
+        return count
+    }
+}

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

@@ -0,0 +1,24 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.core.net
+
+import okhttp3.Interceptor
+import okhttp3.Response
+
+/**
+ * Sets a stable, identifiable User-Agent on every request. The website mounts a
+ * bot/scanner guard ahead of routing (PLAN.md §8); a native client must present
+ * a sane UA so it is not caught by the scanner heuristics that reject blank or
+ * default agents. Constructed with the app's UA string in the network module.
+ */
+class UserAgentInterceptor(
+    private val userAgent: String,
+) : Interceptor {
+    override fun intercept(chain: Interceptor.Chain): Response {
+        val request = chain.request().newBuilder()
+            .header("User-Agent", userAgent)
+            .build()
+        return chain.proceed(request)
+    }
+}

app/src/main/java/com/runicgateway/app/core/prefs/ServerPreferences.kt

@@ -0,0 +1,48 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.core.prefs
+
+import android.content.Context
+import androidx.datastore.core.DataStore
+import androidx.datastore.preferences.core.Preferences
+import androidx.datastore.preferences.core.edit
+import androidx.datastore.preferences.core.stringPreferencesKey
+import androidx.datastore.preferences.preferencesDataStore
+import kotlinx.coroutines.flow.Flow
+import kotlinx.coroutines.flow.first
+import kotlinx.coroutines.flow.map
+import javax.inject.Inject
+import javax.inject.Singleton
+
+private val Context.serverDataStore: DataStore<Preferences> by preferencesDataStore(name = "server")
+
+/**
+ * Persists the selected shard website base URL (PLAN.md §3). The base URL is
+ * non-sensitive, so it lives in plain DataStore; tokens (M3) will use
+ * EncryptedSharedPreferences instead, never this store.
+ */
+@Singleton
+class ServerPreferences @Inject constructor(
+    @param:dagger.hilt.android.qualifiers.ApplicationContext private val context: Context,
+) {
+    private val store = context.serverDataStore
+
+    /** Emits the saved base URL, or null before first-run connect completes. */
+    val baseUrl: Flow<String?> = store.data.map { it[KEY_BASE_URL] }
+
+    suspend fun currentBaseUrl(): String? = baseUrl.first()
+
+    suspend fun setBaseUrl(url: String) {
+        store.edit { it[KEY_BASE_URL] = url }
+    }
+
+    /** Clears the base URL — used by a Settings → Server switch (hard reset, §3). */
+    suspend fun clear() {
+        store.edit { it.remove(KEY_BASE_URL) }
+    }
+
+    private companion object {
+        val KEY_BASE_URL = stringPreferencesKey("base_url")
+    }
+}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

@@ -0,0 +1,65 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.core.result
+
+import kotlinx.coroutines.CancellationException
+import kotlinx.serialization.SerializationException
+import retrofit2.HttpException
+import java.io.IOException
+
+/**
+ * The single result type every repository call returns (PLAN.md §7). The UI
+ * degrades gracefully on a down backend or shard: a repository never throws for
+ * an expected failure, it returns a typed variant the screen can render.
+ *
+ *  - [Ok]           — a 2xx response with a decoded body.
+ *  - [HttpError]    — the server answered with a non-2xx status.
+ *  - [NetworkError] — the request never got an answer (offline, DNS, TLS, timeout).
+ */
+sealed interface ApiResult<out T> {
+    data class Ok<T>(val data: T) : ApiResult<T>
+    data class HttpError(val status: Int, val message: String? = null) : ApiResult<Nothing>
+    data class NetworkError(val cause: Throwable) : ApiResult<Nothing>
+}
+
+/** True for the "shard/sidecar down" signal the player screens treat as offline (§6.3, §7). */
+fun ApiResult<*>.isShardUnavailable(): Boolean =
+    this is ApiResult.HttpError && status == 503
+
+/** Map an [ApiResult.Ok] body while preserving the failure variants unchanged. */
+inline fun <T, R> ApiResult<T>.map(transform: (T) -> R): ApiResult<R> = when (this) {
+    is ApiResult.Ok -> ApiResult.Ok(transform(data))
+    is ApiResult.HttpError -> this
+    is ApiResult.NetworkError -> this
+}
+
+/**
+ * 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())
+} catch (e: CancellationException) {
+    throw e
+} catch (e: HttpException) {
+    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/core/web/WebHandoff.kt

@@ -0,0 +1,32 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.core.web
+
+import android.content.ActivityNotFoundException
+import android.content.Context
+import android.net.Uri
+import androidx.browser.customtabs.CustomTabsIntent
+
+/**
+ * Opens the website's own pages in a Chrome Custom Tab (PLAN.md §4.2):
+ * registration, invite acceptance, forgot/reset password, and SSO all stay
+ * website-handled, so the app hands off rather than rebuilding those flows. The
+ * user completes them in the browser and returns to sign in natively (§4.1).
+ */
+object WebHandoff {
+
+    /**
+     * Launch [url] in a Custom Tab. Returns false if no browser could handle it
+     * (extremely rare on Android) so the caller can surface a fallback.
+     */
+    fun open(context: Context, url: String): Boolean = try {
+        CustomTabsIntent.Builder()
+            .setShowTitle(true)
+            .build()
+            .launchUrl(context, Uri.parse(url))
+        true
+    } catch (_: ActivityNotFoundException) {
+        false
+    }
+}

app/src/main/java/com/runicgateway/app/core/web/WebsiteUrls.kt

@@ -0,0 +1,33 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.core.web
+
+import com.runicgateway.app.core.net.BaseUrlHolder
+import javax.inject.Inject
+import javax.inject.Singleton
+
+/**
+ * Resolves the website's front-end page paths against the configured base URL,
+ * for the Custom-Tab hand-offs (PLAN.md §4.2). These are the React SPA routes
+ * (mirrored from `website/client` `App.jsx`), not API endpoints. Null before a
+ * shard site is configured.
+ */
+@Singleton
+class WebsiteUrls @Inject constructor(
+    private val baseUrlHolder: BaseUrlHolder,
+) {
+    private fun resolve(path: String): String? =
+        baseUrlHolder.current?.resolve(path)?.toString()
+
+    /** Create an account on the website. */
+    fun register(): String? = resolve(REGISTER)
+
+    /** Forgot / reset password (the flow built on the backend before app work, §8). */
+    fun forgotPassword(): String? = resolve(FORGOT)
+
+    private companion object {
+        const val REGISTER = "account/register"
+        const val FORGOT = "account/forgot"
+    }
+}

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

@@ -0,0 +1,97 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.data.api
+
+import com.runicgateway.app.data.api.dto.AdminDashboardDto
+import com.runicgateway.app.data.api.dto.AdminPostDto
+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.AdminWikiCategoryDto
+import com.runicgateway.app.data.api.dto.WikiCategoryRequest
+import com.runicgateway.app.data.api.dto.AdminWikiTagDto
+import retrofit2.Response
+import retrofit2.http.Body
+import retrofit2.http.DELETE
+import retrofit2.http.GET
+import retrofit2.http.PATCH
+import retrofit2.http.PUT
+import retrofit2.http.POST
+import retrofit2.http.Path
+
+/**
+ * The M10 staff-operations surface over `/api/v1/admin/…` (PLAN.md §1, §6.4). On
+ * the authed client — every call carries the bearer, and the backend re-checks the
+ * caller's role on every request (`staffOnly` / `modAccess` / `adminOnly`), so a
+ * demoted user is refused server-side even if a stale menu still showed the entry.
+ *
+ * Grows one group at a time (dashboard first); moderation, support, and content
+ * endpoints are added with their screens.
+ */
+interface AdminApi {
+
+    /** `GET /admin/dashboard` — summary counts + site mode (any staff role). */
+    @GET("api/v1/admin/dashboard")
+    suspend fun dashboard(): AdminDashboardDto
+
+    /** `PUT /admin/site-mode` — switch live/maintenance (admin only; 403 otherwise). */
+    @PUT("api/v1/admin/site-mode")
+    suspend fun setSiteMode(@Body body: SiteModeRequest): SiteModeStateDto
+
+    // ── Content: news posts (any staff role) ──────────────────────────────
+    @GET("api/v1/admin/posts")
+    suspend fun posts(): List<AdminPostDto>
+
+    @POST("api/v1/admin/posts")
+    suspend fun createPost(@Body body: PostCreateRequest): AdminPostDto
+
+    @PATCH("api/v1/admin/posts/{id}/publish")
+    suspend fun publishPost(@Path("id") id: Long, @Body body: PublishRequest): AdminPostDto
+
+    @DELETE("api/v1/admin/posts/{id}")
+    suspend fun deletePost(@Path("id") id: Long): Response<Unit>
+
+    // ── Content: wiki taxonomy (any staff role) ───────────────────────────
+    @GET("api/v1/admin/wiki/categories")
+    suspend fun wikiCategories(): List<AdminWikiCategoryDto>
+
+    @POST("api/v1/admin/wiki/categories")
+    suspend fun createWikiCategory(@Body body: WikiCategoryRequest): AdminWikiCategoryDto
+
+    @DELETE("api/v1/admin/wiki/categories/{id}")
+    suspend fun deleteWikiCategory(@Path("id") id: Long): Response<Unit>
+
+    @GET("api/v1/admin/wiki/tags")
+    suspend fun wikiTags(): List<AdminWikiTagDto>
+
+    // ── Moderation: shard write plane (admin/moderator) ───────────────────
+    @POST("api/v1/admin/shard/kick")
+    suspend fun kick(@Body body: KickRequest): Response<Unit>
+
+    @POST("api/v1/admin/shard/ban")
+    suspend fun ban(@Body body: BanRequest): Response<Unit>
+
+    @POST("api/v1/admin/shard/unban")
+    suspend fun unban(@Body body: UnbanRequest): Response<Unit>
+
+    @POST("api/v1/admin/shard/broadcast")
+    suspend fun broadcast(@Body body: BroadcastRequest): Response<Unit>
+
+    // ── Support queue: help pages (admin/moderator) ───────────────────────
+    @GET("api/v1/admin/shard/pages")
+    suspend fun supportPages(): List<SupportPageDto>
+
+    @POST("api/v1/admin/shard/pages/{id}/respond")
+    suspend fun respondPage(@Path("id") id: String, @Body body: PageRespondRequest): Response<Unit>
+
+    @POST("api/v1/admin/shard/pages/{id}/close")
+    suspend fun closePage(@Path("id") id: String): Response<Unit>
+}

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

@@ -0,0 +1,47 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.data.api
+
+import com.runicgateway.app.data.api.dto.MeResponse
+import com.runicgateway.app.data.api.dto.MobileLoginRequest
+import com.runicgateway.app.data.api.dto.MobileLogoutRequest
+import com.runicgateway.app.data.api.dto.MobileTokenResponse
+import retrofit2.Response
+import retrofit2.http.Body
+import retrofit2.http.GET
+import retrofit2.http.Header
+import retrofit2.http.Headers
+import retrofit2.http.POST
+
+/**
+ * The native bearer-auth surface (PLAN.md §4.1). Login and logout run on the main
+ * OkHttp client; [com.runicgateway.app.core.net.AuthInterceptor] attaches the
+ * access token to logout + `/auth/me`, and [com.runicgateway.app.core.net.TokenAuthenticator]
+ * transparently refreshes on a `401`.
+ *
+ * Login is tagged [com.runicgateway.app.core.net.Http.NO_SESSION_HEADER] so it
+ * carries no bearer and a credential `401` (bad password / `totpRequired`) is not
+ * misread as an expired session. It returns a raw [Response] so the caller can
+ * inspect the status and parse the `{ totpRequired }` error body.
+ */
+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,
+        @Header("X-Trust-Token") trustToken: String? = null,
+    ): Response<MobileTokenResponse>
+
+    @POST("api/v1/auth/mobile/logout")
+    suspend fun logout(@Body body: MobileLogoutRequest): Response<Unit>
+
+    /** Current user — the app's authoritative role source, re-validated on resume (§4.3). */
+    @GET("api/v1/auth/me")
+    suspend fun me(): MeResponse
+}

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

@@ -0,0 +1,27 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.data.api
+
+import com.runicgateway.app.data.api.dto.MobileRefreshRequest
+import com.runicgateway.app.data.api.dto.MobileTokenResponse
+import retrofit2.Call
+import retrofit2.http.Body
+import retrofit2.http.Headers
+import retrofit2.http.POST
+
+/**
+ * The token-rotation endpoint, isolated onto its own **bare** OkHttp client
+ * (no auth interceptor, no authenticator) so refreshing can never recurse
+ * through the very [com.runicgateway.app.core.net.TokenAuthenticator] that calls
+ * it (PLAN.md §4.3). It is a blocking [Call] because the authenticator runs on an
+ * OkHttp dispatcher thread, outside any coroutine, and executes it synchronously.
+ *
+ * Tagged `NO_SESSION` so it carries no stale bearer.
+ */
+interface AuthRefreshApi {
+
+    @Headers("X-Runic-No-Session: 1")
+    @POST("api/v1/auth/mobile/refresh")
+    fun refresh(@Body body: MobileRefreshRequest): Call<MobileTokenResponse>
+}

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

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

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

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

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

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

@@ -0,0 +1,209 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+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
+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.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
+import com.runicgateway.app.data.api.dto.WikiPageDto
+import com.runicgateway.app.data.api.dto.WikiSummaryDto
+import com.runicgateway.app.data.api.dto.WikiTagDto
+import retrofit2.http.Body
+import retrofit2.http.GET
+import retrofit2.http.POST
+import retrofit2.http.Path
+import retrofit2.http.Query
+import retrofit2.http.Url
+
+/**
+ * The public (unauthenticated) surface consumed in M1: site status/settings,
+ * news posts, CMS pages, wiki, and the contact form (PLAN.md §6.1). Paths are
+ * relative to the sentinel base host; [com.runicgateway.app.core.net.HostSelectionInterceptor]
+ * retargets them onto the configured shard site. The public shard widgets (§6.2)
+ * are added in M2; auth (§4) and player game data (§6.3) arrive in later milestones.
+ * The live SSE stream (`/public/shard/stream`) is not a Retrofit call — it is
+ * consumed via OkHttp in [com.runicgateway.app.core.net.ShardStreamClient].
+ */
+interface PublicApi {
+
+    // ── First-run probe (absolute URL; bypasses host rewriting) ──────────
+    /**
+     * Validates a candidate site during the first-run connect flow (§3). Takes a
+     * fully-qualified URL so the request carries a real host and is left
+     * untouched by the host interceptor — the probe targets the URL the user
+     * just typed, not the (not-yet-configured) base.
+     */
+    @GET
+    suspend fun probeStatus(@Url absoluteStatusUrl: String): StatusDto
+
+    // ── Site status / settings ───────────────────────────────────────────
+    @GET("api/v1/public/status")
+    suspend fun getStatus(): StatusDto
+
+    @GET("api/v1/public/settings")
+    suspend fun getSettings(): SettingsDto
+
+    // ── News & content ───────────────────────────────────────────────────
+    @GET("api/v1/public/posts/{category}")
+    suspend fun getPosts(@Path("category") category: String): List<PostDto>
+
+    @GET("api/v1/public/posts/{category}/{idOrSlug}")
+    suspend fun getPost(
+        @Path("category") category: String,
+        @Path("idOrSlug") idOrSlug: String,
+    ): PostDto
+
+    @GET("api/v1/public/pages/{slug}")
+    suspend fun getPage(@Path("slug") slug: String): PageDto
+
+    // ── Wiki ─────────────────────────────────────────────────────────────
+    @GET("api/v1/public/wiki")
+    suspend fun getWikiPages(
+        @Query("q") query: String? = null,
+        @Query("category") category: String? = null,
+        @Query("tag") tag: String? = null,
+    ): List<WikiSummaryDto>
+
+    @GET("api/v1/public/wiki/categories")
+    suspend fun getWikiCategories(): List<WikiCategoryDto>
+
+    @GET("api/v1/public/wiki/tags")
+    suspend fun getWikiTags(): List<WikiTagDto>
+
+    @GET("api/v1/public/wiki/{slug}")
+    suspend fun getWikiPage(@Path("slug") slug: String): WikiPageDto
+
+    // ── Contact ──────────────────────────────────────────────────────────
+    @POST("api/v1/public/contact")
+    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
+
+    @GET("api/v1/public/shard/feed")
+    suspend fun getShardFeed(
+        @Query("kind") kind: String? = null,
+        @Query("limit") limit: Int? = null,
+    ): List<FeedEventDto>
+
+    @GET("api/v1/public/shard/economy")
+    suspend fun getShardEconomy(@Query("limit") limit: Int? = null): List<EconomySampleDto>
+
+    @GET("api/v1/public/shard/online")
+    suspend fun getShardOnline(): List<OnlineStaffDto>
+
+    @GET("api/v1/public/shard/presence")
+    suspend fun getShardPresence(): PresenceDto
+
+    @GET("api/v1/public/shard/champs")
+    suspend fun getShardChamps(): List<ChampDto>
+
+    @GET("api/v1/public/shard/guilds")
+    suspend fun getShardGuilds(): List<GuildDto>
+
+    @GET("api/v1/public/shard/governors")
+    suspend fun getShardGovernors(): List<GovernorDto>
+
+    @GET("api/v1/public/shard/governors/{city}/history")
+    suspend fun getShardGovernorHistory(
+        @Path("city") city: String,
+        @Query("limit") limit: Int? = null,
+    ): List<GovernorTermDto>
+
+    @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/SsoApi.kt

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

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

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

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

@@ -0,0 +1,179 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.data.api.dto
+
+import kotlinx.serialization.SerialName
+import kotlinx.serialization.Serializable
+import kotlinx.serialization.json.JsonElement
+
+/**
+ * Wire shapes for the M10 staff-operations surface over `/api/v1/admin/…` (PLAN.md
+ * §1, §6.4). These are consumed only by the staff screens (dashboard, moderation,
+ * support, content); every DTO ignores unknown keys (NetworkModule's lenient Json)
+ * so additive backend fields stay safe. Nothing here is auto-provisioned or secret.
+ */
+
+/** `GET /admin/dashboard` — the staff landing summary. */
+@Serializable
+data class AdminDashboardDto(
+    @SerialName("site_mode") val siteMode: String = "live",
+    @SerialName("last_change") val lastChange: SiteModeChangeDto = SiteModeChangeDto(),
+    val counts: AdminCountsDto = AdminCountsDto(),
+    @SerialName("recent_activity") val recentActivity: List<AdminActivityDto> = emptyList(),
+)
+
+@Serializable
+data class SiteModeChangeDto(
+    val at: String? = null,
+    val by: String? = null,
+)
+
+@Serializable
+data class AdminCountsDto(
+    /** Post counts keyed by DB category (`news`, `five_on_friday`, …). */
+    val posts: Map<String, Int> = emptyMap(),
+    val users: Int = 0,
+)
+
+/** One row of the recent admin-activity log. `detail` is provider-shaped JSON. */
+@Serializable
+data class AdminActivityDto(
+    val id: Long = 0,
+    val username: String? = null,
+    val action: String = "",
+    val detail: JsonElement? = null,
+    @SerialName("created_at") val createdAt: String? = null,
+)
+
+/** `PUT /admin/site-mode` request + response. */
+@Serializable
+data class SiteModeRequest(val mode: String)
+
+@Serializable
+data class SiteModeStateDto(
+    @SerialName("site_mode") val siteMode: String = "live",
+    @SerialName("changed_at") val changedAt: String? = null,
+    @SerialName("changed_by") val changedBy: String? = null,
+)
+
+// ── Content: news posts ───────────────────────────────────────────────────
+
+/**
+ * A post row from `GET /admin/posts` (all posts, incl. unpublished — unlike the
+ * public feed). `published` is a 0/1 flag (MariaDB tinyint), exposed as [isPublished].
+ */
+@Serializable
+data class AdminPostDto(
+    val id: Long,
+    val category: String = "",
+    val title: String = "",
+    val slug: String? = null,
+    val excerpt: String? = null,
+    val body: String? = null,
+    @SerialName("image_url") val imageUrl: String? = null,
+    val published: Int = 0,
+    @SerialName("published_at") val publishedAt: String? = null,
+    @SerialName("created_at") val createdAt: String? = null,
+) {
+    val isPublished: Boolean get() = published != 0
+}
+
+/** `POST/PUT /admin/posts` body. `category` is a URL category the backend maps
+ *  (news | five-on-friday | newsletter | screenshots). */
+@Serializable
+data class PostCreateRequest(
+    val category: String,
+    val title: String,
+    val excerpt: String? = null,
+    val body: String? = null,
+    @SerialName("image_url") val imageUrl: String? = null,
+    val published: Boolean = false,
+)
+
+/** `PATCH /admin/posts/:id/publish` body. */
+@Serializable
+data class PublishRequest(val published: Boolean)
+
+// ── Content: wiki taxonomy ────────────────────────────────────────────────
+
+/** A wiki category from `GET /admin/wiki/categories` (with page counts). */
+@Serializable
+data class AdminWikiCategoryDto(
+    val id: Long,
+    val slug: String = "",
+    val title: String = "",
+    val description: String? = null,
+    @SerialName("sort_order") val sortOrder: Int? = null,
+    @SerialName("page_count") val pageCount: Int? = null,
+    @SerialName("published_count") val publishedCount: Int? = null,
+)
+
+/** `POST /admin/wiki/categories` body. */
+@Serializable
+data class WikiCategoryRequest(
+    val slug: String,
+    val title: String,
+    val description: String? = null,
+    @SerialName("sort_order") val sortOrder: Int? = null,
+)
+
+/** A wiki tag from `GET /admin/wiki/tags` (tags derive from pages; read-only here). */
+@Serializable
+data class AdminWikiTagDto(
+    val id: Long,
+    val slug: String = "",
+    val label: String = "",
+    @SerialName("published_count") val publishedCount: Int? = null,
+)
+
+// ── Moderation (admin/moderator; shard write plane) ───────────────────────
+
+/** `POST /admin/shard/kick` — at least one of account/serial. */
+@Serializable
+data class KickRequest(val account: String? = null, val serial: String? = null)
+
+/** `POST /admin/shard/ban` — account/serial + optional duration (0/absent = indefinite). */
+@Serializable
+data class BanRequest(
+    val account: String? = null,
+    val serial: String? = null,
+    @SerialName("durationSec") val durationSec: Long? = null,
+    val reason: String? = null,
+)
+
+/** `POST /admin/shard/unban`. */
+@Serializable
+data class UnbanRequest(val account: String)
+
+/** `POST /admin/shard/broadcast` — a system message to everyone online. */
+@Serializable
+data class BroadcastRequest(val text: String, val hue: Int? = null)
+
+// ── Support queue (admin/moderator; help pages) ───────────────────────────
+
+/**
+ * One open help page from `GET /admin/shard/pages` (INTEGRATION.md §4). `pageId`
+ * is the sender's in-game serial (the `:id` for respond/close). Permissive — the
+ * shard-state fields beyond these (coords, timing) are ignored.
+ */
+@Serializable
+data class SupportPageDto(
+    @SerialName("pageId") val pageId: String = "",
+    val type: String? = null,
+    val message: String? = null,
+    val handled: Boolean? = null,
+    val handler: String? = null,
+    val sender: SupportActorDto? = null,
+)
+
+/** The page's sender (actor object); [account] present when the character is linked. */
+@Serializable
+data class SupportActorDto(
+    val name: String? = null,
+    val account: String? = null,
+)
+
+/** `POST /admin/shard/pages/:id/respond` — reply, optionally closing the page. */
+@Serializable
+data class PageRespondRequest(val message: String, val close: Boolean = false)

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

@@ -0,0 +1,86 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.data.api.dto
+
+import kotlinx.serialization.Serializable
+
+/**
+ * The mobile bearer-auth wire shapes (PLAN.md §4.1). Field names match the
+ * backend's `auth/mobile` controller and `/auth/me` exactly; every DTO ignores
+ * unknown keys (NetworkModule's lenient Json), so additive backend fields are
+ * safe (§8, recorded for M1).
+ */
+
+/**
+ * `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. */
+@Serializable
+data class MobileRefreshRequest(val refreshToken: String)
+
+/** `POST /auth/mobile/logout` body — revoke this session or (with [all]) every session. */
+@Serializable
+data class MobileLogoutRequest(
+    val refreshToken: String? = null,
+    val all: Boolean? = null,
+)
+
+/**
+ * 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(
+    val accessToken: String,
+    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). */
+@Serializable
+data class SafeUserDto(
+    val id: Long,
+    val username: String,
+    val role: String,
+)
+
+/** `GET /auth/me` envelope — the role source, re-validated on resume (§4.3). */
+@Serializable
+data class MeResponse(val user: SafeUserDto)
+
+/**
+ * The `401 { totpRequired: true }` body the single-request 2FA flow returns when
+ * an account has TOTP on and no/invalid code accompanied the login (§4.1). Parsed
+ * from the error body since it is not a 2xx response.
+ */
+@Serializable
+data class TotpRequiredError(
+    val totpRequired: Boolean = false,
+    val message: String? = null,
+)

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

@@ -0,0 +1,26 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.data.api.dto
+
+import kotlinx.serialization.Serializable
+
+/** `POST /public/contact` request body. */
+@Serializable
+data class ContactRequest(
+    val name: String,
+    val email: String,
+    val message: String,
+)
+
+/**
+ * `POST /public/contact` response (website `mailer.sendContactMessage`). Either
+ * `{ sent: true }`, or `{ sent: false, fallback: "mailto", email }` when the
+ * site has no mailer configured and the user should email directly instead.
+ */
+@Serializable
+data class ContactResponse(
+    val sent: Boolean = false,
+    val fallback: String? = null,
+    val email: String? = null,
+)

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

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

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

@@ -0,0 +1,38 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.data.api.dto
+
+import kotlinx.serialization.SerialName
+import kotlinx.serialization.Serializable
+import kotlinx.serialization.json.JsonObject
+
+/**
+ * `GET /public/pages/:slug` — a block-based CMS page (website `pages.model.js`
+ * `serialize`). Everything block-specific lives inside `props`; the renderer
+ * dispatches on `type`. `props` is left as a raw JSON object so new block types
+ * or props never break decoding — the renderer reads the keys it knows and
+ * ignores the rest.
+ */
+@Serializable
+data class PageDto(
+    val id: Long,
+    val slug: String = "",
+    val title: String = "",
+    val status: String = "",
+    val blocks: List<BlockDto> = emptyList(),
+    @SerialName("publishedAt") val publishedAt: String? = null,
+    @SerialName("updatedAt") val updatedAt: String? = null,
+)
+
+/**
+ * One CMS block. Known types (website `src/blocks/types`): `heading`,
+ * `rich_text`, `image`, `quote`, `cta`, `divider`, `two_column`. Container
+ * blocks (`two_column`) hold sub-block arrays inside their props.
+ */
+@Serializable
+data class BlockDto(
+    val type: String = "",
+    val props: JsonObject = JsonObject(emptyMap()),
+    val visible: Boolean = true,
+)

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

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

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

@@ -0,0 +1,26 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.data.api.dto
+
+import kotlinx.serialization.SerialName
+import kotlinx.serialization.Serializable
+
+/**
+ * `GET /public/posts/:category` (list) and `/public/posts/:category/:idOrSlug`
+ * (detail). One shape serves both; the list omits nothing the app renders. The
+ * `body` (HTML) is present on the detail response and rendered there.
+ */
+@Serializable
+data class PostDto(
+    val id: Long,
+    /** Stored DB category (`news | five_on_friday | newsletter | screenshot`). */
+    val category: String = "",
+    val title: String = "",
+    val slug: String? = null,
+    val excerpt: String? = null,
+    val body: String? = null,
+    @SerialName("image_url") val imageUrl: String? = null,
+    @SerialName("published_at") val publishedAt: String? = null,
+    @SerialName("created_at") val createdAt: String? = null,
+)

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

@@ -0,0 +1,108 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.data.api.dto
+
+import kotlinx.serialization.SerialName
+import kotlinx.serialization.Serializable
+import kotlinx.serialization.json.JsonElement
+
+/**
+ * DTOs for the public site/identity endpoints. Shapes mirror the backend
+ * responses (website `public.controller.js` + `settings.model.js`); unknown
+ * keys are ignored by the JSON parser so additive backend fields never break
+ * decoding (PLAN.md §8 "additive, v1").
+ */
+
+/** `GET /public/version` and the `version` block embedded in `/public/status`. */
+@Serializable
+data class VersionDto(
+    val service: String = "",
+    val api: String = "",
+    val server: String = "",
+)
+
+/** `GET /public/status` — site mode + version for the first-run probe (§3). */
+@Serializable
+data class StatusDto(
+    val mode: String = "live",
+    @SerialName("status_message") val statusMessage: String = "",
+    val version: VersionDto = VersionDto(),
+) {
+    val isMaintenance: Boolean get() = mode.equals("maintenance", ignoreCase = true)
+}
+
+/** Per-shard branding block the app themes itself from (§3, §6.1). */
+@Serializable
+data class BrandDto(
+    val name: String = "",
+    val shortName: String = "",
+    val tagline: String = "",
+    val description: String? = null,
+    val contactEmail: String = "",
+    val url: String = "",
+    /** Seed/accent color as a hex string, e.g. "#7f99bd". */
+    val accent: String = "",
+    /** Asset URL or site-relative path; empty = none. Resolve against the base URL. */
+    val logo: String = "",
+    val hero: String = "",
+    val favicon: String = "",
+)
+
+/** Derived, public-safe registration availability flags. */
+@Serializable
+data class RegistrationFlagsDto(
+    val password: Boolean = false,
+    val sso: Boolean = false,
+)
+
+/**
+ * Push-notification relay config (M7). [ntfyUrl] is the client-facing ntfy base
+ * URL the app's embedded distributor registers its device topic against; null (or
+ * absent, on an older backend) means push isn't configured for this shard and the
+ * Notifications screen shows it as unavailable.
+ */
+@Serializable
+data class PushConfigDto(
+    val ntfyUrl: String? = null,
+)
+
+/**
+ * `GET /public/settings` — whitelisted settings + branding. Only the keys the
+ * app consumes are modeled; other whitelisted keys are ignored.
+ */
+@Serializable
+data class SettingsDto(
+    @SerialName("site_title") val siteTitle: String? = null,
+    @SerialName("status_message") val statusMessage: String? = null,
+    @SerialName("maintenance_message") val maintenanceMessage: String? = null,
+    val registration: RegistrationFlagsDto = RegistrationFlagsDto(),
+    val gameAccountSignup: Boolean = false,
+    val brand: BrandDto = BrandDto(),
+    /** Push relay config (M7); default (null ntfyUrl) on a backend that predates it. */
+    val push: PushConfigDto = PushConfigDto(),
+    /**
+     * The admin's **resolved** theme tokens — the CSS custom properties the site
+     * paints, already layered `:root ← preset ← custom` by the server
+     * (THEMING_AND_NAV.md §3). Absent when no `theme_visual` row exists, which
+     * means "the shipped defaults" and is the untouched-instance path.
+     *
+     * Held as a raw [JsonElement] rather than a `Map<String, String>` on
+     * purpose: a single unexpected value must not fail the decode of the whole
+     * settings payload and take `brand` and `push` down with it. It is coerced
+     * field-by-field by `SiteAppearance.from`.
+     *
+     * The raw `theme_visual` / `brand_assets` rows ride along in this same
+     * response and are deliberately **not** modeled — they are inputs, and
+     * re-deriving a palette from them would be a second `resolveThemeTokens` in
+     * Kotlin, guaranteed to drift (§3).
+     */
+    val theme: JsonElement? = null,
+    /**
+     * The public nav overrides, as the raw JSON **string** stored in
+     * `settings.value` (TEXT) — so it is parsed a second time, exactly as the web
+     * client's `parseJsonSetting` does. Absent when the admin never edited the
+     * nav.
+     */
+    @SerialName("nav_public") val navPublic: 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

@@ -0,0 +1,199 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.data.api.dto
+
+import kotlinx.serialization.Serializable
+import kotlinx.serialization.json.JsonObject
+
+/**
+ * DTOs for the public shard widgets (PLAN.md §6.2). Shapes mirror the website's
+ * `public/shard.controller.js` responses and the live SSE frames emitted by
+ * `utils/shardBroadcast.js`. The champ/guild/governor board reads return the
+ * stored event payload verbatim (a permissive object), so only the fields the app
+ * renders are modeled; unknown keys are ignored by the JSON parser, and the live
+ * `*.update` frames on `/public/shard/stream` decode into these same DTOs.
+ */
+
+/**
+ * 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: String? = null,
+    val name: String? = null,
+    val acct: String? = null,
+    val webId: String? = null,
+) {
+    /** Best display label for this actor. */
+    val label: String get() = name ?: acct ?: "Someone"
+}
+
+/** A gold-supply sample (`economy.supply`), oldest → newest in the series. */
+@Serializable
+data class EconomySampleDto(
+    val accounts: Int? = null,
+    val gold: Double? = null,
+    val t: Long? = null,
+)
+
+/** `GET /public/shard/status` — connection state + online count + latest economy. */
+@Serializable
+data class ShardStatusDto(
+    val enabled: Boolean = false,
+    /** Sidecar link state: `connected` / `disconnected` / … */
+    val status: String? = null,
+    /** Whether the in-game plugin is currently connected to the sidecar. */
+    val pluginConnected: Boolean = false,
+    /** ISO timestamp of the last ingested event, or null. */
+    val lastEventAt: String? = null,
+    val onlineCount: Int = 0,
+    val economy: EconomySampleDto? = null,
+) {
+    /** True when the shard is live (link enabled and the plugin is connected). */
+    val isOnline: Boolean get() = enabled && pluginConnected
+}
+
+/**
+ * `GET /public/shard/feed` — a stored notable event. The domain fields live under
+ * [payload]; the live SSE frames carry those same fields at the top level (see
+ * `ShardEventText`).
+ */
+@Serializable
+data class FeedEventDto(
+    val id: Long = 0,
+    val kind: String = "",
+    val t: Long? = null,
+    val bootId: String? = null,
+    val payload: JsonObject? = null,
+    val createdAt: String? = null,
+)
+
+/**
+ * `GET /public/shard/online` — a staff member currently in-world. Location is only
+ * present for privileged viewers server-side; anonymous/app callers see name+serial.
+ */
+@Serializable
+data class OnlineStaffDto(
+    val serial: String? = null,
+    val name: String? = null,
+    val map: String? = null,
+    val x: Int? = null,
+    val y: Int? = null,
+    val z: Int? = null,
+)
+
+/**
+ * A house on the public IDOC board (`GET /public/shard/houses`) — location only.
+ * Owner/price/decay detail is staff-only and never reaches the app.
+ */
+@Serializable
+data class HouseDto(
+    val serial: String = "",
+    val name: String? = null,
+    val region: String? = null,
+    val map: String? = null,
+    val x: Int? = null,
+    val y: Int? = null,
+    val z: Int? = null,
+    val isIdoc: Boolean = false,
+)
+
+/**
+ * A champion-spawn board entry (`GET /public/shard/champs` + live `champ.update`).
+ * Three families share the board (`category`: champion / mini / sea); the
+ * category-specific fields are all nullable.
+ */
+@Serializable
+data class ChampDto(
+    val serial: String = "",
+    val category: String? = null,
+    val type: String? = null,
+    val name: String? = null,
+    val status: String? = null,
+    val active: Boolean = false,
+    val map: String? = null,
+    val x: Int? = null,
+    val y: Int? = null,
+    val z: Int? = null,
+    val bossUp: Boolean = false,
+    val boss: String? = null,
+    val level: Int? = null,
+    val maxLevel: Int? = null,
+    val kills: Int? = null,
+    val maxKills: Int? = null,
+    val hits: Long? = null,
+    val hitsMax: Long? = null,
+    val restartAt: String? = null,
+    val t: Long? = null,
+)
+
+/** A guild board entry (`GET /public/shard/guilds` + live `guild.update`). */
+@Serializable
+data class GuildDto(
+    val id: Long = 0,
+    val name: String? = null,
+    val abbr: String? = null,
+    val members: Int? = null,
+    val online: Int? = null,
+    val alliance: String? = null,
+    val leader: ActorDto? = null,
+    val t: Long? = null,
+)
+
+/** A town-governor board entry (`GET /public/shard/governors` + live `city.update`). */
+@Serializable
+data class GovernorDto(
+    val city: String = "",
+    val governor: ActorDto? = null,
+    val governorElect: ActorDto? = null,
+    val electionPhase: String? = null,
+    val t: Long? = null,
+)
+
+/** One term in a city's governor ledger (`GET /public/shard/governors/:city/history`). */
+@Serializable
+data class GovernorTermDto(
+    val city: String? = null,
+    val governor: ActorDto? = null,
+    val startedAt: Long? = null,
+    val endedAt: Long? = null,
+    val votes: Int? = null,
+)
+
+/** `GET /public/shard/presence` — the online-population aggregate (live `presence.online`). */
+@Serializable
+data class PresenceDto(
+    val count: Int = 0,
+    val byFacet: Map<String, Int> = emptyMap(),
+    val byRegion: Map<String, Int> = emptyMap(),
+    val t: Long? = null,
+)

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

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

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

@@ -0,0 +1,76 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.data.api.dto
+
+import kotlinx.serialization.SerialName
+import kotlinx.serialization.Serializable
+
+/**
+ * Wiki DTOs (website `wiki.model.js` / `wiki.db.js`). The list route returns
+ * lighter summary rows (no body); the detail route returns the full page plus
+ * its tags, backlinks, and unresolved ("red") link targets.
+ */
+
+/** `GET /public/wiki` — a summary row (body omitted). */
+@Serializable
+data class WikiSummaryDto(
+    val id: Long,
+    val slug: String = "",
+    val title: String = "",
+    val excerpt: String? = null,
+    @SerialName("category_slug") val categorySlug: String? = null,
+    @SerialName("category_title") val categoryTitle: String? = null,
+    @SerialName("updated_at") val updatedAt: String? = null,
+    @SerialName("published_at") val publishedAt: String? = null,
+)
+
+/** `GET /public/wiki/:slug` — full page + tags/backlinks. */
+@Serializable
+data class WikiPageDto(
+    val id: Long,
+    val slug: String = "",
+    val title: String = "",
+    val body: String? = null,
+    val excerpt: String? = null,
+    @SerialName("category_slug") val categorySlug: String? = null,
+    @SerialName("category_title") val categoryTitle: String? = null,
+    @SerialName("updated_at") val updatedAt: String? = null,
+    @SerialName("published_at") val publishedAt: String? = null,
+    val tags: List<WikiTagRefDto> = emptyList(),
+    val backlinks: List<WikiBacklinkDto> = emptyList(),
+    @SerialName("missing_links") val missingLinks: List<String> = emptyList(),
+)
+
+/** A tag as attached to a page (slug + label only). */
+@Serializable
+data class WikiTagRefDto(
+    val slug: String = "",
+    val label: String = "",
+)
+
+/** A page that links to the current page. */
+@Serializable
+data class WikiBacklinkDto(
+    val slug: String = "",
+    val title: String = "",
+)
+
+/** `GET /public/wiki/categories`. */
+@Serializable
+data class WikiCategoryDto(
+    val id: Long,
+    val slug: String = "",
+    val title: String = "",
+    val description: String? = null,
+    @SerialName("published_count") val publishedCount: Long = 0,
+)
+
+/** `GET /public/wiki/tags`. */
+@Serializable
+data class WikiTagDto(
+    val id: Long,
+    val slug: String = "",
+    val label: String = "",
+    @SerialName("published_count") val publishedCount: Long = 0,
+)

app/src/main/java/com/runicgateway/app/data/appearance/SettingsJson.kt

@@ -0,0 +1,37 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.data.appearance
+
+import kotlinx.serialization.SerializationException
+import kotlinx.serialization.json.Json
+import kotlinx.serialization.json.JsonObject
+
+/**
+ * Parse a JSON-valued settings row, client side — the second stage of decoding
+ * `nav_public` (THEMING_AND_NAV.md §3).
+ *
+ * The Kotlin counterpart to the web client's `lib/settingsJson.js`, and
+ * deliberately the same three lines of judgement: `settings.value` is TEXT, so
+ * the row arrives as a **string inside** the already-decoded settings object,
+ * and a malformed or wrong-shaped one must read as **absent** — the surface
+ * falls back to the coded default — never as an error and never as a
+ * half-applied object.
+ */
+private val settingsJson = Json { ignoreUnknownKeys = true }
+
+/**
+ * @param raw the raw stored value, as it arrived in the settings payload
+ * @return the parsed object, or null when absent/malformed
+ */
+fun parseJsonSetting(raw: String?): JsonObject? {
+    if (raw.isNullOrEmpty()) return null
+    val parsed = try {
+        settingsJson.parseToJsonElement(raw)
+    } catch (_: SerializationException) {
+        return null
+    }
+    // Only plain objects. A stored `null`, `4`, `"x"` or array is as unusable to
+    // every consumer of these keys as a syntax error is.
+    return parsed as? JsonObject
+}

app/src/main/java/com/runicgateway/app/data/appearance/SiteAppearance.kt

@@ -0,0 +1,73 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.data.appearance
+
+import com.runicgateway.app.data.api.dto.BrandDto
+import com.runicgateway.app.data.api.dto.SettingsDto
+import kotlinx.serialization.json.JsonObject
+import kotlinx.serialization.json.JsonPrimitive
+
+/**
+ * Everything the app renders itself with that the shard's admin controls
+ * (THEMING_AND_NAV.md, M12): the brand block, the resolved theme tokens, and the
+ * public navigation overrides. One value, held once in [com.runicgateway.app.ui.AppViewModel],
+ * so the theme and the drawer can never disagree about which shard they are showing.
+ *
+ * **[NONE] is the shipped app.** An instance with no settings rows, a backend
+ * that predates the feature, and a settings call that failed outright are all the
+ * same state here, and all three must render exactly as the app did before this
+ * milestone existed (§2). That is why nothing on this class is nullable except
+ * [brand], which was already nullable and whose absence already meant "use the
+ * bundled strings".
+ */
+data class SiteAppearance(
+    /** The per-shard branding block; null when settings couldn't be loaded. */
+    val brand: BrandDto? = null,
+    /**
+     * The resolved CSS custom properties, keyed by token (`"--accent"` → `"#7f99bd"`).
+     * Empty means "the shipped defaults" — the server never emits an empty map,
+     * but absent and empty are the same thing to the app and it must not depend
+     * on that.
+     */
+    val theme: Map<String, String> = emptyMap(),
+    /**
+     * The parsed `nav_public` row, or null when the admin never edited the nav.
+     * Kept as the raw object here; reading `items` / `sections` / `links` out of
+     * it is the job of the phases that render them.
+     */
+    val navPublic: JsonObject? = null,
+) {
+    companion object {
+        /** The shipped app: no brand, no overrides. Also what a failed load means. */
+        val NONE = SiteAppearance()
+
+        /**
+         * Build the appearance from a `GET /public/settings` body. Forgiving
+         * field by field (§2): a bad `--accent` must not discard a good `--bg`
+         * beside it, and a malformed `nav_public` must not cost the theme.
+         */
+        fun from(settings: SettingsDto?): SiteAppearance {
+            if (settings == null) return NONE
+            return SiteAppearance(
+                brand = settings.brand,
+                theme = themeTokens(settings.theme as? JsonObject),
+                navPublic = parseJsonSetting(settings.navPublic),
+            )
+        }
+
+        // Every themable token is a string server-side (validated on write, and
+        // resolveThemeTokens only ever copies a validated value). Anything else
+        // is dropped rather than coerced, so an unexpected value costs exactly
+        // its own token and the rest of the palette still applies.
+        private fun themeTokens(raw: JsonObject?): Map<String, String> {
+            if (raw.isNullOrEmpty()) return emptyMap()
+            return buildMap {
+                for ((token, value) in raw) {
+                    val text = (value as? JsonPrimitive)?.takeIf { it.isString }?.content
+                    if (!text.isNullOrBlank()) put(token, text)
+                }
+            }
+        }
+    }
+}

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

@@ -0,0 +1,94 @@
+/*
+ * 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.AdminApi
+import com.runicgateway.app.data.api.dto.AdminDashboardDto
+import com.runicgateway.app.data.api.dto.AdminPostDto
+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.AdminWikiCategoryDto
+import com.runicgateway.app.data.api.dto.WikiCategoryRequest
+import com.runicgateway.app.data.api.dto.AdminWikiTagDto
+import retrofit2.HttpException
+import retrofit2.Response
+import javax.inject.Inject
+import javax.inject.Singleton
+
+/**
+ * The M10 staff-operations data source over `/api/v1/admin/…` (PLAN.md §1, §6.4).
+ * Every call returns a typed [ApiResult] so a screen renders a clean error/retry
+ * rather than crashing — a `403` (role lost since the menu rendered) and a `503`
+ * (shard/sidecar offline for the shard-write actions) are both expected outcomes
+ * the UI handles, never thrown. Role is authoritative on the server.
+ */
+@Singleton
+class AdminRepository @Inject constructor(
+    private val api: AdminApi,
+) {
+    suspend fun dashboard(): ApiResult<AdminDashboardDto> = safeApiCall { api.dashboard() }
+
+    suspend fun setSiteMode(mode: String): ApiResult<SiteModeStateDto> =
+        safeApiCall { api.setSiteMode(SiteModeRequest(mode)) }
+
+    // ── Content: news posts ───────────────────────────────────────────────
+    suspend fun posts(): ApiResult<List<AdminPostDto>> = safeApiCall { api.posts() }
+
+    suspend fun createPost(body: PostCreateRequest): ApiResult<AdminPostDto> =
+        safeApiCall { api.createPost(body) }
+
+    suspend fun setPostPublished(id: Long, published: Boolean): ApiResult<AdminPostDto> =
+        safeApiCall { api.publishPost(id, PublishRequest(published)) }
+
+    suspend fun deletePost(id: Long): ApiResult<Unit> = safeApiCall { api.deletePost(id).requireOk() }
+
+    // ── Content: wiki taxonomy ────────────────────────────────────────────
+    suspend fun wikiCategories(): ApiResult<List<AdminWikiCategoryDto>> = safeApiCall { api.wikiCategories() }
+
+    suspend fun createWikiCategory(body: WikiCategoryRequest): ApiResult<AdminWikiCategoryDto> =
+        safeApiCall { api.createWikiCategory(body) }
+
+    suspend fun deleteWikiCategory(id: Long): ApiResult<Unit> =
+        safeApiCall { api.deleteWikiCategory(id).requireOk() }
+
+    suspend fun wikiTags(): ApiResult<List<AdminWikiTagDto>> = safeApiCall { api.wikiTags() }
+
+    // ── Moderation: shard write plane ─────────────────────────────────────
+    suspend fun kick(account: String?, serial: String?): ApiResult<Unit> =
+        safeApiCall { api.kick(KickRequest(account, serial)).requireOk() }
+
+    suspend fun ban(account: String?, serial: String?, durationSec: Long?, reason: String?): ApiResult<Unit> =
+        safeApiCall { api.ban(BanRequest(account, serial, durationSec, reason)).requireOk() }
+
+    suspend fun unban(account: String): ApiResult<Unit> =
+        safeApiCall { api.unban(UnbanRequest(account)).requireOk() }
+
+    suspend fun broadcast(text: String, hue: Int?): ApiResult<Unit> =
+        safeApiCall { api.broadcast(BroadcastRequest(text, hue)).requireOk() }
+
+    // ── Support queue: help pages ─────────────────────────────────────────
+    suspend fun supportPages(): ApiResult<List<SupportPageDto>> = safeApiCall { api.supportPages() }
+
+    suspend fun respondPage(id: String, message: String, close: Boolean): ApiResult<Unit> =
+        safeApiCall { api.respondPage(id, PageRespondRequest(message, close)).requireOk() }
+
+    suspend fun closePage(id: String): ApiResult<Unit> =
+        safeApiCall { api.closePage(id).requireOk() }
+
+    /** Turn a bodyless [Response] into a thrown [HttpException] on a non-2xx, so
+     *  [safeApiCall] can fold it into an [ApiResult.HttpError] like every other call. */
+    private fun Response<Unit>.requireOk() {
+        if (!isSuccessful) throw HttpException(this)
+    }
+}

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

@@ -0,0 +1,227 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+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
+import com.runicgateway.app.data.api.dto.MobileLoginRequest
+import com.runicgateway.app.data.api.dto.MobileLogoutRequest
+import com.runicgateway.app.data.api.dto.MobileTokenResponse
+import com.runicgateway.app.data.api.dto.SsoProviderDto
+import com.runicgateway.app.data.api.dto.TotpRequiredError
+import com.runicgateway.app.data.api.dto.TrustedDeviceDto
+import kotlinx.coroutines.CancellationException
+import kotlinx.coroutines.delay
+import kotlinx.serialization.json.Json
+import retrofit2.Response
+import java.io.IOException
+import javax.inject.Inject
+import javax.inject.Singleton
+
+/**
+ * Native username/password (+TOTP) auth — the app's only native credential flow
+ * (PLAN.md §4.1). It drives the [SessionManager]: a successful login establishes
+ * the session; logout revokes it. Registration/invite/reset/SSO are website
+ * hand-offs (§4.2), not here.
+ */
+@Singleton
+class AuthRepository @Inject constructor(
+    private val authApi: AuthApi,
+    private val ssoApi: SsoApi,
+    private val sessionManager: SessionManager,
+    private val pushManager: PushManager,
+    private val trustTokenStore: TrustTokenStore,
+    private val deviceNameProvider: DeviceNameProvider,
+    private val json: Json,
+) {
+
+    /** The three outcomes of SSO provider discovery, so the login screen can tell a
+     *  shard that offers no SSO ([None]) apart from a discovery that failed
+     *  ([Unavailable], offer a retry) — the old "empty on any failure" conflation hid
+     *  a broken call behind a dead website hand-off (§4.2). */
+    sealed interface SsoDiscovery {
+        /** At least one enabled provider — render a native button per entry. */
+        data class Available(val providers: List<SsoProviderDto>) : SsoDiscovery
+
+        /** Discovery succeeded but the shard has no SSO providers configured. */
+        data object None : SsoDiscovery
+
+        /** The discovery call failed (offline / server error) — surface a retry. */
+        data object Unavailable : SsoDiscovery
+    }
+
+    /**
+     * Discover the shard's enabled SSO providers for the native login buttons (§4.2).
+     * Public discovery, never secrets. Retries once before reporting [Unavailable],
+     * so a single transient blip doesn't strand the user.
+     */
+    suspend fun ssoProviders(): SsoDiscovery {
+        var lastFailed = false
+        repeat(2) { attempt ->
+            try {
+                val providers = ssoApi.providers()
+                return if (providers.isEmpty()) SsoDiscovery.None else SsoDiscovery.Available(providers)
+            } catch (e: CancellationException) {
+                throw e
+            } catch (_: Exception) {
+                lastFailed = true
+                if (attempt == 0) delay(DISCOVERY_RETRY_DELAY_MS)
+            }
+        }
+        return if (lastFailed) SsoDiscovery.Unavailable else SsoDiscovery.None
+    }
+
+    /** Outcome of a login attempt (§4.1). */
+    sealed interface 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
+        data object InvalidCredentials : LoginResult
+
+        /** Guarded by per-IP backoff → slowdown → hard cap; back off and retry. */
+        data object RateLimited : LoginResult
+
+        /** Any other server failure (5xx / unexpected). */
+        data object ServerError : LoginResult
+
+        /** No answer — offline, DNS, TLS, timeout. */
+        data object NetworkError : 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,
+                    recoveryCode = recoveryCode,
+                    trustDevice = trustDevice.takeIf { it },
+                    device_name = if (trustDevice) deviceNameProvider.deviceName() else null,
+                ),
+                trustToken = storedTrustToken,
+            )
+        } catch (e: CancellationException) {
+            throw e
+        } catch (_: IOException) {
+            return LoginResult.NetworkError
+        }
+
+        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(
+                trustLimitReached = body.trustLimitReached,
+                devices = body.devices,
+            )
+        }
+
+        return when (response.code()) {
+            401 -> if (isTotpRequired(response)) LoginResult.TotpRequired else LoginResult.InvalidCredentials
+            429 -> LoginResult.RateLimited
+            else -> LoginResult.ServerError
+        }
+    }
+
+    /**
+     * 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
+     * network call fails, so the user is always signed out locally.
+     */
+    suspend fun logout(allDevices: Boolean = false) {
+        // Deregister this device's push endpoint while the bearer is still valid, so
+        // no orphan device row is left behind (§11). Keeps the opt-in intent so push
+        // resumes on the next sign-in; best-effort, never blocks the logout.
+        try {
+            pushManager.deregisterDevice()
+        } catch (e: CancellationException) {
+            throw e
+        } catch (_: Exception) {
+            // Ignore — local session teardown proceeds regardless.
+        }
+        val refreshToken = sessionManager.currentRefreshToken()
+        try {
+            authApi.logout(MobileLogoutRequest(refreshToken = refreshToken, all = allDevices))
+        } catch (e: CancellationException) {
+            throw e
+        } catch (_: Exception) {
+            // Ignore — we still drop the local session below.
+        }
+        sessionManager.onSignedOut()
+    }
+
+    /**
+     * Re-validate the session against `GET /auth/me` on app resume (§4.3). A
+     * success refreshes the cached role (roles change server-side); a `401` that
+     * survives the silent refresh means the session is dead → sign out. Transient
+     * failures are ignored so a flaky network doesn't bounce the user.
+     */
+    suspend fun revalidate() {
+        if (!sessionManager.isSignedIn) return
+        try {
+            val me = authApi.me()
+            sessionManager.onUserRefreshed(me.user)
+        } catch (e: CancellationException) {
+            throw e
+        } catch (e: retrofit2.HttpException) {
+            if (e.code() == 401) sessionManager.onSignedOut()
+        } catch (_: IOException) {
+            // Offline — keep the session; the next authed call will re-check.
+        }
+    }
+
+    private fun isTotpRequired(response: Response<*>): Boolean = try {
+        val raw = response.errorBody()?.string()
+        !raw.isNullOrBlank() && json.decodeFromString<TotpRequiredError>(raw).totpRequired
+    } catch (_: Exception) {
+        false
+    }
+
+    private companion object {
+        const val DISCOVERY_RETRY_DELAY_MS = 400L
+    }
+}

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

@@ -0,0 +1,157 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+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
+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.StatusDto
+import okhttp3.HttpUrl.Companion.toHttpUrlOrNull
+import javax.inject.Inject
+import javax.inject.Singleton
+
+/**
+ * Owns the shard website base-URL lifecycle (PLAN.md §3): restoring a saved URL
+ * on launch, validating + persisting a candidate on the first-run connect
+ * screen, and the hard reset performed by a Settings → Server switch.
+ */
+@Singleton
+class ConnectionRepository @Inject constructor(
+    private val api: PublicApi,
+    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,
+) {
+
+    /** Outcome of validating a candidate base URL against a live site. */
+    sealed interface ProbeResult {
+        data class Success(val status: StatusDto) : ProbeResult
+        data class InvalidUrl(val reason: ServerUrl.Reason) : ProbeResult
+
+        /** Reachable and 2xx, but not a Runic Gateway backend (wrong version identity). */
+        data object NotRunicGateway : ProbeResult
+
+        /**
+         * A Runic Gateway backend, but speaking an API version this app build does
+         * not support (§3 version guard) — refuse rather than mis-render. [serverApi]
+         * is what the site reported; [supportedApi] is what this app speaks.
+         */
+        data class VersionMismatch(val serverApi: String, val supportedApi: String) : ProbeResult
+        data class ServerError(val status: Int) : ProbeResult
+        data class Unreachable(val cause: Throwable) : ProbeResult
+    }
+
+    /** True once a saved base URL has been loaded into the holder. */
+    val isConnected: Boolean get() = baseUrlHolder.current != null
+
+    /**
+     * Restore any saved base URL into the holder on launch. Returns true if the
+     * app already has a configured shard site (skip the connect screen).
+     */
+    suspend fun restore(): Boolean {
+        val saved = prefs.currentBaseUrl()?.toHttpUrlOrNull()
+        baseUrlHolder.set(saved)
+        return saved != null
+    }
+
+    /**
+     * Validate [rawUrl], and on success persist it and activate it for all
+     * subsequent API calls. Insecure HTTP is allowed only in debug builds
+     * (local dev against 127.0.0.1); release builds require HTTPS.
+     */
+    suspend fun probeAndConnect(rawUrl: String): ProbeResult {
+        val normalized = when (val r = ServerUrl.normalize(rawUrl, allowInsecureHttp = config.allowInsecureHttp)) {
+            is ServerUrl.Result.Invalid -> return ProbeResult.InvalidUrl(r.reason)
+            is ServerUrl.Result.Valid -> r.url
+        }
+
+        val statusUrl = normalized.resolve("api/v1/public/status")?.toString()
+            ?: return ProbeResult.InvalidUrl(ServerUrl.Reason.MALFORMED)
+
+        return when (val result = safeApiCall { api.probeStatus(statusUrl) }) {
+            is ApiResult.Ok -> when (val verdict = evaluateVersion(result.data.version)) {
+                is VersionVerdict.Ok -> {
+                    prefs.setBaseUrl(normalized.toString())
+                    baseUrlHolder.set(normalized)
+                    ProbeResult.Success(result.data)
+                }
+                is VersionVerdict.NotRunicGateway -> ProbeResult.NotRunicGateway
+                is VersionVerdict.Mismatch ->
+                    ProbeResult.VersionMismatch(serverApi = verdict.serverApi, supportedApi = SUPPORTED_API)
+            }
+            is ApiResult.HttpError -> ProbeResult.ServerError(result.status)
+            is ApiResult.NetworkError -> ProbeResult.Unreachable(result.cause)
+        }
+    }
+
+    /**
+     * Hard reset for a Settings → Server switch (§3): sign out (clear stored
+     * tokens), clear the saved URL, and deactivate it — the app returns to a
+     * signed-out state against the new host.
+     */
+    suspend fun disconnect() {
+        // Deregister the push endpoint on the current (old) host while still authed,
+        // then clear the shard's ntfy URL — the new host advertises its own (§11).
+        try {
+            pushManager.deregisterDevice()
+        } catch (_: Exception) {
+            // Best-effort; the reset proceeds regardless.
+        }
+        pushManager.setNtfyUrl(null)
+        sessionManager.onSignedOut()
+        // 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)
+    }
+
+    /** The pure outcome of inspecting a probed site's [VersionDto] (§3 version guard). */
+    internal sealed interface VersionVerdict {
+        data object Ok : VersionVerdict
+        data object NotRunicGateway : VersionVerdict
+        data class Mismatch(val serverApi: String) : VersionVerdict
+    }
+
+    internal companion object {
+        const val RUNIC_SERVICE_ID = "runic-gateway"
+
+        /** The backend API major version this app build speaks (matches `/public/version` `api`). */
+        const val SUPPORTED_API = "v1"
+
+        /**
+         * Decide whether a probed site is a Runic Gateway backend this app can talk
+         * to. Pure (no I/O) so it is unit-testable without a live site. Lenient on a
+         * blank `api` (an older backend that predates version surfacing); refuses only
+         * an API version we positively know we can't parse (e.g. a future `v2`).
+         */
+        fun evaluateVersion(
+            version: com.runicgateway.app.data.api.dto.VersionDto,
+            supportedApi: String = SUPPORTED_API,
+        ): VersionVerdict {
+            if (!version.service.trim().equals(RUNIC_SERVICE_ID, ignoreCase = true)) {
+                return VersionVerdict.NotRunicGateway
+            }
+            val serverApi = version.api.trim()
+            return when {
+                serverApi.isEmpty() -> VersionVerdict.Ok
+                serverApi.equals(supportedApi, ignoreCase = true) -> VersionVerdict.Ok
+                else -> VersionVerdict.Mismatch(serverApi)
+            }
+        }
+    }
+}

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

@@ -0,0 +1,24 @@
+/*
+ * 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 com.runicgateway.app.data.api.dto.ContactRequest
+import com.runicgateway.app.data.api.dto.ContactResponse
+import javax.inject.Inject
+import javax.inject.Singleton
+
+/**
+ * Contact form submission (PLAN.md §6.1). The endpoint is rate-limited; the
+ * caller handles `429` (too many) and `502` (mailer down) via [ApiResult.HttpError].
+ */
+@Singleton
+class ContactRepository @Inject constructor(
+    private val api: PublicApi,
+) {
+    suspend fun send(name: String, email: String, message: String): ApiResult<ContactResponse> =
+        safeApiCall { api.postContact(ContactRequest(name = name, email = email, message = message)) }
+}

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

@@ -0,0 +1,43 @@
+/*
+ * 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 com.runicgateway.app.data.api.dto.PageDto
+import com.runicgateway.app.data.api.dto.PostDto
+import javax.inject.Inject
+import javax.inject.Singleton
+
+/**
+ * News posts and CMS pages (PLAN.md §6.1). URL post categories map 1:1 to the
+ * backend's route segments (`news | five-on-friday | newsletter | screenshots`).
+ */
+@Singleton
+class ContentRepository @Inject constructor(
+    private val api: PublicApi,
+) {
+    /** Known URL categories, in display order. */
+    enum class PostCategory(val urlSlug: String) {
+        NEWS("news"),
+        FIVE_ON_FRIDAY("five-on-friday"),
+        NEWSLETTER("newsletter"),
+        SCREENSHOTS("screenshots"),
+        ;
+
+        companion object {
+            fun fromUrlSlug(slug: String?): PostCategory? = entries.firstOrNull { it.urlSlug == slug }
+        }
+    }
+
+    suspend fun getPosts(category: PostCategory): ApiResult<List<PostDto>> =
+        safeApiCall { api.getPosts(category.urlSlug) }
+
+    suspend fun getPost(category: PostCategory, idOrSlug: String): ApiResult<PostDto> =
+        safeApiCall { api.getPost(category.urlSlug, idOrSlug) }
+
+    suspend fun getPage(slug: String): ApiResult<PageDto> =
+        safeApiCall { api.getPage(slug) }
+}

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

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

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

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

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

@@ -0,0 +1,22 @@
+/*
+ * 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 com.runicgateway.app.data.api.dto.SettingsDto
+import com.runicgateway.app.data.api.dto.StatusDto
+import javax.inject.Inject
+import javax.inject.Singleton
+
+/** Site status (mode/maintenance) and settings/branding (PLAN.md §6.1). */
+@Singleton
+class SettingsRepository @Inject constructor(
+    private val api: PublicApi,
+) {
+    suspend fun getStatus(): ApiResult<StatusDto> = safeApiCall { api.getStatus() }
+
+    suspend fun getSettings(): ApiResult<SettingsDto> = safeApiCall { api.getSettings() }
+}

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

@@ -0,0 +1,159 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.data.repository
+
+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
+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
+import kotlinx.serialization.json.Json
+import kotlinx.serialization.json.JsonObject
+import javax.inject.Inject
+import javax.inject.Singleton
+
+/**
+ * The public shard widgets (PLAN.md §6.2): point-in-time board snapshots over
+ * the `/public/shard/…` GETs plus the live SSE stream. Every read returns a typed
+ * [ApiResult] so a down shard renders as offline (§7); [liveEvents] is the shared
+ * SSE feed the boards merge in place. Live `*.update` frames decode into the same
+ * DTOs as the snapshot reads via the `*Frame` decoders.
+ */
+@Singleton
+class ShardRepository @Inject constructor(
+    private val api: PublicApi,
+    private val stream: ShardStream,
+    private val json: Json,
+) {
+    // ── Snapshots ────────────────────────────────────────────────────────
+    suspend fun status(): ApiResult<ShardStatusDto> = safeApiCall { api.getShardStatus() }
+
+    suspend fun feed(limit: Int = 40): ApiResult<List<FeedEventDto>> =
+        safeApiCall { api.getShardFeed(limit = limit) }
+
+    suspend fun economy(limit: Int = 100): ApiResult<List<EconomySampleDto>> =
+        safeApiCall { api.getShardEconomy(limit) }
+
+    suspend fun online(): ApiResult<List<OnlineStaffDto>> = safeApiCall { api.getShardOnline() }
+
+    suspend fun presence(): ApiResult<PresenceDto> = safeApiCall { api.getShardPresence() }
+
+    suspend fun champs(): ApiResult<List<ChampDto>> = safeApiCall { api.getShardChamps() }
+
+    suspend fun guilds(): ApiResult<List<GuildDto>> = safeApiCall { api.getShardGuilds() }
+
+    suspend fun governors(): ApiResult<List<GovernorDto>> = safeApiCall { api.getShardGovernors() }
+
+    suspend fun governorHistory(city: String, limit: Int = 25): ApiResult<List<GovernorTermDto>> =
+        safeApiCall { api.getShardGovernorHistory(city, limit) }
+
+    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()
+
+    // Decode a live `*.update` frame into the board DTO it mirrors; null on shape
+    // mismatch so a malformed frame is skipped rather than crashing the board.
+    fun champFrame(obj: JsonObject): ChampDto? = decode(obj, ChampDto.serializer())
+    fun guildFrame(obj: JsonObject): GuildDto? = decode(obj, GuildDto.serializer())
+    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/data/repository/WikiRepository.kt

@@ -0,0 +1,37 @@
+/*
+ * 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 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
+import javax.inject.Inject
+import javax.inject.Singleton
+
+/** Wiki listing/filtering, categories, tags, and detail (PLAN.md §6.1). */
+@Singleton
+class WikiRepository @Inject constructor(
+    private val api: PublicApi,
+) {
+    /** Full-text [query] takes precedence over [category]/[tag] on the backend. */
+    suspend fun getPages(
+        query: String? = null,
+        category: String? = null,
+        tag: String? = null,
+    ): ApiResult<List<WikiSummaryDto>> =
+        safeApiCall { api.getWikiPages(query?.takeIf { it.isNotBlank() }, category, tag) }
+
+    suspend fun getCategories(): ApiResult<List<WikiCategoryDto>> =
+        safeApiCall { api.getWikiCategories() }
+
+    suspend fun getTags(): ApiResult<List<WikiTagDto>> =
+        safeApiCall { api.getWikiTags() }
+
+    suspend fun getPage(slug: String): ApiResult<WikiPageDto> =
+        safeApiCall { api.getWikiPage(slug) }
+}

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

@@ -0,0 +1,24 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.di
+
+import com.runicgateway.app.BuildConfig
+import com.runicgateway.app.core.AppConfig
+import dagger.Module
+import dagger.Provides
+import dagger.hilt.InstallIn
+import dagger.hilt.components.SingletonComponent
+import javax.inject.Singleton
+
+@Module
+@InstallIn(SingletonComponent::class)
+object AppModule {
+
+    @Provides
+    @Singleton
+    fun provideAppConfig(): AppConfig = AppConfig(
+        allowInsecureHttp = BuildConfig.DEBUG,
+        versionName = BuildConfig.VERSION_NAME,
+    )
+}

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

@@ -0,0 +1,160 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.di
+
+import android.os.Build
+import com.jakewharton.retrofit2.converter.kotlinx.serialization.asConverterFactory
+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
+import com.runicgateway.app.data.api.AuthRefreshApi
+import com.runicgateway.app.data.api.MeApi
+import com.runicgateway.app.data.api.AdminApi
+import com.runicgateway.app.data.api.NotificationsApi
+import com.runicgateway.app.data.api.PlayerShardApi
+import com.runicgateway.app.data.api.PublicApi
+import com.runicgateway.app.data.api.SsoApi
+import dagger.Module
+import dagger.Provides
+import dagger.hilt.InstallIn
+import dagger.hilt.components.SingletonComponent
+import kotlinx.serialization.json.Json
+import okhttp3.MediaType.Companion.toMediaType
+import okhttp3.OkHttpClient
+import okhttp3.logging.HttpLoggingInterceptor
+import retrofit2.Retrofit
+import javax.inject.Singleton
+
+@Module
+@InstallIn(SingletonComponent::class)
+object NetworkModule {
+
+    @Provides
+    @Singleton
+    fun provideJson(): Json = Json {
+        // Additive backend fields (§8) must never break decoding; be lenient.
+        ignoreUnknownKeys = true
+        explicitNulls = false
+        coerceInputValues = true
+    }
+
+    @Provides
+    @Singleton
+    fun provideUserAgentInterceptor(): UserAgentInterceptor {
+        // Identifiable UA so the site's scanner guard (§8) doesn't reject the app.
+        val ua = "RunicGatewayApp/${BuildConfig.VERSION_NAME} (Android ${Build.VERSION.RELEASE})"
+        return UserAgentInterceptor(ua)
+    }
+
+    /**
+     * The main client every API and the SSE stream ride on. Order: identify (UA),
+     * retarget onto the configured shard host, then attach the bearer; the
+     * [TokenAuthenticator] handles silent refresh-on-401 (§4.1). Logging sits last
+     * so it observes the final, authed request.
+     */
+    @Provides
+    @Singleton
+    fun provideOkHttpClient(
+        hostSelectionInterceptor: HostSelectionInterceptor,
+        userAgentInterceptor: UserAgentInterceptor,
+        authInterceptor: AuthInterceptor,
+        tokenAuthenticator: TokenAuthenticator,
+    ): OkHttpClient {
+        val builder = OkHttpClient.Builder()
+            .addInterceptor(userAgentInterceptor)
+            .addInterceptor(hostSelectionInterceptor)
+            .addInterceptor(authInterceptor)
+            .authenticator(tokenAuthenticator)
+
+        if (BuildConfig.DEBUG) {
+            builder.addInterceptor(
+                HttpLoggingInterceptor().apply { level = HttpLoggingInterceptor.Level.BASIC },
+            )
+        }
+        return builder.build()
+    }
+
+    @Provides
+    @Singleton
+    fun provideRetrofit(client: OkHttpClient, json: Json): Retrofit =
+        Retrofit.Builder()
+            // Compile-time sentinel; every relative call is rewritten onto the
+            // runtime-selected shard site by HostSelectionInterceptor (§3).
+            .baseUrl(BaseUrlHolder.PLACEHOLDER_BASE_URL)
+            .client(client)
+            .addConverterFactory(json.asConverterFactory("application/json".toMediaType()))
+            .build()
+
+    @Provides
+    @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)
+
+    /** Native SSO discovery + code exchange (§4.2, M9) — on the main client. */
+    @Provides
+    @Singleton
+    fun provideSsoApi(retrofit: Retrofit): SsoApi = retrofit.create(SsoApi::class.java)
+
+    /** Role-agnostic self-service (§6.4) — bearer-authed on the main client. */
+    @Provides
+    @Singleton
+    fun provideMeApi(retrofit: Retrofit): MeApi = retrofit.create(MeApi::class.java)
+
+    /** A player's own game data + linking (§6.3) — bearer-authed on the main client. */
+    @Provides
+    @Singleton
+    fun providePlayerShardApi(retrofit: Retrofit): PlayerShardApi =
+        retrofit.create(PlayerShardApi::class.java)
+
+    /** Opt-in push devices + subscriptions (§11, M7) — bearer-authed on the main client. */
+    @Provides
+    @Singleton
+    fun provideNotificationsApi(retrofit: Retrofit): NotificationsApi =
+        retrofit.create(NotificationsApi::class.java)
+
+    /** Staff operations (§1, §6.4, M10) — bearer-authed; the server re-checks role every call. */
+    @Provides
+    @Singleton
+    fun provideAdminApi(retrofit: Retrofit): AdminApi = retrofit.create(AdminApi::class.java)
+
+    /**
+     * Token refresh runs on its own **bare** client — UA + host retargeting only,
+     * no auth interceptor and no authenticator — so a refresh can never recurse
+     * back through [TokenAuthenticator] (§4.3). This throwaway client/Retrofit is
+     * not exposed as a bean, so there is no ambiguous [OkHttpClient] binding.
+     */
+    @Provides
+    @Singleton
+    fun provideAuthRefreshApi(
+        hostSelectionInterceptor: HostSelectionInterceptor,
+        userAgentInterceptor: UserAgentInterceptor,
+        json: Json,
+    ): AuthRefreshApi {
+        val bareClient = OkHttpClient.Builder()
+            .addInterceptor(userAgentInterceptor)
+            .addInterceptor(hostSelectionInterceptor)
+            .build()
+        val retrofit = Retrofit.Builder()
+            .baseUrl(BaseUrlHolder.PLACEHOLDER_BASE_URL)
+            .client(bareClient)
+            .addConverterFactory(json.asConverterFactory("application/json".toMediaType()))
+            .build()
+        return retrofit.create(AuthRefreshApi::class.java)
+    }
+}

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

@@ -0,0 +1,41 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+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
+import dagger.Module
+import dagger.hilt.InstallIn
+import dagger.hilt.components.SingletonComponent
+import javax.inject.Singleton
+
+/** Binds the at-rest stores to their EncryptedSharedPreferences impls (§4.3). */
+@Module
+@InstallIn(SingletonComponent::class)
+abstract class StorageModule {
+
+    @Binds
+    @Singleton
+    abstract fun bindTokenStore(impl: EncryptedTokenStore): TokenStore
+
+    @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/AppViewModel.kt

@@ -0,0 +1,119 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.ui
+
+import androidx.lifecycle.ViewModel
+import androidx.lifecycle.viewModelScope
+import com.runicgateway.app.core.net.BaseUrlHolder
+import com.runicgateway.app.core.push.PushManager
+import com.runicgateway.app.core.result.ApiResult
+import com.runicgateway.app.data.appearance.SiteAppearance
+import com.runicgateway.app.data.repository.ConnectionRepository
+import com.runicgateway.app.data.repository.SettingsRepository
+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
+
+/**
+ * Top-level app gate (PLAN.md §3): decides whether the first-run connect screen
+ * or the main UI shows, and holds the per-shard [SiteAppearance] the theme and
+ * the drawer are built from. Activity-scoped so the whole app observes one state.
+ */
+@HiltViewModel
+class AppViewModel @Inject constructor(
+    private val connectionRepository: ConnectionRepository,
+    private val settingsRepository: SettingsRepository,
+    private val baseUrlHolder: BaseUrlHolder,
+    private val pushManager: PushManager,
+) : ViewModel() {
+
+    sealed interface AppState {
+        /** Restoring the saved base URL / loading branding. */
+        data object Loading : AppState
+
+        /** No shard site configured yet — show the connect screen. */
+        data object NeedsConnection : AppState
+
+        /**
+         * A site is configured. [appearance] is [SiteAppearance.NONE] when settings
+         * couldn't be loaded — the shipped app, still fully usable (§2).
+         */
+        data class Ready(val appearance: SiteAppearance) : AppState
+    }
+
+    private val _state = MutableStateFlow<AppState>(AppState.Loading)
+    val state: StateFlow<AppState> = _state.asStateFlow()
+
+    init {
+        viewModelScope.launch {
+            _state.value = if (connectionRepository.restore()) {
+                AppState.Ready(loadAppearance())
+            } else {
+                AppState.NeedsConnection
+            }
+        }
+    }
+
+    /** Called by the connect screen once a site has been validated + saved. */
+    fun onConnected() {
+        viewModelScope.launch { _state.value = AppState.Ready(loadAppearance()) }
+    }
+
+    /**
+     * Re-read the appearance while the app is already running — on resume, beside
+     * the session's own re-validation (§5.5). An admin who re-skins the site from
+     * a laptop and picks the phone up should see it.
+     *
+     * Best-effort, and silent either way: a failed refresh **keeps the last good
+     * appearance** rather than dropping back to the shipped one, so a moment of
+     * no connectivity does not repaint a themed shard. There is no loading state
+     * and no error surface. Ignored unless a site is configured.
+     */
+    fun refreshAppearance() {
+        if (_state.value !is AppState.Ready) return
+        viewModelScope.launch {
+            val settings = (settingsRepository.getSettings() as? ApiResult.Ok)?.data ?: return@launch
+            pushManager.setNtfyUrl(settings.push.ntfyUrl)
+            // changeServer() may have raced us back to the connect screen while the
+            // call was in flight; don't resurrect Ready on top of it.
+            if (_state.value is AppState.Ready) {
+                _state.value = AppState.Ready(SiteAppearance.from(settings))
+            }
+        }
+    }
+
+    /** Settings → Server switch: hard reset back to the connect screen (§3). */
+    fun changeServer() {
+        viewModelScope.launch {
+            connectionRepository.disconnect()
+            _state.value = AppState.NeedsConnection
+        }
+    }
+
+    /**
+     * Load public settings for the appearance and feed the shard's push relay URL into
+     * the [PushManager] (§11) — its arrival is what lets push re-register after a restart
+     * or sign-in. Returns [SiteAppearance.NONE] if settings couldn't be loaded.
+     */
+    private suspend fun loadAppearance(): SiteAppearance {
+        val settings = (settingsRepository.getSettings() as? ApiResult.Ok)?.data
+        pushManager.setNtfyUrl(settings?.push?.ntfyUrl)
+        return SiteAppearance.from(settings)
+    }
+
+    /**
+     * Resolve a possibly site-relative asset path (branding logos, post images)
+     * to an absolute URL against the configured base (§8: asset fields may be
+     * site-relative). Absolute URLs pass through unchanged; null/blank stays null.
+     */
+    fun resolveAsset(path: String?): String? {
+        if (path.isNullOrBlank()) return null
+        val base = baseUrlHolder.current ?: return path
+        return base.resolve(path)?.toString() ?: path
+    }
+}
+

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

@@ -0,0 +1,18 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.ui
+
+import androidx.compose.runtime.staticCompositionLocalOf
+
+/**
+ * Resolves possibly site-relative asset paths (post images, branding) to
+ * absolute URLs against the configured base URL. Provided at the app root from
+ * [AppViewModel.resolveAsset] so any screen or CMS block can turn a stored path
+ * into a loadable URL without reaching into the network layer.
+ */
+val LocalAssetResolver = staticCompositionLocalOf<(String?) -> String?> {
+    // Default: identity. Overridden at the app root; this fallback keeps previews
+    // and tests from crashing if the provider is missing.
+    { it }
+}

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

@@ -0,0 +1,634 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.ui
+
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.Spacer
+import androidx.compose.foundation.layout.height
+import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.layout.size
+import androidx.compose.foundation.rememberScrollState
+import androidx.compose.foundation.verticalScroll
+import androidx.compose.material.icons.Icons
+import androidx.compose.material.icons.automirrored.filled.ArrowBack
+import androidx.compose.material.icons.automirrored.filled.ExitToApp
+import androidx.compose.material.icons.filled.Menu
+import androidx.compose.material3.DrawerValue
+import androidx.compose.material3.ExperimentalMaterial3Api
+import androidx.compose.material3.HorizontalDivider
+import androidx.compose.material3.Icon
+import androidx.compose.material3.IconButton
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.ModalDrawerSheet
+import androidx.compose.material3.ModalNavigationDrawer
+import androidx.compose.material3.NavigationDrawerItem
+import androidx.compose.material3.NavigationDrawerItemColors
+import androidx.compose.material3.NavigationDrawerItemDefaults
+import androidx.compose.material3.Scaffold
+import androidx.compose.material3.Text
+import androidx.compose.material3.TopAppBar
+import androidx.compose.material3.TopAppBarDefaults
+import androidx.compose.material3.rememberDrawerState
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.LaunchedEffect
+import androidx.compose.runtime.getValue
+import androidx.compose.runtime.rememberCoroutineScope
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.platform.LocalContext
+import androidx.compose.ui.res.stringResource
+import androidx.compose.ui.text.style.TextOverflow
+import androidx.compose.ui.unit.dp
+import androidx.compose.ui.unit.sp
+import androidx.hilt.navigation.compose.hiltViewModel
+import androidx.lifecycle.compose.LifecycleResumeEffect
+import androidx.lifecycle.compose.collectAsStateWithLifecycle
+import androidx.navigation.NavHostController
+import androidx.navigation.NavType
+import androidx.navigation.compose.NavHost
+import androidx.navigation.compose.composable
+import androidx.navigation.compose.currentBackStackEntryAsState
+import androidx.navigation.compose.rememberNavController
+import androidx.navigation.navArgument
+import com.runicgateway.app.R
+import com.runicgateway.app.core.auth.Session
+import com.runicgateway.app.core.web.WebHandoff
+import com.runicgateway.app.data.api.dto.BrandDto
+import com.runicgateway.app.data.appearance.SiteAppearance
+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.components.BrandLogo
+import com.runicgateway.app.ui.contact.ContactScreen
+import com.runicgateway.app.ui.home.HomeScreen
+import com.runicgateway.app.ui.navigation.APP_MENU
+import com.runicgateway.app.ui.navigation.NavNode
+import com.runicgateway.app.ui.navigation.Routes
+import com.runicgateway.app.ui.navigation.buildNavTree
+import com.runicgateway.app.ui.navigation.isEntryVisible
+import com.runicgateway.app.ui.navigation.pruneNav
+import com.runicgateway.app.ui.news.NewsScreen
+import com.runicgateway.app.ui.news.PostScreen
+import com.runicgateway.app.ui.admin.AdminContentScreen
+import com.runicgateway.app.ui.admin.AdminDashboardScreen
+import com.runicgateway.app.ui.admin.AdminModerationScreen
+import com.runicgateway.app.ui.admin.AdminSupportScreen
+import com.runicgateway.app.ui.notifications.NotificationsScreen
+import com.runicgateway.app.ui.page.PageScreen
+import com.runicgateway.app.ui.player.CharacterSheetScreen
+import com.runicgateway.app.ui.player.CharactersScreen
+import com.runicgateway.app.ui.player.MyHousesScreen
+import com.runicgateway.app.ui.player.VendorsScreen
+import com.runicgateway.app.ui.session.SessionViewModel
+import com.runicgateway.app.ui.shard.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.theme.LocalShardStructure
+import com.runicgateway.app.ui.wiki.WikiPageScreen
+import com.runicgateway.app.ui.wiki.WikiScreen
+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,
+)
+
+/**
+ * The main app shell once a shard site is configured (PLAN.md §5): one shared,
+ * declarative, access-level navigation drawer whose entries are filtered by the
+ * current session, plus the Sign in / Sign out toggle and the Settings → Server
+ * switch. The signed-in role is re-validated against the backend on every resume
+ * (§4.3), so a server-side demotion drops menu access promptly.
+ */
+@OptIn(ExperimentalMaterial3Api::class)
+@Composable
+fun RunicApp(
+    appearance: SiteAppearance,
+    onChangeServer: () -> Unit,
+    modifier: Modifier = Modifier,
+    deepLinkStream: String? = null,
+    onDeepLinkConsumed: () -> Unit = {},
+    sessionViewModel: SessionViewModel = hiltViewModel(),
+) {
+    val brand = appearance.brand
+    val navController = rememberNavController()
+    val drawerState = rememberDrawerState(DrawerValue.Closed)
+    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) {
+        sessionViewModel.revalidate()
+        onPauseOrDispose { }
+    }
+
+    // A tapped push notification deep-links to its stream's screen (§11, item 7).
+    LaunchedEffect(deepLinkStream) {
+        val stream = deepLinkStream ?: return@LaunchedEffect
+        navController.navigate(Routes.forStream(stream)) {
+            popUpTo(Routes.HOME) { saveState = true }
+            launchSingleTop = true
+        }
+        onDeepLinkConsumed()
+    }
+
+    val backStackEntry by navController.currentBackStackEntryAsState()
+    // A destination's route is its NavHost *pattern*, so News reports
+    // "news?category={category}" (§6.2). Compare on the part before the query.
+    val currentRoute = backStackEntry?.destination?.route?.substringBefore('?')
+    val isTopLevel = currentRoute in TOP_LEVEL_ROUTES
+    // The admin's nav overrides, then the gates — never the other way round. An
+    // override is presentation only: it may relabel, reorder, group and hide, so
+    // `pruneNav` still decides what this caller may see and remains the boundary
+    // (§6.1, AC-3). With no stored row the merge returns APP_MENU itself.
+    val nav = pruneNav(buildNavTree(APP_MENU, appearance.navPublic)) {
+        isEntryVisible(it, session, shardFeatures)
+    }
+
+    val context = LocalContext.current
+    // An added link's path is site-relative; a hand-off needs it absolute against
+    // the configured base URL, which is exactly what the asset resolver does (§6.3).
+    val resolveUrl = LocalAssetResolver.current
+    val openNode: (NavNode) -> Unit = { node ->
+        scope.launch { drawerState.close() }
+        when (node) {
+            is NavNode.Item -> navController.navigateTopLevel(node.entry.route)
+            // A link the app resolved opens like any other drawer row, detail screen
+            // or not: one rule, and back-press lands on Home as it does from every
+            // row. One it could not resolve goes to the browser, absolute against
+            // the site's base URL (§6.3).
+            is NavNode.Link -> node.route
+                ?.let { navController.navigateTopLevel(it) }
+                ?: resolveUrl(node.path)?.let { WebHandoff.open(context, it) }
+            // Section headers aren't clickable — the group is always open (§6.3).
+            is NavNode.Section -> Unit
+        }
+    }
+
+    ModalNavigationDrawer(
+        drawerState = drawerState,
+        gesturesEnabled = isTopLevel,
+        drawerContent = {
+            ModalDrawerSheet(drawerContainerColor = MaterialTheme.colorScheme.surfaceVariant) {
+                val drawerItemColors = NavigationDrawerItemDefaults.colors(
+                    selectedContainerColor = MaterialTheme.colorScheme.secondaryContainer,
+                    selectedTextColor = MaterialTheme.colorScheme.onSecondaryContainer,
+                    unselectedTextColor = MaterialTheme.colorScheme.onSurface,
+                )
+                // Scroll the drawer: a signed-in session adds Account, Notifications, and
+                // the player groups, and the full list overflows a phone's drawer height —
+                // without this the lower entries (Notifications included) are clipped and
+                // unreachable. See RunicGateway M10.
+                Column(Modifier.verticalScroll(rememberScrollState())) {
+                Spacer(Modifier.height(12.dp))
+                // The instance's logo above its name (§5.6). Decorative — the name
+                // is the very next line — and absent on an instance that uploaded
+                // none, in which case the header is exactly what it was before M12.
+                BrandLogo(
+                    logo = brand?.logo,
+                    height = 32.dp,
+                    modifier = Modifier.padding(start = 24.dp, end = 24.dp, bottom = 4.dp),
+                )
+                Text(
+                    text = brand?.name?.takeIf { it.isNotBlank() } ?: stringResource(R.string.app_name),
+                    style = MaterialTheme.typography.titleLarge,
+                    color = MaterialTheme.colorScheme.onSurface,
+                    modifier = Modifier.padding(horizontal = 24.dp, vertical = 12.dp),
+                )
+                HorizontalDivider()
+                Spacer(Modifier.height(8.dp))
+                nav.forEach { node ->
+                    if (node is NavNode.Section) {
+                        // A group the admin created: its label as a header, its rows
+                        // beneath it. Always open — a drawer is already a vertical
+                        // list, so the website's dropdown does not translate (§6.3).
+                        Text(
+                            text = node.label,
+                            style = MaterialTheme.typography.labelLarge,
+                            color = MaterialTheme.colorScheme.onSurfaceVariant,
+                            modifier = Modifier.padding(
+                                start = 28.dp,
+                                end = 28.dp,
+                                top = 12.dp,
+                                bottom = 4.dp,
+                            ),
+                        )
+                        node.items.forEach { child ->
+                            NavRow(child, currentRoute, drawerItemColors, indented = true) {
+                                openNode(child)
+                            }
+                        }
+                    } else {
+                        NavRow(node, currentRoute, drawerItemColors) { openNode(node) }
+                    }
+                }
+
+                HorizontalDivider(Modifier.padding(vertical = 8.dp))
+
+                // Sign in / Sign out toggles on the session (§5).
+                val signInLabel = if (session is Session.SignedIn) {
+                    R.string.menu_sign_out
+                } else {
+                    R.string.menu_sign_in
+                }
+                NavigationDrawerItem(
+                    label = { Text(stringResource(signInLabel)) },
+                    selected = false,
+                    onClick = {
+                        scope.launch { drawerState.close() }
+                        if (session is Session.SignedIn) {
+                            sessionViewModel.signOut()
+                            navController.navigateTopLevel(Routes.HOME)
+                        } else {
+                            navController.navigate(Routes.LOGIN)
+                        }
+                    },
+                    colors = drawerItemColors,
+                    shape = LocalShardStructure.current.pill,
+                    modifier = Modifier.padding(NavigationDrawerItemDefaults.ItemPadding),
+                )
+                NavigationDrawerItem(
+                    label = { Text(stringResource(R.string.menu_change_server)) },
+                    selected = false,
+                    onClick = {
+                        scope.launch { drawerState.close() }
+                        onChangeServer()
+                    },
+                    colors = drawerItemColors,
+                    shape = LocalShardStructure.current.pill,
+                    modifier = Modifier.padding(NavigationDrawerItemDefaults.ItemPadding),
+                )
+                }
+            }
+        },
+    ) {
+        Scaffold(
+            modifier = modifier,
+            topBar = {
+                TopAppBar(
+                    colors = TopAppBarDefaults.topAppBarColors(
+                        containerColor = MaterialTheme.colorScheme.surfaceVariant,
+                        titleContentColor = MaterialTheme.colorScheme.onSurface,
+                        navigationIconContentColor = MaterialTheme.colorScheme.onSurface,
+                        actionIconContentColor = MaterialTheme.colorScheme.onSurface,
+                    ),
+                    title = {
+                        val name = brand?.name?.takeIf { it.isNotBlank() }
+                            ?: stringResource(R.string.app_name)
+                        // The logo stands in for the title here, so unlike the drawer's
+                        // it is named for a screen reader — and it falls back to the
+                        // text when the instance has no logo or the load fails (§5.6).
+                        BrandLogo(
+                            logo = brand?.logo,
+                            height = 24.dp,
+                            contentDescription = name,
+                        ) {
+                            Text(
+                                text = name.uppercase(),
+                                style = MaterialTheme.typography.titleSmall
+                                    .copy(letterSpacing = 1.2.sp),
+                                maxLines = 1,
+                                overflow = TextOverflow.Ellipsis,
+                            )
+                        }
+                    },
+                    navigationIcon = {
+                        if (isTopLevel) {
+                            IconButton(onClick = { scope.launch { drawerState.open() } }) {
+                                Icon(Icons.Filled.Menu, stringResource(R.string.nav_open_menu))
+                            }
+                        } else {
+                            IconButton(onClick = { navController.popBackStack() }) {
+                                Icon(
+                                    Icons.AutoMirrored.Filled.ArrowBack,
+                                    stringResource(R.string.action_back),
+                                )
+                            }
+                        }
+                    },
+                )
+            },
+        ) { innerPadding ->
+            RunicNavHost(
+                navController = navController,
+                brand = brand,
+                session = session,
+                onSignOut = { sessionViewModel.signOut() },
+                onSignOutEverywhere = { sessionViewModel.signOut(allDevices = true) },
+                modifier = Modifier.padding(innerPadding),
+            )
+        }
+    }
+}
+
+/**
+ * One drawer row: a coded entry, or an admin's added link (§6.3).
+ *
+ * A link that the app can open natively is deliberately indistinguishable from a
+ * coded row — that is the point of resolving it. One that hands off to the browser
+ * carries a trailing icon, so leaving the app is never a surprise.
+ */
+@Composable
+private fun NavRow(
+    node: NavNode,
+    currentRoute: String?,
+    colors: NavigationDrawerItemColors,
+    indented: Boolean = false,
+    onClick: () -> Unit,
+) {
+    val route = when (node) {
+        is NavNode.Item -> node.entry.route
+        is NavNode.Link -> node.route
+        is NavNode.Section -> null
+    }
+    val label = when (node) {
+        // An admin's label wins over the bundled one, and is the same string in
+        // every locale — see MenuEntry.label.
+        is NavNode.Item -> node.entry.label ?: stringResource(node.entry.labelRes)
+        is NavNode.Link -> node.label
+        is NavNode.Section -> return
+    }
+    val handsOff = node is NavNode.Link && node.route == null
+
+    NavigationDrawerItem(
+        label = { Text(label) },
+        selected = route != null && currentRoute == route.substringBefore('?'),
+        onClick = onClick,
+        badge = if (!handsOff) {
+            null
+        } else {
+            {
+                Icon(
+                    Icons.AutoMirrored.Filled.ExitToApp,
+                    contentDescription = stringResource(R.string.nav_opens_in_browser),
+                    modifier = Modifier.size(18.dp),
+                )
+            }
+        },
+        colors = colors,
+        // Like Card's elevation, NavigationDrawerItem takes its shape as a default
+        // argument (CircleShape) rather than from the theme, so --radius-pill has to
+        // be handed to it at every call site or the selected row stays fully round
+        // while every other radius follows the shard (phase 8's AC-5 walk).
+        shape = LocalShardStructure.current.pill,
+        modifier = Modifier
+            .padding(NavigationDrawerItemDefaults.ItemPadding)
+            .padding(start = if (indented) 16.dp else 0.dp),
+    )
+}
+
+@Composable
+private fun RunicNavHost(
+    navController: NavHostController,
+    brand: BrandDto?,
+    session: Session,
+    onSignOut: () -> Unit,
+    onSignOutEverywhere: () -> Unit,
+    modifier: Modifier = Modifier,
+) {
+    NavHost(
+        navController = navController,
+        startDestination = Routes.HOME,
+        modifier = modifier,
+    ) {
+        composable(Routes.HOME) {
+            HomeScreen(brand = brand)
+        }
+        // The category is optional: navigating to plain Routes.NEWS matches this
+        // pattern with no argument and opens the default tab, which is every route
+        // into the screen except an admin's nav override or added link (§6.2).
+        composable(
+            route = Routes.NEWS_ROUTE,
+            arguments = listOf(
+                navArgument(Routes.Args.CATEGORY) {
+                    type = NavType.StringType
+                    nullable = true
+                    defaultValue = null
+                },
+            ),
+        ) {
+            NewsScreen(onOpenPost = { category, idOrSlug ->
+                navController.navigate(Routes.post(category, idOrSlug))
+            })
+        }
+        composable(
+            route = Routes.POST,
+            arguments = listOf(
+                navArgument(Routes.Args.CATEGORY) { type = NavType.StringType },
+                navArgument(Routes.Args.ID_OR_SLUG) { type = NavType.StringType },
+            ),
+        ) {
+            PostScreen()
+        }
+        composable(Routes.SHARD) {
+            ShardScreen(onOpenBoard = { board ->
+                navController.navigate(
+                    when (board) {
+                        ShardBoard.CHAMPS -> Routes.SHARD_CHAMPS
+                        ShardBoard.GUILDS -> Routes.SHARD_GUILDS
+                        ShardBoard.GOVERNORS -> Routes.SHARD_GOVERNORS
+                        ShardBoard.HOUSES -> Routes.SHARD_HOUSES
+                    },
+                )
+            })
+        }
+        composable(Routes.SHARD_CHAMPS) { ChampsScreen() }
+        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)) })
+        }
+        composable(
+            route = Routes.WIKI_PAGE,
+            arguments = listOf(navArgument(Routes.Args.SLUG) { type = NavType.StringType }),
+        ) {
+            WikiPageScreen(onOpenPage = { slug -> navController.navigate(Routes.wikiPage(slug)) })
+        }
+        composable(
+            route = Routes.PAGE,
+            arguments = listOf(navArgument(Routes.Args.SLUG) { type = NavType.StringType }),
+        ) {
+            PageScreen()
+        }
+        composable(Routes.CONTACT) {
+            ContactScreen()
+        }
+        composable(Routes.LOGIN) {
+            // Leave the login screen as soon as the session is established — whether by
+            // password or the SSO bridge. Keying off the shared session (not just the
+            // login VM's local flag) makes this robust to the deep-link/recomposition
+            // timing of the Custom-Tab return, which the LoginScreen callback alone can miss.
+            if (session is Session.SignedIn) {
+                LaunchedEffect(Unit) { navController.popBackStack(Routes.LOGIN, inclusive = true) }
+            } else {
+                LoginScreen(onSignedIn = { navController.popBackStack() })
+            }
+        }
+        composable(Routes.ACCOUNT) {
+            // Only meaningful while signed in; a sign-out (here or from the drawer)
+            // sends the user home rather than leaving a stale identity on screen.
+            when (val s = session) {
+                is Session.SignedIn -> AccountScreen(
+                    username = s.user.username,
+                    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).
+            when (session) {
+                is Session.SignedIn -> NotificationsScreen()
+                Session.SignedOut -> LaunchedEffect(Unit) { navController.navigateTopLevel(Routes.HOME) }
+            }
+        }
+
+        // ── Player game data (§6.3) — reached from the player-only menu groups.
+        // The server enforces the player gate on every call; these screens simply
+        // render 401/403/503 as clean states (§7).
+        composable(Routes.PLAYER_CHARACTERS) {
+            PlayerGate(session, navController) {
+                CharactersScreen(onOpenChar = { serial -> navController.navigate(Routes.playerChar(serial)) })
+            }
+        }
+        composable(
+            route = Routes.PLAYER_CHAR,
+            arguments = listOf(navArgument(Routes.Args.SERIAL) { type = NavType.StringType }),
+        ) {
+            CharacterSheetScreen()
+        }
+        composable(Routes.PLAYER_VENDORS) {
+            PlayerGate(session, navController) { VendorsScreen() }
+        }
+        composable(Routes.PLAYER_HOUSES) {
+            PlayerGate(session, navController) { MyHousesScreen() }
+        }
+
+        // ── Staff operations (§1, §6.4, M10) — reached from the staff menu section.
+        // The backend re-checks role on every /admin/… call; these gates only mirror
+        // the menu's visibility so a signed-out/demoted user isn't left on a stale screen.
+        composable(Routes.ADMIN_DASHBOARD) {
+            StaffGate(session, navController) {
+                AdminDashboardScreen(isAdmin = (session as? Session.SignedIn)?.user?.isAdmin == true)
+            }
+        }
+        composable(Routes.ADMIN_CONTENT) {
+            StaffGate(session, navController) { AdminContentScreen() }
+        }
+        composable(Routes.ADMIN_MODERATION) {
+            StaffGate(session, navController, require = { it.isModerator }) { AdminModerationScreen() }
+        }
+        composable(Routes.ADMIN_SUPPORT) {
+            StaffGate(session, navController, require = { it.isModerator }) { AdminSupportScreen() }
+        }
+    }
+}
+
+/**
+ * A UX guard for the player-only groups: while signed in, render [content]; if the
+ * session drops (sign-out, or a server-side demotion caught on resume, §4.3), send
+ * the user home instead of leaving a stale player screen up. The backend remains
+ * the authority — this only mirrors the menu's visibility rule.
+ */
+@Composable
+private fun PlayerGate(
+    session: Session,
+    navController: NavHostController,
+    content: @Composable () -> Unit,
+) {
+    when (session) {
+        is Session.SignedIn -> content()
+        Session.SignedOut -> LaunchedEffect(Unit) { navController.navigateTopLevel(Routes.HOME) }
+    }
+}
+
+/**
+ * The staff-operations analogue of [PlayerGate] (§1, M10): render [content] only for
+ * a signed-in staff account; a signed-out/demoted session (caught on resume, §4.3) is
+ * sent home rather than left on a stale admin screen. The backend is the authority —
+ * every `/admin/…` call re-checks role — so this only mirrors the menu's visibility.
+ */
+@Composable
+private fun StaffGate(
+    session: Session,
+    navController: NavHostController,
+    require: (com.runicgateway.app.core.auth.SessionUser) -> Boolean = { it.isStaff },
+    content: @Composable () -> Unit,
+) {
+    val ok = (session as? Session.SignedIn)?.user?.let(require) == true
+    if (ok) content() else LaunchedEffect(Unit) { navController.navigateTopLevel(Routes.HOME) }
+}
+
+/** Navigate to a top-level menu destination: single instance, reset to it. */
+private fun NavHostController.navigateTopLevel(route: String) {
+    navigate(route) {
+        popUpTo(Routes.HOME) { saveState = true }
+        launchSingleTop = true
+        restoreState = true
+    }
+}

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

@@ -0,0 +1,85 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.ui
+
+import com.runicgateway.app.core.result.ApiResult
+
+/**
+ * The load state a screen renders. View models expose a `StateFlow<UiState<T>>`;
+ * the Compose layer renders loading / content / error+retry from it (PLAN.md §7:
+ * clean loading/error/retry states, no crash on a down backend).
+ */
+sealed interface UiState<out T> {
+    data object Loading : UiState<Nothing>
+    data class Success<T>(val data: T) : UiState<T>
+    data class Error(val kind: ErrorKind, val httpStatus: Int? = null) : UiState<Nothing>
+}
+
+/**
+ * Coarse failure buckets the UI turns into a friendly message + retry. Kept
+ * transport-agnostic so a screen picks the right copy without inspecting raw
+ * exceptions or status codes.
+ */
+enum class ErrorKind {
+    /** No answer from the backend — offline, DNS, TLS, timeout. */
+    NETWORK,
+
+    /** Requested item doesn't exist (404). */
+    NOT_FOUND,
+
+    /** Too many requests (429) — back off and retry shortly. */
+    RATE_LIMITED,
+
+    /** 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,
+}
+
+/** Fold an [ApiResult] into a [UiState], mapping known statuses to [ErrorKind]s. */
+fun <T> ApiResult<T>.toUiState(): UiState<T> = when (this) {
+    is ApiResult.Ok -> UiState.Success(data)
+    is ApiResult.NetworkError -> UiState.Error(ErrorKind.NETWORK)
+    is ApiResult.HttpError -> UiState.Error(
+        kind = when (status) {
+            404 -> ErrorKind.NOT_FOUND
+            429 -> ErrorKind.RATE_LIMITED
+            503 -> ErrorKind.SHARD_OFFLINE
+            else -> ErrorKind.SERVER
+        },
+        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

@@ -0,0 +1,291 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+package com.runicgateway.app.ui.admin
+
+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
+import androidx.compose.foundation.layout.height
+import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.layout.width
+import androidx.compose.foundation.lazy.LazyColumn
+import androidx.compose.foundation.lazy.items
+import androidx.compose.material3.AlertDialog
+import androidx.compose.material3.FilterChip
+import androidx.compose.material3.HorizontalDivider
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.OutlinedButton
+import androidx.compose.material3.OutlinedTextField
+import androidx.compose.material3.Switch
+import androidx.compose.material3.Tab
+import androidx.compose.material3.TabRow
+import androidx.compose.material3.Text
+import androidx.compose.material3.TextButton
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.getValue
+import androidx.compose.runtime.mutableIntStateOf
+import androidx.compose.runtime.mutableStateOf
+import androidx.compose.runtime.saveable.rememberSaveable
+import androidx.compose.runtime.setValue
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.res.stringResource
+import androidx.compose.ui.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.AdminPostDto
+import com.runicgateway.app.data.api.dto.AdminWikiCategoryDto
+import com.runicgateway.app.data.api.dto.AdminWikiTagDto
+import com.runicgateway.app.ui.UiState
+import com.runicgateway.app.ui.components.ErrorView
+import com.runicgateway.app.ui.components.LoadingView
+import com.runicgateway.app.ui.components.PillTone
+import com.runicgateway.app.ui.components.ShardCard
+import com.runicgateway.app.ui.components.StatusPill
+
+/**
+ * The staff content screen (PLAN.md §1, M10): news posts and wiki taxonomy, in two
+ * tabs. Create/publish/delete over the existing `/admin/posts` + `/admin/wiki/…`
+ * routes; the CMS block/hero editor stays out of scope. Any staff role; the server
+ * re-checks on every call.
+ */
+@Composable
+fun AdminContentScreen(
+    modifier: Modifier = Modifier,
+    viewModel: AdminContentViewModel = hiltViewModel(),
+) {
+    val state by viewModel.state.collectAsStateWithLifecycle()
+    var tab by rememberSaveable { mutableIntStateOf(0) }
+    var showNewPost by rememberSaveable { mutableStateOf(false) }
+    var showNewCategory by rememberSaveable { mutableStateOf(false) }
+
+    Column(modifier.fillMaxSize()) {
+        TabRow(selectedTabIndex = tab) {
+            Tab(selected = tab == 0, onClick = { tab = 0 }, text = { Text(stringResource(R.string.admin_content_tab_posts)) })
+            Tab(selected = tab == 1, onClick = { tab = 1 }, text = { Text(stringResource(R.string.admin_content_tab_wiki)) })
+        }
+
+        state.feedback?.let {
+            Text(
+                text = stringResource(it.messageRes),
+                style = MaterialTheme.typography.bodySmall,
+                color = if (it.ok) MaterialTheme.colorScheme.onSurfaceVariant else MaterialTheme.colorScheme.error,
+                modifier = Modifier.fillMaxWidth().padding(horizontal = 16.dp, vertical = 6.dp),
+            )
+        }
+
+        when (tab) {
+            0 -> PostsTab(
+                state = state.posts,
+                busy = state.busy,
+                onNew = { showNewPost = true },
+                onToggle = viewModel::togglePublish,
+                onDelete = viewModel::deletePost,
+                onRetry = viewModel::loadPosts,
+            )
+            else -> WikiTab(
+                state = state.categories,
+                tags = state.tags,
+                busy = state.busy,
+                onNew = { showNewCategory = true },
+                onDelete = viewModel::deleteCategory,
+                onRetry = viewModel::loadWiki,
+            )
+        }
+    }
+
+    if (showNewPost) {
+        NewPostDialog(
+            categories = viewModel.postCategories,
+            onDismiss = { showNewPost = false },
+            onCreate = { cat, title, excerpt, body, published ->
+                viewModel.createPost(cat, title, excerpt, body, published)
+                showNewPost = false
+            },
+        )
+    }
+    if (showNewCategory) {
+        NewCategoryDialog(
+            onDismiss = { showNewCategory = false },
+            onCreate = { slug, title, desc, sort ->
+                viewModel.createCategory(slug, title, desc, sort)
+                showNewCategory = false
+            },
+        )
+    }
+}
+
+@Composable
+private fun PostsTab(
+    state: UiState<List<AdminPostDto>>,
+    busy: Boolean,
+    onNew: () -> Unit,
+    onToggle: (AdminPostDto) -> Unit,
+    onDelete: (Long) -> Unit,
+    onRetry: () -> Unit,
+) {
+    when (state) {
+        is UiState.Loading -> LoadingView()
+        is UiState.Error -> ErrorView(state.kind, onRetry = onRetry)
+        is UiState.Success -> LazyColumn(Modifier.fillMaxSize().padding(16.dp)) {
+            item {
+                OutlinedButton(onClick = onNew, enabled = !busy, modifier = Modifier.fillMaxWidth().padding(bottom = 8.dp)) {
+                    Text(stringResource(R.string.admin_content_new_post))
+                }
+            }
+            items(state.data, key = { it.id }) { post ->
+                ShardCard(Modifier.fillMaxWidth().padding(vertical = 6.dp)) {
+                    Column(Modifier.padding(12.dp)) {
+                        Text(post.title, style = MaterialTheme.typography.bodyLarge)
+                        Spacer(Modifier.height(4.dp))
+                        Row(verticalAlignment = Alignment.CenterVertically) {
+                            StatusPill(
+                                text = if (post.isPublished) stringResource(R.string.admin_content_published)
+                                else stringResource(R.string.admin_content_draft),
+                                tone = if (post.isPublished) PillTone.Success else PillTone.Neutral,
+                            )
+                            Spacer(Modifier.width(8.dp))
+                            Text(post.category, style = MaterialTheme.typography.bodySmall, color = MaterialTheme.colorScheme.onSurfaceVariant)
+                        }
+                        Row(Modifier.fillMaxWidth().padding(top = 8.dp), horizontalArrangement = Arrangement.End) {
+                            TextButton(onClick = { onToggle(post) }, enabled = !busy) {
+                                Text(
+                                    stringResource(
+                                        if (post.isPublished) R.string.admin_content_unpublish else R.string.admin_content_publish,
+                                    ),
+                                )
+                            }
+                            TextButton(onClick = { onDelete(post.id) }, enabled = !busy) {
+                                Text(stringResource(R.string.admin_content_delete), color = MaterialTheme.colorScheme.error)
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    }
+}
+
+@Composable
+private fun WikiTab(
+    state: UiState<List<AdminWikiCategoryDto>>,
+    tags: List<AdminWikiTagDto>,
+    busy: Boolean,
+    onNew: () -> Unit,
+    onDelete: (Long) -> Unit,
+    onRetry: () -> Unit,
+) {
+    when (state) {
+        is UiState.Loading -> LoadingView()
+        is UiState.Error -> ErrorView(state.kind, onRetry = onRetry)
+        is UiState.Success -> LazyColumn(Modifier.fillMaxSize().padding(16.dp)) {
+            item {
+                OutlinedButton(onClick = onNew, enabled = !busy, modifier = Modifier.fillMaxWidth().padding(bottom = 8.dp)) {
+                    Text(stringResource(R.string.admin_content_new_category))
+                }
+            }
+            items(state.data, key = { it.id }) { cat ->
+                ShardCard(Modifier.fillMaxWidth().padding(vertical = 6.dp)) {
+                    Column(Modifier.padding(12.dp)) {
+                        Text(cat.title, style = MaterialTheme.typography.bodyLarge)
+                        Text(
+                            text = stringResource(R.string.admin_content_cat_meta, cat.slug, cat.pageCount ?: 0),
+                            style = MaterialTheme.typography.bodySmall,
+                            color = MaterialTheme.colorScheme.onSurfaceVariant,
+                        )
+                        Row(Modifier.fillMaxWidth().padding(top = 8.dp), horizontalArrangement = Arrangement.End) {
+                            TextButton(onClick = { onDelete(cat.id) }, enabled = !busy) {
+                                Text(stringResource(R.string.admin_content_delete), color = MaterialTheme.colorScheme.error)
+                            }
+                        }
+                    }
+                }
+            }
+            if (tags.isNotEmpty()) {
+                item {
+                    HorizontalDivider(Modifier.padding(vertical = 12.dp))
+                    Text(
+                        stringResource(R.string.admin_content_tags, tags.joinToString(", ") { it.label }),
+                        style = MaterialTheme.typography.bodySmall,
+                        color = MaterialTheme.colorScheme.onSurfaceVariant,
+                    )
+                }
+            }
+        }
+    }
+}
+
+@Composable
+private fun NewPostDialog(
+    categories: List<String>,
+    onDismiss: () -> Unit,
+    onCreate: (category: String, title: String, excerpt: String, body: String, published: Boolean) -> Unit,
+) {
+    var category by rememberSaveable { mutableStateOf(categories.first()) }
+    var title by rememberSaveable { mutableStateOf("") }
+    var excerpt by rememberSaveable { mutableStateOf("") }
+    var body by rememberSaveable { mutableStateOf("") }
+    var published by rememberSaveable { mutableStateOf(false) }
+
+    AlertDialog(
+        onDismissRequest = onDismiss,
+        confirmButton = {
+            TextButton(onClick = { onCreate(category, title, excerpt, body, published) }) {
+                Text(stringResource(R.string.admin_content_create))
+            }
+        },
+        dismissButton = { TextButton(onClick = onDismiss) { Text(stringResource(R.string.action_cancel)) } },
+        title = { Text(stringResource(R.string.admin_content_new_post)) },
+        text = {
+            Column {
+                Row(horizontalArrangement = Arrangement.spacedBy(6.dp)) {
+                    categories.forEach { c ->
+                        FilterChip(selected = category == c, onClick = { category = c }, label = { Text(c) })
+                    }
+                }
+                OutlinedTextField(value = title, onValueChange = { title = it }, singleLine = true, label = { Text(stringResource(R.string.admin_content_field_title)) }, modifier = Modifier.fillMaxWidth().padding(top = 8.dp))
+                OutlinedTextField(value = excerpt, onValueChange = { excerpt = it }, label = { Text(stringResource(R.string.admin_content_field_excerpt)) }, modifier = Modifier.fillMaxWidth().padding(top = 8.dp))
+                OutlinedTextField(value = body, onValueChange = { body = it }, label = { Text(stringResource(R.string.admin_content_field_body)) }, modifier = Modifier.fillMaxWidth().padding(top = 8.dp))
+                Row(Modifier.fillMaxWidth().padding(top = 8.dp), verticalAlignment = Alignment.CenterVertically) {
+                    Text(stringResource(R.string.admin_content_publish_now), modifier = Modifier.weight(1f))
+                    Switch(checked = published, onCheckedChange = { published = it })
+                }
+            }
+        },
+    )
+}
+
+@Composable
+private fun NewCategoryDialog(
+    onDismiss: () -> Unit,
+    onCreate: (slug: String, title: String, description: String, sortOrder: Int?) -> Unit,
+) {
+    var slug by rememberSaveable { mutableStateOf("") }
+    var title by rememberSaveable { mutableStateOf("") }
+    var description by rememberSaveable { mutableStateOf("") }
+    var sort by rememberSaveable { mutableStateOf("") }
+
+    AlertDialog(
+        onDismissRequest = onDismiss,
+        confirmButton = {
+            TextButton(onClick = { onCreate(slug, title, description, sort.toIntOrNull()) }) {
+                Text(stringResource(R.string.admin_content_create))
+            }
+        },
+        dismissButton = { TextButton(onClick = onDismiss) { Text(stringResource(R.string.action_cancel)) } },
+        title = { Text(stringResource(R.string.admin_content_new_category)) },
+        text = {
+            Column {
+                OutlinedTextField(value = slug, onValueChange = { slug = it }, singleLine = true, label = { Text(stringResource(R.string.admin_content_field_slug)) }, modifier = Modifier.fillMaxWidth())
+                OutlinedTextField(value = title, onValueChange = { title = it }, singleLine = true, label = { Text(stringResource(R.string.admin_content_field_title)) }, modifier = Modifier.fillMaxWidth().padding(top = 8.dp))
+                OutlinedTextField(value = description, onValueChange = { description = it }, label = { Text(stringResource(R.string.admin_content_field_description)) }, modifier = Modifier.fillMaxWidth().padding(top = 8.dp))
+                OutlinedTextField(value = sort, onValueChange = { sort = it.filter(Char::isDigit) }, singleLine = true, label = { Text(stringResource(R.string.admin_content_field_sort)) }, modifier = Modifier.fillMaxWidth().padding(top = 8.dp))
+            }
+        },
+    )
+}