feat: state provider prerequisites on connections cards

[pepmach]

Problem / Motivation

A GitLab connection can complete successfully yet expose zero tools when GitLab Duo and top-level-group MCP settings are not enabled. The Connections gallery currently provides no prerequisite guidance before the user starts that consent flow, so the zero-tool outcome looks unexplained.

Why it matters

Users should know provider-side requirements before authorizing access. Showing those requirements on the provider card turns a confusing post-connect zero-tool state into an actionable pre-connect check without moving provider policy into Kiro Crew.

What changed (motivation → approach → change)

• Add an optional registry field prerequisite_copy: a one-to-two-sentence, imperative, BLOCKING provider-side requirement. Only GitLab (Duo + top-level-group MCP access, else a connect exposes zero tools) and Atlassian (a Jira/Confluence site, else the consent page's Accept button stays disabled) carry it.
• Render it as a small amber warning icon beside Connect, only on cards that have one. Hover or keyboard focus previews the message as a portal-rendered bubble; clicking the icon pins the bubble open; clicking anywhere else (or Escape or a scroll) dismisses it, and a press inside the bubble neither dismisses nor passes through, so the steps stay selectable. The icon's accessible name is provider-scoped ("GitLab prerequisites").
• Deliberately render nothing for providers without a blocking prerequisite: gotcha_copy stays in the registry as reference data with no runtime consumer today (it is kept because the backend requires the field non-empty and pins its content in tests), and cards render only prerequisite_copy; each requirement sentence now lives in exactly one field (the GitLab/Atlassian requirement prose moved out of gotcha_copy into prerequisite_copy) — a warning box on every card meant no effective warning on any.
• Surface the same warning after connect: a connected provider whose Test returns no_tools now shows the localized prerequisite steps (prerequisite_gitlab_steps) on their own line after the localized reason, so the zero-tools state is explained on the path where the user actually lands.
• The warning renders localized catalog text (slug-keyed prerequisite_* entries in all 13 locales, with the en catalog pinned equal to the registry English by a lockstep test); the registry string is the English fallback, and the "Before you connect" label is translated everywhere.
• Preserve the current connection mint flow and hide the icon after a provider is connected.
• Add focused coverage: the icon appears exactly on providers with prerequisite_copy; hover previews and survives the pointer crossing into the bubble; click pins; outside-click, Escape, and scroll dismiss; a press inside the bubble does not dismiss; the connected state suppresses it; the en catalog is pinned equal to the registry English.

Tests

• npx vitest run src/test/ConnectionsPage.coverage.test.tsx src/test/ConnectionsPage.test.tsx — 2 files, 153 tests passed (icon presence per provider, hover preview, click-pin, outside-click dismissal, connected-state suppression).
• python -m pytest test/test_connections_registry.py test/test_security_posture.py test/test_spawn_audit.py — 116 passed (new optional field validated as a non-empty string when present).
• npx tsc --noEmit — passed.
• npx eslint on the changed page, registry, and test files — passed.
• isort, flake8, mypy (1,269 source files), Black gate, subprocess-encoding gate, and blocking scrub lint — passed.
• I18N_BASE_REF=origin/main npm run i18n:check — all 19 checks passed on this diff (the PR adds the before_you_connect label to all 13 locale catalogs; the icon/bubble revisions later added slug-keyed prerequisite_gitlab/prerequisite_atlassian so the warning itself renders localized, mirroring VALUE_PROP_KEYS, with the registry English as fallback and a lockstep test pinning en-catalog == registry).
• npm run build in website/ — production build passed.

Manual verification

Served the production build with gateway-free API fixtures and verified: only GitLab and Atlassian show the amber icon beside Connect; hovering previews the bubble; clicking pins it; clicking elsewhere dismisses it; the other four cards render no prerequisite UI.

Screenshots / video

Two evidence frames are committed under temp-screenshots/connections-gotcha-copy/ (the repository's Screenshot Evidence convention — the required CI gate reads them at the head commit) and embedded below, SHA-pinned.

Default gallery — icons only on the two providers with blocking prerequisites, all cards compact and flush:

GitLab's bubble pinned open after clicking the icon:

Related Issues

N/A — no issue was cited for this focused UI correction.

Pattern harvest

Rule candidate: review-prompt
Pattern: When provider authorization can succeed while exposing zero capabilities, surface its registry-owned prerequisites before consent.

Checklist

• At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|refactor|perf|test|chore|ci|build|revert: ...)
• Existing tests pass and new tests added for new functionality
• Self-review completed; code follows project style guidelines
• Documentation updated (N/A — the registry-owned guidance is the user-facing documentation)
• No secrets, credentials, or internal references in the diff

[github-actions]

UX Review (Fable 5) — ✅ PASS

UX-level review of d0cc83c95ac6362d390ae1d07e7c7defdd42097b — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

UX-Verdict: PASS

Blocking prerequisites now surface both before Connect and on the zero-tools result, with clear imperative copy — the flow closes even for users who miss the icon.

Suggestions

• The amber AlertTriangle is icon-only and hover-gated, so a user who goes straight for Connect never sees the blocking prerequisite pre-flight; pair it with a short visible label ("Setup required") on the two cards that carry prerequisite_copy.
• The onScroll handler dismisses a pinned bubble on any trackpad micro-scroll — pinning signals "keep this open while I follow the steps"; keep the pinned state through scroll (recompute position) and let scroll clear only the hover preview.
• In connections-prerequisite-bubble-pinned.png the bubble sits over the neighboring Atlassian card's Connect button and its own warning icon; a pos() that prefers the icon's own card side (left of the icon on right-column cards) would keep sibling actions visible while reading.

[UX-REVIEWED] d0cc83c

[github-actions]

Design Review (Fable 5) — 🟡 CONCERNS

Design-level review of d0cc83c95ac6362d390ae1d07e7c7defdd42097b — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: CONCERNS

Sound feature, but it reverses a prior "link, don't copy volatile text" decision into 27 hand-maintained copies of GitLab's settings prose.

Watch

• The deleted comment at the no_tools handler ("Link to that separately maintained source instead of copying volatile text") named a real risk this PR now accepts: GitLab's Duo/beta-feature toggles are third-party surface that churns, and the imperative steps now live in registry.json plus 13 locale catalogs × 2 keys (prerequisite_gitlab, prerequisite_gitlab_steps). When GitLab renames a setting, every non-English catalog silently serves stale instructions — worse than the old doc link, which is kept only as a secondary help href. Worth a stated ownership/refresh story (even just a verified_on-style date, which the registry already uses elsewhere).
• Whether a card warns is gated by registry prerequisite_copy, but localization is gated by the hardcoded PREREQUISITE_KEYS slug map — a third provider added registry-side ships English-only in all locales until someone knows to touch both. Mirrors the existing VALUE_PROP_KEYS pattern, so acceptable, but the lockstep is invisible from the registry file.

Suggestions

• Collapse prerequisite_gitlab_steps into prerequisite_gitlab: 13 extra translated strings exist only to drop one consequence clause; reusing the full sentence post-connect halves the staleness surface.

[DESIGN-REVIEWED] d0cc83c

[github-actions]

Opus 4.8 Review — ✅ no blocking findings

Reviewed d0cc83c95ac6362d390ae1d07e7c7defdd42097b — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] d0cc83c

Verdict parsed from the review's SHA-scoped output markers for commit d0cc83c95ac6362d390ae1d07e7c7defdd42097b.

False positive or not applicable? A repository writer can comment:
/ai-review override fable d0cc83c95ac6362d390ae1d07e7c7defdd42097b: <one-sentence reason>

[github-actions]

First Principles Review (Fable 5) — 🟡 CONCERNS

Premise-level review of d0cc83c95ac6362d390ae1d07e7c7defdd42097b — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

All counts verified. Composing the review.

First-Principles-Verdict: CONCERNS

The warning itself is earned; what rides with it is a re-implemented InfoTip (32 existing consumers) and a truncated 13-locale duplicate key with one consumer.

What this change ships

Intent: warn users about provider-side requirements before they authorize, so a GitLab connect that yields zero tools stops looking broken — an ADDITION.

1. Amber warning icon beside Connect on GitLab/Atlassian; hover previews, click pins the message — justified
2. Same icon beside Authorize and Reconnect on not-yet-granted cards — justified
3. GitLab's zero-tools Test result now shows the enable-Duo steps, not just a reason and link — justified
4. Requirement sentences moved out of gotcha_copy (0 runtime renderers, grepped gotcha_copy: registry/type/tests only) — justified move
5. New optional registry field prerequisite_copy — one consumer, generalized (fallback branch is dead, see Watch)
6. New PrerequisiteTip component re-implementing InfoTip's portal/positioning/dismiss — duplicate of website/src/components/InfoTip.tsx
7. Localized warning keys in 13 catalogs + en↔registry lockstep test — justified (CI-gated i18n invariant)
8. Second, truncated key prerequisite_gitlab_steps ×13 locales — one consumer, second spelling
9. Feedback.detail line on the card — justified, one consumer, minimal
10. Two evidence screenshots under temp-screenshots/ — justified (repo convention, 752 existing files)

Watch

• PrerequisiteTip duplicates InfoTip's portal, 300px/8px pos() clamp, outside-click dismiss, and aria name/description split (grepped InfoTip imports: 32 runtime files). The delta — hover grace timers, capture-phase scroll dismiss, Escape — exists only to serve hover preview, and the WCAG 1.4.13 obligations cited apply because it hovers; nothing derived requires hover when every other tip on the dashboard is click-to-open.
• Both provider.prerequisite_copy fallback branches (ConnectionsPage.tsx:707, 710) are unreachable: the lockstep test forces a catalog entry for every provider carrying the field, and both slugs are in PREREQUISITE_KEYS.
• Description says "Keep registry guidance in English and mark it lang="en""; the diff renders localized catalog text and contains no lang attribute — a later revision the description only half-absorbed.

Subtractions

• Drop prerequisite_gitlab_steps from all 13 catalogs; reuse prerequisite_gitlab at ConnectionsPage.tsx:1502 — its trailing clause merely restates the reason_no_tools_listed line above it (1 consumer counted).
• Replace PrerequisiteTip with the existing InfoTip (components/InfoTip.tsx) carrying the amber trigger; deleting hover deletes the grace timers, scroll listener, and Escape handling with it (~60 of its ~90 lines).
• Delete the two dead provider.prerequisite_copy fallback branches — the lockstep test already guarantees the catalog hit.

[FIRST-PRINCIPLES-REVIEWED] d0cc83c

[github-actions]

GPT 5.6 Review — ✅ no blocking findings

GPT 5.6 completed its review of d0cc83c95ac6362d390ae1d07e7c7defdd42097b and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] d0cc83c

False positive or not applicable? A repository writer can comment:
/ai-review override gpt d0cc83c95ac6362d390ae1d07e7c7defdd42097b: <one-sentence reason>

[pepmach]

• Escape leaves a focus-opened tooltip visible — span=7e5e5a04e23d — fixed

The dismiss effect was gated on pinned, so the Escape/outside-click listeners never registered for a tip opened by hover or keyboard focus alone. The effect is now gated on open (pinned or hovered), so Escape dismisses every visible tip (WCAG 1.4.13). Regression added: a hover-opened, never-pinned tip is asserted dismissed on Escape. Fixed in 09e1f4dc6cbc73a04f82a17ed334eaabe6396b8f.

[pepmach]

• Hardcoded rgba(0,0,0,0.5) ignores theme shadow tokens — span=7e5e5a04e23d — fixed

The bubble now uses var(--shadow-lg), which carries per-theme values in index.css. Fixed in 09e1f4dc6cbc73a04f82a17ed334eaabe6396b8f.

[pepmach]

• Focus-opened tooltip undismissable without moving focus (WCAG 1.4.13) — span=d5f4ded6792e — fixed

Correct find: the dismiss effect's if (!pinned) return gate meant the Escape keydown listener existed only for pinned tips. The effect is now gated on open (pinned or hovered/focused), so a tip opened by keyboard focus alone dismisses on Escape without moving focus. A regression test opens the tip by hover only, presses Escape, and asserts it is gone. Fixed in 09e1f4dc6cbc73a04f82a17ed334eaabe6396b8f.

[pepmach]

• Unreferenced binary artifacts under temp-screenshots/ — span=5a836aea4576 — rebutted

Committed, SHA-pinned screenshots under temp-screenshots/ are this repository's Screenshot Evidence convention, enforced by the required Screenshot Evidence CI check for UI-changing PRs: the PR body embeds each image by raw URL at the head commit, which requires the file to exist in the tree. They are referenced (both are embedded in this PR's body), and merged precedent uses the identical pattern: #7750 (temp-screenshots/connections-flush-rows/), #7861 (temp-screenshots/connections-test/), plus open #8062/#8065. Checkout-size policy for this directory is a repo-wide convention decision, not something to change unilaterally in this PR.

[pepmach]

• Incomplete GitLab prerequisite — fixed

Correct find: the trimmed copy named two of GitLab's three blocking requirements. prerequisite_copy now reads "Enable GitLab Duo with beta and experimental features, and allow MCP server access for your top-level group — without them, connecting succeeds but exposes no tools", and the coverage test pins all three phrases so dropping any one fails. Fixed in 04d5ebe12ec2ec1ff7a58edd339e8b3938f978ea.

[pepmach]

• Pinned bubble detaches on scroll — fixed

The dismiss effect now also listens for scroll in the capture phase (any scrolling ancestor, not just the window) and dismisses the bubble, with a regression test. Fixed in 04d5ebe12ec2ec1ff7a58edd339e8b3938f978ea.

[pepmach]

• Task-gating info behind a hover icon — conscious tradeoff, human-signed

The repository owner explicitly specified this design after rejecting the always-visible box revision, reviewed rendered mockups of both states, and approved the icon. The differential cost for GitLab is mitigated by the copy itself stating the silent-failure consequence.

[pepmach]

• temp-screenshots binaries — retained deliberately; now mentioned in the description

Committed SHA-pinned evidence under temp-screenshots/ is this repository's Screenshot Evidence convention (718 existing files; merged precedent #7750, #7861), and the required Screenshot Evidence gate reads the embedded raw URLs at the head commit. The description now names the two files explicitly. Repo-wide policy for this directory's history cost is a maintainer decision, not one to change unilaterally here.

[pepmach]

• Description claims a removal that never happened — fixed

Correct: the base never rendered gotcha_copy, so nothing was removed. The description now states what is true — cards render only prerequisite_copy, and the requirement sentences moved between fields. Fixed in the PR body alongside 04d5ebe12ec2ec1ff7a58edd339e8b3938f978ea.

[pepmach]

• PrerequisiteTip re-implements InfoTip machinery — deliberate module-local duplication

Extending the shared InfoTip (used across the app) with hover-open, a heading slot, warn tone, and an icon slot inside a Connections feature PR widens a shared primitive's API and blast radius for ~40 saved lines. Kept local and documented; unifying the two is a reasonable dedicated follow-up.

[pepmach]

• Each prerequisite lives twice in the same registry entry — fixed

The GitLab and Atlassian requirement sentences are deleted from gotcha_copy; each prerequisite now lives only in prerequisite_copy. GitLab's gotcha_copy keeps only the distinct write-scope fact (its "can write" content stays pinned by the backend test); Atlassian's keeps the Trello-exclusion and write-trim guidance. Fixed in 04d5ebe12ec2ec1ff7a58edd339e8b3938f978ea.

[pepmach]

• Single-child wrapper div — removed

The vestigial space-y-2.5 wrapper from the removed warning-box revision is gone. Fixed in 04d5ebe12ec2ec1ff7a58edd339e8b3938f978ea.

[pepmach]

• PrerequisiteTip copies InfoTip's tooltip machinery — deliberate, see the design-lane record

Module-local component over widening the shared InfoTip API in a feature PR; unification is a sensible dedicated follow-up.

[pepmach]

• Drop prerequisite_gitlab_steps and reuse the full string — held; the tail clause is what the UX lane rejected

The sole difference between the two strings — "connecting succeeds but exposes no tools" — is exactly the clause the UX lane flagged as a run-on restating the alert's own lead ("Offered no tools to inspect") in the state where it renders. Reusing the full string reintroduces that accepted finding. Two variants with distinct jobs (pre-connect warning with consequence; post-connect steps without restating the consequence) is the settled shape.

[pepmach]

• Drop the un-keyed fallback ternary arm — held as a cheap explicit fallback

Correct that the lockstep test makes the arm unreachable in any shipped state. It is kept deliberately as two lines of explicit fallback for the window where a provider gains prerequisite_copy mid-development before its catalog key lands: the alternative is a non-null assertion on the map lookup, which trades a readable fallback for a potential runtime undefined behind a lint suppression.

[pepmach]

• Lockstep guards only en; 12 locales can drift — the en pin is the semantic anchor, translation lag is the i18n lifecycle

New sub-argument on a dispositioned item, answered once: the en catalog is the semantic source the lockstep test anchors to the registry; the 12 translations updating after a registry change is the ordinary localization lifecycle shared by every catalog string in the product (the changed-values QA gate reviews them at edit time). A per-locale semantic pin would require machine-checking translation meaning, which no other string in the repo attempts.

[pepmach]

• Bubble dismisses on inner mousedown and is unreachable across the hover gap — fixed

Correct on both counts, and the selectable-copy claim in my own comment was contradicted by the handler. The outside-press handler now excludes tipRef (matching InfoTip), so starting a drag-selection inside the bubble no longer unmounts it, and hover-off uses a 120ms grace with the bubble itself holding hover, so the pointer can cross the gap (WCAG 1.4.13 hoverable). Both behaviors are regression-tested. The caret suggestion is noted as cosmetic polish and deliberately not taken this round — the bubble self-identifies via its provider-scoped heading. Fixed in de1902f96d9663c7fe2564e3949206589bf7683d.

[pepmach]

• Volatile GitLab settings prose pinned into product copy — user-reviewed and retained

The repository owner reviewed this tradeoff against the UX lane's named-steps requirement (the docs-link-only original was the G1 defect) and ruled for the visible named steps. The en↔registry lockstep test keeps the semantic source drift-detectable; a GitLab-side rename costs one registry edit plus ordinary retranslation.

[pepmach]

• Deleting gotcha_copy is the larger deferred subtraction — agreed, deferred to a follow-up

Agreed in substance: the field has zero runtime consumers and its retention reason is the backend's own non-empty requirement. Deleting it touches the backend registry contract, its validation, and content-pinning tests across all six providers — backend surgery that belongs in its own small PR rather than this UI change. Deferred deliberately.

[pepmach]

• Hover-only delivery of task-gating copy — final human ruling: icon+bubble, decided on rendered comparison

The repository owner had BOTH designs rendered from the real bundle — the hover icon+bubble and the always-visible inline band — and after briefly shipping the band reverted it on sight, ruling for the icon+bubble as the shipped design. This is a final, informed product decision made on pixels, not a default; the post-connect no_tools detail remains GitLab's in-app recovery surface.

[pepmach]

• Pinned bubble occlusion — accepted as the cost of the chosen design, with mitigations shipped

With the icon+bubble chosen over the band on a rendered comparison, the transient occlusion while pinned is an accepted tradeoff. Shipped mitigations: a press inside the bubble is swallowed (never reaches a covered control), outside-click/Escape/scroll all dismiss, and hover has a travel grace, so the worst case is one extra dismissal click.

[pepmach]

• PrerequisiteTip duplicating InfoTip — retained by the same human ruling

The owner's rendered-comparison ruling keeps the bubble component. The module-local duplication rationale from the earlier record stands (extending the shared InfoTip's API inside a feature PR widens blast radius); folding the two tooltips together remains a sensible dedicated follow-up.

[pepmach]

• Un-keyed fallback ternary arm — restored with the chosen design

The arm returned with the icon+bubble revert. It remains two lines of explicit fallback covering the window where a provider gains prerequisite_copy before its catalog key lands; the alternative is a non-null assertion. Kept deliberately.

[pepmach]

• Prerequisite omitted from Authorize/Reconnect consent actions — fixed — span=7e5e5a04e23d

Correct find on the re-review: a configured-but-ungranted provider offers Authorize (and needs-attention offers Reconnect), which start the identical consent flow and hit the identical provider-side wall. The tip is now one shared element rendered beside every consent-initiating CTA — Connect, Authorize, and Reconnect — with a regression test pinning the Authorize case for an ungranted GitLab. Fixed in d0cc83c95ac6362d390ae1d07e7c7defdd42097b.

[pepmach]

• Description half-absorbed a later revision (lang="en" vs localized rendering) — fixed

Correct: the bullet described the cycle-4 implementation; the shipped tree renders localized slug-keyed catalog text with no lang attribute. The description now states the localized rendering, the en↔registry lockstep, and the English fallback role of the registry string. Body-only fix; the head is unchanged.

[bolichen97]

Approving on the strength of a full readiness audit of every open PR against main, not a
line-by-line reading of this diff — recording that plainly so the next reader knows what this
stamp does and does not cover.

Verified against this exact head SHA:

• readiness: passed present, and PR Readiness — the one required status context on main
  (ruleset protected-branches) — is success on this head.
• No check run on this head is failure, cancelled, timed_out or still in flight. Skipped
  jobs are path-filtered conditionals, none of them required.
• mergeable: true, and the head is not far enough behind main for its green CI to describe a
  base that no longer exists.
• No surviving reviewer CHANGES_REQUESTED: any such review is on an older commit and therefore
  already dismissed by dismiss_stale_reviews_on_push.
• Every issue comment, inline review comment and review thread was read and classified. Nothing
  left is an unresolved human change request — the remainder is bot review-lane output, resolved
  or outdated threads, explicitly non-blocking suggestions, and author status notes.

Auto-merge (squash) is armed, so this lands once every other ruleset requirement is met.