Merge pull request 'docs(installer): record Phase 2 as built — sidecar install and service' (#91) from docs/installer-phase2 into main

Reviewed-on: #91
Reviewed-by: Colby Whitlock <whitlocktech@gmail.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

@@ -7,8 +7,11 @@ so they live in one place, independent of either codebase.
 ## Layout
 
 ```
-website/   docs from the shard website (Node/Express + MariaDB + React/Vite)
-link/      docs from the ServUO bridge (C# plugin + Rust sidecar + Node WS)
+website/    docs from the shard website (Node/Express + MariaDB + React/Vite)
+link/       docs from the ServUO bridge (C# plugin + Rust sidecar + Node WS)
+android/    docs from the native Android client (Kotlin + Jetpack Compose)
+installer/  docs for the installer that deploys a shard's bridge components
+ci/         cross-cutting CI/quality notes
 ```
 
 ### `website/`
@@ -17,18 +20,42 @@ link/      docs from the ServUO bridge (C# plugin + Rust sidecar + Node WS)
 | [BACKEND_DESIGN.md](website/BACKEND_DESIGN.md) | API contract, DB schema, security model |
 | [HERO_EDITOR.md](website/HERO_EDITOR.md) | Hero canvas editor feature spec |
 | [WIKI_UPGRADE.md](website/WIKI_UPGRADE.md) | Wiki subsystem upgrade notes |
+| [SHARD_VISIBILITY.md](website/SHARD_VISIBILITY.md) | Who sees which shard data — the admin-configurable audience framework |
+| [SPAWN_ATLAS.md](website/SPAWN_ATLAS.md) | The bestiary / spawn atlas: what the shard contains, parsed from its own ServUO tree |
+| [CLILOCS.md](website/CLILOCS.md) | UO's id → name table: converting one from your client so items have names |
+| [UOFIDDLER.md](website/UOFIDDLER.md) | **Operator runbook** — step-by-step extraction from your own UO client (cliloc table, creature art) |
+| [MARKETPLACE.md](website/MARKETPLACE.md) | The player-vendor index: how it is gathered, what it costs, how to tune it |
 | [website-README.md](website/website-README.md) | Snapshot of the website repo's README (setup/run reference) |
+| [PROJECT_TREE.md](website/PROJECT_TREE.md) | Auto-generated snapshot of the repo's tracked file layout |
 
 ### `link/`
 | Doc | What it covers |
 |---|---|
 | [INTEGRATION.md](link/INTEGRATION.md) | How the website integrates with the uo-link sidecar |
 | [PROTOCOL_2.md](link/PROTOCOL_2.md) | Protocol 2.0 / 2.1 design |
+| [v3.md](link/v3.md) | Protocol 3.0 design — shard content/standings streams + the visibility framework |
 | [ADMIN_CONTROLS.md](link/ADMIN_CONTROLS.md) | Staff write-plane (kick/ban/broadcast, page queue) |
 | [SHARD_PREREQS.md](link/SHARD_PREREQS.md) | Shard-side prerequisites for the bridge |
 | [PLAN.md](link/PLAN.md) | uo-link build plan |
 | [RESEARCH.md](link/RESEARCH.md) | Research notes |
 | [link-README.md](link/link-README.md) | Snapshot of the link repo's README |
+| [PROJECT_TREE.md](link/PROJECT_TREE.md) | Auto-generated snapshot of the repo's tracked file layout |
+
+### `android/`
+| Doc | What it covers |
+|---|---|
+| [PLAN.md](android/PLAN.md) | Android client build plan / milestones |
+| [COVERAGE_PLAN.md](android/COVERAGE_PLAN.md) | Test-coverage rollout plan |
+| [APP_LINKS.md](android/APP_LINKS.md) | Android App Links / deep-link setup |
+| [theme-plan.md](android/theme-plan.md) | Theming plan |
+| [TRUSTED_DEVICES_APP_HANDOFF.md](android/TRUSTED_DEVICES_APP_HANDOFF.md) | Trusted-devices app handoff notes |
+| [PROJECT_TREE.md](android/PROJECT_TREE.md) | Auto-generated snapshot of the repo's tracked file layout |
+
+### `installer/`
+| Doc | What it covers |
+|---|---|
+| [INSTALL.md](installer/INSTALL.md) | **Operator guide** — installing Runic Gateway on a ServUO shard, connecting it to the website, and diagnosing it. Includes the by-hand path, which works today |
+| [PLAN.md](installer/PLAN.md) | Installer design of record — phases, locked decisions, the bundle/compat-matrix model |
 
 ## Provenance
 
@@ -38,3 +65,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/COVERAGE_PLAN.md

@@ -0,0 +1,204 @@
+# Android App — Test Coverage Plan
+
+**Goal:** clear the SonarQube coverage quality gate (`new_coverage ≥ 50%`) for
+`Runic-Gateway-Android-app`, and leave a durable unit-test culture behind it. Companion to
+[`PLAN.md`](./PLAN.md) §12.1 (the JaCoCo wiring that made coverage measurable).
+
+## 1. Current state (2026-07-22, post `Android-app#26`)
+
+The JaCoCo→Sonar wiring is live on `main`, so coverage is now real — and the gate is **failing**:
+
+| Metric | Value |
+|---|---|
+| Quality gate | **ERROR** (one condition) |
+| `new_coverage` | **16.4%** (threshold ≥ 50%) |
+| overall `coverage` | 16.3% |
+| lines to cover | 3,188 |
+| covered | 542 |
+
+Everything else on the gate is green (reliability/security/maintainability **A**, duplication 0%).
+Because this is the *first* measured version, Sonar's "new code" window is essentially the whole
+codebase, so `new_coverage ≈ overall coverage` — to pass we need to roughly **triple** covered
+lines, from 542 to ~1,600.
+
+### Where the uncovered lines are
+
+Bucketed from Sonar's per-file `uncovered_lines` (exclusions from #26 already applied, so `*Screen.kt`
+is absent):
+
+| Bucket | Files | Lines to cover | Covered % | Verdict |
+|---|--:|--:|--:|---|
+| **ViewModels** | 28 | 1,153 | **0.1%** | **Test** — the dominant lever; no ViewModel has any test |
+| **DTOs** | 12 | 648 | 26.7% | **Test** — trivial (serialization); a pattern already exists |
+| **Repositories** | 11 | 274 | 11.3% | **Test** — fake the API interface |
+| **core/\* (logic)** | 21 | 365 | 56.2% | **Test** — top up the partially-covered ones |
+| UI composables (`*Components.kt`, `BlockRenderer`, …) | 7 | 255 | 3.9% | **Exclude** — not JVM-unit-testable, and `*Screen.kt`'s exclusion missed them |
+| core/push (Android services) | 4 | ~191 | ~0% | **Exclude** (or Robolectric later) — foreground service / notifications |
+| core/auth `Encrypted*` stores | 3 | 76 | 0% | **Exclude** — Android Keystore / EncryptedSharedPreferences |
+| framework glue (`di/`, `RunicGatewayApp`, `LocalAssetResolver`) | 3 | ~17 | 0% | **Exclude** |
+
+**Two levers, applied together:** (a) stop *counting* code a JVM unit test physically cannot execute,
+and (b) actually *test* the logic — ViewModels, DTOs, repositories, core utilities.
+
+## 2. Strategy & projected math
+
+Numbers below are line-coverage projections against Sonar's `lines_to_cover`. They are estimates, but
+grounded in the current per-bucket totals.
+
+### Phase 0 — Broaden coverage exclusions (no tests; ~½ day)
+
+Move non-unit-testable code out of the **coverage** denominator (it stays in *analysis* — bugs and
+smells are still reported). Extend `sonar.coverage.exclusions` in `sonar-project.properties`:
+
+```properties
+sonar.coverage.exclusions=\
+  app/src/main/java/**/ui/**/*Screen.kt,\
+  app/src/main/java/**/ui/**/*Screen*.kt,\
+  app/src/main/java/**/ui/**/*Components.kt,\
+  app/src/main/java/**/ui/page/BlockRenderer.kt,\
+  app/src/main/java/**/ui/components/**,\
+  app/src/main/java/**/ui/shard/FrameFields.kt,\
+  app/src/main/java/**/ui/theme/**,\
+  app/src/main/java/**/ui/LocalAssetResolver.kt,\
+  app/src/main/java/**/RunicApp.kt,\
+  app/src/main/java/**/MainActivity.kt,\
+  app/src/main/java/**/*Application.kt,\
+  app/src/main/java/**/RunicGatewayApp.kt,\
+  app/src/main/java/**/di/**,\
+  app/src/main/java/**/core/push/PushService.kt,\
+  app/src/main/java/**/core/push/PushManager.kt,\
+  app/src/main/java/**/core/push/PushNotifier.kt,\
+  app/src/main/java/**/core/push/NtfyStreamClient.kt,\
+  app/src/main/java/**/core/auth/Encrypted*.kt
+```
+
+> Verify each glob targets composable-only / framework-only files before committing (e.g. confirm
+> `FrameFields.kt` holds no testable logic). Keep the *pure-logic* push files in coverage
+> (`PushPreferences`, `PushTickle`, `NtfyTopic`, `PushStreams`) — they already have tests.
+
+Effect: denominator ~3,188 → ~2,650; covered ~542 → ~532. **Coverage ≈ 20%.** (Removing ~540 lines
+that were ~2% covered.)
+
+### Phase 1 — DTO serialization tests (highest ROI; ~1 day) → ~34%
+
+DTOs are `@Serializable` data classes; test them with kotlinx-serialization round-trips against
+representative backend JSON. The pattern already exists (`AccountDtoTest`, `AuthDtoTest`,
+`NotificationsDtoTest`, `PlayerShardDtoTest`, `ShardDtoTest`). Add/extend:
+
+- **New:** `AdminDto` (111 uncov — biggest single file), `WikiDto` (51), `PublicDto` (32),
+  `PageDto` (16), `PostDto` (12), `ContactDto` (11), `SsoDto`, `PageDto`.
+- **Extend to ~85%:** `PlayerShardDto` (30.8%), `ShardDto` (35.6%), `AccountDto` (50.7%),
+  `AuthDto` (47.4%).
+
+Target DTOs to ~85%: **+~380 covered lines** → covered ~912 / ~2,650 ≈ **34%**.
+
+### Phase 2 — ViewModel tests (the big one; ~3–4 days) → clears the gate
+
+28 ViewModels, ~1,153 lines, currently 0%. This is where the gate is won. Requires a small test
+harness (§3). Each test drives the VM with fake collaborators and asserts `UiState` transitions
+(loading → success/error, form validation, actions).
+
+Priority by uncovered lines:
+
+1. `LoginViewModel` (116), `AccountViewModel` (104), `CharactersViewModel` (77),
+   `AdminContentViewModel` (74), `NotificationsViewModel` (66), `TrustedDevicesViewModel` (63),
+   `ShardViewModel` (59)
+2. `HousesViewModel` (51), `GovernorsViewModel` (47), `AdminDashboardViewModel` (43),
+   `AdminSupportViewModel` (41), `ChampsViewModel` (40), `AdminModerationViewModel` (40),
+   `GuildsViewModel` (39), `RecoveryCodesViewModel` (38), `ConnectViewModel` (37),
+   `ContactViewModel` (36), `VendorsViewModel` (32), `AppViewModel` (29)
+3. The small ones (`PostViewModel`, `NewsViewModel`, `WikiViewModel`, `CharacterViewModel`,
+   `MyHousesViewModel`, `WikiPageViewModel`, `PageViewModel`, `HomeViewModel`, `SessionViewModel`)
+
+Target ViewModels to ~70%: **+~800 covered lines** → covered ~1,712 / ~2,650 ≈ **65%. ✅ Gate passes.**
+
+> Phases 0 + 2 alone (skipping DTOs) already reach ~50.5% — but DTOs are cheap insurance and Phase 1
+> lands first because it de-risks the harness work.
+
+### Phase 3 — Repository tests (~1–2 days) → margin
+
+Repositories map API `Response`/exceptions to `ApiResult`; test with a fake `*Api` interface (or
+OkHttp `MockWebServer`). Priority: `AuthRepository` (89), `ConnectionRepository` (43),
+`ShardRepository` (27), `AdminRepository` (21), then the small content/wiki/player repos. Target ~70%:
+**+~160 lines** → buffer well above 50% and resilience as the new-code window narrows.
+
+### Phase 4 — core/net + core/auth top-up (~½–1 day) → durability
+
+Fill the partially-covered utilities: `TokenAuthenticator` (31), `ShardStreamClient` (36),
+`HostSelectionInterceptor` (9), `ApiResult` (6), `WebHandoff`, `WebsiteUrls`, `DeviceNameProvider`,
+`ServerPreferences`, `AppConfig`.
+
+### Trajectory
+
+| After | Denominator | Covered | Coverage |
+|---|--:|--:|--:|
+| Today | 3,188 | 542 | 16.3% |
+| Phase 0 (exclusions) | ~2,650 | ~532 | ~20% |
+| Phase 1 (DTOs) | ~2,650 | ~912 | ~34% |
+| **Phase 2 (ViewModels)** | ~2,650 | ~1,712 | **~65% ✅** |
+| Phase 3 (repos) | ~2,650 | ~1,872 | ~71% |
+| Phase 4 (core) | ~2,650 | ~2,000+ | ~75%+ |
+
+## 3. Test infrastructure to add
+
+The existing suite tests pure-logic classes only; ViewModel/coroutine testing needs a little scaffold.
+`kotlinx-coroutines-test` is already a `testImplementation` dependency.
+
+**`MainDispatcherRule`** (JUnit4) — swaps `Dispatchers.Main` (used by `viewModelScope`) for a test
+dispatcher:
+
+```kotlin
+// app/src/test/java/com/runicgateway/app/util/MainDispatcherRule.kt
+@OptIn(ExperimentalCoroutinesApi::class)
+class MainDispatcherRule(
+    private val dispatcher: TestDispatcher = StandardTestDispatcher(),
+) : TestWatcher() {
+    override fun starting(d: Description) = Dispatchers.setMain(dispatcher)
+    override fun finished(d: Description) = Dispatchers.resetMain()
+}
+```
+
+**ViewModel test pattern** — hand-written fakes (matches the repo's existing no-mock convention; no new
+dependency):
+
+```kotlin
+class LoginViewModelTest {
+    @get:Rule val mainDispatcher = MainDispatcherRule()
+
+    private class FakeAuthRepository(var result: LoginResult) : AuthRepository { /* stub the seam */ }
+
+    @Test fun `blank credentials surface INVALID_CREDENTIALS without a network call`() = runTest {
+        val vm = LoginViewModel(FakeAuthRepository(LoginResult.Success), /* … */)
+        vm.submit()
+        assertEquals(LoginError.INVALID_CREDENTIALS, vm.state.value.error)
+    }
+}
+```
+
+- Assert on `viewModel.state.value` after `advanceUntilIdle()`; or collect the `StateFlow` in a
+  background `launch` when you need to see intermediate (loading) states.
+- **Optional deps (decide once):** `mockk` would cut fake-writing for wide interfaces, and `turbine`
+  simplifies Flow assertions. Recommendation: **stay with hand fakes** to match convention; revisit
+  only if VM tests get boilerplate-heavy.
+
+## 4. Execution notes
+
+- CI already runs `./gradlew testDebugUnitTest jacocoTestReport` before the scan (`sonarqube.yml`),
+  so new tests count automatically on merge to `main`. Locally on this machine: JDK 21 needs
+  `-Pksp.incremental=false`.
+- Sonar recomputes the gate on the post-merge scan; there's no way to fully confirm the number
+  pre-merge. Land phases as separate PRs (0, 1, 2, …) so coverage climbs visibly and reviews stay
+  small.
+- `sonar.coverage.exclusions` removes files from **coverage only** — analysis still flags bugs/smells
+  in them, so excluding UI/framework code is safe.
+- **Android-framework code deferred, not abandoned:** push services and `Encrypted*` stores are
+  excluded now; if we want them covered later, add Robolectric (`testImplementation`) and a
+  `RobolectricTestRunner` suite rather than instrumented tests, to keep it in the fast JVM `test`
+  source set the scan already consumes.
+
+## 5. Definition of done
+
+- `new_coverage ≥ 50%` and the SonarQube quality gate is **green**.
+- `MainDispatcherRule` + a documented ViewModel test pattern exist and are reused.
+- Coverage exclusions list only genuinely non-unit-testable files (UI composables, Android-framework
+  glue) — no ViewModel, repository, DTO, or pure core-logic file is excluded.

android/PROJECT_TREE.md

@@ -0,0 +1,363 @@
+# Android App — Project Tree
+
+> **Auto-generated.** This file is maintained by the `sync-project-tree` CI workflow in
+> the [`RunicGateway/Android-app`](https://gitea.whitlocktech.com/RunicGateway/Android-app) repository, which
+> opens a pull request here whenever the tracked file layout on `main` changes. Do not edit
+> by hand — changes will be overwritten by the next sync.
+
+A snapshot of the tracked files in the repository (build output, dependencies, and other
+git-ignored paths are excluded).
+
+```text
+android-app/
+├── .gitea/
+│   ├── scripts/
+│   │   └── gen_tree.py
+│   └── workflows/
+│       ├── pr-checks.yml
+│       ├── release.yml
+│       ├── sonarqube.yml
+│       └── sync-project-tree.yml
+├── app/
+│   ├── licenses/
+│   │   └── Cinzel-OFL.txt
+│   ├── src/
+│   │   ├── debug/
+│   │   │   └── res/
+│   │   │       └── xml/
+│   │   │           └── network_security_config.xml
+│   │   ├── main/
+│   │   │   ├── java/
+│   │   │   │   └── com/
+│   │   │   │       └── runicgateway/
+│   │   │   │           └── app/
+│   │   │   │               ├── core/
+│   │   │   │               │   ├── auth/
+│   │   │   │               │   │   ├── sso/
+│   │   │   │               │   │   │   ├── EncryptedPendingSsoStore.kt
+│   │   │   │               │   │   │   ├── PendingSsoStore.kt
+│   │   │   │               │   │   │   ├── Pkce.kt
+│   │   │   │               │   │   │   └── SsoAuthManager.kt
+│   │   │   │               │   │   ├── DeviceNameProvider.kt
+│   │   │   │               │   │   ├── EncryptedTokenStore.kt
+│   │   │   │               │   │   ├── EncryptedTrustTokenStore.kt
+│   │   │   │               │   │   ├── Session.kt
+│   │   │   │               │   │   ├── SessionManager.kt
+│   │   │   │               │   │   ├── TokenStore.kt
+│   │   │   │               │   │   └── TrustTokenStore.kt
+│   │   │   │               │   ├── net/
+│   │   │   │               │   │   ├── AuthInterceptor.kt
+│   │   │   │               │   │   ├── BaseUrlHolder.kt
+│   │   │   │               │   │   ├── HostSelectionInterceptor.kt
+│   │   │   │               │   │   ├── Http.kt
+│   │   │   │               │   │   ├── ServerUrl.kt
+│   │   │   │               │   │   ├── ShardStream.kt
+│   │   │   │               │   │   ├── ShardStreamClient.kt
+│   │   │   │               │   │   ├── ShardStreamEvent.kt
+│   │   │   │               │   │   ├── TokenAuthenticator.kt
+│   │   │   │               │   │   └── UserAgentInterceptor.kt
+│   │   │   │               │   ├── prefs/
+│   │   │   │               │   │   └── ServerPreferences.kt
+│   │   │   │               │   ├── push/
+│   │   │   │               │   │   ├── NtfyStreamClient.kt
+│   │   │   │               │   │   ├── NtfyTopic.kt
+│   │   │   │               │   │   ├── PushManager.kt
+│   │   │   │               │   │   ├── PushNotifier.kt
+│   │   │   │               │   │   ├── PushPreferences.kt
+│   │   │   │               │   │   ├── PushService.kt
+│   │   │   │               │   │   ├── PushStreams.kt
+│   │   │   │               │   │   └── PushTickle.kt
+│   │   │   │               │   ├── result/
+│   │   │   │               │   │   └── ApiResult.kt
+│   │   │   │               │   ├── web/
+│   │   │   │               │   │   ├── WebHandoff.kt
+│   │   │   │               │   │   └── WebsiteUrls.kt
+│   │   │   │               │   └── AppConfig.kt
+│   │   │   │               ├── data/
+│   │   │   │               │   ├── api/
+│   │   │   │               │   │   ├── dto/
+│   │   │   │               │   │   │   ├── AccountDto.kt
+│   │   │   │               │   │   │   ├── AdminDto.kt
+│   │   │   │               │   │   │   ├── AuthDto.kt
+│   │   │   │               │   │   │   ├── ContactDto.kt
+│   │   │   │               │   │   │   ├── NotificationsDto.kt
+│   │   │   │               │   │   │   ├── PageDto.kt
+│   │   │   │               │   │   │   ├── PlayerShardDto.kt
+│   │   │   │               │   │   │   ├── PostDto.kt
+│   │   │   │               │   │   │   ├── PublicDto.kt
+│   │   │   │               │   │   │   ├── ShardContentDto.kt
+│   │   │   │               │   │   │   ├── ShardDto.kt
+│   │   │   │               │   │   │   ├── SsoDto.kt
+│   │   │   │               │   │   │   └── WikiDto.kt
+│   │   │   │               │   │   ├── AdminApi.kt
+│   │   │   │               │   │   ├── AuthApi.kt
+│   │   │   │               │   │   ├── AuthRefreshApi.kt
+│   │   │   │               │   │   ├── MeApi.kt
+│   │   │   │               │   │   ├── NotificationsApi.kt
+│   │   │   │               │   │   ├── PlayerShardApi.kt
+│   │   │   │               │   │   ├── PublicApi.kt
+│   │   │   │               │   │   └── SsoApi.kt
+│   │   │   │               │   └── repository/
+│   │   │   │               │       ├── AccountRepository.kt
+│   │   │   │               │       ├── AdminRepository.kt
+│   │   │   │               │       ├── AuthRepository.kt
+│   │   │   │               │       ├── ConnectionRepository.kt
+│   │   │   │               │       ├── ContactRepository.kt
+│   │   │   │               │       ├── ContentRepository.kt
+│   │   │   │               │       ├── NotificationsRepository.kt
+│   │   │   │               │       ├── PlayerShardRepository.kt
+│   │   │   │               │       ├── SettingsRepository.kt
+│   │   │   │               │       ├── ShardFeaturesRepository.kt
+│   │   │   │               │       ├── ShardRepository.kt
+│   │   │   │               │       └── WikiRepository.kt
+│   │   │   │               ├── di/
+│   │   │   │               │   ├── AppModule.kt
+│   │   │   │               │   ├── NetworkModule.kt
+│   │   │   │               │   └── StorageModule.kt
+│   │   │   │               ├── ui/
+│   │   │   │               │   ├── admin/
+│   │   │   │               │   │   ├── AdminContentScreen.kt
+│   │   │   │               │   │   ├── AdminContentViewModel.kt
+│   │   │   │               │   │   ├── AdminDashboardScreen.kt
+│   │   │   │               │   │   ├── AdminDashboardViewModel.kt
+│   │   │   │               │   │   ├── AdminModerationScreen.kt
+│   │   │   │               │   │   ├── AdminModerationViewModel.kt
+│   │   │   │               │   │   ├── AdminSupportScreen.kt
+│   │   │   │               │   │   └── AdminSupportViewModel.kt
+│   │   │   │               │   ├── auth/
+│   │   │   │               │   │   ├── AccountScreen.kt
+│   │   │   │               │   │   ├── AccountViewModel.kt
+│   │   │   │               │   │   ├── LoginScreen.kt
+│   │   │   │               │   │   ├── LoginViewModel.kt
+│   │   │   │               │   │   ├── RecoveryCodesScreen.kt
+│   │   │   │               │   │   ├── RecoveryCodesViewModel.kt
+│   │   │   │               │   │   ├── TrustedDevicesScreen.kt
+│   │   │   │               │   │   └── TrustedDevicesViewModel.kt
+│   │   │   │               │   ├── components/
+│   │   │   │               │   │   ├── HtmlText.kt
+│   │   │   │               │   │   ├── StateViews.kt
+│   │   │   │               │   │   └── ThemeComponents.kt
+│   │   │   │               │   ├── connect/
+│   │   │   │               │   │   ├── ConnectScreen.kt
+│   │   │   │               │   │   └── ConnectViewModel.kt
+│   │   │   │               │   ├── contact/
+│   │   │   │               │   │   ├── ContactScreen.kt
+│   │   │   │               │   │   └── ContactViewModel.kt
+│   │   │   │               │   ├── home/
+│   │   │   │               │   │   ├── HomeScreen.kt
+│   │   │   │               │   │   └── HomeViewModel.kt
+│   │   │   │               │   ├── navigation/
+│   │   │   │               │   │   ├── Menu.kt
+│   │   │   │               │   │   └── Routes.kt
+│   │   │   │               │   ├── news/
+│   │   │   │               │   │   ├── NewsScreen.kt
+│   │   │   │               │   │   ├── NewsViewModel.kt
+│   │   │   │               │   │   ├── PostScreen.kt
+│   │   │   │               │   │   └── PostViewModel.kt
+│   │   │   │               │   ├── notifications/
+│   │   │   │               │   │   ├── NotificationsScreen.kt
+│   │   │   │               │   │   └── NotificationsViewModel.kt
+│   │   │   │               │   ├── page/
+│   │   │   │               │   │   ├── BlockRenderer.kt
+│   │   │   │               │   │   ├── PageScreen.kt
+│   │   │   │               │   │   └── PageViewModel.kt
+│   │   │   │               │   ├── player/
+│   │   │   │               │   │   ├── CharacterSheetScreen.kt
+│   │   │   │               │   │   ├── CharactersScreen.kt
+│   │   │   │               │   │   ├── CharactersViewModel.kt
+│   │   │   │               │   │   ├── CharacterViewModel.kt
+│   │   │   │               │   │   ├── MyHousesScreen.kt
+│   │   │   │               │   │   ├── MyHousesViewModel.kt
+│   │   │   │               │   │   ├── VendorsScreen.kt
+│   │   │   │               │   │   └── VendorsViewModel.kt
+│   │   │   │               │   ├── session/
+│   │   │   │               │   │   └── SessionViewModel.kt
+│   │   │   │               │   ├── shard/
+│   │   │   │               │   │   ├── AtlasScreen.kt
+│   │   │   │               │   │   ├── AtlasViewModel.kt
+│   │   │   │               │   │   ├── ChampsScreen.kt
+│   │   │   │               │   │   ├── ChampsViewModel.kt
+│   │   │   │               │   │   ├── FrameFields.kt
+│   │   │   │               │   │   ├── GovernorsScreen.kt
+│   │   │   │               │   │   ├── GovernorsViewModel.kt
+│   │   │   │               │   │   ├── GuildsScreen.kt
+│   │   │   │               │   │   ├── GuildsViewModel.kt
+│   │   │   │               │   │   ├── HousesScreen.kt
+│   │   │   │               │   │   ├── HousesViewModel.kt
+│   │   │   │               │   │   ├── LeaderboardsScreen.kt
+│   │   │   │               │   │   ├── LeaderboardsViewModel.kt
+│   │   │   │               │   │   ├── LiveBoard.kt
+│   │   │   │               │   │   ├── MarketScreen.kt
+│   │   │   │               │   │   ├── MarketViewModel.kt
+│   │   │   │               │   │   ├── RulesScreen.kt
+│   │   │   │               │   │   ├── RulesViewModel.kt
+│   │   │   │               │   │   ├── ShardComponents.kt
+│   │   │   │               │   │   ├── ShardEventText.kt
+│   │   │   │               │   │   ├── ShardScreen.kt
+│   │   │   │               │   │   └── ShardViewModel.kt
+│   │   │   │               │   ├── theme/
+│   │   │   │               │   │   ├── BrandColor.kt
+│   │   │   │               │   │   ├── Color.kt
+│   │   │   │               │   │   ├── Font.kt
+│   │   │   │               │   │   ├── Theme.kt
+│   │   │   │               │   │   └── Type.kt
+│   │   │   │               │   ├── wiki/
+│   │   │   │               │   │   ├── WikiPageScreen.kt
+│   │   │   │               │   │   ├── WikiPageViewModel.kt
+│   │   │   │               │   │   ├── WikiScreen.kt
+│   │   │   │               │   │   └── WikiViewModel.kt
+│   │   │   │               │   ├── AppViewModel.kt
+│   │   │   │               │   ├── LocalAssetResolver.kt
+│   │   │   │               │   ├── RunicApp.kt
+│   │   │   │               │   └── UiState.kt
+│   │   │   │               ├── MainActivity.kt
+│   │   │   │               └── RunicGatewayApp.kt
+│   │   │   ├── res/
+│   │   │   │   ├── drawable/
+│   │   │   │   │   └── ic_launcher_background.xml
+│   │   │   │   ├── drawable-anydpi/
+│   │   │   │   │   └── ic_stat_name.xml
+│   │   │   │   ├── drawable-hdpi/
+│   │   │   │   │   └── ic_stat_name.png
+│   │   │   │   ├── drawable-mdpi/
+│   │   │   │   │   └── ic_stat_name.png
+│   │   │   │   ├── drawable-xhdpi/
+│   │   │   │   │   └── ic_stat_name.png
+│   │   │   │   ├── drawable-xxhdpi/
+│   │   │   │   │   └── ic_stat_name.png
+│   │   │   │   ├── font/
+│   │   │   │   │   └── cinzel_variable.ttf
+│   │   │   │   ├── mipmap-anydpi-v26/
+│   │   │   │   │   ├── ic_launcher.xml
+│   │   │   │   │   └── ic_launcher_round.xml
+│   │   │   │   ├── mipmap-hdpi/
+│   │   │   │   │   ├── ic_launcher.webp
+│   │   │   │   │   ├── ic_launcher_foreground.webp
+│   │   │   │   │   └── ic_launcher_round.webp
+│   │   │   │   ├── mipmap-mdpi/
+│   │   │   │   │   ├── ic_launcher.webp
+│   │   │   │   │   ├── ic_launcher_foreground.webp
+│   │   │   │   │   └── ic_launcher_round.webp
+│   │   │   │   ├── mipmap-xhdpi/
+│   │   │   │   │   ├── ic_launcher.webp
+│   │   │   │   │   ├── ic_launcher_foreground.webp
+│   │   │   │   │   └── ic_launcher_round.webp
+│   │   │   │   ├── mipmap-xxhdpi/
+│   │   │   │   │   ├── ic_launcher.webp
+│   │   │   │   │   ├── ic_launcher_foreground.webp
+│   │   │   │   │   └── ic_launcher_round.webp
+│   │   │   │   ├── mipmap-xxxhdpi/
+│   │   │   │   │   ├── ic_launcher.webp
+│   │   │   │   │   ├── ic_launcher_foreground.webp
+│   │   │   │   │   └── ic_launcher_round.webp
+│   │   │   │   ├── values/
+│   │   │   │   │   ├── colors.xml
+│   │   │   │   │   ├── strings.xml
+│   │   │   │   │   └── themes.xml
+│   │   │   │   └── xml/
+│   │   │   │       ├── backup_rules.xml
+│   │   │   │       ├── data_extraction_rules.xml
+│   │   │   │       └── network_security_config.xml
+│   │   │   ├── AndroidManifest.xml
+│   │   │   └── ic_launcher-playstore.png
+│   │   └── test/
+│   │       └── java/
+│   │           └── com/
+│   │               └── runicgateway/
+│   │                   └── app/
+│   │                       ├── core/
+│   │                       │   ├── auth/
+│   │                       │   │   ├── sso/
+│   │                       │   │   │   ├── PkceTest.kt
+│   │                       │   │   │   └── SsoAuthManagerTest.kt
+│   │                       │   │   └── SessionManagerTest.kt
+│   │                       │   ├── net/
+│   │                       │   │   ├── HostRewriteTest.kt
+│   │                       │   │   ├── ServerUrlTest.kt
+│   │                       │   │   └── ShardStreamClientTest.kt
+│   │                       │   ├── push/
+│   │                       │   │   ├── NtfyTopicTest.kt
+│   │                       │   │   └── PushTickleTest.kt
+│   │                       │   └── result/
+│   │                       │       ├── ApiResultExtrasTest.kt
+│   │                       │       └── ApiResultTest.kt
+│   │                       ├── data/
+│   │                       │   ├── api/
+│   │                       │   │   ├── dto/
+│   │                       │   │   │   ├── AccountDtoTest.kt
+│   │                       │   │   │   ├── AdminDtoTest.kt
+│   │                       │   │   │   ├── AuthDtoTest.kt
+│   │                       │   │   │   ├── AuthRequestDtoTest.kt
+│   │                       │   │   │   ├── ContentDtoTest.kt
+│   │                       │   │   │   ├── NotificationsDtoTest.kt
+│   │                       │   │   │   ├── PlayerGameDataDtoTest.kt
+│   │                       │   │   │   ├── PlayerShardDtoTest.kt
+│   │                       │   │   │   ├── PublicDtoTest.kt
+│   │                       │   │   │   ├── ShardBoardDtoTest.kt
+│   │                       │   │   │   ├── ShardContentDtoTest.kt
+│   │                       │   │   │   ├── ShardDtoTest.kt
+│   │                       │   │   │   ├── SsoDtoTest.kt
+│   │                       │   │   │   └── WikiDtoTest.kt
+│   │                       │   │   └── fake/
+│   │                       │   │       ├── FakeAdminApi.kt
+│   │                       │   │       ├── FakePlayerShardApi.kt
+│   │                       │   │       ├── FakePublicApi.kt
+│   │                       │   │       └── FakeShardStream.kt
+│   │                       │   └── repository/
+│   │                       │       ├── AccountTrustedDevicesTest.kt
+│   │                       │       ├── ConnectionVersionGuardTest.kt
+│   │                       │       └── ShardFeaturesRepositoryTest.kt
+│   │                       ├── ui/
+│   │                       │   ├── admin/
+│   │                       │   │   ├── AdminContentViewModelTest.kt
+│   │                       │   │   ├── AdminDashboardViewModelTest.kt
+│   │                       │   │   ├── AdminModerationViewModelTest.kt
+│   │                       │   │   └── AdminSupportViewModelTest.kt
+│   │                       │   ├── contact/
+│   │                       │   │   └── ContactViewModelTest.kt
+│   │                       │   ├── navigation/
+│   │                       │   │   ├── MenuAccessTest.kt
+│   │                       │   │   └── MenuFeatureGatingTest.kt
+│   │                       │   ├── notifications/
+│   │                       │   │   └── NotificationRoutingTest.kt
+│   │                       │   ├── player/
+│   │                       │   │   ├── CharacterSheetHelpersTest.kt
+│   │                       │   │   ├── CharactersViewModelTest.kt
+│   │                       │   │   └── PlayerViewModelTest.kt
+│   │                       │   ├── shard/
+│   │                       │   │   ├── FrameFieldsTest.kt
+│   │                       │   │   ├── LiveBoardTest.kt
+│   │                       │   │   ├── ShardBoardViewModelTest.kt
+│   │                       │   │   ├── ShardContentHelpersTest.kt
+│   │                       │   │   ├── ShardContentViewModelTest.kt
+│   │                       │   │   └── ShardEventTextTest.kt
+│   │                       │   ├── theme/
+│   │                       │   │   └── BrandColorTest.kt
+│   │                       │   ├── ContentViewModelTest.kt
+│   │                       │   └── UiStateTest.kt
+│   │                       ├── util/
+│   │                       │   ├── FakeApiSupport.kt
+│   │                       │   └── MainDispatcherRule.kt
+│   │                       └── ScaffoldSanityTest.kt
+│   ├── build.gradle.kts
+│   └── proguard-rules.pro
+├── gradle/
+│   ├── wrapper/
+│   │   ├── gradle-wrapper.jar
+│   │   └── gradle-wrapper.properties
+│   └── libs.versions.toml
+├── .gitattributes
+├── .gitignore
+├── build.gradle.kts
+├── CODE_OF_CONDUCT.md
+├── CONTRIBUTING.md
+├── CONTRIBUTORS.md
+├── gradle.properties
+├── gradlew
+├── gradlew.bat
+├── LICENSE.md
+├── README.md
+├── SECURITY.md
+├── settings.gradle.kts
+└── sonar-project.properties
+```

android/screenshots/README.md

@@ -0,0 +1,49 @@
+# Android app — trusted devices & recovery codes (live smoke test)
+
+Screenshots from a live end-to-end smoke test of the trusted-device + MFA feature on
+the Android client (app PR `RunicGateway/Android-app#23`), captured against the local
+Node server (`127.0.0.1:3000`) and a `uomysticmoon` MariaDB, on an API 36 emulator.
+See `../PLAN.md §4.1.1` for the design and `../../website/TRUSTED_DEVICES_MFA.md` for
+the canonical contract.
+
+| # | Screenshot | Shows |
+|---|---|---|
+| 1 | [`01-login-2fa-trust-device.png`](01-login-2fa-trust-device.png) | The `401 { totpRequired }` login step: the **authentication code** field, the **"Use a recovery code instead"** toggle, and the **"Trust this device (skip codes for 30 days)"** checkbox (ticked). |
+| 2 | [`02-account-security-section.png`](02-account-security-section.png) | The new **Security** section on the account screen linking to Trusted devices and Recovery codes. |
+| 3 | [`03-trusted-devices.png`](03-trusted-devices.png) | The **Trusted Devices** screen listing this device (`Google sdk_gphone64_x86_64` — the `device_name` sent at login) with revoke / trust-this-device / untrust-all. |
+| 4 | [`04-recovery-codes-show-once.png`](04-recovery-codes-show-once.png) | The **Recovery Codes** screen after a password-stepped regenerate: the one-time batch shown once with copy / share, and the updated remaining count. |
+| 5 | [`05-recovery-code-login.png`](05-recovery-code-login.png) | Signing in with a **single-use recovery code** instead of the authenticator code. |
+
+## Verified flows (all passed)
+
+1. **2FA login + "Trust this device"** → `200`, trust token stored; server logged `device trusted`.
+2. **Trust survives logout** — after signing out, a **password-only** sign-in skipped the
+   TOTP step entirely (server: a clean `200` with **no** preceding `401 totpRequired`).
+   This is the headline behaviour: the trust token is *only* consulted at a fresh login,
+   so it must outlive logout (see PLAN §4.1.1).
+3. **Trusted Devices** — list, and the device's `last_used` stamp advancing after the
+   trust-skip login.
+4. **Untrust all** — cleared the server rows **and** the local token; the next
+   password-only sign-in correctly required the TOTP step again (server: `401`).
+5. **Recovery codes** — generate (password step-up, shown once) and a successful
+   **recovery-code login** (server: `mobile login via recovery code` → `200`).
+
+## Full step-by-step walkthrough
+
+The five images above are the curated highlights. These `walkthrough-*` frames are the
+rest of the same smoke-test session, in flow order, for a complete record. (Pure
+automation-artifact frames — soft-keyboard popups, mid-transition spinners, and
+duplicate Home landings — are omitted; the raws that the highlights above supersede are
+not repeated here.)
+
+| # | Screenshot | Shows |
+|---|---|---|
+| 1 | [`walkthrough-01-home-connected.png`](walkthrough-01-home-connected.png) | Home with the shard **Online** (already connected to the local server), signed out. |
+| 2 | [`walkthrough-02-drawer-signed-out.png`](walkthrough-02-drawer-signed-out.png) | Navigation drawer while signed out — **Sign in** entry. |
+| 3 | [`walkthrough-03-login-screen.png`](walkthrough-03-login-screen.png) | The native login screen (no SSO providers configured in dev). |
+| 4 | [`walkthrough-04-login-2fa-step.png`](walkthrough-04-login-2fa-step.png) | The `401 { totpRequired }` step with the fields empty — the **"Use a recovery code instead"** toggle and **"Trust this device"** checkbox before entry (companion to highlight #1, which shows them filled). |
+| 5 | [`walkthrough-05-drawer-signed-in.png`](walkthrough-05-drawer-signed-in.png) | Drawer once signed in — **My account**, Notifications, player groups, **Sign out**. |
+| 6 | [`walkthrough-06-account-overview.png`](walkthrough-06-account-overview.png) | Top of the account screen: identity, username/password, **two-factor ENABLED**. |
+| 7 | [`walkthrough-07-recovery-codes-before-generate.png`](walkthrough-07-recovery-codes-before-generate.png) | Recovery Codes screen before generating — **0 codes remaining** + the password-step-up form. |
+| 8 | [`walkthrough-08-trusted-devices-empty-after-untrust.png`](walkthrough-08-trusted-devices-empty-after-untrust.png) | Trusted Devices after **Untrust all** — "All devices untrusted." and the empty state. |
+| 9 | [`walkthrough-09-login-2fa-required-after-untrust.png`](walkthrough-09-login-2fa-required-after-untrust.png) | The next sign-in **re-prompting for the TOTP step** — proof that untrust-all cleared the local trust token. |

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,59 @@
+# 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 |
+
+## 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.

installer/INSTALL.md

@@ -0,0 +1,793 @@
+# Installing Runic Gateway on your shard
+
+Operator guide for the **Runic Gateway installer** — the tool that takes a working ServUO
+installation and connects it to a Runic Gateway website.
+
+> **Status: the installer binary is not released yet.**
+>
+> Phases 1 and 2 are built and live on the installer repo's `edge` branch: the installer core
+> (bundle resolution, ServUO detection, the overlay sync, `install.json`) and the sidecar half (the
+> binary, its config, its service, and the token handoff). What is still missing is the **patch
+> tier** ([§4](#4-the-patch-tier-optional)), which `install` reports as not applied rather than
+> silently skipping. The first release follows Phase 3, so that a released binary answers every
+> question this guide says it answers.
+>
+> Everything it installs *is* released and published — the sidecar, the plugin overlay, and the
+> [bundle manifest](https://gitea.whitlocktech.com/RunicGateway/installer/src/branch/main/bundles/current.json)
+> that names the checked combination of the two. This guide is the operator-facing contract those
+> phases build to, and it is written first on purpose: it is the specification of what the run
+> looks like, what it asks, where it writes, and what it prints.
+>
+> **You can install today without it** — [Appendix A](#appendix-a--installing-by-hand) is the same
+> deployment done by hand, with the commands verified against the current releases. When the binary
+> ships, Appendix A stays as the reference for what it does under the hood.
+>
+> Design of record: [PLAN.md](PLAN.md).
+
+---
+
+## What this installs
+
+Three things, on the machine that runs your shard:
+
+| # | Component | Where it comes from |
+|---|---|---|
+| 1 | **The plugin overlay** — C# source that ServUO compiles at boot, copied into your server tree | [`RunicGateway/servuo-plugins`](https://gitea.whitlocktech.com/RunicGateway/servuo-plugins) release tarball |
+| 2 | **The uo-link sidecar** — a small Rust service that the shard dials out to, and that your website reads from | [`RunicGateway/link`](https://gitea.whitlocktech.com/RunicGateway/link) release binary |
+| 3 | **A record of what it did** — `install.json`, plus a cached copy of any patches it applied | Written by the installer |
+
+```
+    ServUO shard  ──loopback TCP 127.0.0.1:7788──►  uo-link sidecar  ──HTTP + WebSocket──►  website
+    (1) overlay                                     (2) binary + service                    (yours)
+```
+
+The shard **dials out**; it never listens for the website and is never reachable from the internet.
+Only the sidecar is exposed, and only to your website.
+
+### What it deliberately does not do
+
+- **It never restarts or manages ServUO.** Your shard keeps starting the way it always has. The
+  installer refuses to run while ServUO is up, and tells you when a restart is required.
+- **It never deletes anything from your server tree.** The overlay sync only adds and overwrites.
+- **It never contacts your website.** It prints four values for you to paste into Admin → Shard.
+- **It never edits stock ServUO files without asking.** That is the opt-in
+  [patch tier](#4-the-patch-tier-optional), and skipping it still leaves you with a working bridge.
+
+---
+
+## Before you begin
+
+| Requirement | Detail |
+|---|---|
+| A working ServUO install | It must currently boot and compile scripts cleanly. The installer deploys onto a healthy shard; it does not repair a broken one. |
+| ServUO **57.4** *(patch tier only)* | **57.4 is the only supported version.** The base install works on any reasonably current ServUO. The patch tier is written and tested against stock 57.4; on any other version it is **unsupported and untested** — you can still choose to run it, behind an explicit opt-in, and it applies only where the exact lines it patches are unchanged. See [§4](#4-the-patch-tier-optional). |
+| ServUO **stopped** | `ServUO.exe` holds a lock on `Scripts.dll` and writes `Saves/` on exit. The installer refuses to deploy under a running shard. |
+| Administrator / root | It writes into system directories and registers a service. |
+| Outbound HTTPS | To `gitea.whitlocktech.com`, to fetch the bundle and the two artifacts. Nothing inbound is needed, and no Gitea account or git client is required. |
+| The sidecar on the **same host** as the shard | The shard connects to `127.0.0.1:7788`. Splitting them is not supported — the loopback socket *is* the trust boundary for inbound commands. |
+| Admin access to your Runic Gateway site | The last step is pasting four values into Admin → Shard. |
+
+**Back up first.** The overlay overwrites `Scripts/Scripts.csproj` (a stock file), and the patch
+tier edits stock sources. A copy of `Scripts/` and `Config/` before you start costs nothing.
+
+---
+
+## 1. Download and verify
+
+Releases are **unsigned**. There is no code-signing certificate and no notarization, so the
+`SHA256SUMS` file published beside every artifact is the whole trust anchor — check it.
+
+Download the installer for your OS, plus `SHA256SUMS`, from the
+[installer releases page](https://gitea.whitlocktech.com/RunicGateway/installer/releases):
+
+```
+runicgateway-installer-linux-x86_64
+runicgateway-installer-windows-x86_64.exe
+SHA256SUMS
+```
+
+**Linux**
+
+```bash
+sha256sum -c SHA256SUMS --ignore-missing
+chmod +x runicgateway-installer-linux-x86_64
+```
+
+**Windows** (PowerShell)
+
+```powershell
+(Get-FileHash .\runicgateway-installer-windows-x86_64.exe -Algorithm SHA256).Hash
+Get-Content .\SHA256SUMS      # compare the line for this file, case-insensitively
+```
+
+Windows will show a **SmartScreen "Windows protected your PC"** prompt on first run, because the
+binary is unsigned and unknown. Once you have verified the checksum above: *More info* →
+*Run anyway*. If you would rather not, Appendix A's manual path uses no unsigned binary except the
+sidecar itself, which you verify the same way.
+
+The installer applies the same standard to everything **it** downloads: each artifact's SHA256 is
+checked against the value recorded in the bundle manifest — which CI computed after verifying it
+against the publishing repo's own `SHA256SUMS` — and a mismatch aborts the run.
+
+### What it installs is a bundle, not "latest"
+
+The three components version independently but must agree on one wire protocol, so CI publishes a
+[**bundle**](https://gitea.whitlocktech.com/RunicGateway/installer/src/branch/main/bundles/README.md):
+one exact, protocol-checked pair of sidecar + overlay versions. The installer resolves that at run
+time rather than hardcoding versions or blindly taking each repo's newest release.
+
+Consequences worth knowing:
+
+- A sidecar patch release does **not** mean re-downloading the installer. The bundle is data.
+- `--bundle <tag>` (e.g. `--bundle 2026.08.04`) pins an exact past combination, so a reinstall six
+  months from now reproduces today's install rather than tomorrow's.
+
+---
+
+## 2. Run it
+
+```bash
+sudo ./runicgateway-installer-linux-x86_64 install
+```
+
+```powershell
+# Windows: from an elevated PowerShell
+.\runicgateway-installer-windows-x86_64.exe install
+```
+
+Run `install --verify` first if you want to see exactly what would change and write nothing — the
+same idea as `deploy.ps1 -Verify`, which developers of the plugin use.
+
+The installer **does not install itself.** Keep the binary somewhere sensible on the host (it is
+one file); `doctor`, `update` and `uninstall` are run from it later. Examples below shorten it to
+`runicgateway`.
+
+### What it asks
+
+1. **Your ServUO root** — detected if the installer is run from inside it or from an obvious
+   sibling, otherwise prompted. A directory qualifies only if it contains `ServUO.exe`, `Scripts/`
+   and `Config/`.
+2. **Whether to apply the patch tier** — off unless you say yes. On a ServUO that is not 57.4 the
+   prompt defaults to **no** and carries an unsupported-version warning you have to answer past.
+   See [§4](#4-the-patch-tier-optional).
+3. **The hostname your website should use to reach this machine** — used only to compose the two
+   URLs it prints at the end. The sidecar's bind address is frequently `127.0.0.1` or `0.0.0.0`,
+   neither of which is something to hand to a website.
+4. **Your site's URL** — used only to print a clickable link to its Admin → Shard page. The
+   installer never contacts your website.
+
+### An illustrative run
+
+```
+Runic Gateway installer — bundle 2026.08.04 (protocol 3)
+
+  ServUO           /opt/ServUO  (57.4)
+  Shard process    not running
+  Overlay          servuo-plugins v0.1.1   protocol 3
+  Sidecar          uo-link v1.1.0          protocol 3
+
+✓ overlay tarball verified   sha256 75dc6d6c…
+✓ sidecar binary verified    sha256 27d491ef…
+
+Overlay sync
+  ADD     Config/Bridge.cfg
+  ADD     Scripts/Custom/Bridge/*.cs        (22 files)
+  CHANGE  Scripts/Scripts.csproj
+  deployed. add=23 change=1 unchanged=0
+
+Patch tier                    skipped (not selected)
+  Without it: no vendor.sale events, no in-game moderation audit forwarding.
+
+uo-link sidecar
+  binary           /usr/bin/runicgateway-link            install
+✓ sidecar binary verified    sha256 27d491ef…
+  config           /etc/runicgateway/sidecar.toml        created
+  database         /var/lib/runicgateway/uo-link.db
+  listening on     shard 127.0.0.1:7788   website 127.0.0.1:8080
+  service          runicgateway-link.service             active, enabled
+  running as       runicgateway
+
+Recorded /etc/runicgateway/install.json
+
+Scripts.csproj changed — ServUO rebuilds Scripts.dll on next boot.
+Start your shard when ready; the installer does not start it for you.
+```
+
+Then the [token handoff](#5-connect-the-website).
+
+### Commands and flags
+
+The surface this guide specifies. Each command is idempotent: a second run with nothing new to do
+reports "unchanged" and writes nothing.
+
+| Command | What it does |
+|---|---|
+| `install` | The full run above. |
+| `doctor` | Diagnoses an existing deployment end to end — see [§7](#7-day-two). |
+| `update` | Re-resolves the bundle; updates the sidecar (replace + restart) and the overlay (re-sync + tell you to restart ServUO). |
+| `uninstall` | Removes only what the installer exclusively owns; prints — never performs — anything inside your ServUO tree. |
+
+| Flag | Applies to | Meaning |
+|---|---|---|
+| `--verify` | `install`, `update` | Dry run. Report every change that would be made; write nothing. |
+| `--servuo <path>` | `install`, `doctor`, `update` | Name the ServUO root instead of detecting or prompting. |
+| `--bundle <tag>` | `install`, `update` | Pin an exact published bundle instead of the current one. |
+| `--patches` / `--no-patches` | `install` | Decide the patch tier non-interactively. `--patches` never loosens the region check: patches whose target lines are not stock are reported for you to apply by hand, not forced. |
+| `--patches-unsupported-servuo` | `install` | Required *in addition to* `--patches` to run the patch tier on a ServUO that is not 57.4. Unsupported and untested — see [§4](#4-the-patch-tier-optional). Ignored on 57.4. |
+| `--host <name>` | `install` | The hostname to print in the website URLs. |
+| `--site-url <url>` | `install` | Your site's base URL, for the Admin → Shard link. |
+| `--yes` | all | Assume the default answer to every prompt. Combine with the flags above for an unattended run. |
+| `--purge` | `uninstall` | Also delete `sidecar.toml` and `uo-link.db`, which are otherwise kept. |
+
+---
+
+## 3. Where everything lands
+
+**Linux**
+
+| Path | What |
+|---|---|
+| `/usr/bin/runicgateway-link` | The sidecar binary |
+| `/etc/runicgateway/sidecar.toml` | Sidecar config, including the auth token |
+| `/etc/runicgateway/install.json` | What the installer deployed: versions, commit, per-file hashes, applied patches, timestamps |
+| `/etc/runicgateway/patches/` | Copies of any patches applied, so `uninstall` can print the exact hunks long after the release tarball is gone |
+| `/var/lib/runicgateway/uo-link.db` | The sidecar's SQLite store (event history, cached profiles, link map) |
+| `/etc/systemd/system/runicgateway-link.service` | The service unit, running as a dedicated user |
+
+**Windows**
+
+| Path | What |
+|---|---|
+| `%ProgramFiles%\RunicGateway\uo-link-sidecar.exe` | The sidecar binary |
+| `%ProgramData%\RunicGateway\sidecar.toml` | Sidecar config, including the auth token |
+| `%ProgramData%\RunicGateway\install.json` | As above |
+| `%ProgramData%\RunicGateway\patches\` | As above |
+| `%ProgramData%\RunicGateway\uo-link.db` | The sidecar's SQLite store |
+| Service `RunicGatewayLink` | Automatic start, restart on failure, running as `NT SERVICE\RunicGatewayLink` |
+
+**Inside your ServUO tree** (added by the overlay sync — 24 files):
+
+```
+Config/Bridge.cfg                     every bridge setting, heavily commented
+Scripts/Custom/Bridge/*.cs            22 files: the plugin itself
+Scripts/Scripts.csproj                OVERWRITES a stock file (see below)
+```
+
+**Both service definitions pin the config path**, because the sidecar's own default is relative to
+its working directory — and a service manager's working directory is not somewhere you want a
+database or a config file. On Windows it can be `%SystemRoot%\System32` or, under
+`C:\Program Files\`, a silently redirected VirtualStore copy.
+
+How the *database* path is pinned differs by platform, and that is deliberate:
+
+| | Config | Database |
+|---|---|---|
+| **Linux** | `Environment=UOLINK_CONFIG=` in the unit | `Environment=UOLINK_DB_PATH=` in the unit — `/etc` and `/var/lib` are different directories, so both need naming |
+| **Windows** | `--config` inside the service's own `binPath` | nothing to set: a relative `[store] path` resolves against the config's directory, which *is* `%ProgramData%\RunicGateway` |
+
+The Windows service would otherwise need a **machine-wide** environment variable — `sc.exe` has no
+per-service one — which every process on the host inherits and which outlives an uninstall.
+
+**Both run as a dedicated, unprivileged account.** Linux gets a `runicgateway` system user; Windows
+gets a virtual service account, `NT SERVICE\RunicGatewayLink`, which Windows creates as part of
+registering the service and which has no password. Neither runs as root or `LocalSystem`.
+
+**`sidecar.toml` is locked down, because it holds your auth token.** Neither default location
+protects it on its own — `/etc` is world-readable, and `%ProgramData%` grants `Users` read access by
+inheritance — so the installer sets the permissions itself: `chmod 600` plus `chown` to the service
+user on Linux, and an explicit ACL of SYSTEM, Administrators and the service account on Windows.
+
+> **`Scripts.csproj` is overwritten deliberately.** The stock file omits `Scripts/Custom/`, so the
+> plugin would sit in the tree and never compile — and ServUO would not tell you, because it
+> ignores the script build's exit code and silently reloads the previous `Scripts.dll`. That
+> failure mode is the reason [§6](#6-start-servuo-and-verify) exists.
+
+---
+
+## 4. The patch tier (optional)
+
+Most of the plugin ships as **added** files, which is why the base install is a safe file copy. Two
+features cannot: they need edits to stock ServUO sources, because the events they depend on do not
+exist.
+
+| Patch | Edits | Gives you | Rebuild needed |
+|---|---|---|---|
+| `playervendor-sale-eventsink.patch` + `playervendor-sale-gump.patch` | `Server/EventSink.cs`, `Scripts/Gumps/PlayerVendorGumps.cs` | `vendor.sale` events — player-vendor purchases with buyer, owner, price and commission, which is what cheat detection needs | **Core solution rebuild** (`dotnet build ServUO.sln`) — the dynamic script build is not enough |
+| `commandlogging-event.patch` | `Scripts/Commands/Logging.cs` | In-game moderation actions (`[ban`, `[kick`, `[bcast`) forwarded to the website's moderation log as `admin.audit` | Script build only — a shard restart is enough |
+
+Each patch has a companion `.cs` file that is copied **only after** its patch applies, because it
+references symbols the patch introduces. That is why they are not in the base overlay: shipping them
+unconditionally would break the build on every unpatched install.
+
+How the installer handles it:
+
+- **Opt-in.** The base install completes without it, and declining is a supported outcome, not a
+  degraded one.
+- **Dry-run first, always.** Every patch is checked before anything is applied, and reported per
+  patch. Most real shards are hand-modified; a patch that does not apply is expected, not alarming.
+- **A modified file is not automatically a refusal.** These patches touch three small regions of
+  three large files. If you have edited `Logging.cs` somewhere else entirely, the installer says so
+  and still applies the patch — it checks whether *the lines the patch edits* are still stock, not
+  whether the whole file is. It applies only where the surrounding lines match the patch exactly and
+  appear exactly once; anything less and it stops and hands you the hunk to apply by hand. It never
+  force-fits a patch by loosening the match.
+- **All or nothing per feature.** The two vendor-sale patches are one unit and are applied together
+  or not at all — and within a patch, if one hunk cannot be placed safely, none are.
+- **Your ServUO version is reported, not decisive** — but see the warning below before running this
+  on anything other than 57.4.
+- **Recorded, and the `.patch` files cached**, so re-runs stay idempotent and `uninstall` can print
+  the exact hunks to revert — along with how each was applied, since a patch placed into a file you
+  had already modified is one to look at more carefully when reverting.
+
+### ⚠ On any ServUO that is not 57.4: unsupported, untested, no guarantees
+
+> **Runic Gateway is designed, built and tested against stock ServUO 57.4.** That is the only
+> supported version.
+>
+> On any other version — a newer release, an older one, or a fork — the patch tier is
+> **UNSUPPORTED, UNTESTED, and NOT GUARANTEED TO WORK.** You may run it. If you do, you are on your
+> own: it is not covered by support, and a bad outcome may not show up until your shard is live,
+> because ServUO's script build reports success even when it failed and quietly keeps running the
+> previous `Scripts.dll`.
+>
+> The installer will still refuse to place a patch anywhere the exact lines it edits have changed —
+> but matching text is not the same as matching behaviour. A hunk can land correctly and still be
+> wrong for a tree that has diverged around it.
+>
+> **Back up your ServUO tree first, and verify your shard boots and compiles afterwards.**
+
+Because of that, on a non-57.4 tree the tier is off by default and takes a deliberate yes:
+
+- the interactive prompt defaults to **no** and prints the warning above;
+- `--patches` on its own is **not** enough — an unattended run must also pass
+  `--patches-unsupported-servuo`;
+- the choice is recorded, and `doctor` keeps showing an unsupported-version row for the life of the
+  install — so whoever looks after this shard next can see it without being told.
+
+A run where the tier is selected on a shard that has been worked on looks like this:
+
+```
+Patch tier                    2 of 3 applied
+  ✓ playervendor-sale-eventsink   Server/EventSink.cs            stock file
+  ✓ playervendor-sale-gump        Scripts/Gumps/PlayerVendorGumps.cs
+                                  file modified, patched region stock — applied at line 1180
+  ✗ commandlogging-event          Scripts/Commands/Logging.cs
+                                  patched region has been modified — not applied
+                                  apply this hunk by hand, then re-run install:
+                                    /etc/runicgateway/patches/commandlogging-event.patch
+
+  ⚠ Server/EventSink.cs changed — rebuild the core: dotnet build ServUO.sln
+  Without commandlogging-event: no in-game moderation audit forwarding.
+```
+
+If it is skipped or fails, you lose exactly two things — **`vendor.sale` events** and **in-game
+moderation audit forwarding**. Everything else works. You can apply the patches later by hand (see
+`patches/README.md` in the tarball) and re-run `install` to record it.
+
+---
+
+## 5. Connect the website
+
+The installer ends a successful run by printing the one manual step it cannot do for you:
+
+```
+Runic Gateway is installed.
+
+One manual step remains — connect the website to this sidecar:
+
+  Base URL          http://shard.example.com:8080
+  WebSocket URL     ws://shard.example.com:8080/ws
+  Protocol version  3
+  Auth token        4f9c…   (also in /etc/runicgateway/sidecar.toml)
+
+Paste these into  Admin → Shard  on your Runic Gateway site:
+  https://your-site.example/admin/shard
+
+The token is write-only once saved — the site will never show it back to you.
+```
+
+Every value there comes from asking the installed sidecar itself (`--print-config`), not from a
+log file or a guess, so it cannot drift from what the service actually runs.
+
+On your site, sign in as an administrator and open **Admin → Shard (uo-link)**:
+
+| Field on the page | Paste |
+|---|---|
+| Enable the shard integration | ✔ on |
+| Base URL (REST) | the **Base URL** line |
+| WebSocket URL (feed) | the **WebSocket URL** line |
+| Auth token | the **Auth token** line |
+| Protocol | the **Protocol version** line (`3`) |
+
+Saving restarts the site's ingest client, so the change takes effect immediately. The token is
+AES-GCM encrypted at rest and **never returned to any client** — losing it means reading it back
+from `sidecar.toml` on the shard host, not from the website.
+
+### If your website is on a different machine
+
+The sidecar binds `127.0.0.1:8080` by default, which is reachable only from the shard host. If your
+website runs elsewhere, you must widen the bind — and then narrow the access:
+
+1. Set `[web] bind` in `sidecar.toml` to `0.0.0.0:8080` (or a specific LAN address) and restart the
+   service.
+2. **Firewall port 8080 to your website's address only.** The auth token is always on, but it
+   travels as a plain bearer token — the sidecar speaks HTTP, not HTTPS.
+3. If the two hosts are not on a trusted network, put the sidecar behind a TLS reverse proxy or a
+   VPN/WireGuard link, and give the website the proxied `https://` / `wss://` URLs.
+
+The `[shard] bind` line is a different matter: leave it on `127.0.0.1:7788`. That socket accepts
+*inbound commands* to the game, and being loopback-only is what makes that safe.
+
+---
+
+## 6. Start ServUO and verify
+
+Start your shard the way you always do. Then confirm the bridge is actually live — not merely
+installed. **A successful file copy is not a working bridge**: ServUO shells out to `dotnet build`,
+prints the output, ignores the exit code, and reloads the existing `Scripts.dll`, so a broken script
+build looks exactly like a clean boot.
+
+**a. Watch the boot output.** You want to see the build succeed *and* the bridge announce itself:
+
+```
+Core: Compiling scripts...
+Build succeeded.
+[Bridge] enabled=True endpoint=127.0.0.1:7788 queueCap=10000 sweeps(stat=30s decay=60s …
+```
+
+If you scrolled past it, force the question:
+
+```bash
+cd <servuo root>
+dotnet build Scripts/Scripts.csproj -c Release -p:Platform=x64      # must be 0 errors
+```
+
+**b. Ask the shard, in game.** As an Administrator:
+
+```
+[bridge status
+```
+
+It reports the config plus `connected=True depth=0 sent=… dropped=0 …`. `connected=False` means the
+shard cannot reach the sidecar; `dropped` climbing means the sidecar is wedged and the shard is
+shedding events rather than stalling — which it is designed to do. `[bridge reload` re-reads
+`Bridge.cfg` without a restart; `[bridge sweepnow` forces one pass of every stream.
+
+**c. Ask the sidecar.** `/health` needs no auth, so it is safe to curl from a terminal:
+
+```bash
+curl -s http://127.0.0.1:8080/health
+{"status":"ok","protocol":3,"plugin_connected":true,"database":"ok","uptime":"2m","last_event":"2026-08-04T18:22:10.412Z"}
+```
+
+`plugin_connected: true` is the one that matters — it is the only value in this whole guide that
+distinguishes "files copied" from "the bridge works".
+
+**d. Ask the website.** The public site should stop showing the shard as offline, and live events
+should appear on the admin dashboard within seconds.
+
+---
+
+## 7. Day two
+
+### `runicgateway doctor`
+
+The command that makes this supportable. Run it before asking anyone for help — its output is the
+first thing a maintainer will want.
+
+```
+✓ ServUO found            /opt/ServUO  (57.4)
+✓ Overlay in sync         24 files, all hashes match install.json
+⚠ Patch tier              1 of 3 applied (region-match) — vendor.sale unavailable
+✓ uo-link installed       1.1.0
+✓ Service                 running, enabled
+✓ Sidecar reachable       127.0.0.1:8080  /health ok
+✓ Protocol                sidecar 3 = overlay manifest 3
+✗ Shard connected         no shard has dialed in since boot
+```
+
+Three of those rows come from asking the installed sidecar (`--version`, `--print-config`) rather
+than from reading `install.json`, so `doctor` reports what the binary would actually do — including
+which config and database file the *service* resolves — rather than what the installer believes it
+was told. The overlay row compares live file hashes against both `install.json` and the release
+manifest, which is how it tells "you edited a deployed file" from "the overlay moved on".
+
+### `runicgateway update`
+
+Re-resolves the bundle and moves both halves to a combination whose protocol versions were checked
+together — never to two independently-latest artifacts that may disagree.
+
+- **Sidecar**: download → verify → replace binary → restart service. No shard downtime.
+- **Overlay**: download → verify → re-sync → record the new commit → **tell you to restart ServUO.**
+  It does not restart your shard.
+
+Your `sidecar.toml`, your `Bridge.cfg` edits and your database are not touched. `Bridge.cfg` is
+overwritten only if you have not changed it; a modified copy is reported, not clobbered.
+
+### `runicgateway uninstall`
+
+Removes what it exclusively owns, and **prints** everything else. The installer cannot know what you
+have changed in your own server tree since deployment, so an automatic revert risks silently eating
+your work.
+
+| | |
+|---|---|
+| **Removed** | The sidecar binary, its service entry, `install.json`, the cached patch set |
+| **Kept** | `sidecar.toml` and `uo-link.db` — config and history survive (`--purge` drops them) |
+| **Printed, not done** | Every overlay file deployed into your ServUO tree, by path, for you to delete |
+| **Printed, not done** | The exact hunks each applied patch added to `EventSink.cs`, `PlayerVendorGumps.cs` and `Logging.cs`, for you to revert |
+
+The report is also written to a file, so it survives the scrollback.
+
+---
+
+## Troubleshooting
+
+| Symptom | Cause and fix |
+|---|---|
+| **Windows asks for Administrator as soon as you launch it** | Expected, and it needs Administrator anyway. Windows applies *installer detection* to unsigned executables whose file name contains `install` and elevates them before the program starts. Run it from an already-elevated PowerShell and you will not see the prompt. |
+| **"ServUO is running — stop it before installing"** | Correct, and not overridable. `ServUO.exe` locks `Scripts.dll` and rewrites `Saves/` on exit; deploying underneath it corrupts one or both. Stop the shard, install, start it again. |
+| Shard boots clean but nothing reaches the site | The classic silent failure: ServUO ignores the script build's exit code and reloaded a **stale `Scripts.dll`**. Run `dotnet build Scripts/Scripts.csproj -c Release -p:Platform=x64` and read the errors it prints. |
+| `[bridge status` says `connected=False` | The sidecar is not listening on `127.0.0.1:7788`. Check the service is running, and that `[shard] bind` in `sidecar.toml` matches `Host`/`Port` in `Bridge.cfg`. |
+| `[bridge` is not a command | The plugin did not compile, or `Bridge.cfg` has the bridge disabled. See the row above. |
+| Website says the shard is offline; `/health` is fine locally | The website cannot reach port 8080 — bind address or firewall. See [§5](#if-your-website-is-on-a-different-machine). Note that the site is *designed* to render normally with the shard offline, so this fails quietly by design. |
+| Website logs `409` from the sidecar | Protocol mismatch: the number in Admin → Shard does not match the sidecar's. The sidecar rejects rather than mis-parsing. Set the field to what `/health` reports (`protocol`). If the *sidecar* and *overlay* disagree, you have a hand-assembled pair — reinstall from a bundle. |
+| `401` from the sidecar | Wrong or missing auth token. Read the live one back with `uo-link-sidecar --print-config --config <path>`; do not retype it from a screenshot. |
+| **"service NOT REGISTERED" at the end of an otherwise successful run** | The host has no service manager the installer can drive — most often no systemd (a container, or a distro that never had it), or the `runicgateway` user could not be created. The binary and config *are* installed; the run prints the exact unit and commands to finish by hand. It never falls back to running the service as root or `LocalSystem`. |
+| Service registered but stops immediately | It cannot read its config. On Windows check that `sc qc RunicGatewayLink` shows `--config` in `BINARY_PATH_NAME` and that `NT SERVICE\RunicGatewayLink` has read access to `sidecar.toml`; on Linux check the `runicgateway` user can read `/etc/runicgateway/sidecar.toml` and write `/var/lib/runicgateway/`. |
+| A patch will not apply | Expected on a hand-modified shard. The base install is unaffected; you lose only the two features in [§4](#4-the-patch-tier-optional). Apply the hunks by hand if you want them. |
+| `vendor.sale` events never arrive despite patching | The `EventSink.cs` patch is a **core** change. A shard restart is not enough — rebuild the solution (`dotnet build ServUO.sln`). |
+| Sidecar writes its database somewhere unexpected | A relative `[store] path` resolves against the directory holding `sidecar.toml` — not the working directory. Run `--print-config` to see the absolute path it will actually use. |
+| Token leaked into a log or a screenshot | Clear `[web] auth_token` in `sidecar.toml`, restart the service (a new token is generated and saved), read it back with `--print-config`, and re-save it in Admin → Shard. |
+
+---
+
+## Appendix A — installing by hand
+
+This is what the installer automates. It works today, on the current releases, and is the fallback
+whenever you would rather not run an unsigned binary.
+
+Throughout: `<servuo>` is your ServUO root, and **the shard is stopped**.
+
+### A1. Fetch the bundle (so you install a checked pair)
+
+```bash
+curl -s https://gitea.whitlocktech.com/RunicGateway/installer/raw/branch/main/bundles/current.json
+```
+
+It names the sidecar tag, the overlay tag, their agreed `protocol`, and the SHA256 of every asset.
+Use those versions together; that pairing is the only thing CI has verified.
+
+### A2. Deploy the plugin overlay
+
+```bash
+curl -LO https://gitea.whitlocktech.com/RunicGateway/servuo-plugins/releases/download/v0.1.1/runicgateway-overlay-0.1.1.tar.gz
+curl -LO https://gitea.whitlocktech.com/RunicGateway/servuo-plugins/releases/download/v0.1.1/SHA256SUMS
+sha256sum -c SHA256SUMS --ignore-missing        # must say: OK
+
+tar xzf runicgateway-overlay-0.1.1.tar.gz       # → runicgateway-overlay/
+cd runicgateway-overlay
+cat manifest.json                               # version, commit, protocol, per-file hashes
+
+cp -r overlay/. <servuo>/                       # adds files; overwrites Scripts/Scripts.csproj
+```
+
+On Windows, `Expand-Archive` does not read `.tar.gz`; use `tar.exe` (shipped with Windows 10+) and
+`Copy-Item -Recurse -Force`. Plugin developers have `deploy.ps1` in the source repo, which does the
+same copy with a hash diff and a `-Verify` dry run — it is not shipped in the tarball.
+
+The overlay only ever **adds or overwrites**. Nothing in your tree is deleted.
+
+*Optional — the patch tier* (stock ServUO 57.4 only; see `patches/README.md` in the tarball for the
+full explanation):
+
+```bash
+cd <servuo>
+git apply --check patches/playervendor-sale-eventsink.patch patches/playervendor-sale-gump.patch
+git apply         patches/playervendor-sale-eventsink.patch patches/playervendor-sale-gump.patch
+cp patches/BridgeVendorSale.cs Scripts/Custom/Bridge/
+dotnet build ServUO.sln          # REQUIRED — EventSink.cs is a core file
+
+git apply --check patches/commandlogging-event.patch
+git apply         patches/commandlogging-event.patch
+cp patches/BridgeModerationAudit.cs Scripts/Custom/Bridge/
+```
+
+`git apply` works in a plain directory — the shard does not need to be a git repo. If you use
+`patch` instead, note the core files are CRLF: use `patch --binary`.
+
+### A3. Install the sidecar
+
+```bash
+curl -LO https://gitea.whitlocktech.com/RunicGateway/link/releases/download/v1.1.0/uo-link-sidecar-linux-x86_64
+curl -LO https://gitea.whitlocktech.com/RunicGateway/link/releases/download/v1.1.0/SHA256SUMS
+sha256sum -c SHA256SUMS --ignore-missing
+
+sudo install -m 0755 uo-link-sidecar-linux-x86_64 /usr/bin/runicgateway-link
+sudo mkdir -p /etc/runicgateway /var/lib/runicgateway
+```
+
+Provision the config and read back the token in one step. `--print-config` writes the file if it is
+missing, generates the auth token if there is none, and prints the resolved settings as JSON — it is
+the supported alternative to scraping the startup log:
+
+```bash
+sudo UOLINK_DB_PATH=/var/lib/runicgateway/uo-link.db \
+     /usr/bin/runicgateway-link --print-config --config /etc/runicgateway/sidecar.toml
+```
+
+```json
+{
+  "component": "uo-link-sidecar",
+  "version": "1.1.0",
+  "protocol": 3,
+  "config_path": "/etc/runicgateway/sidecar.toml",
+  "config_created": true,
+  "token_generated": true,
+  "shard": { "bind": "127.0.0.1:7788" },
+  "web": {
+    "bind": "127.0.0.1:8080",
+    "ws_path": "/ws",
+    "auth_required": true,
+    "auth_token": "4f9c…"
+  },
+  "store": { "path": "/var/lib/runicgateway/uo-link.db" }
+}
+```
+
+`config_created` and `token_generated` tell you whether *this* run provisioned anything — the values
+alone cannot distinguish a fresh install from a re-read. **The output contains the auth token in
+clear text**: keep it out of shell transcripts, logs and support bundles.
+
+### A4. Register the service
+
+**Linux** — `/etc/systemd/system/runicgateway-link.service`:
+
+```ini
+[Unit]
+Description=Runic Gateway uo-link sidecar
+After=network.target
+
+[Service]
+Type=simple
+User=runicgateway
+Environment=UOLINK_CONFIG=/etc/runicgateway/sidecar.toml
+Environment=UOLINK_DB_PATH=/var/lib/runicgateway/uo-link.db
+ExecStart=/usr/bin/runicgateway-link
+Restart=on-failure
+RestartSec=5
+
+[Install]
+WantedBy=multi-user.target
+```
+
+```bash
+sudo useradd --system --no-create-home runicgateway
+sudo chown -R runicgateway /var/lib/runicgateway /etc/runicgateway
+sudo systemctl daemon-reload
+sudo systemctl enable --now runicgateway-link
+systemctl status runicgateway-link
+```
+
+**Windows** (elevated PowerShell) — binary under `%ProgramFiles%`, data under `%ProgramData%`:
+
+```powershell
+New-Item -ItemType Directory -Force "$env:ProgramFiles\RunicGateway", "$env:ProgramData\RunicGateway" | Out-Null
+Copy-Item .\uo-link-sidecar-windows-x86_64.exe "$env:ProgramFiles\RunicGateway\uo-link-sidecar.exe"
+
+& "$env:ProgramFiles\RunicGateway\uo-link-sidecar.exe" --print-config --config "$env:ProgramData\RunicGateway\sidecar.toml"
+
+# The config file now holds your auth token. Lock it down before anything else can read it:
+icacls "$env:ProgramData\RunicGateway\sidecar.toml" /inheritance:r /grant:r '*S-1-5-18:(F)' /grant:r '*S-1-5-32-544:(F)'
+
+# binPath carries the config path. The single quotes matter: the value itself contains the double
+# quotes the service manager needs around a path with spaces in it.
+sc.exe create RunicGatewayLink `
+  binPath= '"C:\Program Files\RunicGateway\uo-link-sidecar.exe" --config "C:\ProgramData\RunicGateway\sidecar.toml"' `
+  obj= 'NT SERVICE\RunicGatewayLink' start= auto
+sc.exe failure RunicGatewayLink reset= 86400 actions= restart/5000
+
+# The service account exists only once sc create has created it, so its grants come after:
+icacls "$env:ProgramData\RunicGateway\sidecar.toml" /grant 'NT SERVICE\RunicGatewayLink:(R)'
+icacls "$env:ProgramData\RunicGateway"              /grant 'NT SERVICE\RunicGatewayLink:(OI)(CI)M'
+
+sc.exe start RunicGatewayLink
+```
+
+Three things there are easy to get wrong:
+
+- **The config path goes in `binPath`, not in a machine environment variable.** `sc.exe` has no
+  per-service environment, and a machine-wide `UOLINK_CONFIG` would be inherited by every process on
+  the host and survive an uninstall. Never leave the config path to the default — it is relative to
+  the service's working directory, which for a service is `%SystemRoot%\System32`.
+- **The database needs no pinning here.** A relative `[store] path` resolves against the directory
+  holding `sidecar.toml`, which is already `%ProgramData%\RunicGateway`.
+- **`obj=` is what keeps this off `LocalSystem`.** `NT SERVICE\RunicGatewayLink` is a virtual
+  service account: Windows creates it with the service, it has no password, and it exists only for
+  this service. Omit `obj=` and you get the most privileged local identity there is, for a process
+  listening on two TCP ports.
+
+### A5. Connect the website, start the shard, verify
+
+Exactly as in [§5](#5-connect-the-website) and [§6](#6-start-servuo-and-verify): paste the four
+values into Admin → Shard, start ServUO, then check `[bridge status` in game and `/health` on the
+sidecar.
+
+### A6. Updating by hand
+
+Re-read `current.json`, and if either version moved: replace the sidecar binary and restart its
+service; re-extract the overlay tarball over your tree and restart ServUO. Keep the two in step —
+`current.json` is the only statement that a given pair speaks the same protocol.
+
+---
+
+## Appendix B — `sidecar.toml` reference
+
+Written on first run with a generated token. Environment variables override the file; the file
+overrides these defaults.
+
+```toml
+[shard]
+bind = "127.0.0.1:7788"     # where the SHARD dials in. Keep this on loopback.
+
+[web]
+bind = "127.0.0.1:8080"     # where the WEBSITE connects. Widen only with a firewall in front.
+auth_token = "…"            # generated if blank; the website's Admin → Shard "Auth token"
+
+[store]
+path = "uo-link.db"         # relative paths resolve against this file's directory, not the CWD
+```
+
+| Environment variable | Overrides |
+|---|---|
+| `UOLINK_CONFIG` | Which config file to read (`--config <PATH>` outranks it) |
+| `UOLINK_SHARD_BIND` | `[shard] bind` |
+| `UOLINK_WEB_BIND` | `[web] bind` |
+| `UOLINK_WEB_TOKEN` | `[web] auth_token` |
+| `UOLINK_DB_PATH` | `[store] path` |
+
+| Sidecar command | Output |
+|---|---|
+| `uo-link-sidecar --version` | `uo-link-sidecar 1.1.0 (protocol 3)` |
+| `uo-link-sidecar --print-config [--config PATH]` | The JSON in [A3](#a3-install-the-sidecar). Provisions on first run. **Contains the token.** |
+| `uo-link-sidecar --help` | Usage. An unrecognized argument exits `2` rather than starting a sidecar you did not ask for. |
+
+Authentication is **always on**: a blank token is generated and written back, so the web surface is
+never unauthenticated. `/health` is the one unauthenticated route, so monitoring can reach it.
+
+---
+
+## Appendix C — `Config/Bridge.cfg` settings worth reviewing
+
+The file is deployed heavily commented and every setting has a working default — you can leave it
+entirely alone. These are the ones most shards want to look at once. Run `[bridge reload` after
+editing; endpoint changes take effect on the next reconnect.
+
+| Setting | Default | Why you might change it |
+|---|---|---|
+| `LinkUrl` | `https://yoursite/link` | Shown in game when a player runs `[link` to connect their account. **Set this to your site.** |
+| `PublicConnectAddress` | *(blank)* | The one connection detail the bridge will publish, e.g. `play.myshard.com,2593`. Blank omits it; `Server.cfg`'s address is **never** published automatically. |
+| `AdminWriteEnabled` | `false` | Opt-in staff write plane: kick/ban/broadcast from the website. Authorization is enforced on the website; `AdminAccessFloor` is the shard-side floor that even a compromised sidecar cannot cross. |
+| `MarketEnabled`, `MarketSweepSeconds`, `MarketSweepBatch` | `true`, `60`, `25` | The player-vendor index. Coverage takes `ceil(vendors / batch) × seconds` — 500 vendors is one full pass every 20 minutes at the defaults. |
+| `PointsLeaderboardEnabled`, `PointsTopN`, `PointsSystems` | `true`, `10`, *(all shown on the loyalty gump)* | Standings boards. One frame **per system**, and ServUO carries ~25 of them, so a large `TopN` multiplies. |
+| `RulesetEnabled`, `RulesetIncludeSchedule` | `true`, `true` | Publishes your ruleset (expansion, caps, systems on/off) to the site's rules page. Turn the schedule off if you would rather not advertise a predictable restart window. |
+| `SignupMode` | `hybrid` | Which side may mint accounts — `website`, `game`, or `hybrid`. Pair `website` with `Accounts.AutoCreateAccounts=false`, or an in-game login still creates accounts. |
+| `QueueCap` | `10000` | Outbound queue cap. On overflow the plugin **drops oldest** and counts drops, because a stalled sidecar must never take the shard down with it. |
+
+Sweep intervals (`StatSweepSeconds`, `DecaySweepSeconds`, `EconomySweepSeconds`, and the rest) trade
+freshness against Core-thread time. The measured cost is small — a vitals sweep is 0.0015 ms per
+character, so 1000 online players is ~1.5 ms per pass — but there is rarely anything to gain by
+hurrying them.
+
+---
+
+## Where to go next
+
+| Doc | What |
+|---|---|
+| [PLAN.md](PLAN.md) | The installer's design of record — phases, locked decisions, the bundle model |
+| [`bundles/README.md`](https://gitea.whitlocktech.com/RunicGateway/installer/src/branch/main/bundles/README.md) | The compat matrix: what a bundle is and how it is composed |
+| [link/INTEGRATION.md](../link/INTEGRATION.md) | The sidecar's HTTP/WS API — for anyone integrating something other than the website |
+| [link/ADMIN_CONTROLS.md](../link/ADMIN_CONTROLS.md) | The staff write plane in detail, before you turn `AdminWriteEnabled` on |
+| [website/SHARD_VISIBILITY.md](../website/SHARD_VISIBILITY.md) | Which shard data each audience sees, configured on the website |
+| [link/SHARD_PREREQS.md](../link/SHARD_PREREQS.md) | A worked example of diagnosing a shard whose scripts silently stopped compiling |

installer/PLAN.md

@@ -0,0 +1,939 @@
+# Runic Gateway Installer — plan
+
+Status: **Phases 1 and 2 built, on `edge`.** Phase 0's prerequisites all landed, the installer repo
+publishes the bundle manifest, and [`INSTALL.md`](INSTALL.md) specified the operator-facing run
+before the binary existed. The crate now implements the installer core (bundle resolution, ServUO
+detection and validation, the overlay sync, `install.json` — [Phase 1 as
+built](#phase-1--installer-core)) and the sidecar half (binary, config, service, token handoff —
+[Phase 2 as built](#phase-2--uo-link-install-and-service)). Both are on the `edge` branch, not
+`main`, so no half-capable binary is released. **Phase 3 (the patch tier) is next, and the
+`edge → main` cutover follows it** rather than Phase 2: `INSTALL.md` §4 describes the tier as part
+of the run, and a first release whose every patch-tier answer is "not implemented" is the same
+half-capable binary that kept Phase 1 off `main`.
+This document is the design of record; it supersedes the informal overview it grew out of, which
+described a ServUO integration that does not match how `servuo-plugins` actually ships (see
+[Corrections](#corrections-to-the-original-overview)).
+
+| Phase 0 item | State |
+|---|---|
+| 0.1 `servuo-plugins` release workflow | ✅ Merged — [servuo-plugins#7](https://gitea.whitlocktech.com/RunicGateway/servuo-plugins/pulls/7) + [#8](https://gitea.whitlocktech.com/RunicGateway/servuo-plugins/pulls/8); first overlay release is [`v0.1.1`](https://gitea.whitlocktech.com/RunicGateway/servuo-plugins/releases/tag/v0.1.1) |
+| 0.2 `link` installable (data paths + `--print-config`) | ✅ Merged — [link#24](https://gitea.whitlocktech.com/RunicGateway/link/pulls/24) (docs half [docs#84](https://gitea.whitlocktech.com/RunicGateway/docs/pulls/84)); released as [`v1.1.0`](https://gitea.whitlocktech.com/RunicGateway/link/releases/tag/v1.1.0) |
+| 0.3 Bundle CI in the installer repo | ✅ Merged — [installer#3](https://gitea.whitlocktech.com/RunicGateway/installer/pulls/3), plus the dispatch step in each component ([link#25](https://gitea.whitlocktech.com/RunicGateway/link/pulls/25), [servuo-plugins#9](https://gitea.whitlocktech.com/RunicGateway/servuo-plugins/pulls/9)). First bundle: [`2026.08.04`](https://gitea.whitlocktech.com/RunicGateway/installer/src/branch/main/bundles/current.json) |
+| 0.4 This file + `INSTALL.md` | ✅ Merged — [docs#87](https://gitea.whitlocktech.com/RunicGateway/docs/pulls/87). [`INSTALL.md`](INSTALL.md) is the operator guide, written before the binary because it *is* the specification of the run |
+| — Repo bootstrap (governance + CI) | ✅ [`RunicGateway/installer`](https://gitea.whitlocktech.com/RunicGateway/installer) created; workflows merged ([installer#1](https://gitea.whitlocktech.com/RunicGateway/installer/pulls/1), [#2](https://gitea.whitlocktech.com/RunicGateway/installer/pulls/2)) |
+
+---
+
+## 1. Purpose
+
+Take a stock ServUO installation and configure it for Runic Gateway with minimal manual steps, while
+keeping the components separated and independently maintainable.
+
+The installer handles environment detection, ServUO overlay deployment, the optional stock-file
+patch tier, uo-link installation and service registration, version tracking, diagnostics, and
+updates from Gitea releases.
+
+**It is a deployment tool, not a hosted bootstrapper.** There is no `curl | bash`, no installer
+service, and no hosted bootstrap script. Artifacts are downloaded from a Gitea release page and run.
+
+**It does not replace ServUO startup behavior.** ServUO keeps running through its existing
+release/start scripts. The installer never writes a launcher.
+
+### Decisions locked
+
+| Question | Decision |
+|---|---|
+| Audience | **Public** — any ServUO operator, not just shards we run |
+| Code signing | **Unsigned.** `SHA256SUMS` is the trust anchor; SmartScreen/Gatekeeper warnings are expected and documented, as with most self-hosted tooling |
+| Language | **Rust** — single static binary per OS, reuses the cross-compile pattern already proven in `link/.gitea/workflows/release.yml` |
+| Plugin source | **Release tarball artifact** — no git and no Gitea credentials on the shard host |
+| Composition | **Published bundle manifest** (§7.1). CI names an exact, protocol-checked combination of component versions; the installer fetches it at run time and `--bundle <tag>` pins one. Component releases regenerate JSON, not the installer binary |
+| Token handoff | **Print token + prefilled admin URL** at the end of the run |
+| Repo | **New repo**, `RunicGateway/installer`. It deploys *both* other components, so living inside `link/` would invert the dependency |
+| ServUO version | **57.4 is the only supported version.** The patch tier's gate is content, not a version string: a patch applies where the lines it edits are still stock and is handed to the operator where they are not (§2.2.1). Forks and hand-edited trees are the norm in a public audience, so a non-57.4 tree is still *allowed* to attempt the tier — but **unsupported, untested and not guaranteed**, behind a loud banner, a defaulted-to-no prompt and its own opt-in flag (§2.2.2) |
+| Uninstall | **Never touches the ServUO tree.** Removes uo-link and its service entry, then *prints* the overlay files to delete and the patch hunks to revert. Reverting is the operator's call |
+
+---
+
+## 2. Corrections to the original overview
+
+These are not wording nits — each one changes what the installer has to do.
+
+### 2.1 There is no `RunicGateway.dll` and no `Plugins/` directory
+
+The plugin ships as **C# source** and ServUO compiles it at boot. The real deployable is
+`servuo-plugins/overlay/`, which mirrors the server root:
+
+```
+overlay/
+├── Config/Bridge.cfg
+└── Scripts/
+    ├── Scripts.csproj                 # Phase 0 — whole-file overwrite of a stock file
+    └── Custom/Bridge/*.cs             # 22 files
+```
+
+So the plugin step is a hash-compare file sync, not a DLL drop — mechanically easier than the
+overview assumed. The sting is that **a successful copy does not mean a working bridge.** Per
+`link/SHARD_PREREQS.md`, `ScriptCompiler.Compile()` shells out to `dotnet build`, prints the output,
+**ignores the exit code**, and reloads the existing `Scripts.dll`. A broken script build is
+invisible: the shard boots clean on stale code. Diagnostics must therefore verify *post-boot* state,
+never treat "files copied" as success.
+
+### 2.2 Stock ServUO files *are* modified — by an optional tier
+
+`servuo-plugins/patches/` holds unified diffs against stock ServUO 57.4, plus two `.cs` files that
+can only be copied *after* their patch lands (they reference symbols the patch introduces):
+
+| Patch | Target | Companion file | Rebuild required |
+|---|---|---|---|
+| `playervendor-sale-eventsink.patch` | `Server/EventSink.cs` | `BridgeVendorSale.cs` | **Core** — `dotnet build ServUO.sln`; the dynamic script build is not enough |
+| `playervendor-sale-gump.patch` | `Scripts/Gumps/PlayerVendorGumps.cs` | (same unit as above) | script build |
+| `commandlogging-event.patch` | `Scripts/Commands/Logging.cs` | `BridgeModerationAudit.cs` | script build |
+
+Plus `overlay/Scripts/Scripts.csproj`, which overwrites a stock file (Phase 0 — it fixes the silent
+ServUO build bug above).
+
+This is the hardest part of the installer. `git apply` against a hand-modified shard will fail, and
+most real shards are hand-modified. Therefore:
+
+- The patch tier is **opt-in and skippable**. The base install must complete without it.
+- Always dry-run (`git apply --check`) before applying, and report per-patch.
+- When skipped or failed, say plainly what is lost: **no `vendor.sale` events, no in-game moderation
+  audit forwarding**.
+- The `EventSink.cs` patch must warn loudly that a **core solution rebuild** is required, not just a
+  shard restart.
+- Record applied patches in `install.json`, **and cache the applied `.patch` files** next to it
+  (`/etc/runicgateway/patches/`, `%ProgramData%\RunicGateway\patches\`). Re-runs stay idempotent,
+  and uninstall can print the exact hunks offline long after the release tarball is gone (§5,
+  Phase 4).
+
+#### 2.2.1 A whole-file hash mismatch is not a verdict — check the region
+
+A file-level hash compare answers "is this entire file stock?", which is the wrong question. The
+patches touch three small regions of three large files; an operator who added a custom command to
+`Logging.cs` or a hook to `EventSink.cs` has changed the file's hash without going anywhere near the
+lines the patch edits. Refusing on the file hash alone hands most real shards a manual patch job
+they did not need. So the decision is made in three rungs, cheapest and safest first, and only the
+last one gives up:
+
+| Rung | Test | Outcome |
+|---|---|---|
+| **0 — already applied** | The hunk's *post*-patch text appears in the file | No-op, recorded as applied. Keeps re-runs idempotent |
+| **1 — file is stock** | Whole-file hash matches the patch's pre-image (`index <old>..<new>` in the diff — `git hash-object` on the target reproduces it) | Apply verbatim with `git apply` |
+| **2 — region is stock** | File differs, but every hunk's stock-side region is still byte-identical | Apply hunk-by-hunk at the matched offsets |
+| **3 — region is modified** | Anything else | **Do not touch the file.** Print the path, the hunks and what is lost; the operator patches by hand |
+
+Rung 2 is the semantic review, and it needs no new metadata: a unified diff already carries the
+stock text of the region it edits — the context lines plus the `-` lines *are* the pre-image. For
+each hunk the installer reconstructs that block and searches the target file for it, under these
+rules:
+
+- **Exact match, not fuzzy.** Only line-ending (CRLF/LF) and trailing-whitespace normalization is
+  allowed. No `patch --fuzz`, no context reduction: dropping context to force a match is precisely
+  how a patch lands in the wrong method.
+- **Exactly one occurrence, or it fails.** Zero means the region moved or was edited. More than one
+  means the anchor is ambiguous and the installer cannot know which the author meant. Both are
+  rung 3.
+- **Line numbers are advisory.** The hunk header's offsets are used only to prefer the nearest
+  candidate when reporting; the match itself is by content, since insertions above the region shift
+  every number below it.
+- **All-or-nothing per patch file.** If one hunk of a patch reaches rung 3, none of that patch's
+  hunks are applied. A half-patched `EventSink.cs` compiles against a companion `.cs` that expects
+  the whole thing, and a partial apply is harder for an operator to unpick than an untouched file.
+- **Rung 0 is checked first and is also all-or-nothing.** A file where some hunks are already
+  present and others are not is a hand-merge in progress, not an idempotent re-run — that is
+  rung 3.
+
+#### 2.2.2 Non-57.4 is allowed, unsupported, and must say so loudly
+
+The rung ladder replaces the blanket ServUO-version gate. The old rule skipped the entire tier on
+anything other than stock 57.4 on the grounds that unverified diffs must not be applied to an
+unknown tree — but forks are the norm (§1), so that rule skipped the tier for most of the audience.
+Content matching gives a stronger guarantee than a version string does: on a non-57.4 tree, rung 1
+is simply unavailable (its pre-image hash cannot be trusted), the tier goes straight to rung 2, and
+a hunk lands only where the surrounding lines are still character-for-character the ones the patch
+was written against.
+
+**That is a mechanical safety guarantee about where text lands. It is not a support commitment, and
+the installer must never let the two be confused.** Runic Gateway is designed, built and tested
+against **stock ServUO 57.4**. On anything else the patch tier is **unsupported, untested, and not
+guaranteed to work** — a hunk can match textually and still be wrong for a tree whose surrounding
+behaviour has diverged, and neither the shard's silent script build (§2.1) nor the installer will
+tell you that. So:
+
+- **The disclaimer is unmissable, not a footnote.** On a non-57.4 tree the tier prints a banner
+  before it is even offered — that 57.4 is the only supported version, that the operator is on their
+  own here, and that a bad outcome may not surface until the shard is running.
+- **It is off by default and takes an explicit, separate yes.** The interactive prompt defaults to
+  **no** on a non-57.4 tree, and `--patches` alone is **not** consent: an unattended run must pass
+  `--patches-unsupported-servuo` as well. A flag an operator had to look up cannot be hit by
+  accident in a script copied from somewhere else.
+- **The label follows the install.** `install.json` records the detected version and the fact that
+  the tier ran unsupported; `doctor` shows that row on every subsequent run, not just at install
+  time; and the uninstall report carries it too. An operator who inherits this shard six months
+  later must be able to see it without being told.
+- **It is the first thing quoted back in a bug report.** The tier's summary line names the detected
+  version, so a pasted install log answers "which ServUO?" before anyone asks.
+
+The version is detected and reported everywhere; it just no longer *silently* decides. A refusal
+becomes an informed choice, which is the point — but it stays visibly the operator's choice.
+
+**What the installer records.** `install.json` stores, per patch, which rung applied it
+(`stock-hash`, `region-match`, `already-present`) and the hunk offsets it matched. `doctor` and
+`uninstall` report that: a `region-match` apply on a modified file is a different support story from
+a clean apply to a stock tree, and the operator should be able to see which one they have without
+re-deriving it.
+
+### 2.3 Config paths collide with what the sidecar actually reads
+
+The sidecar reads `$UOLINK_CONFIG`, else `sidecar.toml` in the **working directory**
+(`link/sidecar/src/config.rs`), with keys `[shard].bind`, `[web].bind`, `[web].auth_token`,
+`[store].path`. The overview proposed a `config.toml` with `[updates]`, `[link]`, `[servuo]` — keys
+the sidecar cannot read.
+
+Two files, two owners:
+
+| File | Owner | Contents |
+|---|---|---|
+| `/etc/runicgateway/sidecar.toml` | uo-link | The sidecar's own schema, unchanged. Service sets `UOLINK_CONFIG` to this path |
+| `/etc/runicgateway/install.json` | installer | Deployed versions, file hashes, applied patches, ServUO path, timestamps |
+
+**Working-directory trap:** the sidecar wrote both `sidecar.toml` and `uo-link.db` relative to CWD.
+Under `C:\Program Files\` that fails or silently lands in VirtualStore. Phase 0.2 fixed the second
+half in the sidecar — a relative `[store].path` now resolves against the directory holding
+`sidecar.toml`, so pinning the config alone is enough to put the database somewhere deterministic —
+but the config path itself is still CWD-relative by default, and "deterministic" is not the same as
+"where this install wants it". The service definition therefore always pins the **config** path:
+
+- Linux: config `/etc/runicgateway/sidecar.toml`, db `/var/lib/runicgateway/uo-link.db`, dedicated
+  service user
+- Windows: binary under `%ProgramFiles%\RunicGateway\`, **data under `%ProgramData%\RunicGateway\`**
+
+**How each is pinned differs by platform, and Phase 2 settled it that way deliberately.** Linux's
+unit carries `Environment=UOLINK_CONFIG=` *and* `Environment=UOLINK_DB_PATH=`, because `/etc` and
+`/var/lib` are different directories and both need naming. Windows passes the config as `--config`
+inside the service's own `binPath`, and pins nothing else: config and data are both
+`%ProgramData%\RunicGateway`, so the sidecar's own anchoring rule already puts the database exactly
+where the table above says. The alternative on Windows is a **machine-wide** environment variable —
+`sc.exe` offers no per-service one — which every process on the host would inherit and which would
+outlive an uninstall. See [Phase 2 as built](#phase-2--uo-link-install-and-service).
+
+### 2.4 The token handoff was missing entirely
+
+The whole point is the website reaching the sidecar, and today that is manual and undocumented in
+the install flow: the sidecar generates a token on first run and logs it, then a human pastes base
+URL, WS URL, token, and protocol version into Admin → Shard, where it is AES-GCM encrypted and
+becomes write-only. This is the largest "I installed it and nothing happened" failure mode.
+
+The installer closes it by printing a copy-paste block at the end of a successful run — see §6.
+
+Phase 0.2 supplied the missing half of that: `uo-link-sidecar --print-config` provisions the config
+if absent and prints the resolved settings — token, both binds, `ws_path`, protocol version, db
+path — as JSON. The installer reads the block it prints out of that one call. **It never parses the
+log**, which was the alternative and would have made the handoff depend on a log format that is not
+a contract.
+
+### 2.5 `deploy.ps1` cannot be the cross-platform deployer
+
+It is PowerShell-only; a Linux ServUO host running .NET typically has no `pwsh`. It also hard-throws
+when the ServUO process is running — correct behavior, and the installer must inherit it (detect and
+refuse, rather than corrupt a live `Scripts.dll`). The installer reimplements the sync natively; it
+is a short hash-compare-and-copy that never deletes.
+
+`deploy.ps1` **stays** in `servuo-plugins` as the developer-facing tool. The installer is for
+operators.
+
+### 2.6 Prerequisites the overview assumed away
+
+- **`servuo-plugins` had no release workflow.** Only `link` did. "Pull latest repository" is replaced
+  by a release tarball, which had to be built first — Phase 0 item 1, now in review
+  ([servuo-plugins#7](https://gitea.whitlocktech.com/RunicGateway/servuo-plugins/pulls/7)).
+- **arm64 is not buildable today.** `link/release.yml` cross-compiles only
+  `x86_64-unknown-linux-gnu` and `x86_64-pc-windows-gnu`. An arm64 `.deb` needs another cross
+  toolchain.
+- **The compat matrix has no home.** `PROTOCOL_VERSION` lives in `link/sidecar/src/main.rs`. The
+  sidecar publishes it via `X-UOLink-Version` and `/health`, and the website stores an expected
+  value — but the *plugin's* protocol version is not queryable before boot. Phase 0 item 1 gives it
+  a home: `servuo-plugins/overlay.toml`, declared into the overlay manifest. See §7.0 / §7.1.
+
+---
+
+## 3. Distribution model
+
+Components are published as Gitea release artifacts. Operators download from the release page
+(browser, `curl`/`wget`, or `scp` to the server) and run the binary.
+
+```
+Runic Gateway Installer v1.0.0
+├── runicgateway-installer-windows-x86_64.exe
+├── runicgateway-installer-linux-x86_64
+└── SHA256SUMS
+
+uo-link v1.1.0                        (existing release, extended)
+├── uo-link-sidecar-windows-x86_64.exe
+├── uo-link-sidecar-linux-x86_64
+├── runicgateway-link_<ver>_amd64.deb        (Phase 5)
+└── SHA256SUMS
+
+servuo-plugins v<ver>                 (new release, Phase 0)
+├── runicgateway-overlay-<ver>.tar.gz         # overlay/ + patches/ + manifest.json
+└── SHA256SUMS
+```
+
+Binding those together is the **bundle manifest** (§7.1) — published by the installer repo's CI, not
+by any component, and the thing the installer actually resolves against.
+
+```bash
+scp runicgateway-installer-linux-x86_64 user@server:/tmp/
+chmod +x runicgateway-installer-linux-x86_64
+sudo ./runicgateway-installer-linux-x86_64
+```
+
+### Unsigned-binary posture
+
+Because releases are unsigned, trust is anchored on checksums and the operator's own verification.
+The docs must state this up front rather than let users discover it as a scary dialog:
+
+- Every release publishes `SHA256SUMS`; the install docs lead with the verification command for both
+  OSes.
+- Windows will show a SmartScreen "unrecognized app" prompt. Documented, with the exact click path.
+- The installer verifies the SHA256 of everything **it** downloads (overlay tarball, sidecar binary)
+  against the release's `SHA256SUMS` and refuses on mismatch. Self-verification is not optional just
+  because the installer itself is unsigned.
+- Revisit signing if it ever becomes affordable; the release layout should not have to change.
+
+---
+
+## 4. Component architecture
+
+```
+                 Runic Gateway Installer  (Rust, one binary per OS)
+                                │
+                ┌───────────────┴────────────────┐
+                ▼                                ▼
+      ServUO integration                      uo-link
+                │                                │
+       ┌────────┴────────┐              ┌────────┴────────┐
+       ▼                 ▼              ▼                 ▼
+  overlay sync    patch tier (opt-in)  binary install   service registration
+  (never deletes) (per-region rungs)   + config + data  (systemd / Windows SCM)
+```
+
+Each component keeps its own lifecycle. ServUO's existing startup process is untouched.
+
+---
+
+## 5. Phases
+
+### Phase 0 — prerequisites (no installer code)
+
+Repo work that must land before an installer can exist.
+
+1. **`servuo-plugins`: add `.gitea/workflows/release.yml`.** Retarget the release *engine* half of
+   `link/release.yml` (its header comment explicitly anticipates this — the plan/release steps
+   consume only `{version, changelog, artifacts}`). The adapter half produces
+   `runicgateway-overlay-<ver>.tar.gz` containing `overlay/`, `patches/`, and a `manifest.json`
+   (version, commit, per-file SHA256, declared protocol version, minimum ServUO version).
+
+   As built ([servuo-plugins#7](https://gitea.whitlocktech.com/RunicGateway/servuo-plugins/pulls/7)),
+   with three deviations from `link`'s copy that each fell out of the repo rather than being chosen:
+
+   - **No build gates, structural gates instead.** Nothing in that repo can be compiled without
+     ServUO reference assemblies, so CI asserts what it honestly can: `Bridge.cfg` and the Bridge
+     scripts present, `Scripts.csproj` present (its absence ships code that never compiles while
+     ServUO reports success — §2.1), every `.patch` parseable via `git apply --stat`, and each
+     patch's companion `.cs` present.
+   - **No bump commit, so no push to `main`.** `link` writes the version into `Cargo.toml` because
+     the binary embeds it; the tarball embeds nothing but the generated manifest, so the tag *is*
+     the version. That workflow needs no branch-protection exception.
+   - **`overlay.toml` at the repo root** holds the declared `protocol` and the ServUO compatibility
+     values, read by CI into the manifest. It exists because the number needs one maintained home —
+     see §7 for why the plugin cannot simply be asked.
+
+   The tarball uses a **fixed** top-level directory, `runicgateway-overlay/`, not a versioned one:
+   the installer looks for `overlay/`, `patches/` and `manifest.json` at known paths rather than
+   parsing the version it is trying to read. Member order, mtime and ownership are pinned, so a
+   given tree yields a byte-identical tarball and its checksum moves only when its contents do.
+2. **`link`: make the sidecar installable.** Confirm/settle default data paths, and add a way to
+   read back config non-interactively (e.g. `--print-config` emitting JSON: bind addresses, token,
+   protocol version, db path) so the installer does not have to scrape logs for the token.
+
+   As built ([link#24](https://gitea.whitlocktech.com/RunicGateway/link/pulls/24)) — the sidecar
+   had **no CLI at all** before this, so the shape was chosen rather than inherited:
+
+   - **Four flags, hand-rolled:** `--print-config`, `--config <PATH>`, `--version`, `--help`. No
+     argument-parsing crate — it would be larger than the code it replaced — and deliberately no
+     flags that duplicate a config key, so `sidecar.toml` stays the single place settings live.
+     An unrecognized argument exits `2`; silently ignoring a typo'd flag would start a sidecar that
+     is not the one the installer asked for.
+   - **`--print-config` performs first-run setup rather than only reporting.** It runs the same
+     load path a normal start does, so a missing config file is written and a blank token is
+     generated and saved. That collapses "provision the sidecar" and "find out its token" into one
+     non-interactive call — which is exactly the sequence §6 needs. `config_created` and
+     `token_generated` say whether *this* run did either, because the values alone cannot
+     distinguish a fresh install from a re-read of an existing one, and a re-run must not report a
+     token as newly minted.
+   - **The document is the whole of stdout.** The log subscriber writes to stdout, so it is not
+     started in this mode. `ws_path` is emitted from the same constant the route is registered
+     with, so the installer's WebSocket URL cannot drift from the server's.
+   - **Relative `[store].path` now anchors to the config file's directory, not the CWD** — see
+     §2.3, which this half-closes on the sidecar side. Absolute paths are used as written; parent
+     directories are created; `:memory:` and `file:` URIs are left alone.
+   - **The db path is handed to sqlx as a path, not a `sqlite://` URL.** The URL spelling is
+     parsed as one: it percent-decodes the path and splits it on `?`, so an installed path
+     containing `%20` opened a different file than the operator named.
+   - **No platform data directories are compiled in.** That is the "settle" half of this item, and
+     the answer is that the *installer* owns layout (§2.3) and pins `UOLINK_CONFIG` /
+     `UOLINK_DB_PATH` in the service definition. Baking `/etc` and `%ProgramData%` defaults into
+     the binary would give the same paths two owners and break `cargo run` in a working tree.
+3. **Bundle CI in the installer repo** (§7). Compose job (read both repos' latest releases → run the
+   two gates → publish `bundle.json`), the nightly cron, and the dispatch step appended to each
+   component's release workflow. This must exist before Phase 1 is useful, since the installer
+   resolves what to install *from* the bundle.
+
+   As built ([installer#3](https://gitea.whitlocktech.com/RunicGateway/installer/pulls/3),
+   [link#25](https://gitea.whitlocktech.com/RunicGateway/link/pulls/25),
+   [servuo-plugins#9](https://gitea.whitlocktech.com/RunicGateway/servuo-plugins/pulls/9)) —
+   `installer/.gitea/workflows/bundle.yml`, with the decisions §7 had left open:
+
+   - **Bundles are committed to the installer repo, not published as releases** — see §7.1 for
+     where and why. That was the one genuinely open question here, and the deciding factor is that
+     this repo's *own* releases are the installer binaries.
+   - **Gate 1 reads the sidecar's protocol from source at the release tag**, not from the binary.
+     `--print-config` (Phase 0.2) would answer authoritatively, but only for releases from `v1.1.0`
+     onward, and `--bundle <tag>` has to be able to recompose a bundle from an older pair. Reading
+     `sidecar/src/main.rs` at the tag the release was built from works uniformly, needs no execution
+     of a downloaded artifact, and does not provision a throwaway config whose auth token would then
+     be sitting in a CI log. A constant that has moved or been renamed is a hard failure — treating
+     "could not read" as "matches" is exactly how a mismatched pair would ship.
+   - **Gate 2 records the hash CI computed itself**, after verifying the download against the
+     publishing repo's `SHA256SUMS`. It also asserts the reverse direction — an asset with *no*
+     `SHA256SUMS` entry — because `sha256sum -c` silently passes over a file the sums file does not
+     mention, which would put an unverified artifact in the bundle.
+   - **Release metadata is read anonymously**, on purpose: those are exactly the requests the
+     shipped installer makes on a host with no Gitea credentials, so a repo flipped to private
+     fails CI here instead of on an operator's machine.
+   - **An unrecognized asset name is a hard failure.** link's binaries are mapped onto platform keys
+     by suffix; adding a target (aarch64, macOS) to its release workflow therefore reddens this job
+     rather than silently omitting the new binary from every bundle.
+   - **A run that changes nothing writes nothing** — the comparison excludes `bundle` and
+     `generated`, which are metadata about the run. Without that the nightly cron would commit a
+     dated duplicate of the same matrix every morning.
+
+   The workflow's compose steps were run against the live releases before merge, producing the
+   first bundle (`2026.08.04`: link `v1.1.0` + overlay `v0.1.1`, protocol 3), which is committed so
+   the manifest exists ahead of the binary that reads it.
+4. **`docs`: this file, plus `docs/installer/INSTALL.md`** (the operator-facing guide) once the
+   shape is settled.
+
+   As built ([`INSTALL.md`](INSTALL.md)) — written *before* the binary on purpose. Everything it
+   installs is already released (items 1–3), so the guide is not speculation about a tool that
+   might exist; it is the specification of what the run asks, where it writes, what it prints, and
+   what the operator does next. Phase 1–4 implement it.
+
+   - **It is useful before the installer exists.** Appendix A is the same deployment done by hand —
+     bundle fetch, tarball verify + overlay copy, the optional patch tier, `--print-config`
+     provisioning, and a systemd unit / `sc create` service — composed from the released artifacts'
+     actual contents and the sidecar's config and CLI source rather than from memory. That appendix
+     doubles as **Phase 1's acceptance test**: walking it end to end on a real shard is what proves
+     the automated path has nothing left to discover.
+   - **The installer does not install itself.** §5's `runicgateway doctor` sketch implied a name on
+     `PATH`; nothing places one there, and adding self-installation would give the tool a second
+     lifecycle to manage. The guide names the downloaded artifact, says to keep it, and shortens it
+     in later examples.
+   - **The flag surface got fixed here**, because a guide cannot describe a run in the abstract:
+     `--verify`, `--bundle`, `--purge` were already named by §5/§7; `--servuo`, `--patches` /
+     `--no-patches`, `--host`, `--site-url` and `--yes` are the remainder, chosen so every prompt
+     in §6's handoff has a non-interactive equivalent and an unattended install is expressible.
+   - **A modified `Bridge.cfg` must survive an update** — see Phase 1, where this changes the sync
+     rule inherited from `deploy.ps1`.
+   - **Remote-website deployments needed an answer.** `[web] bind` defaults to `127.0.0.1`, which
+     only works when the site runs on the shard host. The guide says to widen it, firewall it to
+     the website's address, and front it with TLS or a VPN off a trusted network — because the
+     token is always required but travels as a plain bearer token over HTTP. `[shard] bind` stays
+     on loopback, since that socket carries inbound commands *into* the game.
+
+### Phase 1 — installer core
+
+- ServUO root detection and validation (`ServUO.exe`, `Scripts/`, `Config/`), with version detection
+  and an explicit refusal when the ServUO process is running.
+- Overlay sync: fetch tarball → verify SHA256 → hash-compare against the server tree → add/change,
+  **never delete**. Port of `deploy.ps1` semantics including its `-Verify` dry run (`--verify`).
+- **One deviation from `deploy.ps1`: an operator-modified `Config/Bridge.cfg` is reported, not
+  overwritten.** `deploy.ps1` overwrites every file whose hash differs, which is right for a
+  developer redeploying their own tree and wrong for an operator who has set `LinkUrl`,
+  `PublicConnectAddress` and sweep intervals — an `update` would silently revert the shard's entire
+  configuration. `install.json` records the hash deployed, so the installer can distinguish "the
+  operator edited this" from "the overlay moved on" (§7.0) and act only on the second. The rule is
+  specific to `Bridge.cfg`: it is the only file in the overlay that is *meant* to be edited in
+  place, and it carries no code, so a stale copy cannot break the build. Every `.cs` file and
+  `Scripts.csproj` still overwrite unconditionally.
+- Write `install.json`: component, version, source commit, per-file hashes, applied patches,
+  timestamp.
+- Idempotent re-runs; a second run with no upstream change reports "unchanged" and writes nothing.
+
+**As built** ([installer#4](https://gitea.whitlocktech.com/RunicGateway/installer/pulls/4)) — the
+crate at the repo root, `install` implemented end to end, `doctor`/`update`/`uninstall` parsed and
+answered with the phase they arrive in rather than "unrecognized command". The decisions that were
+not already settled above:
+
+- **It lands on `edge`, not `main`.** `release.yml` publishes an installer binary on every push to
+  `main`, and its crate guard was written to arm "the moment Phase 1 lands the crate" — which would
+  have published a binary that deploys the overlay but cannot install the sidecar, contradicting
+  everything `INSTALL.md` promises a release does. Phases 1 and 2 land on `edge`; the `edge → main`
+  cutover cuts the first release. `pr-checks.yml` gates PRs into `edge` on the same rules, so the
+  branch where the work happens is not the ungated one. No workflow needed a temporary edit.
+- **The run says what it did *not* do.** A Phase 1 `install` ends with an unmissable block naming
+  the sidecar as not installed, pointing at `INSTALL.md` A3/A4, and printing the bundle's binary URL
+  and SHA256 so a hand install matches the pair. `--patches` is the sharp edge here: it is accepted
+  (so the flag surface is the published one) but reports `REQUESTED BUT NOT APPLIED — no stock
+  ServUO file has been touched`. A `--patches` run that completed quietly would be read as a
+  patched shard.
+- **The crate is a library plus a thin binary, and the library is not named after it.** Windows
+  applies UAC *installer detection* to unsigned executables whose file name contains `install`: it
+  demands elevation before the process starts, and a non-interactive session gets `os error 740`
+  instead of a program. That is survivable for the shipped binary — it needs Administrator anyway,
+  and `INSTALL.md` already says to run it from an elevated shell — but Cargo names test harnesses
+  after their target, so a target called `runicgateway_installer` makes `cargo test` **unrunnable on
+  Windows**, on the machine the shard smoke tests live on. The code therefore sits in a library
+  called `rgdeploy`, the binary target keeps its published name, and `[[bin]] test = false` stops
+  Cargo building a harness under it. Nothing an operator sees changes.
+- **Dependencies chosen for the MinGW cross-build:** `ureq` (blocking HTTP over rustls/ring — no
+  OpenSSL to cross-compile, and no async runtime for a tool that makes four sequential requests),
+  `flate2` on its pure-Rust backend, `tar`, `sha2`, `serde`/`serde_json`, `chrono`, `anyhow`, and
+  `sysinfo` for the running-shard check.
+- **The shard-running check matches by path, not by process name.** `deploy.ps1` can look for a
+  process called `ServUO` because it only runs on Windows; on Linux the same shard is `mono` or
+  `dotnet` with `ServUO.exe` as an argument, and a name match would answer "not running" for a live
+  shard — the one wrong answer that corrupts `Scripts.dll`. The installer requires a process whose
+  executable or command line names *both* the tree being deployed into and `ServUO.exe`, so a second
+  shard elsewhere on the host does not block this deploy, and the installer never matches itself.
+- **ServUO's version is read from `Server/AssemblyInfo.cs`**, not from `ServUO.exe`'s PE metadata:
+  it is the same *source* tree the patch tier diffs against, needs no dependency, and works
+  identically on Linux. `57.4.0.0` and `57.4` are normalized to compare equal. An unreadable version
+  is reported as `unknown` and treated as **not** supported — an unreadable version is not evidence
+  of a good one — which is what Phase 3 will gate the tier on.
+- **`install.json` records a state, not a verb.** Per-file entries are `deployed` or
+  `kept-operator-modified`, never `add`/`change`/`unchanged`. Recording the run's verb made the
+  record differ between a first run and an identical second one, which rewrote the file on every
+  run and broke "a second run writes nothing" in the least visible way available. What later
+  commands need is whose copy is in the tree, and that does not change because time passed.
+- **The `Bridge.cfg` decision compares against the last hash the installer *deployed*, not the last
+  hash it *saw*.** Once a file has been kept, the record's on-disk hash is the operator's content —
+  so a rule phrased as "is the tree still what the record last saw?" matches on the very next run
+  and overwrites exactly the file it had just protected. A keep has to stay kept for as long as the
+  edit is there; a live three-run test covers it, because the bug only appears from the second run
+  on.
+- **A prior record is only consulted when it names this tree.** A host whose `install.json` points
+  at a different ServUO root — a shard moved or rebuilt beside the old one — is treated as having no
+  prior deployment, which errs toward keeping the operator's file.
+- **The download is verified twice, for two different reasons.** The tarball's SHA256 is checked
+  against the bundle while it is being written (the trust anchor — these artifacts are unsigned);
+  then every extracted file is re-hashed against the release's own `manifest.json`, which catches a
+  truncated extraction and is what makes the hashes copied into `install.json` worth trusting. The
+  manifest's `protocol` and `version` are also cross-checked against the bundle, so an artifact that
+  disagrees with the matrix that named it stops the run before anything is written.
+- **`RUNICGATEWAY_STATE_DIR` relocates the installer's own state**, so a run can be tested without
+  root. Documented in `--help` rather than hidden: an undocumented variable that moves where a tool
+  writes is worse than a documented one, and `doctor` must honour the same value to find what
+  `install` wrote.
+
+Verified on this machine against a real ServUO 57.4 tree (`--verify`, which reported the tree's
+`Bridge.cfg` as operator-owned and 23 code files as changed) and end to end into a scratch tree:
+24 files deployed, a second run reporting `unchanged` and leaving `install.json` untouched, an
+edited `Bridge.cfg` kept across three further runs while a hand-edited `.cs` was overwritten each
+time, a pinned `--bundle`, a missing bundle tag, and a refusal — pid and path named, exit 1 — with a
+process running out of the tree.
+
+### Phase 2 — uo-link install and service
+
+- Linux: binary → `/usr/bin/runicgateway-link`, config → `/etc/runicgateway/sidecar.toml`, db →
+  `/var/lib/runicgateway/`, systemd unit with a dedicated user, `enable` + `start`.
+- Windows: `%ProgramFiles%\RunicGateway\`, data in `%ProgramData%\RunicGateway\`, service
+  registration with automatic start and restart-on-failure.
+- Both: `UOLINK_CONFIG` and `UOLINK_DB_PATH` pinned in the service definition (§2.3).
+- Token surfacing (§6): run the installed binary once as
+  `uo-link-sidecar --print-config --config <the pinned path>` **before** registering the service.
+  That both writes the config the service will read and returns the token to print, so the service
+  never starts against a config that does not exist yet.
+
+**As built** ([installer#5](https://gitea.whitlocktech.com/RunicGateway/installer/pulls/5)) —
+`src/sidecar.rs` (binary, config, handoff) and `src/service.rs` (systemd, Windows SCM), wired into
+the same `install` run. The decisions that were not already settled above:
+
+- **Both platforms run the sidecar as a dedicated unprivileged identity.** Linux gets the system
+  user this section already specified; Windows gets a **virtual service account**
+  (`sc create … obj= "NT SERVICE\RunicGatewayLink"`), which the SCM creates itself and which has no
+  password. Plain `sc create` would have run it as `LocalSystem` — the most privileged local
+  identity there is, for a process that listens on two TCP ports while its Linux twin deliberately
+  does not run as root. The account only exists *after* `sc create`, which fixes the order of the
+  file permissions below.
+- **`sidecar.toml` is locked down, because it holds the token.** Neither default location protects
+  it: `/etc` is world-readable and `%ProgramData%` grants `Users` read by inheritance, so an
+  unprivileged local account could read the shard's auth token out of a stock install. Linux gets
+  `chmod 600` plus `chown` to the service user; Windows gets `icacls /inheritance:r` down to SYSTEM
+  and Administrators **before** registration, then a read grant for the service account after it
+  exists. The database directory gets a separate write grant, since SQLite writes journal and WAL
+  files beside the database.
+- **`--verify` runs no part of the sidecar half.** `--print-config` provisions — it writes the
+  config and mints a token — so a dry run that called it would create exactly the state it claims
+  not to. A `--verify` run reports what would be installed, reads no token, and prints no handoff.
+  It also **carries the existing `link` section of `install.json` through untouched**, so a dry run
+  on an installed host cannot make its service disappear from the record.
+- **The installed binary's protocol version is checked against the bundle, and a mismatch stops the
+  run before the service is registered.** Gate 1 (§7.1) read that number from source at the release
+  tag; this is the same check applied to the binary that will actually answer the website. The
+  binary is left on disk — harmless without a service — rather than the run pretending to succeed.
+- **`RUNICGATEWAY_STATE_DIR` now relocates the sidecar binary too, and suppresses service
+  registration.** Phase 1 left the binary path alone because nothing wrote it. A relocated run that
+  still dropped a binary into `/usr/bin` and registered a system service would be exactly the
+  half-in-the-real-system accident the variable exists to avoid — and there is no such thing as a
+  relocated systemd unit or Windows service. Such a run also leaves file permissions alone, because
+  hardening a scratch config against the only account that will ever read it just breaks the next
+  test run.
+- **A host the installer cannot drive gets the recipe, not a failure or a weaker service.** No
+  systemd (`/run/systemd/system` absent — the correct test, since `systemctl` is present in plenty
+  of containers where PID 1 is not systemd), or a service user that cannot be created: the binary
+  and config are still installed, `install.json` records `service: null`, and the run prints the
+  exact unit text and commands. There is **no fallback to `User=root` or `LocalSystem`** — a service
+  quietly running with more privilege than its own documentation promises is worse than one that was
+  not registered. The printed Windows recipe states plainly whether the run locked the config down
+  or the operator still has to.
+- **`install.json` never records the token.** The `link` section holds versions, the binary's hash,
+  the config and database paths, and the service's name, unit path and account. The token goes to
+  the terminal and to `sidecar.toml`, and the record is a support artifact people paste into bug
+  reports.
+- **The service is stopped before its binary is replaced, and restarted rather than started
+  afterwards.** On Windows the file is locked while the service runs (and `sc stop` returns as soon
+  as the stop is *pending*, so the stop is polled, not slept on); on Linux the replacement is
+  permitted but leaves the old code serving until something restarts it. `systemctl start` on an
+  active unit is a no-op, which is precisely the wrong outcome after a replacement.
+
+Verified on this machine end to end against a relocated layout: the bundle's Windows sidecar
+downloaded and checksum-verified, `--print-config` provisioning a fresh config and returning a
+token, the §6 handoff printed with the URLs composed from the host rather than the bind address, a
+second run reporting `unchanged` / `already present` and leaving `install.json` byte-identical, a
+`--verify` run over an installed host writing nothing and preserving the `link` section, and a
+tampered binary detected by hash and replaced with no stray staging file left behind.
+
+### Phase 3 — patch tier (opt-in)
+
+Everything in §2.2. Detect applicability, dry-run, apply, record, warn about the core rebuild, and
+degrade loudly rather than silently.
+
+The rung ladder of §2.2.1 is the bulk of the work here: parse each `.patch` into hunks, reconstruct
+each hunk's pre- and post-image blocks, and resolve the file through rungs 0–3 before writing
+anything. The unsupported-version path (§2.2.2) is part of this phase, not a later polish — the
+banner, the defaulted-to-no prompt, the `--patches-unsupported-servuo` flag, and the unsupported
+marker carried into `install.json`, `doctor` and the uninstall report. Two pieces carry the risk and want direct tests — the hunk parser (headers, `\ No newline
+at end of file`, CRLF files) and the uniqueness rule (a region that appears twice must fail, not
+pick the first). Fixtures are cheap: the three stock 57.4 files, each with a hand edit far from the
+patched region (must reach rung 2), an edit inside it (must reach rung 3), and an already-patched
+copy (must reach rung 0).
+
+### Phase 4 — diagnostics and updates
+
+`runicgateway doctor` — the command that makes the whole thing supportable:
+
+```
+✓ ServUO found            /opt/ServUO  (57.4)
+✓ Overlay in sync         24 files, all hashes match install.json
+⚠ Patch tier              1 of 3 applied (region-match) — vendor.sale unavailable
+✓ uo-link installed       1.1.0
+✓ Service                 running, enabled
+✓ Sidecar reachable       127.0.0.1:8080  /health ok
+✓ Protocol                sidecar 3 = overlay manifest 3
+✗ Shard connected         no shard has dialed in since boot
+```
+
+The last check matters most: it is the only thing that distinguishes "files copied" from "the bridge
+actually works" (§2.1).
+
+Three of those rows are answered by the sidecar's own CLI rather than by inspecting the filesystem:
+`--version` prints `uo-link-sidecar <ver> (protocol <n>)`, and `--print-config` gives the config and
+db paths the *installed service* resolves — so `doctor` reports what the binary would actually do,
+not what `install.json` believes it was told to do. The protocol row compares that number against
+the overlay manifest's declared one (§7.0).
+
+`runicgateway update` — resolves the current bundle (§7.1), then acts asymmetrically by component,
+deliberately:
+
+- **uo-link**: compare the bundle's version against what is installed → download → verify checksum →
+  replace binary → restart service.
+- **plugin overlay**: download the bundle's overlay tarball → verify → re-sync (leaving a modified
+  `Bridge.cfg` alone — Phase 1) → record commit → tell the operator ServUO must restart (the
+  installer does not restart the shard).
+
+Because both come from one bundle, an update always moves to a combination whose protocol versions
+were checked together, rather than to two independently-latest artifacts that may disagree.
+
+`runicgateway uninstall` — **removes only what it exclusively owns, and never edits the ServUO
+tree.** The installer cannot know what the operator has changed in those files since deployment, so
+a clever automatic revert risks silently eating their work. It removes and it reports:
+
+| Action | Scope |
+|---|---|
+| Removed | uo-link binary, its service entry (systemd unit / Windows service), `install.json` and the cached patch set |
+| Kept | `sidecar.toml` and `uo-link.db` (config and history survive; `--purge` to drop them) |
+| **Printed, not done** | Every overlay file deployed into the ServUO tree, listed by path, for the operator to delete |
+| **Printed, not done** | The exact hunks each applied patch added to `EventSink.cs`, `PlayerVendorGumps.cs`, `Logging.cs`, rendered from the cached `.patch` files — with the rung that applied each one (§2.2.1), since a `region-match` apply means the surrounding file was already the operator's — for them to revert by hand |
+
+The printed report is also written to a file, so it survives the terminal scrollback of a long
+uninstall.
+
+### Phase 5 — packaging polish
+
+`.deb` packaging, Windows MSI, arm64 cross build, and optional automated backup before upgrade.
+Deliberately last: v1 can register services directly (`sc create` / a written systemd unit) and ship
+plain binaries. Nothing in Phases 1–4 should have to change to add these.
+
+---
+
+## 6. Token handoff (the end of a successful run)
+
+```
+Runic Gateway is installed.
+
+One manual step remains — connect the website to this sidecar:
+
+  Base URL          http://<this-host>:8080
+  WebSocket URL     ws://<this-host>:8080/ws
+  Protocol version  3
+  Auth token        4f9c...   (also in /etc/runicgateway/sidecar.toml)
+
+Paste these into  Admin → Shard  on your Runic Gateway site:
+  https://<your-site>/admin/shard
+
+The token is write-only once saved — the site will never show it back to you.
+```
+
+Every value in that block except the host and the site URL comes from one
+`uo-link-sidecar --print-config` call (§2.4): `web.auth_token`, `protocol`, and `web.bind` +
+`web.ws_path` for the two URLs. Only the **host** is substituted — `web.bind` is frequently
+`0.0.0.0`, which is not something to hand a website — so the installer composes the URLs from the
+host it detects or prompts for, rather than echoing the bind address.
+
+The installer prompts for the site URL only to build that link; it never contacts the website. A
+future "installer registers itself with the website" flow (claim code + authenticated endpoint) is
+explicitly **out of scope** — it is real backend work in a security-sensitive area and can be added
+later without changing anything here.
+
+The printed token is a secret in transit: `--print-config` output must go to the operator's
+terminal and the config file, never into an installer log file or a support bundle.
+
+---
+
+## 7. Version tracking, the bundle, and release orchestration
+
+Three components version independently, bound by a protocol contract:
+
+- **sidecar** — `PROTOCOL_VERSION` in `link/sidecar/src/main.rs`, exposed on `/health` and as
+  `X-UOLink-Version` on every response; a mismatch is rejected `409`.
+- **website** — stores an expected protocol version in `uoLinkConfig` (admin-managed).
+- **plugin overlay** — has no queryable version before ServUO boots. The overlay release
+  `manifest.json` declares it, and `install.json` records what was deployed.
+
+### 7.0 The overlay manifest
+
+Shipped inside every `runicgateway-overlay-<ver>.tar.gz`, generated by that repo's release workflow:
+
+```json
+{
+  "component": "servuo-plugins-overlay",
+  "version":   "0.1.0",
+  "commit":    "968b526…",
+  "repo":      "RunicGateway/servuo-plugins",
+  "protocol":  3,
+  "servuo": { "min_version": "57.4", "patches_verified_against": "57.4" },
+  "files":  { "overlay/Config/Bridge.cfg": "32718424…", "patches/…": "…" }
+}
+```
+
+`version` and `commit` come from the release engine; `protocol` and the `servuo` block are read from
+`servuo-plugins/overlay.toml`; `files` is a SHA256 per shipped file.
+
+Two of these carry weight beyond documentation:
+
+- **`protocol` is a hand-maintained declaration, and has to be.** The plugin announces no version on
+  the wire and none is queryable before ServUO boots, so nothing in CI can derive it — which makes
+  this line the only thing §7.1's gate 1 has to compare the sidecar against. The duty is stated in
+  `overlay.toml` and in that repo's README: **bump it in the same PR that changes the emitters**, the
+  way `link` bumps `PROTOCOL_VERSION`.
+- **`files` is what makes `doctor` able to tell "the operator edited a deployed file" from "the
+  overlay moved on"** (§5, Phase 4). The installer copies these hashes into `install.json` at deploy
+  time; a later mismatch against *both* the manifest and `install.json` means upstream changed, a
+  mismatch against `install.json` alone means local edits.
+
+`min_version` and `patches_verified_against` are separate on purpose. The base overlay only *adds*
+files and is expected to work broadly; the patch tier diffs stock ServUO files and is verified
+against exactly one version (§2.2).
+
+### 7.1 The bundle manifest
+
+**The bundle is the compat matrix.** Rather than the installer hardcoding versions or blindly
+resolving "latest", CI publishes a small manifest naming an exact, checked combination:
+
+```json
+{
+  "schema": 1,
+  "bundle": "2026.08.04",
+  "generated": "2026-08-04T16:07:13Z",
+  "protocol": 3,
+  "link": {
+    "repo": "RunicGateway/link", "tag": "v1.1.0", "version": "1.1.0", "protocol": 3,
+    "assets": {
+      "linux-x86_64":   { "name": "uo-link-sidecar-linux-x86_64",       "url": "…", "sha256": "27d491ef…" },
+      "windows-x86_64": { "name": "uo-link-sidecar-windows-x86_64.exe", "url": "…", "sha256": "fbefd886…" }
+    }
+  },
+  "overlay": {
+    "repo": "RunicGateway/servuo-plugins", "tag": "v0.1.1", "version": "0.1.1",
+    "commit": "3a52abb…", "protocol": 3,
+    "servuo": { "min_version": "57.4", "patches_verified_against": "57.4" },
+    "asset": { "name": "runicgateway-overlay-0.1.1.tar.gz", "url": "…", "sha256": "75dc6d6c…" }
+  }
+}
+```
+
+Note `link.assets` is a **map keyed by platform**, not the single `sha256` this section originally
+sketched: link publishes a Linux binary and a Windows `.exe`, and the installer runs on both, so one
+hash could only ever have described one of them. `schema` versions this document's shape and is
+independent of `protocol` and of either component's release version — all three move separately.
+
+The installer fetches the current bundle at run time; `--bundle <tag>` pins an older one for a
+reproducible install. Because the bundle is data, **a new `link` release regenerates ~30 lines of
+JSON and leaves the installer binary untouched** — operators do not re-download the installer to
+pick up a sidecar patch, and the installer does not accumulate releases whose code is byte-identical.
+
+Two gates run at compose time, both cheap and both worth it:
+
+1. The sidecar's `PROTOCOL_VERSION` must equal the overlay manifest's declared protocol version.
+   This is the check that catches an `edge`/`main` protocol mismatch before it reaches an operator.
+   The two halves are read from different places because they *are* different: the overlay's from
+   `manifest.json` inside the tarball (the only statement of it that exists — §7.0), the sidecar's
+   from `sidecar/src/main.rs` at the release tag (see Phase 0 item 3 for why not from the binary).
+2. Every referenced asset must exist and its SHA256 must match the publishing repo's `SHA256SUMS`.
+   The hash recorded in the bundle is the one CI computed from the asset it downloaded, *after* that
+   check — and the installer verifies every download against it. These artifacts are deliberately
+   unsigned (§3), so the checksum is the whole trust anchor; a hash copied from a file nobody
+   verified would make the chain decorative.
+
+#### Where bundles are published
+
+Committed to the installer repo under `bundles/`, so the installer's fetch is a plain anonymous
+`GET` against a public repo — the shard host has no Gitea credentials (§1):
+
+```
+bundles/current.json          → …/RunicGateway/installer/raw/branch/main/bundles/current.json
+bundles/bundle-<tag>.json     → …/raw/branch/main/bundles/bundle-2026.08.04.json   (--bundle)
+```
+
+Every bundle is kept forever, so `--bundle` stays reproducible. Tags are UTC dates; a second bundle
+on the same day — a sidecar release in the morning and an overlay release in the afternoon is the
+normal way that happens — becomes `2026.08.04.2`, so one tag always names exactly one matrix.
+
+**Not one Gitea release per bundle**, which was the obvious alternative. This repo's own releases
+are the installer *binaries*, and `/releases/latest` returns whichever release is newest regardless
+of kind — interleaving bundle releases would make "latest" intermittently resolve to a release
+carrying no installer binary. Committing also yields a reviewable diff and a git history of the
+compat matrix, and needs no new branch-protection exception: `release.yml`'s version-bump commit
+already requires the CI user to be able to push to `main`.
+
+### 7.2 What triggers a bundle
+
+| Trigger | Why |
+|---|---|
+| `link` publishes a release | Its release job `POST`s to the installer repo's workflow-dispatch endpoint as its final step |
+| `servuo-plugins` publishes a release | Same. Phase 0 item 1 gave it the release workflow; the dispatch step was left as a marked TODO until there was something to dispatch, and landed with the bundle CI it calls (item 3) — a step that `404`s on every release is worse than no step |
+| Nightly cron on the installer repo | Recomputes from whatever the latest releases actually are, so a missed or failed dispatch self-heals instead of silently pinning operators to a stale sidecar |
+
+`repository_dispatch` is deliberately avoided — support for it is uncertain on this Gitea version,
+whereas dispatching an existing `workflow_dispatch` workflow via the API works today.
+
+**A failed dispatch is a warning, never a failed release.** By the time that step runs the component
+release is published and correct; failing the job would misreport it. This also keeps the dispatch
+from becoming a new hard credential requirement — `REGISTRY_TOKEN` having write on the installer
+repo is a nicety, and without it the nightly cron picks the release up anyway. A dropped dispatch
+costs latency, not correctness, which is the whole reason the cron exists.
+
+### 7.3 Stale-overlay handling: dispatch, don't wait
+
+Each component **self-releases on merge to its own `main`**, using the same conventional-commit
+engine. Note that "updated since the last release" must mean *releasable* commits — the engine sets
+`RELEASE=false` when nothing but `docs:`/`chore:` has landed, so a docs typo correctly does **not**
+cut an overlay release, and the bundle keeps using the existing one.
+
+The compose job's copy of that rule additionally **excludes merge commits**, whose subject is
+`Merge pull request '<the real subject>'`. Without that, every squash-free merge of a `feat:` branch
+would be counted twice, and worse, a merge of a `docs:` branch whose *title* happens to quote a
+`fix:` would be read as releasable — re-dispatching, every night, a release workflow that correctly
+declines to run.
+
+So by the time the installer's CI looks, the release normally already exists. If it finds
+`servuo-plugins` main ahead of its latest release *with* releasable commits, it:
+
+1. fires that repo's release workflow via workflow-dispatch and **does not wait for it**,
+2. composes this bundle from the assets that exist right now,
+3. writes a loud warning into the job summary.
+
+The new overlay release lands minutes later on its own and the nightly cron folds it into the next
+bundle. This gets the automation without the flaky part: dispatching another repo's workflow is
+fine — that workflow still runs its own gates — but *polling* it is not, because Gitea's dispatch
+endpoint returns no run handle, so the job would have to guess which run is its own and hold a
+runner idle meanwhile. The warning exists so a genuinely broken release workflow surfaces once
+rather than being silently retriggered every night forever.
+
+### 7.4 Open risk
+
+**Settled as of the v3 cutover.** Protocol work landed on `edge` branches and the `edge → main`
+cutover has now merged, so `main` speaks protocol 3 consistently across the repos. The rule it
+motivated stands regardless and is not a temporary measure: **the installer hardcodes no protocol
+version anywhere.** It reads what the artifacts declare, and §7.1's gate 1 is what stops a
+mismatched pair from being published as a bundle — which is the mechanism that will matter at the
+*next* protocol bump, not just this one. See `docs/link/v3.md`.
+
+---
+
+## 8. Open questions
+
+1. **Does the installer manage ServUO stop/start?** Currently it refuses while ServUO runs and tells
+   the operator to restart afterward. Offering to stop/start would be friendlier but means owning
+   another shard's process lifecycle, and the shard's own start scripts vary.
+2. **Co-location assumption** — the shard dials out to the sidecar on loopback `127.0.0.1:7788`, so
+   sidecar and ServUO must share a host. Should the installer support installing only uo-link on a
+   different host, or hard-assume co-location?
+Resolved and moved into §1 / §2.2 / §5: uninstall scope, and minimum ServUO version.
+
+**Resolved — Windows service mechanism** (was question 1). `sc create` against the plain console
+binary, as recommended: it works on a stock host, ships nothing extra, and needs no change to
+`link`. A WinSW/NSSM shim would be a third binary to keep current, and a native `--service` mode
+using the `windows-service` crate would put Windows service plumbing inside a component whose whole
+job is being platform-agnostic. Restart semantics turned out to be adequate —
+`sc failure … actions= restart/5000` is the direct counterpart of systemd's `Restart=on-failure` /
+`RestartSec=5`. What the recommendation did *not* anticipate is the service identity: plain
+`sc create` runs as `LocalSystem`, so Phase 2 registers with `obj= "NT SERVICE\RunicGatewayLink"`
+instead (see [Phase 2 as built](#phase-2--uo-link-install-and-service)).
+
+**Resolved — branch targeting for the new repo** (was question 4). The v3 cutover landed:
+`servuo-plugins#6` merged, so that repo's `main` and `edge` agree at protocol 3. The release
+workflow targets `main`, and the installer repo starts clean on `main`. §7.4's caution still applies
+in principle — the installer hardcodes no protocol version, it reads what the artifacts declare —
+but the specific `edge`/`main` disagreement that motivated it is gone.
+
+---
+
+## 9. Administrator experience
+
+Before:
+
+```
+find plugins → copy files → edit ServUO → download bridge → start bridge
+→ configure startup → find the token → troubleshoot paths
+```
+
+After:
+
+```
+download artifact → verify checksum → run installer → select ServUO directory
+→ install components → paste 4 values into Admin → Shard → start ServUO normally
+```

installer/PROJECT_TREE.md

@@ -0,0 +1,37 @@
+# Runic Gateway installer — Project Tree
+
+> **Auto-generated.** This file is maintained by the `sync-project-tree` CI workflow in
+> the [`RunicGateway/installer`](https://gitea.whitlocktech.com/RunicGateway/installer) repository, which
+> opens a pull request here whenever the tracked file layout on `main` changes. Do not edit
+> by hand — changes will be overwritten by the next sync.
+
+A snapshot of the tracked files in the repository (build output, dependencies, and other
+git-ignored paths are excluded).
+
+```text
+installer/
+├── .gitea/
+│   ├── ISSUE_TEMPLATE/
+│   │   ├── bug_report.md
+│   │   ├── config.yaml
+│   │   └── feature_request.md
+│   ├── scripts/
+│   │   └── gen_tree.py
+│   ├── workflows/
+│   │   ├── bundle.yml
+│   │   ├── pr-checks.yml
+│   │   ├── release.yml
+│   │   └── sync-project-tree.yml
+│   └── PULL_REQUEST_TEMPLATE.md
+├── bundles/
+│   ├── bundle-2026.08.04.json
+│   ├── current.json
+│   └── README.md
+├── .gitignore
+├── CODE_OF_CONDUCT.md
+├── CONTRIBUTING.md
+├── CONTRIBUTORS.md
+├── LICENSE.md
+├── README.md
+└── SECURITY.md
+```

link/INTEGRATION.md

@@ -23,7 +23,31 @@ Every route **except `GET /health`** requires the shared token from `sidecar.tom
 | REST | `X-Api-Key: <token>` |
 | WebSocket | `?token=<token>` in the connect URL (browsers can't set headers on a WS handshake) |
 
-Missing or wrong token → **401** `{"error":"missing or invalid auth token"}`. The token is compared in constant time. It is generated automatically on first run (the sidecar logs it); rotate by editing `sidecar.toml` and restarting.
+Missing or wrong token → **401** `{"error":"missing or invalid auth token"}`. The token is compared in constant time. It is generated automatically on first run; rotate by editing `sidecar.toml` and restarting.
+
+To read it back afterwards, ask the sidecar rather than hunting through the startup log or the TOML:
+
+```console
+$ uo-link-sidecar --print-config --config /etc/runicgateway/sidecar.toml
+{
+  "component": "uo-link-sidecar",
+  "config_created": false,
+  "config_path": "/etc/runicgateway/sidecar.toml",
+  "protocol": 3,
+  "shard": { "bind": "127.0.0.1:7788" },
+  "store": { "path": "/var/lib/runicgateway/uo-link.db" },
+  "token_generated": false,
+  "version": "0.1.0",
+  "web": {
+    "auth_required": true,
+    "auth_token": "c0f04ace…",
+    "bind": "127.0.0.1:8080",
+    "ws_path": "/ws"
+  }
+}
+```
+
+That is the same set of values Admin → Shard asks for — base URL and WS URL are `web.bind` (substituting a reachable host if it is `0.0.0.0`) plus `web.ws_path`. The output **contains the token in clear text**, so treat it as a secret: it belongs in a terminal, not in a log or a CI artifact. `--print-config` also performs first-run setup, writing the config file and generating a token if there is none, and reports whether it did via `config_created` / `token_generated`.
 
 ---
 
@@ -31,18 +55,32 @@ Missing or wrong token → **401** `{"error":"missing or invalid auth token"}`.
 
 The wire protocol is versioned so a mismatch is caught immediately instead of failing weirdly.
 
-- Every response carries an **`X-UOLink-Version: 2`** header.
-- `GET /health` and the WebSocket `ws.hello` frame include `"protocol": 2`.
-- **Optionally**, send `X-UOLink-Version: 2` on your requests. If it disagrees with the sidecar, the request is rejected **409 Conflict**:
+- Every response carries an **`X-UOLink-Version: 3`** header.
+- `GET /health` and the WebSocket `ws.hello` frame include `"protocol": 3`.
+- **Optionally**, send `X-UOLink-Version: 3` on your requests. If it disagrees with the sidecar, the request is rejected **409 Conflict**:
 
   ```json
-  { "error": "protocol version mismatch", "sidecar_protocol": 2, "client_protocol": "1" }
+  { "error": "protocol version mismatch", "sidecar_protocol": 3, "client_protocol": "2" }
   ```
 
 Pin the version you built against and compare it to the header (or `/health.protocol`) at startup.
 
 **v2 (Protocol 2.0)** added the account-provisioning surface (§6.x: `POST /accounts/create`, `DELETE /link/{account}`) and the `account.*` events. Outbound event kinds are **additive** — a v1 client that ignores unknown kinds keeps working against the live feed — but the new *endpoints* require a v2 sidecar. If you send `X-UOLink-Version: 1`, calls to the new endpoints are refused with the 409 above.
 
+**v3 (Protocol 3.0)** adds `world.ruleset`, `points.board` and `vendor.listing` /
+`vendor.listing.remove`, with the `GET /ruleset`, `/points` and `/market` reads that serve them from
+the sidecar's store. Same shape as the v2 bump: the event kinds are additive, so a v2 client that
+ignores unknown kinds keeps working against the live feed, but the three new endpoints require a v3
+sidecar. There is deliberately **no feature-negotiation array** — v3 implies all three kinds, so the
+version number alone tells you what is available.
+
+**Upgrading a v2 integration.** The bump is an operator-visible hard break in one direction only: a
+client still declaring `2` gets a 409 on every protected route and, on the WebSocket, a closed
+connection on the `ws.hello` mismatch. So update the pinned version at the same time you deploy the
+v3 sidecar. Nothing that existed in v2 changed shape, so that is the whole migration — the website
+does it with a one-shot boot migration of its `uo_link_config.protocol` row ([`v3.md`](v3.md) §4.1);
+a third-party client changes the constant it sends.
+
 ---
 
 ## 3. Health
@@ -54,7 +92,7 @@ GET /health          (no auth)
 ```json
 {
   "status": "ok",                      // "ok" when plugin connected AND db reachable, else "degraded"
-  "protocol": 1,
+  "protocol": 3,
   "plugin_connected": true,            // is the shard link up right now?
   "database": "ok",                    // "ok" | "error"
   "uptime": "3d 12h",
@@ -77,7 +115,7 @@ A push-only stream of game events as they happen. You do **not** send commands o
 **On connect**, the first frame is:
 
 ```json
-{ "kind": "ws.hello", "protocol": 1 }
+{ "kind": "ws.hello", "protocol": 3 }
 ```
 
 **Then** a continuous stream of event frames, each with at least `t` (epoch ms) and `kind`. Route on `kind`.
@@ -315,6 +353,198 @@ The house registry — one row per house, complementing the `house.decay` *trans
 
 Render from `GET /houses` (§6) on connect, then keep live with these events.
 
+#### Shard ruleset (Protocol 3.0)
+
+How the shard is actually configured, published by the shard itself. **Not a sweep** — it changes only
+when an operator edits `Config/*.cfg`, so it is emitted once per shard↔sidecar connect (and on
+`[bridge reload`), exactly like `server.hello`.
+
+| kind | fields | notes |
+|------|--------|-------|
+| `world.ruleset` | `rev`, `shard`, `expansion`, `connect?`, `systems`, `caps`, `housing`, `accounts`, `vetRewards`, `loot`, `vendors`, `champions?`, `treasureMaps`, `vvv?`, `store`, `schedule?` | The whole ruleset, always complete — **never a delta**, so the latest frame replaces the previous one outright. Every block except `shard`/`expansion` is optional and is **omitted when its system is off**, so absence means "not applicable here", not "unknown". |
+
+`rev` is the shard's FNV-1a of the body: identical `rev` means the ruleset is unchanged and this frame
+is just a reconnect re-send, so a consumer can skip the write. It is deliberately **not**
+`String.GetHashCode()`, which is seeded per process and would change on every shard restart.
+
+```json
+{"kind":"world.ruleset","rev":"1a2b3c4d","shard":"UOMysticmoon","expansion":"EJ",
+ "systems":{"cityLoyalty":true,"vvv":true,"factions":false,"siege":false,"chat":true,
+            "store":true,"dailyRares":true,"honesty":true,"shadowguard":true,
+            "treasureMaps":true,"vetRewards":true,"testCenter":false},
+ "caps":{"skill":1000,"totalSkill":7000,"stat":225,"str":125,"dex":125,"int":125,
+         "strMax":150,"dexMax":150,"intMax":150},
+ "housing":{"accountHouseLimit":1},
+ "accounts":{"perIp":3,"charSlots":7,"autoCreate":true},
+ "vetRewards":{"enabled":true,"rewardIntervalDays":30},
+ "loot":{"feluccaLuckBonus":1000,"feluccaBudgetBonus":100,"feluccaMaxProps":11},
+ "vendors":{"restockDelayMinutes":60,"maxSell":500,"economyStockAmount":500},
+ "champions":{"powerScrolls":6,"statScrolls":16,"scrollChance":0.1,
+              "transcendenceChance":50.0,"rankThresholds":[5,10,13]},
+ "treasureMaps":{"enabled":true,"lootChance":0.01,"resetDays":30},
+ "vvv":{"enabled":true,"startSilver":2000,"enhancedRules":false},
+ "store":{"enabled":true,"currencyName":"Sovereigns"},
+ "schedule":{"autoSaveEnabled":true,"autoSaveFrequencyMinutes":15,"autoRestartEnabled":false},
+ "t":1752489280000}
+```
+
+**Two things consumers get wrong.**
+
+1. **`caps.skill` and `caps.totalSkill` are in tenths**, the way ServUO stores them: `1000` is `100.0`
+   skill and `7000` is `700.0` total. Rendering the raw number is actively misleading. The other caps
+   (`stat`, `str`, …) are plain integers.
+2. **`connect` is present only if the operator set `Bridge.PublicConnectAddress`.** The shard's real
+   listen address (`Server.cfg`) is never published; nor are `Staff.cfg`, `Email.cfg`, `DataPath.cfg`,
+   `Bridge.cfg`, `Compiler.cfg`, `Reports.cfg` or `Client.cfg`. The frame is built from an explicit
+   allowlist in `BridgeRuleset.cs` — `Config.Entries` is never enumerated, because that would sweep in
+   every key on the server.
+
+Absent entirely if the shard runs `Bridge.RulesetEnabled=false` or an older plugin. Render from
+`GET /ruleset` (§6) on connect, then keep live with this event.
+
+This **supersedes the `world.systems` frame** sketched in [`PROTOCOL_2.md`](PROTOCOL_2.md) §10.4 and
+never implemented; the `systems` block above is what that asked for.
+
+#### Points / loyalty leaderboards (Protocol 3.0)
+
+ServUO carries ~25 separate point currencies — Queen's Loyalty, Void Pool, Casino, Clean Up Britannia,
+the nine city loyalties, Blackthorn, the Doom / Khaldun / Kotl treasure systems — every one a standing
+players accumulate over months, and none of them visible outside an in-game gump before 3.0.
+
+A diff sweep (default 300 s), **one frame per system** rather than one large frame for all of them,
+matching `champ.update` / `guild.update`. A system is emitted only when its top N or its participant
+count actually changes.
+
+| kind | fields | notes |
+|------|--------|-------|
+| `points.board` | `system`, `nameString`, `nameNumber`, `maxPoints`, `showOnGump`, `players`, `top[]` | One system's complete board — **never a delta**. The latest frame for a `system` replaces the previous one outright. `top[]` entries are `{rank, serial, name, points}`. |
+
+`system` is the shard's own `PointsType` enum name (`QueensLoyalty`, `CleanUpBritannia`, …) and is the
+board's stable key. There is deliberately **no `points.remove`**: the set of systems is fixed at startup
+by `PointsSystem.Configure`, so a system cannot disappear at runtime — the same argument `city.update`
+makes for cities.
+
+```json
+{"kind":"points.board","system":"QueensLoyalty",
+ "nameString":"Queen's Loyalty","nameNumber":1114938,
+ "maxPoints":15000,"showOnGump":true,"players":842,
+ "top":[{"rank":1,"serial":"0x1A2B","name":"Darrow","points":29500},
+        {"rank":2,"serial":"0x1A2C","name":"Mireille","points":21000}],
+ "t":1752489280000}
+```
+
+**Four things consumers get wrong.**
+
+1. **`maxPoints` of `0` means UNCAPPED, not "zero points allowed".** ServUO's idiom for an uncapped
+   system is `double.MaxValue` (`DespiseCrystals`, `ShameCrystals` and `VoidPool` all use it), which
+   the plugin normalises to `0` rather than emitting a nonsense integer. On a real shard **most
+   systems are uncapped**, so a UI that renders `points / maxPoints` must special-case this or it will
+   divide by zero on the common path.
+2. **`nameString` is usually `null`.** The shard's `Name` is a `TextDefinition`, which may carry a
+   literal *or* a cliloc id, and in practice most systems use the cliloc — so `nameNumber` is set and
+   `nameString` is `null`. Resolve clilocs consumer-side; failing that, humanising the `system` key
+   ("CleanUpBritannia" → "Clean Up Britannia") reads better than showing a bare number. This is the
+   same contract `titles.reward` already documents.
+3. **`players` counts players who actually hold points**, not the size of the system's table. Ten of
+   the ~25 systems have `AutoAdd = true` and therefore keep a zero-point row for every character that
+   has ever logged in, so the raw table size would report the shard's entire character census as that
+   system's participants.
+4. **Entries carry `serial` and `name` only — never `acct` or `webId`.** A board is the widest-audience
+   surface the bridge has, so the account name of every ranked player deliberately does not cross the
+   wire; resolve serial → site user from your own link mirror if you need it.
+
+Absent entirely if the shard runs `Bridge.PointsLeaderboardEnabled=false` or an older plugin. Render
+from `GET /points` (§6) on connect, then keep live with this event.
+
+##### `char.profile` gains a `points` block
+
+Read-model enrichment on the existing kind — there is **no** request kind for one character's points,
+the same precedent `titles` set in [`PROTOCOL_2.md`](PROTOCOL_2.md) §10.3:
+
+```json
+"points":[{"system":"QueensLoyalty","nameString":"Queen's Loyalty","nameNumber":1114938,
+           "points":29500,"maxPoints":15000}]
+```
+
+Systems where the character has no entry, or an entry at zero, are **omitted** — otherwise every sheet
+would carry ~25 zeroes. `maxPoints` follows the same `0 == uncapped` rule as the board.
+
+`rank` is **absent by default** and appears only when the shard runs `Bridge.PointsProfileRank=true`:
+a points lookup stops at the character's own row, but a rank must count every row that beats them, in
+every system, on every profile build. Derive rank from `points.board` instead for anyone in the top N.
+
+#### Player-vendor marketplace (Protocol 3.0)
+
+The shard-wide shop index: every player vendor's shop name, owner, location and priced inventory —
+the same set the in-game **Vendor Search** gump reads, published so a site can offer the same search
+from outside the game.
+
+An **amortized round-robin diff sweep**, not a snapshot RPC, and the distinction is load-bearing:
+`rpc.rs::try_route` correlates a reply on the FIRST frame carrying a matching `reqId`, so a chunked
+reply sharing one `reqId` would deliver chunk 1 to the HTTP caller and leak chunks 2..N onto the
+broadcast feed. A whole-world snapshot could not fit in one frame inside the 10 s reply timeout
+either. The per-account `vendor.snapshot` RPC (§5) is unaffected and still serves the player portal.
+
+Each tick inventories at most `Bridge.MarketSweepBatch` vendors (default 25) starting from a
+persistent cursor, so **per-tick cost is bounded independently of world size**; full coverage takes
+`ceil(vendors / batch) × MarketSweepSeconds`. A vendor is emitted only when its contents, prices,
+shop name or location actually change.
+
+| kind | fields | notes |
+|------|--------|-------|
+| `vendor.listing` | `serial`, `shopName`, `ownerSerial`, `ownerName`, `location{}`, `count`, `total`, `truncated`, `items[]` | One vendor's complete shop — **never a delta**. The latest frame for a `serial` replaces the previous one outright. |
+| `vendor.listing.remove` | `serial` | The shop is gone from the index: dismissed, expired, or its owner switched off the in-game Vendor Search flag. |
+
+```json
+{"kind":"vendor.listing","serial":"0x40001234",
+ "shopName":"Darrow's Bargains","ownerSerial":"0x1A2B","ownerName":"Darrow",
+ "location":{"map":"Trammel","x":1421,"y":1699,"z":0,
+             "region":"Britain","house":"Darrow's Villa"},
+ "count":2,"total":2,"truncated":false,
+ "items":[{"serial":"0x40012ABC","itemId":3922,"hue":0,"amount":1,
+           "price":25000,"name":null,"cliloc":1023721},
+          {"serial":"0x40012ABD","itemId":7026,"hue":1157,"amount":3,
+           "price":500,"name":"a shard sigil","cliloc":1041243}],
+ "t":1752489280000}
+```
+
+**Six things consumers get wrong.**
+
+1. **`name` is `null` for nearly every item; `cliloc` is the real label.** Items carry a
+   `LabelNumber`, not a name. The plugin deliberately never calls `VendorSearch.GetItemName`, which
+   builds an `ObjectPropertyList`, serialises it and byte-parses the packet **per item** — a
+   multi-hundred-millisecond stall across a full pass. (It would not work anyway: every current
+   client ships its cliloc files compressed and ServUO's bundled `Ultima.StringList` cannot read
+   them, so the in-game gump has the same gap.) Resolve clilocs consumer-side; a non-null `name` is a
+   player-set literal and is strictly more specific, so **prefer it over the cliloc**.
+2. **`location` is one nested object, and it may be absent entirely.** It is nested so that a
+   consumer gating vendor whereabouts gates one field rather than five that can drift apart — the
+   website's `market.location` rule removes the whole object. Treat a missing `location` as "not
+   published", not as an error.
+3. **`truncated` means the shop holds more than the frame carries.** `count` is what was published,
+   `total` is what the shop actually holds, capped by `Bridge.MarketMaxListings` (default 250). A
+   commodity reseller with thousands of stacked resources is real and an uncapped frame for one is
+   measured in megabytes. Say "showing 250 of 3,104" rather than presenting a partial shop as
+   complete.
+4. **`child: true` means the price buys the ENCLOSING CONTAINER.** ServUO prices a container as a
+   unit and everything inside inherits that price with no `VendorItem` of its own; `DoSearch`
+   surfaces the same flag. A UI that prints the container's price against each item inside it is
+   lying about the shard.
+5. **Opted-out vendors are absent, and that is a privacy control.** `pv.VendorSearch` is the player's
+   own in-game toggle and the sweep honours it — hide your vendor in game and it is hidden here too.
+   The same goes for `Map.Internal` and a null backpack, matching `DoSearch`. Process
+   `vendor.listing.remove` promptly: it is how a player *revoking* that consent reaches you.
+6. **Prices are inherently stale, by design.** The round-robin sweep means a shop can be a full cycle
+   behind. Any UI over this must say how old the data may be — the website derives it from the oldest
+   vendor row.
+
+Entries carry `ownerSerial`/`ownerName` and **never `acct` or `webId`**, the same rule `points.board`
+follows. Absent entirely if the shard runs `Bridge.MarketEnabled=false` or an older plugin. Render
+from `GET /market` (§6) on connect, then keep live with these events — though note that a live
+firehose of whole vendor inventories is the largest stream the bridge produces, and a consumer that
+only needs a browsable index (as the website does) is better served by the REST read plus the
+periodic re-sweep.
+
 ---
 
 ## 5. REST — read queries
@@ -354,7 +584,7 @@ Full character sheet: stats, all trained skills, worn equipment with flattened i
 Field notes:
 - `skills[].base` is trained value, `value` includes item/temp bonuses, `cap` is the cap. **Do not assume `base <= cap`** — GM characters can exceed it.
 - `equipment[].mods` is a flattened map of every non-zero AOS attribute on the item (weapon or armor). Empty `{}` for plain items.
-- Item names are usually **clilocs**, not strings: use `name` when present, otherwise resolve `cliloc` against a UO cliloc table on the site.
+- Item names are usually **clilocs**, not strings: use `name` when present, otherwise resolve `cliloc` against a UO cliloc table on the site. **Do not expect the shard to resolve them for you** — on any modern client ServUO's own `Ultima.StringList` cannot read the client's compressed cliloc files, so `VendorSearch.GetItemName` returns `item.Name` and the in-game Vendor Search gump has the same gap. Building that table is a consumer-side job; the website's is described in [`website/CLILOCS.md`](../website/CLILOCS.md).
 - `titles` (Protocol 2.0): `selected` is the index into `reward` currently displayed (`-1` if none). `fameKarma`/`skill` are computed display titles, omitted when the character has none. `reward` entries may be a **cliloc number as a string** or a literal string — resolve numeric ones against your cliloc table, same as item names.
 - Errors: unknown account → **404** `{"kind":"bridge.error","reason":"unknown account"}`; bad slot → **404**/**400** similarly.
 
@@ -658,6 +888,72 @@ GET /houses
 
 Every house's latest snapshot — owner→houses map. Served from the sidecar's projection, kept current by the `house.*` stream (§4). Ordered by name. Survives a sidecar restart.
 
+### Shard ruleset (Protocol 3.0)
+
+```
+GET /ruleset
+→ { "ruleset": {"kind":"world.ruleset","rev":"1a2b3c4d","shard":"UOMysticmoon",
+      "expansion":"EJ","systems":{...},"caps":{...},"accounts":{...}, ... } }
+```
+
+The shard's published ruleset (§4 for the full frame and its two gotchas). Served from the sidecar's
+store, so it **answers while the shard is down** — a rules page that goes blank during a restart is
+worse than one that is briefly stale. Keep it current with the `world.ruleset` stream.
+
+`{"ruleset": null}` means the shard has never published one — an older plugin, or
+`Bridge.RulesetEnabled=false`. That is a real answer distinct from a published ruleset, and worth
+rendering differently ("not published yet") rather than as an empty ruleset.
+
+### Points / loyalty leaderboards (Protocol 3.0)
+
+```
+GET /points
+→ { "boards": [ {"kind":"points.board","system":"QueensLoyalty","nameString":"Queen's Loyalty",
+      "nameNumber":1114938,"maxPoints":15000,"showOnGump":true,"players":842,
+      "top":[{"rank":1,"serial":"0x1A2B","name":"Darrow","points":29500}, ...],"t":...}, ... ] }
+
+GET /points/{system}                 # e.g. /points/QueensLoyalty
+→ {"kind":"points.board","system":"QueensLoyalty", ... }
+```
+
+Every system's latest board, or one by its `PointsType` name (§4 for the frame and its four gotchas).
+Served from the sidecar's projection, kept current by the `points.board` stream, ordered by display
+name. Survives a sidecar restart — which matters more here than for live state, since these are
+standings built over months and blanking them during a restart reads as data loss.
+
+`GET /points/{system}` returns **404** for a system the shard has never published (an unknown name, or
+one excluded by `Bridge.PointsSystems`). That is distinct from a published board nobody has scored in
+yet, which is **200** with an empty `top[]` — and the two are worth rendering differently.
+
+### Player-vendor marketplace (Protocol 3.0)
+
+```
+GET /market?limit=200&offset=0
+→ { "vendors": [ {"kind":"vendor.listing","serial":"0x40001234",
+       "shopName":"Darrow's Bargains","ownerSerial":"0x1A2B","ownerName":"Darrow",
+       "location":{"map":"Trammel","x":1421,"y":1699,"z":0,
+                   "region":"Britain","house":"Darrow's Villa"},
+       "count":2,"total":2,"truncated":false,"items":[ ... ],"t":...}, ... ],
+    "total": 137, "limit": 200, "offset": 0 }
+```
+
+Every vendor's latest shop, exactly as `vendor.listing` published it (§4 for the frame and its six
+gotchas). Served from the sidecar's projection, so it answers while the shard is down.
+
+**This is the only PAGED read the sidecar serves**, because it is the only board that can be a whole
+world's inventory. `limit` is clamped to 1..1000 (default 200); `total` is returned so a caller knows
+when to stop rather than paging until it sees a short page, which would race a concurrent sweep.
+Ordering is by **serial**, not by shop name — a serial is stable while a shop name is renameable, so
+a rename mid-walk cannot make a vendor skip or repeat a page.
+
+The route is `/market` and deliberately **not** `/vendors`: `/vendors/{account}` next door is the
+per-account RPC (§5), and two routes a prefix apart meaning "this player's shops" and "every shop on
+the shard" is a trap nobody wins.
+
+Frames are served **verbatim**, owner names and coordinates included. That is not an oversight: the
+sidecar defines no audiences. Deciding who may see what is the consuming site's job — see
+[`v3.md`](v3.md) §3 for how the website does it.
+
 ---
 
 ## 7. Status codes
@@ -683,7 +979,7 @@ Every house's latest snapshot — owner→houses map. Served from the sidecar's
 A typical character page:
 
 ```js
-const H = { "Authorization": `Bearer ${TOKEN}`, "X-UOLink-Version": "2" };
+const H = { "Authorization": `Bearer ${TOKEN}`, "X-UOLink-Version": "3" };
 
 // 1. render the roster
 const roster = await fetch(`${BASE}/roster/${account}`, { headers: H }).then(r => r.json());

link/PLAN.md

@@ -284,6 +284,15 @@ Counts in `hello` are a live snapshot taken on the Core thread, not a cached val
 
 `Item.Name` is frequently `null`; the display name is `LabelNumber`, a cliloc id. **There is no `Data/Cliloc.enu` in this repo** — `BRIDGE_FINDINGS.md` §IV.4 is wrong about this. Cliloc data lives in the client install, which `DataPath` resolves to `D:\Games\Electronic Arts\Ultima Online Classic\`. Ship **both** `name` (when non-null) and `cliloc`, and resolve the number **on the website** against a cliloc map. That avoids a server-side dependency on the client directory.
 
+**Update (3.0).** That recommendation held, and the reason it had to hold turned out to be stronger
+than "avoids a dependency": **ServUO cannot resolve clilocs either.** Every current client ships its
+`Cliloc.*` files compressed, and the bundled `Ultima.StringList` reads only the older plain layout —
+so `VendorSearch.StringList` is null and `VendorSearch.GetItemName` returns `item.Name` on any modern
+shard. The in-game Vendor Search gump has the same gap, which is why `vendor.listing` never calls it.
+Pushing name resolution to the plugin was never an option. See [`v3.md`](v3.md) §8.6 and
+`docs/website/CLILOCS.md` for how the site gets a table instead (the operator converts one from their
+own client, once).
+
 ---
 
 ## 8. Corrections to `BRIDGE_FINDINGS.md`
@@ -315,6 +324,35 @@ Counts in `hello` are a live snapshot taken on the Core thread, not a cached val
 7. **Core edit: `PlayerVendorSale`** (§6). Then the cheat-detection feed.
 8. **Cheat signals.** `FastWalk`, `OnPropertyChanged` audit, vendor-sale anomaly detection in the sidecar.
 
+**Beyond 1.0.** Phases above are the 1.0 read/event plane. Protocol 2.0's phasing (provisioning +
+world-state boards) is [`PROTOCOL_2.md`](PROTOCOL_2.md) §13; Protocol 3.0's (visibility framework,
+shard content and standings) is [`v3.md`](v3.md) §9, which also tracks what has landed. Shipped from
+3.0 so far: **Part A** — the visibility framework — **`world.ruleset`** ([`v3.md`](v3.md) §5),
+`BridgeRuleset.cs`, the first bridge stream that is neither an event subscription nor a sweep (it is
+emitted once per connect, like `server.hello`, because shard config changes only when an operator
+edits a file) — the **spawn atlas** ([`v3.md`](v3.md) §6), which is website-only and touches no wire
+at all — and **`points.board`** ([`v3.md`](v3.md) §7), `BridgePoints.cs`, the loyalty/points
+leaderboards. `BridgePoints` is the widest read the bridge performs: ten of ServUO's ~25 point systems
+keep a row for every character ever created, so it selects the top N in a single bounded pass rather
+than sorting, and runs on a deliberately slow 300 s interval.
+
+Also shipped: **`vendor.listing`** ([`v3.md`](v3.md) §8), `BridgeMarket.cs`, the shard-wide
+player-vendor index. It introduces the one sweep pattern the bridge did not previously have — an
+**amortized round-robin**. Every other sweep walks its whole collection per tick, which is fine for
+tens of houses or a fixed set of point systems and is not fine for a world of shops whose inventories
+recurse into containers. `BridgeMarket` inventories at most `MarketSweepBatch` vendors per tick from
+a persistent cursor, so the per-tick cost is bounded by the batch rather than by world size, and full
+coverage takes `ceil(vendors / batch) x MarketSweepSeconds`. Measured at **15.4 ms** for a cold tick
+of 25 vendors x 40 listings and **0.3 ms** in steady state (the per-vendor diff), on a shard of 209k
+items / 43k mobiles. It is also the first stream to honour a per-player privacy toggle: ServUO's own
+`PlayerVendor.VendorSearch` flag, so a shop hidden in game is hidden on the site.
+
+That completes 3.0's feature work, so the last step is the version itself: `PROTOCOL_VERSION` **2 →
+3** and the coordinated `edge` → `main` merge across all four repos ([`v3.md`](v3.md) §4 and §4.1).
+The bump is deliberately the *only* thing that happens at that moment — v3 adds kinds and endpoints
+but changes nothing that already existed in v2 — so the operator-visible break is limited to
+re-pinning the version, which the website does for itself in a one-shot boot migration.
+
 ### Config keys (`Config/Bridge.cfg`)
 
 ```ini
@@ -328,6 +366,13 @@ EconomySweepSeconds=300
 
 Read in `Configure()` via `Config.Get<T>("Bridge.<Key>", default)`. Key scope is the filename: `Bridge.cfg` + `StatSweepSeconds` → `Bridge.StatSweepSeconds`.
 
+The set above is the 1.0 sample, not the current one — every later phase added keys (sweep intervals
+for each board, the town-crier/news caps, the admin write plane, account provisioning, and 3.0's
+`RulesetEnabled` / `PublicConnectAddress` / `RulesetIncludeSchedule`, and the `Points*` and `Market*`
+blocks).
+**`servuo-plugins/overlay/Config/Bridge.cfg`
+is the authoritative, commented list**; `BridgeConfig.cs` holds the defaults.
+
 ---
 
 ## 11. Phase 1 acceptance

link/PROJECT_TREE.md

@@ -0,0 +1,48 @@
+# uo-link — Project Tree
+
+> **Auto-generated.** This file is maintained by the `sync-project-tree` CI workflow in
+> the [`RunicGateway/link`](https://gitea.whitlocktech.com/RunicGateway/link) repository, which
+> opens a pull request here whenever the tracked file layout on `main` changes. Do not edit
+> by hand — changes will be overwritten by the next sync.
+
+A snapshot of the tracked files in the repository (build output, dependencies, and other
+git-ignored paths are excluded).
+
+```text
+link/
+├── .gitea/
+│   ├── ISSUE_TEMPLATE/
+│   │   ├── bug_report.md
+│   │   ├── config.yaml
+│   │   └── feature_request.md
+│   ├── scripts/
+│   │   └── gen_tree.py
+│   ├── workflows/
+│   │   ├── pr-checks.yml
+│   │   ├── release.yml
+│   │   ├── sonarqube.yml
+│   │   └── sync-project-tree.yml
+│   └── PULL_REQUEST_TEMPLATE.md
+├── sidecar/
+│   ├── src/
+│   │   ├── cli.rs
+│   │   ├── config.rs
+│   │   ├── main.rs
+│   │   ├── rpc.rs
+│   │   ├── shard.rs
+│   │   ├── store.rs
+│   │   └── web.rs
+│   ├── .gitignore
+│   ├── Cargo.lock
+│   ├── Cargo.toml
+│   ├── README.md
+│   └── sidecar.toml.example
+├── .gitignore
+├── CODE_OF_CONDUCT.md
+├── CONTRIBUTING.md
+├── CONTRIBUTORS.md
+├── LICENSE.md
+├── README.md
+├── SECURITY.md
+└── sonar-project.properties
+```

link/PROTOCOL_2.md

@@ -285,6 +285,18 @@ City titles and faction/VvV merchant titles (`CityLoyaltySystem.ApplyCityTitle`,
 
 ### 10.4 Factions / Vice vs Virtue
 
+> **Status update (Protocol 3.0, 2026-07-28).**
+>
+> - **The deferred question is answered.** This shard runs **Vice vs Virtue** (`VvV.cfg Enabled=True`);
+>   old Factions is off, and in stock ServUO that is not a coincidence —
+>   `Services/Factions/Core/Faction.cs` sets `Settings.Enabled = !ViceVsVirtueSystem.Enabled`, so the
+>   two are mutually exclusive by construction. The `vvv.standings` / `vvv.battle` streams below are
+>   therefore unblocked, but are **not** scoped for 3.0 (see [`v3.md`](v3.md) §2 row 5).
+> - **`world.systems` is superseded by `world.ruleset`** ([`v3.md`](v3.md) §5), which shipped in 3.0.
+>   It was never implemented under this name. `world.ruleset` carries the same
+>   `systems{cityLoyalty, vvv, factions, …}` sub-object this section asked for, plus the rest of the
+>   shard's published ruleset, so no orphan kind is left behind. Do not implement `world.systems`.
+
 **Which system is live is a shard decision — verify before building.** Two exist:
 
 - **Old Factions** (`Scripts/Services/Factions`): `Faction.Commander` (leader, `Faction.cs:160`), `Faction.Election`, `Faction.Members` (`List<PlayerState>`), and faction-controlled **Towns** (`Town.cs` — each town has an owning faction, a sheriff, and finance). Config-gated and, on most modern shards, **off**.
@@ -300,7 +312,10 @@ City titles and faction/VvV merchant titles (`CityLoyaltySystem.ApplyCityTitle`,
 {"kind":"vvv.standings","order":142000,"chaos":138500,"leaderSide":"Order"}
 ```
 
-> Start by detecting which system is enabled at boot and streaming only that one; emit a one-time `world.systems` frame (what's on: cityLoyalty, vvv, factions) so the website renders the right panels instead of guessing.
+> Start by detecting which system is enabled at boot and streaming only that one. ~~emit a one-time
+> `world.systems` frame (what's on: cityLoyalty, vvv, factions) so the website renders the right panels
+> instead of guessing.~~ — **superseded: `world.ruleset` already carries that `systems` block** (see the
+> status note at the top of this section).
 
 ## 11. Further integration points — a menu to pick from
 

website/API_V2_PLAN.md

@@ -0,0 +1,731 @@
+# Website API — router domain split + CSP hardening
+
+Status: **domain split complete** — PR 0 (route manifest), CSP report-only and split PRs 1–5 have all
+landed; only the CSP enforce PR remains, and it is blocked on soak data rather than on code ·
+Target repo: `website/` · Docs owner: this file + `BACKEND_DESIGN.md`
+
+> **This file replaces the earlier "API v2" plan** (auth merge → CSP → domain split, with a parallel
+> `/api/v2` mount and an `/api/mobile` facade). Three of those four pieces are **not being built**:
+> the auth merge and the mobile facade are deferred with their reasoning recorded below, and the
+> parallel-version scaffold in [API_V2_SKELETON.md](./API_V2_SKELETON.md) is superseded. The filename
+> is kept so existing links resolve. What remains is genuinely useful work:
+>
+> 1. **CSP hardening** — small, independent, ships on its own cadence.
+> 2. **The domain split** — `admin.routes.js` (1552 lines, 110 routes) broken into one router file per
+>    business capability, **in place, with every URL unchanged**. This is the actual driver.
+
+---
+
+## Why the auth merge is out
+
+The original plan replaced httpOnly session cookies with a bearer JWT + rotating refresh token for
+every client, so web and mobile would share one session model. Reasons that no longer hold up:
+
+1. **The current model is the more secure one.** httpOnly + SameSite cookies are unreadable from JS
+   and carry CSRF protection by default. Every migration target is a sideways or backwards move:
+   - Refresh token in `localStorage` → any XSS becomes **persistent full account takeover**, not a
+     bounded access-token window. A short access TTL does not help; the attacker mints new pairs.
+   - Refresh token in an httpOnly cookie scoped to the refresh endpoint → safe, but that is
+     *cookies with extra steps*. It concedes the premise.
+2. **"One session model everywhere" is already true where it matters.** `auth/session.service.js`
+   unifies cookie and bearer into a single session, and `auth/token.js` already extracts from either
+   `Cookie` or `Authorization: Bearer`. That abstraction is written, working, and paid for. The merge
+   would move complexity *out* of `extractToken` and *into* the SPA.
+3. **The cookie codepath survives the merge anyway.** The SSO / email-connect redirect flow must keep
+   its short-lived httpOnly tx / PKCE-verifier / pending-TOTP cookies — the browser leaves for the
+   IdP and returns with no JS context. So the merge never actually delivered "cookies are gone."
+4. **It carried the plan's most bug-prone work as a dependency.** The admin SSE rewrite
+   (`EventSource` → hand-rolled `fetch` + `ReadableStream` + SSE frame parser + reconnect/backoff +
+   refresh-on-401) existed *only* to serve the bearer model. Without the merge, the admin stream stays
+   on `EventSource` with `withCredentials` and that code is never written.
+5. **It is a contract change with no user-visible payoff**, competing for the same review attention as
+   the domain split, which is the thing that actually hurts today.
+
+### Dropped with it
+
+- v2 bearer auth routes (`/api/v2/auth/{login,refresh,logout,login/totp}`).
+- Deletion of the `setAuthCookie` / `clearAuthCookie` path.
+- `rg_trust` cookie → `X-Trust-Token` header migration for web (the header stays available for native
+  clients via `extractTrustToken`, unchanged).
+- `api/client.js` bearer + silent-refresh rewrite.
+- `lib/useShardFeed.js` admin-stream fetch rewrite. **The admin SSE stream stays as-is.**
+
+### Kept from it
+
+- **CSP hardening** — now its own phase (below). It was justified as a compensating control for a
+  JS-held token; it is worth doing regardless, just no longer urgent.
+- **The public/admin SSE allowlist split** — unchanged security boundary, unrelated to session model.
+- **The tx-cookie carve-out reasoning** — recorded here so a future merge attempt doesn't rediscover it.
+
+---
+
+## Deferred: the auth merge
+
+Not cancelled — parked behind trigger conditions. Revisit if **any** of these become true:
+
+| Trigger | Why it changes the answer |
+|---|---|
+| The API becomes genuinely cross-origin (separate API host) | `SameSite` cookies stop being the easy path; bearer becomes the natural model. |
+| Third-party or OAuth clients are introduced | Cookies don't serve clients you don't control. |
+| Mobile and web session behavior diverge enough to cause real bugs | The unification argument gets teeth it currently lacks. |
+
+If it is ever revived, two specs the original plan lacked must be written **first**:
+
+- **Refresh-token reuse detection.** Rotation is only useful with it: replay of an already-consumed
+  refresh must revoke the entire token family, not just fail the one request.
+- **Rollback procedure.** Once web clients have discarded their cookies, a bad deploy locks everyone
+  out. Needs a documented path back.
+
+---
+
+## Why there is no `/api/v2`
+
+The domain split reorganizes router *files*. It does not need to move a single URL — because the URL
+surface is **already grouped by capability**. Inventory taken from the live Express stack — 196
+`/api/v1` routes, plus three outside it (`GET /api/health`, `GET /api/docs.json`,
+`GET /.well-known/assetlinks.json`) and 2 on the internal port. Full machine-readable list:
+[`api-route-inventory.json`](./api-route-inventory.json).
+
+| Group | Routes | Second segment → capability |
+|---|---|---|
+| `/admin` | 110 | `shard` 16 · `moderation` 15 · `users` 15 · `wiki` 14 · `posts` 9 · `pages` 7 · `account` 6 · `email` 6 · `uo-link` 5 · `auth` 4 · `invites` 3 · `bot-activity` 2 · `discord-bot` 2 · `settings` 2 · `activity` 1 · `dashboard` 1 · `site-mode` 1 · `uploads` 1 |
+| `/auth` | 42 | `me` 23 · `mobile` 5 · `sso` 4 · `password` 3 · `invite` 2 · `login` 2 · `logout` 1 · `providers` 1 · `register` 1 |
+| `/public` | 24 | `shard` 12 · `wiki` 4 · `pages` 2 · `posts` 2 · `contact` 1 · `settings` 1 · `status` 1 · `version` 1 |
+| `/player` | 20 | `account` 8 · `shard` 8 · `appeals` 4 |
+
+Every capability already owns a URL prefix, so each new router file mounts at the prefix it already
+owns and the emitted paths are **byte-identical**. No URL change means no contract change, and no
+contract change means no reason to mount a parallel version.
+
+Consequences of doing it in place:
+
+- No `/api/v2`, no dual mount, no route-by-route migration, no v1-usage telemetry project, and no
+  v1-retirement sequence.
+- `BASE = /api/v1` in `client/src/api/client.js` never changes. The Discord bot's `SITE_PUBLIC_URL`
+  never changes. The Android app is untouched.
+- [API_V2_SKELETON.md](./API_V2_SKELETON.md) (the `router/v2/` scaffold) is **superseded and not
+  scheduled**. It is kept as the concrete recipe if a real contract break ever forces a versioned API.
+
+**Tripwire:** if any endpoint turns out to *need* a new URL, that is a contract change, not a
+refactor. List it explicitly, and reopen the versioning question before writing the code — do not
+smuggle a URL change into a "mechanical" PR.
+
+---
+
+## Deferred: the `/api/mobile` facade and the app-version floor
+
+The earlier plan's Phase 0 stood up a version-agnostic `/api/mobile` namespace and migrated the
+Android app onto it, plus an app-version header and a server-side min-version floor.
+
+**Why it was proposed:** the app hardcodes **69** distinct `api/v1/…` paths (`data/api/*.kt`,
+`core/net/ShardStreamClient.kt`, `core/net/HostSelectionInterceptor.kt`,
+`core/auth/sso/SsoAuthManager.kt`), has no version negotiation and no force-update, and installs in
+the wild cannot be forced forward. Under a parallel-`/api/v2` plan that made the app the load-bearing
+coupling: v1 could not be retired until the fleet aged out.
+
+**Why it is deferred:** with the split done in place, no URL moves and nothing is being deleted — so
+there is no fleet to sunset and no coupling to break. A facade would add ~70 permanently maintained
+delegate routes plus a contract-test suite to solve a problem that does not currently exist. The
+version floor was scoped to sunsetting the pre-facade fleet, so it goes with it.
+
+**If it is ever revived** (the trigger is the mobile contract genuinely needing to diverge from web —
+different response shapes, a mobile-only aggregation endpoint, a real breaking change):
+
+- **Start with the alias mount, not a delegate layer:** `apiRouter.use('/mobile', v1Router)` gives the
+  app a stable, version-agnostic namespace with identical wiring, identical middleware and zero
+  per-route maintenance. Build hand-written delegates only for the routes that actually diverge.
+- **A facade is a security surface, not a convenience alias.** Any hand-written route must carry the
+  *same* middleware chain as the route it mirrors (`requireAuth`, `staffOnly`/`adminOnly`, validators,
+  the public/admin SSE allowlist split). A re-exposed admin route missing `adminOnly` is privilege
+  escalation.
+- **It needs contract tests.** The moment the app pins a namespace, its response shapes are a
+  committed contract; an internal refactor that changes a shape must fail a test before it ships to
+  installed apps.
+- **The mobile SSE stream stays anonymous** under whatever path it gets — the app sends no
+  `Authorization` header.
+
+---
+
+## Phase 1 — CSP hardening (independent)
+
+Previously bundled with the auth merge as a compensating control for a JS-held token. With no token in
+JS, this is **defense in depth on its own merits** — cheap, worth doing, blocking nothing. It has no
+dependency on the domain split and can ship at any time.
+
+**Sequencing fix from the original plan:** the old version both "ships with the auth merge" and called
+for a one-release report-only soak. Those contradict. Correct order is **report-only first, observe one
+release, then enforce** — now trivially satisfiable since nothing waits on it.
+
+The app already ships a tuned policy (`server/src/app.js`). Two directives are load-bearing and are
+**already correct** — the job is to keep them that way:
+
+- `script-src 'self'` — no `'unsafe-inline'` / `'unsafe-eval'`. Primary defense.
+- `connect-src 'self'` — the exfiltration channel. Don't widen it unless the API genuinely becomes
+  cross-origin (which would also reopen the auth-merge question — see the trigger table).
+
+`style-src 'unsafe-inline'` stays — it permits inline styling, not script execution, and React's
+pervasive `style={{…}}` attributes can't be nonce'd. Not a meaningful hole. The `/api/docs` route keeps
+its deliberately looser policy (swagger-ui injects an inline bootstrap script); that carve-out is
+scoped to the one route and stays scoped.
+
+Target enforced policy:
+
+```
+default-src 'self';
+script-src 'self';
+connect-src 'self';
+img-src 'self' data: https:;
+style-src 'self' 'unsafe-inline';          /* + fonts.googleapis.com only until fonts are self-hosted */
+font-src 'self';                            /* + fonts.gstatic.com only until fonts are self-hosted */
+object-src 'none';
+base-uri 'self';
+form-action 'self';
+frame-ancestors 'none';
+```
+
+Delta vs. the policy in `server/src/app.js` today. This was written as two directives; on
+implementation it turned out to be **one**:
+
+- ~~**Add `form-action 'self'`** (currently absent)~~ — **it was not absent.** The directives object in
+  `app.js` does not list it, but the middleware is configured `useDefaults: true`, and helmet's default
+  set already supplies `form-action 'self'` — so the header served in production has carried it all
+  along. Verified by capturing the live `Content-Security-Policy` header from the running app rather
+  than reading the config, which is how the plan got this wrong. **No behavioural change here.** It is
+  now written out explicitly in `config/csp.js` anyway: a security directive should not depend on a
+  third-party library's defaults surviving its next major version.
+- **Tighten `frame-ancestors`** `'self'` → `'none'` — nothing legitimately frames the site. **This is
+  the entire behavioural delta of the phase.**
+- Unchanged: `default-src`, `script-src`, `connect-src`, `object-src 'none'`, `base-uri 'self'`, and
+  `img-src … https:` (external `BRAND_*` logo/hero and `<img>` in sanitized wiki/news bodies rely on
+  `https:`).
+
+The soak is still worth running for that one directive, and arguably it is the directive that most
+needs one: a `frame-ancestors` report is generated by the browser of *whoever framed the site*, so it
+is the only way to discover that something legitimately embeds us before the enforcing policy breaks
+it. Nothing else can tell us that.
+
+**Rollout:** ship via `Content-Security-Policy-Report-Only` with `report-to` for one release, watch for
+violations, then flip to enforce.
+
+Before trusting `script-src 'self'`: Vite's build injects an inline modulepreload-polyfill `<script>`
+into `dist/index.html`, which that directive blocks (harmless, but throws a violation).
+**Already handled** — `client/vite.config.js` sets `modulePreload: { polyfill: false }`, so the build
+emits no inline bootstrap script. (The `renderIndexHtml` branding injection adds only `<meta>`/`<link>`
+tags — no inline script, no nonce needed.)
+
+### Where reports go
+
+`report-to` needs somewhere to point, so the report-only PR stands up a same-origin sink:
+**`POST /api/csp-report`** (`server/src/router/cspReport.controller.js`, wired in `app.js`). Same-origin
+on purpose — violation reports describe attacks against this site and are not handed to a third-party
+collector. It writes to the `csp` log tag and stores nothing.
+
+It is mounted outside `/api/v1`, alongside `/api/health`: the browser learns the path from the policy
+header, never from a client build, so it is not part of the versioned client contract. This is the
+`+1` in the route manifest that made PR 0 go first (see § Sequencing).
+
+Necessary properties, since it is an unauthenticated public `POST` (browsers send reports with no
+session, and gating it would silence exactly the anonymous visitors worth hearing about):
+
+- **Both wire formats.** `report-uri` (Firefox, Safari) sends `application/csp-report` with a single
+  hyphenated-key object; `report-to` (Chrome) sends `application/reports+json` with an array of
+  camelCase envelopes. Handling one silently drops half the browsers. Both directives are emitted, and
+  `report-to` additionally needs a `Reporting-Endpoints` response header or it is inert.
+- **Always 204, even for junk.** A 4xx would make the global error handler write an ERROR line quoting
+  the attacker-supplied body — turning an open endpoint into a log-flood primitive. A browser cannot
+  act on an error from a report sink anyway.
+- **Bounded everywhere:** 16 KB body cap, a per-IP rate limit, a fixed field allowlist, and every
+  logged field truncated (`script-sample` is attacker-influenced and can carry a whole inline script).
+
+**Retiring it:** the sink exists for the soak. When the tightened policy flips to enforced and the
+report-only twin is deleted, this endpoint goes with it — *unless* a `report-to` group is deliberately
+kept on the enforced policy, which is a reasonable thing to want. Decide that in the enforce PR rather
+than leaving an orphan route behind.
+
+Tracked follow-ups (own PRs):
+
+- **Self-host the Cinzel font** → drop `fonts.googleapis.com` from `style-src` and `fonts.gstatic.com`
+  from `font-src`, removing two third-party origins from the trust surface.
+- **Trusted Types** — `require-trusted-types-for 'script'` + a `trusted-types` policy, report-only
+  first. Audit `dangerouslySetInnerHTML` + the `sanitizeHtml` render path first.
+
+---
+
+## Phase 2 — The domain split
+
+**This is the reason the plan exists.** Everything else is supporting work.
+
+**Rule:** one router file = one business capability; the URL names the domain; related endpoints live
+together regardless of HTTP method; no generic `admin.routes.js` catch-all. Controllers are **already**
+domain-split — this re-wires routes, not logic.
+
+**Invariant:** each capability router mounts at the prefix it already owns, so the emitted URL set does
+not change. Proved per PR by the route manifest (§ PR 0).
+
+Target tree — derived from the inventory above, **inside `router/v1/`** (no `v2/` directory):
+
+```
+router/v1/
+  admin/
+    index.js            # mounts the capability routers below under /admin, keeps the
+                        # shared `noindex, isLoggedIn, staffOnly` gate in one place
+    users.router.js         account.router.js       invites.router.js
+    authProviders.router.js moderation.router.js    botActivity.router.js
+    posts.router.js         pages.router.js         wiki.router.js
+    uploads.router.js       shard.router.js         uoLink.router.js
+    email.router.js         discordBot.router.js    settings.router.js
+    activity.router.js      # the staff audit log — landed in PR 2, not with dashboard
+    dashboard.router.js     # + the /site-mode singleton
+  auth/
+    login.router.js  register.router.js  password.router.js  invite.router.js
+    sso.router.js    mobile.router.js    me.routes.js (already split, 23 routes)
+  public/
+    news.router.js (posts) pages.router.js  wiki.router.js  shard.router.js
+    site.router.js         # status, settings, version, contact
+  player/
+    account.router.js  shard.router.js  appeals.router.js
+  internal/            (unchanged — stays on the unpublished port, never mounted publicly)
+```
+
+Steps:
+
+1. **Land PR 0 (route manifest) first** — the mechanical proof that later PRs move no URL.
+2. Carve `admin.routes.js` into the per-capability files above, each requiring its already-existing
+   controller. `admin/index.js` keeps the shared gate (`noindex, isLoggedIn, staffOnly`) and mounts
+   each capability router at its existing prefix; the `adminOnly` / `modAccess` gates move with the
+   routes that use them.
+3. Split `public.routes.js`, `player.routes.js`, and the remaining `auth.routes.js` groups the same
+   way. `auth/me.routes.js` is already a separate file and stays.
+4. Keep `/internal` off the public listener exactly as today (separate `internalApp.js` port).
+5. Move each route's `#swagger.*` annotations **with** the route, then regenerate
+   (`cd website/server && npm run swagger`).
+6. Update `BACKEND_DESIGN.md` §2 (folder structure) and §4 (API contract — it names
+   `admin.routes.js → admin.controller.js` and friends) as routers move, plus `PROJECT_TREE.md`.
+
+Because the auth model is untouched and the URLs are frozen, each PR is a **pure mechanical refactor
+with a green test suite and a zero-diff route manifest as its acceptance criteria** — which is what
+makes grouped PRs actually reviewable.
+
+> **Step 6 correction:** `PROJECT_TREE.md` is no longer hand-edited. Since website#98 it is
+> auto-generated by the `sync-project-tree` CI workflow, which opens its own docs PR after a merge to
+> `main`. Leave it alone in split PRs. `BACKEND_DESIGN.md` §2/§4 are still manual.
+
+### PR 1 — as landed
+
+`admin/index.js` owns the shared `noindex, isLoggedIn, staffOnly` gate and the mount table, and
+declares no routes itself. The gate sits **ahead of every mount**, so a capability router extracted in
+a later PR cannot silently ship without it. Route counts:
+
+| Router | Routes | Prefix | Extra gate |
+|---|---|---|---|
+| `account.router.js` | 6 | `/admin/account` | none — self-service, an editor manages their own 2FA |
+| `users.router.js` | 15 | `/admin/users` | `adminOnly` at router level |
+| `invites.router.js` | 3 | `/admin/invites` | `adminOnly` per route |
+| `authProviders.router.js` | 4 | `/admin/auth` (routes are `/providers[/:id]`) | `adminOnly` per route |
+| `admin.routes.js` (residual) | 82 | group root, mounted last | unchanged |
+
+6 + 15 + 3 + 4 + 82 = the 110 inventoried admin routes. None of the four prefixes appears in the
+residual file, so nothing depends on mount ordering.
+
+Three findings worth carrying into PRs 2–5:
+
+- **The self-service `/shard/*` routes stay with `shard` (PR 4), despite their `Admin · Account`
+  swagger tag.** The invariant is *prefix ownership*, not tag agreement: one router owns `/shard`, so
+  splitting six routes off it by capability would mean two routers mounting under the same prefix and
+  an ordering hazard for no gain. Retag them in PR 4 if the tag still grates.
+- **`usersRouter.use(adminOnly)` is exactly equivalent to the old `adminRouter.use('/users', adminOnly)`**
+  now that the router is mounted at `/users` — but only because it is mounted at a prefix. Under a
+  *pathless* mount, a bare `use(gate)` would run for every request passing through en route to a later
+  mount, 403-ing an editor on `/admin/posts`. Do not "simplify" a prefix mount away.
+- **`routes.guards.json` came back zero-diff too**, not just the manifest — no route lost or gained a
+  gate. Worth checking both every time; the guards file is the one that would catch a dropped
+  `adminOnly` that the method+path freeze cannot see.
+
+The OpenAPI spec was also byte-for-byte unchanged, which required a prerequisite fix — see below.
+
+### PR 2 — as landed
+
+`moderation`, `bot-activity` and `activity` — 18 routes, leaving 64 in the residual file.
+
+| Router | Routes | Prefix | Extra gate |
+|---|---|---|---|
+| `moderation.router.js` | 15 | `/admin/moderation` | `modAccess` (admin + moderator) at router level |
+| `botActivity.router.js` | 2 | `/admin/bot-activity` | `adminOnly` per route |
+| `activity.router.js` | 1 | `/admin/activity` | none — staff-wide audit log |
+| `admin.routes.js` (residual) | 64 | group root, mounted last | unchanged |
+
+All four gates came back zero-diff: `routes.manifest.json` (200 public + 2 internal),
+`routes.guards.json`, `swagger-output.json` (198 operations), and `docs/website/api-route-inventory.json`
+was already in sync. 434 server tests green.
+
+Notes:
+
+- **`/activity` gets its own file, deviating from the target tree above**, which parked it as a
+  singleton inside `dashboard.router.js`. It is folded into PR 2 by the sequencing list, and PR 4 is
+  where `dashboard` lands — so honouring the tree would have meant leaving one route in the residual
+  file for two PRs to satisfy a filename. It is also a genuinely separate capability: `/activity` is
+  the **staff audit log** (`activity.model.js`), while `/dashboard` is a stats overview and
+  `/bot-activity` is the botScore middleware's in-memory ban state. Three different things that read
+  alike. **PR 4 mounts `dashboard` and `site-mode` only.**
+- **`modAccess` moved to a router-level `use`; `adminOnly` on bot-activity deliberately did not.**
+  Moderation was already gated by a *prefix* mount (`adminRouter.use('/moderation', modAccess)`), so
+  `moderationRouter.use(modAccess)` is the exact equivalent (the PR 1 `users` case). Bot-activity's
+  gate was per-route, and keeping it per-route is what holds the per-route handler count — the one
+  number in `routes.guards.json` that would catch a dropped `adminOnly`, since `requireRole(...)`
+  returns an anonymous arrow and never shows up by name. **Rule for PRs 3–5: move a gate to router
+  level only where it was already a prefix mount; otherwise leave it on the route.**
+- **`modAccess` stays in the residual file** — the `/shard/*` in-game staff operations still use it
+  and do not move until PR 4. Its comment there was retargeted rather than deleted.
+
+### PR 3 — as landed
+
+`posts`, `uploads`, `wiki` and `pages` — 31 routes, leaving 33 in the residual file. The content tier,
+and the first split PR where no gate moved at all: all four capabilities are editor-tier, so the shared
+`staffOnly` in `admin/index.js` is their whole gate.
+
+| Router | Routes | Prefix | Extra gate |
+|---|---|---|---|
+| `posts.router.js` | 9 | `/admin/posts` | none — editor tier |
+| `uploads.router.js` | 1 | `/admin/uploads` | none — editor tier |
+| `wiki.router.js` | 14 | `/admin/wiki` | none — editor tier |
+| `pages.router.js` | 7 | `/admin/pages` | none — editor tier |
+| `admin.routes.js` (residual) | 33 | group root, mounted last | unchanged |
+
+All four gates zero-diff: `routes.manifest.json` (200 public + 2 internal), `routes.guards.json`,
+`swagger-output.json` (198 operations), and `docs/website/api-route-inventory.json` was already in
+sync. 434 server tests green.
+
+Notes:
+
+- **The residual 33 is exactly PR 4's list** — `shard` 16, `email` 6, `uo-link` 5, `settings` 2,
+  `discord-bot` 2, `dashboard` 1, `site-mode` 1. So `admin.routes.js` is deleted by PR 4, one PR
+  earlier than the sequencing list implies, and PR 5 touches only `public/*`, `player/*` and `auth/*`.
+- **A shared module was unavoidable here, and it is the first one in the split.** The multer config
+  (upload dir, mimetype→extension allowlist, 8 MB cap) was defined inline in `admin.routes.js` and used
+  by *two* routes that this PR puts in different files: `POST /posts/upload` (→ `{image_url}`) and
+  `POST /uploads` (→ `{url}`). It moved to `admin/imageUpload.js` rather than being duplicated —
+  duplicating a security allowlist is how the two copies drift. It stays in `admin/` deliberately:
+  `UPLOAD_DIR` is resolved `__dirname`-relative, so relocating the file would silently repoint the
+  upload directory. Guard freshness is unaffected — multer's middleware is named `multerMiddleware`
+  wherever it is constructed, so `routes.guards.json` did not move.
+- **`POST /uploads` keeps its `Admin · Posts` swagger tag**, which now disagrees with its filename. The
+  acceptance criterion is a byte-identical spec, so retagging is a real OpenAPI diff and does not
+  belong in a route-move PR. Same call as PR 1's `/shard/*` tag mismatch: fix tags in a PR that is
+  *about* tags.
+- **The wiki router is the first one with load-bearing intra-file route order.** `/categories` and
+  `/tags` are literal paths that must stay ahead of `/:slug`, or `GET /admin/wiki/categories` gets
+  dispatched as a page whose slug is "categories". **The manifest cannot catch this — it sorts its
+  entries, so a reordering is invisible in all three gates.** It was verified separately by
+  introspecting the built router stack and asserting the last literal layer precedes the first `/:slug`
+  layer. Any future PR moving `/:slug`-style routes needs the same explicit check.
+- **`/admin/pages` (CMS page builder) and `/admin/shard/pages` (in-game help-page queue) are unrelated
+  capabilities that read alike** — the latter stays with `shard` in PR 4. Same trap as PR 2's
+  `activity` / `dashboard` / `bot-activity` trio.
+
+### PR 4 — as landed
+
+`shard`, `uo-link`, `email`, `discord-bot`, `settings` and `dashboard`/`site-mode` — the whole residual
+33. **`admin.routes.js` is deleted**, so the admin group is fully split and every one of its 110 routes
+is declared in a capability router.
+
+| Router | Routes | Prefix | Extra gate |
+|---|---|---|---|
+| `shard.router.js` | 16 | `/admin/shard` | none on the 7 self-service routes; `modAccess` per route on the 9 staff ops |
+| `uoLink.router.js` | 5 | `/admin/uo-link` | `adminOnly` per route |
+| `email.router.js` | 6 | `/admin/email` | `adminOnly` per route |
+| `discordBot.router.js` | 2 | `/admin/discord-bot` | `adminOnly` per route |
+| `settings.router.js` | 2 | `/admin/settings` | `adminOnly` per route |
+| `dashboard.router.js` | 2 | **group root** (`/dashboard`, `/site-mode`) | `adminOnly` per route on `/site-mode` only |
+| ~~`admin.routes.js`~~ | — | deleted | — |
+
+16 + 5 + 6 + 2 + 2 + 2 = 33. All four gates zero-diff: `routes.manifest.json` (200 public + 2
+internal), `routes.guards.json`, `swagger-output.json` (198 operations), and
+`docs/website/api-route-inventory.json` was already in sync. 434 server tests green.
+
+Notes:
+
+- **`dashboard.router.js` is mounted at the group root, not a prefix — the one relaxation of the
+  "always mount at a prefix" rule, and it is deliberate.** `GET /dashboard` and `PUT /site-mode` own no
+  common path segment, so a prefix mount would mean two one-route files instead of the single file the
+  target tree calls for. It is safe **only** because the file declares no router-level middleware: a
+  bare `use(gate)` in a root-mounted router runs for every request passing through toward another
+  mount and would 403 an editor on an unrelated route (the PR 1 finding). The file says so in a
+  comment, because the next person to add a gate there is the one who needs to know.
+- **`/shard` is the first prefix where two tiers share one router**, and it is why prefix ownership
+  beats swagger-tag grouping. The 7 self-service routes (`link`, `accounts`, `roster/:account`,
+  `vendors/:account`, `char/:serial`, `sales`, `POST account`) are tagged `Admin · Account`, run with
+  no gate beyond the shared `staffOnly`, and are served by the very same `player/shard.controller`
+  handlers as `/player/shard` — staff are a superset of players, and the controller keys off
+  `req.user.id`. The 9 in-game ops are tagged `Admin · Shard` and carry `modAccess`. Splitting them by
+  tag would put two routers under one prefix for no gain; instead one router owns `/shard` and gates
+  per route. The tag mismatch stays, on the PR 1 and PR 3 precedent: retagging is a real spec diff and
+  belongs in a PR that is about tags.
+- **No gate moved to router level anywhere in this PR.** Every `adminOnly` in the residual file was
+  per-route, and `modAccess` on `/shard` must stay per-route because half that router must *not* have
+  it. This keeps the per-route handler count intact — the one number `routes.guards.json` can actually
+  check, since `requireRole(...)` returns an anonymous arrow.
+- **The `/:param` shadowing check was run again and is clean**, since the manifest sorts and therefore
+  cannot see declaration order. Introspecting the built stack, all 110 admin routes and all 59 literal
+  admin paths dispatch to their own layer — nothing is captured first by a `:param` sibling. The
+  near-misses worth naming: `GET /shard/pages` (help-page queue) sits alongside
+  `POST /shard/pages/:id/respond|close`, and `POST /shard/towncrier` alongside
+  `DELETE /uo-link/towncrier/:id` — different depths and methods, so neither collides.
+- **Deleting the file left dangling `see admin.routes.js` pointers**, which were repointed in the same
+  PR: `botActivity.controller.js` → `botActivity.router.js`, `moderation.controller.js` →
+  `moderation.router.js`, `announceJobs.logic.js`'s town-crier cap mirror → `admin/uoLink.router.js`,
+  and the "route paths sit on the line *after* `adminRouter.get(`" rationale in
+  `scripts/routeManifest.js`, `README.md` and `pr-checks.yml` was generalized (it was never about that
+  one file).
+- **`/admin/shard/pages` vs `/admin/pages` stayed separate**, as PR 3 flagged: the former is the
+  in-game help-page (support) queue and belongs to `shard`; the latter is the CMS page builder.
+
+### PR 5 — as landed
+
+`public`, `player` and the residual `auth` — 54 routes across three groups, the last split PR.
+`public.routes.js`, `player.routes.js` and `auth.routes.js` are all **deleted**, so every one of the
+200 routes in the manifest is now declared in a capability router and no monolithic route file
+remains anywhere in `router/v1/`.
+
+| Group | Router | Routes | Prefix | Extra gate |
+|---|---|---|---|---|
+| `public` | `posts.router.js` | 2 | `/public/posts` | none — `siteMode` per route |
+| | `wiki.router.js` | 4 | `/public/wiki` | none — `siteMode` per route |
+| | `pages.router.js` | 2 | `/public/pages` | none — `siteMode` per route except the preview |
+| | `shard.router.js` | 12 | `/public/shard` | none — never `siteMode` gated |
+| | `site.router.js` | 4 | **group root** (`/settings`, `/status`, `/version`, `/contact`) | none |
+| `player` | `account.router.js` | 8 | `/player/account` | none beyond the group gate |
+| | `shard.router.js` | 8 | `/player/shard` | none beyond the group gate |
+| | `appeals.router.js` | 4 | `/player/appeals` | none beyond the group gate |
+| `auth` | `login.router.js` | 2 | `/auth/login` | `loginGuards` per route |
+| | `register.router.js` | 1 | `/auth/register` | `loginGuards` + `registerLimiter` |
+| | `invite.router.js` | 2 | `/auth/invite` | `loginGuards` + `registerLimiter` on accept |
+| | `password.router.js` | 3 | `/auth/password` | per-route reset limiters |
+| | `session.router.js` | 2 | **group root** (`/logout`, `/me`) | per route |
+
+24 + 20 + 10 = 54. `auth/`'s other 32 routes (`me` 23, `mobile` 5, `sso` 4) were already in their own
+files and did not move. All four gates zero-diff: `routes.manifest.json` (200 public + 2 internal),
+`routes.guards.json`, `swagger-output.json` (198 operations), and `docs/website/api-route-inventory.json`
+was already in sync. 434 server tests green.
+
+Notes:
+
+- **Each group is now a directory with an `index.js`**, matching `admin/`: `public/index.js`,
+  `player/index.js`, `auth/index.js` own the group gate (where there is one) and the mount table and
+  declare no routes. `v1.router.js` requires the directories. The four tests that imported the
+  deleted entry files were repointed.
+- **Two of the three groups have no group gate, and that is the security-relevant fact about them.**
+  `player/index.js` carries `noindex, requireAuth` — authenticated, *any* role, because staff are a
+  superset of players. `public/index.js` and `auth/index.js` carry **nothing**, deliberately: the
+  public surface is anonymous by contract (logged-out SPA, Discord bot, and the Android
+  `ShardStreamClient` on `/public/shard/stream`, none of which send credentials), and `/auth` is where
+  an anonymous caller *becomes* authenticated. Both index files say so, because the obvious "hardening"
+  edit to either one is an outage.
+- **`GET /auth/me` has a mount-order dependency, and it is the one genuinely non-obvious thing in this
+  PR.** `authRouter.use('/me', meRouter)` matches the bare path `/me`, not just `/me/*` — so a request
+  to `GET /auth/me` runs `meRouter`'s (and `notifRouter`'s) `noindex, requireAuth`, matches no route
+  inside either, and falls through to its own handler. `session.router.js` must therefore stay mounted
+  **last**. Verified by the counterfactual rather than by reading the mount table: moving the mount to
+  the top of `auth/index.js` still answers `401`, but the response loses its `X-Robots-Tag` header. No
+  gate file and neither manifest can see that — only a header assertion can.
+- **Two root-mounted routers, on the PR 4 `dashboard.router.js` precedent.** `public/site.router.js`
+  (`/settings`, `/status`, `/version`, `/contact`) and `auth/session.router.js` (`/logout`, `/me`) hold
+  the routes that own no path segment. Both are safe at the root **only** because they declare no
+  router-level middleware — a bare `use(gate)` there runs for every request passing through toward
+  another mount. Both files say so.
+- **`loginGuards` is the PR's one shared module**, the counterpart to PR 3's `imageUpload.js`. The
+  `[backoffGuard, slowLogin, loginLimiter]` array was defined inline in `auth.routes.js` and spread by
+  four routes that this PR puts in three different files — plus a fifth, already-duplicated copy in
+  `sso.routes.js`. It moved to `auth/loginGuards.js` and `sso.routes.js` now imports it too, so there
+  is one definition rather than five: duplicating a throttling stack is how the copies drift, and the
+  copy that drifts is the one that stops throttling. It is exported `Object.freeze`d — it is
+  module-level shared state, and a router that pushed onto it would silently add middleware to every
+  other login surface. Guard freshness is unaffected: the same three named functions, so
+  `routes.guards.json` did not move.
+- **The `/:param` shadowing check was run again and is clean.** All 86 public/player/auth routes and
+  all 64 literal paths among them dispatch to their own layer. This was checked in *dispatch* order
+  against the built stack, since the manifest sorts and therefore cannot see declaration order. The
+  only ordering-sensitive pair is `GET /public/wiki/{categories,tags}` ahead of `/public/wiki/:slug` —
+  the public twin of the `admin/wiki.router.js` trap PR 3 found, and `wiki.router.js` says so. The
+  `/public/pages` preview route also stays ahead of `/:slug`, though at a different depth.
+- **Filename deviations from the target tree, both for prefix agreement.** The tree named the public
+  posts router `news.router.js`; it is `posts.router.js`, matching the `/posts` prefix it owns and its
+  `admin/posts.router.js` sibling. The tree also implied `sso.router.js` / `mobile.router.js`; those
+  files already exist as `sso.routes.js` / `mobile.routes.js` and were not renamed — they did not move
+  in this PR, and churning their names would add diff noise to a PR whose value is being reviewable.
+- **`auth/session.router.js` is a deviation the target tree did not anticipate**, the same shape as
+  PR 2's `activity.router.js`. The tree listed `login.router.js` but had nowhere to put `/logout` and
+  `GET /me`, which own no prefix. Folding them into `login.router.js` would have forced *that* router
+  to the group root and given up prefix ownership for the four login routes; a separate root-mounted
+  singleton file keeps `/login` a real prefix mount.
+- **Tag mismatches were left alone again**, on the PR 1 / PR 3 / PR 4 precedent: the acceptance
+  criterion is a byte-identical spec, so retagging belongs in a PR that is about tags.
+- **`public.controller.js` was not split.** Unlike the admin controllers, it is still one file serving
+  settings/status/version/contact *and* posts/wiki/pages. The plan's rule is that these PRs re-wire
+  routes, not logic — splitting a controller is a separate change with a separate risk profile, and
+  bundling it would have cost this PR its "pure mechanical refactor" acceptance criteria.
+
+### The swagger path-normalization prerequisite (landed before PR 1)
+
+swagger-autogen builds a path by string-concatenating the mount prefix with the route argument, so a
+capability router mounted at `/users` whose collection route is `router.get('/')` documents as
+`/api/v1/admin/users/` — advertising a URL no client calls while dropping the one the SPA, the Android
+app and the Discord bot all do. Express is indifferent; the published spec is not. It also emits path
+keys in *router-traversal order*, so moving a route between files rewrote most of the ~5k-line
+committed artifact even when the API was provably unchanged — burying the one line a reviewer needs.
+
+Both are fixed once in `server/swagger/swagger.js`, which post-processes the generator's output to
+strip trailing slashes and sort path keys (throwing on a collision rather than silently dropping an
+operation). It shipped as its own PR ahead of PR 1, verified inert by the regenerated spec being
+byte-for-byte the sorted form of the previously committed one — 198 operations, none added or removed.
+`#swagger.path` was rejected as the fix: it bypasses the mount prefix, so every route would hardcode
+its absolute path in a comment that silently lies the moment a mount moves.
+
+**Consequence for PRs 2–5: the swagger diff is now a signal.** With sorting in place, a pure route
+move produces *no* spec diff at all, so any diff there means an annotation actually changed. Treat
+`swagger-output.json`, `routes.manifest.json` and `routes.guards.json` as three zero-diff gates.
+
+### PR 0 — the route manifest (prerequisite of the first split PR) — **landed**
+
+> **Status: shipped.** `server/scripts/routeManifest.js` + `npm run routes:manifest`,
+> `server/routes.manifest.json` (199 public + 2 internal), `server/routes.guards.json`,
+> `server/test/routeManifest.test.js`, and a `routes:manifest -- --check` step in
+> `.gitea/workflows/pr-checks.yml`. No router file moved. **The generator reproduced
+> `api-route-inventory.json` byte-for-byte on first run**, so the freeze is in effect and the
+> committed baseline is confirmed accurate rather than merely asserted.
+>
+> Two deviations from the design below, both deliberate:
+>
+> - **The unauthenticated-status snapshot was tried and dropped**, exactly as this section allowed.
+>   Firing unauthenticated GETs at every manifest path against the dead-port mariadb pool the tests
+>   use does not fail fast — the pool sits on its acquire timeout, and a partial sweep had not
+>   finished after two minutes. A flaky two-minute gate is worse than none. What replaced it is
+>   cheap and deterministic: the test suite asserts from the introspected stack that every
+>   `/api/v1/admin/**` and `/api/v1/player/**` route still carries `requireAuth`.
+> - **`routes.guards.json` is committed and staleness-checked**, though a diff in it is explicitly
+>   *not* a contract change. Left ungenerated it would rot into a misleading review aid within a
+>   release. The gate is on freshness; the meaning of a guards diff is still "read this", not
+>   "justify this". The generator drops app-level plumbing (helmet, morgan, the JSON parser, the bot
+>   guard) since it applies uniformly to all 199 routes and would bury the per-route gates.
+
+
+
+"Every URL is unchanged" must be *proved by a diff*, not asserted in review. PR 0 lands the tool that
+proves it, with no router file moved.
+
+- **Generator:** `server/scripts/routeManifest.js`, wired as `npm run routes:manifest`. It requires
+  `src/app.js` (which exports the app and neither listens nor connects to the DB — `server.js` owns
+  those), walks `app._router.stack` recursively through mounted routers, reconstructs each full path
+  from the layer regexps, and writes a **sorted** array of
+  `{ "method": "GET", "path": "/api/v1/admin/users/:id" }` to `server/routes.manifest.json`.
+  `internalApp.js` is walked into a separate `internal` section so the unpublished port is inventoried
+  without being confused for public surface.
+- **Scope it to the API surface, or it won't be deterministic.** Three mounts are *filesystem*
+  conditional: the SPA catch-all `GET *` (only when `client/dist/index.html` exists), the `/brand`
+  static mount, and `/api/docs*` (only when `swagger-output.json` is present — it is committed, so it
+  is stable). The manifest keeps only `/api/**`, `/.well-known/**`, and the internal app's routes, so
+  it does not change depending on whether CI built the client. Static mounts are not API contract.
+- **The baseline already exists:** [`api-route-inventory.json`](./api-route-inventory.json) in this
+  directory is the frozen surface — **199 API routes** (110 of them `/api/v1/admin`) plus 2
+  internal at the time PR 0 was written. PR 0's generator must **reproduce this file byte-for-byte**;
+  that is PR 0's own acceptance test, and it means the freeze is already in effect before the first
+  router moves. *(It did, on first run. The file has since moved to **200** — the CSP report-only PR
+  added `POST /api/csp-report`, the first deliberate, reviewed manifest diff.)*
+- **Runtime introspection, not source parsing.** It is authoritative about mounts, and the route paths
+  in `admin.routes.js` sit on the line *after* `adminRouter.get(`, which defeats naive greps.
+- **Not `swagger-output.json`.** That is annotation-derived (only annotated routes appear) and churns
+  for unrelated reasons; it documents intent, the manifest records reality.
+- **Frozen key: method + path only.** That is exactly the contract being preserved. Handler names are
+  useless as a guard check here — `requireRole(...)` returns an anonymous arrow, and router-level gates
+  like `adminRouter.use(noindex, isLoggedIn, staffOnly)` never appear in a route's own stack.
+- **Guard coverage, separately.** The generator also emits a non-gated review aid: per route, the
+  handler count plus any *named* middleware collected along the mount chain. If a stable behavioral
+  check proves cheap, prefer it — a test that fires an **unauthenticated** request at every manifest
+  path and snapshots the status code catches a dropped `adminOnly` (403 → 200) in a way names cannot.
+  Try it in PR 0; if DB-touching public routes make it slow or noisy against the dead-port pool the
+  tests use, drop it rather than ship a flaky gate.
+- **CI:** `.gitea/workflows/pr-checks.yml` runs `npm run routes:manifest` and
+  `git diff --exit-code server/routes.manifest.json`. A PR that moves a URL fails unless it
+  deliberately commits the new manifest — which puts the URL change in front of a reviewer instead of
+  letting it pass silently.
+- **Published copy:** `docs/website/api-route-inventory.json` mirrors `server/routes.manifest.json` and
+  is refreshed in each split PR's mandatory docs edit. The markdown table above is orientation for a
+  human reader; **the manifest is the authoritative freeze.**
+
+---
+
+## Sequencing & PR breakdown
+
+CSP and the split are independent; the only hard ordering is PR 0 before the first split PR.
+
+**Resequenced during implementation: PR 0 ships first, before the CSP pair.** The CSP report-only PR
+has to stand up a violation collector (`POST /api/csp-report`) for `report-to` to point at — which is
+a new URL under `/api/**`. Landing it first would mean PR 0's generator emitting 200 routes against a
+199-route committed baseline, so PR 0 could no longer prove itself by reproducing
+`api-route-inventory.json` byte-for-byte. With PR 0 first, the collector shows up as a reviewed,
+deliberate `+1` in the manifest — which is exactly the mechanism working as designed.
+
+1. **PR 0 — route manifest.** Generator + CI check + committed baseline of today's surface. No routers moved. ✅ landed
+2. **PR — CSP report-only.** Tightened policy behind `Content-Security-Policy-Report-Only` + `report-to`,
+   plus the report collector (manifest `+1` — the first deliberate, reviewed manifest diff). ✅ landed
+3. **PR — CSP enforce.** One release later, assuming a clean violation report. **Blocked on real soak
+   data**, not on code: watch the `csp` log tag for `frame-ancestors` reports across one release before
+   flipping. Also decide there whether `/api/csp-report` is retired with the report-only twin or kept
+   as a `report-to` group on the enforced policy.
+4. **PR 1 — admin:** `users`, `account`, `invites`, `auth` (providers). ✅ landed
+5. **PR 2 — admin:** `moderation`, `bot-activity`, `activity`. ✅ landed
+6. **PR 3 — admin (content):** `posts`, `pages`, `wiki`, `uploads`. ✅ landed
+7. **PR 4 — admin (ops/config):** `shard`, `uo-link`, `email`, `discord-bot`, `settings`, `site-mode`,
+   `dashboard`. (`activity` went with PR 2 — see § PR 2 — as landed.) **This is the whole residual
+   file** — `admin.routes.js` is deleted here, not by PR 5. ✅ landed
+8. **PR 5 — `public/*` + `player/*`** (and the residual `auth/*` grouping). ✅ landed — **the domain
+   split is complete.** The only remaining item in this plan is the CSP enforce PR (3), which is
+   blocked on soak data, not on code.
+
+Each PR: **zero-line diff in `routes.manifest.json`**, server tests green
+(`cd website/server && npm test`), Swagger regenerated, matching `docs/` edit, Conventional Commit,
+AI-disclosure trailer, branch from a freshly-pulled `main`.
+
+---
+
+## Cross-component blast radius
+
+Three independent clients consume the site's HTTP/SSE API, two of them in separate repos on separate
+release cadences. **With the auth merge and the version bump both gone, the blast radius is empty** —
+no client's URLs or authentication change at all.
+
+| Consumer | Repo (cadence) | Pinning | Impact under this plan |
+|---|---|---|---|
+| Browser SPA | `website/client` (lockstep) | `BASE = /api/v1` in `client/src/api/client.js` | **None.** Same URLs, same cookie session. |
+| Android app | `android-app` (app-store cadence, un-updatable installs in the wild) | 69 hardcoded `api/v1/…` paths; SSE path in `ShardStreamClient.kt`; SSO in `SsoAuthManager.kt` | **None.** No repoint, no release required. |
+| Discord bot | `website/bot` (separate deploy, env-configured) | `SITE_PUBLIC_URL` env → `/api/v1/public` | **None.** Anonymous public reads on unchanged paths. |
+
+Standing constraints, unchanged:
+
+- **The public SSE stream stays anonymous.** Consumed by logged-out browser visitors *and* the Android
+  `ShardStreamClient`, neither of which sends an `Authorization` header. Adding `requireAuth` blacks
+  out the public live boards on web and mobile. The single most likely regression in a careless
+  refactor is reflexively wrapping *both* shard streams in auth.
+- **The admin SSE stream keeps its current cookie-based gating** (`isLoggedIn`, `EventSource` +
+  `withCredentials`) — the rewrite that would have changed this went out with the auth merge.
+- **The public/admin allowlist split is a security boundary**, not an implementation detail. Preserve
+  it verbatim in `utils/shardBroadcast.js` / `utils/shardIngest.js` as routes move.
+- **SSO / email-connect transaction cookies are load-bearing for web *and* native.** The Android SSO
+  flow opens a Custom Tab to the website's `/auth/…/sso/start` and rides the same server-side redirect
+  transaction and the same tx cookies. Nothing in this plan touches them; don't let a future "cookies
+  go away" push delete them.
+- **`link/` is out of scope.** The sidecar contract (`uoLinkConfig`, `utils/uoLinkClient.js`,
+  `utils/shardIngest.js`, `X-UOLink-Version`) is a separate versioning axis. `PROTOCOL_VERSION` does
+  **not** bump for this work.
+
+---
+
+## Appendix: mapping from the previous plan
+
+| Previous | Now |
+|---|---|
+| Phase 0 — `/api/mobile` facade + app-version floor | **Deferred.** See § Deferred: the `/api/mobile` facade |
+| Phase 1 — auth merge | **Removed.** See § Why the auth merge is out and § Deferred: the auth merge |
+| Phase 1b — CSP hardening (shipped with the auth merge) | **Phase 1**, standalone; report-only-first ordering fixed |
+| Phase 2 — domain split under `router/v2/` | **Phase 2**, in place under `router/v1/`; now the primary driver |
+| PR 1 — `/api/v2` scaffold ([API_V2_SKELETON.md](./API_V2_SKELETON.md)) | **Superseded**, kept as the recipe if a versioned API is ever forced |
+| PR final — retire v1 | **Not applicable** — v1 is never replaced |

website/API_V2_SKELETON.md

@@ -0,0 +1,131 @@
+# Website API v2 — `/api/v2` Skeleton (PR 1)
+
+> ## ⚠ Superseded — not scheduled
+>
+> The router domain split is being done **in place**, with every URL byte-identical, so there is no
+> parallel version to stand up and this scaffold will not be built. See
+> [API_V2_PLAN.md](./API_V2_PLAN.md) § Why there is no `/api/v2`.
+>
+> The file is kept, unedited below, as the concrete recipe **if** a real contract break ever forces a
+> versioned API. Nothing here describes current or planned work.
+
+Companion to [API_V2_PLAN.md](./API_V2_PLAN.md) — this is the concrete scaffold for **PR 1** in that
+plan's sequencing. It stands up `/api/v2` **empty but wired**, next to a frozen `/api/v1`, with **no
+behavior change**. Endpoints are filled in by the later PRs (auth merge, then the domain split).
+
+## Scope
+
+- Create the `router/v2/` tree of empty, domain-named routers.
+- Mount `/v2` alongside `/v1` in `api.router.js`.
+- Add a single trivial `GET /api/v2/version` so the mount is testable end-to-end.
+- **Out of scope:** any real endpoint, any auth change, any controller edit. Those are PR 2+.
+
+## File tree to create
+
+```
+website/server/src/router/v2/
+  v2.router.js              # mounts the domain sub-routers; adds GET /version
+  admin/
+    index.js                # mounts the admin capability routers under /admin
+    dashboard.router.js     users.router.js       moderation.router.js
+    content.router.js       wiki.router.js         shard.router.js
+    settings.router.js      invites.router.js      bot-activity.router.js
+  auth/
+    index.js                login.router.js  sso.router.js  totp.router.js  session.router.js
+  public/
+    index.js                news.router.js   wiki.router.js  page.router.js  shard.router.js
+  player/
+    index.js                profile.router.js  appeals.router.js  shard.router.js
+```
+
+`internal/` is **not** part of v2's public tree — the internal routes stay on the separate,
+unpublished port (`internalApp.js`), exactly as in v1. See `API_V2_PLAN.md` § Phase 2.
+
+## Wiring
+
+`api.router.js` gains the v2 mount next to v1:
+
+```js
+const v1Router = require('./v1/v1.router')
+const v2Router = require('./v2/v2.router')
+
+apiRouter.use('/v1', v1Router)
+apiRouter.use('/v2', v2Router)   // NEW — parallel version, migrate off v1 route-by-route
+```
+
+`v2.router.js` mounts each domain group and exposes the version ping:
+
+```js
+const express = require('express')
+const v2Router = express.Router()
+
+const adminRouter = require('./admin')
+const authRouter = require('./auth')
+const publicRouter = require('./public')
+const playerRouter = require('./player')
+
+// Cheap liveness/mount check so the parallel version is testable before any
+// real endpoint exists. Returns the API major version, nothing sensitive.
+v2Router.get('/version', (req, res) => res.json({ version: 2 }))
+
+v2Router.use('/auth', authRouter)
+v2Router.use('/public', publicRouter)
+v2Router.use('/admin', adminRouter)
+v2Router.use('/player', playerRouter)
+// NOTE: /internal is intentionally NOT mounted here — same reason as v1.
+
+module.exports = v2Router
+```
+
+Each capability router is an empty stub at this stage — a router that mounts cleanly and adds no
+routes yet, so PR 2+ only has to add handlers, never re-wire:
+
+```js
+// router/v2/admin/dashboard.router.js
+const express = require('express')
+const router = express.Router()
+
+// Routes added in the admin domain-split PR (see API_V2_PLAN.md § Phase 2).
+
+module.exports = router
+```
+
+Each `index.js` mounts its group's capability routers under the URL that names them, e.g.:
+
+```js
+// router/v2/admin/index.js
+const express = require('express')
+const admin = express.Router()
+
+admin.use('/dashboard', require('./dashboard.router'))
+admin.use('/users', require('./users.router'))
+admin.use('/moderation', require('./moderation.router'))
+admin.use('/content', require('./content.router'))
+admin.use('/wiki', require('./wiki.router'))
+admin.use('/shard', require('./shard.router'))
+admin.use('/settings', require('./settings.router'))
+admin.use('/invites', require('./invites.router'))
+admin.use('/bot-activity', require('./bot-activity.router'))
+
+module.exports = admin
+```
+
+## Acceptance criteria
+
+- Server boots with no error; every sub-router mounts.
+- `GET /api/v2/version` → `200 { "version": 2 }`.
+- `GET /api/v1/**` behavior is **byte-for-byte unchanged** — v1 is untouched.
+- Existing server tests stay green (`cd website/server && npm test`).
+- A new test asserts the `/api/v2/version` mount (smallest possible coverage of the wiring).
+
+## Docs / spec
+
+- Swagger regeneration is deferred until v2 has real routes (PR 2) — a lone `/version` ping doesn't
+  need an annotation. When PR 2 lands, add `#swagger.*` to the new routes and run `npm run swagger`.
+- No `BACKEND_DESIGN.md` change here beyond noting the parallel `/api/v2` mount exists; the
+  route-map/security-contract edits land with the PRs that add real endpoints.
+
+## Next
+
+PR 2 fills the `auth/` routers with the bearer access + refresh flow and drops the session cookie —
+see [API_V2_PLAN.md](./API_V2_PLAN.md) § Phase 1.

website/ARCHITECTURE.md

@@ -0,0 +1,120 @@
+# Website — Architecture
+
+How the pieces of `RunicGateway/website` fit together. The React SPA and the native mobile app
+talk to one Express backend (`router → controller → model → db`), which persists to MariaDB and
+bridges to the live game world **only** through the **uo-link** sidecar. The ServUO shard itself is
+never internet-facing — it dials out to the sidecar over loopback, and only the sidecar is exposed.
+
+This is the canonical copy of the diagram; the same diagram is embedded in the website's
+[`README.md`](https://gitea.whitlocktech.com/RunicGateway/website/src/branch/main/README.md#architecture).
+See [BACKEND_DESIGN.md](BACKEND_DESIGN.md) for the full API / schema / security contract, and
+[`docs/link/`](../link/) for the wire protocol between the sidecar and the shard.
+
+```mermaid
+flowchart TB
+    %% ---------- Clients ----------
+    subgraph clients["Clients"]
+        browser["Browser<br/>React + Vite SPA<br/>(public · wiki · admin)"]
+        mobile["Native mobile app<br/>(bearer tokens)"]
+    end
+
+    idp["SSO providers<br/>Google · Discord · custom OIDC"]
+    discord["Discord"]
+
+    %% ---------- Website (one repo) ----------
+    subgraph website["website/ &nbsp;— Node app (one repo)"]
+        direction TB
+
+        subgraph backend["server/ — Express backend"]
+            direction TB
+            mw["Middleware<br/>helmet · siteMode · noindex<br/>rateLimit · loginProtection · botScore · validate"]
+            router["Router /api/v1<br/>auth (web · mobile · sso) · public · admin"]
+            ctrl["Controllers"]
+            auth["Session layer (auth/)<br/>sessionService · JWT/cookie · bearer · SSO+PKCE"]
+            model["Models (.model + .db)<br/>raw parameterized SQL — no ORM"]
+            sse["SSE fan-out<br/>public stream (allowlist) · admin stream (sensitive)"]
+
+            subgraph shardutil["Shard integration (utils/)"]
+                ingest["shardIngest.js<br/>WS ingest dispatcher"]
+                restcli["uoLinkClient.js<br/>REST client (never throws)"]
+            end
+
+            secret["secretBox.js<br/>AES-256-GCM secrets at rest"]
+        end
+
+        bot["bot/<br/>Discord bot"]
+    end
+
+    db[("MariaDB<br/>users · posts · wiki · settings · activity<br/>mobileSessions · authProviders · userIdentities<br/>uoLinkConfig · shard_online/economy/houses/events")]
+
+    %% ---------- Shard side ----------
+    subgraph shardside["Game shard (never internet-facing)"]
+        direction TB
+        sidecar["uo-link sidecar<br/>(Rust) — the only bridge exposed"]
+        servuo["ServUO shard<br/>(C# plugin)"]
+    end
+
+    %% ---------- Edges ----------
+    browser <-->|"same-origin JSON + SSE (cookie)"| mw
+    mobile -->|"REST (bearer access/refresh)"| mw
+    browser -.->|"OAuth redirect + PKCE"| idp
+    auth -.->|"token exchange"| idp
+
+    mw --> router --> ctrl
+    ctrl --> auth
+    ctrl --> model
+    ctrl --> restcli
+    ctrl --> sse
+    auth --> model
+    model <--> db
+    auth -. reads/writes secrets .-> secret
+    restcli -. reads config/token .-> secret
+    ingest --> model
+    ingest --> sse
+    sse -->|"live events"| browser
+    bot -->|"messages"| discord
+    bot <--> db
+
+    restcli -->|"REST: /char /roster /economy /history · /link/confirm · /towncrier"| sidecar
+    sidecar -->|"WebSocket live event feed (bearer + X-UOLink-Version)"| ingest
+    servuo -->|"loopback TCP 127.0.0.1:7788<br/>newline-delimited JSON (shard dials out)"| sidecar
+
+    %% ---------- Styling ----------
+    classDef ext fill:#2d2233,stroke:#7a5c94,color:#e8dff0;
+    classDef store fill:#1f2d2a,stroke:#4c8c7d,color:#dff0ea;
+    classDef bridge fill:#2d2620,stroke:#94764c,color:#f0e6d8;
+    class idp,discord ext;
+    class db store;
+    class sidecar,servuo bridge;
+```
+
+## Notes on the diagram
+
+- **One backend, layered.** Every request flows `middleware → router → controller → model → db`.
+  Web browsers authenticate with an httpOnly JWT cookie; the native app uses short-lived bearer
+  access tokens plus rotated, hashed, revocable refresh tokens; SSO (Google/Discord/OIDC) is
+  link-only and PKCE-guarded. All three surfaces resolve to the *same* session model via the session
+  layer, and admin routes are re-validated against the DB on every request.
+- **The shard is never reachable.** The ServUO shard *dials out* over loopback TCP `127.0.0.1:7788`
+  (newline-delimited JSON) to the uo-link sidecar; only the sidecar is exposed, and only the backend
+  talks to it. Every backend→sidecar call carries `Authorization: Bearer <token>` and an
+  `X-UOLink-Version` header (a protocol mismatch fails fast with `409`). The REST client
+  (`uoLinkClient.js`) never throws — every call returns `{ ok, data, status }` — so the site degrades
+  gracefully when the shard is down. That guarantee covers **reading the config too**: resolving the
+  admin-managed config decrypts the stored auth token, which throws when the ciphertext can't be
+  authenticated (`SECRET_ENC_KEY` rotated, or a DB dump restored under a different key). This is
+  handled inside the client and reported as `{ ok: false, status: 0, error: 'uo-link config
+  unreadable' }` plus a distinct `ERROR`-level log, so a wrong key degrades the shard surface to
+  "unavailable" instead of 500ing it — and `GET /admin/uo-link/config` keeps working, which is the
+  screen an admin needs to re-enter the token and recover.
+- **Two ways in from the sidecar.** Live game events arrive over an outbound **WebSocket** and are
+  routed by the `shardIngest.js` dispatcher (state-changing kinds update `shard_*` tables, notable
+  kinds append to `shard_events`, high-frequency kinds only update state). Point-in-time reads and
+  commands go over **REST** through `uoLinkClient.js`.
+- **Sensitive events stay private.** Ingested events fan out to browsers over two **SSE** channels —
+  a public allowlist stream and an admin-only stream that additionally carries staff audit, cheat
+  detection, and login-attempt events. The allowlist split is a security boundary; sensitive kinds
+  can never leak onto the public channel.
+- **Secrets at rest.** OAuth client secrets, the uo-link token, and the Gmail refresh token are
+  AES-256-GCM encrypted via `secretBox.js` (keyed by `SECRET_ENC_KEY`). The uo-link token is
+  write-only in the API — never returned to any client.

website/BACKEND_DESIGN.md

@@ -29,6 +29,24 @@ Public contact email: **UOMysticmoon@gmail.com**
 
 Skeleton from the spec, with a small number of justified additions marked **(+)**.
 
+> **Complete.** The monolithic route files (`admin.routes.js` especially, originally 1552 lines /
+> 110 routes) have been split into one router file per business capability — **in place, with every
+> URL unchanged**. See [API_V2_PLAN.md](./API_V2_PLAN.md) § Phase 2.
+>
+> `users`, `account`, `invites`, `auth/providers` (PR 1, 28 routes), `moderation`, `bot-activity`,
+> `activity` (PR 2, 18 routes), `posts`, `uploads`, `wiki`, `pages` (PR 3, 31 routes) and `shard`,
+> `uo-link`, `email`, `discord-bot`, `settings`, `dashboard`/`site-mode` (PR 4, 33 routes) each live
+> in their own router under `admin/`, behind `admin/index.js`. PR 5 did the same for `public/` (24),
+> `player/` (20) and the residual `auth/` (10). **`admin.routes.js`, `public.routes.js`,
+> `player.routes.js` and `auth.routes.js` are all deleted**; each group is now a directory whose
+> `index.js` owns the group gate and the mount table and declares no routes of its own.
+>
+> "Every URL unchanged" is enforced mechanically, not by review: `server/scripts/routeManifest.js`
+> (`npm run routes:manifest`) walks the live Express stack and writes the sorted
+> `{ method, path }` freeze to `server/routes.manifest.json`, mirrored here as
+> [api-route-inventory.json](./api-route-inventory.json). PR checks regenerate it and fail on any
+> diff, so a split PR that moves a URL cannot merge silently. See § 4.0.
+
 ```
 server/
   .env.example
@@ -42,10 +60,108 @@ server/
     router/
       api.router.js             mounts /v1
       v1/
-        v1.router.js            mounts /auth /public /admin
-        auth/    auth.routes.js    + auth.controller.js
-        public/  public.routes.js  + public.controller.js
-        admin/   admin.routes.js   + admin.controller.js
+        v1.router.js            mounts /auth /public /admin /player
+        auth/    index.js          mounts the routers below; no group gate — /auth
+                                   is where an anonymous caller becomes
+                                   authenticated, so the authenticated parts gate
+                                   themselves. Mount order is load-bearing (see
+                                   session.router.js)
+                 login.router.js        (2)  /auth/login + /login/totp — shared
+                                             loginGuards stack
+                 register.router.js     (1)  /auth/register — honours the
+                                             player_registration setting
+                 invite.router.js       (2)  /auth/invite/:token[/accept] — the
+                                             token is its own authority, so it
+                                             bypasses player_registration
+                 password.router.js     (3)  /auth/password/forgot + reset/:token
+                 session.router.js      (2)  POST /logout and GET /me — the two
+                                             singletons owning no path segment, so
+                                             mounted at the group root, LAST: the
+                                             /me sub-routers below also match the
+                                             bare /me and supply its noindex header
+                 me.routes.js          (23)  /auth/me/account*, sessions, trusted
+                                             devices — router-level requireAuth
+                 notifications.routes.js (3) /auth/me/devices*, notifications/*
+                 mobile.routes.js +          /auth/mobile/* — native bearer login
+                 mobileSso.routes.js    (5)
+                 sso.routes.js          (4)  mounted PATHLESS: owns two prefixes,
+                                             /auth/providers and /auth/sso/*
+                 loginGuards.js              shared backoff/slow/limiter stack for
+                                             every credential-guessing surface
+                                             (not a router)
+                 auth.controller.js + invite/passwordReset/sso/mobile controllers
+        public/  index.js          mounts the routers below; **no group gate** —
+                                   this surface is anonymous by design (SPA
+                                   logged-out, Discord bot, Android ShardStream)
+                 posts.router.js        (2)  /public/posts/:category[/:idOrSlug]
+                 wiki.router.js         (4)  /public/wiki — /categories and /tags
+                                             MUST precede /:slug
+                 pages.router.js        (2)  /public/pages — the draft-preview
+                                             route precedes /:slug and is
+                                             deliberately not site-mode gated
+                 shard.router.js       (14)  /public/shard/* incl. the anonymous
+                                             SSE stream; never site-mode gated
+                 atlas.router.js        (6)  /public/atlas/* — the spawn atlas.
+                                             NOT under /shard: nothing here
+                                             touches the sidecar, and unlike
+                                             /shard it IS site-mode gated
+                 site.router.js         (4)  /settings /status /version /contact —
+                                             the group-root singletons; declares no
+                                             router-level middleware
+                 public.controller.js + shard.controller.js
+        player/  index.js          owns the shared `noindex, requireAuth` gate
+                                   (authenticated, ANY role — staff are a superset
+                                   of players) and the mount table
+                 account.router.js      (8)  /player/account — credentials, TOTP,
+                                             linked identities; handlers shared
+                                             with /admin/account and /auth/me
+                 shard.router.js        (8)  /player/shard — linking + own roster,
+                                             vendors, chars, sales, houses
+                 appeals.router.js      (4)  /player/appeals
+                 shard.controller.js + appeals.controller.js
+        admin/   index.js          mounts the capability routers below at their
+                                   own prefixes; owns the shared
+                                   `noindex, isLoggedIn, staffOnly` gate and
+                                   declares no routes itself
+                 account.router.js       (6)  /admin/account  — self-service, no adminOnly
+                 users.router.js        (15)  /admin/users    — adminOnly
+                 invites.router.js       (3)  /admin/invites  — adminOnly
+                 authProviders.router.js (4)  /admin/auth     — adminOnly
+                 moderation.router.js   (15)  /admin/moderation    — modAccess
+                                              (admin+moderator) at router level
+                 botActivity.router.js   (2)  /admin/bot-activity  — adminOnly
+                 activity.router.js      (1)  /admin/activity      — staff-wide
+                                              audit log, no extra gate
+                 posts.router.js         (9)  /admin/posts    — editor tier, no
+                                              gate beyond staffOnly
+                 uploads.router.js       (1)  /admin/uploads  — rich-text editor
+                                              image upload
+                 wiki.router.js         (14)  /admin/wiki     — pages, revisions,
+                                              categories, tags
+                 pages.router.js         (7)  /admin/pages    — CMS page builder
+                 imageUpload.js               shared multer config for the two
+                                              upload routes above (not a router)
+                 shard.router.js        (16)  /admin/shard    — 7 self-service
+                                              account-linking routes (no extra
+                                              gate, handlers shared with
+                                              /player/shard) + 9 in-game staff
+                                              ops on modAccess, per route
+                 uoLink.router.js        (5)  /admin/uo-link  — sidecar config,
+                                              town crier, admin SSE — adminOnly
+                 email.router.js         (6)  /admin/email    — Gmail OAuth2
+                                              delivery — adminOnly
+                 discordBot.router.js    (2)  /admin/discord-bot — adminOnly
+                 settings.router.js      (2)  /admin/settings — adminOnly
+                 dashboard.router.js     (2)  GET /dashboard (staff-wide) and
+                                              PUT /site-mode (adminOnly) — the
+                                              two singletons owning no path
+                                              segment, so mounted at the group
+                                              root; declares no router-level
+                                              middleware, which is what makes a
+                                              root mount safe
+                 admin.controller.js + the per-capability controllers
+                                   (already domain-split; the split PRs re-wire
+                                   routes, not logic)
     model/
       users/     users.model.js    + users.db.js
       posts/     posts.model.js     + posts.db.js     (news/five-on-friday/newsletter/screenshots)
@@ -142,6 +258,336 @@ 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 |
+| trust_device | TINYINT(1) NOT NULL DEFAULT 0 | user ticked "trust this device" on the Custom Tab TOTP form. A **boolean only** — it tells `/exchange` to mint the app's own trust token; the token never rests here (only its sha256 reaches `trusted_devices`) |
+| 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.
+
+### trusted_devices  — MFA "Trust this device"
+
+Lets a browser/app **skip the TOTP step** at login (never the password) for 30 days. Pattern-identical
+to `mobile_refresh_tokens`: the opaque trust token lives client-side (the `rg_trust` httpOnly cookie on
+web, `X-Trust-Token` / EncryptedSharedPreferences on native) and only its **sha256** hash is stored
+(`token_hash CHAR(64) UNIQUE`) — sha256, not bcrypt, because a 256-bit random token is looked up **by
+its hash** via the unique index (a per-row salt would break that). Columns mirror the mobile table
+(`platform`, `device_name`, `device_hash`, `user_agent`, `created_at`, `last_used_at`, `expires_at`,
+`revoked_at`). Capped at 10 rows/user **in application code — no silent pruning** (an over-cap trust is
+refused so the client can prompt the user to revoke one first). Consulted only at the login/password
+step, never at token refresh, and revoked wholesale on untrust / password change / password reset /
+TOTP disable. See `docs/website/TRUSTED_DEVICES_MFA.md`.
+
+### recovery_codes  — single-use MFA backup codes
+
+Generated at TOTP enrollment (10 at a time, shown to the user **once**) so a user who loses their
+authenticator can complete login without an admin reset. `code_hash VARCHAR(72)` is a **bcrypt** hash
+(not sha256): a recovery code is a human-typed, lower-entropy fallback credential — the closest
+analogue to a password — and there is no hash-lookup constraint (verification fetches the user's ≤10
+unused rows and `bcrypt.compare`s each, like password verification). `used_at` is the single-use
+marker. Cleared wholesale on TOTP disable / password change / password reset.
+
+### shard_ruleset  — the shard's published ruleset (Protocol 3.0)
+
+Singleton row (`id = 1`, CHECK-constrained) holding the latest `world.ruleset` frame: `rev`,
+`expansion`, `payload` JSON (the whole frame), `t`, `updated_at`. The shard re-emits the complete
+ruleset on every sidecar connect, so this is an **overwrite, not an append** — and the kind is
+deliberately **not** in `LOGGED_KINDS`, since logging it would put a duplicate row in `shard_events`
+on every reconnect while `server.hello` already marks each of those.
+
+The frame is stored whole rather than normalized into columns: it is a flat description of server
+config that is read as one page, so splitting it up would mean a schema change every time the shard
+grows a new block. `rev` (the shard's FNV-1a of the body) and `expansion` are hoisted only because
+they are cheap to display — the same payload-plus-hoisted-columns shape `shard_champs` uses.
+
+**No row means the shard has never published one** (an older plugin, or `Bridge.RulesetEnabled=false`),
+served as `null` rather than `{}`: "not published yet" and "published, everything off" are different
+answers and the page renders them differently.
+
+### shard_points_boards  — points / loyalty leaderboards (Protocol 3.0)
+
+One row per point system, keyed by the shard's own `PointsType` name (`QueensLoyalty`,
+`CleanUpBritannia`, …). The shard carries ~25 of these, each a standing players build over months.
+Columns: `system` (PK), `name`, `name_cliloc`, `max_points`, `players`, `show_on_gump`, `payload` JSON
+(the whole `points.board` frame), `t`, `updated_at`.
+
+**The top-N list stays inside `payload`** rather than being normalized into a `shard_points_entries`
+table. It is a fixed-size list (10 by default) that is only ever read whole — exactly like
+`shard_governors.candidates` — so normalizing buys nothing until something needs a per-character
+reverse lookup, and a character's own standings already ride inside `char.profile` instead.
+
+Board state, not events: `points.board` is **not** in `LOGGED_KINDS`, for the same reason
+`guild.update` isn't. The shard emits a frame every time anyone's score moves a top ten, so logging
+would grow `shard_events` without bound for something whose only interesting value is its latest
+version. There is also **no delete path** — the shard's set of systems is fixed at startup, so there is
+no `points.remove` to mirror.
+
+Two values carry non-obvious meanings, both set by the plugin and both documented in
+[`link/INTEGRATION.md`](../link/INTEGRATION.md) §4:
+
+- **`max_points = 0` means uncapped**, and on a real shard that is the *common* case (ServUO's
+  uncapped idiom is `double.MaxValue`, which the plugin normalises to 0). Anything rendering
+  `points / max_points` must special-case it.
+- **`name` is usually NULL**, with `name_cliloc` set instead — most systems name themselves with a
+  cliloc rather than a literal. Listing therefore orders by `COALESCE(name, system)`, so boards
+  awaiting cliloc resolution sort by their own key rather than clumping together under NULL.
+
+### shard_vendors / shard_vendor_items — the player-vendor marketplace (Protocol 3.0)
+
+The shard-wide shop index, fed by `vendor.listing` / `vendor.listing.remove`. One row per player
+vendor and one per priced listing. Full operator detail in [`MARKETPLACE.md`](MARKETPLACE.md); the
+design is `docs/link/v3.md` §8.
+
+| Table | Shape |
+|---|---|
+| `shard_vendors` | `serial` (PK), `shop_name`, `owner_serial`, `owner_name`, `map`/`x`/`y`/`z`, `region`, `house`, `item_count`, `item_total`, `truncated`, `t`, `updated_at`. Indexes on owner, map, region and `updated_at`. |
+| `shard_vendor_items` | `id` (PK), `vendor_serial`, `serial`, `item_id`, `hue`, `amount`, `price`, `name`, `cliloc`, `display_name`, `child`. Indexes on `vendor_serial`, `price`, `item_id`, `display_name`, and `(display_name, price)`. |
+
+**Ingest is per-vendor and authoritative**: the frame is the whole shop, so ingest is
+delete-then-insert of that vendor's listings inside one transaction. All-or-nothing matters
+specifically because the two writes are "the shop" and "what is in it" — a failure between them
+leaves a shop advertising an inventory it no longer has, which is visibly wrong and indistinguishable
+from a genuinely empty shop. No foreign keys, consistent with every other `shard_*` table.
+
+**There is deliberately no `payload` column**, unlike `shard_points_boards` directly above. The
+board's top-N is a fixed-size list read whole, so it lives in JSON; here the items *are* the
+searchable rows, so they are normalized and nothing is left worth duplicating. The sidecar keeps the
+whole blob — outage resilience is its job, search is ours.
+
+Market state, not events: neither kind is in `LOGGED_KINDS`, and this is the strongest case of the
+three v3 kinds. One frame carries up to 250 listings and the sweep re-emits a shop on any price
+change, so logging would turn `shard_events` into a price history nobody reads.
+
+Two columns carry non-obvious meanings:
+
+- **`item_count` vs `item_total`.** `item_count` is what the frame published; `item_total` is what
+  the shop actually holds. They differ when `truncated` — the shard caps listings per frame
+  (`Bridge.MarketMaxListings`, 250 by default), and a commodity reseller with thousands of stacks
+  genuinely exceeds it. Any UI must show both or it presents a partial shop as complete.
+- **`display_name` is denormalized at ingest**, resolved from the item's literal `name` (preferred —
+  a player set it, so it is more specific) else its `cliloc` against `shard_clilocs`. Resolving at
+  query time would put the cliloc table on the hot path and make search-by-name impossible. Because
+  the shard's diff sweep will not re-send an unchanged shop just because the site learned what its
+  items are called, **a cliloc import triggers a bulk re-resolution** of this column (after a boot
+  import and after an admin import; ~50 ms per thousand rows, never throws).
+
+`updated_at` is written explicitly on every upsert rather than left to `ON UPDATE CURRENT_TIMESTAMP`,
+which MariaDB does not fire when every column is written back unchanged. A shop re-published
+identically is still *freshly confirmed*, and without this the staleness banner would age a perfectly
+current shop forever.
+
+### shard_feature_visibility  — per-feature audience config (Protocol 3.0)
+
+One row per shard feature: `feature` (PK), `enabled`, `audience` (a rung on the ladder in §6.5),
+`stream` (whether the feature's kinds fan out over SSE at all), `field_rules` JSON (`{field: rung}`
+for the sensitive fields only), `updated_by`, `updated_at`.
+
+**An absent row means "use the compiled default", and the compiled defaults reproduce pre-3.0
+behavior — so an empty table is a no-op and there is nothing to seed.** Stored rows are merged over
+the defaults on read, which is also where the invariants are re-applied: a row naming an unknown
+feature is ignored (a stale row must not resurrect a removed feature), an invalid rung falls back to
+the default rather than failing open, and a rule touching a locked field (`acct` / `webId`) is
+discarded. See §6.5.
+
+### shard_spawn_* / shard_regions / shard_landmarks / shard_champion_spawns / shard_atlas_meta — the spawn atlas (Protocol 3.0)
+
+Static shard **content**, not live shard state. Nothing here comes from the sidecar: the atlas is
+derived from the shard's own ServUO tree, re-read on **every server boot** and hash-gated so an
+unchanged tree costs one read pass and no write. Nothing is precomputed and committed — a shard's
+maps change over its life, and a snapshot in the repo would silently drift from the world players
+actually see. These tables stay populated whether the shard is up or not. Full operator detail in
+[`SPAWN_ATLAS.md`](SPAWN_ATLAS.md); the design is `docs/link/v3.md` §6.
+
+**No facet name appears anywhere in the code.** A shard may add facets, replace them, or rename them
+when its maps are updated; the facet set is discovered from the tree, and the loose spellings in
+`Data/Locations` are matched against it rather than looked up in a table.
+
+| Table | Key columns |
+|---|---|
+| `shard_spawn_creatures` | `slug` PK, `name`, `total`, `points`, `facets` JSON, `art` NULL |
+| `shard_spawn_points` | `id` PK, `facet`, `name`, `x`, `y`, `width`, `height`, `spawn_range`, `max_count`, `min_delay`, `max_delay`, `tod_start/end/mode`, `region`, `landmark`, `label` |
+| `shard_spawn_point_types` | `(point_id, slug)` PK, `max_count` |
+| `shard_regions` | `facet`, `name`, `type`, `priority`, `parent`, `rects` JSON |
+| `shard_landmarks` | `facet`, `name`, `grp`, `x`, `y`, `z` |
+| `shard_champion_spawns` | `slug` PK, `name`, `grp`, `type`, `random_type`, `facet`, `x`, `y`, `z`, `radius`, `label` |
+| `shard_atlas_meta` | Singleton (`id = 1`), `payload` JSON (counts, a sha256 per source file, `parserVersion`), `imported_at` |
+| `shard_atlas_pending` | Singleton (`id = 1`), `status` (`pending`/`rejected`), `payload` JSON, `detected_at` |
+
+The first seven are **import-owned**: a refresh empties and reloads every one inside a single
+transaction, so a failed reload leaves the previous atlas intact rather than a half-loaded world.
+Nothing else writes to them, and nothing holds a foreign key to them — no FKs at all, consistent with
+every other `shard_*` table.
+
+**`shard_atlas_pending` is the security-relevant one.** A refresh that would REMOVE a facet is never
+applied automatically: facet loss is indistinguishable at boot from a half-copied or mid-update tree,
+so it is staged here for an admin to approve or reject, and **startup is never blocked by it**. Only
+the decision is stored — source hashes plus the facet diff, a few KB — and approving re-parses the
+tree, so a multi-megabyte blob never lands in the database and what gets applied matches the tree at
+approval time. A rejection is remembered against those exact hashes so a declined refresh does not
+re-prompt on every restart. Everything else (new facets, renamed regions, changed spawns) applies
+immediately, since none of it can destroy data an operator would miss.
+
+The boot refresh is **best-effort by contract**: no configured path, an unreadable mount, a malformed
+file or a database error is caught and logged, and the site comes up serving whatever atlas it had.
+The tree path comes from the `spawn_atlas_servuo_path` setting, falling back to `SERVUO_PATH`.
+
+**A refresh re-derives when the tree changed OR the parser did.** `spawnAtlasSource.PARSER_VERSION`
+is stored in `shard_atlas_meta` beside the source hashes and bumped whenever the parser produces
+different data from identical files. Hashing the tree alone would strand an install whose maps never
+change on whatever an older build derived — a corrected parse would ship and never reach the data.
+
+Four column choices worth stating, because each one is a trap:
+
+- **`spawn_range`, not `range`**, and **`grp`, not `group`** — both are reserved words.
+- **`DELETE`, not `TRUNCATE`.** `TRUNCATE` is DDL in MariaDB and implicitly commits, which would
+  defeat the all-or-nothing reload. At ~7k rows the difference does not matter.
+- **Point ids are assigned explicitly**, not left to `AUTO_INCREMENT`: the `shard_spawn_point_types`
+  rows need to know them, and `conn.batch()` reports no usable `insertId` for a multi-row insert.
+- **Plain `INDEX` on `name`, deliberately not `FULLTEXT`.** ~800 creature rows makes a `LIKE` scan
+  free, and FULLTEXT's minimum token length would break searches for names like "orc".
+
+`shard_champion_spawns` is the *configured* altar roster ("there is an Unholy Terror altar in
+Deceit"). The live `champ.update` feed in `shard_champs` is the separate answer to "it is on level 3
+right now". Both exist; they are not the same data.
+
+**`shard_spawn_creatures.art` is always NULL on a fresh import.** The project ships no creature
+artwork: sprites live in the operator's own client `.mul`/`.uop` files and are theirs, not ours to
+redistribute. An operator supplies art via a gitignored map plus images under the (already
+gitignored) `server/uploads/atlas/`. Text-only is the normal, supported state.
+
+### shard_clilocs / shard_cliloc_meta — UO's localization table (Protocol 3.0)
+
+Items on the wire carry a `LabelNumber`, not a name. The bridge has always sent it —
+`char.profile.equipment.cliloc`, reward titles as a cliloc number in string form, and one per
+marketplace listing — but with no table to resolve it against, the character sheet could only render
+`id 1023721` where the game renders "quarter staff".
+
+| Table | Shape |
+|---|---|
+| `shard_clilocs` | `number` INT PK, `flag`, `text` TEXT |
+| `shard_cliloc_meta` | Singleton (`id = 1`), `payload` JSON (source file, sha256, count, `parserVersion`), `imported_at` |
+
+Import-owned and all-or-nothing in one transaction, same contract as the atlas — including **`DELETE`,
+not `TRUNCATE`**, for the same reason.
+
+**Sourced from files the operator supplies**, at a path from the `cliloc_client_path` setting falling
+back to `UO_CLIENT_PATH`. Nothing client-derived is committed: UO's strings are EA's, exactly as the
+creature sprites are. A shard with nothing configured is fully supported — names render as ids. Full
+design and operator guide: [`CLILOCS.md`](CLILOCS.md).
+
+**It reads a SET of sources, not one file**, because shards edit items and add new ones and those
+carry cliloc ids no stock client table has. A base (the converted client table) plus every overlay
+under `custom/` are re-read on every boot and hash-gated **together**, exactly as the atlas re-reads
+`Regions.xml` + `Locations/*.xml` + `Spawns/*.xml` + `ChampionSpawns.xml`. Later sources win, so an
+overlay both adds ids and overrides stock ones, and adding one custom item never means re-exporting a
+5 MB client file. Scale, measured on the live shard: its script tree references 16,434 cliloc ids and
+only 37 are absent from stock — tens of entries against a 67k base, which is why this is an overlay
+and not a second table.
+
+The conversion step is not avoidable: **every current client ships its cliloc files compressed**
+(first DWORD's high byte `0x8E`), and ServUO's own bundled `Ultima.StringList` cannot read that
+either — so the shard cannot supply names on our behalf. The plain layout and a delimited text export
+are both accepted, sniffed by header rather than extension.
+
+Three decisions worth stating:
+
+- **`text` is TEXT, not VARCHAR.** Long property descriptions reach 12 KB. The index that matters for
+  marketplace search is the denormalized `shard_vendor_items.display_name`, not this table.
+- **Blank entries are dropped at import** — 123,490 parsed → **67,496** stored. Roughly half a cliloc
+  table is empty strings for ids the client reserves and never uses; a row that resolves to no name is
+  indistinguishable from no row at all, and dropping them makes the binary and text imports converge
+  on identical content.
+- **Two refusals, one of them the atlas's.** A corrupt source fails the parse on a truncated record,
+  so it is caught outright and leaves the previous table serving. But a source that has **vanished**
+  parses perfectly and imports a table quietly missing everything it contributed — an unmounted volume
+  and a deliberate deletion are indistinguishable from here, which is precisely the ambiguity the
+  atlas stages a facet removal for. So it is escalated: `status: 'needsReview'`, nothing applied,
+  `missingSources` reported by both the import and `status()`, and an admin accepts it with
+  `{approve:true}`. That is a flag rather than the atlas's approve/reject pair because the atlas
+  stores a pending decision so that approving **re-parses** the tree; here nothing is stored, so
+  re-reading at approval time is automatic.
+
+**Resolution is server-side and there is no public route.** The table is never served *as* a table:
+67k rows would dwarf any page using them, and the Android client consumes the same already-resolved
+JSON. `resolveMany()` returns only ids that resolved to something displayable — placeholders like
+`~1_val~` are stripped, since the bridge sends the id and never the property packet that carries the
+arguments — and it never throws, because a cliloc lookup is decoration on a character sheet.
+
 ---
 
 ## 4. API contract
@@ -149,30 +595,234 @@ Seeded keys: `site_mode` (default `maintenance`), `site_mode_changed_at`,
 Base path `/api/v1`. JSON in/out. Auth via httpOnly cookie (`isLoggedIn` reads it; also
 accepts `Authorization: Bearer` for API testing).
 
-### /auth  (auth.routes.js → auth.controller.js)
+### 4.0 The authoritative route list
+
+The prose tables below are **orientation for a human reader** and can drift. Two generated artifacts
+are authoritative, and they answer different questions:
+
+| Artifact | Source of truth for | Generated by |
+|---|---|---|
+| `server/routes.manifest.json` — mirrored as [api-route-inventory.json](./api-route-inventory.json) | **What URLs exist.** 215 public routes + 2 on the internal listener, sorted, method + path only. | `npm run routes:manifest`, by walking the live Express stack |
+| `server/swagger/swagger-output.json` — served at `/api/docs` | **What each route means.** Parameters, bodies, response codes, security. | `npm run swagger`, from `#swagger.*` annotations |
+
+The split is deliberate: Swagger is annotation-derived, so an unannotated route is invisible in it and
+it churns whenever a description is reworded — it documents *intent*. The manifest is introspection-
+derived and records *reality*, which is why it, not Swagger, is the thing PR checks freeze
+(`npm run routes:manifest -- --check`).
+
+Both artifacts are emitted with **sorted** keys, so a diff in either is proportional to the change
+rather than to how the routers happen to be traversed. `swagger.js` additionally strips trailing
+slashes from generated path keys — see *Regenerating the spec* in the website README for why the
+domain split makes that necessary.
+
+Scope: the manifest keeps `/api/**` and `/.well-known/**` from the public app plus everything on the
+internal listener. The SPA catch-all, `/uploads` and `/brand` are filesystem-conditional static
+mounts — not API contract, and including them would make the output depend on whether CI had built
+the client.
+
+A third generated file, `server/routes.guards.json`, is a **review aid and not a contract**: per route,
+the middleware handler count plus the *named* middleware on its mount chain. It exists because a
+router-level `router.use(noindex, isLoggedIn, staffOnly)` gate never appears in an individual route's
+own stack, so a capability router extracted without re-applying the gate would otherwise publish
+authenticated endpoints silently. Names are a hint only — `requireRole(...)` returns an anonymous
+arrow and cannot be observed — but a *missing* `requireAuth` is unambiguous, and the server test suite
+asserts every `/admin/**` and `/player/**` route still carries it.
+
+### /auth  (auth/index.js → the capability routers in §2)
+
+No group gate — `/auth` is where an anonymous caller becomes authenticated. The authenticated parts
+gate themselves: `me.routes.js` and `notifications.routes.js` each apply `noindex, requireAuth` at
+their own router level, and `/sso/:provider/link` carries `requireAuth` per route.
+
 | Method | Path | Auth | Body | Purpose |
 |---|---|---|---|---|
-| 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 |
+| POST | `/login` | — (rate-limited) | `{username,password}` | verify, set cookie, log `auth.login`, update `last_login_at`. If the account has TOTP **and this browser is a trusted device** (a valid `rg_trust` cookie bound to the user), the TOTP step is **skipped** and a session is issued directly (logs `auth.login.trusted_device`). Otherwise a 2FA account returns `{totpRequired, challenge}`. |
+| POST | `/login/totp` | — (rate-limited) | `{challenge, code? \| recoveryCode?, trustDevice?, deviceName?}` | complete 2FA with a TOTP **or** single-use recovery code. `trustDevice` sets the `rg_trust` cookie so future logins skip TOTP; at the device cap the session is still issued and the body carries `{trustLimitReached, devices}`. |
+| POST | `/logout` | cookie | — | clear cookie (the `rg_trust` trust cookie deliberately **survives** logout) |
+| 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). **enable** returns the one-time `recoveryCodes`; **disable** clears the user's trusted devices + recovery codes |
+| GET | `/me/account/identities` · DELETE `…/:provider` | cookie / bearer | — | list / unlink own SSO identities |
+| GET | `/me/trusted-devices` | cookie / bearer | — | list own active trusted devices (never tokens) |
+| POST | `/me/trusted-devices` | cookie / bearer (rate-limited) | `{deviceName?}` | trust the current device; web gets an httpOnly `rg_trust` cookie, native gets `{trustToken}`. **409 `{error:'trusted_device_limit', devices}`** at the cap |
+| DELETE | `/me/trusted-devices` · `…/:id` | cookie / bearer | — | untrust all / one (ownership-scoped) |
+| GET | `/me/account/recovery-codes/status` | cookie / bearer | — | remaining unused code count (never the codes) |
+| POST | `/me/account/recovery-codes/generate` | cookie / bearer (rate-limited, **password step-up**) | `{currentPassword?}` | regenerate the one-time recovery codes (returned once); refused when 2FA is off |
+| 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.
+
+**The `/player/*` group is self-service, not player-only.** Staff are a **superset** of players — every
+player ability plus their staff tools on top — so the whole group (`account.router.js`,
+`shard.router.js`, `appeals.router.js`, mounted by `player/index.js`) sits behind the shared
+`noindex, requireAuth` gate **only**, never `requireRole('player')`. Every handler is self-scoped to the caller by `req.user.id`, so an admin/editor/
+moderator using it sees only their **own** linked accounts and characters (with the pre-existing
+`isAdmin` bypass still letting a genuine admin read *any* character). Staff also reach the identical
+self-scoped handlers under `/admin/shard/*` (same controller) for the web admin surface; the two are
+interchangeable. This is why a staff account with linked game characters gets its "My characters" and
+personal notification streams on the mobile client — the group no longer 403s a non-`player` role.
+
+**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`.
+
+The TOTP gate it reuses includes the **trusted-device skip** (see
+`TRUSTED_DEVICES_MFA.md` §6). Because the app opens this flow in a Custom Tab, which shares the
+system browser's cookie jar, the `rg_trust` cookie set on the TOTP form is presented back on the next
+app sign-in — so "don't ask me again" works for native SSO without the app injecting a header into a
+tab it does not control, and without a trust token ever appearing in a start URL.
+
+| 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}`. When the session carries `trust_device`, also mint a `platform:'mobile'` trusted device and add `trustToken` — minted here, on an authenticated app→server call, so it never travels in the deep link. Best-effort: at the trusted-device cap the response simply omits it rather than failing the sign-in |
+| 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/index.js → the capability routers in §2) — all GET except `/contact`, no auth
+
+**No group gate, deliberately.** This surface is anonymous by design: the SPA renders it logged-out,
+the Discord bot reads it with no credentials, and the Android `ShardStreamClient` consumes
+`/public/shard/stream` without an `Authorization` header. Content visibility during maintenance comes
+from the per-route **siteMode** middleware (§5), never from an auth gate.
 
-### /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) |
 | GET | `/wiki/:slug` | single page |
 | POST | `/contact` | (rate-limited) send mail via SMTP; if unconfigured, respond `{fallback:"mailto", email}` |
+| GET | `/shard/ruleset` | the shard's own published ruleset (Protocol 3.0 `world.ruleset`): expansion, which optional systems are on, skill/stat caps, account and house limits, champion scroll rules, the save/restart schedule. Served from `shard_ruleset`, so it renders while the shard is down; live via `world.ruleset` on `/shard/stream`. Behind `requireFeature('ruleset')`. **`null`** means the shard has never published one — a real answer, distinct from a published ruleset. `caps.skill` / `caps.totalSkill` are in **tenths** (1000 = 100.0). |
+| GET | `/shard/points` | every points/loyalty leaderboard the shard publishes (Protocol 3.0 `points.board`) — Queen's Loyalty, Void Pool, the nine city loyalties, Clean Up Britannia, … Served from `shard_points_boards`, so it renders while the shard is down; live via `points.board` on `/shard/stream`. Behind `requireFeature('leaderboards')`, ordered by display name. **`maxPoints: 0` means uncapped** (the common case), and `nameString` is usually `null` with `nameNumber` holding a cliloc — resolve client-side or humanise the `system` key. |
+| GET | `/shard/points/:system` | one board by the shard's `PointsType` name (e.g. `QueensLoyalty`); `:system` must match `/^[A-Za-z][A-Za-z0-9_]{0,47}$/` or **400** before any query runs. **404** = the shard has never published that system, which is distinct from a published board nobody has scored in yet (**200** with an empty `top`). |
+| GET | `/shard/market?q=&minPrice=&maxPrice=&itemId=&map=&region=&sort=&limit=&offset=` | search the player-vendor marketplace (Protocol 3.0 `vendor.listing`). Returns **listings**, not vendors — "who sells X and for how much" is the question, and a vendor-shaped result would make every caller flatten the shops back out. Served from `shard_vendors` + `shard_vendor_items`, so it renders while the shard is down. Behind `requireFeature('market')` **and rate-limited** — the first genuinely expensive public read on the site (a `LIKE` scan plus a `COUNT` over what is typically the largest `shard_*` table, reachable with no session). `sort ∈ {price_asc, price_desc, recent}`. `q` matches the resolved display name **or** the item's literal name, with `%`/`_` escaped: they are `LIKE` metacharacters, not SQL ones, so parameterization alone would let `?q=%` match every listing on the shard. Every response repeats `staleAt` (the oldest vendor row) because the shard sweeps round-robin — a banner that ages with the results it labels, not one fetched once. |
+| GET | `/shard/market/meta` | index size, staleness (`staleAt`/`freshAt`) and which facets and regions actually hold vendors, so a client builds its filters without running a search it will discard. |
+| GET | `/shard/market/vendors/:serial` | one shop and its listings; `:serial` must match `/^0x[0-9A-Fa-f]{1,16}$/` or **400** before any query runs. **404** = a serial the index has never seen, which also covers a vendor since dismissed or hidden — to an anonymous caller those are the same answer, and distinguishing them would leak that a hidden vendor exists. `truncated` (with `total` exceeding `count`) means the shop holds more than the shard publishes per frame. |
+| GET | `/shard/features` | the shard features **this caller** may reach plus the audience rung they resolved to (§6.5), so a client hides nav it can't follow. Reports only what the caller can see — the list itself never discloses a gated feature. Consumed by the SPA header and (pending) the Android nav. |
+| GET | `/atlas/creatures?q=&facet=&limit=&offset=` | the bestiary, most numerous first, with an unpaginated `total`. Static content parsed from the shard's ServUO tree — **not** sidecar-backed, which is why the atlas sits outside `/shard`, and unlike `/shard/*` it **is** site-mode gated. Behind `requireFeature('atlas')`. `?facet=` is matched exactly and never validated against a list (no facet name exists in the code); the filter is an `EXISTS` over the points rather than a JSON path or `JSON_SEARCH` built from caller input, whose `%`/`_` wildcards would make `?facet=%` match everything. |
+| GET | `/atlas/creatures/:slug` | one creature: `places` (the point-in-rect aggregate — "lizardman → Shrines, Isamu-Jima, Yew"), `spawners` (the bounded raw list, with `spawnersTruncated`), `alsoHere`. **`points` is a COUNT and `spawners` is the LIST** — named apart so one key never means a number on one route and an array on another. `minDelay`/`maxDelay` are in **seconds**, normalised at parse time from the source's per-record minutes-or-seconds. 404 = no such creature in this atlas. |
+| GET | `/atlas/regions?facet=&q=` | named regions and the rectangles that placed each spawner |
+| GET | `/atlas/landmarks?facet=&q=` | points of interest, labelled by `group` ("Covetous", not "Level 1") |
+| GET | `/atlas/champions?facet=` | the **configured** altar roster. Not `/shard/champs`, which is the live board. |
+| GET | `/atlas/meta` | facets, counts and when the atlas was parsed. Game-world facts only — the ServUO path, source hashes and any pending refresh are operator detail and live on the admin route. |
 
 Public content GETs pass through the **siteMode** gate (§5).
 
-### /admin  (admin.routes.js → admin.controller.js) — all behind `isLoggedIn` + `noindex`
+### /admin  (admin/index.js → the capability routers in §2) — all behind `isLoggedIn` + `noindex` + `staffOnly`
+
+`admin/index.js` applies the shared gate and mounts each capability router at the prefix it owns;
+`users`, `invites`, `auth/providers` and `bot-activity` add `adminOnly` on top, and `moderation` adds
+`modAccess` (admin + moderator, so editors are excluded). The content capabilities — `posts`,
+`uploads`, `wiki`, `pages` — add nothing: managing content is the editor tier's job, so `staffOnly` is
+the whole gate. The ops/config capabilities — `uo-link`, `email`, `discord-bot`, `settings`, and
+`PUT /site-mode` — are `adminOnly`; `shard` is the one mixed prefix, where self-service account
+linking carries no extra gate and the in-game staff operations carry `modAccess`. There is no residual
+file: every admin route is declared in a capability router.
+
+`GET`/`PUT /admin/shard/visibility` are the third tier on that mixed prefix: **`adminOnly`**, because
+they decide what *anonymous* visitors can see (§6.5). They sit above `modAccess` deliberately — a
+moderator can ban a player but cannot decide what the public internet reads.
+
+`GET /dashboard` and `PUT /site-mode` are the one place where a **single screen spans two tiers**: the
+dashboard is staff-wide, but the site-mode toggle on it is `adminOnly`. The client must therefore gate
+that control on its own (`Dashboard.jsx` renders it only for `role === 'admin'`) rather than relying on
+the route gate that admitted them to the page — the same rule the sidebar follows, so a non-admin is
+never shown a control that would 403. The URLs below are unaffected by which
+file a route sits in — that is the property the route manifest freezes.
 | Method | Path | Purpose |
 |---|---|---|
 | GET | `/dashboard` | current mode, last change time + who, content counts, recent activity |
@@ -189,6 +839,16 @@ Public content GETs pass through the **siteMode** gate (§5).
 | GET | `/settings` · PUT `/settings` | read all / update `{key:value,...}` |
 | GET | `/activity?limit=&offset=` | paginated activity log |
 | GET | `/users` · POST `/users` · PUT `/users/:id` · DELETE `/users/:id` | user mgmt (can't delete self / last admin; password hashed on write) |
+| GET | `/users/:id/trusted-devices` | list a user's active trusted devices (never tokens) |
+| DELETE | `/users/:id/trusted-devices` · `…/:deviceId` | revoke all / one of a user's trusted devices (logs `admin.trusted_device.revoke[_all]`) |
+| POST | `/users/:id/mfa/reset` | recover a locked-out user: disable TOTP + revoke all trusted devices + clear recovery codes (logs `admin.user.totp.reset`) |
+| GET | `/shard/atlas` | spawn-atlas status (`adminOnly`): the ServUO path, whether the tree is readable, whether it has drifted from what is loaded, counts, facets, and any refresh staged for review. The public `/atlas/meta` reports the game world only; the filesystem detail is here. |
+| POST | `/shard/atlas/import` | re-import without restarting; `{force}` ignores the hash gate. **An unreadable tree answers 200 with `status:"unavailable"`, not 500** — `refresh()` reports outcomes rather than throwing (the boot path must never be blocked by a bad tree) and that contract is preserved at the API. |
+| POST | `/shard/atlas/approve` · `/shard/atlas/reject` | answer a refresh staged because it would REMOVE a facet. Approving **re-parses** the tree, so what lands matches it at approval time; rejecting is remembered against those source hashes so it does not re-prompt every restart. 404 when nothing is staged. |
+| PUT | `/shard/atlas/path` | point the atlas at a different tree (persisted as `spawn_atlas_servuo_path`, which wins over `SERVUO_PATH`). Blank clears it. Deliberately **does not import** — moving the mount and reloading the world are separate decisions — and returns fresh status so the panel can offer the import next. |
+| GET | `/shard/clilocs` | cliloc-table status (`adminOnly`): every source found now (base first, then `custom/` overlays in merge order), what each contributed at the last import, readability, drift across the set, the entry count, and `missingSources`. `configured:false` is a supported state — item names then render as ids. No public counterpart: the table is never served *as* a table. |
+| POST | `/shard/clilocs/import` | reload after a client patch or an overlay edit; `{force}` ignores the hash gate, `{approve}` accepts a **vanished** source (refused by default — see the table notes above). **A missing path — or the likely mistake of pointing at the client's own COMPRESSED `Cliloc.enu` — answers 200 with `status:"unavailable"` and a `code`, not 500.** `COMPRESSED` is called out by name: a 500 would say only "something broke", and the operator needs to be told which file to convert. |
+| PUT | `/shard/clilocs/path` | point the site at a different cliloc base file or directory (persisted as `cliloc_client_path`, which wins over `UO_CLIENT_PATH`). Overlays are read from `custom/` beside it either way. Blank clears it. Deliberately **does not import**, same reasoning as the atlas path. |
 
 Every admin write logs to `activity_log`.
 
@@ -219,17 +879,128 @@ who"; `activity_log` provides the history feed.
 ## 6. Auth & security
 
 - **JWT** signed with `JWT_SECRET`, `expiresIn=JWT_EXPIRES_IN` (default `1d`); payload `{id,username,role}`.
-- **Cookie**: `httpOnly`, `sameSite=Lax`, `path=/`, and **`secure` decided per-request** (`COOKIE_SECURE=auto` → `secure: req.secure`). This is the key to dual access: the cookie is `Secure` when reached through Pangolin (HTTPS, `X-Forwarded-Proto: https`) but **not** `Secure` when reached directly over the LAN IP on plain HTTP — so login works in both. `COOKIE_SECURE=true|false` can force it. Requires `trust proxy` (below). `localhost:5173` (Vite) and `localhost:3000` are same-site, so the cookie flows in dev too.
+- **Cookie**: `httpOnly`, `sameSite=Lax`, `path=/`, and **`secure` decided per-request** (`COOKIE_SECURE=auto` → `secure: req.secure`).
+- **Trusted-device MFA.** A second, separate httpOnly cookie (`rg_trust`, default 30d) — opaque, sha256-hashed server-side in `trusted_devices` — lets a browser/app **skip the TOTP step** (never the password) on future logins. It is a server-side, per-row-revocable record (never a JWT claim), so the stateless session JWT is unchanged and trust stays revocable. It only ever gates the **second factor**; it deliberately outlives logout, and is cleared on untrust / password change / password reset / TOTP disable. **Recovery codes** (bcrypt, single-use) are the 2FA-lockout fallback. All admin trusted-device/MFA actions and the self actions (`auth.login.trusted_device`, `account.trusted_device.*`, `account.recovery_code*`, `admin.trusted_device.*`, `admin.user.totp.reset`) are audit-logged. See `docs/website/TRUSTED_DEVICES_MFA.md`. This is the key to dual access: the cookie is `Secure` when reached through Pangolin (HTTPS, `X-Forwarded-Proto: https`) but **not** `Secure` when reached directly over the LAN IP on plain HTTP — so login works in both. `COOKIE_SECURE=true|false` can force it. Requires `trust proxy` (below). `localhost:5173` (Vite) and `localhost:3000` are same-site, so the cookie flows in dev too.
 - **bcrypt** hashing (cost 10+); plaintext passwords never stored, logged, or returned.
-- **Rate limiting** (`express-rate-limit`) on `/auth/login` and `/public/contact`.
+- **Rate limiting** (`express-rate-limit`) on `/auth/login`, `/public/contact`, and — the only limited
+  *read* — `/public/shard/market` and `/public/shard/market/vendors/:serial` (60/min/IP). Every other
+  public read is an indexed lookup of bounded size; the marketplace search is a `LIKE` scan plus a
+  `COUNT` over the largest `shard_*` table, anonymous by default, so it is the one public GET that is
+  worth money to serve.
 - **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. The policies now live in
+  **`server/src/config/csp.js`** (`app.js` only wires them up):
+  `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'`; `form-action 'self'` (blocks an injected `<form action="https://evil">` from POSTing
+  credentials off-origin — an exfil path `connect-src` does not cover; it was always emitted via
+  helmet's `useDefaults` and is now pinned explicitly so it cannot vanish under a helmet upgrade).
+  `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.
+- **A second, tightened policy ships alongside on `Content-Security-Policy-Report-Only`** for one
+  release before it replaces the enforced one (`docs/website/API_V2_PLAN.md` § Phase 1). It is derived
+  from the enforced policy so the two cannot drift, and differs by exactly one directive:
+  `frame-ancestors 'self'` → **`'none'`**. Serving both headers at once means the live policy keeps
+  protecting users while anything the tightened version would break arrives as a report rather than as
+  a broken page — and for `frame-ancestors` specifically, a report from the browser of whoever framed
+  the site is the only way to learn that something does.
+- **`POST /api/csp-report`** is the same-origin violation sink that `report-to` / `report-uri` point at
+  (`report-to` additionally requires the `Reporting-Endpoints` response header, which is set alongside).
+  Same-origin on purpose: reports describe attacks against this site and are not handed to a
+  third-party collector. It parses **both** wire formats (`application/csp-report` from Firefox/Safari,
+  `application/reports+json` from Chrome's Reporting API — handling one drops half the browsers),
+  writes to the `csp` log tag and **stores nothing**. Necessarily unauthenticated (browsers send
+  reports with no session), so it is bounded on every axis: 16 KB body cap, per-IP rate limit, fixed
+  field allowlist, every logged field truncated, and **always 204 — even for malformed input**, since a
+  4xx would make the global error handler log the attacker-supplied body and turn an open endpoint into
+  a log-flood primitive. Mounted outside `/api/v1` next to `/api/health`: the browser learns the path
+  from the policy header, never from a client build, so it is not part of the versioned client
+  contract.
 - **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.
 - **`app.set('trust proxy', 1)`** so secure cookies, `req.ip`, and rate-limiting work behind Pangolin.
 - **CORS**: same-origin in prod (SPA served by Express). Dev only: allow `CLIENT_ORIGIN` (Vite, `http://localhost:5173`) with `credentials:true`.
 
+### 6.5 Shard visibility — the audience boundary (Protocol 3.0)
+
+Every shard-derived surface is gated by an **admin-configurable, per-feature and per-field** audience
+setting. This **replaces** the static `PUBLIC_KINDS` allowlist that used to be the whole boundary.
+Policy lives in `utils/shardVisibility.js`; rows live in `shard_feature_visibility`; the admin surface
+is `GET`/`PUT /admin/shard/visibility` (`adminOnly`). Admin-facing guide:
+[`SHARD_VISIBILITY.md`](SHARD_VISIBILITY.md). Design: [`../link/v3.md`](../link/v3.md) §3.
+
+**The ladder.** `anonymous < logged_in < player < staff < admin`, each rung implying the ones below.
+`viewerLevel(req)` resolves it: no session ⇒ `anonymous`; authenticated ⇒ `logged_in`; authenticated
+with a linked game account ⇒ `player`; moderator ⇒ `staff`; admin ⇒ `admin`. **Staff satisfy the
+`player` rung without a linked account** (consistent with `/player/*` being role-agnostic).
+**`editor` gets no shard privilege** — it is a content role, and mapping it to `staff` would silently
+widen what editors see.
+
+**Two invariants that are code, not configuration.** Both are enforced server-side and both reject
+rather than silently ignore:
+
+1. **`acct` and `webId` are admin-only, always.** They are not exposed as configurable fields, and a
+   stored row attempting to loosen them is discarded on read as well as rejected on write. A character
+   name is visible in game; the account behind it and the website user it links to are not.
+   The lock is on the field's **meaning, not one spelling**: `isLockedField(key)` matches a key that
+   *is* or *ends in* `acct`/`webId`, case-insensitively, so the flattened forms the read models emit
+   (`shapeHouse` → `ownerAcct`, `shapeGuild` → `leaderWebId`) are covered too. An exact-key check was
+   the original implementation and it let `GET /public/shard/idoc` serve `ownerAcct` anonymously.
+2. **A kind absent from `KIND_FEATURE` is never broadcast below `admin`.** Fail closed. This is what
+   keeps the kind map a security boundary rather than a convenience filter, and it means a shard that
+   starts emitting an unknown event degrades to staff-only, never to public.
+
+**Fail-closed everywhere else too.** An unreadable visibility config withholds every public frame; a
+DB failure falls back to the compiled defaults (pre-3.0 behavior), not to open; an unresolvable viewer
+subscribes as `anonymous`. The ladder comparison uses **asymmetric** fallbacks by design — an unknown
+*viewer* level floors to the bottom rung and an unknown *requirement* ceils to admin, so an
+unrecognised value loses on both sides. (A single shared fallback cannot do that: whichever direction
+it picks, it fails open on one side.)
+
+**Three enforcement points, one config:**
+
+| Where | Mechanism |
+|---|---|
+| Routes | `requireFeature(name)` — **404** when the feature is disabled (don't leak that it exists), **403** when the caller is below its audience. `projectFeature` then strips out-of-rung fields from the body. |
+| SSE (`utils/shardBroadcast.js`) | Per-connection filtering. A subscriber's rung is resolved **once at subscribe time and frozen** for that connection, so a long-lived stream can't gain privilege; each frame is then mapped kind→feature, gated, and field-projected per viewer. Two subscribers can legitimately receive different versions of one event, or one of them nothing. |
+| Nav | `GET /public/shard/features` returns only what the caller may reach, so the SPA never renders a link that would 403. Presentation only. |
+
+Config reads are cached ~5s, so admin changes take effect within seconds **including on already-open
+streams**. `PUBLIC_KINDS` still exists and is still exported (`notificationStreams.js`) but is now
+**derived** from the kind map rather than hand-maintained, so the two cannot drift.
+
+**`PUBLIC_KINDS` is a module-load constant and must not be used to answer "may this caller read this
+kind?"** — it is computed from the compiled *defaults*, so it cannot see an admin's changes. Use
+`visibleKinds(level, config)`, which resolves against the live config. `/feed` uses it; it originally
+used `PUBLIC_KINDS` and consequently kept serving `guild.join` to anonymous callers after an admin had
+moved `guilds` to `staff`. `visibleKinds` deliberately ignores the `stream` flag: that governs SSE
+fan-out only, so a feature whose live firehose ships off (market) stays readable from stored history.
+
+**Every read path that returns shard data must call `projectFeature`.** The stored-history endpoints
+are not exempt — `/feed` returns the same events the stream does, and returning them unprojected
+reopens on the REST side exactly what the stream closes. Relatedly, `shardEvents.db.list` treats an
+**empty** `kinds` array as "serve nothing", never "no filter"; the fall-through it used to take would
+have turned a fully-gated config into a dump of the entire event log.
+
+`projectFeature` walks **arrays and plain objects only**. A `Date`, `Buffer` or other class instance
+is passed through as a value — rebuilding one key-by-key yields `{}`, which is the difference between
+the pure-JSON wire frames and the DB-backed read models whose rows carry real `Date` columns.
+
+**Defaults reproduce pre-3.0 behavior exactly**, so installing the framework is a no-op until an admin
+changes something — with deliberate exceptions, which are the leaks it was written to close.
+`/public/shard/guilds`, `/public/shard/governors` and `/public/shard/feed` previously returned the raw
+stored payload, whose actors carry `acct` and `webId`; `/public/shard/idoc` returned the flattened
+`ownerAcct`. All are now stripped for every caller below admin.
+
 ---
 
 ## 7. Email
@@ -248,7 +1019,11 @@ instead. Errors never leak credentials.
 
 `utils/logger.js` — a small dependency-free logger with **two transports, console + file**,
 and four levels (`error`/`warn`/`info`/`debug`). Each line is timestamped and tagged by
-subsystem (`[server]`, `[http]`, `[db]`, `[auth]`, `[admin]`, `[ratelimit]`, …).
+subsystem (`[server]`, `[http]`, `[db]`, `[auth]`, `[admin]`, `[ratelimit]`, `[csp]`, …).
+
+> During the CSP report-only soak, `[csp]` is the tag to watch: a `csp violation` warn line with
+> `directive: frame-ancestors` means something really does frame the site and the enforce PR would
+> break it. Silence across one release is the green light to flip.
 
 - **Console**: color on a TTY, plain in Docker; verbosity = `LOG_LEVEL` (default `info`).
 - **File**: plain text appended to `LOG_DIR/LOG_FILE` (default `<server>/logs/app.log`,
@@ -270,7 +1045,15 @@ 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`,
+  **publishes `:80` on a host port** (`${NTFY_HOST_PORT:-2586}:80`, binds 0.0.0.0) so Pangolin — which
+  runs outside the compose network — can forward the notification subdomain to it, the same reason
+  `app` publishes `3000`. Both devices (SSE subscribe) and the backend publisher (POSTing tickles to
+  registered device endpoints) reach ntfy on that public origin. 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 +1075,19 @@ 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
+# Host port the ntfy container publishes :80 on (default 2586); the reverse proxy
+# forwards the notification subdomain to host:NTFY_HOST_PORT. Change on a conflict.
+NTFY_HOST_PORT=2586
 ```
 
 `.gitignore`: `node_modules/`, `.env`, `_reference/`, `client/dist/`, `uploads/`.

website/CLILOCS.md

@@ -0,0 +1,309 @@
+# Cliloc table (item and title names)
+
+**Status:** Complete on `edge` — website [#115](https://gitea.whitlocktech.com/RunicGateway/website/pulls/115), docs [#70](https://gitea.whitlocktech.com/RunicGateway/docs/pulls/70).
+**Design:** [`docs/link/v3.md` §8.6](../link/v3.md) — Protocol 3.0, the dependency Part B/3 was sequenced behind.
+
+A "cliloc" is UO's localization table: an integer id mapped to a display string.
+**Items on the wire carry a `LabelNumber`, not a name.** The bridge has always
+sent that number — `char.profile.equipment` has a `cliloc` field, reward titles
+arrive as a cliloc number in string form, and every marketplace listing carries
+one — but the site had no table to look it up in, so a character sheet could only
+render `id 1023721` where the game renders **"quarter staff"**.
+
+The number was never the missing piece. The table was.
+
+## Why the operator has to convert the file
+
+This is the awkward part, and it is not avoidable:
+
+**Every current UO client ships its cliloc files compressed.** All eight
+`Cliloc.*` files in a modern client (`chs`, `cht`, `deu`, `enu`, `esp`, `fra`,
+`jpn`, `kor`) begin with a DWORD whose high byte is `0x8E` — the "Mythic"
+compressed container. The plain layout this site parses is what those files
+looked like *before* that change.
+
+Decompressing it means an inverse-BWT coder with a frequency header — a few
+hundred lines of bit-level work whose failure mode is plausible-looking garbage
+rather than an error. The site has no business carrying that at runtime.
+
+Two facts make the alternatives worse, not better:
+
+- **ServUO cannot read it either.** Its bundled `Ultima.StringList` implements
+  only the plain layout, so on a modern client `VendorSearch.StringList` is null
+  and `VendorSearch.GetItemName` returns `item.Name` — usually nothing. The
+  shard cannot supply names on our behalf; the in-game Vendor Search gump has the
+  same gap.
+- **Nothing client-derived may be committed.** UO's strings are EA's. The repo
+  ships no string table for the same reason it ships no artwork and no map
+  snapshot — see [`SPAWN_ATLAS.md`](SPAWN_ATLAS.md).
+
+So the conversion happens **once, on the operator's machine, against their own
+client**, and the site reads the result from a path it is given. A shard that
+never does this is in a fully supported state: names render as ids, exactly as
+they did before the table existed.
+
+## Converting
+
+> **Step-by-step operator instructions — where to get UOFiddler, where your
+> client files are, and how to verify the import — are in
+> [`UOFIDDLER.md`](UOFIDDLER.md).** This section covers the formats and the
+> reasoning behind them.
+
+Either format below is accepted; the site sniffs which one it was handed.
+
+| Format | Fidelity | Notes |
+|---|---|---|
+| **Plain binary** (recommended) | Exact | 6-byte header, then `{int32 number, byte flag, uint16 length, UTF-8}` records |
+| Delimited text | Loses leading/trailing whitespace | `number<TAB\|,\|;>text` per line; a header row, blank lines and `#` comments are ignored |
+
+The whitespace caveat is real but cosmetic: ~1,300 of the 123,490 entries in a
+stock `Cliloc.enu` are label prefixes like `"max = "` whose trailing space is
+meaningful when the client concatenates a value onto them. Nothing on this site
+concatenates, and every consumer passes through `displayText()`, which trims.
+
+### Using the bundled tool
+
+`server/tools/cliloc-export/` is a small .NET console app that drives
+[UOFiddler](https://github.com/polserver/UOFiddler)'s `Ultima.dll` — the
+decompressor that already exists and is already maintained — and writes the plain
+format. It loads that DLL **reflectively** so it compiles against any SDK, and it
+writes the records by hand because UOFiddler's own `SaveStringList` *re-compresses*
+on save (its purpose is round-tripping a file back into the client, so its output
+is byte-identical to its input — a trap worth knowing about).
+
+```bash
+cd website/server/tools/cliloc-export
+dotnet build -c Release
+
+# binary (recommended)
+dotnet run -- "<UOFiddler>/Ultima.dll" "<UO client>/Cliloc.enu" /srv/uo-data/clilocs.plain
+
+# or tab-delimited
+dotnet run -- "<UOFiddler>/Ultima.dll" "<UO client>/Cliloc.enu" /srv/uo-data/clilocs.tsv --tsv
+```
+
+A UOFiddler GUI export works too, but **not unmodified**: its Cliloc tab writes
+`Number;Text;Flag` — three columns, the flag *last* — and the parser reads
+`number<separator>text`, so the trailing field is absorbed into the name and
+every item renders as `quarter staff;0`. Stripping it is one `sed`, given in
+[`UOFIDDLER.md`](UOFIDDLER.md) §Route B.
+
+The parser already tolerates `number,flag,text`, with the flag in the *middle*.
+It is not extended to cover the trailing form because a final `;0` is
+indistinguishable from a name that genuinely ends that way — a heuristic there
+would corrupt real names to save the operator one command.
+
+## Shard-added and shard-edited items
+
+**Shards edit items and add new ones**, and those carry cliloc ids no stock
+client table has. The table is therefore built from a **set** of sources, all
+re-read on every boot and hash-gated together — the same shape as the spawn
+atlas, which reads `Regions.xml` + `Locations/*.xml` + `Spawns/*.xml` +
+`ChampionSpawns.xml` and merges them:
+
+```
+<cliloc path>/
+  clilocs.plain            ← base: the converted client table
+  custom/
+    01-uomysticmoon.tsv    ← overlays: shard additions and overrides
+    02-events.tsv
+```
+
+Overlays use the same delimited-text format, are read in **sorted order**, and
+**later sources win** — so an overlay both *adds* ids the client never had and
+*overrides* stock ones the shard has re-purposed. Any `.tsv`, `.csv`, `.txt`,
+`.enu` or `.plain` file in `custom/` is picked up; anything else (a `README.md`,
+say) is ignored.
+
+Adding, editing or removing any overlay counts as drift, so a new custom item
+needs only a file edit and a restart — or the admin panel's Import button.
+**Adding one item never means re-exporting a 5 MB client file.**
+
+The import result reports what each source contributed, which is how you confirm
+an overlay took effect — `overrode: 0` on a file meant to re-label stock items
+says it did not:
+
+```json
+"sources": [
+  { "label": "clilocs.plain",           "kind": "base",   "entries": 123490, "added": 123490, "overrode": 0 },
+  { "label": "custom/uomysticmoon.tsv", "kind": "custom", "entries": 2,      "added": 1,      "overrode": 1 }
+]
+```
+
+**Why a convention rather than discovery.** Everywhere else this pipeline follows
+the shard's own files, but **ServUO has no server-side notion of a custom
+cliloc** — they live in the patched client a shard distributes to its players,
+and nothing in the tree declares them. There is nothing to discover, so `custom/`
+is the one thing here that is our convention rather than the shard's. (An
+operator who *does* patch their client cliloc needs no overlay at all: convert
+the patched file and their edits are simply in the base.)
+
+Measured on the live shard for scale: its script tree references **16,434** cliloc
+ids and only **37** are absent from the stock client table — tens of entries
+against a 67k base, which is what makes an overlay the right shape rather than a
+second full table.
+
+## Configuring the path
+
+Two ways to point at the sources, the setting winning over the environment:
+
+| Source | Notes |
+|---|---|
+| `cliloc_client_path` setting | Admin-editable (Admin → Shard); takes effect on the next refresh without a redeploy |
+| `UO_CLIENT_PATH` env var | The deploy-time default, since the path usually describes a mount the deployment sets up |
+
+The value may be **the base file itself or a directory to search**, because both
+are natural answers to "where is it". Overlays are read from a `custom/`
+directory beside the base **either way** — pointing at a file does not forfeit
+them.
+
+A directory is searched case-insensitively (the client writes `Cliloc.enu` on
+Windows; the site usually runs on Linux) for, in order: `clilocs.tsv`,
+`clilocs.csv`, `clilocs.plain`, `cliloc.plain`, `cliloc.plain.enu`,
+`cliloc.enu.plain`, `clilocs.txt`, `cliloc.enu`.
+
+That ordering puts explicitly-converted names first on purpose. Pointing the
+setting straight at an unconverted client directory finds `cliloc.enu`, which is
+compressed — and the site says so by name rather than failing obscurely:
+
+```
+status: unavailable
+code:   COMPRESSED
+reason: This is a compressed (Mythic-format) cliloc file, which the site cannot
+        read. Convert it to the plain format first — see docs/website/CLILOCS.md.
+```
+
+## Refresh contract
+
+Identical in shape to the spawn atlas, and for the same reasons:
+
+- **It never blocks startup.** No path, an unreadable file, a wrong-format file,
+  a database error — all caught and logged. The site comes up either way.
+- **Hash-gated.** The boot path hashes the file and skips the parse entirely when
+  it matches what is loaded, which is every restart that did not follow a client
+  patch. Measured on a stock table: **14 ms** for the no-op, **663 ms** for a full
+  parse and replace.
+- **A `PARSER_VERSION` bump also counts as drift**, so a corrected parse reaches
+  an install whose client never patches.
+
+### Two ways a refresh is refused
+
+**A corrupt file** — the realistic failure for any single source — makes the
+parser fail on a truncated record rather than yield a plausible-but-short table,
+so it is caught outright. Verified: a file truncated to half its length reports
+
+```
+code:   TRUNCATED
+reason: Truncated record header at byte 2486759 (74909 entries read)
+```
+
+and the rows already loaded are untouched. A malformed overlay names the file it
+came from (`custom/broken.tsv: No cliloc entries found…`), because "which of my
+six overlay files is broken" is otherwise a guessing game.
+
+**A source that has VANISHED** is the hazard a single file did not have. It
+parses perfectly and imports a table quietly missing everything that file
+contributed — and an unmounted volume looks exactly like a deliberate deletion
+from here. This is the same ambiguity the atlas stages a facet removal for, so it
+is escalated rather than applied:
+
+```
+status:         needsReview
+reason:         1 previously-loaded cliloc source(s) are missing;
+                the existing table is unchanged
+missingSources: ["custom/uomysticmoon.tsv"]
+```
+
+`status()` reports `missingSources` too, so the panel can show it before anyone
+clicks Import. An admin accepts it by re-running the import with
+`{ "approve": true }`.
+
+**Why that is a flag and not the atlas's approve/reject pair.** The atlas stores
+a pending decision in its own table so that approving *re-parses the tree*, which
+is what keeps a multi-megabyte blob out of the database and makes the applied
+result match the tree at approval time. Here nothing is stored, so re-reading at
+approval time is automatic — the decision is a single boolean on the import an
+admin was already going to run.
+
+## What gets stored
+
+| | |
+|---|---|
+| Parsed from a stock `Cliloc.enu` | **123,490** entries |
+| Of those, empty strings | **55,994** (ids the client reserves and never uses) |
+| Stored in `shard_clilocs` | **67,496** |
+
+Blank entries are dropped at import. A row resolving to no name is
+indistinguishable from no row at all to every caller, and dropping them makes the
+binary and text imports converge on **identical** content — the binary format
+carries the blanks explicitly and a text export may or may not, depending on the
+tool. Verified: both formats import to the same 67,496 rows with the same keys.
+
+`text` is `TEXT`, not `VARCHAR`: the long property descriptions reach 12 KB, and
+silently truncating them would be worse than storing them. The index that matters
+for marketplace search is on the denormalized `shard_vendor_items.display_name`,
+not here.
+
+## How names are applied
+
+**Resolution happens server-side.** The table is never served *as* a table and
+there is no public route for it. Two reasons: 67k rows would dwarf any page that
+used them, and the Android client consumes the same JSON and would otherwise need
+its own copy.
+
+`resolveMany()` takes a batch of ids and returns a `Map` holding only those that
+resolved to something displayable, so "no such id" and "id with no usable name"
+collapse into one branch at the call site. It never throws — a cliloc lookup is
+decoration on someone's character sheet, and a database blip must not fail the
+sheet. A capped in-process cache fronts it; measured cold **4.2 ms**, warm
+**0.015 ms**.
+
+### `displayText()`
+
+Cliloc strings interpolate arguments the client pulls from an item's property
+list — `~1_val~`, `~2_NAME~`. **We never have those**: the bridge sends the id,
+not the packet. So a name carrying them is reduced to what is actually knowable.
+
+| Raw | Displayed |
+|---|---|
+| `quarter staff` | `quarter staff` |
+| `cold damage ~1_val~%` | `cold damage` |
+| `[~1_stuff~]` | *(nothing — the whole string was the argument)* |
+| `50%` | `50%` |
+| `Runic Gateway Sigil (v2)` | `Runic Gateway Sigil (v2)` |
+
+**Punctuation is only tidied when a placeholder was actually removed.** The
+trailing `%` in row two is the unit belonging to the number we never had, and the
+brackets in row three only ever wrapped the argument — but a string with no
+placeholder has no such debris, and trimming it anyway corrupts real names. Rows
+four and five are the ones that caught it: a shard's custom
+`"Runic Gateway Sigil (v2)"` rendered as `"(v2"` while the bracket trim was
+unconditional.
+
+### Consumers
+
+- **Character sheet equipment.** `enrichCharProfile` attaches `clilocName` to each
+  item. A player-given `name` always wins — "Bob's lucky axe" must not be
+  relabelled "hatchet" — and the client re-states that precedence.
+- **Reward titles.** `titles.rewardResolved` is a parallel array with the numeric
+  entries turned into words (`null` where nothing resolved). The sheet used to
+  *skip* numeric reward titles entirely, having no way to render them.
+- **Marketplace listings** (Protocol 3.0 §8) denormalize the resolved name into
+  `shard_vendor_items.display_name` so search can index it.
+
+## Admin surface
+
+All admin-only, alongside the atlas under Admin → Shard:
+
+| Route | Purpose |
+|---|---|
+| `GET /api/v1/admin/shard/clilocs` | Sources found, what each contributed at the last import, readability, drift, entry count, `missingSources` |
+| `POST /api/v1/admin/shard/clilocs/import` | Reload after a client patch or an overlay edit; `{ "force": true }` reimports an unchanged set, `{ "approve": true }` accepts a vanished source |
+| `PUT /api/v1/admin/shard/clilocs/path` | Set the path; blank disables resolution |
+
+A refresh **result is not an exception**: a missing file, or the likely mistake of
+pointing at the client's own compressed `Cliloc.enu`, answers `200` with
+`status: "unavailable"` and a reason. A `500` would say only "something broke";
+the operator needs to be told which file to convert. Setting the path
+deliberately does **not** import as a side effect — the response carries the
+refreshed status so the panel can offer that as the next step.

website/MARKETPLACE.md

@@ -0,0 +1,167 @@
+# Marketplace — the player-vendor index
+
+**Status:** On `edge` — servuo-plugins [#5](https://gitea.whitlocktech.com/RunicGateway/servuo-plugins/pulls/5), link [#19](https://gitea.whitlocktech.com/RunicGateway/link/pulls/19), website [#116](https://gitea.whitlocktech.com/RunicGateway/website/pulls/116).
+**Design:** [`docs/link/v3.md` §8](../link/v3.md) — Protocol 3.0 Part B/3.
+**Depends on:** [`CLILOCS.md`](CLILOCS.md) — without a cliloc table, listings render as item ids.
+
+The marketplace is a searchable index of every player vendor on the shard: what
+each shop is selling, for how much, and where it is standing. It is the same set
+the in-game **Vendor Search** gump reads, offered from outside the game — so a
+player can find the vanquishing kryss they want before logging in, and someone
+who does not play at all can see that the economy exists.
+
+Page: `/site/market`, plus `/site/market/vendors/:serial` for one shop.
+
+## Three things the pages must say out loud
+
+Everything below follows from how the data is gathered, and each has a visible
+consequence the UI is required to surface.
+
+**1. The prices are not live.** The shard sweeps vendors **round-robin** — at
+most `Bridge.MarketSweepBatch` shops per tick — so a given shop can be a full
+cycle behind. The page carries a *"prices last refreshed N minutes ago"* banner
+driven by the **oldest** vendor row, not the newest: the one stale shop is the
+one that wastes somebody's trip.
+
+**2. A shop can be truncated.** `Bridge.MarketMaxListings` (250 by default) caps
+how many listings one frame carries. A commodity reseller with thousands of
+stacked resources is a real thing, and an uncapped frame for one is measured in
+megabytes. Over the cap the shop reports `truncated`, and the vendor page says
+*"showing 250 of 3,104 — this shop holds more than the shard publishes"* rather
+than presenting a partial shop as complete.
+
+**3. An item may have no name.** Items on the wire carry a cliloc id, not a name.
+On a shard whose operator has not converted a cliloc table
+([`CLILOCS.md`](CLILOCS.md)) the honest render is the item id — never an invented
+label, which would be indistinguishable from a real one.
+
+## Privacy: the player's own toggle wins
+
+Only vendors whose owner left the in-game **Vendor Search** flag ON are ever sent
+to the site. A player who hides their shop in game is hidden here too, and no
+admin setting overrides that. When they hide one that was already indexed, the
+shard emits `vendor.listing.remove` and the row is deleted — so revoking consent
+takes effect, it does not merely stop refreshing.
+
+Shop name, owner character name and location default to **Everyone**, because the
+stock Vendor Search gump already shows exactly that set to any player in game.
+They remain admin-configurable; see [`SHARD_VISIBILITY.md`](SHARD_VISIBILITY.md).
+Account names and website user ids never cross the wire at all.
+
+## How it is put together
+
+```
+ServUO                          uo-link sidecar               website
+──────                          ───────────────               ───────
+BridgeMarket.cs                 vendors table                 shard_vendors
+  round-robin sweep    ──────►    (whole frame blob)  ──────►  shard_vendor_items
+  per-vendor diff                 GET /market (paged)          + display_name
+  vendor.listing                                               resolved at ingest
+  vendor.listing.remove
+```
+
+**The shard side** walks at most `MarketSweepBatch` vendors per tick from a
+persistent cursor, diffs each against what it last published, and emits a whole
+frame for any shop that moved. Per-tick cost is therefore bounded by the batch,
+not by how many vendors the world holds — full coverage takes
+`ceil(vendors / batch) × MarketSweepSeconds`.
+
+**The sidecar** stores each frame whole and serves `GET /market`, its only paged
+read. It normalizes nothing and defines no audiences: it is a dumb forwarder, and
+search is the website's job.
+
+**The website** splits each frame into a vendor row and its listings, replacing
+that vendor's whole listing set inside one transaction (the frame is
+authoritative for that vendor, never a delta). Item names are resolved against
+the cliloc table **on the way in** and stored denormalized, which is what makes
+search-by-name possible and keeps the cliloc table off the hot path.
+
+## Operating it
+
+Everything is in `Config/Bridge.cfg` on the shard. There is nothing to configure
+on the website.
+
+| Setting | Default | What it does |
+|---|---|---|
+| `MarketEnabled` | `true` | Master switch. Off publishes nothing; the page shows an empty index. |
+| `MarketSweepSeconds` | `60` | Tick interval. |
+| `MarketSweepBatch` | `25` | Vendors inventoried per tick. Clamped 1..500. |
+| `MarketMaxListings` | `250` | Per-shop listing cap, after which `truncated`. Clamped 1..5000. |
+
+**Faster coverage vs. per-tick cost.** Lowering `MarketSweepSeconds` or raising
+`MarketSweepBatch` both refresh the index sooner and both cost more per tick.
+The expensive part is the item walk, which recurses into every container a vendor
+is selling — so a shard of big shops should raise the interval rather than the
+batch.
+
+`[bridge status` reports the sweep, including `lastMs` and `maxMs`:
+
+```
+market(enabled=True sweeps=42 scanned=108 emitted=27 removed=0 skipped=0
+       truncated=0 tracked=27 vendors=27 cursor=2 batch=25 lastMs=0.31 maxMs=15.40)
+```
+
+A tick over **50 ms** prints a rate-limited warning naming the knob:
+
+```
+[Bridge] market sweep took 82.4 ms (budget 50 ms) - lower Bridge.MarketSweepBatch (now 25) if this persists
+```
+
+Measured on a shard with 27 vendors × 40 listings (209k items, 43k mobiles):
+**15.4 ms** for the first cold tick of 25 vendors, **0.3 ms** in steady state —
+the diff is what makes an unchanged world nearly free. Note the arithmetic: 25
+*full* shops at the 250-listing cap is 6,250 items ≈ 95 ms, over budget. Real
+shops hold tens, which is why 25 is the default and why the warning exists.
+
+`[bridge sweepnow` runs one tick immediately; `[bridge reload` re-reads the
+settings above without a restart.
+
+## Names arriving late
+
+Item names come from the cliloc table, and the market sweep will **not** re-send
+an unchanged shop just because the site learned what its items are called. So a
+cliloc import triggers a bulk re-resolution of every stored listing — otherwise
+an operator who configures clilocs after the first sweep would see item ids until
+every shop happened to change on its own. It runs after a boot import and after
+an admin import, takes ~50 ms per thousand listings, and never throws: a failure
+leaves names exactly as they were.
+
+## API
+
+All under `/api/v1/public/shard`, gated by the `market` feature and
+**rate-limited** — these are the first genuinely expensive public reads on the
+site (a `LIKE` scan plus a `COUNT` over what is typically the largest `shard_*`
+table, reachable with no session).
+
+| Route | What |
+|---|---|
+| `GET /market` | Search. Returns **listings**, not vendors — "who sells X and for how much" is the question. `?q=&minPrice=&maxPrice=&itemId=&map=&region=&sort=&limit=&offset=`, `sort ∈ {price_asc, price_desc, recent}`. |
+| `GET /market/meta` | Index size, staleness, and which facets and regions actually hold vendors — so a client builds its filters without running a search it will discard. |
+| `GET /market/vendors/:serial` | One shop and its listings. **404** for a serial the index has never seen, which also covers a vendor since dismissed or hidden — to an anonymous caller those are the same answer. |
+
+`q` matches the resolved display name **or** the item's own literal name, because
+an item with a player-set name (most of what is worth searching for on a
+player-run shard) may carry a generic cliloc. `%` and `_` in a query are escaped:
+they are `LIKE` metacharacters, not SQL ones, so parameterization alone would let
+a search for `%` match every listing on the shard.
+
+Full schemas are in the OpenAPI spec (`ShardMarketPage`, `ShardMarketVendor`,
+`ShardMarketMeta`, `ShardMarketListing`, `ShardMarketLocation`).
+
+## Tables
+
+`shard_vendors` (one row per shop) and `shard_vendor_items` (one row per priced
+listing). Both are ingest-owned; nothing else writes to them. No foreign keys,
+in keeping with every other `shard_*` table — the ingest transaction is what
+keeps them consistent, and an FK would turn a malformed frame into a failed write
+rather than a dropped row.
+
+There is deliberately **no `payload` column** on `shard_vendors`, unlike the
+points board next door. The board's top-N is a fixed-size list read whole, so it
+lives in JSON; here the items *are* the searchable rows, so they are normalized
+and there is nothing left worth duplicating. The sidecar keeps the whole blob,
+because outage resilience is its job.
+
+`shard_vendor_items.display_name` is denormalized and indexed (alone, and
+composite with `price` for "cheapest matching X"). See "Names arriving late"
+above for how it is kept current.

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/PROJECT_TREE.md

@@ -0,0 +1,626 @@
+# Website — Project Tree
+
+> **Auto-generated.** This file is maintained by the `sync-project-tree` CI workflow in
+> the [`RunicGateway/website`](https://gitea.whitlocktech.com/RunicGateway/website) repository, which
+> opens a pull request here whenever the tracked file layout on `main` changes. Do not edit
+> by hand — changes will be overwritten by the next sync.
+
+A snapshot of the tracked files in the repository (build output, dependencies, and other
+git-ignored paths are excluded).
+
+```text
+website/
+├── .claude/
+│   └── launch.json
+├── .gitea/
+│   ├── ISSUE_TEMPLATE/
+│   │   ├── bug_report.md
+│   │   ├── config.yaml
+│   │   └── feature_request.md
+│   ├── scripts/
+│   │   └── gen_tree.py
+│   ├── workflows/
+│   │   ├── build-images.yml
+│   │   ├── pr-checks.yml
+│   │   ├── sonarqube.yml
+│   │   └── sync-project-tree.yml
+│   └── PULL_REQUEST_TEMPLATE.md
+├── bot/
+│   ├── src/
+│   │   ├── discord/
+│   │   │   ├── commands/
+│   │   │   │   ├── announce.command.js
+│   │   │   │   ├── autorole.command.js
+│   │   │   │   ├── ban.command.js
+│   │   │   │   ├── filter.command.js
+│   │   │   │   ├── filterallow.command.js
+│   │   │   │   ├── index.js
+│   │   │   │   ├── invite.command.js
+│   │   │   │   ├── kick.command.js
+│   │   │   │   ├── modlog.command.js
+│   │   │   │   ├── mute.command.js
+│   │   │   │   ├── news.command.js
+│   │   │   │   ├── ping.command.js
+│   │   │   │   ├── role.command.js
+│   │   │   │   ├── rolemenu.command.js
+│   │   │   │   ├── roles.command.js
+│   │   │   │   ├── schedule.command.js
+│   │   │   │   ├── warn.command.js
+│   │   │   │   ├── warnings.command.js
+│   │   │   │   └── wiki.command.js
+│   │   │   ├── discordManager.js
+│   │   │   ├── guildMemberAdd.js
+│   │   │   ├── guildMemberRemove.js
+│   │   │   ├── inviteTracker.js
+│   │   │   ├── messageFilter.js
+│   │   │   ├── modLog.js
+│   │   │   ├── newsAnnounce.js
+│   │   │   └── roleMenuHandler.js
+│   │   ├── filter/
+│   │   │   ├── filterCache.js
+│   │   │   ├── inviteFilter.js
+│   │   │   ├── normalize.js
+│   │   │   └── spamFilter.js
+│   │   ├── internal/
+│   │   │   ├── internal.controller.js
+│   │   │   ├── internal.routes.js
+│   │   │   └── requireInternalKey.js
+│   │   ├── invites/
+│   │   │   ├── inviteRotator.js
+│   │   │   └── inviteScheduler.js
+│   │   ├── model/
+│   │   │   ├── filterAllowlist.js
+│   │   │   ├── filterHits.js
+│   │   │   ├── filterWords.js
+│   │   │   ├── guildConfig.js
+│   │   │   ├── inviteLog.js
+│   │   │   ├── memberEvents.js
+│   │   │   ├── roleMenus.js
+│   │   │   ├── scheduledMessages.js
+│   │   │   ├── spamHits.js
+│   │   │   ├── tempRoles.js
+│   │   │   └── warnings.js
+│   │   ├── roles/
+│   │   │   └── tempRoleSweeper.js
+│   │   ├── scheduler/
+│   │   │   └── scheduler.js
+│   │   ├── site/
+│   │   │   └── siteApiClient.js
+│   │   ├── utils/
+│   │   │   ├── duration.js
+│   │   │   └── logger.js
+│   │   ├── app.js
+│   │   ├── bootstrap.js
+│   │   ├── brand.js
+│   │   ├── db.js
+│   │   └── server.js
+│   ├── .env.example
+│   ├── .gitignore
+│   ├── Dockerfile
+│   ├── package-lock.json
+│   └── package.json
+├── brand/
+│   └── README.md
+├── client/
+│   ├── public/
+│   │   ├── assets/
+│   │   │   └── img/
+│   │   │       ├── favicon.ico
+│   │   │       ├── hero-moon.png
+│   │   │       ├── runic-emblem.png
+│   │   │       └── uomysticmoon-main-hero.png
+│   │   └── robots.txt
+│   ├── src/
+│   │   ├── api/
+│   │   │   └── client.js
+│   │   ├── blocks/
+│   │   │   ├── types/
+│   │   │   │   ├── cta.jsx
+│   │   │   │   ├── divider.jsx
+│   │   │   │   ├── heading.jsx
+│   │   │   │   ├── image.jsx
+│   │   │   │   ├── quote.jsx
+│   │   │   │   ├── richText.jsx
+│   │   │   │   └── twoColumn.jsx
+│   │   │   ├── BlockRenderer.jsx
+│   │   │   ├── editorKit.jsx
+│   │   │   ├── index.js
+│   │   │   └── registry.js
+│   │   ├── components/
+│   │   │   ├── security/
+│   │   │   │   ├── RecoveryCodesDisplay.jsx
+│   │   │   │   ├── RecoveryCodesPanel.jsx
+│   │   │   │   ├── TrustedDevicesPanel.jsx
+│   │   │   │   └── TrustLimitModal.jsx
+│   │   │   ├── CharacterSheet.jsx
+│   │   │   ├── CharacterStats.jsx
+│   │   │   ├── CreateGameAccountForm.jsx
+│   │   │   ├── GameAccounts.jsx
+│   │   │   ├── HeroElement.jsx
+│   │   │   ├── MaintenanceGate.jsx
+│   │   │   ├── Modal.jsx
+│   │   │   ├── MoonDot.jsx
+│   │   │   ├── PageHeader.jsx
+│   │   │   ├── PageState.jsx
+│   │   │   ├── PlayersOnline.jsx
+│   │   │   ├── ProviderIcon.jsx
+│   │   │   ├── PublicLayout.jsx
+│   │   │   ├── RequireAuth.jsx
+│   │   │   ├── RequirePlayer.jsx
+│   │   │   ├── RichTextEditor.jsx
+│   │   │   ├── RoleGate.jsx
+│   │   │   ├── ShardAccountActions.jsx
+│   │   │   ├── SiteFooter.jsx
+│   │   │   ├── SiteHeader.jsx
+│   │   │   └── VendorSales.jsx
+│   │   ├── contexts/
+│   │   │   ├── AuthContext.jsx
+│   │   │   └── SiteContext.jsx
+│   │   ├── data/
+│   │   │   ├── cityCrests.js
+│   │   │   └── regionBuckets.js
+│   │   ├── lib/
+│   │   │   ├── format.js
+│   │   │   ├── heroLayout.js
+│   │   │   ├── shardEvents.js
+│   │   │   ├── useAsync.js
+│   │   │   ├── useShardFeatures.js
+│   │   │   └── useShardFeed.js
+│   │   ├── routes/
+│   │   │   ├── admin/
+│   │   │   │   ├── views/
+│   │   │   │   │   ├── AccountAdmin.jsx
+│   │   │   │   │   ├── ActivityAdmin.jsx
+│   │   │   │   │   ├── AdminCharacter.jsx
+│   │   │   │   │   ├── AdminCharacters.jsx
+│   │   │   │   │   ├── Appeals.jsx
+│   │   │   │   │   ├── AuthProvidersAdmin.jsx
+│   │   │   │   │   ├── BotActivityAdmin.jsx
+│   │   │   │   │   ├── Dashboard.jsx
+│   │   │   │   │   ├── DiscordBotAdmin.jsx
+│   │   │   │   │   ├── EmailDelivery.jsx
+│   │   │   │   │   ├── HeroEditor.jsx
+│   │   │   │   │   ├── HousesAdmin.jsx
+│   │   │   │   │   ├── InvitesAdmin.jsx
+│   │   │   │   │   ├── Moderation.jsx
+│   │   │   │   │   ├── ModerationUser.jsx
+│   │   │   │   │   ├── PageBuilder.jsx
+│   │   │   │   │   ├── PagesAdmin.jsx
+│   │   │   │   │   ├── PostEditor.jsx
+│   │   │   │   │   ├── PostsAdmin.jsx
+│   │   │   │   │   ├── SettingsAdmin.jsx
+│   │   │   │   │   ├── ShardAdmin.jsx
+│   │   │   │   │   ├── ShardOps.jsx
+│   │   │   │   │   ├── ShardVisibility.jsx
+│   │   │   │   │   ├── SpawnAtlas.jsx
+│   │   │   │   │   ├── UserDetail.jsx
+│   │   │   │   │   ├── UserEditor.jsx
+│   │   │   │   │   ├── UsersAdmin.jsx
+│   │   │   │   │   ├── WikiAdmin.jsx
+│   │   │   │   │   ├── WikiCategories.jsx
+│   │   │   │   │   ├── WikiEditor.jsx
+│   │   │   │   │   └── WikiHistory.jsx
+│   │   │   │   ├── AdminLayout.jsx
+│   │   │   │   └── AdminLogin.jsx
+│   │   │   ├── player/
+│   │   │   │   ├── AcceptInvite.jsx
+│   │   │   │   ├── ForgotPassword.jsx
+│   │   │   │   ├── PlayerAccount.jsx
+│   │   │   │   ├── PlayerAppeals.jsx
+│   │   │   │   ├── PlayerCharacter.jsx
+│   │   │   │   ├── PlayerCharacters.jsx
+│   │   │   │   ├── PlayerLogin.jsx
+│   │   │   │   ├── PlayerPortalLayout.jsx
+│   │   │   │   ├── PlayerRegister.jsx
+│   │   │   │   ├── PlayerShell.jsx
+│   │   │   │   └── ResetPassword.jsx
+│   │   │   ├── public/
+│   │   │   │   ├── About.jsx
+│   │   │   │   ├── Atlas.jsx
+│   │   │   │   ├── AtlasCreature.jsx
+│   │   │   │   ├── ChampSpawns.jsx
+│   │   │   │   ├── CmsPage.jsx
+│   │   │   │   ├── FiveOnFriday.jsx
+│   │   │   │   ├── Governors.jsx
+│   │   │   │   ├── Guilds.jsx
+│   │   │   │   ├── Houses.jsx
+│   │   │   │   ├── Leaderboards.jsx
+│   │   │   │   ├── Maintenance.jsx
+│   │   │   │   ├── Market.jsx
+│   │   │   │   ├── MarketVendor.jsx
+│   │   │   │   ├── News.jsx
+│   │   │   │   ├── Newsletter.jsx
+│   │   │   │   ├── NewsletterIssue.jsx
+│   │   │   │   ├── Portal.jsx
+│   │   │   │   ├── Rules.jsx
+│   │   │   │   ├── Screenshots.jsx
+│   │   │   │   ├── Shard.jsx
+│   │   │   │   ├── ShardActivity.jsx
+│   │   │   │   ├── Status.jsx
+│   │   │   │   └── Website.jsx
+│   │   │   └── wiki/
+│   │   │       ├── Wiki.jsx
+│   │   │       └── WikiArticle.jsx
+│   │   ├── styles/
+│   │   │   └── theme.css
+│   │   ├── App.jsx
+│   │   └── main.jsx
+│   ├── test/
+│   │   ├── apiClient.test.js
+│   │   ├── format.test.js
+│   │   ├── heroLayout.test.js
+│   │   ├── regionBuckets.test.js
+│   │   └── shardEvents.test.js
+│   ├── index.html
+│   ├── package-lock.json
+│   ├── package.json
+│   └── vite.config.js
+├── ntfy/
+│   └── server.yml
+├── scripts/
+│   ├── dev/
+│   │   ├── README.md
+│   │   ├── seed-sso-provider.js
+│   │   ├── sso-bridge-smoketest.js
+│   │   └── stub-idp.js
+│   └── sonar-test-reporter.mjs
+├── server/
+│   ├── db/
+│   │   ├── data/
+│   │   │   └── spawnAtlas.art.example.json
+│   │   ├── schema.sql
+│   │   └── seed.js
+│   ├── scripts/
+│   │   ├── importSpawnAtlas.js
+│   │   └── routeManifest.js
+│   ├── src/
+│   │   ├── auth/
+│   │   │   ├── providers/
+│   │   │   │   ├── base.provider.js
+│   │   │   │   ├── discord.provider.js
+│   │   │   │   ├── genericOidc.provider.js
+│   │   │   │   ├── google.provider.js
+│   │   │   │   ├── local.provider.js
+│   │   │   │   ├── oauth2.provider.js
+│   │   │   │   └── registry.js
+│   │   │   ├── session.middleware.js
+│   │   │   ├── session.service.js
+│   │   │   ├── ssoState.js
+│   │   │   ├── token.js
+│   │   │   └── usernamePolicy.js
+│   │   ├── blocks/
+│   │   │   ├── types/
+│   │   │   │   ├── cta.js
+│   │   │   │   ├── divider.js
+│   │   │   │   ├── heading.js
+│   │   │   │   ├── image.js
+│   │   │   │   ├── quote.js
+│   │   │   │   ├── richText.js
+│   │   │   │   └── twoColumn.js
+│   │   │   ├── index.js
+│   │   │   ├── propHelpers.js
+│   │   │   ├── registry.js
+│   │   │   ├── sanitizeBlocks.js
+│   │   │   └── validateBlocks.js
+│   │   ├── config/
+│   │   │   ├── brand.js
+│   │   │   ├── csp.js
+│   │   │   ├── notificationStreams.js
+│   │   │   └── version.js
+│   │   ├── middleware/
+│   │   │   ├── botScore.js
+│   │   │   ├── loginProtection.js
+│   │   │   ├── noindex.js
+│   │   │   ├── rateLimit.js
+│   │   │   ├── requireInternalKey.js
+│   │   │   ├── siteMode.js
+│   │   │   └── validate.js
+│   │   ├── model/
+│   │   │   ├── activity/
+│   │   │   │   ├── activity.db.js
+│   │   │   │   └── activity.model.js
+│   │   │   ├── announceJobs/
+│   │   │   │   ├── announceJobs.db.js
+│   │   │   │   ├── announceJobs.logic.js
+│   │   │   │   └── announceJobs.model.js
+│   │   │   ├── appeals/
+│   │   │   │   ├── appeals.db.js
+│   │   │   │   ├── appeals.model.js
+│   │   │   │   └── appeals.pure.js
+│   │   │   ├── authProviders/
+│   │   │   │   ├── authProviders.db.js
+│   │   │   │   └── authProviders.model.js
+│   │   │   ├── botConfig/
+│   │   │   │   ├── botConfig.db.js
+│   │   │   │   └── botConfig.model.js
+│   │   │   ├── emailConfig/
+│   │   │   │   ├── emailConfig.db.js
+│   │   │   │   └── emailConfig.model.js
+│   │   │   ├── invites/
+│   │   │   │   ├── invites.db.js
+│   │   │   │   └── invites.model.js
+│   │   │   ├── mobileAuthBridge/
+│   │   │   │   ├── mobileAuthBridge.db.js
+│   │   │   │   └── mobileAuthBridge.model.js
+│   │   │   ├── mobileSessions/
+│   │   │   │   ├── mobileSessions.db.js
+│   │   │   │   └── mobileSessions.model.js
+│   │   │   ├── moderation/
+│   │   │   │   ├── moderation.db.js
+│   │   │   │   ├── moderation.model.js
+│   │   │   │   └── moderation.pure.js
+│   │   │   ├── modNotes/
+│   │   │   │   ├── modNotes.db.js
+│   │   │   │   └── modNotes.model.js
+│   │   │   ├── notificationSubs/
+│   │   │   │   ├── notificationSubs.db.js
+│   │   │   │   └── notificationSubs.model.js
+│   │   │   ├── pages/
+│   │   │   │   ├── pages.db.js
+│   │   │   │   ├── pages.model.js
+│   │   │   │   └── reservedSlugs.js
+│   │   │   ├── passwordResets/
+│   │   │   │   ├── passwordResets.db.js
+│   │   │   │   └── passwordResets.model.js
+│   │   │   ├── posts/
+│   │   │   │   ├── posts.db.js
+│   │   │   │   └── posts.model.js
+│   │   │   ├── pushDevices/
+│   │   │   │   ├── pushDevices.db.js
+│   │   │   │   └── pushDevices.model.js
+│   │   │   ├── recoveryCodes/
+│   │   │   │   ├── recoveryCodes.db.js
+│   │   │   │   └── recoveryCodes.model.js
+│   │   │   ├── revokedSessions/
+│   │   │   │   ├── revokedSessions.db.js
+│   │   │   │   └── revokedSessions.model.js
+│   │   │   ├── settings/
+│   │   │   │   ├── settings.db.js
+│   │   │   │   └── settings.model.js
+│   │   │   ├── shardAtlas/
+│   │   │   │   ├── shardAtlas.db.js
+│   │   │   │   └── shardAtlas.model.js
+│   │   │   ├── shardClilocs/
+│   │   │   │   ├── shardClilocs.db.js
+│   │   │   │   └── shardClilocs.model.js
+│   │   │   ├── shardEvents/
+│   │   │   │   ├── shardEvents.db.js
+│   │   │   │   └── shardEvents.model.js
+│   │   │   ├── shardLinks/
+│   │   │   │   ├── shardLinks.db.js
+│   │   │   │   └── shardLinks.model.js
+│   │   │   ├── shardMarket/
+│   │   │   │   ├── shardMarket.db.js
+│   │   │   │   └── shardMarket.model.js
+│   │   │   ├── shardState/
+│   │   │   │   ├── shardState.db.js
+│   │   │   │   └── shardState.model.js
+│   │   │   ├── shardVisibility/
+│   │   │   │   ├── shardVisibility.db.js
+│   │   │   │   └── shardVisibility.model.js
+│   │   │   ├── trustedDevices/
+│   │   │   │   ├── trustedDevices.db.js
+│   │   │   │   └── trustedDevices.model.js
+│   │   │   ├── uoLinkConfig/
+│   │   │   │   ├── uoLinkConfig.db.js
+│   │   │   │   └── uoLinkConfig.model.js
+│   │   │   ├── userIdentities/
+│   │   │   │   ├── userIdentities.db.js
+│   │   │   │   └── userIdentities.model.js
+│   │   │   ├── users/
+│   │   │   │   ├── users.db.js
+│   │   │   │   └── users.model.js
+│   │   │   ├── wiki/
+│   │   │   │   ├── wiki.db.js
+│   │   │   │   ├── wiki.links.js
+│   │   │   │   └── wiki.model.js
+│   │   │   └── singletonConfigDb.js
+│   │   ├── router/
+│   │   │   ├── v1/
+│   │   │   │   ├── admin/
+│   │   │   │   │   ├── account.controller.js
+│   │   │   │   │   ├── account.router.js
+│   │   │   │   │   ├── activity.router.js
+│   │   │   │   │   ├── admin.controller.js
+│   │   │   │   │   ├── authProviders.controller.js
+│   │   │   │   │   ├── authProviders.router.js
+│   │   │   │   │   ├── botActivity.controller.js
+│   │   │   │   │   ├── botActivity.router.js
+│   │   │   │   │   ├── dashboard.router.js
+│   │   │   │   │   ├── discordBot.controller.js
+│   │   │   │   │   ├── discordBot.router.js
+│   │   │   │   │   ├── email.router.js
+│   │   │   │   │   ├── emailConfig.controller.js
+│   │   │   │   │   ├── imageUpload.js
+│   │   │   │   │   ├── index.js
+│   │   │   │   │   ├── invites.controller.js
+│   │   │   │   │   ├── invites.router.js
+│   │   │   │   │   ├── moderation.controller.js
+│   │   │   │   │   ├── moderation.router.js
+│   │   │   │   │   ├── pages.controller.js
+│   │   │   │   │   ├── pages.router.js
+│   │   │   │   │   ├── posts.router.js
+│   │   │   │   │   ├── settings.router.js
+│   │   │   │   │   ├── shard.router.js
+│   │   │   │   │   ├── shardAtlas.controller.js
+│   │   │   │   │   ├── shardClilocs.controller.js
+│   │   │   │   │   ├── shardOps.controller.js
+│   │   │   │   │   ├── shardVisibility.controller.js
+│   │   │   │   │   ├── uoLink.controller.js
+│   │   │   │   │   ├── uoLink.router.js
+│   │   │   │   │   ├── uploads.router.js
+│   │   │   │   │   ├── users.router.js
+│   │   │   │   │   ├── usersShard.controller.js
+│   │   │   │   │   └── wiki.router.js
+│   │   │   │   ├── auth/
+│   │   │   │   │   ├── auth.controller.js
+│   │   │   │   │   ├── index.js
+│   │   │   │   │   ├── invite.controller.js
+│   │   │   │   │   ├── invite.router.js
+│   │   │   │   │   ├── login.router.js
+│   │   │   │   │   ├── loginGuards.js
+│   │   │   │   │   ├── me.routes.js
+│   │   │   │   │   ├── mobile.controller.js
+│   │   │   │   │   ├── mobile.routes.js
+│   │   │   │   │   ├── mobileSso.controller.js
+│   │   │   │   │   ├── mobileSso.routes.js
+│   │   │   │   │   ├── notifications.controller.js
+│   │   │   │   │   ├── notifications.routes.js
+│   │   │   │   │   ├── password.router.js
+│   │   │   │   │   ├── passwordReset.controller.js
+│   │   │   │   │   ├── register.router.js
+│   │   │   │   │   ├── session.router.js
+│   │   │   │   │   ├── sso.controller.js
+│   │   │   │   │   ├── sso.routes.js
+│   │   │   │   │   └── trustDevice.helper.js
+│   │   │   │   ├── internal/
+│   │   │   │   │   ├── internal.controller.js
+│   │   │   │   │   └── internal.routes.js
+│   │   │   │   ├── player/
+│   │   │   │   │   ├── account.router.js
+│   │   │   │   │   ├── appeals.controller.js
+│   │   │   │   │   ├── appeals.router.js
+│   │   │   │   │   ├── index.js
+│   │   │   │   │   ├── shard.controller.js
+│   │   │   │   │   └── shard.router.js
+│   │   │   │   ├── public/
+│   │   │   │   │   ├── atlas.controller.js
+│   │   │   │   │   ├── atlas.router.js
+│   │   │   │   │   ├── index.js
+│   │   │   │   │   ├── pages.router.js
+│   │   │   │   │   ├── posts.router.js
+│   │   │   │   │   ├── public.controller.js
+│   │   │   │   │   ├── shard.controller.js
+│   │   │   │   │   ├── shard.router.js
+│   │   │   │   │   ├── site.router.js
+│   │   │   │   │   └── wiki.router.js
+│   │   │   │   └── v1.router.js
+│   │   │   ├── api.router.js
+│   │   │   ├── cspReport.controller.js
+│   │   │   └── wellKnown.controller.js
+│   │   ├── utils/
+│   │   │   ├── announceWorker.js
+│   │   │   ├── auth.js
+│   │   │   ├── botInternalClient.js
+│   │   │   ├── botInternalKey.js
+│   │   │   ├── clilocParse.js
+│   │   │   ├── clilocSource.js
+│   │   │   ├── db.js
+│   │   │   ├── logger.js
+│   │   │   ├── mailer.js
+│   │   │   ├── newsGump.js
+│   │   │   ├── pushDispatch.js
+│   │   │   ├── sanitizeHtml.js
+│   │   │   ├── secretBox.js
+│   │   │   ├── shardBroadcast.js
+│   │   │   ├── shardIngest.js
+│   │   │   ├── shardSales.js
+│   │   │   ├── shardVisibility.js
+│   │   │   ├── spawnAtlasParse.js
+│   │   │   ├── spawnAtlasSource.js
+│   │   │   ├── totp.js
+│   │   │   ├── trustProxy.js
+│   │   │   ├── uoLinkClient.js
+│   │   │   └── uoLinkSocket.js
+│   │   ├── app.js
+│   │   ├── internalApp.js
+│   │   └── server.js
+│   ├── swagger/
+│   │   ├── swagger-output.json
+│   │   └── swagger.js
+│   ├── test/
+│   │   ├── _helper.js
+│   │   ├── adminTrustedDevices.test.js
+│   │   ├── adminUserShard.test.js
+│   │   ├── announceJobs.test.js
+│   │   ├── appeals.pure.test.js
+│   │   ├── appeals.test.js
+│   │   ├── appLinks.test.js
+│   │   ├── atlasController.test.js
+│   │   ├── authController.test.js
+│   │   ├── authMe.test.js
+│   │   ├── authTrustedDevice.test.js
+│   │   ├── botInternalKey.test.js
+│   │   ├── botScore.test.js
+│   │   ├── clilocParse.test.js
+│   │   ├── clilocSource.test.js
+│   │   ├── csp.test.js
+│   │   ├── emailConfig.model.test.js
+│   │   ├── honeypot.test.js
+│   │   ├── inviteController.test.js
+│   │   ├── invites.test.js
+│   │   ├── loginProtection.test.js
+│   │   ├── mailer.test.js
+│   │   ├── mobileAuthBridge.model.test.js
+│   │   ├── mobileDeviceSessions.test.js
+│   │   ├── mobileSession.test.js
+│   │   ├── mobileSsoBridge.test.js
+│   │   ├── moderation.model.test.js
+│   │   ├── moderation.test.js
+│   │   ├── newsGump.test.js
+│   │   ├── notificationsRoutes.test.js
+│   │   ├── pages.model.test.js
+│   │   ├── passwordResetController.test.js
+│   │   ├── passwordResets.test.js
+│   │   ├── playerAccounts.test.js
+│   │   ├── playerRouteAccess.test.js
+│   │   ├── providers.test.js
+│   │   ├── publicBrand.test.js
+│   │   ├── publicController.test.js
+│   │   ├── publicShardOnline.test.js
+│   │   ├── publicVersion.test.js
+│   │   ├── pushDispatch.test.js
+│   │   ├── recoveryCodes.test.js
+│   │   ├── registry.test.js
+│   │   ├── requireInternalKey.test.js
+│   │   ├── routeManifest.test.js
+│   │   ├── secretBox.test.js
+│   │   ├── selfTrustedDevices.test.js
+│   │   ├── session.test.js
+│   │   ├── shardBroadcast.visibility.test.js
+│   │   ├── shardControllerPublic.test.js
+│   │   ├── shardIngest.champsPages.test.js
+│   │   ├── shardIngest.market.test.js
+│   │   ├── shardIngest.points.test.js
+│   │   ├── shardIngest.protocol2.test.js
+│   │   ├── shardIngest.ruleset.test.js
+│   │   ├── shardMarket.model.test.js
+│   │   ├── shardState.governorTerms.test.js
+│   │   ├── shardState.model.test.js
+│   │   ├── shardVisibility.test.js
+│   │   ├── spawnAtlas.parse.test.js
+│   │   ├── spawnAtlas.source.test.js
+│   │   ├── ssoCallback.test.js
+│   │   ├── ssoState.test.js
+│   │   ├── ssoTrustedDevice.test.js
+│   │   ├── totp.test.js
+│   │   ├── trustedDevices.test.js
+│   │   ├── trustProxy.test.js
+│   │   ├── uoLinkClient.test.js
+│   │   └── usernamePolicy.test.js
+│   ├── tools/
+│   │   └── cliloc-export/
+│   │       ├── clilocexport.csproj
+│   │       ├── Program.cs
+│   │       └── README.md
+│   ├── .env.example
+│   ├── package-lock.json
+│   ├── package.json
+│   ├── routes.guards.json
+│   └── routes.manifest.json
+├── .dockerignore
+├── .env.example
+├── .env.uomysticmoon.example
+├── .gitignore
+├── CODE_OF_CONDUCT.md
+├── CONTRIBUTING.md
+├── CONTRIBUTORS.md
+├── docker-compose.dev.yml
+├── docker-compose.yml
+├── Dockerfile
+├── LICENSE.md
+├── package.json
+├── README.md
+├── SECURITY.md
+└── sonar-project.properties
+```

website/SHARD_VISIBILITY.md

@@ -0,0 +1,158 @@
+# Shard visibility — who sees which shard data
+
+**Status:** Built (Protocol 3.0 Part A). Admin → Shard Visibility.
+**Audience:** shard owners and admins.
+**Companion to** [`../link/v3.md`](../link/v3.md) §3 (the design) and
+[`BACKEND_DESIGN.md`](BACKEND_DESIGN.md) §6 (the security contract).
+
+The website surfaces a lot of live shard data. What your players, your staff and the anonymous
+internet may each see is **yours to decide**, per feature, from Admin → Shard Visibility.
+
+Nothing changes until you change it: every setting ships at the value that reproduces how the site
+behaved before this panel existed.
+
+---
+
+## 1. The audience ladder
+
+Five rungs. Each one includes everyone below it.
+
+| Rung | In the UI | Who that is |
+|---|---|---|
+| `anonymous` | **Everyone** | Anyone at all, signed in or not. |
+| `logged_in` | **Signed in** | Any registered account, whether or not they've linked a game account. |
+| `player` | **Linked players** | Accounts with a linked in-game account. **Staff always qualify**, linked or not. |
+| `staff` | **Staff** | Admins and moderators. |
+| `admin` | **Admins only** | Admins. |
+
+Two notes that surprise people:
+
+- **`editor` is a content role, not a shard role.** Editors write news and wiki pages; they get no
+  shard privilege from that. An editor is treated by link status like any other member. This matches
+  the rest of the site, where shard staff powers are admin-or-moderator.
+- **Staff satisfy `player` without linking.** Otherwise an admin would be locked out of surfaces
+  they'd gated to players, which is how the `/player/*` routes already behave.
+
+## 2. What you can set per feature
+
+**Enabled.** Off means gone. The feature's pages return “not found”, not “forbidden” — a disabled
+feature doesn't advertise that it exists.
+
+**Who can see it.** The minimum rung, from the ladder above.
+
+**Live updates.** Whether this feature pushes changes to open pages in real time. Turning it off
+doesn't break the page; it just refreshes on load instead of updating in place.
+
+**Sensitive fields.** Some features expose a field that deserves its own rung — you can publish the
+board while holding back one column. See the table in §3.
+
+## 3. The features, and their defaults
+
+| Feature | What it exposes | Default | Sensitive fields |
+|---|---|---|---|
+| **Shard status** | Connection state, online count, gold-supply series | Everyone | — |
+| **Activity feed** | Deaths, kills, skill gains, quests, logins | Everyone | — |
+| **Champion spawns** | The live champion / mini-champ / sea-boss board | Everyone | — |
+| **Guilds** | Guild rosters, alliances, leaders | Everyone | — |
+| **Town governors** | City Loyalty governors, elections, term history | Everyone | — |
+| **Houses / IDOC** | Houses in danger | Everyone | House owner → Staff · House price → Staff |
+| **Players online** | Population aggregate, staff-online widget | Everyone | In-game location → Staff |
+| **Shard rules** | Skill/stat caps, house limits, vet rewards, the ruleset | Everyone | Connect address → Everyone |
+| **Spawn atlas** | Bestiary and spawn locations (static content) | Everyone | — |
+| **Leaderboards** | Point and loyalty standings | Everyone | Character names → Everyone |
+| **Marketplace** | The shard-wide player-vendor index | Everyone, **live updates off** | Vendor owner name → Everyone · Vendor owner character id → Everyone · In-game location → Everyone |
+
+**Why the marketplace ships with live updates off.** A live feed of every vendor's full inventory
+would be the single largest thing the site sends. No page needs it — the marketplace is a search over
+stored data with a “prices last refreshed N minutes ago” stamp. Turn it on only if you want it.
+
+**Why the marketplace's fields default to Everyone.** A vendor's shop name, its owner's character
+name and where it is standing are *already* visible to every player in game: the stock Vendor Search
+gump surfaces exactly that set to anyone who opens it. Publishing them on the site is not a new
+disclosure. They stay configurable because a shard may still prefer to keep its economy behind a
+login — and because "already public in game" is a judgement about your shard, not ours.
+
+**Location is one setting covering four things.** Hiding it removes the facet, the coordinates, the
+region *and* the house name together. That is deliberate: those are four ways of saying the same
+thing, and a setting that hid the coordinates while publishing the house name would not have hidden
+anything.
+
+**Hiding the owner name also hides the owner character id.** They are separate settings so you can
+be explicit, but leaving the id published while hiding the name achieves nothing — the leaderboards
+and guild boards resolve that same id back to a character name. Set both.
+
+**What hiding a vendor cannot do.** Only vendors whose owner left the in-game *Vendor Search* flag ON
+are ever sent to the site, so a player who hides their shop in game is hidden here too — and no
+setting on this page can override that. It works the other way as well: these settings control who
+sees the index, not whether players can find each other's shops in game.
+
+**Why house owner/price default to Staff.** The public Houses page has always been a "where are the
+falling houses" board — location only. Owner and price are the staff view. That split is preserved.
+
+## 4. What you cannot change
+
+Two rules are enforced in code and are not settings. Attempting to set them returns an error rather
+than silently ignoring you.
+
+**1. Game account names and website user ids are admin-only, always.**
+`acct` and `webId` never appear below the admin rung on any surface. A character *name* is visible in
+game to anyone standing next to them; the **account** behind it is not, and neither is the website
+user it's linked to. Publishing those would disclose something the shard itself doesn't, and would
+tie a player's in-game identity to their forum identity without their consent.
+
+This rule matches the *meaning* of a field, not one spelling of it. Some responses nest the player
+who owns a record (`leader.acct`); others flatten it into the row (`ownerAcct`, `leaderWebId`,
+`governorAcct`). Every one of those is locked, and the admin API refuses to configure any of them —
+so a new response shape can't quietly reopen the hole by naming the field differently.
+
+**2. Unknown event kinds are never broadcast below admin.**
+The live stream maps each event kind to a feature. A kind with no mapping — a new event from a shard
+plugin the site doesn't know yet, say — goes to admins only. It fails closed. This is what keeps the
+stream safe by default when the shard starts sending something new: the worst case is that staff see
+it and players don't, never the reverse.
+
+## 5. How it's enforced
+
+Three places, one config:
+
+- **Page and API requests** are checked before the handler runs, and the response is then stripped of
+  any field above the caller's rung.
+- **The live stream** resolves a viewer's rung once, when they connect, and freezes it for that
+  connection — a long-open page can't gain privilege because something changed underneath it. Each
+  event is then gated and stripped per viewer, so two people watching the same page can legitimately
+  receive different versions of the same event, or one of them nothing.
+- **Navigation** hides links a viewer can't follow, so they don't hit a wall. This is presentation
+  only — the gate is server-side either way.
+
+**Stored history answers the same way the live stream does.** The activity feed reads from the event
+log rather than the live stream, but it resolves the *same* question against the *same* config: which
+kinds you may read, and which fields survive. So moving a feature up a rung hides it from the history
+as well as the stream — there is no back door where yesterday's copy of an event is more revealing
+than today's.
+
+One deliberate asymmetry: turning **live updates** off for a feature stops the push, not the reading.
+The marketplace ships this way — its history and its pages are public, only the firehose is off.
+
+Changes take effect within about five seconds, **including on streams that are already open**. You
+don't need to restart anything.
+
+If the database is briefly unreachable, the site falls back to the built-in defaults — the pre-v3
+behavior — rather than to "everything is public".
+
+## 6. Worked examples
+
+**"I want a private shard — nothing public until people register."**
+Set every feature to **Signed in**. Anonymous visitors still get the site itself; the shard data
+disappears from the nav.
+
+**"Publish the market, but don't tie vendors to players."**
+Marketplace → Everyone, with **Vendor owner name** → Staff. Prices, items and locations stay public;
+who owns each vendor doesn't.
+
+**"Leaderboards for members only."**
+Leaderboards → **Linked players**. Anyone who's linked a game account sees the standings; drive-by
+visitors don't.
+
+**"Let players see house owners."**
+Houses → Everyone, **House owner** → Linked players. Note this is a real disclosure: house ownership
+is visible in game, but the website makes it searchable in a way the game doesn't.

website/SPAWN_ATLAS.md

@@ -0,0 +1,355 @@
+# Spawn atlas
+
+**Status:** Complete on `edge` — data pipeline in website [#112](https://gitea.whitlocktech.com/RunicGateway/website/pulls/112), API + pages in website [#113](https://gitea.whitlocktech.com/RunicGateway/website/pulls/113).
+**Design:** [`docs/link/v3.md` §6](../link/v3.md) — Protocol 3.0 Part C.
+
+The spawn atlas is a browsable catalogue of what the shard *contains*: which
+creatures spawn, where, how many, and which champion altars are configured. It
+answers "where do I find a lizardman?" with **"Shrines, Yew, Isamu-Jima"** rather
+than with a list of raw coordinates.
+
+## Two things that shape the whole design
+
+**The shard's ServUO tree is the single source of truth.** Nothing is
+precomputed and committed to the repository. A shard's maps change over its
+lifetime — facets get added, replaced, or renamed — and a snapshot in the repo
+would silently drift from the world players actually see. The atlas is therefore
+re-derived from the tree **on every server boot**.
+
+**Facets are not a fixed list.** Nothing in the codebase names Felucca, Trammel,
+or any other stock facet. The facet set is whatever the shard's own files
+declare, discovered at parse time. A shard running entirely custom maps gets
+exactly the same treatment as a stock one, with no code change.
+
+## What it is not
+
+The atlas is **static shard content, not live shard state.**
+
+- It does **not** come from the sidecar. Nothing here touches the bridge, and
+  there is no event kind, no wire change and no `PROTOCOL_VERSION` bump for it.
+  Part C is website-only.
+- It stays fully populated while the shard is down.
+- Its champion table (`shard_champion_spawns`) is the *configured roster* —
+  "there is an Unholy Terror altar in Deceit". The live `champ.update` feed in
+  `shard_champs` is the separate, sidecar-fed answer to "it is on level 3 right
+  now". Both exist; do not conflate them.
+
+Routes live at `/api/v1/public/atlas`, deliberately **not** under `/shard`,
+because `/shard/*` means sidecar-dependent.
+
+## Configuring the tree
+
+The website needs to be able to *read* the ServUO tree — same host, a bind mount,
+or a shared volume. Two ways to point at it, the setting winning over the
+environment:
+
+| Source | Notes |
+|---|---|
+| `spawn_atlas_servuo_path` setting | Admin-editable; changes take effect on the next refresh without a redeploy |
+| `SERVUO_PATH` env var | The deploy-time default, since the path usually describes a mount the deployment sets up |
+
+With neither set the atlas is simply skipped — the site runs normally without
+one.
+
+## The boot path
+
+On every start the server hashes the source files and compares them against what
+is loaded. Unchanged (the normal case on a restart) costs one read pass, ~120 ms,
+and no database write. A real change costs a ~400 ms parse and a reload.
+
+Two contracts govern it:
+
+**1. It never blocks startup.** No configured path, an unreadable mount, a
+malformed file, a database error — every one is caught and logged, and the site
+comes up serving whatever atlas it already had.
+
+**2. A facet disappearing is never applied automatically.** Losing a facet looks
+exactly like a half-copied or mid-update tree, and boot cannot tell that apart
+from a real map change. That refresh is *staged* for a human instead. Everything
+else — new facets, renamed regions, changed spawns — applies immediately, since
+none of it can destroy something an operator would miss.
+
+```
+boot
+ └─ path configured?            no ──▶ skip
+     └─ tree readable?          no ──▶ warn, carry on
+         └─ hashes changed?     no ──▶ done (nothing parsed)
+             └─ parse
+                 └─ a facet would be removed?
+                      no ──▶ import
+                     yes ──▶ stage for admin review; atlas unchanged
+```
+
+### Approving or rejecting a staged refresh
+
+Only the *decision* is stored, never the parsed world — a few KB of source hashes
+plus the facet diff. Approving **re-parses** the tree, so what lands matches the
+tree at approval time rather than at boot, and a multi-megabyte blob never sits
+in the database.
+
+A rejection is remembered against those exact source hashes, so a declined
+refresh does not re-prompt on every restart. Change the tree and the hashes
+differ, which asks again.
+
+From **Admin → Spawn Atlas**, or from the CLI:
+
+```bash
+cd website/server
+npm run atlas:import -- --status     # what is loaded, and what is pending
+npm run atlas:import -- --approve    # apply the staged refresh
+npm run atlas:import -- --reject     # keep the current atlas, dismiss it
+```
+
+## The CLI
+
+The server refreshes itself on boot, so this is for applying a map change
+*without* a restart, and for the approve/reject flow above.
+
+```bash
+npm run atlas:import                       # import if the tree differs
+npm run atlas:import -- --servuo <path>    # override the path for this run
+npm run atlas:import -- --force            # reimport even if unchanged
+```
+
+`--servuo` is a per-run override and deliberately does **not** persist — changing
+where the atlas permanently reads from is an admin action, not a side effect of a
+one-off import.
+
+## Sources
+
+| File | Count (stock ServUO 57.4) | Used for |
+|---|---|---|
+| `Spawns/*.xml` | 13 files, ~10.5 MB | Every spawner: location, size, delays, time-of-day, creature types |
+| `Data/Regions.xml` | 129 KB, nested | Named regions and their rectangles |
+| `Data/Locations/*.xml` | 6 files | Landmarks (dungeon levels, town markers) |
+| `Config/ChampionSpawns.xml` | 4.8 KB | Configured champion altars |
+
+**A stock tree has 13 spawn files but only 6 facets.** `Eodon.xml`,
+`GravewaterLake.xml`, `TreasuresOfKotl.xml` and the other named-area files hold
+TerMur/Trammel points. The facet always comes from each record's own `<Map>`,
+never from the file name.
+
+## How a coordinate becomes a place name
+
+This is the transform the atlas exists for, in `resolveRegion()`:
+
+1. The highest-`priority` named region whose rectangle contains the point. Ties
+   break toward the **smallest** rect, so a specific room wins over the
+   dungeon-wide rect enclosing it.
+2. Otherwise the nearest landmark within the landmark radius (200 tiles by
+   default), labelled by its **group** ("Covetous"), not its individual marker
+   ("Level 1").
+3. Otherwise `"Wilderness"`.
+
+The radius cap in step 2 is what keeps step 3 reachable. Without it the nearest
+landmark is always *some* landmark however far away, and open countryside gets
+labelled with a dungeon on the far side of the map.
+
+Against stock ServUO this resolves **83.2%** of points (5,369 of 6,455): 3,681 by
+region, 1,688 by landmark, 1,086 Wilderness.
+
+## Three quirks in the source data
+
+Each of these is silent if unhandled — the atlas still builds, it is just wrong.
+
+**Facet names disagree between sources.** `Data/Locations/*.xml` spells them
+`Ter Mur` and `Tokuno Islands`, while `<Map>` and `<Facet name>` say `TerMur` and
+`Tokuno`. Unreconciled, the landmark bucket is keyed differently from the points
+looking it up, so the fallback never fires and every unregioned spawn on those
+facets reads "Wilderness".
+
+This is reconciled **by matching, not by a lookup table** — there is no list of
+facet names anywhere. `facetKey()` collapses spelling differences (lowercase,
+alphanumerics only), and `resolveFacetName()` matches a loose spelling against
+the canonical set discovered from the shard's own spawn and region data, by exact
+key then by prefix in either direction. A name matching nothing keeps its own
+name: forcing a wrong match would file a real custom facet's landmarks under the
+wrong facet, which is worse than leaving it alone.
+
+**Spawn type tokens carry XmlSpawner directives.** The `<Objects2>` type is not
+always a bare class name:
+
+```
+Fairy,{RND,4,8}      alchemist/z/-50      Agralem/Name/Agralem
+GargishRouser,1      greatape,true        GargishRefugee/hue/34532
+```
+
+Taken literally these invent creatures that do not exist *and* split real ones in
+two, because `Fairy` and `Fairy,{RND,4,8}` slug apart into separate entries. 71 of
+845 were affected. Everything from the first `/` or `,` is stripped, leaving 800
+real creatures.
+
+**Case is inconsistent across files.** The same creature is `Lizardman` in one
+file and `lizardman` in another. Slugging collapses them correctly, but the
+display name is chosen deterministically — most common spelling wins, ties break
+to the more capitalised form, then alphabetically — because otherwise it would
+depend on file read order and change on an unrelated restart.
+
+## Tables
+
+All are **import-owned**: a refresh empties and reloads them in one transaction,
+so a failed reload leaves the previous atlas intact rather than a half-loaded
+world. Nothing else writes to them and nothing holds a foreign key to them — no
+FKs at all, consistent with every other `shard_*` table. Full column listings in
+[`BACKEND_DESIGN.md`](BACKEND_DESIGN.md).
+
+| Table | Rows (stock) | Notes |
+|---|---|---|
+| `shard_spawn_creatures` | 800 | `slug` PK; `total` = sum of each type's own max; nullable `art` |
+| `shard_spawn_points` | 6,455 | `spawn_range`, since `range` is reserved in MariaDB |
+| `shard_spawn_point_types` | 23,927 | The many-to-many; one spawner commonly carries six types |
+| `shard_regions` | 387 | Flattened out of the nesting; `rects` JSON |
+| `shard_landmarks` | 558 | `grp`, since `group` is reserved in SQL |
+| `shard_champion_spawns` | 25 | Configured altars, not the live feed |
+| `shard_atlas_meta` | 1 | Singleton; source hashes, for the change check |
+| `shard_atlas_pending` | 0–1 | Singleton; a staged refresh awaiting admin review |
+
+`shard_spawn_creatures.name` carries a plain `INDEX`, deliberately **not
+`FULLTEXT`**: ~800 rows makes a `LIKE` scan free, and FULLTEXT's minimum token
+length would break searches for names like "orc".
+
+The reload uses `DELETE`, not `TRUNCATE` — `TRUNCATE` is DDL in MariaDB and would
+implicitly commit, defeating the all-or-nothing guarantee. Point ids are assigned
+explicitly rather than left to `AUTO_INCREMENT`, because the join rows need them
+and `conn.batch()` reports no usable `insertId`.
+
+## Artwork — operator-supplied, never shipped
+
+**This project ships no creature art and no extraction tooling, and never will.**
+UO sprites live in the operator's own client `.mul`/`.uop` files. They are the
+operator's, not ours to redistribute.
+
+The atlas is fully functional as text. `shard_spawn_creatures.art` is nullable
+and is NULL on every fresh import; pages render without images, which is the
+normal and supported state, not a degraded one.
+
+An operator who wants art — step-by-step, with the UOFiddler side spelled out, in
+[`UOFIDDLER.md`](UOFIDDLER.md) §Part 2:
+
+1. Extracts it from **their own** client files (UOFiddler, ClassicUO tooling, or
+   any art extractor).
+2. Drops the images under `server/uploads/atlas/`.
+3. Copies `server/db/data/spawnAtlas.art.example.json` to `spawnAtlas.art.json`
+   and maps creature slugs to file names.
+4. Restarts, or runs `npm run atlas:import -- --force`.
+
+Both `spawnAtlas.art.json` and `server/uploads/` are gitignored, so neither the
+map nor the images can be committed by accident.
+
+## Code layout
+
+| File | Role |
+|---|---|
+| `src/utils/spawnAtlasParse.js` | **Pure and fs-free** parsers, so CI covers them with no ServUO tree. Zero dependencies. |
+| `src/utils/spawnAtlasSource.js` | The only thing that reads a ServUO tree; shared by the boot path and the CLI |
+| `src/model/shardAtlas/shardAtlas.db.js` | The one-transaction replace |
+| `src/model/shardAtlas/shardAtlas.model.js` | The refresh decision, staging, approve/reject |
+| `scripts/importSpawnAtlas.js` | Thin CLI over the model |
+
+Parsing notes:
+
+- `Regions.xml`, `Locations/*.xml` and `ChampionSpawns.xml` genuinely nest, and
+  get a small hand-rolled **subset** tokenizer — elements, attributes,
+  self-closing tags, comments, the XML declaration, CDATA, and the five
+  predefined entities plus numeric refs. It is not a general-purpose XML parser
+  and must not be reused as one.
+- The ~10.5 MB of `Spawns/*.xml` never touches that tokenizer. Those records are
+  flat, so they get a streaming regex sweep instead; a DOM would allocate a node
+  per element across ~40 fields on every record to keep 14 of them. **Do not put
+  the Points files through a DOM parser.**
+- `<Objects2>` is `Type:MX=n:SB=…` segments joined by `:OBJ=`. Split on `:OBJ=`
+  *first* — a naive `split(':')` shreds it. A single Trammel point carries six
+  types.
+- **Respawn delays are stored in two different units, per record.** XmlSpawner
+  writes `MinDelay`/`MaxDelay` in minutes, and switches to seconds only when a
+  spawner's delay does not divide into whole minutes — flagging that with
+  `DelayInSec` on the same record. A `5` therefore means five *minutes* on one
+  spawner and five *seconds* on the next, and both are plausible respawn times,
+  so a reader assuming either unit is silently wrong about the other. Stock
+  ServUO 57.4 has ~170 second-flagged spawners out of 6,455. The parser
+  normalises everything to **seconds**; the API and UI carry seconds throughout.
+
+### The parser version
+
+`spawnAtlasSource.js` exports `PARSER_VERSION`, stored in `shard_atlas_meta`
+alongside the source hashes and bumped whenever the parser derives **different
+data from identical files** — a fixed misreading, a new field, a changed unit.
+
+A refresh re-derives when the tree changed **or** the parser did. Hashing the
+tree alone would be a trap: an install whose maps never change would keep serving
+whatever an older build derived, indefinitely, and a deploy that corrects the
+parse would never reach the data. A version mismatch counts as drift, so the
+correction lands on the next boot without an operator having to know it happened.
+
+## The API
+
+Everything is served from MariaDB. Nothing on this path touches the sidecar, so
+the pages stay complete while the shard is down — which is why the routes sit at
+`/api/v1/public/atlas` and **not** under `/public/shard`, where a prefix means
+"sidecar-dependent". Unlike `/shard/*`, they *are* `siteMode`-gated, like
+`/posts` and `/wiki`: a bestiary is site content and follows site content's rules.
+
+Every route carries `requireFeature('atlas')` — **404** when an admin has
+disabled the feature (its pages must not reveal that it exists) and **403** when
+the caller sits below its configured audience. The default is `anonymous`, so the
+gates are inert until an admin changes something. Responses are field-projected
+like every other shard read; `atlas` declares no sensitive fields today, and the
+projection call is there so the first one that does is covered by construction
+rather than by a retrofit ([`v3.md` §3.6.1](../link/v3.md)).
+
+| Route | Answers |
+|---|---|
+| `GET /atlas/creatures?q=&facet=&limit=&offset=` | The bestiary, most numerous first, paginated with an unpaginated `total` |
+| `GET /atlas/creatures/:slug?facet=&points=` | One creature: `places`, `spawners`, `alsoHere` |
+| `GET /atlas/regions?facet=&q=` | Named regions and their rectangles |
+| `GET /atlas/landmarks?facet=&q=` | Points of interest, labelled by `group` |
+| `GET /atlas/champions?facet=` | The configured altar roster |
+| `GET /atlas/meta` | Facets, counts and when the atlas was parsed |
+
+Two shapes worth knowing:
+
+- **`places` is the aggregate the atlas exists for.** "Lizardman → Shrines,
+  Isamu-Jima, Yew", grouped in SQL rather than by summing 6,455 point rows in
+  Node. `spawners` is the raw list underneath it, bounded, with
+  `spawnersTruncated` saying when it was cut.
+- **`points` is a COUNT, `spawners` is the LIST.** The two are named apart
+  deliberately: the same key meaning a number on the search route and an array on
+  the detail route is the kind of thing a client only discovers in production.
+
+`GET /atlas/meta` reports the **game world only**. The ServUO path, the per-file
+hashes and any pending refresh describe the operator's filesystem, and live on
+the admin route instead.
+
+A facet is never validated against a list — nothing in the codebase names one.
+`?facet=` is length-bounded and matched exactly, so an unknown name returns an
+empty result rather than an error. The filter is an `EXISTS` over the points and
+deliberately not a JSON path or `JSON_SEARCH` built from caller input: that
+function treats `%` and `_` as wildcards, which would make `?facet=%` match
+everything.
+
+## The admin panel
+
+**Admin → Spawn Atlas** (`/admin/shard-atlas`, admin-only — it reads a path on
+the server's filesystem and replaces every atlas table, which is closer to a
+deploy action than to moderation).
+
+| Route | Does |
+|---|---|
+| `GET /admin/shard/atlas` | Status: path, readable, drift, counts, facets, pending |
+| `POST /admin/shard/atlas/import` | Import now; `{ force: true }` ignores the hash gate |
+| `POST /admin/shard/atlas/approve` | Apply a staged refresh, facet loss and all |
+| `POST /admin/shard/atlas/reject` | Keep the current atlas; remember the decision |
+| `PUT /admin/shard/atlas/path` | Point the atlas at a different tree |
+
+Three behaviours that are deliberate:
+
+- **An unreadable tree is a 200, not a 500.** `refresh()` reports outcomes rather
+  than throwing, because the boot path must never be stopped by a bad tree, and
+  that contract is preserved at the API. The panel says *"The tree could not be
+  read: …"*; a 500 would say only that something broke.
+- **Setting the path does not import.** Moving the mount and reloading the world
+  are separate decisions, and an operator fixing a typo should not have a
+  multi-thousand-row replace happen under them. The response carries fresh status
+  so the panel can offer the import as the next step.
+- **Every action is written to the admin activity log** (`shard.atlas.import` /
+  `.approve` / `.reject` / `.path`).

website/TRUSTED_DEVICES_MFA.md

@@ -0,0 +1,259 @@
+# Trusted Devices & MFA Improvements — Design & Implementation Plan
+
+> Reference plan for the trusted-device + MFA hardening work. Approved 2026-07-21.
+> This document is the contract the implementation builds against; keep it in sync
+> with `BACKEND_DESIGN.md` (§3 schema, §4 API, §6 security) as code lands.
+
+## 1. Goal & scope
+
+Reduce 2FA friction without weakening the second-factor boundary, and close the
+2FA-lockout gap. Four deliverables:
+
+1. **Trusted devices** — an opt-in "Trust this device" that lets a browser or the
+   Android app **skip the TOTP step** (never the password) on future logins for a
+   fixed window.
+2. **Recovery / backup codes** — single-use codes generated at 2FA enrollment so a
+   user who loses their authenticator can self-recover instead of needing an admin
+   reset.
+3. **Admin-managed revocation** — staff can view and revoke a user's trusted
+   devices and reset their MFA, with full audit logging (**backend endpoints _and_
+   admin front-end screens**).
+4. **Step-up (password) for sensitive operations** — reusing the existing
+   `currentPassword`-verification pattern; disabling TOTP keeps its stronger
+   current-TOTP-code requirement.
+
+Touches `website/` (server + client), `docs/`, and `android-app/` (plan only in
+this pass). **No** `link/` or `servuo-plugins/` change — no wire-protocol impact.
+
+### Approved decisions
+
+| Decision | Value |
+|---|---|
+| Trust duration | **30 days** (matches mobile refresh-token lifetime) |
+| Roles eligible | **All roles** (no staff carve-out) |
+| Opt-in model | **Explicit "Trust this device" checkbox, default off** |
+| Recovery codes | **10 codes**, shown **once**, single-use |
+| Trusted-device cap | **10 per user, no silent pruning** (see §5) |
+| Trust-token hashing | **sha256** |
+| Recovery-code hashing | **bcrypt** (cost 10) |
+
+## 2. Current state (starting point)
+
+- **One session service** (`server/src/auth/session.service.js`) backs web (JWT
+  `httpOnly` cookie, 1d) and mobile (15m access JWT + 30d opaque refresh token).
+  `requireAuth` accepts either via `token.extractToken()`.
+- **TOTP** is opt-in per user (`users.totp_secret` / `totp_enabled`), demanded on
+  **every** login. Web uses a staged 5-min `stage:'totp'` challenge; mobile uses a
+  single-request `401 { totpRequired }`. **No recovery codes** exist today.
+- **Device tracking exists only on mobile** (`mobile_refresh_tokens` rows with
+  `device_name` / `device_hash` / `user_agent` / `last_used_at`). Web JWTs are
+  stateless with no per-session row.
+- **Revocation is mature:** `revoked_sessions` (jti denylist) + `tokens_valid_after`
+  (per-user cutoff) for web; per-token rows + `revokeAllForUser` for mobile.
+- **No trusted-device or step-up concept exists anywhere.**
+
+## 3. Hashing rationale
+
+The repo already splits hashing by secret entropy, and this plan follows it:
+
+- **sha256** — every high-entropy machine-generated opaque token
+  (`mobile_refresh_tokens`, `mobile_auth_codes`, `user_invites`, `password_resets`,
+  SSO PKCE). **Trusted-device tokens use sha256:** they are 256-bit random values
+  (nothing to brute-force) looked up **by a `token_hash UNIQUE` index**, which
+  requires a deterministic hash — bcrypt's per-row salt would break the lookup and
+  truncates input at 72 bytes.
+- **bcrypt (`bcryptjs`, cost 10)** — the repo uses it only for **passwords**, the
+  one human-chosen low-entropy secret. **Recovery codes use bcrypt:** they are a
+  human-typed, lower-entropy fallback credential that grants a login (the closest
+  analogue to a password), and there is no hash-lookup constraint — we fetch the
+  identified user's ≤10 code rows and `bcrypt.compare` each, exactly like password
+  verification.
+
+## 4. Database (additive, idempotent — matches `schema.sql` style)
+
+### `trusted_devices`
+Pattern-identical to `mobile_refresh_tokens`; stores only the token hash.
+
+| Column | Type | Notes |
+|---|---|---|
+| id | INT PK AUTO_INCREMENT | |
+| user_id | INT NOT NULL | FK → users, `ON DELETE CASCADE` |
+| token_hash | CHAR(64) NOT NULL UNIQUE | sha256 hex of the opaque trust token |
+| platform | ENUM('web','mobile') NOT NULL DEFAULT 'web' | |
+| device_name | VARCHAR(100) NULL | friendly label |
+| device_hash | VARCHAR(32) NULL | best-effort UA+IP, **display only** |
+| user_agent | VARCHAR(255) NULL | |
+| created_at | DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP | |
+| last_used_at | DATETIME NULL | stamped when trust is honored at login |
+| expires_at | DATETIME NOT NULL | created_at + 30d |
+| revoked_at | DATETIME NULL | |
+
+Indices: `idx_td_user (user_id)`, `idx_td_expires (expires_at)`.
+
+### `mobile_auth_sessions.trust_device` (SSO bridge)
+
+| Column | Type | Notes |
+|---|---|---|
+| trust_device | TINYINT(1) NOT NULL DEFAULT 0 | user ticked "trust this device" on the Custom Tab TOTP form |
+
+A **boolean only**. It records the user's choice so `POST /auth/mobile/sso/exchange`
+knows to mint the app's own trust token over that authenticated app→server call; the
+token itself is never written here (only its sha256 reaches `trusted_devices`). Set
+only while the session is still `pending` and unexpired, for the same reason
+`completeSession` is guarded — a replayed TOTP post must not re-arm a consumed
+session.
+
+### `recovery_codes`
+| Column | Type | Notes |
+|---|---|---|
+| id | INT PK AUTO_INCREMENT | |
+| user_id | INT NOT NULL | FK → users, `ON DELETE CASCADE` |
+| code_hash | VARCHAR(72) NOT NULL | **bcrypt** hash of one code |
+| used_at | DATETIME NULL | single-use marker |
+| created_at | DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP | |
+
+Index: `idx_rc_user (user_id)`.
+
+No new `users` column: password change/reset and TOTP-disable **bulk-revoke**
+`trusted_devices` rows and **delete** `recovery_codes` (consistent with
+`revokeAllForUser`), so no "trust epoch" column is needed.
+
+## 5. Trusted-device cap — no silent pruning
+
+Cap = **10**. A shared `assertUnderTrustCap(userId)` guards both entry points (the
+login/TOTP trust path and the authenticated "trust this device" path). On the 11th
+attempt the backend **refuses to create the row** and returns
+`409 { error: 'trusted_device_limit', devices: [...] }`. Login itself still
+succeeds — only the trust marker is withheld. The web client then renders a modal
+**in the same visual pattern as the TOTP entry flow** that:
+
+1. shows the existing trusted devices,
+2. requires revoking ≥1 before continuing,
+3. completes via `POST /auth/me/trusted-devices` (trust current device), and
+4. offers **Cancel**, which returns without creating any trust entry.
+
+## 6. API additions
+
+### Auth (login paths)
+- `POST /auth/login` — after password verify, if a valid unrevoked `rg_trust`
+  cookie matches a live `trusted_devices` row for this user → **skip TOTP**, issue
+  the session, log `auth.login.trusted_device`, stamp `last_used_at`. Otherwise
+  unchanged (`{ totpRequired, challenge }`).
+- `POST /auth/login/totp` — gains optional `trustDevice` + `deviceName`, and
+  accepts a **recovery code** as an alternative to the TOTP code (single-use). On
+  success with `trustDevice`, mint the opaque trust token, set the `rg_trust`
+  cookie, insert the row (subject to the cap → `409` signal).
+- `POST /auth/mobile/login` — gains `trustDevice` / `recoveryCode`; returns a
+  `trustToken` the app stores in EncryptedSharedPreferences and replays on a later
+  login to skip TOTP. Same cap behavior.
+
+#### SSO login paths
+
+SSO is **not** exempt: an account with TOTP on is asked for a code after a
+Google/Discord sign-in exactly as it is after a password one, and a trusted device
+skips that code exactly the same way. (Originally SSO consulted trust nowhere, so a
+user who signed in with an external identity was asked for a code on *every* sign-in
+no matter how many times they had ticked "trust this device".)
+
+- `GET /auth/sso/:provider/callback` — once the account is resolved and before a
+  TOTP challenge is staged, resolve the presented trust (cookie, or `X-Trust-Token`)
+  and, if it belongs to **this** user, skip the code, stamp `last_used_at`, and log
+  `auth.login.trusted_device`. The first factor is the IdP authentication that just
+  succeeded, so this is the same posture as the password path. A store error falls
+  through to the challenge — fail **closed** to asking for the code.
+- `POST /auth/sso/totp` — gains optional `trustDevice` + `deviceName`, mints the
+  trust and sets the `rg_trust` cookie on success. At the cap the sign-in still
+  completes and the response carries `{ trustLimitReached, devices }`, matching
+  `POST /auth/login/totp`. Recovery codes remain password-login only: this step
+  verifies an authenticator code against the staged challenge.
+
+**How this reaches the Android app.** The app's SSO runs in a Custom Tab, which
+shares the system browser's cookie jar, so both halves land in the same place: the
+`rg_trust` cookie set on the Custom Tab TOTP form is presented back on the *next*
+app SSO sign-in and skips the code — no app change, and no trust token smuggled
+through a start URL where it would leak into query strings and logs.
+
+To cover the app's **native** password login on the same device as well, ticking
+the box also sets `mobile_auth_sessions.trust_device` (a boolean — never the
+token), and `POST /auth/mobile/sso/exchange` then mints a `platform: 'mobile'`
+trust and returns `{ trustToken }` in its JSON body. Minting at exchange time is
+deliberate: it is an authenticated app→server call, so the raw token never travels
+in the deep link and never rests in the bridge row. One tick therefore produces two
+independently-revocable rows (the browser and the app) — which is honest, since they
+are two distinct credentials on one device. If the user is at the cap, the exchange
+simply returns no token; it never turns a successful sign-in into an error.
+
+### Self-service (`/auth/me/*`, `requireAuth`, any role)
+- `GET /auth/me/trusted-devices` — list active trusted devices (never tokens).
+- `POST /auth/me/trusted-devices` — trust the current browser/device (cap-checked).
+- `DELETE /auth/me/trusted-devices/:id` — revoke one (ownership-scoped).
+- `DELETE /auth/me/trusted-devices` — revoke all ("untrust everywhere").
+- `POST /auth/me/account/recovery-codes/generate` — **password step-up required**;
+  returns the codes **once**.
+- `GET /auth/me/account/recovery-codes/status` — remaining count only.
+
+### Admin (`requireRole('admin')`)
+- `GET /admin/users/:id/trusted-devices` — list a user's trusted devices.
+- `DELETE /admin/users/:id/trusted-devices/:deviceId` — revoke one.
+- `DELETE /admin/users/:id/trusted-devices` — revoke all.
+- MFA reset control (revoke trust + disable TOTP + clear recovery codes).
+
+## 7. Cookie / refresh / JWT interaction
+
+- New **`rg_trust`** cookie: `httpOnly`, `sameSite=Lax`, `secure` per-request
+  (reuse `cookieSecure`), `path=/`, `maxAge` 30d, opaque 256-bit base64url,
+  sha256-hashed server-side. **Separate from the session cookie and deliberately
+  survives logout** (so the next login skips 2FA); only untrust / password-change /
+  TOTP-disable revoke it.
+- **JWTs stay stateless and unchanged** — trust is a server-side cookie+row, never
+  a JWT claim, so it remains revocable.
+- **Refresh flow untouched** — trust is consulted only at the login/password step,
+  never at token refresh; the two stores stay independent.
+
+## 8. Security & invalidation
+
+- Trust **only ever gates the second factor**; password is always required.
+- Recovery-code entry reuses the login brute-force stack (backoff + bot scoring +
+  rate limits); recovery codes are single-use.
+- **Password change/reset and TOTP-disable clear trust and recovery codes.**
+- **Audit logging** via existing `activity.log` / `activity_log`:
+  `auth.login.trusted_device`, `account.trusted_device.add` / `.revoke` /
+  `.revoke_all`, `account.recovery_codes.generate`, `account.recovery_code.consume`,
+  and admin `admin.trusted_device.revoke` / `.revoke_all`, `admin.user.totp.reset`
+  — each with actor, target user, and device id in `detail`.
+
+## 9. Backwards compatibility
+
+Fully additive. With no `rg_trust` cookie the behavior is exactly today's (TOTP
+every login). Recovery codes exist only for users who generate them. No existing
+session or login flow changes shape. New tables via `CREATE TABLE IF NOT EXISTS`
+and columns via `ALTER TABLE … ADD COLUMN IF NOT EXISTS`.
+
+## 10. Implementation roadmap
+
+1. **Schema + models** — `trusted_devices` (sha256, cap-checked) + `recovery_codes`
+   (bcrypt); `.db.js` / `.model.js` pairs mirroring `mobileSessions`.
+2. **Session service** — trust-token mint/sha256/verify + recovery-code
+   generate/bcrypt-verify/consume helpers (pure, DB-free); shared
+   `assertUnderTrustCap()`.
+3. **Web login** — trust-cookie skip in `/auth/login`; `trustDevice` / recovery
+   handling + cap `409` in `/auth/login/totp`; set/clear `rg_trust`.
+4. **Mobile login** — `trustDevice` / `trustToken` / `recoveryCode`, same cap.
+5. **Self-service + admin backend** — `/auth/me/trusted-devices*` + recovery-code
+   endpoints; `/admin/users/:id/trusted-devices*` + MFA reset (all admin-gated).
+6. **Invalidation wiring** — password change/reset & TOTP-disable revoke trust +
+   delete recovery codes.
+7. **Web client UI** — "Trust this device" checkbox; cap-reached TOTP-styled modal
+   (revoke-to-continue / cancel); user Trusted Devices + Recovery Codes screens.
+8. **Admin front-end UI** — admin Trusted Devices management & revocation screens
+   (per-user list, revoke one / revoke all, MFA reset), wired to step 5.
+9. **Android** — record the app-side trust/recovery flow in
+   `docs/android/PLAN.md`; app implementation sequenced after the backend lands.
+10. **OpenAPI + docs** — `#swagger.*` on every new/modified route + regenerate
+    `server/swagger/swagger-output.json`; update `BACKEND_DESIGN.md` §3/§4/§6.
+11. **Automated tests** — trusted-device login skip (valid / missing / expired /
+    revoked), token mint+hash, recovery-code single-use consume + wrong-code
+    backoff, cap `409` behavior, revocation (self + admin), invalidation on
+    password-change / TOTP-disable, and permission checks (admin routes reject
+    non-admins; self routes ownership-scoped); web client pure-logic tests; Android
+    JVM DTO/repository tests.

website/UOFIDDLER.md

@@ -0,0 +1,282 @@
+# Extracting from your own UO client (UOFiddler)
+
+**Audience:** the shard operator, once, at setup time.
+**Related:** [`CLILOCS.md`](CLILOCS.md) (why the cliloc conversion is unavoidable),
+[`SPAWN_ATLAS.md`](SPAWN_ATLAS.md) (where creature art fits).
+
+Two features read data that **only exists inside a UO client**, and a UO client's
+files are EA's, not ours to redistribute. So neither this repo nor any image we
+publish can ship them — the operator extracts from **their own** client, once,
+and points the site at the result.
+
+| Feature | What it needs | Required? | Without it |
+|---|---|---|---|
+| **Item / title names** ([`CLILOCS.md`](CLILOCS.md)) | `Cliloc.enu`, converted | No | Names render as raw ids — `id 1023721` instead of *quarter staff* |
+| **Creature art** ([`SPAWN_ATLAS.md`](SPAWN_ATLAS.md)) | Sprites from `.mul`/`.uop` | No | Atlas pages render as text, which is the normal state |
+
+**Both are optional and neither is load-bearing.** A shard that never does any of
+this is fully supported. Do part one and skip part two if art is not worth your
+time — they share only the tool.
+
+Everything you extract stays **outside the repository**: the converted cliloc
+file lives at a path you choose, and `spawnAtlas.art.json` plus `server/uploads/`
+are gitignored, so none of it can be committed by accident.
+
+---
+
+## Part 0 — Get UOFiddler
+
+[UOFiddler](https://github.com/polserver/UOFiddler) is the community client-file
+editor. We use it because its `Ultima.dll` already contains the cliloc
+decompressor, maintained by people who do this for a living.
+
+1. Download the latest release zip from
+   <https://github.com/polserver/UOFiddler/releases/latest> — one asset, named
+   `UOFiddler-<version>.zip` (4.22.2 is ~2 MB).
+2. Extract it. The zip contains a single top-level folder, and the two files that
+   matter are at **its root**:
+
+   ```
+   UOFiddler-4.22.2/
+     Ultima.dll        ← the decompressor (Part 1 needs this path)
+     UoFiddler.exe     ← the GUI (Part 2 needs this)
+     plugins/
+     …
+   ```
+
+3. **Runtime:** UOFiddler 4.22.2 is built for **.NET 10**. Running `UoFiddler.exe`
+   needs the .NET 10 **Desktop** Runtime (Windows only); loading `Ultima.dll` from
+   the converter in Part 1 needs the .NET 10 runtime. Install from
+   <https://dotnet.microsoft.com/download/dotnet/10.0>.
+
+### Finding your client files
+
+The cliloc file is in your **UO client installation directory**, not in your
+ServUO tree — the shard server has no copy of it. Look for `Cliloc.enu` (English;
+the other seven are `chs`, `cht`, `deu`, `esp`, `fra`, `jpn`, `kor`) beside
+`art.mul` / `artLegacyMUL.uop`. The EA Classic Client's default location is:
+
+```
+C:\Program Files (x86)\Electronic Arts\Ultima Online Classic\
+```
+
+**If your shard distributes its own patched client to players, use that copy.**
+Any cliloc edits you shipped to players are then already in the base table and
+you need no overlay for them (see [`CLILOCS.md`](CLILOCS.md) §Shard-added and
+shard-edited items).
+
+---
+
+## Part 1 — Convert the cliloc table
+
+**Goal:** turn the client's compressed `Cliloc.enu` into a file the site can
+read, and point the site at it.
+
+The site cannot read `Cliloc.enu` directly. Every modern client compresses it
+(the "Mythic" container), and so does ServUO's own bundled `Ultima.StringList` —
+which is why the shard cannot supply names on our behalf either. The full
+reasoning is in [`CLILOCS.md`](CLILOCS.md) §Why the operator has to convert the
+file; this section is just the procedure.
+
+Two routes. **The bundled tool is the recommended one** — the GUI export needs a
+fixup step, described below.
+
+### Route A — the bundled converter (recommended)
+
+Needs a .NET SDK (any version 8 or newer — the project targets `net8.0` and rolls
+forward, so whatever you have works) **plus** the .NET 10 runtime from Part 0,
+which is what actually loads `Ultima.dll`.
+
+```bash
+cd website/server/tools/cliloc-export
+dotnet build -c Release
+
+# plain binary — recommended, exact
+dotnet run -c Release -- \
+  "/path/to/UOFiddler-4.22.2/Ultima.dll" \
+  "/path/to/UO client/Cliloc.enu" \
+  /srv/uo-data/clilocs.plain
+
+# or tab-delimited text, if you want to eyeball or hand-edit it
+dotnet run -c Release -- \
+  "/path/to/UOFiddler-4.22.2/Ultima.dll" \
+  "/path/to/UO client/Cliloc.enu" \
+  /srv/uo-data/clilocs.tsv --tsv
+```
+
+Expected output for a stock English client:
+
+```
+wrote 123490 entries to /srv/uo-data/clilocs.plain (maxTextBytes=12150, skippedOversize=0)
+```
+
+**Sanity-check that number.** A stock `Cliloc.enu` is ~123,000 entries. A few
+hundred means it read something else and you should not ship the result. The
+tool exits non-zero and says `no entries were written — is that a cliloc file?`
+when it gets nothing at all.
+
+The conversion runs on whatever machine has the client (usually Windows), and the
+site reads the output wherever it runs — so **copy the output file to the server**
+if those are different machines. It is a single self-contained file (~5 MB); the
+`--tsv` form is larger but diff-able.
+
+<details>
+<summary>Errors you may hit</summary>
+
+| Message | Cause |
+|---|---|
+| `Ultima.StringList not found — is that really UOFiddler's Ultima.dll?` | First argument points at some other `Ultima.dll` (ServUO ships one too — it is **not** the same assembly and cannot do this) |
+| `You must install .NET to run this application` | Missing the .NET 10 runtime from Part 0 step 3 |
+| `Unexpected Ultima.StringList API` | UOFiddler older than 4.21 |
+| `usage: clilocexport …` | Fewer than three arguments |
+
+</details>
+
+### Route B — the UOFiddler GUI
+
+Use this if you would rather not install a .NET SDK. **It needs one extra step**,
+so do not skip the fixup.
+
+1. Launch `UoFiddler.exe` and point it at your client directory when it asks
+   (or **Options → Path Settings**).
+2. Open the **Cliloc** tab and use its **export to CSV** action.
+3. It writes `CliLoc.csv` to UOFiddler's configured output path, in **three**
+   columns with a header row:
+
+   ```
+   Number;Text;Flag
+   1023721;quarter staff;0
+   ```
+
+4. **Strip the trailing flag column.** The site's text parser reads
+   `number<TAB|,|;>text`, so that third field is otherwise absorbed into the name
+   and every item on the site renders as `quarter staff;0`.
+
+   ```bash
+   sed -E 's/;[0-9]+$//' CliLoc.csv > clilocs.csv
+   ```
+
+   ```powershell
+   Get-Content CliLoc.csv |
+     ForEach-Object { $_ -replace ';\d+$','' } |
+     Set-Content -Encoding utf8 clilocs.csv
+   ```
+
+   The header row needs no removal — a line whose first field is not an integer
+   is skipped. Blank entries (`1005008;`) survive the fixup correctly and are
+   dropped at import, as intended.
+
+5. Copy `clilocs.csv` to the server.
+
+**Why the fixup is not just done for us:** the parser already handles
+`number,flag,text` — the flag in the *middle*, which is what several exports
+emit. UOFiddler puts it at the *end*, where it is indistinguishable from a name
+that genuinely ends in `;0`. One `sed` on the operator's side beats a parser
+heuristic that would corrupt real names.
+
+### Point the site at it
+
+Two ways, the setting winning over the environment:
+
+| Where | How |
+|---|---|
+| **Admin → Shard → cliloc path** | Takes effect on the next refresh, no redeploy |
+| `UO_CLIENT_PATH` env var | The deploy-time default |
+
+The value may be **the file itself or a directory to search** — both are natural
+answers to "where is it", and overlays are picked up either way.
+
+Setting the path deliberately does **not** import as a side effect. Click
+**Import** (or `POST /api/v1/admin/shard/clilocs/import`) to load it.
+
+### Verify
+
+`GET /api/v1/admin/shard/clilocs`, or the Admin → Shard panel, reports what each
+source contributed:
+
+```json
+"sources": [
+  { "label": "clilocs.plain", "kind": "base", "entries": 123490, "added": 123490, "overrode": 0 }
+]
+```
+
+Roughly **67,500 rows stored** from a stock table is correct — about half a
+cliloc table is empty strings for ids the client reserves and never uses.
+
+Then load any character sheet with equipment: items should show names rather than
+`id 1023721`.
+
+<details>
+<summary>What a refusal means</summary>
+
+A bad file answers `200` with a `status` and a named reason, not a `500` — you
+need to be told *which file* to fix.
+
+| `code` | Meaning |
+|---|---|
+| `COMPRESSED` | You pointed at the raw client `Cliloc.enu`. Convert it — this whole page. |
+| `TRUNCATED` | Half-copied file. Re-copy; the loaded table is untouched. |
+| `EMPTY` | A text source with no parseable rows — the file is named in the reason. |
+| `status: needsReview` + `missingSources` | A previously-loaded source has vanished (unmounted volume? deliberate deletion?). Nothing changes until you re-import with `{ "approve": true }`. |
+
+</details>
+
+### Custom items — do *not* re-export for these
+
+Shard-added items carry ids no client table has. Drop a small delimited file in a
+`custom/` directory beside the base file and re-import:
+
+```
+/srv/uo-data/
+  clilocs.plain            ← base, from this guide
+  custom/
+    01-uomysticmoon.tsv    ← your additions and overrides
+```
+
+Files are read in sorted order and **later sources win**, so an overlay both adds
+new ids and overrides stock ones you have re-purposed. **Adding one item never
+means re-exporting a 5 MB client file.** Details in [`CLILOCS.md`](CLILOCS.md).
+
+---
+
+## Part 2 — Creature art for the spawn atlas (optional)
+
+**Goal:** put sprites on atlas pages. Purely cosmetic — the atlas is fully
+functional as text, and `art` is NULL on every fresh import.
+
+**This project ships no art and no art-extraction tooling, and never will.**
+
+1. In `UoFiddler.exe` (paths configured as in Route B step 1), open the
+   **Animations** tab for creature sprites — or **Items** for object art — find
+   the creature, and export as PNG. Right-click an entry for its export options,
+   or use the tab's *Export All* action for a batch. (4.22.2 added an export
+   option to the Animation tab's thumbnail list, which is the convenient one
+   here.)
+2. Put the images under `server/uploads/atlas/`.
+3. Copy `server/db/data/spawnAtlas.art.example.json` to `spawnAtlas.art.json` in
+   the same directory and map creature slugs to file names:
+
+   ```json
+   {
+     "lizardman": "lizardman.png",
+     "orc": "orc.png"
+   }
+   ```
+
+   **Keys are the slugs the atlas API reports**, derived from the type names in
+   your own shard's `Spawns/*.xml` — read them off the atlas rather than guessing.
+   A creature with no entry renders without art, which is the default.
+
+4. Restart, or `npm run atlas:import -- --force`.
+
+The art map is re-read on every atlas refresh, so adding one image is an edit plus
+a refresh. Both `spawnAtlas.art.json` and `server/uploads/` are gitignored.
+
+---
+
+## Licensing, briefly
+
+UO's strings and sprites are EA's. Extracting from **your own** client for
+**your own** shard is the arrangement here; redistributing the extracted files is
+not something this project does or can advise on. That is the whole reason this
+page exists instead of a download link.

website/WIKI_UPGRADE.md

@@ -54,7 +54,7 @@ auth model (admin/editor — no new roles, no public contributions).
 | Schema | flat `wiki_pages(slug,title,body,updated_by,timestamps)` | [server/db/schema.sql:31](server/db/schema.sql) |
 | Model | thin CRUD by slug | [server/src/model/wiki/wiki.db.js](server/src/model/wiki/wiki.db.js), [wiki.model.js](server/src/model/wiki/wiki.model.js) |
 | Public API | `GET /public/wiki`, `GET /public/wiki/:slug` | [public.controller.js:53](server/src/router/v1/public/public.controller.js) |
-| Admin API | `GET/POST/PUT/DELETE /admin/wiki[...]` | [admin.controller.js:163](server/src/router/v1/admin/admin.controller.js), [admin.routes.js:68](server/src/router/v1/admin/admin.routes.js) |
+| Admin API | `GET/POST/PUT/DELETE /admin/wiki[...]` | [admin.controller.js:163](server/src/router/v1/admin/admin.controller.js), [wiki.router.js](server/src/router/v1/admin/wiki.router.js) |
 | Public UI | card grid (hardcoded blurbs + Roman numerals), article w/ auto-TOC | [Wiki.jsx](client/src/routes/wiki/Wiki.jsx), [WikiArticle.jsx](client/src/routes/wiki/WikiArticle.jsx) |
 | Admin UI | raw-HTML `<textarea>` modal | [WikiAdmin.jsx](client/src/routes/admin/views/WikiAdmin.jsx), [WikiEditor.jsx](client/src/routes/admin/views/WikiEditor.jsx) |
 | API client | `api.wiki`, `api.admin.*Wiki` | [client/src/api/client.js:52](client/src/api/client.js) |
@@ -196,7 +196,7 @@ centralized error handler unchanged. **Every write logs to `activity_log`**
 
 ### 4.4 Image uploads
 
-Generalize the existing screenshot upload (multer config in [admin.routes.js:17](server/src/router/v1/admin/admin.routes.js))
+Generalize the existing screenshot upload (multer config now in [admin/imageUpload.js](server/src/router/v1/admin/imageUpload.js))
 into a shared `POST /admin/uploads` returning `{ url: "/uploads/<file>" }`, reused by both
 the post editor and the wiki editor. Same size/mime limits. No new storage —
 served from the existing `uploads/` volume.

website/api-route-inventory.json

@@ -0,0 +1,875 @@
+{
+  "$comment": "Generated route inventory - the authoritative freeze of the URL surface. Regenerate with `npm run routes:manifest` in website/server; a domain-split PR must produce a zero-line diff here.",
+  "public": [
+    {
+      "method": "GET",
+      "path": "/.well-known/assetlinks.json"
+    },
+    {
+      "method": "POST",
+      "path": "/api/csp-report"
+    },
+    {
+      "method": "GET",
+      "path": "/api/docs.json"
+    },
+    {
+      "method": "GET",
+      "path": "/api/health"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/admin/account"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/admin/account/identities"
+    },
+    {
+      "method": "DELETE",
+      "path": "/api/v1/admin/account/identities/:provider"
+    },
+    {
+      "method": "POST",
+      "path": "/api/v1/admin/account/totp/disable"
+    },
+    {
+      "method": "POST",
+      "path": "/api/v1/admin/account/totp/enable"
+    },
+    {
+      "method": "POST",
+      "path": "/api/v1/admin/account/totp/setup"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/admin/activity"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/admin/auth/providers"
+    },
+    {
+      "method": "POST",
+      "path": "/api/v1/admin/auth/providers"
+    },
+    {
+      "method": "DELETE",
+      "path": "/api/v1/admin/auth/providers/:id"
+    },
+    {
+      "method": "PUT",
+      "path": "/api/v1/admin/auth/providers/:id"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/admin/bot-activity"
+    },
+    {
+      "method": "POST",
+      "path": "/api/v1/admin/bot-activity/unban"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/admin/dashboard"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/admin/discord-bot/config"
+    },
+    {
+      "method": "PUT",
+      "path": "/api/v1/admin/discord-bot/config"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/admin/email/config"
+    },
+    {
+      "method": "PUT",
+      "path": "/api/v1/admin/email/config"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/admin/email/connect/callback"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/admin/email/connect/start"
+    },
+    {
+      "method": "POST",
+      "path": "/api/v1/admin/email/disconnect"
+    },
+    {
+      "method": "POST",
+      "path": "/api/v1/admin/email/test"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/admin/invites"
+    },
+    {
+      "method": "POST",
+      "path": "/api/v1/admin/invites"
+    },
+    {
+      "method": "DELETE",
+      "path": "/api/v1/admin/invites/:id"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/admin/moderation/appeals"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/admin/moderation/appeals/:id"
+    },
+    {
+      "method": "POST",
+      "path": "/api/v1/admin/moderation/appeals/:id/claim"
+    },
+    {
+      "method": "POST",
+      "path": "/api/v1/admin/moderation/appeals/:id/resolve"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/admin/moderation/filter-hits"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/admin/moderation/members"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/admin/moderation/recent"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/admin/moderation/search"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/admin/moderation/spam-hits"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/admin/moderation/stats/summary"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/admin/moderation/user/:discordId"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/admin/moderation/user/:discordId/actions"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/admin/moderation/user/:discordId/appeals"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/admin/moderation/user/:discordId/notes"
+    },
+    {
+      "method": "POST",
+      "path": "/api/v1/admin/moderation/user/:discordId/notes"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/admin/pages"
+    },
+    {
+      "method": "POST",
+      "path": "/api/v1/admin/pages"
+    },
+    {
+      "method": "DELETE",
+      "path": "/api/v1/admin/pages/:id"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/admin/pages/:id"
+    },
+    {
+      "method": "PATCH",
+      "path": "/api/v1/admin/pages/:id"
+    },
+    {
+      "method": "POST",
+      "path": "/api/v1/admin/pages/:id/preview"
+    },
+    {
+      "method": "POST",
+      "path": "/api/v1/admin/pages/:id/unprotect"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/admin/posts"
+    },
+    {
+      "method": "POST",
+      "path": "/api/v1/admin/posts"
+    },
+    {
+      "method": "DELETE",
+      "path": "/api/v1/admin/posts/:id"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/admin/posts/:id"
+    },
+    {
+      "method": "PUT",
+      "path": "/api/v1/admin/posts/:id"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/admin/posts/:id/announce"
+    },
+    {
+      "method": "POST",
+      "path": "/api/v1/admin/posts/:id/announce/retry"
+    },
+    {
+      "method": "PATCH",
+      "path": "/api/v1/admin/posts/:id/publish"
+    },
+    {
+      "method": "POST",
+      "path": "/api/v1/admin/posts/upload"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/admin/settings"
+    },
+    {
+      "method": "PUT",
+      "path": "/api/v1/admin/settings"
+    },
+    {
+      "method": "POST",
+      "path": "/api/v1/admin/shard/account"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/admin/shard/accounts"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/admin/shard/atlas"
+    },
+    {
+      "method": "POST",
+      "path": "/api/v1/admin/shard/atlas/approve"
+    },
+    {
+      "method": "POST",
+      "path": "/api/v1/admin/shard/atlas/import"
+    },
+    {
+      "method": "PUT",
+      "path": "/api/v1/admin/shard/atlas/path"
+    },
+    {
+      "method": "POST",
+      "path": "/api/v1/admin/shard/atlas/reject"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/admin/shard/audit"
+    },
+    {
+      "method": "POST",
+      "path": "/api/v1/admin/shard/ban"
+    },
+    {
+      "method": "POST",
+      "path": "/api/v1/admin/shard/broadcast"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/admin/shard/char/:serial"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/admin/shard/houses"
+    },
+    {
+      "method": "POST",
+      "path": "/api/v1/admin/shard/kick"
+    },
+    {
+      "method": "POST",
+      "path": "/api/v1/admin/shard/link"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/admin/shard/pages"
+    },
+    {
+      "method": "POST",
+      "path": "/api/v1/admin/shard/pages/:id/close"
+    },
+    {
+      "method": "POST",
+      "path": "/api/v1/admin/shard/pages/:id/respond"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/admin/shard/roster/:account"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/admin/shard/sales"
+    },
+    {
+      "method": "POST",
+      "path": "/api/v1/admin/shard/unban"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/admin/shard/vendors/:account"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/admin/shard/visibility"
+    },
+    {
+      "method": "PUT",
+      "path": "/api/v1/admin/shard/visibility"
+    },
+    {
+      "method": "PUT",
+      "path": "/api/v1/admin/site-mode"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/admin/uo-link/config"
+    },
+    {
+      "method": "PUT",
+      "path": "/api/v1/admin/uo-link/config"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/admin/uo-link/stream"
+    },
+    {
+      "method": "POST",
+      "path": "/api/v1/admin/uo-link/towncrier"
+    },
+    {
+      "method": "DELETE",
+      "path": "/api/v1/admin/uo-link/towncrier/:id"
+    },
+    {
+      "method": "POST",
+      "path": "/api/v1/admin/uploads"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/admin/users"
+    },
+    {
+      "method": "POST",
+      "path": "/api/v1/admin/users"
+    },
+    {
+      "method": "DELETE",
+      "path": "/api/v1/admin/users/:id"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/admin/users/:id"
+    },
+    {
+      "method": "PUT",
+      "path": "/api/v1/admin/users/:id"
+    },
+    {
+      "method": "POST",
+      "path": "/api/v1/admin/users/:id/mfa/reset"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/admin/users/:id/shard/accounts"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/admin/users/:id/shard/houses"
+    },
+    {
+      "method": "DELETE",
+      "path": "/api/v1/admin/users/:id/shard/link/:account"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/admin/users/:id/shard/online"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/admin/users/:id/shard/sales"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/admin/users/:id/shard/standing"
+    },
+    {
+      "method": "DELETE",
+      "path": "/api/v1/admin/users/:id/trusted-devices"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/admin/users/:id/trusted-devices"
+    },
+    {
+      "method": "DELETE",
+      "path": "/api/v1/admin/users/:id/trusted-devices/:deviceId"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/admin/wiki"
+    },
+    {
+      "method": "POST",
+      "path": "/api/v1/admin/wiki"
+    },
+    {
+      "method": "DELETE",
+      "path": "/api/v1/admin/wiki/:slug"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/admin/wiki/:slug"
+    },
+    {
+      "method": "PUT",
+      "path": "/api/v1/admin/wiki/:slug"
+    },
+    {
+      "method": "PATCH",
+      "path": "/api/v1/admin/wiki/:slug/publish"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/admin/wiki/:slug/revisions"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/admin/wiki/:slug/revisions/:id"
+    },
+    {
+      "method": "POST",
+      "path": "/api/v1/admin/wiki/:slug/revisions/:id/restore"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/admin/wiki/categories"
+    },
+    {
+      "method": "POST",
+      "path": "/api/v1/admin/wiki/categories"
+    },
+    {
+      "method": "DELETE",
+      "path": "/api/v1/admin/wiki/categories/:id"
+    },
+    {
+      "method": "PUT",
+      "path": "/api/v1/admin/wiki/categories/:id"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/admin/wiki/tags"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/auth/invite/:token"
+    },
+    {
+      "method": "POST",
+      "path": "/api/v1/auth/invite/:token/accept"
+    },
+    {
+      "method": "POST",
+      "path": "/api/v1/auth/login"
+    },
+    {
+      "method": "POST",
+      "path": "/api/v1/auth/login/totp"
+    },
+    {
+      "method": "POST",
+      "path": "/api/v1/auth/logout"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/auth/me"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/auth/me/account"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/auth/me/account/identities"
+    },
+    {
+      "method": "DELETE",
+      "path": "/api/v1/auth/me/account/identities/:provider"
+    },
+    {
+      "method": "PATCH",
+      "path": "/api/v1/auth/me/account/password"
+    },
+    {
+      "method": "POST",
+      "path": "/api/v1/auth/me/account/recovery-codes/generate"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/auth/me/account/recovery-codes/status"
+    },
+    {
+      "method": "POST",
+      "path": "/api/v1/auth/me/account/totp/disable"
+    },
+    {
+      "method": "POST",
+      "path": "/api/v1/auth/me/account/totp/enable"
+    },
+    {
+      "method": "POST",
+      "path": "/api/v1/auth/me/account/totp/setup"
+    },
+    {
+      "method": "PATCH",
+      "path": "/api/v1/auth/me/account/username"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/auth/me/devices"
+    },
+    {
+      "method": "POST",
+      "path": "/api/v1/auth/me/devices"
+    },
+    {
+      "method": "DELETE",
+      "path": "/api/v1/auth/me/devices/:id"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/auth/me/notifications/streams"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/auth/me/notifications/subscriptions"
+    },
+    {
+      "method": "PUT",
+      "path": "/api/v1/auth/me/notifications/subscriptions"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/auth/me/sessions"
+    },
+    {
+      "method": "DELETE",
+      "path": "/api/v1/auth/me/sessions/:id"
+    },
+    {
+      "method": "DELETE",
+      "path": "/api/v1/auth/me/trusted-devices"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/auth/me/trusted-devices"
+    },
+    {
+      "method": "POST",
+      "path": "/api/v1/auth/me/trusted-devices"
+    },
+    {
+      "method": "DELETE",
+      "path": "/api/v1/auth/me/trusted-devices/:id"
+    },
+    {
+      "method": "POST",
+      "path": "/api/v1/auth/mobile/login"
+    },
+    {
+      "method": "POST",
+      "path": "/api/v1/auth/mobile/logout"
+    },
+    {
+      "method": "POST",
+      "path": "/api/v1/auth/mobile/refresh"
+    },
+    {
+      "method": "POST",
+      "path": "/api/v1/auth/mobile/sso/exchange"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/auth/mobile/sso/start"
+    },
+    {
+      "method": "POST",
+      "path": "/api/v1/auth/password/forgot"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/auth/password/reset/:token"
+    },
+    {
+      "method": "POST",
+      "path": "/api/v1/auth/password/reset/:token"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/auth/providers"
+    },
+    {
+      "method": "POST",
+      "path": "/api/v1/auth/register"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/auth/sso/:provider/callback"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/auth/sso/:provider/link"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/auth/sso/:provider/start"
+    },
+    {
+      "method": "POST",
+      "path": "/api/v1/auth/sso/totp"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/player/account"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/player/account/identities"
+    },
+    {
+      "method": "DELETE",
+      "path": "/api/v1/player/account/identities/:provider"
+    },
+    {
+      "method": "PATCH",
+      "path": "/api/v1/player/account/password"
+    },
+    {
+      "method": "POST",
+      "path": "/api/v1/player/account/totp/disable"
+    },
+    {
+      "method": "POST",
+      "path": "/api/v1/player/account/totp/enable"
+    },
+    {
+      "method": "POST",
+      "path": "/api/v1/player/account/totp/setup"
+    },
+    {
+      "method": "PATCH",
+      "path": "/api/v1/player/account/username"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/player/appeals"
+    },
+    {
+      "method": "POST",
+      "path": "/api/v1/player/appeals"
+    },
+    {
+      "method": "POST",
+      "path": "/api/v1/player/appeals/:id/withdraw"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/player/appeals/eligible"
+    },
+    {
+      "method": "POST",
+      "path": "/api/v1/player/shard/account"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/player/shard/accounts"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/player/shard/char/:serial"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/player/shard/houses"
+    },
+    {
+      "method": "POST",
+      "path": "/api/v1/player/shard/link"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/player/shard/roster/:account"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/player/shard/sales"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/player/shard/vendors/:account"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/public/atlas/champions"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/public/atlas/creatures"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/public/atlas/creatures/:slug"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/public/atlas/landmarks"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/public/atlas/meta"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/public/atlas/regions"
+    },
+    {
+      "method": "POST",
+      "path": "/api/v1/public/contact"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/public/pages/:id/preview/:token"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/public/pages/:slug"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/public/posts/:category"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/public/posts/:category/:idOrSlug"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/public/settings"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/public/shard/champs"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/public/shard/economy"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/public/shard/features"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/public/shard/feed"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/public/shard/governors"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/public/shard/governors/:city/history"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/public/shard/guilds"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/public/shard/houses"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/public/shard/idoc"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/public/shard/online"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/public/shard/presence"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/public/shard/ruleset"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/public/shard/status"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/public/shard/stream"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/public/status"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/public/version"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/public/wiki"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/public/wiki/:slug"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/public/wiki/categories"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/public/wiki/tags"
+    }
+  ],
+  "internal": [
+    {
+      "method": "GET",
+      "path": "/health"
+    },
+    {
+      "method": "GET",
+      "path": "/internal/bot-config"
+    }
+  ]
+}

website/test-plan.md

@@ -0,0 +1,154 @@
+# Runic Gateway Website — Test Plan (Discord bot)
+
+> Companion to [website-README.md](website-README.md) (overview) and
+> [BACKEND_DESIGN.md](BACKEND_DESIGN.md) (server API/schema/security contract).
+> Establishes the test plan for the **`bot/` workspace** (the Discord bot), the
+> last of the three `website` npm workspaces without a suite. The server and
+> client suites already exist (website PR #86); this doc closes the bot gap and
+> records the shared conventions so all three stay consistent.
+
+## 1. Goal & philosophy
+
+Cover **meaningful bot behavior** — the moderation/filter decisions a future
+change could silently break — not a coverage number. The bot's value is in *what
+it decides to delete, warn, mute, or let through*; a good test reads "given this
+message + config, what action does the bot take?", never "did this function call
+that function?".
+
+The whole `website` repo tests on **Node's built-in runner (`node --test`)** with
+**zero external test dependencies** — no jest, no vitest, no jsdom. Unit tests
+run without a database or a live Discord gateway: the DB pool is pointed at a dead
+port and every collaborator (`db.query`, a model, a Discord `message`/`client`) is
+replaced with an in-memory fake. This mirrors the server suite exactly (the bot is
+CommonJS, like the server — `require`/`module.exports` — so the same patterns
+apply verbatim).
+
+## 2. Current state
+
+| Workspace | Runner | Status |
+|---|---|---|
+| `server/` | `node --test` | **Exists** — models, controllers, auth/session, shard ingest. |
+| `client/` | `node --test` (pure-logic ESM) | **Exists** (PR #86) — `lib/`, `api/`, `data/`. |
+| `bot/` | — | **This plan** — no runner or tests yet. |
+
+The 46% SonarQube aggregate is dragged down by the bot (and the client's
+un-unit-testable React components) reading as 0% covered. Standing up the bot
+suite lifts the real number and, more importantly, locks the filter/moderation
+rules.
+
+## 3. Harness
+
+Add a test script to `bot/package.json` (mirrors server/client):
+
+```json
+"scripts": { "test": "node --test" }
+```
+
+Conventions, identical to `server/test/`:
+
+- **No DB.** Set `process.env.DB_HOST = '127.0.0.1'` / `DB_PORT = '59999'` at the
+  top of any test whose module transitively `require`s `../db`, so the pool is
+  built against a dead port and a stray query fails fast instead of hanging.
+  Models are exercised by monkeypatching `db.query` (or the model method the unit
+  under test calls) with an in-memory fake; restore it in `afterEach`.
+- **No Discord.** The `discord.js` `Client`, `Message`, `GuildMember`, and
+  `Interaction` objects are hand-rolled fakes carrying only the fields the unit
+  reads (e.g. `message.mentions.users.size`, `message.member.roles.cache`,
+  `message.client.fetchInvite`). Never construct a real client or open a gateway
+  connection.
+- **Tests live in `bot/test/*.test.js`.** One file per module under test.
+
+## 4. Units to cover
+
+Ordered high-value first. Each row names the module, the behavior worth locking,
+and the seam a test drives it through.
+
+### 4.1 Pure logic (no mocks beyond inputs)
+
+| Module | Behaviors to lock | Notes |
+|---|---|---|
+| `filter/normalize.js` | leetspeak folding (`b4d`→`bad`, `@ss`→`ass`), 3+-repeat collapse (`sooooo`→`so`), case-fold; `matches()` is word-boundary anchored (so `bad` does not fire inside `badminton`); `findMatch()` returns the first `{word, severity}` row or `null`; the *documented gaps* stay gaps (spaced-out `b a d` is **not** caught). | The core obfuscation-resistance contract. Pin the gaps too, so a future tightening is a deliberate, test-visible change. |
+| `utils/duration.js` | `"30s"/"10m"/"2h"/"1d"` → correct ms; whitespace tolerated; garbage/empty/unknown-unit → `null`; `MAX_TIMEOUT_MS` is 28 days (the Discord cap callers clamp to). | Feeds `/mute` and temp-role expiry — a wrong parse mutes for the wrong span. |
+| `filter/spamFilter.js` | `isRateLimited` trips on the 6th message inside the 5 s window and is per-`guild:user`; it has a **side effect** (records the timestamp) so it must be called once; `isMassMention` counts users **+** roles against the threshold; `isMassEmoji` counts custom `<:name:id>` and unicode pictographs. | Drive time with a stubbed `Date.now` (or accept the real clock and use tight windows). The module-load `setInterval(...).unref()` sweep must not keep the runner alive — `.unref()` already handles this; assert no leak by letting the suite exit. |
+
+### 4.2 Logic with a single mocked collaborator
+
+| Module | Behaviors to lock | Seam / mock |
+|---|---|---|
+| `filter/inviteFilter.js` | returns the **code** (not a bool) of the first *foreign* invite; an invite resolving to the current guild is allowed; an invite that **fails to resolve** (expired/invalid) is treated as foreign (fail-closed); no invite in the message → `null`. | Fake `message.client.fetchInvite(code)` — resolve with `{ guild: { id } }` for local/foreign, or throw for unresolvable. Set `message.guildId` + `message.content`. |
+| `site/siteApiClient.js` | never throws on a network/timeout/HTTP failure — always returns the `{ ok, ... }` shape so a command never breaks when the site is down: `{ ok: true, data }` on success, `{ ok: false, error }` on failure, and the distinct `{ ok: false, maintenance: true, message }` for the site's 503 maintenance response. (Public read client — **no** shared secret; the keyed channel is `botInternalClient.js`.) | Stub `global.fetch` (resolve various statuses/bodies, reject/timeout via `AbortController`). Same non-throwing contract the server's `uoLinkClient` follows. |
+| `internal/requireInternalKey.js` | `401` on a missing/wrong key; `next()` on the configured key; **fail-closed** when `BOT_INTERNAL_KEY` is empty (never matches); timing-safe compare (equal-length + `crypto.timingSafeEqual`, no early-exit length leak). | Call the middleware with a fake `req` (`req.get('X-Internal-Key')`) + `res`/`next` spies; mirrors `server/test/requireInternalKey.test.js`. |
+
+### 4.3 The filter pipeline (orchestration)
+
+`discord/messageFilter.js` is the highest-value integration seam — it composes
+all of §4.1–4.2. Lock the **decision order and the actions**, with every
+collaborator faked:
+
+- **Bypass wins first:** an allow-listed channel, or a member holding an
+  allow-listed role, short-circuits the whole pipeline (`isBypassed`) — no
+  delete, no hit recorded.
+- **Order:** invite link → banned word → spam (rate-limit → mass-mention →
+  mass-emoji). `detectSpam` must evaluate `isRateLimited` **first and exactly
+  once** (it has the timestamp side effect).
+- **Actions:** invite/spam always delete + warn (no severity tiers); a
+  word-filter hit applies the action for its severity; filter-triggered mutes use
+  the fixed `FILTER_MUTE_SECONDS` (600 s).
+- **Best-effort recording never breaks moderation:** `recordFilterHit` /
+  `recordSpamHit` throwing must be swallowed — the delete/warn still happens.
+
+Mocks: `filterCache` (in-memory `allowChannels`/`allowRoles` Sets + words), a fake
+`message` (content, author, member roles, `delete()`, `guildId`), and spies on
+`warnings`/`filterHits`/`spamHits`/`modLog` to assert what was called.
+
+### 4.4 Models (`bot/model/*.js`)
+
+Thin `db.query` wrappers (e.g. `warnings.js`, `filterWords.js`, `filterHits.js`,
+`spamHits.js`, `memberEvents.js`, `guildConfig.js`, `scheduledMessages.js`,
+`tempRoles.js`). Cover only those with **shaping/branching logic** (a query that
+maps rows, applies an "active/not-expired" predicate, or upserts) by asserting the
+**SQL params** passed to a fake `db.query` and the shape returned. Skip pure
+one-line inserts with no logic — testing those only proves the mock.
+
+## 5. Explicitly out of scope
+
+- **`discord.js` internals / the live gateway** — not ours to test; never open a
+  real connection.
+- **Thin command wrappers** (`discord/commands/*.command.js`) that only validate
+  args and call a Discord API + a model — cover their *logic* (arg parsing,
+  duration clamping) if any, but not the Discord round-trip.
+- **`node-cron` scheduling itself** — test the job's callback logic, not that cron
+  fires.
+
+## 6. CI & coverage wiring
+
+Mirror what PR #86 did for the client:
+
+- **`.gitea/workflows/pr-checks.yml`** — add a `bot-tests` job (or a
+  `Run bot tests` step) that runs `npm test --prefix bot`, gating PRs into `main`.
+- **`.gitea/workflows/sonarqube.yml`** — generate a bot LCOV from the repo root so
+  `SF:` paths resolve to `bot/src/...`:
+
+  ```
+  node --test --experimental-test-coverage \
+    --test-reporter=lcov --test-reporter-destination=bot/coverage/lcov.info \
+    bot/test/*.test.js
+  ```
+
+- **`sonar-project.properties`** — add `bot/test` to `sonar.tests`, the glob to
+  `sonar.test.inclusions`, `bot/coverage/lcov.info` to
+  `sonar.javascript.lcov.reportPaths`, and `bot/coverage/**` to `sonar.exclusions`.
+  (`bot/src` is already in `sonar.sources`.)
+
+Bot units need no `npm ci` to run when they import only relative files + Node
+built-ins; a test that stubs `global.fetch` or fakes `db` needs no `discord.js`
+either. Keep the pool pointed at a dead port so the run is hermetic.
+
+## 7. Suggested phasing
+
+1. **Harness + pure logic** — `test` script, then `normalize`, `duration`,
+   `spamFilter`. Fast, zero mocks, immediate value.
+2. **Single-collaborator units** — `inviteFilter`, `siteApiClient`,
+   `requireInternalKey`.
+3. **Pipeline** — `messageFilter` decision order + actions (the payoff test).
+4. **Models with logic**, then the **CI/Sonar wiring** so it all counts.

website/website-README.md

@@ -1,12 +1,16 @@
-# UOMysticmoon Website
+# Runic Gateway Website
 
-Public site, wiki, and protected admin panel for the **UOMysticmoon** private Ultima Online
-shard — a full-stack app in one repo:
+Public site, wiki, and protected admin panel for a private Ultima Online shard — a
+full-stack app in one repo. Branding is instance-configurable via `BRAND_*` (see
+[Branding](#branding)); **UOMysticmoon** is the first instance.
+
+A full-stack app in one repo:
 
 - **Backend** — Node.js + Express REST API (layered `router → controller → model → db`), MariaDB, a provider-agnostic session layer (JWT cookie for web, bearer tokens for mobile, pluggable SSO).
 - **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 ([UOM/link](https://gitea.whitlocktech.com/UOM/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).
+- **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).
 
@@ -14,6 +18,7 @@ The design reference is [BACKEND_DESIGN.md](BACKEND_DESIGN.md) (API contract, sc
 
 ## Contents
 
+- [Architecture](#architecture)
 - [Tech stack](#tech-stack)
 - [Project structure](#project-structure)
 - [Prerequisites](#prerequisites)
@@ -33,6 +38,103 @@ The design reference is [BACKEND_DESIGN.md](BACKEND_DESIGN.md) (API contract, sc
 
 ---
 
+## Architecture
+
+How the pieces fit together — the React SPA and native app talk to one Express backend
+(`router → controller → model → db`), which persists to MariaDB and bridges to the live
+game world only through the **uo-link** sidecar. The shard itself is never internet-facing.
+See [ARCHITECTURE.md](ARCHITECTURE.md) for the fuller write-up.
+
+```mermaid
+flowchart TB
+    %% ---------- Clients ----------
+    subgraph clients["Clients"]
+        browser["Browser<br/>React + Vite SPA<br/>(public · wiki · admin)"]
+        mobile["Native mobile app<br/>(bearer tokens)"]
+    end
+
+    idp["SSO providers<br/>Google · Discord · custom OIDC"]
+    discord["Discord"]
+
+    %% ---------- Website (one repo) ----------
+    subgraph website["website/ &nbsp;— Node app (one repo)"]
+        direction TB
+
+        subgraph backend["server/ — Express backend"]
+            direction TB
+            mw["Middleware<br/>helmet · siteMode · noindex<br/>rateLimit · loginProtection · botScore · validate"]
+            router["Router /api/v1<br/>auth (web · mobile · sso) · public · admin"]
+            ctrl["Controllers"]
+            auth["Session layer (auth/)<br/>sessionService · JWT/cookie · bearer · SSO+PKCE"]
+            model["Models (.model + .db)<br/>raw parameterized SQL — no ORM"]
+            sse["SSE fan-out<br/>public stream (allowlist) · admin stream (sensitive)"]
+
+            subgraph shardutil["Shard integration (utils/)"]
+                ingest["shardIngest.js<br/>WS ingest dispatcher"]
+                restcli["uoLinkClient.js<br/>REST client (never throws)"]
+            end
+
+            secret["secretBox.js<br/>AES-256-GCM secrets at rest"]
+        end
+
+        bot["bot/<br/>Discord bot"]
+    end
+
+    db[("MariaDB<br/>users · posts · wiki · settings · activity<br/>mobileSessions · authProviders · userIdentities<br/>uoLinkConfig · shard_online/economy/houses/events")]
+
+    %% ---------- Shard side ----------
+    subgraph shardside["Game shard (never internet-facing)"]
+        direction TB
+        sidecar["uo-link sidecar<br/>(Rust) — the only bridge exposed"]
+        servuo["ServUO shard<br/>(C# plugin)"]
+    end
+
+    %% ---------- Edges ----------
+    browser <-->|"same-origin JSON + SSE (cookie)"| mw
+    mobile -->|"REST (bearer access/refresh)"| mw
+    browser -.->|"OAuth redirect + PKCE"| idp
+    auth -.->|"token exchange"| idp
+
+    mw --> router --> ctrl
+    ctrl --> auth
+    ctrl --> model
+    ctrl --> restcli
+    ctrl --> sse
+    auth --> model
+    model <--> db
+    auth -. reads/writes secrets .-> secret
+    restcli -. reads config/token .-> secret
+    ingest --> model
+    ingest --> sse
+    sse -->|"live events"| browser
+    bot -->|"messages"| discord
+    bot <--> db
+
+    restcli -->|"REST: /char /roster /economy /history · /link/confirm · /towncrier"| sidecar
+    sidecar -->|"WebSocket live event feed (bearer + X-UOLink-Version)"| ingest
+    servuo -->|"loopback TCP 127.0.0.1:7788<br/>newline-delimited JSON (shard dials out)"| sidecar
+
+    %% ---------- Styling ----------
+    classDef ext fill:#2d2233,stroke:#7a5c94,color:#e8dff0;
+    classDef store fill:#1f2d2a,stroke:#4c8c7d,color:#dff0ea;
+    classDef bridge fill:#2d2620,stroke:#94764c,color:#f0e6d8;
+    class idp,discord ext;
+    class db store;
+    class sidecar,servuo bridge;
+```
+
+- **One backend, layered.** Every request flows `middleware → router → controller → model → db`.
+  Web browsers authenticate with an httpOnly JWT cookie; the native app uses short-lived bearer
+  access tokens plus rotated refresh tokens; SSO (Google/Discord/OIDC) is link-only and PKCE-guarded.
+  All three surfaces produce the *same* session via the session layer.
+- **The shard is never reachable.** The ServUO shard *dials out* over loopback TCP to the uo-link
+  sidecar; only the sidecar is exposed, and only the backend talks to it. The REST client
+  (`uoLinkClient.js`) never throws, so the site degrades gracefully when the shard is down.
+- **Sensitive events stay private.** Ingested game events fan out to browsers over two SSE channels —
+  a public allowlist stream and an admin-only stream that adds staff audit / cheat / login events.
+
+---
+
 ## Tech stack
 
 | Layer | Tech |
@@ -133,14 +235,14 @@ to the backend, so the SPA stays same-origin (cookies work).
 **1. Start a MariaDB the backend can reach** (published on `localhost:3306`):
 
 ```bash
-docker run -d --name uomm-db -p 3306:3306 -e MARIADB_DATABASE=uomysticmoon -e MARIADB_USER=uomm -e MARIADB_PASSWORD=devpass -e MARIADB_ROOT_PASSWORD=rootpass mariadb:11
+docker run -d --name rg-db -p 3306:3306 -e MARIADB_DATABASE=runic_gateway -e MARIADB_USER=runic -e MARIADB_PASSWORD=devpass -e MARIADB_ROOT_PASSWORD=rootpass mariadb:11
 ```
 
 **2. Configure + start the backend** (terminal 1):
 
 ```bash
 cp server/.env.example server/.env
-# Set DB_HOST=127.0.0.1, DB_PORT=3306, DB_USER=uomm, DB_PASSWORD=devpass,
+# Set DB_HOST=127.0.0.1, DB_PORT=3306, DB_USER=runic, DB_PASSWORD=devpass,
 #     JWT_SECRET=<anything>, ADMIN_USERNAME=admin, ADMIN_PASSWORD=<your password>
 npm run install-server
 npm run server          # nodemon → http://localhost:3000
@@ -249,7 +351,7 @@ actually returns (`400` validation, `401`/`403` auth, `404`, `409` conflicts, `4
 
 **Authentication in the UI** — click **Authorize** and provide either:
 
-- `cookieAuth` — the `uomm_token` session cookie (set automatically in the browser after
+- `cookieAuth` — the session cookie (name `rg_token`, configurable via `COOKIE_NAME`; set automatically in the browser after
   `POST /api/v1/auth/login`), or
 - `bearerAuth` — a mobile access token from `POST /api/v1/auth/mobile/login` (sent as
   `Authorization: Bearer <token>`).
@@ -265,6 +367,18 @@ cd server
 npm run swagger        # → server/swagger/swagger-output.json
 ```
 
+`swagger.js` post-processes the generator's output in two ways before writing it:
+
+- **Trailing slashes are stripped from path keys.** swagger-autogen builds a path by
+  string-concatenating the mount prefix with the route argument, so a capability router mounted at
+  `/users` whose collection route is `router.get('/')` would document as `/api/v1/admin/users/` —
+  a URL no client calls, while dropping the one they all do. Express is indifferent (non-strict
+  routing treats the two as one route), but the published spec is a contract.
+- **Path keys are sorted.** The generator emits them in router-traversal order, so moving a route
+  between files rewrote most of this ~5k-line committed artifact even when the API was provably
+  unchanged. Sorting keeps the diff proportional to the change. OpenAPI attaches no meaning to path
+  order, and `scripts/routeManifest.js` already sorts for the same reason.
+
 If the generated spec is missing, the server logs a warning and simply disables `/api/docs` (it does
 not crash).
 
@@ -274,7 +388,7 @@ not crash).
 
 The site is wired to the live in-game world through **uo-link**, a standalone sidecar service that
 runs next to the ServUO shard. Its source lives in a separate repo:
-**[UOM/link](https://gitea.whitlocktech.com/UOM/link)**. uo-link speaks the shard's internals and
+**[RunicGateway/link](https://gitea.whitlocktech.com/RunicGateway/link)**. uo-link speaks the shard's internals and
 exposes a small, authenticated HTTP + WebSocket API; this website is a *client* of it. The shard
 itself is never exposed to the internet — only the sidecar is, and only the website's backend talks
 to it.
@@ -282,7 +396,7 @@ to it.
 ### How it works
 
 ```
-ServUO shard  ──▶  uo-link sidecar (UOM/link)  ──▶  website backend  ──▶  browser
+ServUO shard  ──▶  uo-link sidecar (RunicGateway/link)  ──▶  website backend  ──▶  browser
                    REST + WebSocket, bearer-auth      ingest + REST         same-origin JSON/SSE
 ```
 
@@ -328,7 +442,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). |
 
@@ -348,19 +462,20 @@ Copy `.env.example` (Compose) or `server/.env.example` (local) and fill in. **`.
 | `PORT` | `3000` | server listens on `0.0.0.0:PORT` |
 | `UPLOAD_DIR` | `<server>/uploads` | where post images are written (`/app/uploads`, volume-mounted, in Compose) |
 | `DB_HOST` / `DB_PORT` | `db` / `3306` | `db` in Compose; `127.0.0.1` for local dev |
-| `DB_NAME` / `DB_USER` / `DB_PASSWORD` | `uomysticmoon` / `uomm` / — | app database credentials |
+| `DB_NAME` / `DB_USER` / `DB_PASSWORD` | `runic_gateway` / `runic` / — | app database credentials |
 | `DB_ROOT_PASSWORD` | — | MariaDB root (Compose only) |
 | `JWT_SECRET` | — | **required** — long random string; signs session, mobile, and SSO-flow tokens |
 | `JWT_EXPIRES_IN` | `1d` | web session token + cookie lifetime |
 | `COOKIE_SECURE` | `auto` | `auto` = Secure only over HTTPS (works on LAN HTTP + Pangolin HTTPS) |
-| `COOKIE_NAME` | `uomm_token` | |
+| `COOKIE_NAME` | `rg_token` | changing it on a live instance invalidates existing sessions |
+| `BRAND_*` | Runic Gateway | instance branding (name, tagline, colors, logo/hero/favicon) — see [Branding](#branding) |
 | `SECRET_ENC_KEY` | — | **required in prod** — key for AES-256-GCM encryption of stored OAuth client secrets. Dev falls back to a key derived from `JWT_SECRET` (with a warning) |
 | `APP_BASE_URL` | — | public base URL, used to build the SSO OAuth `redirect_uri` (`${APP_BASE_URL}/api/v1/auth/sso/:provider/callback`). Set in prod to match what you register with Google/Discord; if unset it is derived from the request (fine for local dev) |
 | `MOBILE_ACCESS_TTL` | `15m` | mobile bearer **access** token lifetime (short-lived) |
 | `MOBILE_REFRESH_TTL_DAYS` | `30` | mobile **refresh** token lifetime (long-lived, rotated on use) |
 | `TRUST_PROXY` | `1` | reverse-proxy trust for correct `req.ip` / `req.secure` (rate limiting, backoff, bot-ban). Pin to the proxy hop's LAN IP in prod. A blanket `true` is rejected (coerced to `1`) to block `X-Forwarded-For` spoofing |
 | `DEBUG_TRUST_PROXY` | `0` | `1` logs raw peer address + `X-Forwarded-For` + resolved `req.ip` per request (to verify/refresh the proxy IP). Noisy — leave off |
-| `TOTP_ISSUER` | `UOMysticmoon` | label shown in authenticator apps for optional per-user 2FA |
+| `TOTP_ISSUER` | `BRAND_NAME` | label shown in authenticator apps for optional per-user 2FA |
 | `TOTP_CHALLENGE_TTL` | `5m` | lifetime of the short-lived post-password "awaiting code" step |
 | `ADMIN_USERNAME` / `ADMIN_PASSWORD` | — | first-admin bootstrap (first boot only) |
 | _Email_ | — | configured in Admin → Settings → Email (Gmail OAuth2), not via env; recipient = `contact_email` setting |
@@ -372,6 +487,32 @@ Copy `.env.example` (Compose) or `server/.env.example` (local) and fill in. **`.
 
 ---
 
+## Branding
+
+Instance identity is data, not code — set via `BRAND_*` env vars, so one prebuilt
+image can run as any shard. With none set, everything renders as **Runic Gateway**.
+
+| Var | What |
+|---|---|
+| `BRAND_NAME` / `BRAND_SHORT_NAME` | display name (full / short-in-prose) |
+| `BRAND_TAGLINE` / `BRAND_DESCRIPTION` | tagline + meta/OG description |
+| `BRAND_CONTACT_EMAIL` / `BRAND_URL` | contact + canonical URL (for OG/absolute links) |
+| `BRAND_ACCENT_COLOR` | theme `--accent` (web) + Discord embed color |
+| `BRAND_LOGO` / `BRAND_HERO` / `BRAND_FAVICON` | image paths under the `/brand` mount, or absolute URLs |
+
+**How it flows:** text/colors reach the SPA at runtime through the public settings
+API (`SiteContext`), so no rebuild is needed; the server templates `index.html`
+`<title>`/meta/OG/favicon at boot; emails, TOTP issuer, and the Discord bot read
+`BRAND_*` directly. The admin-editable **site title** and **contact email**
+settings override `BRAND_NAME` / `BRAND_CONTACT_EMAIL` when set. Image assets are
+delivered from the `./brand` bind-mount (see `brand/README.md`).
+
+**UOMysticmoon** is the first instance — [`.env.uomysticmoon.example`](https://gitea.whitlocktech.com/RunicGateway/website/src/branch/main/.env.uomysticmoon.example)
+holds the exact `BRAND_*` + infra (`DB_NAME`/`DB_USER`/`COOKIE_NAME`) pinning to
+run this repo as UOMysticmoon.
+
+---
+
 ## Security
 
 **Session & authorization**