V2: replace the Agent catalogue classic hand-off

[Paul Lizer (paullizer)]

Summary

V2's Agents entry still handed users off to classic, which becomes a dead end for non-admins under the companion "New UI only" policy. This implements row 1 of the parity issue as a native V2 flow.

• Replace the placeholder and /agents Latest Features hand-offs with native browsing: Popular usage/promotions, Personal/Group/Enterprise categories, cross-scope search, AND tag filters, remembered list/card views, and details.
• Add an authenticated, feature-gated V2 catalogue API. Governance filtering runs before usage/promotions, the response uses an explicit allowlist, and instructions follow the display setting. Unexpected failures fail closed. The classic API and administrator promotion picker remain unchanged.
• Launch chats with the exact agent and scope, including the agent's own group rather than the account's active group. Chat refreshes its authorized catalogue before resolving the launch. Long names and tags wrap on mobile, including shared modal headings.
• Reuse existing configuration, UI components, and local browser assets; add regression coverage and documentation, with application version 0.261.305. No packages, settings keys, or database migrations are added.

Restricted-agent discovery/request access is deliberately not implemented: governance-restricted agents remain hidden, including promoted agents. Other parity rows and the routing/interface-mode work in #1723 are outside this PR.

Linked issue

Refs #1722

This completes row 1 only; the umbrella issue should remain open.

Release Notes & Latest Features

• New Feature
• Bug Fix
• UI Enhancement
• Breaking Change
• Internal only

Is this visible to end users?

• Yes
• No

Is this admin-facing (Admin Settings, governance, deployment, config)?

• Yes
• No

Existing admin configuration and governance policies are reused; no new admin controls or policy settings are introduced.

Should this become a Latest Feature card?

• Yes
• No
• Already added

Screenshot needed for the card?

• Yes
• No
• Attached

A release card and catalogue screenshot are recommended, but no new card or release-note entry is included in this PR. Existing Agents shortcuts are updated.

Version bump

• application/single_app/config.py VERSION third segment bumped, or not needed because this is docs-only
• deployers/version.txt bumped, or not needed because deployers/ was not changed

Application version: 0.261.304 -> 0.261.305. No deployer changes.

Testing / validation

Results from validation of the committed change; the worktree is unchanged since that run.

Command	Result
npm --prefix application\v2_ui run typecheck	Passed
npm --prefix application\v2_ui run build	Passed; existing large-chunk warning remains
python functional_tests\test_v2_agents_catalog_endpoint.py	8/8 passed
python functional_tests\test_v2_agents_catalog.py	28 executable TypeScript checks passed
python functional_tests\test_v2_support_menu.py	8/8 passed, including 27 TypeScript checks
python functional_tests\test_v2_api_security.py	5/5 passed
python functional_tests\route_tests\test_route_blueprint_policy_inventory.py	14/14 passed
python functional_tests\route_tests\test_route_unauthenticated_policy_contract.py	9/9 passed
python functional_tests\route_tests\test_route_policy_test_coverage.py	3/3 passed
python functional_tests\test_docs_app_surface_coverage.py	7/7 passed; regenerated inventory has no semantic change
python functional_tests\test_docs_site_quality.py	6/6 passed
python -m pytest ui_tests\test_v2_agents_catalog.py ui_tests\test_v2_support_menu.py -q --browser chromium --tracing retain-on-failure	29/29 passed

Existing shared-modal keyboard/focus regressions also passed (2/2):

$env:PYTHONPATH = (Resolve-Path .\ui_tests\fixtures).Path; python -m pytest ui_tests\test_v2_group_directory.py::test_the_create_dialog_holds_and_returns_keyboard_focus ui_tests\test_v2_public_directory.py::test_the_create_dialog_holds_and_returns_keyboard_focus -q --browser chromium

Explicit XSS sink scans passed (6 full files and 3 modified files):

python scripts\check_xss_sinks.py --full-file application\v2_ui\src\lib\agentCatalog.ts application\v2_ui\src\pages\AgentsCatalogPage.tsx application\v2_ui\src\components\agentsCatalog\AgentCatalogParts.tsx application\v2_ui\src\components\agentsCatalog\AgentDetailsModal.tsx application\v2_ui\src\components\ui\Modal.tsx application\single_app\functions_v2_agents_catalog.py
python scripts\check_xss_sinks.py --base-sha HEAD application\single_app\route_backend_v2.py application\v2_ui\src\App.tsx application\v2_ui\src\lib\latestFeatureShortcuts.ts

The browser suite uses the real production SPA/CSS with closed synthetic APIs. It covers all three chat scopes and submitted agent_info, authorized-catalogue refresh, filtering, storage, loading/error/retry/unavailable states, keyboard/modal behavior, safe Markdown, and light/dark desktop/mobile overflow. Desktop light and mobile dark screenshots were also inspected. No live Azure service, Teams-tab, or separately hosted root-basename smoke test was run.

Selected regressions have verified unchanged baseline failures:

• python functional_tests\test_agents_catalog_feature.py: 11/12. Its registration check expects a direct register_route_frontend_agents(app) call, while the existing app uses Blueprint registration.
• python functional_tests\test_admin_settings_sidebar_card_parity.py: 3/4. Existing M365 retrieval card/sidebar mismatches and duplicate inbound-MCP card IDs. The tests and affected app/template inputs are unchanged.

Documentation

• Release notes updated, or not needed
• Feature documentation updated, or not needed
• Fix documentation updated, or not needed

Added docs\explanation\features\V2_AGENTS_CATALOG.md and updated the related V2 feature notes, Agents admin reference, and workspace guide. The mobile wrapping correction is covered by the feature documentation and regression suite; separate fix documentation is not needed. Release notes remain unchanged.

Security checklist

• New Flask routes include @swagger_route(security=get_auth_security())
• Settings sent to non-admin frontends use sanitize_settings_for_user()
• Browser JavaScript is served from local SimpleChat static assets only; no CDN-hosted JS
• No secrets, keys, connection strings, or local-only artifacts are included