docs(ci): use the actual case-sensitive SonarQube project keys

link and Android-app reuse the pre-existing capitalised keys
(Runic-Gateway-link, Runic-Gateway-Android-app); the server rejects
case-variant duplicates. Note the case-sensitivity gotcha.

Co-Authored-By: Claude <noreply@anthropic.com>

.gitea/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,41 @@
+---
+name: Bug report
+about: Report something that is broken or behaving unexpectedly
+title: "[bug] "
+labels:
+  - bug
+---
+
+## Summary
+
+<!-- A clear, concise description of the bug. -->
+
+## Steps to reproduce
+
+1.
+2.
+3.
+
+## Expected behavior
+
+<!-- What you expected to happen. -->
+
+## Actual behavior
+
+<!-- What actually happened. Include exact error messages and logs if you have them. -->
+
+## Environment
+
+- Component / repo:
+- Version or commit:
+- OS / runtime (Node, Rust, ServUO, browser…):
+- Deployment (Docker Compose, local dev, bare metal…):
+
+## Additional context
+
+<!-- Screenshots, config (with secrets redacted), anything else that helps. -->
+
+<!--
+  Security issue? Do NOT file it here. See SECURITY.md and email
+  whitlocktech@gmail.com instead.
+-->

.gitea/ISSUE_TEMPLATE/config.yaml

@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Security vulnerability
+    url: https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/SECURITY.md
+    about: Please do not open a public issue for security problems — report them privately by email instead (see SECURITY.md).

.gitea/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,23 @@
+---
+name: Feature request
+about: Suggest an idea, enhancement, or new capability
+title: "[feature] "
+labels:
+  - enhancement
+---
+
+## Problem / motivation
+
+<!-- What are you trying to do? What's missing or painful today? -->
+
+## Proposed solution
+
+<!-- What you'd like to see happen. -->
+
+## Alternatives considered
+
+<!-- Other approaches you thought about, and why you prefer the one above. -->
+
+## Additional context
+
+<!-- Mockups, links, related issues, affected component/repo, etc. -->

.gitea/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,33 @@
+<!--
+  Thanks for contributing to Runic Gateway!
+  Please fill out the sections below and check every box before requesting review.
+-->
+
+## What & why
+
+<!-- What does this PR change, and why? Link any related issue: "Closes #123". -->
+
+## How it was tested
+
+<!-- Commands you ran, manual steps, screenshots. -->
+
+## Checklist
+
+- [ ] I have read [CONTRIBUTING.md](CONTRIBUTING.md).
+- [ ] The change builds and existing tests/checks pass locally.
+- [ ] I have added or updated tests/docs where it makes sense.
+- [ ] My commits are reasonably scoped with clear messages.
+
+## AI-assisted contributions (required)
+
+This project **requires disclosure of AI tool usage**. Please pick one:
+
+- [ ] No AI tools were used to produce this contribution.
+- [ ] AI tools were used. Tool(s): `___________`. I have reviewed and understand
+      every change, and take responsibility for it. AI-authored commits are
+      marked with a `Co-Authored-By` / `Assisted-By` trailer.
+
+## License
+
+- [ ] I agree that my contribution is licensed under this project's license
+      (**GNU GPL v3.0 or later**), and I have the right to contribute it.

CODE_OF_CONDUCT.md

@@ -0,0 +1,133 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+**whitlocktech@gmail.com**.
+
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

CONTRIBUTING.md

@@ -0,0 +1,73 @@
+# Contributing to Runic Gateway — Documentation
+
+Thanks for your interest in contributing! This repo is the **central
+documentation** for the Runic Gateway platform — design docs, the protocol spec,
+integration guides, and research, extracted from the code repos so they live in
+one place.
+
+By participating you agree to abide by our
+[Code of Conduct](CODE_OF_CONDUCT.md).
+
+## Ways to contribute
+
+- **Report an error** (something wrong, outdated, or unclear) or **request new
+  documentation** through the
+  [issue tracker](https://gitea.whitlocktech.com/RunicGateway/docs/issues)
+  (issue templates are provided).
+- **Fix or expand the docs** by opening a pull request (see below).
+- **Never** report a security vulnerability in a public issue — see
+  [SECURITY.md](SECURITY.md).
+
+## Working on the docs
+
+Everything here is Markdown — no build step. Just edit the relevant file and
+preview it in any Markdown viewer (or on Gitea).
+
+```
+website/   docs for the shard website (Node/Express + MariaDB + React/Vite)
+link/      docs for the ServUO bridge (C# plugin + Rust sidecar)
+```
+
+Guidelines:
+
+- Keep documents in the folder matching their subsystem (`website/` or `link/`).
+- These docs are the **authoritative** copy of the protocol and design; when you
+  change behavior in a code repo, update the matching doc here in the same or a
+  follow-up PR so the spec and implementation stay in sync.
+- Use relative links between docs, and check that any links you add resolve.
+- Prefer clear prose and tables over screenshots where possible.
+
+## Branch & PR workflow
+
+1. Branch from `main` with a descriptive name (`docs/…`, `fix/…`, `chore/…`).
+2. Keep changes focused; small PRs are easier to review.
+3. Push and open a pull request against `main`. Fill out the PR template,
+   including the **AI-assisted contributions** disclosure.
+4. A maintainer will review; address feedback with follow-up commits.
+
+### Commit messages
+
+We use [Conventional Commits](https://www.conventionalcommits.org/) —
+`type(scope): summary` (e.g. `docs(link): clarify town-crier caps`).
+
+## AI-assisted contributions (disclosure required)
+
+This project is developed openly with AI assistance, and we ask the same
+transparency of everyone. **If you used an AI tool** (Claude, Copilot, ChatGPT,
+Cursor, etc.) to help produce a contribution, you must disclose it:
+
+- Tick the AI-usage box in the pull-request template and name the tool(s).
+- Mark AI-authored commits with a trailer, e.g.
+  `Co-Authored-By: Claude <noreply@anthropic.com>` or `Assisted-By: <tool>`.
+- You remain responsible for every line you submit: review it, understand it,
+  and make sure it is accurate and that you have the right to contribute it.
+
+Disclosed AI assistance is welcome. Undisclosed AI-generated contributions are
+not, and may be closed.
+
+## License
+
+Runic Gateway is licensed under the **GNU General Public License v3.0 or later**
+(see [LICENSE.md](LICENSE.md)). By submitting a contribution you agree that it is
+licensed under the same terms (inbound = outbound) and that you have the right to
+contribute it.

CONTRIBUTORS.md

@@ -0,0 +1,31 @@
+# Contributors
+
+Runic Gateway is built and maintained by the people and tools listed here.
+Thank you to everyone who has contributed.
+
+## Maintainers
+
+- **whitlocktech** <whitlocktech@gmail.com> — project lead and maintainer
+
+## Contributors
+
+<!--
+  Add yourself here when your contribution is merged — alphabetical by name or
+  handle. One line each:
+
+  - **Name or handle** (optional link) — what you contributed
+-->
+
+- _Your name could be here — see [CONTRIBUTING.md](CONTRIBUTING.md)._
+
+## AI-assisted development
+
+Parts of Runic Gateway were developed with the assistance of AI coding tools,
+including **Claude** (Anthropic) via Claude Code. AI-assisted commits are
+attributed in their commit trailers (e.g. `Co-Authored-By: Claude ...`).
+
+In keeping with this project's transparency policy, **all contributors must
+disclose their use of AI tools** on any contribution — see the
+"AI-assisted contributions" section of [CONTRIBUTING.md](CONTRIBUTING.md).
+Disclosed AI assistance is welcome; undisclosed AI-generated contributions are
+not.

LICENSE.md

@@ -0,0 +1,674 @@
+                    GNU GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+                            Preamble
+
+  The GNU General Public License is a free, copyleft license for
+software and other kinds of works.
+
+  The licenses for most software and other practical works are designed
+to take away your freedom to share and change the works.  By contrast,
+the GNU General Public License is intended to guarantee your freedom to
+share and change all versions of a program--to make sure it remains free
+software for all its users.  We, the Free Software Foundation, use the
+GNU General Public License for most of our software; it applies also to
+any other work released this way by its authors.  You can apply it to
+your programs, too.
+
+  When we speak of free software, we are referring to freedom, not
+price.  Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+them if you wish), that you receive source code or can get it if you
+want it, that you can change the software or use pieces of it in new
+free programs, and that you know you can do these things.
+
+  To protect your rights, we need to prevent others from denying you
+these rights or asking you to surrender the rights.  Therefore, you have
+certain responsibilities if you distribute copies of the software, or if
+you modify it: responsibilities to respect the freedom of others.
+
+  For example, if you distribute copies of such a program, whether
+gratis or for a fee, you must pass on to the recipients the same
+freedoms that you received.  You must make sure that they, too, receive
+or can get the source code.  And you must show them these terms so they
+know their rights.
+
+  Developers that use the GNU GPL protect your rights with two steps:
+(1) assert copyright on the software, and (2) offer you this License
+giving you legal permission to copy, distribute and/or modify it.
+
+  For the developers' and authors' protection, the GPL clearly explains
+that there is no warranty for this free software.  For both users' and
+authors' sake, the GPL requires that modified versions be marked as
+changed, so that their problems will not be attributed erroneously to
+authors of previous versions.
+
+  Some devices are designed to deny users access to install or run
+modified versions of the software inside them, although the manufacturer
+can do so.  This is fundamentally incompatible with the aim of
+protecting users' freedom to change the software.  The systematic
+pattern of such abuse occurs in the area of products for individuals to
+use, which is precisely where it is most unacceptable.  Therefore, we
+have designed this version of the GPL to prohibit the practice for those
+products.  If such problems arise substantially in other domains, we
+stand ready to extend this provision to those domains in future versions
+of the GPL, as needed to protect the freedom of users.
+
+  Finally, every program is threatened constantly by software patents.
+States should not allow patents to restrict development and use of
+software on general-purpose computers, but in those that do, we wish to
+avoid the special danger that patents applied to a free program could
+make it effectively proprietary.  To prevent this, the GPL assures that
+patents cannot be used to render the program non-free.
+
+  The precise terms and conditions for copying, distribution and
+modification follow.
+
+                       TERMS AND CONDITIONS
+
+  0. Definitions.
+
+  "This License" refers to version 3 of the GNU General Public License.
+
+  "Copyright" also means copyright-like laws that apply to other kinds of
+works, such as semiconductor masks.
+
+  "The Program" refers to any copyrightable work licensed under this
+License.  Each licensee is addressed as "you".  "Licensees" and
+"recipients" may be individuals or organizations.
+
+  To "modify" a work means to copy from or adapt all or part of the work
+in a fashion requiring copyright permission, other than the making of an
+exact copy.  The resulting work is called a "modified version" of the
+earlier work or a work "based on" the earlier work.
+
+  A "covered work" means either the unmodified Program or a work based
+on the Program.
+
+  To "propagate" a work means to do anything with it that, without
+permission, would make you directly or secondarily liable for
+infringement under applicable copyright law, except executing it on a
+computer or modifying a private copy.  Propagation includes copying,
+distribution (with or without modification), making available to the
+public, and in some countries other activities as well.
+
+  To "convey" a work means any kind of propagation that enables other
+parties to make or receive copies.  Mere interaction with a user through
+a computer network, with no transfer of a copy, is not conveying.
+
+  An interactive user interface displays "Appropriate Legal Notices"
+to the extent that it includes a convenient and prominently visible
+feature that (1) displays an appropriate copyright notice, and (2)
+tells the user that there is no warranty for the work (except to the
+extent that warranties are provided), that licensees may convey the
+work under this License, and how to view a copy of this License.  If
+the interface presents a list of user commands or options, such as a
+menu, a prominent item in the list meets this criterion.
+
+  1. Source Code.
+
+  The "source code" for a work means the preferred form of the work
+for making modifications to it.  "Object code" means any non-source
+form of a work.
+
+  A "Standard Interface" means an interface that either is an official
+standard defined by a recognized standards body, or, in the case of
+interfaces specified for a particular programming language, one that
+is widely used among developers working in that language.
+
+  The "System Libraries" of an executable work include anything, other
+than the work as a whole, that (a) is included in the normal form of
+packaging a Major Component, but which is not part of that Major
+Component, and (b) serves only to enable use of the work with that
+Major Component, or to implement a Standard Interface for which an
+implementation is available to the public in source code form.  A
+"Major Component", in this context, means a major essential component
+(kernel, window system, and so on) of the specific operating system
+(if any) on which the executable work runs, or a compiler used to
+produce the work, or an object code interpreter used to run it.
+
+  The "Corresponding Source" for a work in object code form means all
+the source code needed to generate, install, and (for an executable
+work) run the object code and to modify the work, including scripts to
+control those activities.  However, it does not include the work's
+System Libraries, or general-purpose tools or generally available free
+programs which are used unmodified in performing those activities but
+which are not part of the work.  For example, Corresponding Source
+includes interface definition files associated with source files for
+the work, and the source code for shared libraries and dynamically
+linked subprograms that the work is specifically designed to require,
+such as by intimate data communication or control flow between those
+subprograms and other parts of the work.
+
+  The Corresponding Source need not include anything that users
+can regenerate automatically from other parts of the Corresponding
+Source.
+
+  The Corresponding Source for a work in source code form is that
+same work.
+
+  2. Basic Permissions.
+
+  All rights granted under this License are granted for the term of
+copyright on the Program, and are irrevocable provided the stated
+conditions are met.  This License explicitly affirms your unlimited
+permission to run the unmodified Program.  The output from running a
+covered work is covered by this License only if the output, given its
+content, constitutes a covered work.  This License acknowledges your
+rights of fair use or other equivalent, as provided by copyright law.
+
+  You may make, run and propagate covered works that you do not
+convey, without conditions so long as your license otherwise remains
+in force.  You may convey covered works to others for the sole purpose
+of having them make modifications exclusively for you, or provide you
+with facilities for running those works, provided that you comply with
+the terms of this License in conveying all material for which you do
+not control copyright.  Those thus making or running the covered works
+for you must do so exclusively on your behalf, under your direction
+and control, on terms that prohibit them from making any copies of
+your copyrighted material outside their relationship with you.
+
+  Conveying under any other circumstances is permitted solely under
+the conditions stated below.  Sublicensing is not allowed; section 10
+makes it unnecessary.
+
+  3. Protecting Users' Legal Rights From Anti-Circumvention Law.
+
+  No covered work shall be deemed part of an effective technological
+measure under any applicable law fulfilling obligations under article
+11 of the WIPO copyright treaty adopted on 20 December 1996, or
+similar laws prohibiting or restricting circumvention of such
+measures.
+
+  When you convey a covered work, you waive any legal power to forbid
+circumvention of technological measures to the extent such circumvention
+is effected by exercising rights under this License with respect to
+the covered work, and you disclaim any intention to limit operation or
+modification of the work as a means of enforcing, against the work's
+users, your or third parties' legal rights to forbid circumvention of
+technological measures.
+
+  4. Conveying Verbatim Copies.
+
+  You may convey verbatim copies of the Program's source code as you
+receive it, in any medium, provided that you conspicuously and
+appropriately publish on each copy an appropriate copyright notice;
+keep intact all notices stating that this License and any
+non-permissive terms added in accord with section 7 apply to the code;
+keep intact all notices of the absence of any warranty; and give all
+recipients a copy of this License along with the Program.
+
+  You may charge any price or no price for each copy that you convey,
+and you may offer support or warranty protection for a fee.
+
+  5. Conveying Modified Source Versions.
+
+  You may convey a work based on the Program, or the modifications to
+produce it from the Program, in the form of source code under the
+terms of section 4, provided that you also meet all of these conditions:
+
+    a) The work must carry prominent notices stating that you modified
+    it, and giving a relevant date.
+
+    b) The work must carry prominent notices stating that it is
+    released under this License and any conditions added under section
+    7.  This requirement modifies the requirement in section 4 to
+    "keep intact all notices".
+
+    c) You must license the entire work, as a whole, under this
+    License to anyone who comes into possession of a copy.  This
+    License will therefore apply, along with any applicable section 7
+    additional terms, to the whole of the work, and all its parts,
+    regardless of how they are packaged.  This License gives no
+    permission to license the work in any other way, but it does not
+    invalidate such permission if you have separately received it.
+
+    d) If the work has interactive user interfaces, each must display
+    Appropriate Legal Notices; however, if the Program has interactive
+    interfaces that do not display Appropriate Legal Notices, your
+    work need not make them do so.
+
+  A compilation of a covered work with other separate and independent
+works, which are not by their nature extensions of the covered work,
+and which are not combined with it such as to form a larger program,
+in or on a volume of a storage or distribution medium, is called an
+"aggregate" if the compilation and its resulting copyright are not
+used to limit the access or legal rights of the compilation's users
+beyond what the individual works permit.  Inclusion of a covered work
+in an aggregate does not cause this License to apply to the other
+parts of the aggregate.
+
+  6. Conveying Non-Source Forms.
+
+  You may convey a covered work in object code form under the terms
+of sections 4 and 5, provided that you also convey the
+machine-readable Corresponding Source under the terms of this License,
+in one of these ways:
+
+    a) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by the
+    Corresponding Source fixed on a durable physical medium
+    customarily used for software interchange.
+
+    b) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by a
+    written offer, valid for at least three years and valid for as
+    long as you offer spare parts or customer support for that product
+    model, to give anyone who possesses the object code either (1) a
+    copy of the Corresponding Source for all the software in the
+    product that is covered by this License, on a durable physical
+    medium customarily used for software interchange, for a price no
+    more than your reasonable cost of physically performing this
+    conveying of source, or (2) access to copy the
+    Corresponding Source from a network server at no charge.
+
+    c) Convey individual copies of the object code with a copy of the
+    written offer to provide the Corresponding Source.  This
+    alternative is allowed only occasionally and noncommercially, and
+    only if you received the object code with such an offer, in accord
+    with subsection 6b.
+
+    d) Convey the object code by offering access from a designated
+    place (gratis or for a charge), and offer equivalent access to the
+    Corresponding Source in the same way through the same place at no
+    further charge.  You need not require recipients to copy the
+    Corresponding Source along with the object code.  If the place to
+    copy the object code is a network server, the Corresponding Source
+    may be on a different server (operated by you or a third party)
+    that supports equivalent copying facilities, provided you maintain
+    clear directions next to the object code saying where to find the
+    Corresponding Source.  Regardless of what server hosts the
+    Corresponding Source, you remain obligated to ensure that it is
+    available for as long as needed to satisfy these requirements.
+
+    e) Convey the object code using peer-to-peer transmission, provided
+    you inform other peers where the object code and Corresponding
+    Source of the work are being offered to the general public at no
+    charge under subsection 6d.
+
+  A separable portion of the object code, whose source code is excluded
+from the Corresponding Source as a System Library, need not be
+included in conveying the object code work.
+
+  A "User Product" is either (1) a "consumer product", which means any
+tangible personal property which is normally used for personal, family,
+or household purposes, or (2) anything designed or sold for incorporation
+into a dwelling.  In determining whether a product is a consumer product,
+doubtful cases shall be resolved in favor of coverage.  For a particular
+product received by a particular user, "normally used" refers to a
+typical or common use of that class of product, regardless of the status
+of the particular user or of the way in which the particular user
+actually uses, or expects or is expected to use, the product.  A product
+is a consumer product regardless of whether the product has substantial
+commercial, industrial or non-consumer uses, unless such uses represent
+the only significant mode of use of the product.
+
+  "Installation Information" for a User Product means any methods,
+procedures, authorization keys, or other information required to install
+and execute modified versions of a covered work in that User Product from
+a modified version of its Corresponding Source.  The information must
+suffice to ensure that the continued functioning of the modified object
+code is in no case prevented or interfered with solely because
+modification has been made.
+
+  If you convey an object code work under this section in, or with, or
+specifically for use in, a User Product, and the conveying occurs as
+part of a transaction in which the right of possession and use of the
+User Product is transferred to the recipient in perpetuity or for a
+fixed term (regardless of how the transaction is characterized), the
+Corresponding Source conveyed under this section must be accompanied
+by the Installation Information.  But this requirement does not apply
+if neither you nor any third party retains the ability to install
+modified object code on the User Product (for example, the work has
+been installed in ROM).
+
+  The requirement to provide Installation Information does not include a
+requirement to continue to provide support service, warranty, or updates
+for a work that has been modified or installed by the recipient, or for
+the User Product in which it has been modified or installed.  Access to a
+network may be denied when the modification itself materially and
+adversely affects the operation of the network or violates the rules and
+protocols for communication across the network.
+
+  Corresponding Source conveyed, and Installation Information provided,
+in accord with this section must be in a format that is publicly
+documented (and with an implementation available to the public in
+source code form), and must require no special password or key for
+unpacking, reading or copying.
+
+  7. Additional Terms.
+
+  "Additional permissions" are terms that supplement the terms of this
+License by making exceptions from one or more of its conditions.
+Additional permissions that are applicable to the entire Program shall
+be treated as though they were included in this License, to the extent
+that they are valid under applicable law.  If additional permissions
+apply only to part of the Program, that part may be used separately
+under those permissions, but the entire Program remains governed by
+this License without regard to the additional permissions.
+
+  When you convey a copy of a covered work, you may at your option
+remove any additional permissions from that copy, or from any part of
+it.  (Additional permissions may be written to require their own
+removal in certain cases when you modify the work.)  You may place
+additional permissions on material, added by you to a covered work,
+for which you have or can give appropriate copyright permission.
+
+  Notwithstanding any other provision of this License, for material you
+add to a covered work, you may (if authorized by the copyright holders of
+that material) supplement the terms of this License with terms:
+
+    a) Disclaiming warranty or limiting liability differently from the
+    terms of sections 15 and 16 of this License; or
+
+    b) Requiring preservation of specified reasonable legal notices or
+    author attributions in that material or in the Appropriate Legal
+    Notices displayed by works containing it; or
+
+    c) Prohibiting misrepresentation of the origin of that material, or
+    requiring that modified versions of such material be marked in
+    reasonable ways as different from the original version; or
+
+    d) Limiting the use for publicity purposes of names of licensors or
+    authors of the material; or
+
+    e) Declining to grant rights under trademark law for use of some
+    trade names, trademarks, or service marks; or
+
+    f) Requiring indemnification of licensors and authors of that
+    material by anyone who conveys the material (or modified versions of
+    it) with contractual assumptions of liability to the recipient, for
+    any liability that these contractual assumptions directly impose on
+    those licensors and authors.
+
+  All other non-permissive additional terms are considered "further
+restrictions" within the meaning of section 10.  If the Program as you
+received it, or any part of it, contains a notice stating that it is
+governed by this License along with a term that is a further
+restriction, you may remove that term.  If a license document contains
+a further restriction but permits relicensing or conveying under this
+License, you may add to a covered work material governed by the terms
+of that license document, provided that the further restriction does
+not survive such relicensing or conveying.
+
+  If you add terms to a covered work in accord with this section, you
+must place, in the relevant source files, a statement of the
+additional terms that apply to those files, or a notice indicating
+where to find the applicable terms.
+
+  Additional terms, permissive or non-permissive, may be stated in the
+form of a separately written license, or stated as exceptions;
+the above requirements apply either way.
+
+  8. Termination.
+
+  You may not propagate or modify a covered work except as expressly
+provided under this License.  Any attempt otherwise to propagate or
+modify it is void, and will automatically terminate your rights under
+this License (including any patent licenses granted under the third
+paragraph of section 11).
+
+  However, if you cease all violation of this License, then your
+license from a particular copyright holder is reinstated (a)
+provisionally, unless and until the copyright holder explicitly and
+finally terminates your license, and (b) permanently, if the copyright
+holder fails to notify you of the violation by some reasonable means
+prior to 60 days after the cessation.
+
+  Moreover, your license from a particular copyright holder is
+reinstated permanently if the copyright holder notifies you of the
+violation by some reasonable means, this is the first time you have
+received notice of violation of this License (for any work) from that
+copyright holder, and you cure the violation prior to 30 days after
+your receipt of the notice.
+
+  Termination of your rights under this section does not terminate the
+licenses of parties who have received copies or rights from you under
+this License.  If your rights have been terminated and not permanently
+reinstated, you do not qualify to receive new licenses for the same
+material under section 10.
+
+  9. Acceptance Not Required for Having Copies.
+
+  You are not required to accept this License in order to receive or
+run a copy of the Program.  Ancillary propagation of a covered work
+occurring solely as a consequence of using peer-to-peer transmission
+to receive a copy likewise does not require acceptance.  However,
+nothing other than this License grants you permission to propagate or
+modify any covered work.  These actions infringe copyright if you do
+not accept this License.  Therefore, by modifying or propagating a
+covered work, you indicate your acceptance of this License to do so.
+
+  10. Automatic Licensing of Downstream Recipients.
+
+  Each time you convey a covered work, the recipient automatically
+receives a license from the original licensors, to run, modify and
+propagate that work, subject to this License.  You are not responsible
+for enforcing compliance by third parties with this License.
+
+  An "entity transaction" is a transaction transferring control of an
+organization, or substantially all assets of one, or subdividing an
+organization, or merging organizations.  If propagation of a covered
+work results from an entity transaction, each party to that
+transaction who receives a copy of the work also receives whatever
+licenses to the work the party's predecessor in interest had or could
+give under the previous paragraph, plus a right to possession of the
+Corresponding Source of the work from the predecessor in interest, if
+the predecessor has it or can get it with reasonable efforts.
+
+  You may not impose any further restrictions on the exercise of the
+rights granted or affirmed under this License.  For example, you may
+not impose a license fee, royalty, or other charge for exercise of
+rights granted under this License, and you may not initiate litigation
+(including a cross-claim or counterclaim in a lawsuit) alleging that
+any patent claim is infringed by making, using, selling, offering for
+sale, or importing the Program or any portion of it.
+
+  11. Patents.
+
+  A "contributor" is a copyright holder who authorizes use under this
+License of the Program or a work on which the Program is based.  The
+work thus licensed is called the contributor's "contributor version".
+
+  A contributor's "essential patent claims" are all patent claims
+owned or controlled by the contributor, whether already acquired or
+hereafter acquired, that would be infringed by some manner, permitted
+by this License, of making, using, or selling its contributor version,
+but do not include claims that would be infringed only as a
+consequence of further modification of the contributor version.  For
+purposes of this definition, "control" includes the right to grant
+patent sublicenses in a manner consistent with the requirements of
+this License.
+
+  Each contributor grants you a non-exclusive, worldwide, royalty-free
+patent license under the contributor's essential patent claims, to
+make, use, sell, offer for sale, import and otherwise run, modify and
+propagate the contents of its contributor version.
+
+  In the following three paragraphs, a "patent license" is any express
+agreement or commitment, however denominated, not to enforce a patent
+(such as an express permission to practice a patent or covenant not to
+sue for patent infringement).  To "grant" such a patent license to a
+party means to make such an agreement or commitment not to enforce a
+patent against the party.
+
+  If you convey a covered work, knowingly relying on a patent license,
+and the Corresponding Source of the work is not available for anyone
+to copy, free of charge and under the terms of this License, through a
+publicly available network server or other readily accessible means,
+then you must either (1) cause the Corresponding Source to be so
+available, or (2) arrange to deprive yourself of the benefit of the
+patent license for this particular work, or (3) arrange, in a manner
+consistent with the requirements of this License, to extend the patent
+license to downstream recipients.  "Knowingly relying" means you have
+actual knowledge that, but for the patent license, your conveying the
+covered work in a country, or your recipient's use of the covered work
+in a country, would infringe one or more identifiable patents in that
+country that you have reason to believe are valid.
+
+  If, pursuant to or in connection with a single transaction or
+arrangement, you convey, or propagate by procuring conveyance of, a
+covered work, and grant a patent license to some of the parties
+receiving the covered work authorizing them to use, propagate, modify
+or convey a specific copy of the covered work, then the patent license
+you grant is automatically extended to all recipients of the covered
+work and works based on it.
+
+  A patent license is "discriminatory" if it does not include within
+the scope of its coverage, prohibits the exercise of, or is
+conditioned on the non-exercise of one or more of the rights that are
+specifically granted under this License.  You may not convey a covered
+work if you are a party to an arrangement with a third party that is
+in the business of distributing software, under which you make payment
+to the third party based on the extent of your activity of conveying
+the work, and under which the third party grants, to any of the
+parties who would receive the covered work from you, a discriminatory
+patent license (a) in connection with copies of the covered work
+conveyed by you (or copies made from those copies), or (b) primarily
+for and in connection with specific products or compilations that
+contain the covered work, unless you entered into that arrangement,
+or that patent license was granted, prior to 28 March 2007.
+
+  Nothing in this License shall be construed as excluding or limiting
+any implied license or other defenses to infringement that may
+otherwise be available to you under applicable patent law.
+
+  12. No Surrender of Others' Freedom.
+
+  If conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License.  If you cannot convey a
+covered work so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you may
+not convey it at all.  For example, if you agree to terms that obligate you
+to collect a royalty for further conveying from those to whom you convey
+the Program, the only way you could satisfy both those terms and this
+License would be to refrain entirely from conveying the Program.
+
+  13. Use with the GNU Affero General Public License.
+
+  Notwithstanding any other provision of this License, you have
+permission to link or combine any covered work with a work licensed
+under version 3 of the GNU Affero General Public License into a single
+combined work, and to convey the resulting work.  The terms of this
+License will continue to apply to the part which is the covered work,
+but the special requirements of the GNU Affero General Public License,
+section 13, concerning interaction through a network will apply to the
+combination as such.
+
+  14. Revised Versions of this License.
+
+  The Free Software Foundation may publish revised and/or new versions of
+the GNU General Public License from time to time.  Such new versions will
+be similar in spirit to the present version, but may differ in detail to
+address new problems or concerns.
+
+  Each version is given a distinguishing version number.  If the
+Program specifies that a certain numbered version of the GNU General
+Public License "or any later version" applies to it, you have the
+option of following the terms and conditions either of that numbered
+version or of any later version published by the Free Software
+Foundation.  If the Program does not specify a version number of the
+GNU General Public License, you may choose any version ever published
+by the Free Software Foundation.
+
+  If the Program specifies that a proxy can decide which future
+versions of the GNU General Public License can be used, that proxy's
+public statement of acceptance of a version permanently authorizes you
+to choose that version for the Program.
+
+  Later license versions may give you additional or different
+permissions.  However, no additional obligations are imposed on any
+author or copyright holder as a result of your choosing to follow a
+later version.
+
+  15. Disclaimer of Warranty.
+
+  THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
+APPLICABLE LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
+HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
+OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
+THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
+IS WITH YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
+ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
+
+  16. Limitation of Liability.
+
+  IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
+THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
+GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
+USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
+DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
+PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
+EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
+SUCH DAMAGES.
+
+  17. Interpretation of Sections 15 and 16.
+
+  If the disclaimer of warranty and limitation of liability provided
+above cannot be given local legal effect according to their terms,
+reviewing courts shall apply local law that most closely approximates
+an absolute waiver of all civil liability in connection with the
+Program, unless a warranty or assumption of liability accompanies a
+copy of the Program in return for a fee.
+
+                     END OF TERMS AND CONDITIONS
+
+            How to Apply These Terms to Your New Programs
+
+  If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these terms.
+
+  To do so, attach the following notices to the program.  It is safest
+to attach them to the start of each source file to most effectively
+state the exclusion of warranty; and each file should have at least
+the "copyright" line and a pointer to where the full notice is found.
+
+    <one line to give the program's name and a brief idea of what it does.>
+    Copyright (C) <year>  <name of author>
+
+    This program is free software: you can redistribute it and/or modify
+    it under the terms of the GNU General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU General Public License for more details.
+
+    You should have received a copy of the GNU General Public License
+    along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+Also add information on how to contact you by electronic and paper mail.
+
+  If the program does terminal interaction, make it output a short
+notice like this when it starts in an interactive mode:
+
+    <program>  Copyright (C) <year>  <name of author>
+    This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
+    This is free software, and you are welcome to redistribute it
+    under certain conditions; type `show c' for details.
+
+The hypothetical commands `show w' and `show c' should show the appropriate
+parts of the General Public License.  Of course, your program's commands
+might be different; for a GUI interface, you would use an "about box".
+
+  You should also get your employer (if you work as a programmer) or school,
+if any, to sign a "copyright disclaimer" for the program, if necessary.
+For more information on this, and how to apply and follow the GNU GPL, see
+<https://www.gnu.org/licenses/>.
+
+  The GNU General Public License does not permit incorporating your program
+into proprietary programs.  If your program is a subroutine library, you
+may consider it more useful to permit linking proprietary applications with
+the library.  If this is what you want to do, use the GNU Lesser General
+Public License instead of this License.  But first, please read
+<https://www.gnu.org/licenses/why-not-lgpl.html>.

README.md

@@ -38,3 +38,21 @@ link/      docs from the ServUO bridge (C# plugin + Rust sidecar + Node WS)
 Commit history and authorship for each doc are preserved. The two source repos
 retain a short pointer to this repo in their own READMEs; the authoritative copy
 of each document now lives here.
+
+---
+
+## License
+
+Runic Gateway's documentation is free: licensed under the **GNU General Public
+License v3.0 or later** — see [LICENSE.md](LICENSE.md).
+
+    Copyright (C) 2026 Runic Gateway
+
+    This documentation is distributed in the hope that it will be useful, but
+    WITHOUT ANY WARRANTY. You may redistribute and/or modify it under the terms of
+    the GNU General Public License as published by the Free Software Foundation,
+    either version 3 of the License, or (at your option) any later version.
+
+Contributions are welcome — please read [CONTRIBUTING.md](CONTRIBUTING.md) (note
+the **AI-usage disclosure** requirement) and our
+[Code of Conduct](CODE_OF_CONDUCT.md).

SECURITY.md

@@ -0,0 +1,50 @@
+# Security Policy
+
+Thank you for helping keep Runic Gateway and its users safe.
+
+## Reporting a vulnerability
+
+**Please do not report security vulnerabilities through public issues, pull
+requests, or the wiki.** A public report tips off attackers before a fix is
+available.
+
+Instead, report privately by email to:
+
+**whitlocktech@gmail.com**
+
+Please include as much of the following as you can:
+
+- The repository and component affected.
+- The type of issue (e.g. authentication bypass, injection, secret exposure,
+  remote code execution, denial of service).
+- Step-by-step instructions to reproduce, and a proof-of-concept if you have one.
+- The impact — what an attacker could do with it.
+- Any suggested remediation.
+
+You will receive an acknowledgement of your report, typically within a few days.
+We will keep you informed as we investigate and work toward a fix, and we are
+happy to credit you in the release notes once the issue is resolved (let us know
+if you would prefer to remain anonymous).
+
+## Scope
+
+Runic Gateway is a self-hosted platform made up of several components:
+
+| Component | Repo | Network exposure |
+|---|---|---|
+| Website (site + admin + API) | `RunicGateway/website` | Internet-facing (behind a reverse proxy) |
+| uo-link sidecar | `RunicGateway/link` | The only network-facing part of the game bridge |
+| ServUO plugin | `RunicGateway/servuo-plugins` | Loopback only — dials the sidecar on `127.0.0.1` |
+| Documentation | `RunicGateway/docs` | Content only |
+
+Because instances are self-hosted, the security of any given deployment also
+depends on how it is configured and operated — strong secrets (`JWT_SECRET`,
+`SECRET_ENC_KEY`, database and admin passwords), a correctly configured reverse
+proxy and `TRUST_PROXY`, and keeping the shard itself unreachable from the
+internet (only the sidecar should be exposed). See each repo's README for the
+security model.
+
+## Supported versions
+
+This project is developed continuously and does not maintain long-term release
+branches. Security fixes land on `main`; please run a recent build.

android/APP_LINKS.md

@@ -0,0 +1,196 @@
+# Android App Links — implementation spec
+
+Status: **implementation spec (M9 follow-up).** Stacks on the native SSO bridge (M9 Part 2):
+the app already handles the **custom-scheme** callback `runicgateway://auth/callback`, and that stays
+the permanent default and universal fallback. App Links are an **opt-in hardening** layered on top —
+a verified `https://` callback that only the domain's real owner can claim.
+
+Read alongside: the "Mobile SSO Authorization Bridge" section of
+[`../website/BACKEND_DESIGN.md`](../website/BACKEND_DESIGN.md) (endpoints/tables/allowlist), and
+[`PLAN.md`](./PLAN.md) §4.2 / §9 (the app milestone). This spec matches what ships on the
+`feat/mobile-app-links` (website) and `feat/app-links` (android) branches.
+
+---
+
+## 1. The problem it solves
+
+The mobile SSO bridge redirects the browser back to the app with a one-time code:
+
+```
+runicgateway://auth/callback?code=…&state=…
+```
+
+A **custom URI scheme** is fine for a self-hosted internal client, but it is not *owned* by anyone:
+any other Android app can register an intent-filter for `runicgateway://auth/callback` and, if chosen
+by the user, intercept the callback. The code is single-use, PKCE-bound (Layer B), and short-lived —
+so an interceptor still cannot complete `/exchange` without the app's `code_verifier` — but a hijacked
+callback is still a denial-of-service and a phishing surface we would rather close.
+
+**Android App Links** (verified `https://` deep links) close it: the OS only routes an `https://`
+link to an app that has proven, via a file served from *that domain*, that it owns the app. An
+attacker cannot serve that file on a domain they do not control.
+
+## 2. Why this is harder here than in a normal app
+
+RunicGateway is **self-hosted per shard**. There is no single canonical domain — every shard owner
+runs the website on **their own** domain (`play.exampleshard.com`, `uo.anothershard.net`, …). App
+Links verification is **per-domain**: the domain must serve
+
+```
+https://<shard-domain>/.well-known/assetlinks.json
+```
+
+asserting the Android app's **package name** + **signing-certificate SHA-256 fingerprint**.
+
+That is only half the problem. The other half is an Android platform constraint that decides the whole
+shape of the app side:
+
+> **`android:autoVerify` needs a *literal* host at build time.** An intent-filter's `<data android:host>`
+> is a static string in the merged manifest; there is no "any host" or runtime host. A **single
+> published multi-tenant APK therefore cannot autoVerify an open-ended set of shard domains** — the set
+> is not known when the APK is built.
+
+So App Links here are **not** a drop-in replacement for the custom scheme. They split into two pieces
+that ship independently:
+
+1. **Server (`assetlinks.json`) — shippable now, benefits any App-Links-capable build.** Every shard
+   can auto-serve its Digital Asset Links statement behind an admin toggle. This is a pure add and is
+   implemented on `feat/mobile-app-links`.
+2. **App (`autoVerify` intent-filter) — a *build-time* opt-in.** Because the host must be baked in,
+   App Links are available to:
+   - a **white-label / first-party build** that bakes one shard's host (`-PappLinkHost=play.myshard.com`);
+   - a future **canonical relay domain** (`runicgateway.app`, PLAN §14 — *not yet secured*) that all
+     shards could bounce their final callback through, autoVerified by the generic build.
+
+   The **generic multi-tenant build bakes no host and stays custom-scheme-only** — correct and safe.
+
+The custom scheme is never removed. It is the fallback on every build, for every shard, always.
+
+## 3. Server design — `feat/mobile-app-links`
+
+### 3.1 Auto-served `assetlinks.json`
+
+- **Route:** `GET /.well-known/assetlinks.json`, served at the **web root** (outside `/api/v1`, before
+  the SPA catch-all) in `server/src/app.js`.
+- **Gate:** the admin setting `mobile_app_links_enabled` (default **off**). Off ⇒ the route **404s** and
+  the app stays on the custom scheme for that shard. On ⇒ the shard opts into App Links.
+- **Body:** the Digital Asset Links statement for the fixed package `com.runicgateway.app` and the
+  release signing cert SHA-256 fingerprint(s):
+
+  ```json
+  [
+    {
+      "relation": ["delegate_permission/common.handle_all_urls"],
+      "target": {
+        "namespace": "android_app",
+        "package_name": "com.runicgateway.app",
+        "sha256_cert_fingerprints": ["AB:CD:…"]
+      }
+    }
+  ]
+  ```
+
+- **Fingerprint source:** env `MOBILE_APP_CERT_SHA256` — comma-separated (supports **cert rotation** and
+  a debug + release cert during testing). It is a **constant of the published app**, identical for every
+  shard, so it is a shipped/env default, not something each owner types. The package name is likewise
+  fixed (`MOBILE_APP_PACKAGE`, default `com.runicgateway.app`).
+- **Enabled but no fingerprint configured ⇒ 404** (+ a one-time warn): serving a statement with no
+  fingerprint asserts nothing and would only mislead the verifier.
+- Response is `application/json`, `Cache-Control: public, max-age=3600` (the Play verifier and the OS
+  re-fetch it; it changes only on a cert rotation).
+
+### 3.2 Redirect-URI allowlist extension
+
+`mobileSso.controller` validates the app's `redirect_uri` by **exact match** against
+`MOBILE_AUTH_REDIRECT_URIS` (default `runicgateway://auth/callback`). App Links add exactly one more
+acceptable value, and **only when the toggle is on**:
+
+- When `mobile_app_links_enabled`, `/start` additionally accepts the **self-origin** HTTPS callback
+  `https://<request-host>/mobile/callback` (derived from the request/`APP_BASE_URL`, never from
+  attacker-controlled input). Still **exact match** — never a prefix match.
+- The static custom-scheme allowlist is never narrowed; the HTTPS entry is *additive*.
+- No new table or schema: the check reads the one boolean setting.
+
+### 3.3 Public settings advertise the capability
+
+`settings.getPublic()` gains `mobileAppLinks: <bool>` (mirrors the toggle) so a client can tell whether
+a shard opted in before requesting an HTTPS `redirect_uri` (a white-label build uses it to avoid asking
+for a callback the server would reject).
+
+## 4. App design — `feat/app-links`
+
+### 4.1 Build-time host (`appLinkHost`)
+
+- Gradle property `appLinkHost` (default empty). Wired in `app/build.gradle.kts` into **both**:
+  - `BuildConfig.APP_LINK_HOST` — read by `SsoAuthManager` to decide the redirect;
+  - `manifestPlaceholders["appLinkHost"]` — substituted into the App Link intent-filter's host.
+- **Default (generic build):** empty ⇒ `BuildConfig.APP_LINK_HOST = ""` and the placeholder falls back
+  to the reserved sentinel `runic-gateway.invalid` (RFC 6761 — never resolves), so the `autoVerify`
+  filter is **inert**: it matches no real link and verification simply never succeeds. No custom-scheme
+  behaviour changes.
+- **White-label build:** `./gradlew assembleRelease -PappLinkHost=play.myshard.com` bakes that one host
+  into the filter and enables the HTTPS redirect for that host.
+
+### 4.2 Manifest
+
+A second intent-filter on `MainActivity`, alongside the unchanged custom-scheme one:
+
+```xml
+<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>
+```
+
+### 4.3 `SsoAuthManager` (pure Kotlin, unit-tested on the JVM)
+
+- **Redirect selection in `buildStartUrl`:** request the HTTPS `redirect_uri`
+  `https://<pairedHost>/mobile/callback` **iff** `BuildConfig.APP_LINK_HOST` is non-blank *and* equals
+  the paired base-URL host (case-insensitive); otherwise the fixed custom-scheme `REDIRECT_URI`. A
+  white-label build that bakes the host is responsible for enabling the server toggle too (§3.2).
+- **Verified-callback matcher + host-trust check:** a new `matchesAppLinkCallback(scheme, host, path)`
+  accepts only `scheme == https`, `path == /mobile/callback`, and **`host == the paired base-URL host`**.
+  The paired-host equality is defense-in-depth: even though `autoVerify` already means only a real,
+  opted-in shard domain can route here, the app still refuses any HTTPS callback whose host isn't the
+  shard it is currently paired to.
+- The rest is unchanged: both matchers feed the *same* `complete(state, code, error)` → `/exchange` →
+  `SessionManager.onSignedIn`. There is no second auth path.
+
+### 4.4 `MainActivity`
+
+`handleSsoCallback` routes a VIEW intent through **`matchesCallback(...) || matchesAppLinkCallback(...)`**;
+everything downstream (state check, exchange, sign-in) is shared. Custom-scheme and App Link callbacks
+are indistinguishable past the edge.
+
+## 5. Turning it on for a shard
+
+1. Publish/point the app build at the shard host (`-PappLinkHost=<host>`) — or use the generic build and
+   leave App Links off.
+2. Set `MOBILE_APP_CERT_SHA256` (release cert fingerprint) in the website env.
+3. Admin → Shard/Settings: enable **App Links** (`mobile_app_links_enabled`).
+4. Verify `https://<host>/.well-known/assetlinks.json` returns the statement; confirm Android verifies
+   (`adb shell pm get-app-links com.runicgateway.app`).
+
+If any step is skipped the app transparently keeps using the custom scheme — nothing breaks.
+
+## 6. Testing
+
+- **Server (`node --test`):** route 404s when the toggle is off; 404s when on but no fingerprint;
+  returns the correct statement + content-type when on and configured; the redirect allowlist accepts
+  `https://<host>/mobile/callback` only when enabled and rejects it otherwise (custom scheme always
+  accepted).
+- **App (JVM unit tests):** `matchesAppLinkCallback` accepts only https + `/mobile/callback` + the paired
+  host and rejects a foreign host / http / wrong path; `buildStartUrl` requests the HTTPS redirect only
+  when the baked host matches the paired host, else the custom scheme.
+
+## 7. What does *not* change
+
+- The bridge's server design (PKCE Layer A/B, single-use codes, `/start` + `/exchange`) is untouched;
+  App Links are *one more allowlist entry* + *one static file route*. That is the whole point of keeping
+  the allowlist exact-match and configurable from day one.
+- The custom scheme remains on every build and is the permanent fallback.
+- No change to `servuo-plugins/` — App Links are entirely a website ↔ app concern.

android/PLAN.md

@@ -0,0 +1,940 @@
+# Android App — Plan
+
+Status: **M0–M7 landed; M7 (push notifications) both parts done — Part 1 backend (website#78) and Part 2 app (Android-app#15) plus a small `push.ntfyUrl` settings addition (website#79). Remaining: set the shard's `NTFY_*` deploy config so push lights up, and cut the v1 tag. M9 (native SSO login) is now underway backend-first — the Mobile SSO Authorization Bridge is being built in `website/` + `docs/` ahead of the app-side client (§4.2, §9 M9); custom-scheme callback only for now, App Links deferred (see [`APP_LINKS.md`](./APP_LINKS.md)).** This document is the
+design contract for the `RunicGateway/Android-app` repo. It was written before implementation so the
+API changes it depends on could be landed in `website/` and `docs/` first. The authoritative API
+reference is the committed OpenAPI spec at `website/server/swagger/swagger-output.json` (regenerated
+via `npm run swagger`).
+
+**Build progress (§9):** ✅ **M0 — repo scaffold** (2026-07-19, `RunicGateway/Android-app#2`):
+Gradle 8.7 wrapper + AGP 8.6.1 / Kotlin 2.0.20, JDK 17, minSdk 29 / compile-target 35,
+`applicationId com.runicgateway.app`; a version catalog pinning the full §2 stack; a Compose + Hilt
+single-activity skeleton (externalized strings, adaptive icon); and CI (`pr-checks.yml` →
+`./gradlew lint test assembleDebug`).
+
+✅ **M1 — connect & browse** (2026-07-19, `RunicGateway/Android-app#6`, functional Kotlin pass): the
+first-run base-URL connect flow (probe `GET /public/status`, verify the backend's version identity,
+persist to DataStore; HTTPS-only in release, HTTP allowed in debug; Settings → Server hard reset);
+a runtime-selected base URL via a sentinel-host Retrofit + `HostSelectionInterceptor` (the host is
+**not** compiled in) plus a `UserAgentInterceptor` past the scanner guard (§8); the layered
+`screen → ViewModel → repository → PublicApi → DTO` stack returning a typed `ApiResult`
+(`Ok`/`HttpError`/`NetworkError`) for graceful degradation (§7); brand-seeded Material 3 theming from
+`/public/settings`; and functional Compose screens for Home/Status, News (+ post detail), Wiki
+(+ detail), CMS pages (block renderer: `heading/rich_text/image/quote/cta/divider/two_column`), and
+the contact form, under one declarative navigation drawer (§5). JVM unit tests cover URL
+normalization, host rewriting, `ApiResult`/`UiState` mapping, and brand-color parsing.
+
+> **API-client deviation from §2 (recorded):** DTOs + the Retrofit interface are **hand-written and
+> spec-aligned**, not `openapi-generator` output. The committed `swagger-output.json` is produced by
+> **swagger-autogen**, whose component schemas are meta-descriptive (nested `{type, example}`
+> wrappers) rather than codegen-clean OpenAPI models, so a generator would emit unusable DTOs. The
+> hand-authored client is the "checked-in generated module" §2 already allows; shapes were matched
+> against the website controllers/models and every DTO ignores unknown keys (additive fields are
+> safe). True codegen would first require authoring the spec's component schemas as real OpenAPI
+> models.
+
+✅ **M2 — public shard** (2026-07-19, `RunicGateway/Android-app#7`, functional Kotlin pass): the public
+shard widgets (§6.2) over `/public/shard/*` — a shard hub (connection status, online count, latest
+economy, presence, staff online) plus live boards for champion spawns, guilds, governors (with
+on-demand term history) and falling houses (IDOC) — and the live **SSE** feed. `ShardStreamClient`
+consumes `/public/shard/stream` over OkHttp SSE and, unlike the browser `EventSource`, drives its own
+reconnect/backoff (reset on open, no read timeout for the idle keepalive), so a dropped feed degrades
+to "offline" rather than crashing (§7). Boards seed from a snapshot then merge `*.update` / `*.remove`
+SSE deltas in place via a reusable `LiveBoard`, mirroring the website's merge semantics; DTOs are
+hand-authored + spec-aligned (as recorded for M1) and the live frames decode into the same board
+DTOs. Wired into the shared drawer (§5), all strings externalized (§2). JVM unit tests (28) cover DTO
+/ live-frame decode, the board merge, event-text formatting (parity with `lib/shardEvents.js`), and
+SSE frame parsing. No backend/API change — the app is a pure consumer of the existing public shard
+surface.
+
+✅ **M3 — auth** (2026-07-19, `RunicGateway/Android-app#8`, functional Kotlin pass): native
+**username/password (+ single-request TOTP) login** over the existing `POST /auth/mobile/login` — a
+`401 { totpRequired }` reveals the code field and a wrong code re-lands as a code error; `429` surfaces
+a friendly backoff message (§4.1). The token pair lives in **EncryptedSharedPreferences** (a
+`TokenStore` behind `SessionManager`, the single source of truth for the in-memory bearer + the
+observable `Session`); the base URL stays in plain DataStore (§4.3). An OkHttp `AuthInterceptor`
+attaches the bearer and a `TokenAuthenticator` does a **one-shot, mutex-serialized refresh** on a
+bearer `401` and replays the request — refresh runs on its own **bare** client (no interceptor/
+authenticator) so it can never recurse, rotated single-use tokens are stored atomically, and a dead
+refresh (`401`) signs out while a transient network error keeps the session. Logout
+(`POST /auth/mobile/logout`, this session or all devices) tears down locally even if the call fails.
+`GET /auth/me` **re-validates the role on every resume** (`LifecycleResumeEffect`); a surviving `401`
+signs out, so a server-side demotion drops menu access promptly (role stays advisory — the backend is
+authority, §4.3). The **access-level menu** is one declarative list (`visibleEntries` filters by
+session — public / signed-in / player) with a Sign in / Sign out toggle and a **My Account** screen
+(identity + role + sign-out / sign-out-everywhere). Registration, forgot-password, and SSO are
+**Custom-Tab hand-offs** (androidx.browser) to the website's own pages (`/account/register`,
+`/account/forgot`, `/account/login`) — no native screens (§4.2). The Settings → Server switch now also
+clears the stored session (§3). JVM unit tests (18) cover auth-DTO decode (incl. `totpRequired` vs a
+plain credential `401`), the `SessionManager` lifecycle over a fake store, and the menu access filter
++ role mapping. **No backend/API change** — the app is a pure consumer of the existing mobile bearer +
+`/auth/me` surface.
+
+> **Biometric app-lock — descoped from v1 (decided at M6).** §4.3/§9 flagged an *optional* biometric
+> app-lock, deferred from M3 to M6. At M6 it was **descoped from v1 entirely**: tokens are already
+> encrypted at rest (Tink/AES-256-GCM), so an app-lock is a pure UX convenience, not a security
+> requirement, and it changes no data flow. It is **not** in the first release; revisit only if it
+> becomes a requested feature.
+
+✅ **M4 — player self-service & game data** (2026-07-19, `RunicGateway/Android-app#9`, functional Kotlin
+pass): the signed-in player surface, all as a pure consumer of the existing bearer-gated API.
+**Account self-service** over the role-agnostic `/auth/me/account*` (§6.4) — change username (409
+"taken" surfaced; a success re-validates the session so the shell reflects the new name at once),
+change/set password (the SSO-account "no current password" path from `has_password`), TOTP
+**setup → scan → enable** (the `data:` QR is base64-decoded to a bitmap in-app) / disable-by-code, and
+list/unlink SSO identities — each mutation folding its `ApiResult` into a section-scoped, localized
+banner (§7). **Game-account linking** (§6.3) — the in-game `[link` one-time code (`POST
+/player/shard/link`) plus the hybrid signup (`POST /player/shard/account`, shown only when the public
+`gameAccountSignup` flag is set), and the linked-accounts list. **Own game data**, text-only (§6.3):
+per-account character roster → a character sheet (attributes, vitals, resistances, best-first skills,
+equipment with AOS mods, and guild/governor standing chips — bare cliloc-number titles/item names are
+skipped, as the app ships no cliloc table, matching the website's `CharacterSheet.jsx`); player
+vendors (shops + listings) with recent sales; and the player's own houses (decay/IDOC). Each
+per-account read carries its **own** load state, so a down shard degrades that one account to
+offline/retry (`503`) — or not-found (`403`) — without blocking the rest. The menu gains three
+**PLAYER-access** groups (My Characters / Vendors / Houses) revealed only when the session role is
+`player`; a `PlayerGate` sends a signed-out or server-side-demoted user home. DTOs are hand-authored +
+spec-aligned (as recorded for M1); 17 new JVM unit tests cover the account + player-shard DTO decode
+(hex serials, permissive objects, equipment mods) and the character-sheet title/skill display helpers.
+**No backend/API change** — the `/auth/me/*` and `/player/shard/*` surfaces the app consumes were the
+§8 prerequisites, already landed.
+
+✅ **M5 — design pass** (2026-07-20, `RunicGateway/Android-app#10`): the shard-website theme applied
+across every screen, restyling the working M1–M4 UI with **no architecture, data-flow, endpoint, or DTO
+change** (§2.1). The design was produced in Claude Design (`Runic Gateway Screens.dc.html`) and
+implemented in Compose. Because the functional screens already draw their color/type/shape from
+`MaterialTheme` tokens (§2), the restyle lives mostly in the **theme layer** and propagates: a deep
+blue-black surface stack (page `#0b0f14` / screen `#0e1318` / elevated `#11161d`), a slate-blue accent
+(`#7f99bd`) with a light CTA fill (`#cdd9e8`), parchment serif body copy, and the engraved **Cinzel**
+serif display face (bundled weight-axis variable font, SIL OFL) for headings and the top bar. The app is
+now **dark-only** — the shard-website look is a single dark theme, so the light scheme is dropped and the
+system light/dark setting is ignored; **per-shard brand-accent seeding is retained** (a site's published
+accent still tints the primary/secondary roles, §3). A small set of reusable components — semantic status
+pills, section labels, a gradient "feature" card, and slim stat meters — carries the motifs the design
+repeats (home status, shard-online banner, champ/character/house status, character vitals & skills). The
+launch theme and system bars are darkened so the first frame matches (no white flash). Verified by
+`:app:assembleDebug` + `:app:testDebugUnitTest` (green); an on-device visual pass against the mockup is
+the one open QA item noted on the PR.
+
+✅ **M6 — polish & release mechanics** (2026-07-20, `RunicGateway/Android-app#11`): the release
+plumbing to ship v1 as a signed, sideloadable APK, with **no architecture, data-flow, or endpoint
+change**. **Default brand app icons** — a gateway-medallion adaptive launcher icon (all densities +
+round + Play Store icon) over the deep-indigo brand background (the Image Asset wizard's default
+green grid was replaced, and the legacy square/round bitmaps + 512 Play icon recomposited to match);
+plus an "RG" notification icon staged for M7. A **version-mismatch guard** (§3): the first-run connect
+probe refuses a backend whose API version this build can't speak (a future `v2`) with a clear
+"app out of date" message rather than mis-rendering (lenient on an older backend that omits `api`).
+**Release build hardening** (§7, §12) — R8 full-mode minify + resource shrink (~31 MB debug → ~4 MB
+signed release) with keep-rules for the kotlinx.serialization serializers, the wire DTOs, and the
+Retrofit interfaces; a release `signingConfig` that reads keystore material from a **gitignored**
+`keystore.properties` or env vars (absent → unsigned; the keystore is never committed); and
+`versionName`/`versionCode` overridable via `-P` so a release tag + CI run number drive them (§10).
+**CI `release.yml`** — on a `v*` tag, builds a **signed** APK (keystore decoded from a base64 Gitea
+secret) and attaches it + `SHA256SUMS` to a Gitea release; `workflow_dispatch` is a signing dry run.
+HTTPS-only in release (M1), no token logging (logging is debug-gated, M3), and the Settings → Server
+hard reset (M3) were already in place. Biometric app-lock is **descoped from v1** (see the note below).
+
+**The functional build (M0–M4), design pass (M5), and release mechanics (M6) are complete. Cutting
+the first `v*` release tag (once the signing secrets are set + the on-device QA pass is done) and M7
+push notifications are what remain.**
+
+### M7 plan — push notifications (in progress)
+
+M7 spans three repos, so it ships in **two parts**; the backend contract lands first because the app
+is a pure consumer of it (§8/§11).
+
+**Part 1 — `website/` backend + `docs/` — ✅ LANDED** (2026-07-20, `RunicGateway/website#78` merged
++ docs#20). Additive, v1-only (new tables/routes/compose
+service; no existing response shape changes). Decision: **no ntfy publish token** — publishes go over
+the internal compose network to unguessable per-device topics carrying **content-free tickles**
+(`{ stream, ref }`); the publisher honors an optional `NTFY_PUBLISH_TOKEN` if ever set but requires
+none (keeps §11's zero-interaction promise).
+- **Two event sources, one publisher.** The fan-out is a small transport-agnostic
+  `utils/pushDispatch.js` that both producers call: `utils/shardIngest.js` (`ingest()`, beside the
+  existing `broadcast(event)`) for shard-derived streams, and the admin create-post path for the
+  `news.post` stream (§11 lists news posts as a public stream, but they originate in the website, not
+  the shard feed).
+- **Stream catalog** (`config/notificationStreams.js`): public/opt-in — `news.post`,
+  `server.status`, `idoc.warning`, `champ.start`, `governor.election`; personal/owner-keyed
+  (require a linked game account) — `vendor.sale`, `house.idoc`, `account.login`. `mapShardEvent()`
+  maps event kinds → streams, drawing public streams **only** from the SSE `PUBLIC_KINDS` allowlist;
+  sensitive kinds are never fanned out publicly. Personal events are delivered only to the owning
+  user's devices, resolved via `shardLinks.getByAccount` (same ownership source as `/player/shard/*`).
+- **Tables:** `push_devices` (per-device endpoint) and `notification_subscriptions` (per-user opted-in
+  streams), FK → `users` ON DELETE CASCADE, mirroring `mobile_refresh_tokens`.
+- **Routes** under the role-agnostic self surface (never `/admin`): `POST|GET /auth/me/devices`,
+  `DELETE /auth/me/devices/:id`, `GET /auth/me/notifications/streams` (catalog),
+  `GET|PUT /auth/me/notifications/subscriptions`. All bearer/cookie auth; Swagger regenerated.
+- **SSRF guard (important):** a device `endpoint` is a client-supplied URL the backend POSTs to, so
+  registration and every publish validate it is HTTPS and its origin is in the shard's ntfy
+  allow-set (`NTFY_BASE_URL` / `NTFY_ALLOWED_ORIGINS`), rejecting loopback/private hosts.
+- **ntfy** added to `website/docker-compose.yml` as a pinned upstream image with a committed
+  declarative `./ntfy/server.yml` and named volume, **no published host port** (reached via the
+  reverse proxy; internal-only for the publisher), anonymous read-write to unguessable topics (no
+  per-user accounts — safe because tickles are content-free).
+
+**Part 2 — the Android app — ✅ LANDED** (2026-07-20, `RunicGateway/Android-app#15` + a small
+`RunicGateway/website#79` settings addition + this docs PR). Built exactly to the plan below, with
+two recorded implementation decisions:
+- **Direct-ntfy embedded distributor, no UnifiedPush library (deviation from §2's "UnifiedPush
+  connector" wording — the plan's stated likely path, work item 1).** The app talks straight to ntfy
+  over its own topic rather than pulling in `org.unifiedpush.android:connector` + an external
+  distributor: a foreground `PushService` holds an OkHttp-SSE connection to `<ntfy>/<topic>/sse`
+  (reusing the M2 `ShardStreamClient` reconnect pattern) on a **bare** client, `PushManager`
+  orchestrates topic mint / device register / start-stop keyed to the session, and `PushNotifier`
+  posts a per-stream notification whose tap deep-links via `MainActivity` intent extras. No new Gradle
+  dependency; a `PushResult`/transport seam keeps the future FCM Play flavor cheap. Reasons: the
+  UnifiedPush distributor model assumes a *separate* app (exactly what the user vetoed), we already own
+  the SSE machinery, and this keeps the APK Google-free and dependency-light. New code lives in
+  `core/push/` + `ui/notifications/` + a `NotificationsApi`/`NotificationsRepository`; no existing
+  screen's data flow changed.
+- **One small additive backend field was required after all (`push.ntfyUrl`).** The embedded
+  distributor must know the shard's client-facing ntfy URL to build its topic endpoint, and Part 1
+  never surfaced it (the `NTFY_*` vars are server-only). So `/public/settings` now carries
+  `push: { ntfyUrl }` (from `NTFY_PUBLIC_URL` / first `NTFY_ALLOWED_ORIGINS`; never the internal
+  `NTFY_BASE_URL`), null when unconfigured → the app shows push as unavailable for that shard. This is
+  the "no backend work in Part 2" caveat corrected: it is additive, non-sensitive, and forward-compatible
+  (an older backend omitting it just decodes to null). **Deploy dependency stands:** push only delivers
+  once the shard sets `NTFY_PUBLIC_URL`/`NTFY_ALLOWED_ORIGINS` (§13).
+
+Verified green: `:app:testDebugUnitTest` (18 new JVM tests — notifications DTO decode, ntfy tickle
+parse incl. malformed, topic/URL building, stream→route map + personal gating) + `:app:lintDebug` +
+`:app:assembleDebug`; backend 250 tests (+3 for `push.ntfyUrl`) and `npm run swagger` clean. The
+foreground-service tradeoff (§11) and the POST_NOTIFICATIONS runtime permission are implemented as
+planned; an on-device delivery pass against a live ntfy is the one open QA item.
+
+**Part 2 (original plan) — the Android app.** UnifiedPush receiver + device registration
+against the merged Part-1 contract, a Notifications settings screen, and notification-tap deep-links.
+The app is architected for push from M0 (§11), so this is **additive** — a new feature slice
+(`core/push` + `ui/notifications` + a `DevicesApi`/`NotificationsApi` pair) that touches no existing
+screen's data flow. Everything the app calls already exists and is merged; there is **no backend
+work** in Part 2.
+
+The Part-1 contract the app codes against (verified against the merged `website` source):
+- `POST /auth/me/devices` `{ transport?: 'unifiedpush'|'fcm', endpoint, platform? }` → `201 PushDevice`
+  `{ id, transport, endpoint, platform, createdAt, lastSeenAt }`. Idempotent per `(user, endpoint)`
+  (upsert). `endpoint` **must** be HTTPS on the shard's ntfy allow-set — a private/loopback or
+  off-allowlist origin is rejected `400` (the SSRF guard). Bearer-auth, so registration only happens
+  while signed in.
+- `GET /auth/me/devices` → `PushDevice[]`; `DELETE /auth/me/devices/:id` → `{ ok: true }` (`404` if not
+  the caller's).
+- `GET /auth/me/notifications/streams` → `{ streams: [{ id, label, description, personal,
+  requiresLinkedAccount }] }` — the eight-stream catalog (`news.post`, `server.status`,
+  `idoc.warning`, `champ.start`, `governor.election`; personal `vendor.sale`, `house.idoc`,
+  `account.login`). Render from this, don't hardcode.
+- `GET /auth/me/notifications/subscriptions` → `{ streams: [id…] }`; `PUT` the same shape (full
+  replace; unknown ids dropped server-side; the stored set is echoed back).
+- **The wire tickle** the device receives is the content-free `{ "stream": "<id>", "ref": "<opaque>" }`
+  JSON body (`utils/pushDispatch.js`). `ref` is a serial / city / timestamp hint — **never** content.
+
+Work items:
+
+1. **Transport — the app is its own distributor; no second app (DECIDED).** The Runic Gateway app
+   **embeds its own UnifiedPush distributor**. The self-hosted **ntfy is only the relay server**, never
+   a user-installed app — the user installs *one* APK and it receives its own notifications, with no
+   external distributor (no ntfy app, no NextPush) and no Google Play Services. Concretely, the embedded
+   distributor holds a **persistent connection to the shard's ntfy** in a **foreground service**,
+   reusing the OkHttp reconnect/backoff pattern already built for `core/net/ShardStreamClient` (M2): it
+   subscribes to the app's own random, unguessable ntfy **topic** (over `wss://<ntfy-host>/<topic>/ws`
+   or the `/json` stream) and forwards each received `{stream,ref}` tickle to the app's receiver. The
+   **endpoint the app registers** with the backend (work item 5) is that topic's public URL
+   (`https://<ntfy-host>/<topic>`) — exactly the client-supplied `endpoint` the merged `POST
+   /auth/me/devices` contract expects and the URL the backend POSTs tickles to. Keep the transport
+   behind a small `PushTransport` seam so the **future Play/FCM build flavor** (§11, §M8) can swap the
+   embedded-ntfy distributor for FCM without touching registration, subscriptions, or notification code.
+   (Implementation detail to confirm: whether a maintained Google-free embedded UnifiedPush-distributor
+   library fits, or — more likely — a thin in-app distributor written directly over ntfy's subscribe API
+   reusing `ShardStreamClient`. Either way the distributor lives **inside this app**; the UnifiedPush
+   *receiver* abstraction is retained only to keep the FCM-flavor seam clean.)
+   - **Tradeoff, accepted:** instant background delivery requires a persistent foreground service with
+     an ongoing (low-importance) notification and its battery cost — this is exactly how ntfy's own app
+     does instant delivery, and it is the price of Google-free self-delivery. A future "battery saver"
+     option could fall back to periodic polling, but v1 ships the always-connected foreground service.
+2. **Deps + manifest.** Add the UnifiedPush connector + the embedded-distributor transport (per #1) to
+   the version catalog; declare `POST_NOTIFICATIONS` (API 33+ runtime permission) **and
+   `FOREGROUND_SERVICE` + `FOREGROUND_SERVICE_DATA_SYNC`** (API 34+, for the persistent ntfy
+   connection); register the receiver and the foreground service in `AndroidManifest.xml`; define the
+   notification channels (id/name externalized, §2) — one for real notifications plus a low-importance
+   channel for the ongoing foreground-service notification — and reuse the "RG" notification icon
+   **already staged in M6**.
+3. **`core/push` — embedded distributor + receiver.** The **distributor** component is a foreground
+   service that owns the ntfy connection (per #1): it (re)creates the app's topic, subscribes over
+   OkHttp with reconnect/backoff cloned from `ShardStreamClient`, and forwards each frame to the
+   receiver. The **receiver** parses the `{ stream, ref }` tickle (`kotlinx.serialization`; an
+   unknown/garbled body is dropped, not crashed — §7 discipline) and posts a notification (work item 7).
+   Endpoint (re)registration against the backend fires on first subscribe / topic (re)creation
+   (work item 5); a transient ntfy drop is just a reconnect, not a re-register.
+4. **`DevicesApi` + `NotificationsApi` (Retrofit) + DTOs.** Hand-authored, spec-aligned (as recorded
+   for M1): `RegisterDeviceRequestDto`, `PushDeviceDto`, `NotificationStreamDto`,
+   `NotificationStreamsDto`, `NotificationSubscriptionsDto`. Both go through the existing bearer/refresh
+   stack (`AuthInterceptor` + `TokenAuthenticator`) and return the typed `ApiResult` (§7). A
+   `NotificationsRepository` owns register/list/delete-device and get/put streams+subscriptions.
+5. **Endpoint ↔ backend lifecycle (mirror the M3 token teardown).** Persist the app's ntfy topic, its
+   endpoint URL, and the returned device `id` in prefs (DataStore; the topic/endpoint isn't a secret —
+   its security rests on being unguessable + the content-free tickle, §11). Start the embedded
+   distributor and `POST /auth/me/devices` **only when the user has ≥1 subscription and is signed in**.
+   On **logout / dead-refresh sign-out / Settings→Server switch**, `DELETE /auth/me/devices/:id`, **stop
+   the foreground service**, and drop the topic — wire this into `SessionManager` beside the existing
+   token-clear so a signed-out device stops receiving (§4.3, §11 "unregister on logout / token
+   revocation"). On a **server (base-URL) switch**, mint a fresh topic against the new shard's ntfy (the
+   old endpoint's origin won't be on the new host's allow-set). Re-assert the endpoint + restart the
+   service on app start when signed-in + subscribed. A `400` on register (endpoint origin off the
+   shard's `NTFY_ALLOWED_ORIGINS`) surfaces a clear "your shard's push relay isn't reachable" state, not
+   a crash.
+6. **Notifications settings screen (`ui/notifications`).** Lists the catalog from
+   `GET …/streams` with a per-stream toggle bound to `GET/PUT …/subscriptions`; a **personal** stream
+   (`requiresLinkedAccount`) is greyed with a "link a game account" hint until the user has a linked
+   account — reuse the linked-accounts signal already fetched for M4's player surface
+   (`PlayerShardRepository`), not a fresh source of truth. Toggling to a non-empty set triggers the
+   register flow (#5) and requests `POST_NOTIFICATIONS`; emptying the set unregisters. Each mutation
+   folds its `ApiResult` into a section-scoped, localized banner (§7 parity with M4).
+7. **Deep-links (resolves the §13 open item).** Tapping a notification opens the app to the stream's
+   home: `news.post`→News, `server.status`/`champ.start`/`idoc.warning`/`governor.election`→Shard,
+   `vendor.sale`→Vendors, `house.idoc`→My Houses, `account.login`→My Account. Routed through the
+   existing `ui/navigation/Routes.kt`; a signed-out/deep-link-to-player tap lands on the `PlayerGate`
+   (M4) rather than erroring. **v1 shows a generic per-stream notification** (localized catalog
+   `label`) and deep-links — it does **not** pull `ref` content first; the content-free design means
+   nothing needs decrypting to render the tap, and the target screen fetches fresh over the
+   authenticated API on open. (Pulling `ref` for a richer inline notification is a possible later
+   enhancement, not v1.)
+8. **Menu.** Add a **Notifications** entry to the signed-in group in `ui/navigation/Menu.kt` (near My
+   Account), visible once signed in.
+9. **Permission UX.** Request `POST_NOTIFICATIONS` at the moment the user first enables a stream (API
+   33+); on denial, keep the toggle off and show how to enable it in system settings — never nag on
+   launch.
+10. **Tests (JVM, `testDebugUnitTest`).** DTO decode (device/stream/subscription), `{ stream, ref }`
+    tickle parse (incl. a malformed body → dropped), the stream→deep-link map, the "personal greyed
+    until linked" gate, and the register/unregister lifecycle over a fake `SessionManager` + repository
+    (parity with M3's session tests).
+
+**Cross-repo dependency to confirm before/at implementation** (a Part-1 §13 open item): the shard's
+finalized **ntfy reverse-proxy hostname** must be in `NTFY_ALLOWED_ORIGINS`, because the distributor
+hands the app an endpoint on *that* origin and the backend rejects a register whose origin isn't
+allow-listed. This is deployment config, not code, but Part 2 can't be end-to-end tested until it's
+pinned. No `website`/`link`/`servuo-plugins` code change is expected in Part 2.
+
+Ships as `RunicGateway/Android-app#15`; bumps `versionCode`/`versionName` for a post-v1 release
+(§10). Like M1–M4 it records itself in the §9 build-progress block on landing.
+
+### M9 plan — native SSO login (in progress)
+
+M9 spans `website/` + `android-app/` + `docs/`, so — like M7 — it ships in **two parts**, backend
+first (the app is a pure consumer of the bridge contract; §4.2, §9 item 10).
+
+**Part 1 — `website/` backend + `docs/` — ✅ LANDED** (the Mobile SSO Authorization Bridge:
+`mobile_auth_sessions`/`mobile_auth_codes` tables, `GET /auth/mobile/sso/start`, the `mode:'mobile'`
+branch in the reused SSO callback + TOTP completion, `POST /auth/mobile/sso/exchange`, the exact-match
+`MOBILE_AUTH_REDIRECT_URIS` allowlist, and bridge-table cleanup). Canonical ref:
+`../website/BACKEND_DESIGN.md` → "Mobile SSO Authorization Bridge".
+
+**Part 2 — the Android app (this milestone).** The native in-app "Sign in with Google / Discord"
+client. **Additive** — a new auth slice (`core/auth/sso` + a `SsoApi`/`SsoAuthManager` + a login-screen
+provider list) that feeds the *existing* M3 session machinery; it adds **no** new token-storage or
+refresh code, and touches no other screen. **No backend work** — every endpoint it calls is merged.
+
+The Part-1 contract the app codes against (verified against the merged `website` source):
+- `GET /auth/providers` → `[{ id, name, icon, loginUrl, priority }]` (public discovery, no secrets).
+  `icon` ∈ `google|discord|oidc|oauth2`. Render the provider buttons from this — don't hardcode.
+- `GET /auth/mobile/sso/start?provider&code_challenge&state&redirect_uri` — **opened in a Custom Tab**
+  (not an XHR): it 302s through the IdP and finally deep-links back to `redirect_uri`. `redirect_uri`
+  must be an **exact** allowlist entry — the app always sends the one fixed callback
+  `runicgateway://auth/callback`.
+- The callback deep link carries **either** `?code=<one-time>&state=<echoed>` (success) **or**
+  `?error=<reason>&state=<echoed>` (`invalid_provider`/`provider_unavailable`/`server_error`, or an
+  IdP/link refusal) — **never a token**.
+- `POST /auth/mobile/sso/exchange` `{ code, code_verifier }` → the **same** `{ accessToken,
+  refreshToken, expiresIn, user }` pair as `/auth/mobile/login`; `401` on an unknown/expired/used code
+  or a PKCE-verifier mismatch.
+
+Work items:
+
+1. **PKCE + state (Layer B, app↔website).** A pure-JVM `Pkce` helper (unit-testable, no Android
+   framework types): `code_verifier` = 32 random bytes base64url (RFC 7636 S256), `code_challenge` =
+   base64url(SHA-256(verifier)), plus a random `state`. `java.util.Base64` URL encoder without padding
+   + `MessageDigest` — matches the backend's `crypto.createHash('sha256')…base64url` exactly.
+2. **`SsoAuthManager` (Singleton) — the flow orchestrator.** Holds the **pending** `{state, verifier}`
+   in memory (lost on process death → the exchange fails closed and the user retries; acceptable and
+   safe, documented). `buildStartUrl(provider)` mints PKCE+state, stashes pending, and builds the
+   absolute `/start` URL off `BaseUrlHolder` for the Custom Tab. `isCallback(uri)` matches our scheme;
+   `complete(uri)` verifies `state` (CSRF), maps an `error`, exchanges the `code` with the stashed
+   `verifier`, and on success drives `SessionManager.onSignedIn` — the *same* entry the password login
+   uses, so push registration (`PushManager` observes the session) and the menu react identically. It
+   exposes an `outcome: StateFlow` (Idle/Success/Failed(reason)) the login screen consumes, robust to a
+   ViewModel/activity recreation while the Custom Tab is foreground.
+3. **`SsoApi` + DTOs.** `GET api/v1/auth/providers` → `List<SsoProviderDto>`; `POST
+   api/v1/auth/mobile/sso/exchange` tagged `Http.NO_SESSION_HEADER` (no bearer; a credential-style
+   `401` must not be read as an expired session or trip the refresh `Authenticator`) → the reused
+   `MobileTokenResponse`. Lenient Json (additive fields safe, §8).
+4. **Deep link.** Register the `runicgateway://auth/callback` intent-filter on `MainActivity`
+   (`VIEW` + `DEFAULT` + `BROWSABLE`, `scheme/host/path` from one shared constant) and set
+   `launchMode="singleTop"` so the returning Custom Tab reuses the running task; `onCreate`/`onNewIntent`
+   route a matching `ACTION_VIEW` intent to `SsoAuthManager.complete` on `lifecycleScope`. Custom scheme
+   only for now — App Links deferred (`APP_LINKS.md`).
+5. **Login screen.** Replace the single "SSO on the website" hand-off with a native provider list from
+   `GET /auth/providers`: one button per provider (Google/Discord/OIDC glyph from `icon`), each opening
+   its `/start` URL in a Custom Tab via the existing `WebHandoff`. The `LoginViewModel` collects
+   `SsoAuthManager.outcome` → a success pops back like a password sign-in; a failure surfaces a friendly
+   inline error (reusing the existing `LoginError` channel + a new SSO string). Falls back to the
+   website login hand-off when discovery returns no providers or the base URL is unset.
+6. **Tests (JVM, `testDebugUnitTest`).** `Pkce` (verifier charset/length, challenge = base64url-SHA-256
+   of a known vector, no padding), start-URL building (encoded params, fixed `redirect_uri`), and
+   `SsoAuthManager.complete` over a fake `SsoApi` + `SessionManager`: success signs in; a mismatched or
+   missing `state` fails without exchanging; an `error=` callback maps to the right reason; a `401`
+   exchange maps to expired-code; a missing pending (process death) fails closed.
+
+Ships as a `RunicGateway/Android-app` PR; bumps `versionCode`/`versionName` for a post-v1 release
+(§10) and records itself in the §9 build-progress block on landing. No `website`/`link`/`servuo-plugins`
+code change is expected in Part 2.
+
+**Prerequisite progress (§8):** all v1 prerequisites are **done** (2026-07-19) — ✅ password reset
+(item 2; website#75 + docs#8), ✅ role-agnostic `/auth/me/*` self surface (item 1; website#76 + docs#10),
+✅ version/health surfacing (item 4) and ✅ branding for mobile (item 6). **Push notifications (item 3)
+is the only remaining §8 work and is post-v1 (M7).** The app's functional Kotlin pass (M0–M4) is now
+unblocked.
+
+The workspace already holds `website/`, `link/`, `servuo-plugins/`, and `docs/`. `android-app/` is
+the fifth repo. It is **purely an API client of the website backend** — it never talks to the
+`link/` sidecar or the shard directly, and it ships none of the shard/sidecar wiring.
+
+---
+
+## 1. Purpose & scope
+
+A native Android client for a Runic Gateway shard's public site + player self-service. It surfaces
+the same content and player features as `website/client`, minus every administrative/management
+console. It is a **read + self-service** app, not an operator tool.
+
+### In scope
+- **Public content** (no auth): news / Five-on-Friday / newsletter / screenshots, wiki, CMS pages,
+  site status & maintenance page, contact form.
+- **Public shard widgets** (no auth): shard status, online staff, live event feed, economy series,
+  champion spawns, guilds, governors, houses/IDOC, presence — including the live **SSE** stream.
+- **Account & auth** (bearer token): native **username/password login (with TOTP 2FA)**, logout,
+  refresh; account self-service (change username/password, TOTP enroll/disable, list/unlink SSO
+  identities). Registration, invite acceptance, password reset, and SSO are **website-handled** — the
+  app hands off to the website's pages for those (§4.2), not native screens.
+- **Player's own shard/game data** (bearer token): link a game account via a `[link` one-time code,
+  hybrid game-account signup, list linked accounts, own character roster, character sheet, own
+  player vendors, own vendor sales, own houses (home/decay status).
+- **Access-level menu**: one shared navigation that reveals items based on the signed-in user's role.
+- **Opt-in push notifications** (post-v1; architected for from the start): per-stream subscriptions the
+  user chooses — nothing is pushed unless subscribed. See §11.
+
+### Explicitly OUT of scope (never in the app, for any role)
+- The **hero editor** and any CMS authoring/block editing.
+- The **admin / auth-management console** — user management, invites issuance, SSO provider config,
+  moderation console, email config, bot-activity/ban console. (Players still *log in*; what's
+  excluded is the management surface, not authentication itself.)
+- The **Discord bot** management (and anything under the unpublished `/internal/**` port — it
+  returns the decrypted bot token and must never be reachable from a client).
+- **Shard / uo-link administration** — sidecar base-URL/token config (`uoLinkConfig`), shard ops,
+  the staff shard-user console. (The app shows *public* shard widgets and a player's *own* game
+  data; it does not manage the sidecar.)
+
+> The excluded surfaces all live under `/api/v1/admin/**` and `/api/v1/internal/**`. The app only
+> ever calls `/api/v1/public/**`, `/api/v1/auth/**` (incl. the new role-agnostic self surface
+> `/auth/me/*`, §6.4), and `/api/v1/player/**` — it never references `/admin`.
+
+---
+
+## 2. Architecture & stack
+
+Native, Android-only:
+
+| Concern | Choice |
+|---|---|
+| Language / UI | **Kotlin + Jetpack Compose** (Material 3) |
+| Navigation | Navigation-Compose, single-activity |
+| HTTP | **Retrofit + OkHttp**, `kotlinx.serialization` converter |
+| Async | Coroutines + Flow; `viewModelScope` |
+| DI | Hilt |
+| Saved base URL / prefs | **Jetpack DataStore** (Preferences) |
+| Tokens at rest | **EncryptedSharedPreferences** (Jetpack Security / Tink-backed) |
+| Live feed | OkHttp SSE (`EventSource`) for `/public/shard/stream` |
+| Images | Coil |
+| Min SDK | **Android 10 (API 29)** — ~95% device reach with a modern baseline (biometric, storage, TLS) and no compat shims |
+| Target/compile SDK | Latest stable (35) |
+| Telemetry | **None in v1** — no crash/analytics SDK (privacy-first). Revisit self-hosted crash reporting later. |
+| Localization | **Strings externalized from day one** (`res/values/strings.xml`); English is the only bundled locale, but the structure invites community translations. No hardcoded UI strings. |
+| Web hand-off | Chrome Custom Tabs — opens the website for registration / invite / password reset / SSO (§4.2) |
+
+**API model generation.** The DTOs and the Retrofit interface are generated from
+`swagger-output.json` (OpenAPI 3.0) rather than hand-written, so the client stays in lockstep with
+the backend contract. A build step (or a checked-in generated module regenerated on contract change)
+runs `openapi-generator` against the committed spec. Endpoints that return
+`additionalProperties: true` (several shard reads) are typed as permissive maps / JsonElement.
+
+**Layering** mirrors the backend's discipline: `screen (Compose) → ViewModel → repository → API
+service (Retrofit) → DTO`. Repositories expose `Result`-like sealed types so the UI degrades
+gracefully (see §7).
+
+### 2.1 Build workflow: Kotlin first, then design-led UI
+The app is built in two passes. **First**, the functional Kotlin is written — the layering above with
+placeholder/functional Compose screens: navigation, ViewModels, repositories, the generated API
+client, auth/token handling, and every screen wired to its endpoints and working end-to-end. **Then**,
+once that Kotlin code is done, **Claude Design produces the front-end design** for the app, and
+**Claude Code implements the final UI (Compose screens, theming, components) according to that
+design.** The design pass restyles and refines the already-working screens; it does not change the
+architecture, data flow, or endpoint contracts established in the first pass. Keeping strings
+externalized and branding data-driven (§2, §3) from the start is what lets the design pass reskin
+freely without touching logic.
+
+---
+
+## 3. Base URL: first-run + settings
+
+The app is **brandable to any shard's site** (one site per install), so the API host is not
+compiled in.
+
+- **First run (before init):** a mandatory **"Connect to your shard's website"** screen asks for the
+  site base URL. The app validates it by calling `GET /api/v1/public/status` (and reads
+  `/public/settings` for branding: name/colors/logo). Only on a successful, well-formed response is
+  the URL persisted to DataStore and the app allowed to initialize its main UI.
+  - Accept `https://host[/base]`; normalize/trim; require HTTPS in release builds (allow HTTP only in
+    debug for local dev against `127.0.0.1:3000`).
+  - Failure states: unreachable, non-2xx, not-a-Runic-Gateway-site (missing expected `/public/status`
+    shape), TLS error — each gets a clear retry message. Nothing else in the app runs until this
+    succeeds.
+- **Settings:** the base URL is editable later under **Settings → Server**. Changing it is a
+  hard reset of session state: clear stored tokens, drop cached content, re-run the validation probe,
+  and return to a signed-out state against the new host.
+- **Version guard:** the backend is versioned; surface a clear "app/site version mismatch" state if a
+  future protocol/version header disagrees, rather than mis-rendering.
+
+---
+
+## 4. Authentication & token handling
+
+**Design rule (decided): credential/identity flows live on the website, not in the app.** The app
+implements **only native username/password (+TOTP) login**. Registration, invite acceptance,
+forgot/reset password, and SSO all **run through the website's API + web front end** — the app hands
+off to the website in a browser (Chrome Custom Tab) and the user returns to sign in. This keeps every
+account-provisioning, OAuth, and password path in one audited place rather than duplicated (and
+security-reviewed twice), and it means **no new mobile-facing auth endpoints** are required for v1.
+Password reset is being built on the backend + web front end **before** app work begins (§8), so it is
+simply available in that hand-off, not app scope.
+
+### 4.1 Username + password (+ TOTP) — the app's only native auth, ready today
+Uses the existing **mobile bearer** surface, no backend changes:
+
+- `POST /auth/mobile/login` `{ username, password, code? }` →
+  `{ accessToken, refreshToken, expiresIn, user: { id, username, role } }`.
+  - **Single-request 2FA:** a `401 { totpRequired: true }` means re-submit with `code`. The login
+    screen reveals a code field on that response.
+  - Respect `429` (backoff / rate-limit) with a friendly "try again shortly" state — login is guarded
+    by per-IP backoff → slow-down → hard cap on the server.
+- `POST /auth/mobile/refresh` `{ refreshToken }` → new pair. **Refresh tokens are single-use and
+  rotated**: store the new pair atomically; a failed refresh (401) means the session is dead → sign
+  out and return to login. An OkHttp `Authenticator`/interceptor performs a one-shot refresh on a
+  `401` from a bearer call, with a mutex so concurrent 401s trigger only one refresh.
+- `POST /auth/mobile/logout` `{ refreshToken?, all? }` (requires bearer) — revoke this session or all
+  sessions. Called on user logout and on "sign out everywhere."
+### 4.2 Website-handled flows: registration, invite, forgot-password, SSO
+These are **not** rebuilt in the app. The app links out to the website's own pages/API and the user
+completes them in a Custom Tab, then returns and signs in natively (§4.1):
+- **Register / accept invite** — the app opens the website's register / `…/invite/:token` pages. Invite
+  emails already link to the website. After the account exists, the user signs into the app with their
+  new username + password. (No mobile register/invite endpoints needed.)
+- **Forgot / reset password** — the app links to the website's reset page (the flow being built in §8
+  before app work). The user resets there, then signs into the app. (No mobile reset endpoint needed.)
+- **SSO (Google / Discord / OIDC)** — **v1** shipped this as a website browser hand-off: an SSO user
+  links their identity and sets a password on the website, then uses password login in the app.
+  `GET /auth/providers` is shown so the login screen can direct users to "sign in with … on the website."
+  - **Native in-app SSO — now being built (M9), post-v1 additive.** The "possible later enhancement"
+    noted here is now the **Mobile SSO Authorization Bridge**: a Custom-Tab flow that hands a one-time
+    code back to the app's fixed callback (`runicgateway://auth/callback`), exchanged for the *existing*
+    mobile bearer tokens. It **extends** the existing `/auth/sso/*` redirect flow rather than adding a
+    parallel auth path — same PKCE-vs-IdP, same link-only + opt-in-provisioning policy, same TOTP gate,
+    same token shape as `/auth/mobile/login`. The bridge adds a **second** PKCE layer (app ↔ website)
+    and an app-generated `state` (CSRF, verified by the app before exchange). Backend + docs land first
+    (this document's canonical API ref is `../website/BACKEND_DESIGN.md` → "Mobile SSO Authorization
+    Bridge"); the native app client is M9. Custom-scheme callback only for now — App Links are deferred
+    (see [`APP_LINKS.md`](./APP_LINKS.md)).
+
+### 4.3 Session model (all paths)
+- **Refresh:** `POST /auth/mobile/refresh` `{ refreshToken }` → new pair. **Single-use / rotated:** store
+  the new pair atomically; a failed refresh (401) means the session is dead → sign out. An OkHttp
+  `Authenticator` does a one-shot refresh on a bearer `401`, behind a mutex so concurrent 401s trigger
+  only one refresh.
+- **Logout:** `POST /auth/mobile/logout` `{ refreshToken?, all? }` (requires bearer) — this session or
+  all sessions ("sign out everywhere").
+- **Storage:** access + refresh tokens live in EncryptedSharedPreferences, never in plain prefs/logs.
+  The base URL may live in plain DataStore; tokens must not. An optional **biometric app-lock** was
+  considered here but **descoped from v1** (tokens are already encrypted at rest; see the M3 note).
+- **Role for the menu** comes from the login response `user.role` and is re-validated via
+  `GET /auth/me` on app resume (roles can change server-side; admin access is re-checked every
+  request on the backend, so the app treats role as *advisory for menu rendering* and lets the server
+  be the authority — a 403 is handled gracefully, never assumed-away).
+
+---
+
+## 5. Navigation — one shared, access-level menu
+
+A **single** navigation definition; each entry declares the minimum access it requires, and the menu
+renders only the entries the current session satisfies. Roles: `anonymous` < `player` /
+`moderator` / `editor` / `admin` (the three staff roles are not a strict ladder — gate by capability,
+not rank).
+
+| Menu group | Visible to | Backing endpoints |
+|---|---|---|
+| Home / Status | everyone | `/public/status`, `/public/settings` |
+| News & content | everyone | `/public/posts/:category`, `/public/pages/:slug` |
+| Wiki | everyone | `/public/wiki`, `/public/wiki/categories`, `/public/wiki/tags`, `/public/wiki/:slug` |
+| Shard (live) | everyone | `/public/shard/*` + `/public/shard/stream` (SSE) |
+| Contact | everyone | `/public/contact` |
+| **My Account** | signed-in | `/player/account/*` (or `/admin/account/*` for staff — see §6.4) |
+| **My Characters / Vendors / Houses** | `player` (linked) | `/player/shard/*` |
+| Sign in / Sign out | toggles on session | `/auth/mobile/*` |
+
+Guidelines:
+- The menu is **declarative + data-driven**, not a pile of `if role ==` checks — one list of entries
+  with a `minAccess`/`requiredCapability` field, filtered by the session.
+- Never hide the fact that more exists behind auth in a way that misleads; anonymous users see public
+  groups and a "Sign in" affordance.
+- The server is the source of truth: a hidden/greyed item is a UX convenience; every gated call still
+  enforces on the backend and the app handles 401/403 cleanly.
+
+---
+
+## 6. Screen ↔ endpoint map
+
+### 6.1 Public content
+- **Home/Status** — `GET /public/status`, `GET /public/settings` (branding + maintenance banner).
+- **News hub** — `GET /public/posts/:category` (`news | five-on-friday | newsletter | screenshots`),
+  detail via `GET /public/posts/:category/:idOrSlug`.
+- **CMS pages** — `GET /public/pages/:slug` (block-based; render the block types the site uses).
+- **Wiki** — list/categories/tags/detail as above.
+- **Contact** — `POST /public/contact` (rate-limited; handle 429/502).
+
+### 6.2 Public shard (live)
+- Status/online/feed/economy/champs/guilds/governors(+history)/presence/houses/idoc — the
+  `/public/shard/*` GETs.
+- **Live updates** — subscribe to `GET /public/shard/stream` (SSE, safe kinds only) and patch the
+  in-memory boards in place (champ/guild/city/house/presence update+remove frames). Reconnect with
+  backoff; fall back to poll if SSE drops.
+
+### 6.3 Player self-service & game data (bearer)
+- **Account** — `GET /player/account`; `PATCH /player/account/username`;
+  `PATCH /player/account/password`; TOTP `setup`/`enable`/`disable`; identities `GET` / `DELETE`.
+- **Game account linking** — `POST /player/shard/link` (one-time `[link` code),
+  `POST /player/shard/account` (hybrid signup, when enabled), `GET /player/shard/accounts`.
+- **My game data** — `GET /player/shard/roster/:account`, `/char/:serial`, `/vendors/:account`,
+  `/sales`, `/houses`. All ownership-checked server-side; a `503` means shard/sidecar down → show an
+  "offline, retry" state (see §7).
+- **Presentation is text-only for v1.** Character sheets and vendor listings render as data/text — no
+  item icons or paperdoll art. A richer "pretty paperdoll" view is a **future** enhancement (pending the
+  art/asset work on the platform side) and is explicitly out of the first release.
+
+### 6.4 Self-service is role-agnostic under `/auth/**` (decided)
+Player self-service is under `/player/account/*` (gated to `role='player'`) and staff use the *same*
+handlers under `/admin/account/*`. Rather than have the app branch by role (and touch `/admin`), we
+**add a role-agnostic self surface under `/auth/**`** — the canonical "me" endpoints for every role.
+The app calls these regardless of role, and never references `/admin`. This is an **additive v1**
+change (see §8): the existing `/player/account/*` and `/admin/account/*` routes stay for web
+back-compat; `/auth/me/*` reuses the same `account.controller` handlers behind `requireAuth` (any
+authenticated role), so there's no logic duplication.
+
+---
+
+## 7. Degradation & offline
+
+Mirrors the website's "degrade gracefully" invariant:
+- Every repository call returns a typed result (`Ok`/`HttpError(status)`/`NetworkError`); the UI never
+  crashes on a down backend or shard.
+- **Shard down** (`503` from shard reads, or `/public/shard/status` shows disconnected) → render the
+  shard as **offline**, keep the rest of the app usable.
+- **Site maintenance** (`/public/status` = maintenance) → show the maintenance page; public shard
+  widgets may still render (they're not maintenance-gated server-side).
+- **Offline caching is not a v1 requirement** (decided). The app assumes connectivity and shows clean
+  loading/error/retry states; it does **not** ship a Room cache in v1. Cached read-only content can be
+  added later without reworking the repository layer (its typed results already isolate the UI from the
+  data source). No `Room` dependency in the initial build.
+
+---
+
+## 8. Cross-repo work to do *before* coding the app
+
+The bridge repos are contracts; the app adds a new consumer. Land these first (in `website/` +
+`docs/`), each with regenerated Swagger.
+
+**Already verified — no change needed** (checked against the current backend):
+- **CORS / native reachability.** CORS is only enabled when `CLIENT_ORIGIN` is set (local Vite dev);
+  in prod the SPA is same-origin and CORS is off. A native HTTP client is not browser-origin-bound, so
+  no CORS/preflight applies. *Caveat:* `app.js` mounts a bot/scanner guard before routing — the app
+  must send a sane `User-Agent` so it isn't caught by scanner heuristics.
+- **`GET /auth/me` bearer support.** `auth/token.js:extractToken` reads the cookie *then* falls back to
+  `Authorization: Bearer`, and `/auth/me` advertises both auth schemes. It returns the current user for
+  a bearer token today. The entire `/player/**` and self-service surface works with bearer as-is.
+- **Token lifetimes.** Access `MOBILE_ACCESS_TTL` = 15m default; refresh `MOBILE_REFRESH_TTL_DAYS` =
+  30 days. The login/refresh response's `expiresIn` reflects the access TTL — drive proactive refresh
+  off it.
+
+**API versioning: everything below stays in v1 (decided).** These are all *additive* routes — new
+endpoints that change no existing response shape — so they do **not** warrant a v2. A v2 API is only
+justified by a breaking change to a contract existing clients depend on, which none of this is. The
+web client and the app both consume v1; a second parallel route tree + Swagger spec would be pure
+maintenance cost. Reserve v2 for a real breaking re-shape if one ever arises.
+
+**To build (all additive, v1):**
+1. **Role-agnostic self-service under `/auth/**` (§6.4, decided).**
+   ✅ **DONE (2026-07-19, RunicGateway/website#76 (+ this docs PR)).** A `me.routes.js`
+   sub-router mounts the existing `account.controller` self handlers behind `requireAuth` (any role) at
+   `/auth/me/*`, so the app has one self surface and never touches `/admin`. The old
+   `/player/account/*` + `/admin/account/*` routes stay for web back-compat. Shipped routes:
+   - `GET /auth/me` — current `{ id, username, role }` (already existed; the app's role source).
+   - `GET /auth/me/account` — full self account.
+   - `PATCH /auth/me/account/username`, `PATCH /auth/me/account/password`.
+   - `POST /auth/me/account/totp/setup|enable|disable`.
+   - `GET /auth/me/account/identities`, `DELETE /auth/me/account/identities/:provider`.
+   - Swagger regenerated with `#swagger` annotations; `test/authMe.test.js` guards the auth gate; and
+     an end-to-end smoketest confirmed both a player and an editor (staff) drive the same surface.
+2. **Password reset — build on backend + web front end FIRST (a prerequisite, not app scope).**
+   ✅ **DONE (2026-07-19, RunicGateway/website#75 + docs#8).** Full platform flow shipped in `website/`:
+   request-reset (`POST /auth/password/forgot`, always a generic 200 — no account enumeration) emails a
+   single-use, ~1h link → reset page + endpoints (`GET|POST /auth/password/reset/:token`) that verify,
+   set the password, and revoke every session (web cutoff + mobile refresh tokens). The token is an
+   opaque random value stored as a **sha256 hash** in a new `password_resets` table (mirroring
+   `user_invites` — chosen over a signed JWT to match the house pattern; functionally equivalent). It
+   also serves SSO-only accounts (null hash) as their set-initial-password path. Swagger regenerated;
+   documented in `BACKEND_DESIGN.md`. The app just links users to the web page (§4.2) — **no mobile reset
+   endpoint.**
+   - No mobile SSO/invite/register endpoints are needed: SSO, registration, and invite acceptance all
+     stay website-handled and the app hands off to them (§4.2). This is a deliberate scope reduction.
+3. **Push notifications** — see §11. Additive v1 endpoints under `/auth/me/devices*` and
+   `/auth/me/notifications*`, plus a **self-hosted `ntfy` service added to `website/docker-compose.yml`**
+   with fully declarative, zero-interaction config. Not required for the first release (M7, not M1–M6).
+   ✅ **Backend + docs LANDED (2026-07-20, RunicGateway/website#78 merged (+ docs#20)).** The
+   contract Part 1 is built: the two tables, the stream catalog + `PUBLIC_KINDS`-gated event mapping,
+   the content-free-tickle fan-out (`utils/pushDispatch`, SSRF-guarded endpoints, owner-keyed personal
+   streams), the six `/auth/me/*` routes (Swagger regenerated), and the declarative `ntfy` compose
+   service (247 server tests green). The app (Part 2, §9 M7) consumes this next — see the "M7 plan"
+   block for the detailed Part 2 plan.
+4. **Version/health surfacing.**
+   ✅ **DONE (2026-07-19, RunicGateway/website#77 (+ this docs PR)).** A dependency-free
+   `config/version.js` (`{ service:'runic-gateway', api:'v1', server:<pkg> }`) is surfaced on
+   `GET /public/status` (so the first-run probe recognizes the backend + reads its version in one call)
+   and on a new **DB-free `GET /public/version`** (canonical target for the version-mismatch guard +
+   a cheap liveness check). Swagger: `PublicVersion` schema. `test/publicVersion.test.js` covers both.
+5. **Docs** — update `docs/website/BACKEND_DESIGN.md` for any new/changed endpoint; keep this file and
+   the OpenAPI spec current. (The workspace `CLAUDE.md` is a **local, uncommitted** file — update it in
+   place as repos come online, but it is never committed.)
+6. **Branding for mobile.**
+   ✅ **DONE (2026-07-19, RunicGateway/website#77 (+ this docs PR)).** Confirmed
+   `GET /public/settings` returns the per-shard `brand` block (name, `accent` color, logo/hero/favicon,
+   plus shortName/tagline/description/url/contactEmail) sourced from `BRAND_*` with admin
+   `site_title`/`contact_email` overrides — the app themes itself from it. Made it first-class in the
+   OpenAPI contract (`Brand` + `PublicSettings` schemas) so the app's codegen gets typed branding
+   instead of an untyped map; `test/publicBrand.test.js` locks the contract. Asset fields may be
+   site-relative paths — the app resolves them against its stored base URL.
+
+No `link/` or `servuo-plugins/` changes are expected — the app is downstream of the website only.
+
+---
+
+## 9. Milestones
+
+**Two passes (§2.1).** M0–M4 were the **functional Kotlin pass** — every screen wired to its endpoints
+and working end-to-end with placeholder/functional Compose UI, no design investment yet. **M5 was the
+design pass**: with the functional Kotlin done, Claude Design produced the front-end design and Claude
+Code implemented the final UI to it. **Both passes are now complete** (M0–M5 landed); polish/release,
+push, and Play (M6–M8) follow the designed app.
+
+1. **M0 — Repo scaffold**: Gradle + Compose + Hilt skeleton, CI (build + lint + unit test), license
+   headers (GPL-3.0-or-later), CONTRIBUTING/AI-disclosure parity with the other repos.
+2. **M1 — Connect & browse** *(functional pass)*: first-run base-URL flow,
+   `/public/status`+`/public/settings` theming, generated API client, public content
+   (news/wiki/pages) + contact. No auth yet.
+3. **M2 — Public shard** *(functional pass)*: shard widgets + SSE live stream with
+   reconnect/degradation.
+4. **M3 — Auth (§4)** *(functional pass)*: native password+TOTP login (429 handling), token storage,
+   refresh interceptor, logout, `/auth/me` role re-validation, the access-level menu. Custom-Tab
+   **hand-offs** to the website for register / invite / password-reset / SSO (no native screens for
+   those). (An optional biometric app-lock was considered here, then descoped from v1 at M6.)
+   *Prerequisite:* the website password-reset flow (§8) is already built.
+5. **M4 — Player self-service & game data** *(functional pass)*: account management (via
+   `/auth/me/*`), game-account linking, own roster/characters/vendors/houses/sales — **text-only**
+   presentation (§6.3).
+6. **M5 — Design pass & final UI (§2.1)**: with the functional Kotlin from M1–M4 working end-to-end,
+   **Claude Design produces the front-end design** for the app, then **Claude Code implements the final
+   UI to it** — Compose screens, Material 3 theming from the per-shard branding (§3), reusable
+   components, loading/error/empty states, the designed access-level menu. Restyles the existing
+   screens only; no changes to architecture, data flow, or endpoint contracts. Text-only game data
+   (§6.3) still holds — this is visual design of the data screens, not paperdoll art. **Landed**
+   2026-07-20 (`RunicGateway/Android-app#10`): dark-only shard-website theme, Cinzel display face,
+   reusable pill/label/card/meter components; brand-accent seeding retained (see §9 build progress).
+7. **M6 — Polish & release mechanics**: settings (server switch = hard reset, done M3),
+   version-mismatch guard, release build hardening (HTTPS-only, no token logging, R8 minify + resource
+   shrink, release signing). No offline cache in v1 (§7). **Ships v1 as a signed APK attached to a Gitea
+   release** via `release.yml` on a `v*` tag (see §10). Biometric app-lock **descoped** (below).
+   **Landed** 2026-07-20 (`RunicGateway/Android-app#11`).
+8. **M7 — Push notifications** (post-v1): add the self-hosted `ntfy` service to
+   `website/docker-compose.yml` (declarative, zero-interaction config), UnifiedPush integration in the
+   app, device registration, the subscriptions UI, and the content-free-tickle backend fan-out (see
+   §11). The app is built with room for this from M0 but it does not gate the first release.
+   ✅ **Both parts landed** 2026-07-20 — Part 1 backend (`RunicGateway/website#78` merged + docs#20),
+   Part 2 app (`RunicGateway/Android-app#15`) + a small `push.ntfyUrl` settings addition
+   (`RunicGateway/website#79`). The app embeds its own ntfy distributor (a foreground-service SSE
+   connection, no second app, no Google Play Services, no UnifiedPush library); see the "M7 plan"
+   Part 2 block for the recorded transport + backend-field decisions. Push delivers once the shard sets
+   its `NTFY_*` deploy config (§13).
+9. **M8 — Google Play**: Play Console listing, signing/upload key, and (optionally) an FCM build flavor
+   — after the direct-APK release is stable.
+10. **M9 — Native SSO login** (post-v1, additive; independent of M8): in-app "Sign in with Google /
+    Discord" via the **Mobile SSO Authorization Bridge** (§4.2). **Backend-first**, mirroring M7's
+    split:
+    - **Part 1 — backend + docs (in progress):** `mobile_auth_sessions` + `mobile_auth_codes` bridge
+      tables; `GET /auth/mobile/sso/start` (seeds a bridge session, reuses the existing SSO redirect
+      tagged `mode:'mobile'`); a mobile branch in the SSO callback + TOTP-completion that mints a
+      single-use, hashed, PKCE-bound authorization code and redirects to the fixed app callback instead
+      of setting a cookie; `POST /auth/mobile/sso/exchange` (code + PKCE verifier → the existing mobile
+      bearer token pair); an exact-match redirect-URI allowlist; boot-time + opportunistic cleanup of
+      the bridge tables. Reuses `GET /auth/providers` for discovery and `POST /auth/mobile/{refresh,
+      logout}` unchanged. See `../website/BACKEND_DESIGN.md`.
+    - **Part 2 — app client:** register the `runicgateway://auth/callback` intent-filter; generate
+      `code_verifier`/`code_challenge` + `state`; open the Custom Tab at `/auth/mobile/sso/start`;
+      verify `state` on the callback; `POST …/exchange`; store the returned pair in the existing
+      `TokenStore` (M3). No new token-storage or refresh code — it feeds the M3 session machinery.
+    - **Follow-up — App Links (opt-in hardening on top of Part 2):** a website `GET
+      /.well-known/assetlinks.json` route behind the `mobile_app_links_enabled` admin toggle, a
+      self-origin HTTPS entry added to the redirect-URI allowlist when enabled, and an app-side
+      `autoVerify` intent-filter for `https://<host>/mobile/callback` driven by a **build-time**
+      `appLinkHost` (a single multi-tenant APK cannot autoVerify open-ended shard domains, so the
+      generic build stays custom-scheme; white-label/first-party builds bake one host). The custom
+      scheme remains the permanent fallback on every build. Full spec + rollout in
+      [`APP_LINKS.md`](./APP_LINKS.md).
+
+---
+
+## 10. Distribution
+
+- **v1: direct APK.** Build a signed release APK in CI and **attach it to a Gitea release** (mirrors
+  how `link/` cuts release binaries). Users sideload; the app already self-configures its server URL on
+  first run (§3), so one APK works for any shard. Keep a stable **upload/signing keystore** out of the
+  repo from day one — Play later requires a consistent signing identity.
+- **Later: Google Play.** Add a Play Console listing and (if using FCM) a `google-services` config as a
+  **build flavor**, so the direct-APK build stays Google-free. Versioning: semantic `versionName` +
+  monotonic `versionCode`; tag releases in the repo.
+
+## 11. Push notifications (built-for, shipped post-v1)
+
+The app is architected from M0 to accommodate push, but push itself ships in M7 — it does not block the
+first release. Users **opt in per stream**: nothing is pushed unless subscribed.
+
+### Transport — UnifiedPush via self-hosted ntfy (decided)
+- **Primary: UnifiedPush, delivered by a self-hosted `ntfy` service added to the website's
+  `docker-compose.yml`.** FOSS, no Google Play Services dependency, works for the sideloaded APK on any
+  device, and keeps delivery under the org's own infrastructure — consistent with the self-hosted ethos.
+- **The app embeds its own distributor — no second app (decided; see M7 Part 2 work item 1).** ntfy is
+  purely the relay *server*; the Runic Gateway app receives notifications itself via an in-app embedded
+  UnifiedPush distributor (a foreground-service persistent connection to the shard's ntfy). The user
+  installs one APK — never a separate distributor app — and no Google Play Services is involved.
+- **FCM stays optional and Play-only.** If/when a Play build wants it, add FCM as a **build flavor**;
+  the direct-APK flavor stays Google-free. The backend fan-out is **transport-agnostic** and dispatches
+  to whatever endpoint a device registered, so adding FCM later touches no core logic.
+
+### ntfy deployment — fully automated, zero interactive setup (hard requirement)
+- Runs as an **additional service in `website/docker-compose.yml`** (the compose *pulls* images and
+  never builds — ntfy is a pinned upstream image, so this fits that model). Confirm the exact image
+  path/tag at implementation.
+- **All config is declarative** — a committed `ntfy` config file and/or `NTFY_*` env vars baked into
+  compose. No `docker exec`, no interactive `ntfy user add`, no post-deploy manual steps. Bringing the
+  stack up provisions a working push relay. Reachable to devices via the existing reverse proxy on its
+  own hostname/path; internal-only for the backend publisher.
+- **No per-user ntfy accounts to administer.** The security model (below) removes the need for ntfy ACL
+  provisioning, which is exactly what keeps setup interaction-free. ntfy topics are the random,
+  unguessable endpoints UnifiedPush hands out; the backend treats ntfy as an **untrusted relay**.
+
+### Backend (additive, v1)
+- `POST /auth/me/devices` — register a device: `{ transport, endpoint, platform }` where `endpoint` is
+  the UnifiedPush/ntfy URL the distributor gave the app (or an FCM token for a Play/FCM build). `DELETE
+  /auth/me/devices/:id` — unregister. Devices belong to the authenticated user.
+- `GET /notifications/streams` — catalog of subscribable streams + which require a linked game account.
+- `GET|PUT /auth/me/notifications/subscriptions` — the user's selected streams (per-user; applied to
+  all their devices).
+- **Fan-out worker** hangs off the existing event dispatcher (`website` `utils/shardIngest.js`) — the
+  same event source that already feeds the SSE channels — matches events against subscriptions and
+  **publishes a content-free tickle** (see below) to each matching device's endpoint. Store endpoints
+  per device. Any secret (an ntfy publish token, or an FCM server key if that flavor is used) is
+  encrypted at rest via `utils/secretBox.js`, like the other secrets.
+
+### Stream catalog (initial)
+- **Public / opt-in** (no account needed): news posts, server up/down, IDOC warnings, champion-spawn
+  starts, governor elections.
+- **Personal** (require a linked game account; delivered only to the owner): *your* vendor sold an
+  item, *your* house entered IDOC, a login to *your* account.
+
+### Security boundary (hard requirement)
+The ntfy relay is treated as **untrusted infrastructure**, and the design makes that safe:
+
+- **Content-free tickles.** A push payload carries **no sensitive data** — only a stream id and an
+  opaque reference (e.g. `{ stream: "vendor.sale", ref: "…" }`). On receipt the app wakes and **pulls
+  the actual content over the authenticated, ownership-checked API** (`/auth/me/*`, `/player/shard/*`).
+  So even if an ntfy topic name leaked, nothing meaningful leaks with it, and no data reaches a device
+  that its user isn't already entitled to fetch. This is what lets ntfy be automated with no per-user
+  ACLs while still honoring the security rules.
+- **Same allowlist split as the SSE streams.** Sensitive kinds (staff audit, cheat detection, login
+  attempts, IPs) are never fanned out to push at all — the publisher applies the identical public/safe
+  allowlist used by the SSE dispatcher.
+- **Personal events are owner-keyed.** A personal tickle (your vendor sold, your house IDOC) is
+  published **only** to the endpoints of the owning user, decided by the same ownership check as the
+  `/player/shard/*` reads — a device never receives another user's events.
+- **Transport hardening.** ntfy served over TLS via the reverse proxy; the backend→ntfy publish is
+  internal. Endpoints are unguessable random topics; unregister on logout / token revocation.
+
+### App
+- A **Notifications** settings screen lists the catalog with per-stream toggles; personal streams are
+  disabled/greyed until the user has a linked game account. Registration happens after login; toggles
+  write to `/auth/me/notifications/subscriptions`. Tapping a notification deep-links to the relevant
+  screen (§ open item below).
+
+## 12. Build & CI (Gitea Actions)
+
+Builds run on the org's existing self-hosted runners (`runs-on: ubuntu-latest`, same label the other
+repos use), on a bare `ubuntu:latest` container.
+
+- **Toolchain:** JDK **17** (temurin) for Android Gradle Plugin 8.x; Android SDK installed in-CI via
+  `android-actions/setup-android@v3` (cmdline-tools + license acceptance). Cache `~/.gradle` and the SDK.
+- **Bare-image gotcha:** `ubuntu:latest` lacks `git`/`curl`/`unzip` that `actions/checkout` and
+  `sdkmanager` need — first step `apt-get install -y git curl unzip`. (Faster option once builds are
+  frequent: run the job under a prebuilt Android-SDK `container:` image so nothing installs per-run.)
+- **PR gate** (`.gitea/workflows/pr-checks.yml`, on PR → `main`): `./gradlew lint test assembleDebug`.
+  Debug builds are auto-signed, so the gate needs no secrets. Mirrors `website/`'s pre-merge gate.
+- **Release** (`.gitea/workflows/release.yml`, M6+): build a **signed release APK** and attach it to a
+  Gitea release (mirrors `link/`'s release job). The **keystore is a base64 Gitea Actions secret**
+  decoded in CI; store/key passwords are secrets. The keystore never lives in the repo. Keep the
+  signing identity stable from the first release (Play later requires consistency).
+- Semantic `versionName` + monotonic `versionCode`; tag releases.
+
+## 13. Open questions (revisit as we go)
+
+**Decided (recorded here for context):** single shard per install (§3); native auth is
+password+TOTP only, with registration/invite/reset/SSO **handled by the website** (§4); **password
+reset built on backend + web first**, before app work (§8); minSdk 29, compile/target 35 (§2); no
+telemetry in v1 (§2); strings externalized from day one, English-only bundled (§2); **text-only** game
+data in v1, pretty paperdoll is future (§6.3); **no offline cache in v1** (§7); push via self-hosted
+ntfy / UnifiedPush (§11) with the **distributor embedded in the app — no second app to install**
+(M7 Part 2 work item 1); **biometric app-lock descoped from v1** (tokens already encrypted at rest, so
+it is a UX convenience, not a v1 requirement — deferred at M3, descoped at M6; revisit only if requested).
+
+**Still open:**
+- **App identity / domain.** Target application ID **`com.runicgateway.app`** — pending securing the
+  `runicgateway.app` domain (needed for a verified app-link host and a matching package namespace). Also
+  the fixed launcher name (baked at build even though in-app branding is per-shard — one APK, any shard).
+  Since SSO/invite/reset are website-handled, the app mostly *opens* website URLs rather than needing its
+  own verified app links. **App Links resolved (M9 follow-up):** the SSO callback is the one place a
+  verified deep-link-back helps; the server side (`assetlinks.json` + toggle) ships for any shard, but
+  the app-side `autoVerify` needs a **literal build-time host**, so it is a white-label/first-party build
+  opt-in (`-PappLinkHost=<host>`) — the generic multi-tenant build stays custom-scheme. A canonical
+  `runicgateway.app` relay host, if secured, would let the generic build autoVerify one central domain.
+  See [`APP_LINKS.md`](./APP_LINKS.md).
+- ntfy: exact upstream image + pinned tag (Part-1 landed the compose service — confirm the tag), and
+  its reverse-proxy hostname/path. The hostname must land in `NTFY_ALLOWED_ORIGINS` before M7 Part 2 is
+  end-to-end testable (the app registers an endpoint on that origin; the SSRF guard rejects others). No
+  backend publish token — **decided** (the content-free-tickle design does not require one; optional
+  `NTFY_PUBLISH_TOKEN` is honored if ever set).
+- FCM flavor: build it for the Play release or ship Play on UnifiedPush too? Decide at M8. (The M7
+  Part 2 `PushTransport` seam keeps this swap cheap.)
+- Deep-link / share targets for wiki pages and posts (share/open-in-app). *Notification-tap* deep-links
+  are **resolved** for M7 Part 2 (stream→screen map, work item 7).
+- iOS: none planned (this is the Android-only choice); revisit only if cross-platform is later
+  required (would change §2 — and push, which would then favor a cross-platform transport).

android/theme-plan.md

@@ -0,0 +1,98 @@
+# Android theme plan — mirroring the website frontend
+
+This is a summary of the **website frontend theme** (source of truth:
+`website/client/src/styles/theme.css`, applied at runtime by
+`website/client/src/contexts/SiteContext.jsx`) so the native Android client can
+present a visually consistent brand. Where the web uses CSS custom properties,
+the Android equivalent is a Compose `MaterialTheme` `ColorScheme` + `Typography`.
+
+## Overall character
+
+A **dark, moody, "arcane fantasy" theme** — deep blue-black backgrounds, muted
+slate-blue accent, parchment-white text, and an engraved serif display face. It
+reads like a leather-and-moonlight fantasy ledger, not a bright consumer app.
+There is **no light mode** on the web; the app should ship dark-only to match.
+
+## Color tokens
+
+The web theme is a flat set of CSS variables under `:root`. Map them to Compose
+as follows (hex is authoritative):
+
+| Web token         | Hex        | Role                                   | Compose slot (suggested)      |
+|-------------------|------------|----------------------------------------|-------------------------------|
+| `--bg`            | `#0e1318`  | App background                          | `background`                  |
+| `--bg-deep`       | `#0b0f14`  | Deepest surface / on-accent text       | `surfaceDim` / `onPrimary`    |
+| `--panel-a`       | `#192231`  | Card gradient top                       | `surface`                     |
+| `--panel-b`       | `#141a21`  | Card gradient bottom                    | `surfaceContainer`            |
+| `--panel-flat`    | `#11161d`  | Flat panels, toolbars                  | `surfaceContainerLow`         |
+| `--line`          | `#2a3544`  | Borders / dividers                     | `outline`                     |
+| `--line-soft`     | `#1d2733`  | Subtle row dividers                    | `outlineVariant`              |
+| `--accent`        | `#7f99bd`  | **Primary accent** (brand-overridable) | `primary`                     |
+| `--accent-bright` | `#cdd9e8`  | Primary button fill, active states     | `primaryContainer` / bright   |
+| `--ink`           | `#eef3f8`  | Highest-contrast text                  | `onBackground`                |
+| `--head`          | `#e6edf6`  | Headings                               | heading color                 |
+| `--text`          | `#c4cdd8`  | Body prose                             | `onSurface`                   |
+| `--muted`         | `#aeb8c4`  | Secondary text                         | `onSurfaceVariant`            |
+| `--dim`           | `#6f7d8e`  | Meta / captions / placeholders         | dim / disabled text           |
+| `--blue`          | `#13243c`  | Accent hover/active background         | `secondaryContainer`          |
+| `--mode-live`     | `#5fb98a`  | "Shard live" status (green)            | success                       |
+| `--mode-maint`    | `#e6c26a`  | "Maintenance" status (amber)           | warning                       |
+
+### Semantic / status colors (used in badges, diffs, moderation)
+
+- **Success / published / live:** green `#5fb98a` (fills at ~16–22% alpha, text `#7fd0a4`).
+- **Warning / maintenance / moderation (kick/mute/warn):** amber `#e0b070` / `#e6c26a`.
+- **Danger / ban / red-link / errors:** desaturated red `#d98b84` (borders `#6e3b38`).
+- **Admin badge:** near-white `#d8e2ef` on `#3a4a5e`.
+
+## Branding is data, not code
+
+The `--accent` value is **overridden at runtime** per shard instance. On the web,
+`SiteContext` reads `brand.accent` from the site settings API and sets the CSS
+variable, so one build reskins for any shard. **The Android app should do the
+same:** fetch the brand payload (name, `accent`, colors, logo/hero/favicon) from
+the website API and derive the `primary` color at runtime rather than hardcoding
+`#7f99bd`. Default to `#7f99bd` when the brand payload is absent/offline.
+
+## Typography
+
+Three font families, by role:
+
+- **Display** (`--display`): **Cinzel**, falling back to Georgia serif — an
+  engraved Roman capitals face used for the logo, `h1`/`.h1`, and prose
+  `h2`/`h3`. Bundle Cinzel as an app font; this face carries the brand.
+- **Serif body** (`--serif`): **Georgia / Times New Roman** — default body and
+  prose text; `line-height ≈ 1.6`.
+- **Sans** (`--sans`): **Helvetica Neue / Arial** — UI chrome: buttons, pills,
+  form labels, table headers, badges, meta. Labels/eyebrows/kickers are
+  UPPERCASE with wide letter-spacing (`0.1–0.18em`) and small (0.68–0.86rem).
+
+Heading scale is fluid on web (`h1` clamps ~2.4–3.6rem); pick fixed Material type
+scale equivalents (e.g. display for `h1`, headline for `h2`, title for `h3`).
+
+## Shape, elevation & motion
+
+- **Corners:** cards/panels `10–12px` radius; inputs/small elements `8px`;
+  pills and buttons are **fully rounded** (`999px` / capsule).
+- **Cards:** vertical gradient `--panel-a → --panel-b`, 1px `--line` border, soft
+  drop shadow (`0 14px 34px rgba(0,0,0,0.3)`). On hover the web lifts `-3px` and
+  brightens the border to `--accent` — translate to a pressed/focused accent
+  border on Android.
+- **Buttons:** primary = bright fill (`--accent-bright`) with dark text;
+  ghost/secondary = translucent dark fill with accent-on-hover border.
+- **Motion:** short, subtle transitions (0.12–0.18s). Keep animations understated.
+
+## Signature accents (nice-to-have)
+
+- The **"moon"** motif: a radial-gradient sphere (`#eef3f8 → #9fb0c6 → #5d6e88`) —
+  a small brand flourish worth reproducing.
+- Accent-tinted focus rings and left-border "note" callouts
+  (`border-left: 3px solid --accent` over a translucent `--blue` background).
+
+## Implementation note for Compose
+
+Define one `darkColorScheme(...)` from the table above, a `Typography` binding the
+three families, and a `Shapes` set (`small = 8.dp`, `medium = 10.dp`, capsule for
+buttons). Load `accent` from the brand API into a state holder and rebuild the
+`primary` (and derived `primaryContainer`) at runtime so a shard's custom accent
+flows through the whole UI — exactly as `SiteContext` does on the web.

ci/SONARQUBE.md

@@ -0,0 +1,64 @@
+# SonarQube static analysis
+
+Each code repo in the Runic Gateway org reports static-analysis results to the
+self-hosted **SonarQube** server for review. Analysis is **non-blocking**: it
+runs on push to `main` (i.e. *after* merge), never on pull requests, so it never
+gates a PR. It complements each repo's PR gate and release pipeline — it only
+feeds the dashboard.
+
+## Server
+
+- **URL:** `https://sonar.whitlocktech.com`
+- Each repo is a separate SonarQube project, keyed as below.
+
+## Projects
+
+| Repo | Project key | Sources analysed | Language |
+|---|---|---|---|
+| `website` | `runic-gateway-website` | `server/src`, `client/src`, `bot/src` | JS/TS |
+| `link` | `Runic-Gateway-link` | `sidecar/src` | Rust |
+| `Android-app` | `Runic-Gateway-Android-app` | `app/src/main` | Kotlin |
+
+> Project keys are **case-sensitive** and must match what already exists on the
+> server — SonarQube refuses to create a key that differs only in case from an
+> existing one. `link` and `Android-app` reuse the pre-existing capitalised keys
+> above; `website` predates this note with its lower-case key.
+
+## How it's wired
+
+Each repo carries two files, identical in shape across repos:
+
+- **`sonar-project.properties`** (repo root) — declares the project key, sources,
+  tests, and exclusions. The Sonar scanner reads this.
+- **`.gitea/workflows/sonarqube.yml`** — a `SonarQube` workflow that, on push to
+  `main` (and via manual `workflow_dispatch`), checks out with full history
+  (`fetch-depth: 0`, needed for accurate blame + "new code") and runs
+  `sonarsource/sonarqube-scan-action@v4`.
+
+The scan is **source-based** — it does not build the project or run a language
+toolchain, so the workflows are lightweight (checkout + scan only). Richer
+signals (Rust Clippy, Android Lint, JaCoCo coverage) are left as documented,
+commented-out enrichment in each repo's `sonar-project.properties`; enable them
+per repo when wanted.
+
+## One-time setup per repo (Gitea UI → Repo → Settings → Actions)
+
+Both are consumed by the scan action via `env:` in the workflow:
+
+- **Secret `SONAR_TOKEN`** — a SonarQube *Analysis* token (My Account →
+  Security in SonarQube; project-scoped or global).
+- **Variable `SONAR_HOST_URL`** — the SonarQube base URL reachable from the
+  self-hosted runner. Kept as a **variable, not committed**, so the internal
+  address stays out of git.
+
+The self-hosted `ubuntu-latest` runner must be able to reach `SONAR_HOST_URL` on
+the network. Nothing waits on the SonarQube Quality Gate, so a failing gate does
+not fail the job — check the dashboard.
+
+## Adding a new repo
+
+1. Create the project in SonarQube; note its key.
+2. Add `sonar-project.properties` (copy an existing repo's, adjust key + sources).
+3. Add `.gitea/workflows/sonarqube.yml` (copy verbatim — it's language-agnostic).
+4. Set the `SONAR_TOKEN` secret and `SONAR_HOST_URL` variable in the repo's
+   Gitea Actions settings.

website/BACKEND_DESIGN.md

@@ -142,6 +142,87 @@ Seeded keys: `site_mode` (default `maintenance`), `site_mode_changed_at`,
 | ip | VARCHAR(45) NULL | from `req.ip` (needs `trust proxy`) |
 | created_at | DATETIME DEFAULT CURRENT_TIMESTAMP | |
 
+### password_resets  — self-service reset links
+| col | type | notes |
+|---|---|---|
+| id | INT PK AUTO_INCREMENT | |
+| token_hash | CHAR(64) UNIQUE NOT NULL | sha256 hex of the opaque token; **plaintext never stored** |
+| user_id | INT NOT NULL FK→users(id) ON DELETE CASCADE | the account this reset targets |
+| status | ENUM('pending','used') DEFAULT 'pending' | single-use (atomic `markUsed`) |
+| requested_ip | VARCHAR(64) NULL | who asked (audit only) |
+| expires_at | DATETIME NOT NULL | ~1h TTL, enforced in the model on top of this |
+| created_at / used_at | DATETIME | |
+
+Same "store only the hash of an opaque token" pattern as `user_invites` / `mobile_refresh_tokens`.
+A DB read never yields a usable reset link. See §4 `/auth/password/*`.
+
+### push_devices  — opt-in push endpoints (M7)
+| col | type | notes |
+|---|---|---|
+| id | INT PK AUTO_INCREMENT | |
+| user_id | INT NOT NULL FK→users(id) ON DELETE CASCADE | owner |
+| transport | ENUM('unifiedpush','fcm') DEFAULT 'unifiedpush' | UnifiedPush for the sideloaded APK; FCM reserved for a later Play flavor |
+| endpoint | VARCHAR(512) NOT NULL | the distributor URL the app's ntfy topic was handed (or an FCM token). Unguessable but **not a secret** — stored in the clear (unlike refresh tokens), because pushes are content-free tickles |
+| platform | VARCHAR(40) NULL | free-form label, e.g. `android` |
+| created_at / last_seen_at | DATETIME | |
+
+`UNIQUE(user_id, endpoint)` — re-registering the same endpoint is an idempotent upsert.
+
+### notification_subscriptions  — which streams a user opted into (M7)
+| col | type | notes |
+|---|---|---|
+| user_id | INT NOT NULL FK→users(id) ON DELETE CASCADE | |
+| stream_id | VARCHAR(64) NOT NULL | an id from the catalog (`config/notificationStreams.js`), validated on write |
+| created_at | DATETIME | |
+
+`PRIMARY KEY(user_id, stream_id)`. Subscriptions are per-user (applied to every device); a PUT
+replaces the whole set. Nothing is pushed unless the user subscribed.
+
+### mobile_auth_sessions / mobile_auth_codes  — mobile SSO bridge (M9)
+
+Two short-lived, self-pruning tables that bridge a browser SSO redirect flow to a native client. They
+carry the **app ↔ website** PKCE + CSRF state (a *second* PKCE layer, distinct from the website ↔ IdP
+PKCE the `sso_tx` cookie already carries) and the one-time authorization code the app exchanges for
+bearer tokens. Neither holds a secret in the clear — the PKCE `code_challenge` is a hash by
+construction, and the authorization code is stored as a **sha256 hash only** (same pattern as
+`user_invites` / `password_resets` / `mobile_refresh_tokens`).
+
+`mobile_auth_sessions` — one row per `/auth/mobile/sso/start`:
+
+| col | type | notes |
+|---|---|---|
+| id | INT PK AUTO_INCREMENT | |
+| session_id | CHAR(36) UNIQUE | opaque uuid; carried inside the signed `sso_tx` (mode `mobile`) so the callback can find this row |
+| provider | VARCHAR(40) NOT NULL | provider id validated enabled at `/start` |
+| code_challenge | VARCHAR(255) NOT NULL | app-supplied PKCE S256 challenge (base64url); verified at `/exchange` |
+| redirect_uri | VARCHAR(255) NOT NULL | the requested app callback — **exact-match** against the allowlist (never prefix) |
+| state | VARCHAR(255) NOT NULL | app-generated opaque CSRF value, echoed on the callback for the app to verify |
+| status | ENUM('pending','completed','consumed') DEFAULT 'pending' | `pending`→`completed` when the code is minted; `consumed` after a successful exchange |
+| user_id | INT NULL FK→users(id) ON DELETE CASCADE | set once SSO resolves the account |
+| expires_at | DATETIME NOT NULL | short (~10 min — one redirect round-trip incl. TOTP) |
+| created_at / used_at | DATETIME | `used_at` stamped at exchange |
+
+`mobile_auth_codes` — one row per completed SSO callback (the code the app redeems):
+
+| col | type | notes |
+|---|---|---|
+| id | INT PK AUTO_INCREMENT | |
+| code_hash | CHAR(64) UNIQUE | sha256 hex of the opaque ≥128-bit code; the raw code never touches the DB |
+| user_id | INT NOT NULL FK→users(id) ON DELETE CASCADE | the authenticated account |
+| session_id | CHAR(36) NOT NULL | the owning `mobile_auth_sessions.session_id` (ties the code to its PKCE challenge) |
+| expires_at | DATETIME NOT NULL | very short (~5 min) |
+| used_at | DATETIME NULL | set on first successful exchange — **single use** (a reused code fails) |
+| created_at | DATETIME | |
+
+Both self-prune (indexed `expires_at`): a best-effort sweep runs at boot beside the existing
+`revoked_sessions` prune, and each bridge write opportunistically deletes expired rows — so no cron
+infra is added (same approach as `revoked_sessions`).
+
+**`mobile_refresh_tokens` additions (M9).** Two nullable columns are added to support the device
+list/revoke surface: `device_name VARCHAR(100) NULL` (a friendly label) and `last_used_at DATETIME
+NULL` (bumped on each refresh). Existing rows get them via the schema's ALTER section; the token model
+is otherwise unchanged.
+
 ---
 
 ## 4. API contract
@@ -154,16 +235,121 @@ accepts `Authorization: Bearer` for API testing).
 |---|---|---|---|---|
 | POST | `/login` | — (rate-limited) | `{username,password}` | verify, set cookie, log `auth.login`, update `last_login_at` |
 | POST | `/logout` | cookie | — | clear cookie |
-| GET | `/me` | cookie | — | current user (no hash) or 401 — client bootstraps auth state |
+| GET | `/me` | cookie / bearer | — | current user (no hash) or 401 — client bootstraps auth state |
+| POST | `/password/forgot` | — (rate-limited) | `{email}` | email a single-use, ~1h reset link to **every active account** on the address; **always** returns the same generic 200 (no account enumeration). Email is non-unique, so several accounts may each get a link naming their username. Logs `account.password.reset.request`. |
+| GET | `/password/reset/:token` | — | — | validate a link → `{username}` for the form, else 404 (never distinguishes expired/used/never-existed) |
+| POST | `/password/reset/:token` | — (rate-limited) | `{password}` | consume the single-use link, rotate the hash, and revoke **all** sessions (web cutoff + mobile refresh tokens). Does **not** sign the user in — they log in fresh (so a 2FA account still passes TOTP). Logs `account.password.reset.complete`. |
+| GET | `/me/account` | cookie / bearer | — | full self account (`id, username, role, email, status, totp_enabled, has_password`) |
+| PATCH | `/me/account/username` | cookie / bearer (rate-limited) | `{username}` | change own username; re-issues the caller's session |
+| PATCH | `/me/account/password` | cookie / bearer (rate-limited) | `{newPassword, currentPassword?}` | change/set own password (current required unless the account has none); revokes other sessions, keeps the caller's |
+| POST | `/me/account/totp/setup` · `…/enable` · `…/disable` | cookie / bearer | `{code}` on enable/disable | self 2FA enrollment (disable needs a valid current code, not a password) |
+| GET | `/me/account/identities` · DELETE `…/:provider` | cookie / bearer | — | list / unlink own SSO identities |
+| POST | `/me/devices` | cookie / bearer | `{endpoint, transport?, platform?}` | register a push endpoint; **rejects a disallowed endpoint 400** (SSRF guard). Idempotent per (user, endpoint) |
+| GET | `/me/devices` · DELETE `…/:id` | cookie / bearer | — | list / unregister own push devices |
+| GET | `/me/notifications/streams` | cookie / bearer | — | the subscribable catalog (`personal`/`requiresLinkedAccount` flags) |
+| GET · PUT | `/me/notifications/subscriptions` | cookie / bearer | `{streams:[id]}` on PUT | get / replace own opted-in streams (unknown ids dropped) |
 
-No public `register`. First admin is bootstrapped by `seed.js` from env (see §6). Further
-admins are created under `/admin/users`.
+**Role-agnostic self-service (`/auth/me/*`).** The canonical "me" surface for **every** authenticated
+role. It reuses the exact `account.controller` handlers as `/player/account/*` and `/admin/account/*`
+(no logic duplication) behind `requireAuth` **only** — any active account, never a specific role. This
+lets a client (the Android app) manage its own account through one surface without ever touching
+`/admin` (docs/android/PLAN.md §6.4). The older `/player/account/*` + `/admin/account/*` routes stay
+for web back-compat.
+
+**Password reset.** Uses the same audited pattern as `user_invites`: an opaque 32-byte token
+whose **sha256 hash only** is stored in `password_resets`, single-use and short-lived (~1h). It
+also serves SSO-only accounts (null `password_hash`) as their "set an initial password" path. The
+reset link points at the web front end (`/account/reset/:token`); the Android app hands off here
+rather than shipping its own reset screen (docs/android/PLAN.md §4.2). First admin is bootstrapped
+by `seed.js` from env (see §6); further staff are created under `/admin/users` or via email invites.
+
+**Push notifications (M7, opt-in).** The app subscribes per stream (`/auth/me/notifications/*`) and
+registers device endpoints (`/auth/me/devices`); nothing is pushed unless subscribed. Delivery is a
+**content-free tickle** — `{ stream, ref }`, no sensitive data — POSTed to each subscribed device's
+self-hosted **ntfy** endpoint (`utils/pushDispatch`); the app wakes and pulls the real, ownership-
+checked content over the authenticated API. Two producers fan out through the one publisher: the shard
+ingest dispatcher (`utils/shardIngest`, beside the SSE broadcast) for shard-derived streams, and the
+create/publish-post path for `news.post`. The stream catalog + event→stream mapping is
+`config/notificationStreams.js`. Security invariants:
+- **Same public/admin split as the SSE feed.** Public streams are drawn *only* from the SSE
+  `PUBLIC_KINDS` allowlist; a sensitive kind (audit/cheat/IP/login-attempt) can never produce a public
+  push.
+- **Personal streams are owner-keyed.** `vendor.sale` / `house.idoc` / `account.login` are delivered
+  only to the *owning* user's devices, resolved via `shardLinks` (the same ownership check as
+  `/player/shard/*`).
+- **SSRF guard.** A device `endpoint` is a client-supplied URL the server POSTs to, so registration and
+  every publish validate it is HTTPS, non-private/loopback, and (when configured) on the shard's ntfy
+  allow-set (`NTFY_BASE_URL` / `NTFY_ALLOWED_ORIGINS`).
+- ntfy is treated as an **untrusted relay** — no per-user accounts, unguessable topics; an optional
+  `NTFY_PUBLISH_TOKEN` hardens backend→ntfy publishes but is not required. See docs/android/PLAN.md §11.
+
+### Mobile SSO Authorization Bridge (`/auth/mobile/sso/*`, M9)
+
+Native "Sign in with Google/Discord" for the Android app **without shipping any OAuth secret in the
+app**. The website stays the identity authority: each shard owner's provider credentials live in
+`auth_providers` (encrypted at rest) and are only ever used server-side. The bridge is a **new
+consumer of the existing SSO + mobile-bearer machinery**, not a parallel auth path — it reuses the
+`/auth/sso/:provider/*` redirect flow, the link-only + opt-in-provisioning policy, the TOTP gate, and
+issues the **same** token pair as `/auth/mobile/login`.
+
+| Method | Path | Auth | Body / Query | Purpose |
+|---|---|---|---|---|
+| GET | `/auth/providers` | — | — | **reused** discovery; the app renders provider buttons from this (never exposes secrets) |
+| GET | `/auth/mobile/sso/start` | — (rate-limited per-IP + per-provider) | `?provider&code_challenge&state&redirect_uri` | validate provider enabled + `redirect_uri` **exact-match** allowlist; insert a `mobile_auth_sessions` row; create the existing `sso_tx` tagged `mode:'mobile'` carrying `session_id`; **302 to the IdP** (existing authorize URL) |
+| GET | `/auth/sso/:provider/callback` | — (signed `sso_tx`) | `?code&state` | **existing** endpoint; a new branch when `tx.mode==='mobile'`: resolve the account (same policy as web login incl. TOTP), mint a single-use hashed authorization code into `mobile_auth_codes`, mark the session `completed`, and **302 to `redirect_uri?code=…&state=…`** (the app's original `state`) — **no cookie is set** |
+| POST | `/auth/mobile/sso/exchange` | — (rate-limited per-IP) | `{code, code_verifier}` | validate the code exists / unexpired / unused (mark used) and `sha256(code_verifier)` matches the stored challenge → issue the existing mobile access + refresh pair (`createMobileSession`) → `{accessToken, refreshToken, expiresIn, user}` |
+| POST | `/auth/mobile/refresh` | — | `{refreshToken}` | **reused** unchanged — rotate the pair |
+| POST | `/auth/mobile/logout` | bearer | `{refreshToken?, all?}` | **reused** unchanged — revoke this (or all) refresh token(s) |
+| GET | `/auth/me/sessions` · DELETE `…/:id` | cookie / bearer | — | list / revoke own **mobile sessions** (device_name, last_used_at, created_at) — the "Active Devices" surface (distinct from `/auth/me/devices`, which is push endpoints) |
+
+**Two PKCE layers (do not conflate).**
+- *Layer A (existing):* website ↔ IdP. The `code_verifier` is generated at `/start`, kept only in the
+  httpOnly `sso_tx` cookie, sent to the IdP token endpoint at the callback. Unchanged.
+- *Layer B (new):* app ↔ website. The **app** generates `code_verifier`/`code_challenge`; the
+  challenge is stored in `mobile_auth_sessions` at `/start`; the verifier is presented at `/exchange`.
+  This is what stops an intercepted callback code from being redeemed by anyone but the real app.
+
+**State / CSRF.** The app-generated `state` is stored at `/start`, echoed on the callback redirect,
+and **verified by the app** before it calls `/exchange` — a CSRF guard independent of both PKCE
+layers (a different app instance triggering `/start` cannot complete someone else's flow).
+
+**Redirect-URI allowlist.** `/start` and the callback validate `redirect_uri` by **exact match**
+against a configured allowlist (`MOBILE_AUTH_REDIRECT_URIS`, default the one fixed application-owned
+callback `runicgateway://auth/callback`) — **never prefix match** (prefix matching on custom schemes
+is a known open-redirect vector). Tokens are **never** placed in the callback URL — only the
+short-lived authorization code.
+
+*App Links (implemented).* When the admin toggle `mobile_app_links_enabled` is **on**, `/start` also
+accepts the self-origin HTTPS callback `https://<request-host>/mobile/callback` — one *additive*
+exact-match entry, derived from the request/`APP_BASE_URL` and never from client input; the
+custom-scheme allowlist is never narrowed. The shard then auto-serves `GET
+/.well-known/assetlinks.json` (fixed package `com.runicgateway.app` + `MOBILE_APP_CERT_SHA256`
+fingerprints; 404 when the toggle is off or no fingerprint is configured), and
+`settings.getPublic()` advertises `mobileAppLinks: <bool>`. These two things — one static file route
+and one more allowlist entry — are the *entire* server surface App Links require. See
+docs/android/APP_LINKS.md.
+
+**TOTP through the bridge.** A 2FA account keeps full parity: the callback stages the existing
+pending-TOTP cookie (now also carrying the bridge `session_id`) and bounces the Custom Tab through the
+web TOTP form; on a correct code the completion mints the authorization code and deep-links back to
+the app — it never mints a session cookie for a mobile flow.
+
+**Revocation latency (documented tradeoff).** Revoking a refresh token (device revoke / logout) stops
+future renewals but does **not** invalidate an already-issued access token until it expires — up to
+the access-token lifetime (`MOBILE_ACCESS_TTL`, default 15 min) of continued access. This is an
+accepted tradeoff given the short lifetime. If instant revocation is ever required, add an
+access-token (jti) blocklist check on the `requireAuth` path — the same `revoked_sessions` mechanism
+web sessions already use.
+
+**Authorization code.** Cryptographically random, ≥128 bits, stored **hash-only**, single-use, short
+expiry (~5 min); `/exchange` is rate-limited per-IP. The bridge tables self-prune (§3).
 
 ### /public  (public.routes.js → public.controller.js) — all GET, no auth
 | Method | Path | Notes |
 |---|---|---|
-| GET | `/settings` | whitelisted public keys only (mode, maintenance_message, status_message, homepage_teaser, contact_email, site_title) |
-| GET | `/status` | status message + current mode |
+| GET | `/settings` | whitelisted public keys, derived `registration`/`gameAccountSignup` flags, the per-shard **`brand`** block (name, `accent` color, logo/hero/favicon) a client themes itself from — one image runs as any shard, asset fields may be site-relative paths (resolve against the base URL) — and a **`push`** block `{ ntfyUrl }` (M7): the client-facing ntfy relay URL the app's embedded distributor registers its device topic against, from `NTFY_PUBLIC_URL` / first `NTFY_ALLOWED_ORIGINS` (never the internal `NTFY_BASE_URL`); `null` when push isn't configured for the shard. |
+| GET | `/status` | status message + current mode, **plus a `version` block** (`{ service:'runic-gateway', api, server }`) so a client first-run probe recognizes the backend and can run a version-mismatch guard |
+| GET | `/version` | lightweight, **DB-free** backend identity/version (`{ service, api, server }`) — the canonical target for the version guard and a cheap liveness check |
 | GET | `/posts/:category` | published only; `category` ∈ news\|five-on-friday\|newsletter\|screenshots |
 | GET | `/posts/:category/:idOrSlug` | single published post |
 | GET | `/wiki` | list of pages (slug + title) |
@@ -223,7 +409,19 @@ who"; `activity_log` provides the history feed.
 - **bcrypt** hashing (cost 10+); plaintext passwords never stored, logged, or returned.
 - **Rate limiting** (`express-rate-limit`) on `/auth/login` and `/public/contact`.
 - **Validation** (`express-validator`) on all writes; centralized error handler.
-- **helmet** with a CSP suited to the SPA (self + inline styles as needed; image sources for uploads/hero).
+- **helmet** with a Content-Security-Policy tuned for the built React SPA (see `server/src/app.js`):
+  `default-src 'self'`; `script-src 'self'` (the Vite build emits only external module chunks — the
+  inline module-preload polyfill is disabled in `client/vite.config.js` to keep this valid);
+  `style-src 'self' 'unsafe-inline' https://fonts.googleapis.com` (React's pervasive inline
+  `style={{…}}` attributes can't be nonce'd, plus the Google Fonts stylesheet); `font-src 'self'
+  https://fonts.gstatic.com` (Cinzel); `img-src 'self' data: https:` (same-origin uploads, plus
+  external https images embedded in wiki/news bodies or `BRAND_*` logo/hero/favicon); `connect-src
+  'self'` (REST + SSE are same-origin); `frame-ancestors 'self'`; `object-src 'none'`; `base-uri
+  'self'`. `upgrade-insecure-requests` is intentionally **not** set (TLS terminates at the proxy, there
+  are no mixed-content subresources, and it would break a local `npm start` over plain http). The
+  `/api/docs` Swagger UI route gets a **looser** policy that additionally allows inline script/style,
+  since swagger-ui-express injects an inline bootstrap. helmet also strips `X-Powered-By`; the two
+  internal-only listeners (`internalApp.js`, `bot/src/app.js`) disable it explicitly too.
 - **Admin not indexed**: `X-Robots-Tag: noindex, nofollow` on `/api/v1/admin` and the admin SPA routes; `robots.txt` disallows `/admin`.
 - **No directory browsing** (express.static doesn't list; no `serve-index`).
 - **No hardcoded credentials**: first admin via `seed.js` reading `ADMIN_USERNAME`/`ADMIN_PASSWORD` from env (created only if no users exist); `.env` git-ignored, `.env.example` committed.
@@ -270,7 +468,13 @@ subsystem (`[server]`, `[http]`, `[db]`, `[auth]`, `[admin]`, `[ratelimit]`, …
 - `app`: builds the Dockerfile (installs client+server, builds Vite, serves via Express),
   `env_file: .env`, `DB_HOST=db`, `depends_on: db (healthy)`, volume `uploads:/app/uploads`,
   `ports: "3000:3000"` — **binds 0.0.0.0** (no `127.0.0.1:` prefix) so Pangolin reaches it.
-- Volumes: `dbdata`, `uploads`.
+- `ntfy` (M7): pinned upstream `binwiederhier/ntfy` image, declarative config only
+  (`./ntfy/server.yml` mounted `:ro` + `NTFY_BASE_URL`), volume `ntfydata:/var/lib/ntfy`, **no
+  published host port** — devices reach it via the reverse proxy; the backend publisher reaches it
+  over the private compose network. Anonymous read-write to unguessable topics (no accounts to
+  provision) — safe because pushes are content-free tickles. Bringing the stack up provisions a
+  working push relay with **zero interactive setup**.
+- Volumes: `dbdata`, `uploads`, `ntfydata`.
 
 Express listens on `0.0.0.0:${PORT||3000}`. Pangolin terminates TLS and proxies to `app`.
 
@@ -292,6 +496,16 @@ ADMIN_USERNAME=
 ADMIN_PASSWORD=
 # Email: configured in Admin → Settings → Email (Gmail OAuth2), not via env
 CLIENT_ORIGIN=http://localhost:5173
+# Push (M7): the ntfy relay URL — also the backend's SSRF allow-set for device
+# endpoints. NTFY_ALLOWED_ORIGINS / NTFY_PUBLISH_TOKEN are optional.
+NTFY_BASE_URL=https://ntfy.example.com
+# The client-facing ntfy URL surfaced to the app via /public/settings.push.ntfyUrl
+# (the app registers its topic endpoint here). Defaults to the first
+# NTFY_ALLOWED_ORIGINS entry; set explicitly when the public URL differs from the
+# internal NTFY_BASE_URL. Without it (and without NTFY_ALLOWED_ORIGINS) the app
+# shows push as unavailable for the shard.
+NTFY_PUBLIC_URL=https://ntfy.example.com
+NTFY_ALLOWED_ORIGINS=https://ntfy.example.com
 ```
 
 `.gitignore`: `node_modules/`, `.env`, `_reference/`, `client/dist/`, `uploads/`.

website/MODERATION_APPEALS.md

@@ -0,0 +1,128 @@
+# Runic Gateway Website — Moderation Appeals (Phase 6c/6d)
+
+> Website feature branch: **`feature/moderation-appeals`**. Builds on the moderation
+> dashboard (Phase 6a/6b) and the Discord bot's `mod_actions` log. Companion to
+> [website-README.md](website-README.md) (overview) and
+> [BACKEND_DESIGN.md](BACKEND_DESIGN.md) (base API contract).
+
+## 1. Overview
+
+A player whose linked Discord identity was **banned** or **muted** — an action
+recorded in the bot's `mod_actions` log — can open an **appeal** from the player
+portal and track its status. Staff (**admin** or **moderator** role) work the
+appeal from an **appeals queue** in the admin moderation section: claim it, then
+resolve it **approved** or **denied** with a written staff response.
+
+When staff **approve** a ban/mute appeal, the website makes a best-effort call to
+the Discord bot's internal API to actually lift the ban / clear the timeout in
+Discord, and the bot posts a mod-log embed ("Appeal approved"). This is
+**best-effort**: if the bot is unreachable the appeal still resolves as approved,
+the reversal is recorded as failed, and staff can reverse the sanction manually in
+Discord.
+
+Only **ban** and **mute** actions are appealable — the sanctions that have an
+ongoing effect. Warnings/kicks and similar one-shot actions are not.
+
+## 2. Ownership & eligibility
+
+- **`appeals` is a server-owned table** — only the website reads/writes it. It
+  references the bot-owned `mod_actions` log by a plain id column
+  (`mod_action_id`); there is **no hard cross-owner foreign key** between the two
+  databases, so the reference is validated in application code (same pattern as
+  the rest of the uo-link / bot integration, where the two services never share a
+  live FK).
+- **Eligibility** — the appellant must be a **logged-in player** whose linked
+  Discord identity (`user_identities`, `provider = 'discord'`) matches the
+  `mod_actions` row's target. A player cannot open an appeal for someone else's
+  action, and an unlinked player has nothing eligible to appeal.
+- **One active appeal per action** — only one `pending` / `under_review` appeal is
+  allowed for a given `mod_action_id` at a time; a second attempt while one is
+  already open is rejected.
+
+## 3. Appeal lifecycle
+
+```
+pending ──▶ under_review ──▶ approved
+                          └─▶ denied
+
+pending ──▶ withdrawn
+under_review ──▶ withdrawn
+```
+
+- **`pending`** — submitted by the player, not yet claimed.
+- **`under_review`** — claimed by a staffer (the claiming admin/moderator is
+  stamped on the row).
+- **`approved`** / **`denied`** — resolved by staff with an optional
+  `staff_response`. Approving a ban/mute appeal triggers the Phase 6d reversal
+  (§5).
+- **`withdrawn`** — the player pulled the appeal back before it was resolved.
+
+`reversal_status` (only meaningful on an approved ban/mute appeal) is one of
+`none` (not attempted / not applicable), `done`, or `failed`. No new
+`mod_actions` row is written for a reversal — it modifies the *original* action's
+standing rather than logging a new one.
+
+## 4. API — player (role: `player`)
+
+Base `/api/v1/player/appeals`.
+
+| Method | Path | Purpose |
+|---|---|---|
+| GET | `/player/appeals` | The caller's own appeals. |
+| GET | `/player/appeals/eligible` | The caller's ban/mute actions with no active appeal (empty if they have no linked Discord identity). |
+| POST | `/player/appeals` | Open an appeal — `{ mod_action_id, submitted_text }`. `403` if the action isn't the caller's, `400` if the action isn't a ban/mute, `409` if one is already open for it. |
+| POST | `/player/appeals/:id/withdraw` | Withdraw an appeal that hasn't been resolved yet. |
+
+## 5. API — staff (role: `admin` or `moderator`)
+
+Base `/api/v1/admin/moderation/appeals`, alongside the existing moderation
+section.
+
+| Method | Path | Purpose |
+|---|---|---|
+| GET | `/admin/moderation/appeals?status=&limit=&offset=` | The queue. Defaults to `pending` + `under_review`; pass `status=all` or a specific status to filter. |
+| GET | `/admin/moderation/appeals/:id` | One appeal. |
+| POST | `/admin/moderation/appeals/:id/claim` | `pending` → `under_review`, stamping the claiming staffer. |
+| POST | `/admin/moderation/appeals/:id/resolve` | `{ status: 'approved' \| 'denied', staff_response? }`. On an approved ban/mute, triggers the Discord reversal (§6). |
+| GET | `/admin/moderation/user/:discordId/appeals` | A user's appeals — shown as a tab on the per-user moderation history page. |
+
+`resolve` returns a `reversal` object describing what happened:
+
+```jsonc
+{
+  "reversal": {
+    "attempted": true,
+    "ok": true,
+    "reversal_status": "done",   // "none" | "done" | "failed"
+    "bot_status": 200,
+    "error": null
+  }
+}
+```
+
+## 6. Auto-reversal (Phase 6d)
+
+On `resolve` with `status: 'approved'` against a ban/mute appeal, the website
+calls the Discord bot's internal API:
+
+```
+POST /internal/mod-reverse
+```
+
+— gated by the same shared-secret scheme as the existing `/internal/announce`
+call. The bot lifts the ban / clears the timeout for the target and posts an
+"Appeal approved" embed to its mod log.
+
+The call is **best-effort**: the appeal resolution itself always completes
+(the appeal is marked `approved` and the staff response is saved) regardless of
+whether the bot answers. If the bot is down or the call otherwise fails,
+`reversal_status` is recorded as `failed` and staff are expected to reverse the
+sanction by hand in Discord; the `reversal` object in the `resolve` response
+surfaces `ok: false` and an `error` so the UI can flag it. Denied appeals never
+attempt a reversal.
+
+---
+
+See [website-README.md](website-README.md) for the moderation dashboard's place
+in the wider site, and [BACKEND_DESIGN.md](BACKEND_DESIGN.md) for the base API
+conventions (auth, error shapes, response codes) these endpoints follow.

website/website-README.md

@@ -10,6 +10,7 @@ A full-stack app in one repo:
 - **Frontend** — React + Vite single-page app (public site, wiki, and the admin panel), dark "gothic" theme (Cinzel + Georgia).
 - **Deploy** — Docker Compose (app + MariaDB) behind a Pangolin reverse proxy. Express serves the built SPA in production.
 - **Shard link** — a live bridge to the in-game ServUO shard through the **uo-link** sidecar ([RunicGateway/link](https://gitea.whitlocktech.com/RunicGateway/link)): the site ingests a live event feed and makes server-side REST calls to show shard status, economy, staff presence, IDOCs, live activity, and per-character sheets. See [Shard integration (uo-link)](#shard-integration-uo-link).
+- **Moderation appeals** — a player whose linked Discord identity was banned or muted (per the bot's `mod_actions` log) can open an appeal from the player portal; staff claim and resolve appeals from an admin queue, and approving a ban/mute appeal best-effort reverses it in Discord automatically. See [MODERATION_APPEALS.md](MODERATION_APPEALS.md).
 
 The design reference is [BACKEND_DESIGN.md](BACKEND_DESIGN.md) (API contract, schema, security).
 
@@ -331,7 +332,7 @@ character**; players and editor/moderator staff are limited to their own linked
 
 | Surface | Endpoints | Who | Data |
 |---|---|---|---|
-| **Public** | `/api/v1/public/shard/*` (`status`, `feed`, `economy`, `online`, `idoc`, `stream`) | anyone | Shard up/down, gold-supply series, IDOC houses, a curated live feed, and **"Staff online"** — only players whose account is linked to a **staff** user (admin/editor/moderator), shown with name + map location. Linked *players* are never listed publicly; no vitals or account are exposed. |
+| **Public** | `/api/v1/public/shard/*` (`status`, `feed`, `economy`, `online`, `idoc`, `stream`) | anyone | Shard up/down, gold-supply series, IDOC houses, a curated live feed, and **"Staff online"** — only players whose account is linked to a **staff** user (admin/editor/moderator), shown by name. Their in-game **map location is only included for admin/moderator viewers** — for players and the public it is stripped from the payload entirely (server-enforced, not just hidden in the UI). Linked *players* are never listed publicly; no vitals or account are exposed. |
 | **Player** | `/api/v1/player/shard/*` (`link`, `accounts`, `roster/:account`, `vendors/:account`, `char/:serial`, `sales`) | logged-in player | Their own linked accounts: character rosters, character sheets, player-vendor snapshots, and recent vendor sales. |
 | **Admin** | `/api/v1/admin/shard/*` (self-linking, same as player) · `/api/v1/admin/uo-link/*` (`config`, `towncrier`, `stream`) | staff / admin | Staff link their own accounts like players; **admins** additionally read *any* character's data, edit the sidecar connection config, publish/remove **town-crier** messages, and subscribe to the full event stream (incl. audit/cheat). |