RAOPST-4023: document the one-time first-sign-in consent dialog

[OS-joaocastilho]

Summary

Add a short note (and a Troubleshooting redirect) explaining the one-time consent dialog users will see on first OAuth sign-in against the OutSystems MCP server. Companion to OutSystems/rd-ai-ase-toolkit#223 (RAOPST-4023), which starts advertising openid offline_access on all four OAuth channels.

Problem / Why

rd-ai-ase-toolkit#223 begins advertising offline_access on the RFC 9728 protected-resource metadata, the RFC 8414 AS metadata, the WWW-Authenticate challenge, and the RFC 7591 DCR registration response. Clients that see it request it; every tenant IdP we broker to shows a one-time consent screen the first time that scope is requested. Before this PR, every install recipe here says "opens a browser for OAuth sign-in" and leaves the reader unprepared for the extra prompt.

No server-side change can suppress the dialog: it is emitted by the tenant IdP, not by this MCP or the AS proxy. The docs are the only lever.

How it is solved

Two pieces, both in README.md:

1. A "Note on the first sign-in" section, placed just above Troubleshooting so it applies to every install path. It explains what the dialog is, why it appears, that it is one-time per browser profile, and that this repo cannot switch it off.
2. A Troubleshooting row that points at that note, so a user who first meets the symptom by scrolling to Troubleshooting still lands on the explanation.

No install-recipe wording changes: they still say "opens a browser for OAuth sign-in", which stays accurate. The extra screen appears only once, so weaving it into every recipe would raise noise for everyone who has already installed once.

Alternatives considered

• Weave a "you will see a consent dialog once" clause into every install recipe. Rejected: the recipes are step-by-step and pass verbatim into agent prompts; a conditional first-time detail on every step raises noise for everyone who has already installed once. A single Note plus a Troubleshooting entry survives the copy-paste-into-the-agent workflow better.
• Add it only to Troubleshooting. Rejected: users hitting the dialog on first install may not know to look under Troubleshooting because they have not yet reached a broken state.
• Nothing (leave the docs unchanged). Rejected: this is the only user-visible artifact of the scope change, and confusing the first sign-in on an "Early Alpha" tool is exactly the wrong friction.

Why this option

Minimal footprint (five lines), single ground-truth explanation reachable from both entry points (top-down reader and troubleshooter), no coupling to individual harness sections. If the dialog wording or trigger changes upstream, only the one Note needs an edit.

Drawbacks & limitations

• The Note refers to offline_access by name to be honest about the mechanism. A non-technical reader may find the term unfamiliar; the surrounding sentence explains what it does in plain English, but a reader who scans only headings may not read that far.
• If a specific IdP does not gate offline_access behind consent (Keycloak sometimes does not, depending on realm configuration), the Note is a false alarm for that user. Preferred over the reverse failure mode (silence when the dialog does appear).
• Nothing here changes if the server later stops advertising offline_access (via the OAUTH_SCOPES=none kill switch in the server repo). The dialog would stop appearing but the Note would still be there. Cheap to remove if that ever ships.

Smoke tests

• N/A. Docs-only change; no runtime behavior. Verified locally that the new section renders and its internal anchor resolves.

Test plan

• README preview renders
• Internal anchor (#note-on-the-first-sign-in) resolves
• Land after rd-ai-ase-toolkit#223 is merged and image rolls out, so the dialog described here is actually reachable to a reader following the install path

[david-santos-os]

LGTM