well-known is for programmatic access, it either namespaces something you’re told to look for (e.g. various types of domain markers) or it lets you discover a feature / endpoint.

In the latter case you just probe, for instance if you’re a password manager and you have a password for site A you hit A/.well-known/change-password and if they returns something you can surface a change password link to your user.

The one you found is for OIDC provider discovery (https://openid.net/specs/openid-connect-discovery-1_0.html#P...) so someone tells you they want to log in via Google, you hit that endpoint, and it lets you setup Google as an oidc provider rather without needing to hard-code providers. Even if you just want to support Google as a provider, you hit that and you get the entire configuration rather than have to hunt down the same information in the docs.

Thank you, that it is part of OIDC provider discovery spec explains a lot.

That said, I still find it very bizzare that it's so hard to find a tangible example to see how it is in practice.

The rfc has none. Another spec including the use of it has none. In the end only completed service provider/implementers show it.

Before programmatic access happens, it needs to be written by a human. Yet the whole thing feels so human-unfriendly.

Perhaps I am biased robots.txt sets a high bar on how easy it is to find and work with?