[minekube-ai-engineer]

Source: Discord ask-support thread

Source: Discord ask-support thread — the user report ("LOGINTO" auth plugin + Connect-tunneled Paper join never completes) that surfaced these content gaps. Verdict of the investigation: plugin-side limitation, not a Connect defect (kanban t_644bb679).

Why

Three public-content gaps were verified against the live site and main (2026-09-28). All three misroute support answers today; none is a code defect.

1. The connect-player contract was repo-only

• https://connect.minekube.com/guide/login-plugin-integration.md → 404; the public guide has no route for it.
• .web/docs/guide/ contained only login-plugins.md on this topic. The contract lived in connect-java/docs/login-plugin-integration.md, which plugin authors reading the public guide cannot find.

Fix: new page .web/docs/guide/login-plugin-integration.md + a sidebar entry next to Login and Auth Plugins. It publishes the contract a plugin author needs: the exact attribute name connect-player (permanent), the Netty key io.netty.util.AttributeKey.valueOf("connect-player"), the ConnectAttributes.CONNECT_PLAYER constant, the ConnectPlayer value type, the single set-site covering Velocity/BungeeCord/Spigot, "set before any login event", the passthrough-absent rule, ConnectApi.isConnectPlayer/getPlayer for post-login checks, and the copy-paste Floodgate-style exemption recipe.

Deliberately not duplicated: the operator-side login-reassert config and ordering detail. That stays owned by /guide/login-plugins, and the new page links to it. Keeping one home per fact is why the page is an adapted copy rather than a dump of the connector-repo file.

2. The rule table missed the packet-level mechanism

login-plugins.md documented only "can force online mode at pre-login" — a proxy/platform decision. A plugin that hooks the login packet and runs its own EncryptionRequest + Mojang sessionserver check (witness: LoginTo 4.0.x premium autologin, which cancels the login start, AES-encrypts the channel and only then replays a synthetic LoginStart) shows the same failure shape the page describes — never finishes joining, no kick message, nothing in the server log — from a different mechanism.

• New table row for that class, stating plainly that the v0.13.1+ re-assert cannot help: it restores Connect's own login decision, it cannot answer a handshake another plugin is waiting on.
• The first row ("only acts on offline-mode connections … → Compatible by design") now carries the packet clause, plus a sentence after the table that the row is about the login decision, not the login packet — the wrong conclusion that row invited.

3. The passthrough caveat was invisible

connect-player is absent for passthrough sessions, so the documented "extend your Floodgate-style exemption to connect-player" advice cannot fire on an offline-mode / allow-offline-mode-players endpoint. Added where the exemption is recommended: the exemption only fires where Connect authenticated the session, so on those endpoints either the endpoint has to be sending Connect-authenticated players or the plugin's conflicting mode has to be turned off, and a support answer cannot recommend the marker route there. The same rule is stated in the contract page's attribute table and prose.

Also

• Plain Paper/Spigot has no login-reassert (implemented on Velocity and BungeeCord only), so the marker is the Spigot-side integration path. Added to the re-assert section and to the contract page's operator pointer. Wording coordinated with the companion verification card t_25fd50e8: this change claims only the verified absence of a floor, not a mechanism.
• New row in compatibility.md (where support answers start), with the "High" verdict, the witness, "do not answer it with a Connect version upgrade", and the passthrough-endpoint caveat.

Guards

.web/scripts/check-docs.mjs gains assertions pinning the new contract (attribute name, Netty key, constant, single set-site, set-before-events, passthrough-absent, the never-renamed sentence, the exemption recipe), the three new login-plugins.md statements, the Spigot scope note, the sidebar link in config.ts, and the compatibility row (witness + verdict). One assertNotIncludes blocks the regression back to the ambiguous never forces online mode | Compatible by design row.

Evidence, run locally on this exact tree (CI parity: yarn install --immutable with yarn@4.17.1 from packageManager, then yarn build):

baseline:  node scripts/check-docs.mjs -> PASS ("Docs content assertions passed.")
          yarn build -> "build complete in 20.98s." + "Generated LLM routes passed."
          dist/guide/login-plugin-integration.md + .html generated;
          llms.txt -> "- [Login Plugin Integration](https://connect.minekube.com/guide/login-plugin-integration.md)"
          dist/guide/login-plugins.html contains the new row; dist/guide/compatibility.html contains the new row
11-mutation matrix (10 CAUGHT, 1 equivalent):
  remove the packet-level table row        -> CAUGHT  missing required docs coverage
  rename attribute in the published page   -> CAUGHT  missing required docs coverage
  flip the passthrough rule to "marked"    -> CAUGHT  missing required docs coverage
  restore the bare compatible-by-design row-> CAUGHT  contains retired guidance
  drop the passthrough caveat opener       -> CAUGHT  missing required docs coverage
  drop the spigot scope note               -> CAUGHT  missing required docs coverage
  drop the sidebar entry                   -> CAUGHT  missing required docs coverage
  downgrade the compat-row verdict         -> CAUGHT  missing required docs coverage
  remove the exemption-recipe line         -> CAUGHT  missing required docs coverage
  delete the page                          -> CAUGHT  (ENOENT in the guard)
  retitle the page H1 only                 -> MISSED  (equivalent on the corpus: no guard and no link depends on the H1)

yarn check:changelog-layout (Chrome geometry) is untouched by this diff and was not run locally (no browser on this host); it runs in the repo's docs CI job.

Not a deploy

Merging does not publish. The docs site is deployed manually (canary → production custom hostname) and the live host currently serves a build older than 2026-09-13, so this page still 404s until a deploy runs. That deploy is tracked by kanban t_c4b9534b and needs a Cloudflare Workers credential plus Robin's explicit authorization for the production hostname; this PR deliberately does not duplicate it.

Cross-repo note

minekube/connect-java keeps its own copy at docs/login-plugin-integration.md for plugin authors browsing the connector repo. This page points at it, and the connector-repo copy gains the matching back-reference in minekube/connect-java#173 (docs-only, docs: commit, no release impact) so the two copies stay in step.

[cloudflare-workers-and-pages]

Deploying connect-minekube with    Cloudflare Pages

Latest commit:	e7f8e8c
Status:	✅  Deploy successful!
Preview URL:	https://cfbf0a51.connect-minekube.pages.dev
Branch Preview URL:	https://docs-login-plugin-integratio.connect-minekube.pages.dev

View logs