Records what the live Protocol 3.0 smoke test (ServUO + sidecar + website +
AVD) turned up, so none of it has to be rediscovered.
v3.md §5.3 — the ruleset `shard` field now falls back to the instance's own
name when the shard publishes ServUO's stock "My Shard", why that is done at
ingest rather than on read (the frame is also broadcast live), and why the
backfill snapshot must go through the dispatcher instead of writing state
directly: a direct call made it a second writer that skipped the
normalization.
v3.md §7.4 — an unscored board renders a placeholder row rather than a blank
card, and why it is deliberately not shaped like a real entry.
PLAN.md §9 M11 — `places` is a list of {facet,label,spawners,maxAlive} OBJECTS,
not of place-name strings, and typing it `List<String>` makes the whole detail
route fail to decode while the request itself returns 200. Adds the rule that
came out of it: decode tests must feed real captured JSON, because the fakes
build DTOs in Kotlin and can never catch a wire mismatch.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01U7CBg11prhLimL9iHSX1bP
The v3 work added four shard features and an admin-configurable visibility
framework the Android client knows nothing about. v3.md §10 deferred the app
side as a follow-up; re-examining it before the cutover found the gap is wider
than nav hiding:
- no consumer for any of ruleset / leaderboards / market / atlas,
- no `points` block on the character sheet (§7.3),
- no cliloc-resolved item names (§8.6), and
- shard nav gated on session role alone, so an admin who disables a feature
or raises its audience leaves the app rendering entries that 404/403 into a
generic error where the web client hides them.
Scoped as PLAN.md §9 M11 in two PRs (the visibility rules + read-model adds,
then the four screens), with the traps a real shard exposes recorded inline:
uncapped `maxPoints: 0`, cliloc-named boards with a null `nameString`, skill
caps in tenths, the required market staleness banner, the market stream being
off by default, atlas delays in seconds, and `points`-count vs `spawners`-list.
edge → main is held until both land so web and app surface the same shard on
the same day. Neither PR is coupled to the merge order — on a pre-v3 website
every new route and /public/shard/features 404s and the app falls back to
today's behavior — so holding the cutover is a schedule decision, not a
technical dependency.
Also records two things verified as already correct, so they are not
re-derived: the app's SSE request rides the authenticated client (same audience
rung as the same account on web), and every shard DTO is nullable-with-defaults
(field projection cannot cause a decode failure).
Co-Authored-By: Claude <noreply@anthropic.com>
The API v2 plan is revised down to the work that is actually justified: a CSP
hardening pass and an in-place domain split of the monolithic route wiring.
- Auth merge (httpOnly cookies -> bearer + rotating refresh for every client) is
removed and re-filed as deferred behind trigger conditions. httpOnly+SameSite
is the stronger model, session.service.js already unifies cookie and bearer,
the SSO/PKCE transaction cookies survive any merge, and it dragged the admin
SSE fetch/ReadableStream rewrite along as a dependency for no user-visible
payoff. A revival must first spec refresh-token reuse detection and a rollback
procedure.
- No parallel /api/v2. The URL surface is already grouped by capability, so each
new router file mounts at the prefix it already owns and every URL stays
byte-identical. No dual mount, no per-route migration, no v1 retirement; the
SPA, Discord bot, and Android app are all untouched. API_V2_SKELETON.md is
marked superseded (kept as the recipe if a versioned API is ever forced).
- The /api/mobile facade and app-version floor are deferred with the revival note
that it starts as a one-line alias mount, not ~70 hand-written delegates. The
M11 milestone is dropped from android/PLAN.md.
- Adds PR 0: a generated route manifest, so "every URL is unchanged" is proved by
a zero-line diff rather than asserted in review. The baseline
api-route-inventory.json (199 API routes + 2 internal) is committed here and is
what PR 0's generator must reproduce byte-for-byte.
- Split sequenced as five grouped PRs; CSP fixed to report-only first, then
enforce (the old plan contradicted itself), with the verified delta being just
form-action 'self' and frame-ancestors 'none'.
Co-Authored-By: Claude <noreply@anthropic.com>
Expand the API v2 plan to account for consumers beyond the browser and
insulate the Android app from version churn before the v2 work begins.
- Inventory the three v1 API consumers (browser, Android app, Discord bot)
and map the cross-component contracts (site<->link, site<->mobile).
- Fix two concrete plan bugs: the public shard SSE stream must stay
anonymous (logged-out browsers and the app's ShardStreamClient send no
auth header), and the useShardFeed fetch-rewrite is admin-stream-only.
- Add "Phase 0 - the mobile facade": a version-agnostic /api/mobile
namespace (a thin BFF delegating to current controllers behind pinned
wire shapes), landed before v2 so the auth merge never touches the app.
- Note link/ is essentially out of scope (no PROTOCOL_VERSION bump), with
the admin-stream allowlist split as the only shared seam.
- Resequence PRs (Phase 0 first) and gate v1 retirement on the pre-facade
app fleet aging out via an app-version floor, not the web client.
- Add M11 to docs/android/PLAN.md: migrate the app to /api/mobile + ship
the app-version floor, cross-referenced with the website plan's Phase 0.
Co-Authored-By: Claude <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NgyHnrNa8WwG3doxvxjuCr
Add auto-generated project-tree snapshots for the website, link, and
Android-app repos under docs/<repo>/PROJECT_TREE.md, and link them from
the README (adding a previously-missing android/ section). These files
are maintained going forward by the sync-project-tree CI workflow in each
source repo, which opens a PR here whenever the tracked layout changes.
Co-Authored-By: Claude <noreply@anthropic.com>
Post-#26 the JaCoCo→Sonar wiring is live and coverage measures 16.4% on new
code — under the 50% gate. Add COVERAGE_PLAN.md: a bucketed analysis of the
gap (ViewModels 0.1%/1153 lines is the dominant lever; DTOs, repositories,
core utils next) and a phased plan — Phase 0 broadens coverage exclusions to
drop non-unit-testable UI/framework code, Phases 1–4 test DTOs, ViewModels,
repositories, and core. Includes a MainDispatcherRule harness + VM test
pattern and per-phase coverage projections (Phase 2 clears the gate at ~65%).
Cross-linked from PLAN.md §12.1.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NgyHnrNa8WwG3doxvxjuCr
Add §12.1 documenting the Android-app SonarQube setup: the coverage gate
failed at 0% because the source-only scan received no JaCoCo report (a
reporting gap, not a testing gap). Records the JaCoCo wiring (jacoco plugin +
report task, sonar.coverage.jacoco.xmlReportPaths, pure-UI coverage
exclusions, a Gradle step in sonarqube.yml) and the 2026-07-22 triage:
3 smells fixed in code, 12 marked Won't Fix (snake_case DTO fields that
mirror the wire contract; idiomatic Compose/nav complexity).
Pairs with RunicGateway/Android-app chore/sonar-coverage-and-cleanup.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NgyHnrNa8WwG3doxvxjuCr
Record the "can't turn off the last notification" class of bug in PLAN.md §11:
the PUT /auth/me/notifications/subscriptions validator requires `streams`, so an
empty set must serialize as {"streams":[]} not {}. kotlinx.serialization drops a
property equal to its default (encodeDefaults=false), so a request DTO field
defaulting to emptyList() gets omitted when empty and the server rejects it 400.
Generalized to any "replace the full set" PUT/POST whose empty value equals a DTO
default. Documents the fix in Android-app fix/notifications-empty-subscriptions.
Co-Authored-By: Claude <noreply@anthropic.com>
Match the website change: the ntfy relay is reached through the public
reverse proxy, which runs outside the compose network and can only reach
a service via a published host port. Update the "no published host port /
internal-only publisher" claims in android/PLAN.md (§11 + §13) and
website/BACKEND_DESIGN.md to describe the published NTFY_HOST_PORT
(default 2586 -> ntfy:80), and note that both devices and the backend
publisher reach ntfy on the public origin.
Co-Authored-By: Claude <noreply@anthropic.com>
Supplements the five curated highlights (docs#34) with the remaining
distinct frames from the same live smoke-test session, in flow order:
home/connected, signed-out + signed-in drawers, login + empty 2FA step,
account overview, recovery-codes pre-generate, and the untrust-all to
empty-list to TOTP-required-again sequence. Extends the screenshots
README with a walkthrough table.
Excludes the raws superseded by the five highlights and pure automation
artifacts (soft-keyboard popups, mid-transition spinners, duplicate Home
landings) that do not represent a distinct app state.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NgyHnrNa8WwG3doxvxjuCr
docs(android): add trusted-devices/MFA live smoke-test screenshots
Live end-to-end smoke test of the Android trusted-device + recovery-code
feature (app PR RunicGateway/Android-app#23) against the local server +
MariaDB on an API 36 emulator. Adds android/screenshots/ with five
captures (login trust step, account Security section, Trusted Devices,
recovery-codes show-once, recovery-code login) and a README documenting
the verified flows — including that trust survives logout (password-only
re-login skipped TOTP) and untrust-all clears the local token.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NgyHnrNa8WwG3doxvxjuCr
@
docs(android): record trusted-devices app implementation in PLAN §4.1.1
Marks §4.1.1 implemented (app PR RunicGateway/Android-app
feature/trusted-devices-mfa) and captures two deliberate design
decisions from the build:
- The trust token DELIBERATELY SURVIVES logout (native analogue of the
rg_trust cookie): it is only consulted at a fresh login, so clearing
it on logout would make the feature a no-op. Kept in a separate,
username-scoped encrypted store; cleared only on Settings→Server
switch, untrust-all, or server-side revocation. Supersedes the earlier
handoff note.
- The login-time trust cap is surfaced + resolved on the Trusted Devices
screen rather than a blocking login modal, since native login already
issued the session.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NgyHnrNa8WwG3doxvxjuCr
@
Add TRUSTED_DEVICES_MFA.md (the approved design/implementation plan) and fold
the feature into BACKEND_DESIGN §3 (trusted_devices + recovery_codes schema),
§4 (login/totp trust+recovery, /auth/me/trusted-devices*, recovery-codes*,
admin trusted-device + /mfa/reset routes), and §6 (trusted-device security
model + audit actions). Note the app-side trust/recovery flow in android PLAN §4.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Record the M10 plan and correct the admin-scope contract:
- §1: narrow the app's exclusion list. The operational admin subset is now
IN scope for staff (moderation, support queue, dashboard/site-mode, content =
news posts + wiki cats/tags). Only the hero/CMS block editor, Discord-bot
config, uo-link config, and OAuth-provider setup remain excluded.
- §6.4: self-service stays role-agnostic under /auth/me/*, but the operational
admin subset now calls /api/v1/admin/** directly, gated by a STAFF/ADMIN menu
access level; bearer is accepted and role re-checked every request.
- §9: add milestone M10 covering the SSO discovery/reachability fixes (native
buttons, no website fallback, encrypted pending PKCE, scrollable drawer, dev
stub IdP) and the staff-operations screens.
Co-Authored-By: Claude <noreply@anthropic.com>
Record that the app's HTTPS-only-in-release / HTTP-in-debug rule (ServerUrl,
allowInsecureHttp = BuildConfig.DEBUG) is backed at the platform socket layer
by an explicit network security config: main/release forbids all cleartext, a
debug override re-permits cleartext to loopback only. Matches the fix in
RunicGateway/Android-app (fix/manifest-cleartext-traffic).
Co-Authored-By: Claude <noreply@anthropic.com>
Promote APP_LINKS.md from a deferred design note into an implementation spec
matching the website `feat/mobile-app-links` and android `feat/app-links`
branches: the server-side `/.well-known/assetlinks.json` route + `mobile_app_links_enabled`
toggle + additive redirect-allowlist entry, and the app-side `autoVerify`
intent-filter driven by a build-time `appLinkHost` (a single multi-tenant APK
cannot autoVerify open-ended shard domains, so App Links are a white-label /
first-party build opt-in; the custom scheme stays the permanent fallback).
Update PLAN.md §9 (M9 follow-up) and the §14 open item, and the redirect-URI
allowlist section of website/BACKEND_DESIGN.md.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NgyHnrNa8WwG3doxvxjuCr
Add the "M9 plan — native SSO login" block to android/PLAN.md: the two-part
(backend-first) split, the frozen Part-1 bridge contract the app codes against
(/auth/providers, /auth/mobile/sso/start Custom-Tab redirect, the code/error
callback deep link, /auth/mobile/sso/exchange), and the six Part-2 app work
items (PKCE+state, SsoAuthManager, SsoApi+DTOs, the callback intent-filter,
the login-screen provider list, and the JVM tests).
Co-Authored-By: Claude <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NgyHnrNa8WwG3doxvxjuCr
Record the plan before coding: native Android "Sign in with Google/Discord"
via a Mobile SSO Authorization Bridge that extends the existing /auth/sso/*
redirect flow and terminates in the existing mobile bearer tokens.
- BACKEND_DESIGN.md: mobile_auth_sessions / mobile_auth_codes schema, the
/auth/mobile/sso/{start,exchange} contract, the two PKCE layers, state/CSRF,
exact-match redirect-URI allowlist, TOTP parity, and the documented
revocation-latency window.
- android/PLAN.md: promote §4.2's "possible later enhancement" to milestone M9
(backend-first, mirroring M7); status note.
- android/APP_LINKS.md: new architecture note on the per-shard assetlinks.json
/ pairing multi-tenancy question (App Links deferred; custom scheme only now).
Co-Authored-By: Claude <noreply@anthropic.com>
Flip M7 Part 2 to landed (Android-app#15) and record the two implementation
decisions: the direct-ntfy embedded distributor (no UnifiedPush library — the
plan's stated likely path; foreground-service SSE, no second app, no Google
Play Services), and the small additive push.ntfyUrl settings field the app
needs to discover the relay (website#79). Document push.ntfyUrl +
NTFY_PUBLIC_URL in BACKEND_DESIGN.md.
Co-Authored-By: Claude <noreply@anthropic.com>
Part 1 backend landed (website#78 merged); flip its status to landed and
expand the M7 plan block into a detailed Part 2 (app) plan, grounded in the
merged /auth/me/devices + notifications contract.
Transport decision (per user): the app EMBEDS its own UnifiedPush
distributor — ntfy is only the relay server, no second app installed, no
Google Play Services. A foreground-service persistent ntfy connection
(reusing the ShardStreamClient pattern) subscribes to the app's own topic;
the registered endpoint is that topic URL. A PushTransport seam keeps the
future FCM Play flavor cheap.
Also records the ten Part-2 work items, resolves the §13 notification-tap
deep-link open item, and drops the now-decided distributor-strategy question.
Co-Authored-By: Claude <noreply@anthropic.com>
- BACKEND_DESIGN.md: push_devices + notification_subscriptions tables (§3), the
/auth/me/devices* + /auth/me/notifications/* API rows (§4), a push-notification
design + security section (content-free tickles, PUBLIC_KINDS split, owner-keyed
personal streams, SSRF endpoint guard, untrusted-relay model), and the ntfy
compose service in the deploy section (§8).
- PLAN.md: flip M7 Part 1 (backend + docs) to in-review — status line, §8 item 3,
§9 M7.
Co-Authored-By: Claude <noreply@anthropic.com>
Capture the M7 backend/docs breakdown in PLAN.md before the code lands: two
event sources / one publisher, the stream catalog + PUBLIC_KINDS-gated mapping,
push_devices + notification_subscriptions tables, the /auth/me routes, the SSRF
endpoint guard, and the content-free-tickle ntfy service (no publish token).
Co-Authored-By: Claude <noreply@anthropic.com>
Mark M6 landed (RunicGateway/Android-app#11): signed-APK release plumbing
(R8 minify + resource shrink, release signingConfig from a gitignored keystore,
release.yml on a v* tag), the §3 version-mismatch guard, and the default brand
app icons (deep-indigo medallion). Record the decision to descope the optional
biometric app-lock from v1 (tokens already encrypted at rest) across §4.3, the
M3 note, §9, and §13.
Co-Authored-By: Claude <noreply@anthropic.com>
Mark the M5 shard-website design pass complete in docs/android/PLAN.md,
matching RunicGateway/Android-app#10: dark-only theme (deep blue-black
surfaces, slate accent, Cinzel display face), reusable pill/label/card/meter
components, and retained per-shard brand-accent seeding — restyling the
working M1–M4 screens with no architecture, data-flow, endpoint, or DTO
change. Updates the status header, the §9 build-progress record, and the
milestone list (M0–M5 landed; M6 release hardening next).
Co-Authored-By: Claude <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NgyHnrNa8WwG3doxvxjuCr
Marks M4 done in android/PLAN.md §9 build-progress and flips the top
status to "M0–M4 landed; M5 (design pass) next." Documents the account
self-service (/auth/me/account*), game-account linking, and text-only
own game-data screens shipped in RunicGateway/Android-app#9 — a pure
consumer of the existing bearer API, no backend/protocol change.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NgyHnrNa8WwG3doxvxjuCr
Records the M3 functional auth pass in docs/android/PLAN.md: native
username/password (+TOTP) login, EncryptedSharedPreferences token storage,
the refresh-on-401 authenticator, /auth/me resume re-validation, the
declarative access-level menu + My Account, and the Custom-Tab hand-offs for
register / forgot-password / SSO. Also records the decision to defer the
optional biometric app-lock to M6 (tokens are already encrypted at rest).
No backend/API change accompanied M3 — the app is a pure consumer of the
existing mobile bearer + /auth/me surface — so no Swagger regeneration.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NgyHnrNa8WwG3doxvxjuCr
Mark M2 done in the build-progress section: the public shard widgets over
/public/shard/* (hub + champ/guild/governor/house boards) and the live SSE
feed with self-driven reconnect/backoff (Android-app#7). Update the status
line to "M0–M2 landed; M3 next". No API change — the app consumes the
existing public shard surface.
Co-Authored-By: Claude <noreply@anthropic.com>
Mark M0+M1 done in the build-progress header and next up M2. Summarize
the M1 functional pass (first-run connect, runtime base URL + host
interceptor, layered ApiResult stack, brand-seeded theming, public
content/wiki/pages/contact screens) and record the deliberate
hand-written-vs-openapi-generated API-client deviation from §2 and its
rationale (swagger-autogen schemas are meta-descriptive, not
codegen-clean). Tracks RunicGateway/Android-app#6.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NgyHnrNa8WwG3doxvxjuCr
Update the PLAN.md status header now that the Android-app repo scaffold
(RunicGateway/Android-app#2) is in: Gradle+Compose+Hilt skeleton, version
catalog, and CI. Records M0 done and points at M1 (functional Kotlin pass).
Co-Authored-By: Claude <noreply@anthropic.com>
Counterpart to RunicGateway/website#77.
- BACKEND_DESIGN.md: /public table now documents the new GET /public/version
(DB-free identity/version), the version block on /public/status, and the brand
block on /public/settings (per-shard theming: name/accent/logo/hero/favicon).
- android/PLAN.md: mark §8 item 4 (version/health) and item 6 (branding) DONE and
update the prerequisite-progress summary — all v1 prerequisites are now done;
only push notifications (item 3) remains and is post-v1 (M7). App M0–M4 unblocked.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NgyHnrNa8WwG3doxvxjuCr
Counterpart to RunicGateway/website#76 (role-agnostic /auth/me/* self surface).
- BACKEND_DESIGN.md: add the /auth/me/account* rows to the /auth API contract and
a note that the surface reuses account.controller behind requireAuth (any role),
so a client manages its own account without touching /admin.
- android/PLAN.md: mark §8 item 1 (role-agnostic self-service) DONE and update the
prerequisite-progress summary; version/health (item 4) and branding (item 6)
remain open, push (item 3) is post-v1.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NgyHnrNa8WwG3doxvxjuCr
§8 item 2 (password reset — the "build FIRST before app work" prerequisite)
shipped in RunicGateway/website#75 + docs#8. Mark it done, note the shipped
design (opaque token stored as a sha256 hash in password_resets, mirroring
user_invites, rather than a signed JWT), and record which §8 items remain open.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NgyHnrNa8WwG3doxvxjuCr
Record the two-pass build process: functional Kotlin first (M0-M4), then a Claude Design pass producing the front-end design that Claude Code implements as the final UI (new M5). Add §2.1 documenting the workflow and reconcile §9 milestones (insert M5 design pass, renumber Polish/Push/Play to M6-M8) plus the milestone cross-references in §8, §11, §12, and §13.
Co-Authored-By: Claude <noreply@anthropic.com>
Add docs/android/PLAN.md — the design contract for the RunicGateway/Android-app
repo (planning only, no app code yet).
Scope: native Kotlin + Jetpack Compose client of the website v1 API. Public
content + public shard widgets (incl. SSE), native username/password + TOTP
login, player self-service via a new role-agnostic /auth/me/* surface, and a
player's own shard/game data. Excludes every admin/management console (hero
editor, auth/provider admin, Discord bot, shard/uo-link ops).
Key decisions captured: stay on v1 (all additions are additive, no v2);
registration/invite/reset/SSO are website-handled hand-offs, not native screens;
password reset is built on the backend + web front end first; single shard per
install; minSdk 29; no telemetry and no offline cache in v1; text-only game data
(paperdoll is future); strings externalized from day one; push via a self-hosted
ntfy/UnifiedPush service with content-free tickles that keep the relay untrusted;
Gitea Actions build on ubuntu:latest with a signed-APK release.
Co-Authored-By: Claude <noreply@anthropic.com>
