Skip to content

🙌 OpenHands: AI-Driven Development

feat(onboarding): open the next setup guide step when one is done in Canvas (#18138)

Hiep Le5fea36ab7fea
diff --git a/.pr/issue-17680-live-verification.html b/.pr/issue-17680-live-verification.html
deleted file mode 100644
index 5f8f7e8400..0000000000
--- a/.pr/issue-17680-live-verification.html
+++ /dev/null
@@ -1,214 +0,0 @@
-<!doctype html>
-<html lang="en">
- <head>
- <meta charset="utf-8" />
- <meta name="viewport" content="width=device-width, initial-scale=1" />
- <title>Issue #17680 — live verification</title>
- <style>
- :root {
- color-scheme: dark;
- font-family:
- Inter,
- ui-sans-serif,
- system-ui,
- -apple-system,
- BlinkMacSystemFont,
- "Segoe UI",
- sans-serif;
- background: #09090b;
- color: #f4f4f5;
- }
- body {
- margin: 0;
- padding: 48px 24px;
- }
- main {
- max-width: 960px;
- margin: 0 auto;
- }
- h1,
- h2 {
- letter-spacing: -0.025em;
- }
- h1 {
- margin: 0 0 8px;
- font-size: 36px;
- }
- h2 {
- margin: 0 0 12px;
- font-size: 20px;
- }
- p,
- li {
- color: #d4d4d8;
- line-height: 1.6;
- }
- .lede {
- margin: 0 0 32px;
- color: #a1a1aa;
- }
- .grid {
- display: grid;
- grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));
- gap: 16px;
- margin: 20px 0 32px;
- }
- .card {
- border: 1px solid #27272a;
- border-radius: 16px;
- padding: 20px;
- background: #111113;
- }
- .badge {
- display: inline-flex;
- align-items: center;
- border-radius: 999px;
- padding: 5px 10px;
- font-size: 12px;
- font-weight: 700;
- }
- .success {
- color: #86efac;
- background: #052e16;
- }
- .review {
- color: #fde68a;
- background: #422006;
- }
- code,
- pre {
- font-family: "SFMono-Regular", Consolas, "Liberation Mono", monospace;
- }
- code {
- color: #e4e4e7;
- }
- pre {
- overflow-x: auto;
- border: 1px solid #27272a;
- border-radius: 12px;
- padding: 16px;
- background: #09090b;
- color: #e4e4e7;
- line-height: 1.5;
- }
- table {
- width: 100%;
- border-collapse: collapse;
- margin: 16px 0 32px;
- }
- th,
- td {
- border-bottom: 1px solid #27272a;
- padding: 12px;
- text-align: left;
- vertical-align: top;
- }
- th {
- color: #a1a1aa;
- font-size: 12px;
- text-transform: uppercase;
- letter-spacing: 0.08em;
- }
- .note {
- border-left: 3px solid #f59e0b;
- padding-left: 16px;
- }
- </style>
- </head>
- <body>
- <main>
- <h1>Narrow “Needs review” to genuine review cases</h1>
- <p class="lede">
- Reviewer evidence for OpenHands/OpenHands issue #17680. Verified on the
- real local Agent Canvas, Agent Server, and automation service stack on
- September 24, 2026.
- </p>
-
- <h2>Behavior change</h2>
- <div class="grid">
- <section class="card">
- <span class="badge review">Before: Needs review</span>
- <p>
- Any completed run with a finish response but no recognized
- <code>status</code> was treated as unknown, including a response
- containing only <code>outcome_summary</code>.
- </p>
- </section>
- <section class="card">
- <span class="badge success">After: Successful</span>
- <p>
- A completed run now defaults to success when the response omits
- <code>status</code>. The outcome summary is still displayed.
- Explicit unrecognized status strings still require review.
- </p>
- </section>
- </div>
-
- <h2>Decision table</h2>
- <table>
- <thead>
- <tr>
- <th>Completed run response</th>
- <th>Badge</th>
- <th>Summary</th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td><code>{ "outcome_summary": "Report published" }</code></td>
- <td><span class="badge success">Successful</span></td>
- <td>Report published</td>
- </tr>
- <tr>
- <td><code>{ "status": "unexpected", ... }</code></td>
- <td><span class="badge review">Needs review</span></td>
- <td>Preserved when provided</td>
- </tr>
- <tr>
- <td>No finish response</td>
- <td><span class="badge success">Successful</span></td>
- <td>None</td>
- </tr>
- </tbody>
- </table>
-
- <h2>Real-stack verification</h2>
- <section class="card">
- <p>
- Created the isolated prompt automation
- <code>PR 17680 live verification</code>
- (<code>0d36598c-537d-4deb-92e5-ec2bcf680a33</code>) and manually
- dispatched run <code>e1d6e30f-1556-439c-bbae-605377679acf</code>. The
- prompt prohibited network, repository, secret, plugin, integration,
- and file access. The automation was disabled after the run.
- </p>
- <p>
- The live SDK (1.49.5) rejected a summary-only FinishTool call because
- its schema requires <code>status</code>. The resulting fallback
- metadata remained visibly marked
- <span class="badge review">Needs review</span>, confirming that
- explicit unknown/unrecognized outcomes retain the conservative state.
- Existing real completed script runs with no finish response remained
- <span class="badge success">Successful</span>.
- </p>
- <p class="note">
- The live service cannot produce the exact backward-compatibility
- payload from this issue because its current FinishTool schema requires
- <code>status</code>. The summary-only and custom-metadata cases are
- therefore exercised through the frontend's real display helper and
- component tests, without changing the backend or its stored data.
- </p>
- </section>
-
- <h2>Verification completed</h2>
- <ul>
- <li>
- Focused display, modal, health-card, and manifest tests: 67 passed.
- </li>
- <li>Full test suite under UTC: 7,774 passed, 7 todo.</li>
- <li>Application and library production builds passed.</li>
- <li>Lint passed with pre-existing warnings and no errors.</li>
- </ul>
- </main>
- </body>
-</html>
diff --git a/.pr/issue-17936/after-refused.png b/.pr/issue-17936/after-refused.png
deleted file mode 100644
index bb4b94dec1..0000000000
Binary files a/.pr/issue-17936/after-refused.png and /dev/null differ
diff --git a/.pr/issue-17936/after-unreachable.png b/.pr/issue-17936/after-unreachable.png
deleted file mode 100644
index 771a2ff781..0000000000
Binary files a/.pr/issue-17936/after-unreachable.png and /dev/null differ
diff --git a/.pr/issue-17936/before-refused.png b/.pr/issue-17936/before-refused.png
deleted file mode 100644
index d490301b3f..0000000000
Binary files a/.pr/issue-17936/before-refused.png and /dev/null differ
diff --git a/.pr/issue-17936/before-unreachable.png b/.pr/issue-17936/before-unreachable.png
deleted file mode 100644
index e91b769480..0000000000
Binary files a/.pr/issue-17936/before-unreachable.png and /dev/null differ
diff --git a/.pr/map-maintenance/2026-10-08/coverage-summary.json b/.pr/map-maintenance/2026-10-08/coverage-summary.json
deleted file mode 100644
index c43ec15b22..0000000000
--- a/.pr/map-maintenance/2026-10-08/coverage-summary.json
+++ /dev/null
@@ -1,16 +0,0 @@
-{
- "reviewed_at": "2026-10-08T07:04:32.322254+00:00",
- "families": 27,
- "mapped_behaviors": 736,
- "counts": {
- "pass": 0,
- "fail": 0,
- "blocked": 736,
- "not-run": 0
- },
- "live_entrypoints_exercised": 0,
- "live_viewports_exercised": 0,
- "launched_runs": 0,
- "model_spend_usd": 0,
- "limitation": "Behavior inventory with literal family prerequisites and entry points, not an executed entry-point/viewport ledger. No launched run exists, so CLI evidence add/report has no valid run to attach to."
-}
diff --git a/.pr/map-maintenance/2026-10-08/intent.md b/.pr/map-maintenance/2026-10-08/intent.md
deleted file mode 100644
index f3d817bf39..0000000000
--- a/.pr/map-maintenance/2026-10-08/intent.md
+++ /dev/null
@@ -1,39 +0,0 @@
-# Reviewed delta intent
-
-Read-only review at 2026-10-08 07:01:07 UTC. Repository OpenHands/OpenHands.
-
-BASE ed815e141409c7b52991ab8d13c553b595da9165; TARGET baf1cbef090fce793d3017276c1025c057920a4b.
-
-All 14 commits resolve via commits/<sha>/pulls to one merged PR each. Intent: 14 documented, 0 undocumented, 0 contradictory. Runtime is separate and not assessed by this reader.
-
-| Commit | PR | Intent | Families / scope | Needed live proof |
-|---|---|---|---|---|
-| 7cd649604 | [#18051](https://github.com/OpenHands/OpenHands/pull/18051) | SDK HttpError toasts show readable server message/validation content; unreadable bodies use localized caller fallback. Axios/plain Error/string wording stays stable. | F01, F03, F04, F07, F08, F10, F13, F15, F16, F17, F18, F22, F25, F27 | Desktop and phone Condenser invalid max_size save -> readable validation toast; Stale MCP delete -> readable not-found server reason; Shared-conversation route on Local -> readable Not Found toast; Application save after backend stop -> localized fallback; Additional distinct global and direct helper consumers including ACP secret save, conversation read/download/compact, onboarding and automation responder error paths |
-| a2a74bdbe | [#18085](https://github.com/OpenHands/OpenHands/pull/18085) | Refresh previously fixed plugin/App errors, hooks, automation preset sources and Git Sync credentials; retain verified remaining failures and record maintenance baseline. | F05, F07, F08, F19, F20, F23, F24 | Skill/map-only change: static integrity and recipe correctness against intended product fixes; no product behavior introduced by this commit |
-| 2ad3c574b | [#18087](https://github.com/OpenHands/OpenHands/pull/18087) | Give inert test Slack stand-in catalog command/args so installed-detection matches; keep placeholder credentials and offline/no real server behavior. | Non-user-facing harness/test change | Explicit non-user-facing E2E fixture change; mocked spec outcomes do not prove live product behavior |
-| 9f055996c | [#18095](https://github.com/OpenHands/OpenHands/pull/18095) | Escape closes composer tools, status-dot and tabs menus through shared topmost-layer stack; focus returns for click/Enter while hover close preserves focus. | F05, F06, F07, F08 | Desktop and phone composer tools Escape from trigger/item; Status menu hover/click/Enter Escape focus behavior; Desktop drawer and phone panel tabs menu Escape from trigger/item; Layering: status over context-window, command menu over tools/tabs closes most recent layer first; Outside click/toggle/item close, reopen and neighboring Escape consumers |
-| 7ea83bab4 | [#18093](https://github.com/OpenHands/OpenHands/pull/18093) | Add daily delta maintenance, source/testid checks, baseline tools, affected-family mapping, ledger notes/counts/comparison, browser clock, and launch/tmux fixes. | F02, F18, F26 | Credential-free map commands and harness regression checks; Live proof for changed browser/run-management verbs when correction depends on them |
-| 208993e6c | [#18105](https://github.com/OpenHands/OpenHands/pull/18105) | Add twenty proven map recipes across twelve families, correct four drift cases, lengthen browser RPC limits to requested timeout, and update existing git fixture origin on --remote. | F01, F03, F05, F06, F09, F10, F17, F18, F20, F25, F26, F27 | Skill/map-only change: retain static recipe integrity and documented prerequisites; Live browser-clock/RPC-limit/git-fixture proof where any maintenance correction depends on these verbs |
-| 3b5304fcd | [#18079](https://github.com/OpenHands/OpenHands/pull/18079) | Wait for delete-profile success toast and onClose after asynchronous mutation resolves; product delete behavior unchanged. | Non-user-facing harness/test change | Explicit non-user-facing unit-test synchronization change |
-| f1aed4e3e | [#17988](https://github.com/OpenHands/OpenHands/pull/17988) | Detect enterprise organization/membership-suspended 403 scoped to the request's backend/org; block app with explanatory screen and offer other workspace buttons. | F25 | Real Enterprise backend with org suspension and membership suspension; desktop/phone messages and allowed other-workspace switch; In-flight request keeps suspension attached to requested org/backend; Unscoped/unrelated errors and exempt Super Admin path remain unaffected |
-| fd093cd55 | [#17969](https://github.com/OpenHands/OpenHands/pull/17969) | Eligible first Enterprise Super Admin sees server-derived setup guide, shared ordered progress, collapse/dismiss/links/navigation refresh; ordinary checklist suppressed only while guide loads/shows. | F01, F02, F17, F21, F22, F25 | Real Enterprise backend exposing /api/admin/setup-state and eligible first Super Admin guide org; Desktop/phone guide progress, collapse/dismiss, server steps and proper OHE/Canvas links; Navigation, automation creation and MCP add invalidate/read updated setup state; Local/SaaS/non-admin no extra setup request; feature-off HTML falls back to ordinary checklist; Host-locked navigation same-tab and guide/checklist mutual exclusion |
-| 50535c32a | [#18122](https://github.com/OpenHands/OpenHands/pull/18122) | Scope Commits overflow fallback locator to tabs pane's Customize tabs menu, excluding sidebar/title ellipsis buttons. | Non-user-facing harness/test change | Explicit non-user-facing E2E locator change; no product behavior introduced |
-| 64fe658d5 | [#18084](https://github.com/OpenHands/OpenHands/pull/18084) | Fix live E2E graceful SIGTERM cleanup and short tmux socket path; use Agent Server default critic route/model with only critic key configured. | Non-user-facing harness/test change | Explicit non-user-facing E2E configuration/helper/guide; actual critic success requires supported critic key and API, not invented DeepSeek substitute |
-| 6e8157147 | [#18121](https://github.com/OpenHands/OpenHands/pull/18121) | Point active named default agent profile to BETA before same-model profile picker test; preserve assertion and cleanup restoration. | Non-user-facing harness/test change | Explicit non-user-facing E2E profile arrangement; no product behavior introduced |
-| 3f9868476 | [#18128](https://github.com/OpenHands/OpenHands/pull/18128) | Cloud backend health interval becomes 5 minutes without focus/reconnect bursts; disabled repository queries disable installations; Cloud menu repository/search loads only while open. | F03, F04, F07, F25, F27 | Real Cloud backend at desktop/phone: observe org probe cadence and no focus/reconnect probe; Closed Cloud new-conversation menu has no repository/search/installation traffic; opening enables, closing disables; provider/search and create still work; Home repository dropdown still honors enabled, installation/direct providers and pagination; Local backend 30-second/focus/reconnect behavior unchanged, disabled/missing-key/failure-cap health unchanged |
-| baf1cbef0 | [#18086](https://github.com/OpenHands/OpenHands/pull/18086) | All Do Not Track signals suppress PostHog initialization and requests while consent remains denied; standard initialization/consent and hard-disable behavior unchanged. | F01, F26 | Observe real browser network under build DNT, browser DNT, process DNT/runtime embedding disable where supported; No requests to PostHog/z.openhands.dev including config/flags; telemetry consent stays denied; Normal consent/init and runtime hard-disable/re-enable boundary separately; avoid sending real telemetry |
-
-## Scope notes
-
-- No live runtime classification made by this reader.
-- Private OHE issue acceptance criteria unavailable; PRs #17988/#17969 descriptions document intent.
-- Closed #18091 retains superseded E2E/spec-linking acceptance criteria, with deliberate scope reduction documented by final #18093 description and approving review.
-- PR-only artifact cleanup comment from github-actions[bot] appears on each PR; no inline review comments were returned.
-
-Last merged PR at/before TARGET: https://github.com/OpenHands/OpenHands/pull/18086 (2026-10-08T03:13:50Z).
-
-Exact supplied new-PR HUMAN text with substitutions:
-
-Engel Nyst (@enyst) set up a daily automation that keeps the verify-openhands feature map current. This PR is its run for main@baf1cbef0, after PR https://github.com/OpenHands/OpenHands/pull/18086.
-
-This read does not authorize or perform GitHub mutation and launches no stack.
diff --git a/.pr/map-maintenance/2026-10-08/issue-closures.json b/.pr/map-maintenance/2026-10-08/issue-closures.json
deleted file mode 100644
index a4c2b35066..0000000000
--- a/.pr/map-maintenance/2026-10-08/issue-closures.json
+++ /dev/null
@@ -1,184 +0,0 @@
-{
- "base": "ed815e141409c7b52991ab8d13c553b595da9165",
- "target": "baf1cbef090fce793d3017276c1025c057920a4b",
- "base_time": "2026-10-06T20:43:00Z",
- "audit_time_utc": "2026-10-08T07:02:04.406677+00:00",
- "counts": {
- "references": 65,
- "issues": 46,
- "issues_open": 40,
- "issues_closed": 6,
- "pull_requests": 19,
- "pull_requests_merged": 18,
- "pull_requests_closed_unmerged": 1
- },
- "closed_since_base": [
- "OpenHands/OpenHands#18094"
- ],
- "closed_issues_with_stale_failure_description": [
- "OpenHands/OpenHands#18094",
- "OpenHands/automation#551"
- ],
- "required_families": [
- "F05",
- "F07",
- "F08",
- "F24"
- ],
- "required_checks": [
- {
- "issue": "https://github.com/OpenHands/OpenHands/issues/18094",
- "closed_at": "2026-10-07T01:05:49Z",
- "fix_pr": "https://github.com/OpenHands/OpenHands/pull/18095",
- "feature_id": "F05.plus-menu",
- "file": ".agents/skills/verify-openhands/references/feature-map/F05-composer.md",
- "recipe_lines": [
- 64,
- 65
- ],
- "stale_gotcha_line": 94,
- "entry_points": [
- "Home composer /",
- "Conversation composer /conversations/<id>"
- ],
- "viewports": [
- "desktop",
- "phone"
- ],
- "selected_backend_scenario": "Local OpenHands Agent Server; plus tools menu",
- "expected": "Escape closes tools-context-menu, chat-plus-button aria-expanded=false and focus returns to chat-plus-button, also from a menu item. One Escape closes top-most layer when command menu is layered over the tools menu. Narrow More input actions menu is outside issue 18094 scope and remains a separate known failure.",
- "prerequisites": [
- "A healthy doctored isolated real stack",
- "Conversation entry requires an existing real conversation and selected profile; the literal family preconditions require DeepSeek credentials and a finished real-model turn",
- "No model call is needed for the Home menu keyboard interaction itself"
- ]
- },
- {
- "issue": "https://github.com/OpenHands/OpenHands/issues/18094",
- "closed_at": "2026-10-07T01:05:49Z",
- "fix_pr": "https://github.com/OpenHands/OpenHands/pull/18095",
- "feature_id": "F07.status-menu",
- "file": ".agents/skills/verify-openhands/references/feature-map/F07-conversation-page.md",
- "recipe_lines": [
- 65,
- 70
- ],
- "stale_gotcha_line": 93,
- "entry_points": [
- "Conversation header reached by sidebar row",
- "Conversation header direct URL /conversations/<id>"
- ],
- "viewports": [
- "desktop",
- "phone"
- ],
- "selected_backend_scenario": "Local OpenHands Agent Server; running/paused status menu",
- "expected": "Escape closes server-status-context-menu. Click/Enter-opened menu restores server-status-menu-trigger focus. Hover-opened menu preserves current focus. Layered context-window popover remains after first Escape and closes after second.",
- "prerequisites": [
- "A healthy doctored isolated real stack",
- "A finished real conversation and a paused/running fixture as required by the literal F07 recipe",
- "The literal conversation preconditions require an active DeepSeek profile and supplied DEEPSEEK_API_KEY or key file"
- ]
- },
- {
- "issue": "https://github.com/OpenHands/OpenHands/issues/18094",
- "closed_at": "2026-10-07T01:05:49Z",
- "fix_pr": "https://github.com/OpenHands/OpenHands/pull/18095",
- "feature_id": "F08.tabs-menu",
- "file": ".agents/skills/verify-openhands/references/feature-map/F08-workspace-files-and-changes.md",
- "recipe_lines": [
- 73
- ],
- "stale_gotcha_line": 107,
- "entry_points": [
- "Desktop conversation right drawer via right-panel-toggle",
- "Phone panel via right-panel-toggle",
- "Phone direct /conversations/<id>/panel"
- ],
- "viewports": [
- "desktop",
- "phone"
- ],
- "selected_backend_scenario": "Local OpenHands Agent Server; Customize tabs menu",
- "expected": "Escape closes all conversation-tabs-menu-* rows and focus returns to Customize tabs trigger, also with focus on a row. First Escape closes command menu layered above; second closes tabs menu.",
- "prerequisites": [
- "A healthy doctored isolated real stack",
- "A real conversation and right drawer/panel page",
- "The literal F08 family workspace/model preconditions remain required for a full family pass"
- ]
- },
- {
- "issue": "https://github.com/OpenHands/automation/issues/551",
- "closed_at": "2026-10-06T12:10:56Z",
- "fix_pr": "https://github.com/OpenHands/automation/pull/563",
- "feature_id": "F24.encryption",
- "file": ".agents/skills/verify-openhands/references/feature-map/F24-git-sync.md",
- "recipe_lines": [
- 67
- ],
- "stale_gotcha_line": 95,
- "entry_points": [
- "Automate dashboard > Git Sync",
- "Direct URL /automations/git-sync"
- ],
- "viewports": [
- "desktop",
- "phone"
- ],
- "selected_backend_scenario": "Local automation service Git Sync with local git remote fixture",
- "expected": "Setting or rotating encryption key then syncing re-exports every existing automation as ciphertext without individually editing it; clearing key then syncing re-exports plaintext. Existing current recipe explicitly dirties an automation before sync, masking the previously fixed defect, so re-drive non-dirty fixtures too.",
- "prerequisites": [
- "A healthy doctored isolated real stack with real automation service carrying automation PR 563; TARGET pins automation 1.19.0",
- "Local git fixture qa-sync-remote, writable qa-sync branch, configured Git Sync and already-exported inert QA_F24 Sync automation",
- "No LLM profile, LLM API key, paid model calls, external Git credentials or real schedule are required"
- ]
- }
- ],
- "other_closed_issue_assessments": [
- {
- "issue": "OpenHands/OpenHands#17939",
- "closed_at": "2026-10-06T05:23:09Z",
- "families": [
- "F12",
- "F13",
- "F15",
- "F17",
- "F18"
- ],
- "assessment": "Historical wording explicitly says PR 18035 fixed Canvas copy; no current known-failure claim against closed issue."
- },
- {
- "issue": "OpenHands/OpenHands#17934",
- "closed_at": "2026-10-06T00:56:15Z",
- "families": [
- "F13"
- ],
- "assessment": "Explicitly distinguishes closed LLM menu issue fixed by PR 18019 from current agent menu open issue 18060."
- },
- {
- "issue": "OpenHands/OpenHands#17930",
- "closed_at": "2026-10-06T05:19:12Z",
- "families": [
- "F17"
- ],
- "assessment": "Explicit current intended behavior after PR 18034; no stale failure."
- },
- {
- "issue": "OpenHands/OpenHands#17562",
- "closed_at": "2026-09-24T12:02:24Z",
- "families": [
- "F27"
- ],
- "assessment": "Row F27.info-modals-phone and gotcha say passes. Gotcha line 108 nevertheless calls it a known open issue; GitHub state label is stale but not a current failure claim or new closure requiring delta retest."
- },
- {
- "reference": "OpenHands/software-agent-sdk#5531",
- "closed_at": "2026-10-06T18:02:09Z",
- "families": [
- "F15"
- ],
- "assessment": "Closed unmerged PR, not a closed issue; current map correctly explains dropdown remains expected behavior."
- }
- ],
- "live_result": "not-run by this read-only audit; parent reports stacks blocked by memory preflight"
-}
diff --git a/.pr/map-maintenance/2026-10-08/report.md b/.pr/map-maintenance/2026-10-08/report.md
deleted file mode 100644
index cd9dcb933c..0000000000
--- a/.pr/map-maintenance/2026-10-08/report.md
+++ /dev/null
@@ -1,45 +0,0 @@
-# 2026-10-08 DELTA maintenance — blocked/partial
-
-I'm an AI agent (Codex) helping Engel Nyst (@enyst) with project work.
-
-Two new enterprise surfaces now have explicit **Not mapped** reasons and exact live prerequisites. This is source-verified coverage accounting, with **zero live passes**. The accepted baseline remains unchanged. This run does not include the daily smoke or rotation tiers.
-
-- Repository: `OpenHands/OpenHands`; origin verified as `enyst/playground`, not canonical.
-- BASE: `ed815e141409c7b52991ab8d13c553b595da9165` (2026-10-06); TARGET: `baf1cbef090fce793d3017276c1025c057920a4b`.
-- Complete history, ancestor check valid; 14 commits / 77 changed paths. All 14 resolve through the owning repository's commits/pulls API to merged PRs: 14 documented intents, 0 undocumented, 0 contradictory. Private OHE acceptance criteria for #17988/#17969 remain unavailable; their descriptions document intent.
-- Source scope expands to F01–F27 because #18051's HTTP-error parser feeds the common QueryCache/MutationCache. This is conservative delta widening; it does not claim every happy path changed. All 77 paths, all 8 shared paths and all 4 initially unmapped paths are accounted for in `source-scope.json`; Playwright configuration is non-user-facing harness work.
-
-## Coverage and prerequisites
-
-| Evidence type | Pass | Fail | Blocked | Not-run | Denominator |
-|---|---:|---:|---:|---:|---|
-| Live mapped behavior inventory | 0 | 0 | 736 | 0 | 736 mapped sub-features in 27 families |
-| Live families completed | 0 | 0 | 27 | 0 | 27 affected families |
-| Static map check / coverage / testids / baseline / affected | 5 | 0 | 0 | 0 | 5 commands |
-
-The behavior inventory is a list of required obligations, not an executed entry-point/viewport matrix. **No live entry point, viewport, doctor or backend scenario was exercised.** The complete private inventory records each stable ID, expected behavior, literal family recipe, prerequisites, planned entry points and the launch blocker. No run was allocated, so CLI `evidence add/report` has no valid run; no artificial run metadata or screenshots were created. Viewport and actual selected backend/scenario must be explicit in every evidence entry when live work resumes.
-
-Coordinator normal launch stopped before allocation: `Only 874 MB of memory available; a run needs about 1500 MB.` A reduced-threshold attempt also stopped at 79 MB. Automatic approval review rejected disabling the guard (`--min-free-mb 0`) because a resource-heavy stack could cause severe system-wide memory pressure; the rejected action was not executed or bypassed. An independent fresh default-threshold launch at 07:03 UTC stopped at 117 MB. Live checks require safe memory headroom that passes the normal guard, or explicit approval for the rejected override.
-
-No scheduled `DEEPSEEK_API_KEY` or active project environment/key source was found. Real-model turns, event/tool outcomes and recipes requiring configured DeepSeek credentials are additionally blocked by that key prerequisite. No provider substitution or mocked live proof was used. DeepSeek spend: **USD 0 of USD 10**.
-
-## Changed rows and retained limits
-
-| Index correction | Expected / actual proof | Live result |
-|---|---|---|
-| Enterprise Super Admin setup guide (#17969) | Exact Cloud `/me` permission and genuine setup-state gates agree with source; the new directory is now explicitly excluded from coverage. Positive guide progress, links, collapse/reopen, server removal and desktop/phone states were not driven. | blocked |
-| Suspended Cloud workspace recovery (#17988) | Exact selected-org 403 detail strings and another accessible workspace are documented. Genuine organization/membership suspension, switching and request isolation were not driven. | blocked |
-
-Neither exclusion retires a feature or treats an account gap as a pass. Existing IDs/counts remain 27 families / 736 sub-features; all 999 cited test IDs resolve. Coverage now reports setup-guide as an explicit prerequisite exclusion; this **does not mean it has a proven recipe**.
-
-Issue audit checked 65 owning-repository references: 46 issues (40 open, 6 closed) and 19 PR references. #18094 closed after BASE and requires F05.plus-menu, F07.status-menu and F08.tabs-menu retests. Automation #551 closed before BASE but still has failure wording: F24.encryption needs set/rotate/clear + sync without dirtying an existing exported automation, since the old recipe can mask the fixed behavior. Their known-failure text remains unchanged until live verification. Further source candidates retained without runtime claims: F25's 10s health wording versus Local 30s / Cloud 5m, the DNT/PostHog failure note after #18086, and F27 calling closed #17562 open. Details and exact entry points/prerequisites are in `issue-closures.json` and `intent.md`.
-
-No new defect was independently reproduced, so no new issue or causal regression claim was filed. No product code, schedules or user state changed.
-
-## Environment, review and teardown
-
-macOS; Node 25.9.0, npm 11.12.1, uv/uvx 0.11.19, installed Google Chrome 154.0.8037.98. Locked dependencies installed with `npm ci --ignore-scripts`; npm emitted Node 25 engine warnings for jsdom/vitest. No build or runtime result is inferred from installation. TARGET pins Agent Server 1.53.0 and automation 1.19.0; no backend was started and no ports were allocated. The active configured identity is `smolpaws`, upstream push=false, verified `smolpaws/OpenHands` fork push=true. Commit author is user-authorized enyst; actual committer/signing configuration is preserved.
-
-Independent source review accepted both exclusions and independently reran the static checks. This two-bullet documentation change needs no design diagram. #17568 is closed but retains `ready-for-dev`; its acceptance criteria explicitly own maintained feature maps and honest account gaps, and the current PR-description gate checks the label without requiring an open state. It is referenced as context, not claimed fixed again. No `codex` or `codex-automation` label exists upstream.
-
-All attempted launches stopped before run allocation; coordinator and independent `runs` inventories are empty. There are no owned stack processes, ports, browser sessions, fixtures or conversations to stop. Reviewed artifacts survive under this directory. Raw GitHub source, complete inventory and private notes remain outside GitHub. CI/review status belongs to the PR; this draft must not be merged as a completed delta. **BASE is retained, and no next baseline is proposed.**
diff --git a/.pr/map-maintenance/2026-10-08/source-scope.json b/.pr/map-maintenance/2026-10-08/source-scope.json
deleted file mode 100644
index 249ce6e541..0000000000
--- a/.pr/map-maintenance/2026-10-08/source-scope.json
+++ /dev/null
@@ -1,403 +0,0 @@
-{
- "BASE": "ed815e141409c7b52991ab8d13c553b595da9165",
- "TARGET": "baf1cbef090fce793d3017276c1025c057920a4b",
- "status": "source-only; no stacks launched and no runtime proof claimed",
- "rawAffected": {
- "families": [
- {
- "id": "F01",
- "file": "F01-first-run-and-sign-in.md",
- "paths": [
- "src/routes/root-layout.tsx"
- ]
- },
- {
- "id": "F02",
- "file": "F02-app-shell.md",
- "paths": [
- "src/components/features/sidebar/use-sidebar-onboarding-checklist.ts"
- ]
- },
- {
- "id": "F04",
- "file": "F04-conversation-list.md",
- "paths": [
- "src/components/features/conversation-panel/cloud-new-conversation-menu.tsx"
- ]
- },
- {
- "id": "F05",
- "file": "F05-composer.md",
- "paths": [
- "src/components/features/chat/chat-add-file-button.tsx"
- ]
- },
- {
- "id": "F06",
- "file": "F06-agent-activity.md",
- "paths": [
- "src/components/features/chat/chat-add-file-button.tsx"
- ]
- },
- {
- "id": "F07",
- "file": "F07-conversation-page.md",
- "paths": [
- "src/components/features/conversation-panel/cloud-new-conversation-menu.tsx",
- "src/components/features/conversation/conversation-name-with-status.tsx",
- "src/components/features/conversation/conversation-tabs/conversation-tabs-context-menu.tsx"
- ]
- },
- {
- "id": "F08",
- "file": "F08-workspace-files-and-changes.md",
- "paths": [
- "src/components/features/conversation/conversation-tabs/conversation-tabs-context-menu.tsx"
- ]
- },
- {
- "id": "F25",
- "file": "F25-backends-and-cloud.md",
- "paths": [
- "src/api/cloud/client.ts",
- "src/api/cloud/organization-suspension-store.ts",
- "src/api/cloud/proxy.ts",
- "src/api/cloud/setup-state-service.api.ts",
- "src/api/cloud/types.ts",
- "src/components/features/backends/cloud-organization-boundary.tsx",
- "src/hooks/query/use-backends-health.ts"
- ]
- },
- {
- "id": "F27",
- "file": "F27-workspace-tools.md",
- "paths": [
- "src/components/features/conversation-panel/cloud-new-conversation-menu.tsx"
- ]
- }
- ],
- "shared": [
- "src/hooks/mutation/use-add-mcp-server.ts",
- "src/hooks/query/query-keys.ts",
- "src/hooks/query/use-app-installations.ts",
- "src/hooks/query/use-git-repositories.ts",
- "src/i18n/translation.json",
- "src/services/telemetry.ts",
- "src/utils/api-error-message.ts",
- "src/utils/retrieve-axios-error-message.ts"
- ],
- "unmapped": [
- "playwright.live.config.ts",
- "src/components/features/setup-guide/super-admin-setup-guide.constants.ts",
- "src/components/features/setup-guide/super-admin-setup-guide.tsx",
- "src/components/features/setup-guide/use-super-admin-setup-guide.ts"
- ],
- "nonUserFacing": [
- ".agents/skills/e2e-testing/references/guide.md",
- ".agents/skills/verify-openhands/SKILL.md",
- ".agents/skills/verify-openhands/references/adaptation.md",
- ".agents/skills/verify-openhands/references/daily.md",
- ".agents/skills/verify-openhands/references/feature-map/F01-first-run-and-sign-in.md",
- ".agents/skills/verify-openhands/references/feature-map/F02-app-shell.md",
- ".agents/skills/verify-openhands/references/feature-map/F03-home.md",
- ".agents/skills/verify-openhands/references/feature-map/F05-composer.md",
- ".agents/skills/verify-openhands/references/feature-map/F06-agent-activity.md",
- ".agents/skills/verify-openhands/references/feature-map/F07-conversation-page.md",
- ".agents/skills/verify-openhands/references/feature-map/F08-workspace-files-and-changes.md",
- ".agents/skills/verify-openhands/references/feature-map/F09-settings-shell.md",
- ".agents/skills/verify-openhands/references/feature-map/F10-llm-profiles.md",
- ".agents/skills/verify-openhands/references/feature-map/F17-mcp-servers.md",
- ".agents/skills/verify-openhands/references/feature-map/F18-skills.md",
- ".agents/skills/verify-openhands/references/feature-map/F19-plugins.md",
- ".agents/skills/verify-openhands/references/feature-map/F20-canvas-apps.md",
- ".agents/skills/verify-openhands/references/feature-map/F23-automation-detail.md",
- ".agents/skills/verify-openhands/references/feature-map/F24-git-sync.md",
- ".agents/skills/verify-openhands/references/feature-map/F25-backends-and-cloud.md",
- ".agents/skills/verify-openhands/references/feature-map/F26-runtime-variants.md",
- ".agents/skills/verify-openhands/references/feature-map/F27-workspace-tools.md",
- ".agents/skills/verify-openhands/references/feature-map/README.md",
- ".agents/skills/verify-openhands/references/maintenance.md",
- ".agents/skills/verify-openhands/references/mapping.md",
- ".agents/skills/verify-openhands/scripts/browser-daemon.mjs",
- ".agents/skills/verify-openhands/scripts/control-openhands.mjs",
- ".agents/skills/verify-openhands/scripts/control-openhands.test.mjs",
- ".agents/skills/verify-openhands/scripts/lib/baseline.mjs",
- ".agents/skills/verify-openhands/scripts/lib/call-limit.mjs",
- ".agents/skills/verify-openhands/scripts/lib/map-sources.mjs",
- ".agents/skills/verify-openhands/scripts/lib/testids.mjs",
- ".agents/skills/verify-openhands/scripts/lib/tmux-path.mjs",
- "__tests__/api/cloud/proxy.test.ts",
- "__tests__/components/backends/cloud-organization-startup.test.tsx",
- "__tests__/components/chat/chat-add-file-button.test.tsx",
- "__tests__/components/features/conversation-panel/cloud-new-conversation-menu.test.tsx",
- "__tests__/components/features/conversation/conversation-name-with-status.test.tsx",
- "__tests__/components/features/conversation/conversation-tabs-context-menu.test.tsx",
- "__tests__/components/features/setup-guide/super-admin-setup-guide.test.tsx",
- "__tests__/components/features/sidebar/sidebar-onboarding-checklist.test.tsx",
- "__tests__/components/settings/llm-profiles/delete-profile-modal.test.tsx",
- "__tests__/hooks/mutation/use-add-mcp-server.test.ts",
- "__tests__/hooks/query/use-backends-health.test.tsx",
- "__tests__/hooks/query/use-git-repositories.test.ts",
- "__tests__/query-client-config.behavior.test.ts",
- "__tests__/services/telemetry.test.ts",
- "__tests__/utils/retrieve-axios-error-message.test.ts",
- "tests/e2e/live/utils/agent-server-conversation.ts",
- "tests/e2e/mock-llm/automations/mock-llm-preset-automation.spec.ts",
- "tests/e2e/mock-llm/files/mock-llm-files-and-git.spec.ts",
- "tests/e2e/mock-llm/settings/mock-llm-profile-management.spec.ts"
- ]
- },
- "directErrorConsumers": [
- "src/query-client-config.ts",
- "src/routes/app-settings.tsx",
- "src/routes/mcp.tsx",
- "src/hooks/use-skill-enablement.ts",
- "src/utils/custom-toast-handlers.tsx",
- "src/hooks/mutation/use-switch-llm-profile.ts",
- "src/hooks/use-download-conversation.ts",
- "src/hooks/use-compact-context-action.ts",
- "src/hooks/use-responder-url-secret.ts",
- "src/hooks/mutation/use-read-conversation-file.ts",
- "src/hooks/use-save-acp-secrets.ts",
- "src/components/features/conversation/conversation-overview-mcp-panel.tsx",
- "src/components/features/onboarding/steps/choose-agent-step.tsx",
- "src/components/features/settings/agent-profiles/global-tools-notice.tsx",
- "src/components/features/settings/agent-profiles/agent-profiles-local-view.tsx",
- "src/components/features/settings/sdk-settings/sdk-section-page.tsx",
- "src/components/features/mcp-page/mcp-server-health.tsx",
- "src/components/features/mcp-page/install-server-modal.tsx",
- "src/components/features/mcp-page/custom-server-editor.tsx"
- ],
- "directErrorOwners": {
- "families": [
- {
- "id": "F01",
- "file": "F01-first-run-and-sign-in.md",
- "paths": [
- "src/components/features/onboarding/steps/choose-agent-step.tsx"
- ]
- },
- {
- "id": "F02",
- "file": "F02-app-shell.md",
- "paths": [
- "src/utils/custom-toast-handlers.tsx"
- ]
- },
- {
- "id": "F04",
- "file": "F04-conversation-list.md",
- "paths": [
- "src/hooks/use-download-conversation.ts"
- ]
- },
- {
- "id": "F07",
- "file": "F07-conversation-page.md",
- "paths": [
- "src/components/features/conversation/conversation-overview-mcp-panel.tsx"
- ]
- },
- {
- "id": "F10",
- "file": "F10-llm-profiles.md",
- "paths": [
- "src/components/features/settings/sdk-settings/sdk-section-page.tsx"
- ]
- },
- {
- "id": "F13",
- "file": "F13-agent-profiles.md",
- "paths": [
- "src/components/features/settings/agent-profiles/global-tools-notice.tsx",
- "src/components/features/settings/agent-profiles/agent-profiles-local-view.tsx"
- ]
- },
- {
- "id": "F15",
- "file": "F15-agent-behavior-settings.md",
- "paths": [
- "src/components/features/settings/sdk-settings/sdk-section-page.tsx"
- ]
- },
- {
- "id": "F16",
- "file": "F16-application-settings.md",
- "paths": [
- "src/routes/app-settings.tsx"
- ]
- },
- {
- "id": "F17",
- "file": "F17-mcp-servers.md",
- "paths": [
- "src/routes/mcp.tsx",
- "src/components/features/mcp-page/mcp-server-health.tsx",
- "src/components/features/mcp-page/install-server-modal.tsx",
- "src/components/features/mcp-page/custom-server-editor.tsx"
- ]
- },
- {
- "id": "F18",
- "file": "F18-skills.md",
- "paths": [
- "src/hooks/use-skill-enablement.ts"
- ]
- },
- {
- "id": "F22",
- "file": "F22-automation-creation.md",
- "paths": [
- "src/hooks/use-responder-url-secret.ts"
- ]
- },
- {
- "id": "F27",
- "file": "F27-workspace-tools.md",
- "paths": [
- "src/components/features/conversation/conversation-overview-mcp-panel.tsx"
- ]
- }
- ],
- "shared": [
- "src/hooks/mutation/use-switch-llm-profile.ts",
- "src/hooks/use-compact-context-action.ts",
- "src/hooks/mutation/use-read-conversation-file.ts",
- "src/hooks/use-save-acp-secrets.ts"
- ],
- "unmapped": [
- "src/query-client-config.ts"
- ],
- "nonUserFacing": []
- },
- "sharedClassification": {
- "src/hooks/mutation/use-add-mcp-server.ts": {
- "families": [
- "F17",
- "F02"
- ],
- "reason": "MCP add now invalidates enterprise setup-guide server progress; settings invalidation unchanged. Setup-guide integration progress requires real Enterprise first-Super-Admin account."
- },
- "src/hooks/query/query-keys.ts": {
- "families": [
- "F02",
- "F17"
- ],
- "reason": "New SUPER_ADMIN_SETUP_QUERY_KEYS only consumed by guide state query and MCP-add invalidation; no global existing query key changed."
- },
- "src/hooks/query/use-app-installations.ts": {
- "families": [
- "F03",
- "F04"
- ],
- "reason": "New enabled option propagated from useGitRepositories; home repo dropdown and Cloud sidebar new-conversation repo picker are two concrete consumers."
- },
- "src/hooks/query/use-git-repositories.ts": {
- "families": [
- "F03",
- "F04"
- ],
- "reason": "Forwards enabled to provider installations query; no other non-test useGitRepositories callers."
- },
- "src/i18n/translation.json": {
- "families": [
- "F02",
- "F25"
- ],
- "reason": "Only added Setup guide and suspension/workspace-switch strings; no existing keys/locale logic changed."
- },
- "src/services/telemetry.ts": {
- "families": [
- "F01",
- "F16",
- "F26"
- ],
- "reason": "isDoNotTrackEnabled now prevents PostHog initialization for every DNT path; consent entry F01, analytics entry F16, embedded configureTelemetry(false) and launcher/runtime opt-out F26. No conversation/automation-specific tracked payload changed."
- },
- "src/utils/api-error-message.ts": {
- "families": [
- "F02",
- "F05",
- "F19",
- "F20"
- ],
- "reason": "Removes recursive dependency: connection-error branch calls getUserFacingConnectionErrorMessage directly. Explicit consumer model switch (F05), displayApiErrorToast for plugin mutations F19 and app mutation F20. Global toast owner F02."
- },
- "src/utils/retrieve-axios-error-message.ts": {
- "families": [
- "F01",
- "F02",
- "F04",
- "F07",
- "F10",
- "F13",
- "F15",
- "F16",
- "F17",
- "F18",
- "F22",
- "F27"
- ],
- "reason": "New SDK HttpError parsed body extraction affects explicit inline errors plus generic unsuppressed QueryCache/MutationCache handlers. See error-scope markdown for broader potential families."
- }
- },
- "unmappedClassification": {
- "playwright.live.config.ts": {
- "classification": "non-user-facing",
- "reason": "E2E runner configuration; not product source or launched user surface."
- },
- "src/components/features/setup-guide/super-admin-setup-guide.constants.ts": {
- "classification": "new surface/map gap",
- "proposedOwner": "F02",
- "reason": "Enterprise floating shell setup guide destinations and required/optional step definitions."
- },
- "src/components/features/setup-guide/super-admin-setup-guide.tsx": {
- "classification": "new surface/map gap",
- "proposedOwner": "F02",
- "reason": "New floating panel, progress, step links, Start, minimize/reopen and enterprise setup-page link."
- },
- "src/components/features/setup-guide/use-super-admin-setup-guide.ts": {
- "classification": "new surface/map gap",
- "proposedOwner": "F02",
- "reason": "Cloud selected org membership permission, enterprise server-derived guide state and progress; suppresses old sidebar checklist while guide visible/loading."
- }
- },
- "conservativeDeltaFamilies": [
- "F01",
- "F02",
- "F03",
- "F04",
- "F05",
- "F06",
- "F07",
- "F08",
- "F09",
- "F10",
- "F11",
- "F12",
- "F13",
- "F14",
- "F15",
- "F16",
- "F17",
- "F18",
- "F19",
- "F20",
- "F21",
- "F22",
- "F23",
- "F24",
- "F25",
- "F26",
- "F27"
- ],
- "conservativeDeltaReason": "Generic unsuppressed QueryCache/MutationCache errors call the changed helper under common UI provider; library export also covers F26 embedded boundary. This widens DELTA to shared error surfaces across all 27 families; it is not smoke/rotation or proof every happy behavior changed.",
- "conservativeDeltaCitations": [
- "src/query-client-config.ts:52",
- "src/query-client-config.ts:77",
- "src/components/providers/agent-server-ui-providers.tsx:76",
- "src/components/providers/agent-server-ui-providers.tsx:140",
- "src/lib/index.ts:18"
- ],
- "readmeReview": "Prepared Not mapped bullet gates are accurate. Prefer collapse/reopen, server-driven dismissal and progress persistence over unqualified dismissal/reload persistence: panel X only sets local open false; server guide dismissal is external, initial panel open true after mount."
-}
diff --git a/.pr/map-maintenance/2026-10-08/static-checks.json b/.pr/map-maintenance/2026-10-08/static-checks.json
deleted file mode 100644
index ce85f38939..0000000000
--- a/.pr/map-maintenance/2026-10-08/static-checks.json
+++ /dev/null
@@ -1,209 +0,0 @@
-{
- "check": {
- "exit_code": 0,
- "output": {
- "ok": true,
- "files": 27,
- "ids": 736,
- "checked": "all",
- "problems": []
- }
- },
- "coverage": {
- "exit_code": 0,
- "output": {
- "ok": true,
- "routes": {
- "total": 30,
- "unmapped": [],
- "excluded": [],
- "fileOnly": []
- },
- "featureComponentDirs": {
- "total": 29,
- "unmapped": [],
- "excluded": [
- "src/components/features/context-menu",
- "src/components/features/setup-guide"
- ]
- }
- }
- },
- "testids": {
- "exit_code": 0,
- "output": {
- "ok": true,
- "cited": 999,
- "unresolved": [],
- "note": "every cited test id is accounted for in src/"
- }
- },
- "baseline": {
- "exit_code": 0,
- "output": {
- "ok": true,
- "baseline": {
- "sha": "ed815e141409c7b52991ab8d13c553b595da9165",
- "date": "2026-10-06",
- "known": true,
- "ancestorOfHead": true,
- "commitsSince": 14
- }
- }
- },
- "affected": {
- "exit_code": 0,
- "output": {
- "ok": true,
- "range": {
- "base": "ed815e141409c7b52991ab8d13c553b595da9165",
- "target": "baf1cbef090fce793d3017276c1025c057920a4b",
- "baseSource": "map index baseline"
- },
- "changed": 77,
- "families": [
- {
- "id": "F01",
- "file": "F01-first-run-and-sign-in.md",
- "paths": [
- "src/routes/root-layout.tsx"
- ]
- },
- {
- "id": "F02",
- "file": "F02-app-shell.md",
- "paths": [
- "src/components/features/sidebar/use-sidebar-onboarding-checklist.ts"
- ]
- },
- {
- "id": "F04",
- "file": "F04-conversation-list.md",
- "paths": [
- "src/components/features/conversation-panel/cloud-new-conversation-menu.tsx"
- ]
- },
- {
- "id": "F05",
- "file": "F05-composer.md",
- "paths": [
- "src/components/features/chat/chat-add-file-button.tsx"
- ]
- },
- {
- "id": "F06",
- "file": "F06-agent-activity.md",
- "paths": [
- "src/components/features/chat/chat-add-file-button.tsx"
- ]
- },
- {
- "id": "F07",
- "file": "F07-conversation-page.md",
- "paths": [
- "src/components/features/conversation-panel/cloud-new-conversation-menu.tsx",
- "src/components/features/conversation/conversation-name-with-status.tsx",
- "src/components/features/conversation/conversation-tabs/conversation-tabs-context-menu.tsx"
- ]
- },
- {
- "id": "F08",
- "file": "F08-workspace-files-and-changes.md",
- "paths": [
- "src/components/features/conversation/conversation-tabs/conversation-tabs-context-menu.tsx"
- ]
- },
- {
- "id": "F25",
- "file": "F25-backends-and-cloud.md",
- "paths": [
- "src/api/cloud/client.ts",
- "src/api/cloud/organization-suspension-store.ts",
- "src/api/cloud/proxy.ts",
- "src/api/cloud/setup-state-service.api.ts",
- "src/api/cloud/types.ts",
- "src/components/features/backends/cloud-organization-boundary.tsx",
- "src/hooks/query/use-backends-health.ts"
- ]
- },
- {
- "id": "F27",
- "file": "F27-workspace-tools.md",
- "paths": [
- "src/components/features/conversation-panel/cloud-new-conversation-menu.tsx"
- ]
- }
- ],
- "shared": [
- "src/hooks/mutation/use-add-mcp-server.ts",
- "src/hooks/query/query-keys.ts",
- "src/hooks/query/use-app-installations.ts",
- "src/hooks/query/use-git-repositories.ts",
- "src/i18n/translation.json",
- "src/services/telemetry.ts",
- "src/utils/api-error-message.ts",
- "src/utils/retrieve-axios-error-message.ts"
- ],
- "unmapped": [
- "playwright.live.config.ts",
- "src/components/features/setup-guide/super-admin-setup-guide.constants.ts",
- "src/components/features/setup-guide/super-admin-setup-guide.tsx",
- "src/components/features/setup-guide/use-super-admin-setup-guide.ts"
- ],
- "nonUserFacing": [
- ".agents/skills/e2e-testing/references/guide.md",
- ".agents/skills/verify-openhands/SKILL.md",
- ".agents/skills/verify-openhands/references/adaptation.md",
- ".agents/skills/verify-openhands/references/daily.md",
- ".agents/skills/verify-openhands/references/feature-map/F01-first-run-and-sign-in.md",
- ".agents/skills/verify-openhands/references/feature-map/F02-app-shell.md",
- ".agents/skills/verify-openhands/references/feature-map/F03-home.md",
- ".agents/skills/verify-openhands/references/feature-map/F05-composer.md",
- ".agents/skills/verify-openhands/references/feature-map/F06-agent-activity.md",
- ".agents/skills/verify-openhands/references/feature-map/F07-conversation-page.md",
- ".agents/skills/verify-openhands/references/feature-map/F08-workspace-files-and-changes.md",
- ".agents/skills/verify-openhands/references/feature-map/F09-settings-shell.md",
- ".agents/skills/verify-openhands/references/feature-map/F10-llm-profiles.md",
- ".agents/skills/verify-openhands/references/feature-map/F17-mcp-servers.md",
- ".agents/skills/verify-openhands/references/feature-map/F18-skills.md",
- ".agents/skills/verify-openhands/references/feature-map/F19-plugins.md",
- ".agents/skills/verify-openhands/references/feature-map/F20-canvas-apps.md",
- ".agents/skills/verify-openhands/references/feature-map/F23-automation-detail.md",
- ".agents/skills/verify-openhands/references/feature-map/F24-git-sync.md",
- ".agents/skills/verify-openhands/references/feature-map/F25-backends-and-cloud.md",
- ".agents/skills/verify-openhands/references/feature-map/F26-runtime-variants.md",
- ".agents/skills/verify-openhands/references/feature-map/F27-workspace-tools.md",
- ".agents/skills/verify-openhands/references/feature-map/README.md",
- ".agents/skills/verify-openhands/references/maintenance.md",
- ".agents/skills/verify-openhands/references/mapping.md",
- ".agents/skills/verify-openhands/scripts/browser-daemon.mjs",
- ".agents/skills/verify-openhands/scripts/control-openhands.mjs",
- ".agents/skills/verify-openhands/scripts/control-openhands.test.mjs",
- ".agents/skills/verify-openhands/scripts/lib/baseline.mjs",
- ".agents/skills/verify-openhands/scripts/lib/call-limit.mjs",
- ".agents/skills/verify-openhands/scripts/lib/map-sources.mjs",
- ".agents/skills/verify-openhands/scripts/lib/testids.mjs",
- ".agents/skills/verify-openhands/scripts/lib/tmux-path.mjs",
- "__tests__/api/cloud/proxy.test.ts",
- "__tests__/components/backends/cloud-organization-startup.test.tsx",
- "__tests__/components/chat/chat-add-file-button.test.tsx",
- "__tests__/components/features/conversation-panel/cloud-new-conversation-menu.test.tsx",
- "__tests__/components/features/conversation/conversation-name-with-status.test.tsx",
- "__tests__/components/features/conversation/conversation-tabs-context-menu.test.tsx",
- "__tests__/components/features/setup-guide/super-admin-setup-guide.test.tsx",
- "__tests__/components/features/sidebar/sidebar-onboarding-checklist.test.tsx",
- "__tests__/components/settings/llm-profiles/delete-profile-modal.test.tsx",
- "__tests__/hooks/mutation/use-add-mcp-server.test.ts",
- "__tests__/hooks/query/use-backends-health.test.tsx",
- "__tests__/hooks/query/use-git-repositories.test.ts",
- "__tests__/query-client-config.behavior.test.ts",
- "__tests__/services/telemetry.test.ts",
- "__tests__/utils/retrieve-axios-error-message.test.ts",
- "tests/e2e/live/utils/agent-server-conversation.ts",
- "tests/e2e/mock-llm/automations/mock-llm-preset-automation.spec.ts",
- "tests/e2e/mock-llm/files/mock-llm-files-and-git.spec.ts",
- "tests/e2e/mock-llm/settings/mock-llm-profile-management.spec.ts"
- ]
- }
- }
-}
diff --git a/__tests__/components/features/setup-guide/setup-guide-tour.test.ts b/__tests__/components/features/setup-guide/setup-guide-tour.test.ts
new file mode 100644
index 0000000000..b0161be497
--- /dev/null
+++ b/__tests__/components/features/setup-guide/setup-guide-tour.test.ts
@@ -0,0 +1,62 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import {
+ SUPER_ADMIN_SETUP_STEPS,
+ type SuperAdminSetupStepId,
+} from "#/components/features/setup-guide/super-admin-setup-guide.constants";
+import {
+ hasSetupGuideTour,
+ startSetupGuideTour,
+} from "#/components/features/setup-guide/tour/setup-guide-tour";
+import { startGuidedTour } from "#/components/features/setup-guide/tour/tour-engine";
+
+vi.mock("#/components/features/setup-guide/tour/tour-engine", () => ({
+ startGuidedTour: vi.fn(),
+}));
+
+const t = (key: string) => `t:${key}`;
+const NAV = { navigate: vi.fn(), getPath: () => "/" };
+
+describe("setup guide tours", () => {
+ beforeEach(() => {
+ vi.mocked(startGuidedTour).mockReset();
+ });
+
+ it("has a tour for each step done in Canvas, and only those", () => {
+ expect(
+ SUPER_ADMIN_SETUP_STEPS.filter(({ id }) => hasSetupGuideTour(id)).map(
+ ({ id }) => id,
+ ),
+ ).toEqual(["first-automation", "add-integration"]);
+ });
+
+ it.each<[SuperAdminSetupStepId, string]>([
+ ["first-automation", "/automations/templates"],
+ ["add-integration", "/mcp"],
+ ])(
+ "starts the %s tour on the step's page and waits for the step",
+ async (stepId, route) => {
+ await startSetupGuideTour(stepId, NAV, t);
+
+ expect(startGuidedTour).toHaveBeenCalledTimes(1);
+ const [tour, nav, labels] = vi.mocked(startGuidedTour).mock.calls[0];
+ expect(nav).toBe(NAV);
+ expect(tour.stops.map((stop) => stop.route)).toEqual([route, undefined]);
+ expect(tour.stops.at(-1)?.waitForComplete).toBe(stepId);
+ for (const stop of tour.stops) {
+ expect(stop.title).toMatch(/^t:ONBOARDING\$SETUP_GUIDE_TOUR_/);
+ expect(stop.body).toMatch(/^t:ONBOARDING\$SETUP_GUIDE_TOUR_/);
+ }
+ expect(labels).toEqual({
+ next: "t:ONBOARDING$NEXT",
+ previous: "t:ONBOARDING$BACK",
+ done: "t:ONBOARDING$SETUP_GUIDE_TOUR_DONE",
+ });
+ },
+ );
+
+ it("starts nothing for a step done in the enterprise app", async () => {
+ await startSetupGuideTour("invite-users", NAV, t);
+
+ expect(startGuidedTour).not.toHaveBeenCalled();
+ });
+});
diff --git a/__tests__/components/features/setup-guide/super-admin-setup-guide.test.tsx b/__tests__/components/features/setup-guide/super-admin-setup-guide.test.tsx
index 7176dc3c90..2ae2cf0a0f 100644
--- a/__tests__/components/features/setup-guide/super-admin-setup-guide.test.tsx
+++ b/__tests__/components/features/setup-guide/super-admin-setup-guide.test.tsx
@@ -1,5 +1,5 @@
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-import { render, screen, waitFor } from "@testing-library/react";
+import { act, render, screen, waitFor } from "@testing-library/react";
import userEvent from "@testing-library/user-event";
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { http, HttpResponse } from "msw";
@@ -11,13 +11,44 @@ import {
import type { Backend } from "#/api/backend-registry/types";
import type { CloudSetupGuideSteps } from "#/api/cloud/types";
import SuperAdminSetupGuide from "#/components/features/setup-guide/super-admin-setup-guide";
+import type { SuperAdminSetupStepId } from "#/components/features/setup-guide/super-admin-setup-guide.constants";
+import { notifySuperAdminSetupStep } from "#/components/features/setup-guide/super-admin-setup-step-event";
+import { startSetupGuideTour } from "#/components/features/setup-guide/tour/setup-guide-tour";
import { NavigationProvider } from "#/context/navigation-context";
import { ActiveBackendProvider } from "#/contexts/active-backend-context";
import { I18nKey } from "#/i18n/declaration";
import { server } from "#/mocks/node";
+const locked = vi.hoisted(() => ({ cloudHost: null as string | null }));
+const tour = vi.hoisted(() => ({ active: false }));
+
+// Canvas served from the cloud host opens enterprise pages in its own tab.
+vi.mock("#/api/agent-server-config", async (importOriginal) => ({
+ ...(await importOriginal<typeof import("#/api/agent-server-config")>()),
+ getLockedCloudHost: () => locked.cloudHost,
+}));
+
+// The spotlight needs a real layout; these tests check which tour starts.
+vi.mock(
+ "#/components/features/setup-guide/tour/setup-guide-tour",
+ async (importOriginal) => ({
+ ...(await importOriginal<
+ typeof import("#/components/features/setup-guide/tour/setup-guide-tour")
+ >()),
+ startSetupGuideTour: vi.fn(),
+ }),
+);
+
+vi.mock("#/components/features/setup-guide/tour/tour-engine", () => ({
+ startGuidedTour: vi.fn(),
+ isGuidedTourActive: () => tour.active,
+ subscribeGuidedTourActive: () => () => {},
+}));
+
const CLOUD_HOST = "https://ohe.example.com";
const GUIDE_ORG_ID = "org-1";
+/** The invite step on the guide's organization, asking for its tour. */
+const INVITE_TOUR_URL = `${CLOUD_HOST}/settings/org-members?org=${GUIDE_ORG_ID}&setup_tour=invite-users`;
const cloudBackend: Backend = {
id: "cloud-1",
@@ -89,6 +120,7 @@ function renderGuide(currentPath = "/conversations") {
const queryClient = new QueryClient({
defaultOptions: { queries: { retry: false } },
});
+ const navigate = vi.fn();
const ui = (path: string) => (
<QueryClientProvider client={queryClient}>
<ActiveBackendProvider>
@@ -97,7 +129,7 @@ function renderGuide(currentPath = "/conversations") {
currentPath: path,
conversationId: null,
isNavigating: false,
- navigate: vi.fn(),
+ navigate,
}}
>
<SuperAdminSetupGuide />
@@ -106,7 +138,7 @@ function renderGuide(currentPath = "/conversations") {
</QueryClientProvider>
);
const view = render(ui(currentPath));
- return { navigateTo: (path: string) => view.rerender(ui(path)) };
+ return { navigate, navigateTo: (path: string) => view.rerender(ui(path)) };
}
async function expectNoGuide() {
@@ -121,10 +153,15 @@ describe("SuperAdminSetupGuide", () => {
beforeEach(() => {
localStorage.clear();
__resetActiveStoreForTests();
+ locked.cloudHost = null;
+ tour.active = false;
+ vi.mocked(startSetupGuideTour).mockReset();
});
afterEach(() => {
__resetActiveStoreForTests();
+ vi.unstubAllGlobals();
+ window.history.replaceState(null, "", "/");
});
it("shows the first Super Admin the progress the server reports", async () => {
@@ -206,7 +243,7 @@ describe("SuperAdminSetupGuide", () => {
).toHaveAttribute("href", "/mcp");
});
- it("opens an enterprise step from Start on the guide's organization", async () => {
+ it("opens an enterprise step from Start on the guide's organization, with its tour", async () => {
activateBackend(cloudBackend);
serveSetupGuide({
setupState: () =>
@@ -219,10 +256,92 @@ describe("SuperAdminSetupGuide", () => {
expect(
await screen.findByTestId("super-admin-setup-guide-start"),
- ).toHaveAttribute(
- "href",
- `${CLOUD_HOST}/settings/org-members?org=${GUIDE_ORG_ID}`,
- );
+ ).toHaveAttribute("href", INVITE_TOUR_URL);
+ });
+
+ describe("when the guide's next step is done", () => {
+ it("opens the Canvas MCP page with its tour after an automation is created", async () => {
+ activateBackend(cloudBackend);
+ let state = guideState({ org_llm: true });
+ serveSetupGuide({ setupState: () => HttpResponse.json(state) });
+ const { navigate } = renderGuide("/automations/new/widget");
+ expect(await screen.findByText("1/4")).toBeInTheDocument();
+
+ state = guideState({ org_llm: true, automation: true });
+ act(() => notifySuperAdminSetupStep("first-automation"));
+
+ // The tour opens the page itself.
+ await waitFor(() =>
+ expect(startSetupGuideTour).toHaveBeenCalledWith(
+ "add-integration",
+ expect.objectContaining({ navigate }),
+ expect.any(Function),
+ ),
+ );
+ expect(navigate).not.toHaveBeenCalled();
+ });
+
+ it("opens the enterprise invite page with its tour when Canvas is served from the cloud host", async () => {
+ locked.cloudHost = CLOUD_HOST;
+ const assign = vi.fn();
+ vi.stubGlobal("location", { ...window.location, assign });
+ activateBackend(cloudBackend);
+ let state = guideState({ org_llm: true, automation: true });
+ serveSetupGuide({ setupState: () => HttpResponse.json(state) });
+ renderGuide("/mcp");
+ expect(await screen.findByText("2/4")).toBeInTheDocument();
+
+ state = guideState({ org_llm: true, automation: true, mcp_server: true });
+ act(() => notifySuperAdminSetupStep("add-integration"));
+
+ await waitFor(() => expect(assign).toHaveBeenCalledWith(INVITE_TOUR_URL));
+ });
+
+ it("points at Start instead of opening the enterprise page in a new tab", async () => {
+ const assign = vi.fn();
+ vi.stubGlobal("location", { ...window.location, assign });
+ const user = userEvent.setup();
+ activateBackend(cloudBackend);
+ let state = guideState({ org_llm: true, automation: true });
+ serveSetupGuide({ setupState: () => HttpResponse.json(state) });
+ renderGuide("/mcp");
+ expect(await screen.findByText("2/4")).toBeInTheDocument();
+ await user.click(
+ screen.getByRole("button", { name: I18nKey.BUTTON$CLOSE }),
+ );
+
+ state = guideState({ org_llm: true, automation: true, mcp_server: true });
+ act(() => notifySuperAdminSetupStep("add-integration"));
+
+ expect(
+ await screen.findByTestId("super-admin-setup-guide-start"),
+ ).toHaveAttribute("href", INVITE_TOUR_URL);
+ expect(assign).not.toHaveBeenCalled();
+ });
+ });
+
+ it.each<[string, Partial<CloudSetupGuideSteps>, SuperAdminSetupStepId]>([
+ ["a step finished out of order", { mcp_server: true }, "add-integration"],
+ ["a step the server does not report done", {}, "first-automation"],
+ ])("opens nothing after %s", async (_case, after, completed) => {
+ const assign = vi.fn();
+ vi.stubGlobal("location", { ...window.location, assign });
+ activateBackend(cloudBackend);
+ let state = guideState({ org_llm: true });
+ const requests = serveSetupGuide({
+ setupState: () => HttpResponse.json(state),
+ });
+ const { navigate } = renderGuide("/automations/templates");
+ expect(await screen.findByText("1/4")).toBeInTheDocument();
+ const before = requests.setupState;
+
+ state = guideState({ org_llm: true, ...after });
+ act(() => notifySuperAdminSetupStep(completed));
+
+ await waitFor(() => expect(requests.setupState).toBeGreaterThan(before));
+ await act(async () => {});
+ expect(navigate).not.toHaveBeenCalled();
+ expect(assign).not.toHaveBeenCalled();
});
it("closes the panel from Start, even on the next step's own page", async () => {
@@ -245,6 +364,77 @@ describe("SuperAdminSetupGuide", () => {
).toHaveAttribute("aria-expanded", "false");
});
+ it("starts a Canvas step's tour from Start, which opens the page itself", async () => {
+ activateBackend(cloudBackend);
+ serveSetupGuide({
+ setupState: () => HttpResponse.json(guideState({ org_llm: true })),
+ });
+ const user = userEvent.setup();
+ const { navigate } = renderGuide();
+
+ await user.click(
+ await screen.findByTestId("super-admin-setup-guide-start"),
+ );
+
+ expect(startSetupGuideTour).toHaveBeenCalledWith(
+ "first-automation",
+ expect.objectContaining({ navigate }),
+ expect.any(Function),
+ );
+ expect(navigate).not.toHaveBeenCalled();
+ expect(
+ screen.getByTestId("super-admin-setup-guide-toggle"),
+ ).toHaveAttribute("aria-expanded", "false");
+ });
+
+ it("starts the tour a page opened from the enterprise guide asks for, once", async () => {
+ window.history.replaceState(
+ null,
+ "",
+ "/mcp?org=org-1&setup_tour=add-integration",
+ );
+ activateBackend(cloudBackend);
+ serveSetupGuide({
+ setupState: () =>
+ HttpResponse.json(guideState({ org_llm: true, automation: true })),
+ });
+
+ renderGuide("/mcp");
+
+ await waitFor(() =>
+ expect(startSetupGuideTour).toHaveBeenCalledWith(
+ "add-integration",
+ expect.anything(),
+ expect.any(Function),
+ ),
+ );
+ expect(startSetupGuideTour).toHaveBeenCalledTimes(1);
+ expect(window.location.search).toBe("?org=org-1");
+ });
+
+ it("ignores a tour request for a step done in the enterprise app", async () => {
+ window.history.replaceState(null, "", "/mcp?setup_tour=invite-users");
+ activateBackend(cloudBackend);
+ serveSetupGuide();
+
+ renderGuide("/mcp");
+
+ await screen.findByTestId("super-admin-setup-guide-panel");
+ await waitFor(() => expect(window.location.search).toBe(""));
+ expect(startSetupGuideTour).not.toHaveBeenCalled();
+ });
+
+ it("stays out of the way while a tour is open", async () => {
+ tour.active = true;
+ activateBackend(cloudBackend);
+ const requests = serveSetupGuide();
+
+ renderGuide();
+
+ await waitFor(() => expect(requests.setupState).toBeGreaterThan(0));
+ await expectNoGuide();
+ });
+
it("re-reads progress when the admin moves to another page", async () => {
activateBackend(cloudBackend);
let state = guideState({ org_llm: true });
diff --git a/__tests__/components/features/setup-guide/tour-engine.test.ts b/__tests__/components/features/setup-guide/tour-engine.test.ts
new file mode 100644
index 0000000000..e247610746
--- /dev/null
+++ b/__tests__/components/features/setup-guide/tour-engine.test.ts
@@ -0,0 +1,165 @@
+import { waitFor } from "@testing-library/react";
+import type { Config } from "driver.js";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { notifySuperAdminSetupStep } from "#/components/features/setup-guide/super-admin-setup-step-event";
+import {
+ isGuidedTourActive,
+ startGuidedTour,
+ stopGuidedTour,
+} from "#/components/features/setup-guide/tour/tour-engine";
+import type {
+ GuidedTour,
+ GuidedTourStop,
+} from "#/components/features/setup-guide/tour/tour-types";
+
+const { drivers } = vi.hoisted(() => ({
+ drivers: [] as {
+ destroy: ReturnType<typeof vi.fn>;
+ moveTo: ReturnType<typeof vi.fn>;
+ }[],
+}));
+
+// Like driver.js, destroying a tour runs its onDestroyed hook.
+vi.mock("driver.js", () => ({
+ driver: (config: Config) => {
+ const instance = {
+ drive: vi.fn(),
+ refresh: vi.fn(),
+ moveTo: vi.fn(),
+ moveNext: vi.fn(),
+ movePrevious: vi.fn(),
+ destroy: vi.fn(() => config.onDestroyed?.(undefined, {}, {} as never)),
+ };
+ drivers.push(instance);
+ return instance;
+ },
+}));
+
+const LABELS = { next: "Next", previous: "Back", done: "Done" };
+const NAV = { navigate: vi.fn(), getPath: () => "/" };
+
+function stop(overrides: Partial<GuidedTourStop>): GuidedTourStop {
+ return {
+ id: "stop",
+ anchor: "#anchor",
+ title: "Title",
+ body: "Body",
+ ...overrides,
+ };
+}
+
+function tour(...stops: GuidedTourStop[]): GuidedTour {
+ return { id: "tour", stops };
+}
+
+const wait = (ms: number) =>
+ new Promise((resolve) => {
+ setTimeout(resolve, ms);
+ });
+
+describe("startGuidedTour", () => {
+ beforeEach(() => {
+ document.body.innerHTML = `
+ <section id="anchor">
+ <button id="card" type="button">Template</button>
+ <input id="search" />
+ </section>
+ <form id="form"></form>`;
+ Element.prototype.scrollIntoView = vi.fn();
+ drivers.length = 0;
+ });
+
+ afterEach(() => {
+ stopGuidedTour();
+ document.body.innerHTML = "";
+ });
+
+ it("ends the tour when the step its last stop waits for succeeds", async () => {
+ // Arrange
+ await startGuidedTour(
+ tour(stop({ waitForComplete: "add-integration" })),
+ NAV,
+ LABELS,
+ );
+ await wait(60); // the stop starts waiting once it is shown
+
+ // Act
+ notifySuperAdminSetupStep("add-integration");
+
+ // Assert
+ await waitFor(() => expect(isGuidedTourActive()).toBe(false));
+ expect(drivers[0].destroy).toHaveBeenCalledTimes(1);
+ });
+
+ it("does not let a replaced tour act on the tour that replaced it", async () => {
+ // Arrange: the first tour's stop is done, so it is about to end itself.
+ await startGuidedTour(
+ tour(stop({ waitForComplete: "first-automation" })),
+ NAV,
+ LABELS,
+ );
+ await wait(60);
+ notifySuperAdminSetupStep("first-automation");
+
+ // Act: the next step's tour starts before that happens.
+ await startGuidedTour(tour(stop({ id: "next" })), NAV, LABELS);
+ await wait(150);
+
+ // Assert
+ expect(isGuidedTourActive()).toBe(true);
+ expect(drivers[0].destroy).toHaveBeenCalledTimes(1);
+ expect(drivers[1].destroy).not.toHaveBeenCalled();
+ });
+
+ it("moves on when a matching element in the anchor is clicked, not on other clicks", async () => {
+ // Arrange
+ await startGuidedTour(
+ tour(
+ stop({ id: "pick", advanceOnClick: "#card" }),
+ stop({ id: "form", anchor: "#form" }),
+ ),
+ NAV,
+ LABELS,
+ );
+ await wait(60);
+
+ // Act
+ document.getElementById("search")!.click();
+ await wait(350);
+ const afterOtherClick = drivers[0].moveTo.mock.calls.length;
+ document.getElementById("card")!.click();
+
+ // Assert
+ expect(afterOtherClick).toBe(0);
+ await waitFor(() => expect(drivers[0].moveTo).toHaveBeenCalledWith(1));
+ });
+
+ it("keeps the page usable while an interactive stop is shown", async () => {
+ // Act
+ await startGuidedTour(
+ tour(stop({ anchor: "#form", interactive: true })),
+ NAV,
+ LABELS,
+ );
+
+ // Assert
+ expect(document.body).toHaveClass("oh-setup-tour-interactive");
+ stopGuidedTour();
+ expect(document.body).not.toHaveClass("oh-setup-tour-interactive");
+ });
+
+ it("opens the first stop's route when the admin is elsewhere", async () => {
+ // Arrange
+ const navigate = vi.fn();
+
+ // Act
+ await startGuidedTour(
+ tour(stop({ route: "/mcp" })),
+ { navigate, getPath: () => "/conversations" },
+ LABELS,
+ );
+
+ // Assert
+ expect(navigate).toHaveBeenCalledWith("/mcp");
+ });
+});
diff --git a/__tests__/components/manifest/manifest-setup-dialog.test.tsx b/__tests__/components/manifest/manifest-setup-dialog.test.tsx
index 774980f131..11bd4d5643 100644
--- a/__tests__/components/manifest/manifest-setup-dialog.test.tsx
+++ b/__tests__/components/manifest/manifest-setup-dialog.test.tsx
@@ -5,6 +5,7 @@ import userEvent from "@testing-library/user-event";
import { beforeEach, describe, expect, it, vi } from "vitest";
import AutomationService from "#/api/automation-service/automation-service.api";
import { SetupDialog } from "#/components/features/manifest/manifest-setup-dialog";
+import { SUPER_ADMIN_SETUP_STEP_EVENT } from "#/components/features/setup-guide/super-admin-setup-step-event";
import type { SetupPrerequisitesResult } from "#/hooks/query/use-manifest-prerequisites";
import type { DeploymentCapabilities, SetupEntry } from "#/manifests/types";
import {
@@ -447,6 +448,54 @@ describe("SetupDialog", () => {
});
});
+ it("tells the Super Admin setup guide when it creates an automation", async () => {
+ // Arrange
+ const onSetupStep = vi.fn();
+ window.addEventListener(SUPER_ADMIN_SETUP_STEP_EVENT, onSetupStep);
+ mocks.runAction.mockResolvedValue({ response: { id: "automation-1" } });
+ const { user } = renderDialog();
+ await fillForm(user);
+
+ // Act
+ await user.click(screen.getByTestId("setup-continue-button"));
+ await waitFor(() =>
+ expect(screen.getByTestId("setup-review")).toBeInTheDocument(),
+ );
+ await user.click(screen.getByTestId("setup-continue-button"));
+
+ // Assert
+ await waitFor(() => expect(onSetupStep).toHaveBeenCalledTimes(1));
+ expect((onSetupStep.mock.calls[0][0] as CustomEvent).detail).toEqual({
+ id: "first-automation",
+ });
+ window.removeEventListener(SUPER_ADMIN_SETUP_STEP_EVENT, onSetupStep);
+ });
+
+ it("does not report an automation that a conversation will create", async () => {
+ // Arrange
+ const onSetupStep = vi.fn();
+ window.addEventListener(SUPER_ADMIN_SETUP_STEP_EVENT, onSetupStep);
+ mocks.capabilities.mockReturnValue(UNSUPPORTED);
+ mocks.runAction.mockResolvedValue({
+ response: { conversation_id: "conv-1" },
+ });
+ const { user } = renderDialog(
+ createSetupEntry({
+ setup: createSetup({
+ message: "Set this up in a conversation instead.",
+ }),
+ }),
+ );
+
+ // Act
+ await user.click(screen.getByTestId("setup-fallback-conversation"));
+
+ // Assert
+ await waitFor(() => expect(mocks.navigate).toHaveBeenCalled());
+ expect(onSetupStep).not.toHaveBeenCalled();
+ window.removeEventListener(SUPER_ADMIN_SETUP_STEP_EVENT, onSetupStep);
+ });
+
it("offers the conversation fallback when the deployment cannot run a direct entry", async () => {
// Arrange — capabilities answered and came up short, and the entry ships
// a fallback-conversation seed.
diff --git a/__tests__/hooks/mutation/use-add-mcp-server.test.ts b/__tests__/hooks/mutation/use-add-mcp-server.test.ts
index 7a4f727e97..5d953edcad 100644
--- a/__tests__/hooks/mutation/use-add-mcp-server.test.ts
+++ b/__tests__/hooks/mutation/use-add-mcp-server.test.ts
@@ -3,6 +3,7 @@ import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { renderHook } from "@testing-library/react";
import { beforeEach, describe, expect, it, vi } from "vitest";
import SettingsService from "#/api/settings-service/settings-service.api";
+import { SUPER_ADMIN_SETUP_STEP_EVENT } from "#/components/features/setup-guide/super-admin-setup-step-event";
import { useAddMcpServer } from "#/hooks/mutation/use-add-mcp-server";
import { SUPER_ADMIN_SETUP_QUERY_KEYS } from "#/hooks/query/query-keys";
@@ -113,6 +114,28 @@ describe("useAddMcpServer", () => {
expect(client.getQueryState(setupStateKey)?.isInvalidated).toBe(true);
});
+ it("tells the Super Admin setup guide that a server was added", async () => {
+ vi.spyOn(SettingsService, "createMcpServer").mockResolvedValue(true);
+ const onSetupStep = vi.fn();
+ window.addEventListener(SUPER_ADMIN_SETUP_STEP_EVENT, onSetupStep);
+ const { result } = renderHook(() => useAddMcpServer(), {
+ wrapper: createWrapper(),
+ });
+
+ await result.current.mutateAsync({
+ id: "",
+ type: "shttp",
+ name: "docs",
+ url: "https://docs.example/mcp",
+ });
+
+ expect(onSetupStep).toHaveBeenCalledTimes(1);
+ expect((onSetupStep.mock.calls[0][0] as CustomEvent).detail).toEqual({
+ id: "add-integration",
+ });
+ window.removeEventListener(SUPER_ADMIN_SETUP_STEP_EVENT, onSetupStep);
+ });
+
it("fails instead of reporting a successful install before settings load", async () => {
useSettingsMock.mockReturnValue({ data: undefined });
const createSpy = vi.spyOn(SettingsService, "createMcpServer");
diff --git a/package-lock.json b/package-lock.json
index 6a51e0f9a6..e03248dc35 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -27,6 +27,7 @@
"class-variance-authority": "0.7.1",
"clsx": "2.1.1",
"downshift": "9.4.0",
+ "driver.js": "1.3.6",
"framer-motion": "12.38.0",
"httpxy": "0.5.5",
"i18next": "26.4.2",
@@ -11272,6 +11273,12 @@
"react": ">=16.12.0"
}
},
+ "node_modules/driver.js": {
+ "version": "1.3.6",
+ "resolved": "https://registry.npmjs.org/driver.js/-/driver.js-1.3.6.tgz",
+ "integrity": "sha512-g2nNuu+tWmPpuoyk3ffpT9vKhjPz4NrJzq6mkRDZIwXCrFhrKdDJ9TX5tJOBpvCTBrBYjgRQ17XlcQB15q4gMg==",
+ "license": "MIT"
+ },
"node_modules/dunder-proto": {
"version": "1.0.1",
"resolved": "https://registry.npmjs.org/dunder-proto/-/dunder-proto-1.0.1.tgz",
diff --git a/package.json b/package.json
index d1b463e869..3e00311dee 100644
--- a/package.json
+++ b/package.json
@@ -37,6 +37,7 @@
"class-variance-authority": "0.7.1",
"clsx": "2.1.1",
"downshift": "9.4.0",
+ "driver.js": "1.3.6",
"framer-motion": "12.38.0",
"httpxy": "0.5.5",
"i18next": "26.4.2",
diff --git a/src/components/features/manifest/manifest-setup-dialog.tsx b/src/components/features/manifest/manifest-setup-dialog.tsx
index afd893c516..52188359ef 100644
--- a/src/components/features/manifest/manifest-setup-dialog.tsx
+++ b/src/components/features/manifest/manifest-setup-dialog.tsx
@@ -12,6 +12,7 @@ import { cn } from "#/utils/utils";
import { modalTitleLgClassName } from "#/utils/modal-classes";
import { getApiErrorBody } from "#/utils/api-error-message";
import { useTracking } from "#/hooks/use-tracking";
+import { notifySuperAdminSetupStep } from "#/components/features/setup-guide/super-admin-setup-step-event";
import { useSetupCapabilities } from "#/hooks/query/use-manifest-capabilities";
import { useSetupPrerequisites } from "#/hooks/query/use-manifest-prerequisites";
import { useLlmProfiles } from "#/hooks/query/use-llm-profiles";
@@ -381,6 +382,8 @@ export function SetupDialog({ entry, onClose }: SetupDialogProps) {
automationId: entry.id,
setupMode,
});
+ // An assisted setup only starts the conversation that creates it.
+ if (setupMode === "direct") notifySuperAdminSetupStep("first-automation");
const destination = getDestination(response);
if (destination) navigate(destination, { replace: true });
else onClose();
diff --git a/src/components/features/setup-guide/super-admin-setup-guide.constants.ts b/src/components/features/setup-guide/super-admin-setup-guide.constants.ts
index 13b1b938e0..0af7a5eff7 100644
--- a/src/components/features/setup-guide/super-admin-setup-guide.constants.ts
+++ b/src/components/features/setup-guide/super-admin-setup-guide.constants.ts
@@ -8,6 +8,13 @@ export const MANAGE_SUPER_ADMINS_PERMISSION = "manage_super_admins";
/** The enterprise setup guide page, on the cloud host. */
export const SUPER_ADMIN_SETUP_GUIDE_PAGE_PATH = "/super-admin/setup";
+/**
+ * Names the setup step whose tour to start when a page loads. The enterprise
+ * guide reads it on the links this guide opens, and Canvas on the links the
+ * enterprise guide opens.
+ */
+export const SETUP_TOUR_PARAM = "setup_tour";
+
export type SuperAdminSetupStepId =
| "add-llm"
| "add-integration"
diff --git a/src/components/features/setup-guide/super-admin-setup-guide.tsx b/src/components/features/setup-guide/super-admin-setup-guide.tsx
index ae77663994..5b70dcc606 100644
--- a/src/components/features/setup-guide/super-admin-setup-guide.tsx
+++ b/src/components/features/setup-guide/super-admin-setup-guide.tsx
@@ -1,4 +1,12 @@
-import { type ReactNode, useEffect, useState } from "react";
+import {
+ type MouseEvent,
+ type ReactNode,
+ useCallback,
+ useEffect,
+ useRef,
+ useState,
+ useSyncExternalStore,
+} from "react";
import { useTranslation } from "react-i18next";
import { ArrowUpRight, Check, ClipboardList, X } from "lucide-react";
import { getLockedCloudHost } from "#/api/agent-server-config";
@@ -9,10 +17,25 @@ import { I18nKey } from "#/i18n/declaration";
import { formControlButtonClassName } from "#/utils/form-control-classes";
import { cn } from "#/utils/utils";
import {
+ SETUP_TOUR_PARAM,
SUPER_ADMIN_SETUP_GUIDE_PAGE_PATH,
+ SUPER_ADMIN_SETUP_STEPS,
type SuperAdminSetupStep,
+ type SuperAdminSetupStepId,
} from "./super-admin-setup-guide.constants";
-import { useSuperAdminSetupGuide } from "./use-super-admin-setup-guide";
+import { SUPER_ADMIN_SETUP_STEP_EVENT } from "./super-admin-setup-step-event";
+import {
+ hasSetupGuideTour,
+ startSetupGuideTour,
+} from "./tour/setup-guide-tour";
+import {
+ isGuidedTourActive,
+ subscribeGuidedTourActive,
+} from "./tour/tour-engine";
+import {
+ getNextSetupStep,
+ useSuperAdminSetupGuide,
+} from "./use-super-admin-setup-guide";
const ICON_BUTTON_CLASS = cn(
"inline-flex size-7 shrink-0 items-center justify-center rounded-md",
@@ -31,6 +54,23 @@ const START_BUTTON_CLASS = cn(
const START_TEST_ID = "super-admin-setup-guide-start";
+/**
+ * A page on the cloud host, on the guide's organization when given, and
+ * naming the step whose tour the enterprise guide should start.
+ */
+function cloudPageUrl(
+ cloudHost: string,
+ path: string,
+ orgId: string | null,
+ tourStepId?: SuperAdminSetupStepId,
+) {
+ const params = new URLSearchParams();
+ if (orgId) params.set("org", orgId);
+ if (tourStepId) params.set(SETUP_TOUR_PARAM, tourStepId);
+ const query = params.toString();
+ return query ? `${cloudHost}${path}?${query}` : `${cloudHost}${path}`;
+}
+
/**
* Floating lower-right setup guide for the enterprise Super Admin, matching
* the guide in the OpenHands Enterprise app. Steps that live in the
@@ -38,7 +78,7 @@ const START_TEST_ID = "super-admin-setup-guide-start";
*/
export default function SuperAdminSetupGuide() {
const { t } = useTranslation("openhands");
- const { currentPath } = useNavigation();
+ const { currentPath, navigate } = useNavigation();
const { backend } = useActiveBackend();
const {
steps,
@@ -50,6 +90,26 @@ export default function SuperAdminSetupGuide() {
refetch,
} = useSuperAdminSetupGuide();
const [open, setOpen] = useState(true);
+ const tourActive = useSyncExternalStore(
+ subscribeGuidedTourActive,
+ isGuidedTourActive,
+ isGuidedTourActive,
+ );
+
+ // The tour checks the current route after it navigates, between renders.
+ const pathRef = useRef(currentPath);
+ useEffect(() => {
+ pathRef.current = currentPath;
+ }, [currentPath]);
+ const startTour = useCallback(
+ (stepId: SuperAdminSetupStepId) =>
+ startSetupGuideTour(
+ stepId,
+ { navigate, getPath: () => pathRef.current },
+ t,
+ ),
+ [navigate, t],
+ );
// Progress is read from the server, so re-read it as the admin moves around.
useEffect(() => {
@@ -58,29 +118,113 @@ export default function SuperAdminSetupGuide() {
}
}, [currentPath, visible, refetch]);
- if (!visible) {
- return null;
- }
-
const cloudHost = backend.host.replace(/\/+$/, "");
// Locked-to-Cloud serves the canvas on the cloud host itself, so enterprise
// pages open in this tab; standalone / Electron keep a new tab.
const isLockedToCloud = getLockedCloudHost() !== null;
+
+ // When the guide's next step is done, open the step after it the way Start
+ // does. A step finished out of order, or not confirmed by the server, only
+ // refreshes the progress; nothing opens after the last required step.
+ const nextStepId = nextStep?.id ?? null;
+ useEffect(() => {
+ if (!visible) {
+ return undefined;
+ }
+ const onStep = async (event: Event) => {
+ const completedId = (event as CustomEvent<{ id?: string }>).detail?.id;
+ const { data } = await refetch();
+ const guideSteps = data?.guide_steps;
+ if (!guideSteps || !completedId || completedId !== nextStepId) {
+ return;
+ }
+ const after = getNextSetupStep(guideSteps);
+ if (!after || after.id === completedId) {
+ return;
+ }
+ const { destination } = after;
+ if (destination.kind === "canvas") {
+ if (hasSetupGuideTour(after.id)) {
+ await startTour(after.id);
+ } else {
+ navigate(destination.path);
+ }
+ } else if (isLockedToCloud) {
+ window.location.assign(
+ cloudPageUrl(
+ cloudHost,
+ destination.path,
+ destination.withOrg ? guideOrgId : null,
+ after.id,
+ ),
+ );
+ } else {
+ // A new tab opened after a save is blocked, so point at Start instead.
+ setOpen(true);
+ }
+ };
+ window.addEventListener(SUPER_ADMIN_SETUP_STEP_EVENT, onStep);
+ return () =>
+ window.removeEventListener(SUPER_ADMIN_SETUP_STEP_EVENT, onStep);
+ }, [
+ visible,
+ refetch,
+ nextStepId,
+ navigate,
+ startTour,
+ cloudHost,
+ guideOrgId,
+ isLockedToCloud,
+ ]);
+
+ // A page opened from the enterprise guide names the step whose tour to
+ // start. Enterprise steps have no tour here, so only Canvas steps start.
+ useEffect(() => {
+ if (!visible) {
+ return;
+ }
+ const params = new URLSearchParams(window.location.search);
+ const requested = params.get(SETUP_TOUR_PARAM);
+ if (!requested) {
+ return;
+ }
+ // Drop it first, so the tour starts once.
+ params.delete(SETUP_TOUR_PARAM);
+ const query = params.toString();
+ window.history.replaceState(
+ window.history.state,
+ "",
+ `${window.location.pathname}${query ? `?${query}` : ""}${window.location.hash}`,
+ );
+ const step = SUPER_ADMIN_SETUP_STEPS.find(({ id }) => id === requested);
+ if (step && hasSetupGuideTour(step.id)) {
+ setOpen(false);
+ startTour(step.id);
+ }
+ }, [visible, startTour]);
+
+ if (!visible || tourActive) {
+ return null;
+ }
+
const cloudLinkProps = {
target: isLockedToCloud ? undefined : "_blank",
rel: isLockedToCloud ? undefined : "noopener noreferrer",
};
- const cloudUrl = (path: string, withOrg: boolean) =>
- withOrg && guideOrgId
- ? `${cloudHost}${path}?org=${encodeURIComponent(guideOrgId)}`
- : `${cloudHost}${path}`;
- // A step row and Start open the same page for a step.
+ const cloudUrl = (
+ path: string,
+ withOrg: boolean,
+ tourStepId?: SuperAdminSetupStepId,
+ ) => cloudPageUrl(cloudHost, path, withOrg ? guideOrgId : null, tourStepId);
+ // A step row and Start open the same page for a step; Start also asks the
+ // enterprise guide for the step's tour.
const renderStepLink = (
step: SuperAdminSetupStep,
testId: string,
className: string,
children: ReactNode,
- onClick?: () => void,
+ onClick?: (event: MouseEvent<HTMLAnchorElement>) => void,
+ startsTour = false,
) =>
step.destination.kind === "canvas" ? (
<NavigationLink
@@ -93,7 +237,11 @@ export default function SuperAdminSetupGuide() {
</NavigationLink>
) : (
<a
- href={cloudUrl(step.destination.path, step.destination.withOrg)}
+ href={cloudUrl(
+ step.destination.path,
+ step.destination.withOrg,
+ startsTour ? step.id : undefined,
+ )}
{...cloudLinkProps}
data-testid={testId}
className={className}
@@ -216,13 +364,31 @@ export default function SuperAdminSetupGuide() {
</p>
{/* Like the enterprise Start, close the panel before opening
the step, so Start does something even when the admin is
- already on that step's page. */}
+ already on that step's page. A Canvas step's tour opens
+ the page itself; a modified click still follows the link. */}
{renderStepLink(
nextStep,
START_TEST_ID,
START_BUTTON_CLASS,
t(I18nKey.ONBOARDING$SETUP_GUIDE_START),
- () => setOpen(false),
+ (event) => {
+ setOpen(false);
+ const plainClick =
+ event.button === 0 &&
+ !event.metaKey &&
+ !event.ctrlKey &&
+ !event.shiftKey &&
+ !event.altKey;
+ if (
+ plainClick &&
+ nextStep.destination.kind === "canvas" &&
+ hasSetupGuideTour(nextStep.id)
+ ) {
+ event.preventDefault();
+ startTour(nextStep.id);
+ }
+ },
+ true,
)}
</div>
) : null}
diff --git a/src/components/features/setup-guide/super-admin-setup-step-event.ts b/src/components/features/setup-guide/super-admin-setup-step-event.ts
new file mode 100644
index 0000000000..69f6aadd75
--- /dev/null
+++ b/src/components/features/setup-guide/super-admin-setup-step-event.ts
@@ -0,0 +1,11 @@
+import type { SuperAdminSetupStepId } from "./super-admin-setup-guide.constants";
+
+/** Dispatched when the action behind a setup guide step succeeds in Canvas. */
+export const SUPER_ADMIN_SETUP_STEP_EVENT = "oh-super-admin-setup-step";
+
+/** Tell the setup guide that a step's action just succeeded. */
+export function notifySuperAdminSetupStep(stepId: SuperAdminSetupStepId) {
+ window.dispatchEvent(
+ new CustomEvent(SUPER_ADMIN_SETUP_STEP_EVENT, { detail: { id: stepId } }),
+ );
+}
diff --git a/src/components/features/setup-guide/tour/setup-guide-tour.ts b/src/components/features/setup-guide/tour/setup-guide-tour.ts
new file mode 100644
index 0000000000..a8a0716f6c
--- /dev/null
+++ b/src/components/features/setup-guide/tour/setup-guide-tour.ts
@@ -0,0 +1,88 @@
+import { I18nKey } from "#/i18n/declaration";
+import {
+ SUPER_ADMIN_SETUP_STEPS,
+ type SuperAdminSetupStepId,
+} from "../super-admin-setup-guide.constants";
+import { startGuidedTour, type GuidedTourNavigation } from "./tour-engine";
+import type { GuidedTourStop } from "./tour-types";
+
+type TourStopSpec = Omit<GuidedTourStop, "title" | "body"> & {
+ title: I18nKey;
+ body: I18nKey;
+};
+
+/**
+ * Tour stops for the setup steps done in Canvas. Each step's first stop is on
+ * the step's page; the next one follows the admin's click.
+ */
+const SETUP_GUIDE_TOUR_STOPS: Partial<
+ Record<SuperAdminSetupStepId, TourStopSpec[]>
+> = {
+ "first-automation": [
+ {
+ id: "choose-template",
+ anchor: '[data-testid="recommended-automations-section"]',
+ advanceOnClick: '[data-testid^="recommended-automation-card-"]',
+ title: I18nKey.ONBOARDING$SETUP_GUIDE_TOUR_TEMPLATE_TITLE,
+ body: I18nKey.ONBOARDING$SETUP_GUIDE_TOUR_TEMPLATE_BODY,
+ side: "top",
+ },
+ {
+ id: "set-up-automation",
+ anchor: '[data-testid="setup-dialog"]',
+ waitForComplete: "first-automation",
+ interactive: true,
+ title: I18nKey.ONBOARDING$SETUP_GUIDE_TOUR_AUTOMATION_TITLE,
+ body: I18nKey.ONBOARDING$SETUP_GUIDE_TOUR_AUTOMATION_BODY,
+ side: "left",
+ },
+ ],
+ "add-integration": [
+ {
+ id: "add-custom-server",
+ anchor: '[data-testid="mcp-add-custom-server"]',
+ nextClicksAnchor: true,
+ title: I18nKey.ONBOARDING$SETUP_GUIDE_TOUR_MCP_ADD_TITLE,
+ body: I18nKey.ONBOARDING$SETUP_GUIDE_TOUR_MCP_ADD_BODY,
+ side: "bottom",
+ },
+ {
+ id: "connect-server",
+ anchor: '[data-testid="mcp-custom-editor"]',
+ waitForComplete: "add-integration",
+ interactive: true,
+ title: I18nKey.ONBOARDING$SETUP_GUIDE_TOUR_MCP_FORM_TITLE,
+ body: I18nKey.ONBOARDING$SETUP_GUIDE_TOUR_MCP_FORM_BODY,
+ side: "left",
+ },
+ ],
+};
+
+export function hasSetupGuideTour(stepId: SuperAdminSetupStepId): boolean {
+ return Boolean(SETUP_GUIDE_TOUR_STOPS[stepId]?.length);
+}
+
+/** Open a Canvas setup step's page and walk the admin through it. */
+export async function startSetupGuideTour(
+ stepId: SuperAdminSetupStepId,
+ nav: GuidedTourNavigation,
+ t: (key: I18nKey) => string,
+): Promise<void> {
+ const specs = SETUP_GUIDE_TOUR_STOPS[stepId];
+ const step = SUPER_ADMIN_SETUP_STEPS.find(({ id }) => id === stepId);
+ if (!specs || step?.destination.kind !== "canvas") {
+ return;
+ }
+ const route = step.destination.path;
+ const stops = specs.map(({ title, body, ...stop }, index) => ({
+ ...stop,
+ route: index === 0 ? route : undefined,
+ title: t(title),
+ body: t(body),
+ }));
+ await startGuidedTour({ id: stepId, stops }, nav, {
+ next: t(I18nKey.ONBOARDING$NEXT),
+ previous: t(I18nKey.ONBOARDING$BACK),
+ done: t(I18nKey.ONBOARDING$SETUP_GUIDE_TOUR_DONE),
+ });
+}
diff --git a/src/components/features/setup-guide/tour/tour-engine.ts b/src/components/features/setup-guide/tour/tour-engine.ts
new file mode 100644
index 0000000000..0a2901da76
--- /dev/null
+++ b/src/components/features/setup-guide/tour/tour-engine.ts
@@ -0,0 +1,359 @@
+import { driver, type Driver } from "driver.js";
+import "driver.js/dist/driver.css";
+import { SUPER_ADMIN_SETUP_STEP_EVENT } from "../super-admin-setup-step-event";
+import type {
+ GuidedTour,
+ GuidedTourLabels,
+ GuidedTourSide,
+ GuidedTourStop,
+} from "./tour-types";
+import "./tour-theme.css";
+
+/**
+ * Spotlight tour for the enterprise setup guide's steps in Canvas, ported from
+ * the enterprise app's tour engine so both apps' tours look and behave alike.
+ */
+
+/** On `<body>` while the current stop keeps the whole page usable. */
+const INTERACTIVE_STOP_CLASS = "oh-setup-tour-interactive";
+
+export interface GuidedTourNavigation {
+ navigate: (to: string) => void;
+ /** The current route, relative to the app's base path. */
+ getPath: () => string;
+}
+
+let activeDriver: Driver | null = null;
+const resolvedAnchors = new Map<string, Element>();
+const tourActiveListeners = new Set<() => void>();
+let tourActive = false;
+let setupStepListener: ((event: Event) => void) | null = null;
+// Bumped whenever a tour is stopped or replaced. driver.js keeps its state at
+// module level, so a delayed callback from an older tour would act on (and
+// destroy) the current one; callbacks check their generation first.
+let tourGeneration = 0;
+
+function setTourActive(next: boolean): void {
+ if (tourActive === next) {
+ return;
+ }
+ tourActive = next;
+ tourActiveListeners.forEach((listener) => listener());
+}
+
+export function isGuidedTourActive(): boolean {
+ return tourActive;
+}
+
+export function subscribeGuidedTourActive(listener: () => void): () => void {
+ tourActiveListeners.add(listener);
+ return () => {
+ tourActiveListeners.delete(listener);
+ };
+}
+
+function wait(ms: number): Promise<void> {
+ return new Promise((resolve) => {
+ window.setTimeout(resolve, ms);
+ });
+}
+
+function setInteractive(stop: GuidedTourStop | undefined): void {
+ document.body.classList.toggle(
+ INTERACTIVE_STOP_CLASS,
+ Boolean(stop?.interactive),
+ );
+}
+
+function queryFirst(selector: string): Element | null {
+ const parts = selector.split(",").map((part) => part.trim());
+ for (const part of parts) {
+ const el = document.querySelector(part);
+ if (el) {
+ return el;
+ }
+ }
+ return null;
+}
+
+async function resolveAnchor(selector: string): Promise<Element | null> {
+ // A stop reached by a click (a new route, a dialog) can take a moment.
+ for (let attempt = 0; attempt < 50; attempt += 1) {
+ const el = queryFirst(selector);
+ if (el) {
+ el.scrollIntoView({ block: "nearest", inline: "nearest" });
+ return el;
+ }
+ await wait(100);
+ }
+ return null;
+}
+
+function sideFor(el: Element, requested?: GuidedTourSide): GuidedTourSide {
+ const rect = el.getBoundingClientRect();
+ const spaceRight = window.innerWidth - rect.right;
+ const spaceBottom = window.innerHeight - rect.bottom;
+ if (requested === "right" && spaceRight > 340) {
+ return "right";
+ }
+ if (requested === "left" && rect.left > 340) {
+ return "left";
+ }
+ if (spaceBottom > 220) {
+ return "bottom";
+ }
+ if (rect.top > 220) {
+ return "top";
+ }
+ return requested ?? "bottom";
+}
+
+async function prepareStop(
+ stop: GuidedTourStop,
+ nav: GuidedTourNavigation,
+): Promise<Element | null> {
+ if (stop.route && nav.getPath() !== stop.route) {
+ nav.navigate(stop.route);
+ // The route's page needs a beat before its anchors exist.
+ await wait(400);
+ }
+ const el = await resolveAnchor(stop.anchor);
+ if (el) {
+ resolvedAnchors.set(stop.id, el);
+ } else {
+ resolvedAnchors.delete(stop.id);
+ }
+ return el;
+}
+
+function clearSetupStepListener(): void {
+ if (setupStepListener) {
+ window.removeEventListener(SUPER_ADMIN_SETUP_STEP_EVENT, setupStepListener);
+ setupStepListener = null;
+ }
+}
+
+export function stopGuidedTour(): void {
+ tourGeneration += 1;
+ clearSetupStepListener();
+ setInteractive(undefined);
+ activeDriver?.destroy();
+ activeDriver = null;
+ resolvedAnchors.clear();
+ setTourActive(false);
+}
+
+export async function startGuidedTour(
+ tour: GuidedTour,
+ nav: GuidedTourNavigation,
+ labels: GuidedTourLabels,
+): Promise<void> {
+ stopGuidedTour();
+ const generation = tourGeneration;
+ const isCurrent = () => generation === tourGeneration;
+
+ const { stops } = tour;
+ if (stops.length === 0) {
+ return;
+ }
+ await prepareStop(stops[0], nav);
+ if (!isCurrent()) {
+ return;
+ }
+
+ let index = 0;
+ let anchorClickHandler: ((event: Event) => void) | null = null;
+ const isWaiting = (stop: GuidedTourStop | undefined) =>
+ Boolean(stop?.waitForComplete || stop?.advanceOnClick);
+
+ const tourCtl: {
+ clearAnchorClickHandler: () => void;
+ advanceFrom: (instanceApi: Driver, nextIndex: number) => Promise<void>;
+ bindWaitForComplete: (instanceApi: Driver) => void;
+ bindInteractiveStop: (instanceApi: Driver) => void;
+ } = {
+ clearAnchorClickHandler: () => {
+ if (!anchorClickHandler) {
+ return;
+ }
+ for (const el of resolvedAnchors.values()) {
+ el.removeEventListener("click", anchorClickHandler);
+ }
+ anchorClickHandler = null;
+ },
+ advanceFrom: async (instanceApi, nextIndex) => {
+ if (!isCurrent()) {
+ return;
+ }
+ const nextStop = stops[nextIndex];
+ if (!nextStop) {
+ instanceApi.destroy();
+ return;
+ }
+ clearSetupStepListener();
+ tourCtl.clearAnchorClickHandler();
+ await prepareStop(nextStop, nav);
+ if (!isCurrent()) {
+ return;
+ }
+ index = nextIndex;
+ setInteractive(nextStop);
+ instanceApi.moveTo(nextIndex);
+ window.setTimeout(() => {
+ if (!isCurrent()) {
+ return;
+ }
+ instanceApi.refresh();
+ tourCtl.bindInteractiveStop(instanceApi);
+ }, 30);
+ },
+ bindWaitForComplete: (instanceApi) => {
+ clearSetupStepListener();
+ const waitIndex = stops.findIndex((stop) => stop.waitForComplete);
+ if (waitIndex < 0) {
+ return;
+ }
+ const { waitForComplete } = stops[waitIndex];
+ setupStepListener = (event: Event) => {
+ const { detail } = event as CustomEvent<{ id?: string }>;
+ if (detail?.id !== waitForComplete || index > waitIndex) {
+ return;
+ }
+ clearSetupStepListener();
+ // Let the completing UI (a dialog) unmount before moving on.
+ wait(80)
+ .then(() => tourCtl.advanceFrom(instanceApi, waitIndex + 1))
+ .catch(() => undefined);
+ };
+ window.addEventListener(SUPER_ADMIN_SETUP_STEP_EVENT, setupStepListener);
+ },
+ bindInteractiveStop: (instanceApi) => {
+ tourCtl.clearAnchorClickHandler();
+ tourCtl.bindWaitForComplete(instanceApi);
+ const current = stops[index];
+ const anchor = current && resolvedAnchors.get(current.id);
+ if (!anchor || (!current.nextClicksAnchor && !current.advanceOnClick)) {
+ return;
+ }
+ anchorClickHandler = (event: Event) => {
+ const { target } = event;
+ if (
+ current.advanceOnClick &&
+ !(target instanceof Element && target.closest(current.advanceOnClick))
+ ) {
+ return;
+ }
+ tourCtl.clearAnchorClickHandler();
+ wait(280)
+ .then(() => tourCtl.advanceFrom(instanceApi, index + 1))
+ .catch(() => undefined);
+ };
+ anchor.addEventListener("click", anchorClickHandler);
+ },
+ };
+
+ const instance = driver({
+ showProgress: stops.length > 1,
+ progressText: "{{current}}/{{total}}",
+ nextBtnText: labels.next,
+ prevBtnText: labels.previous,
+ doneBtnText: labels.done,
+ allowClose: true,
+ // Arrow keys would move the tour while the admin types in a form.
+ allowKeyboardControl: false,
+ // Allow clicking the highlighted control (a template card, a button).
+ disableActiveInteraction: false,
+ overlayColor: "#000",
+ overlayOpacity: 0.6,
+ stagePadding: 8,
+ popoverOffset: 16,
+ smoothScroll: true,
+ popoverClass: "oh-setup-tour-popover",
+ steps: stops.map((stop) => ({
+ element: () => resolvedAnchors.get(stop.id) as Element,
+ popover: {
+ title: stop.title,
+ description: stop.body,
+ side: stop.side ?? "bottom",
+ align: "start",
+ },
+ })),
+ onHighlightStarted: (el, step) => {
+ if (el && step.popover) {
+ // eslint-disable-next-line no-param-reassign -- driver.js reads it back
+ step.popover.side = sideFor(
+ el,
+ step.popover.side as GuidedTourSide | undefined,
+ );
+ }
+ },
+ onPopoverRender: (popover) => {
+ // Completion and clicks are event-driven on these stops.
+ // eslint-disable-next-line no-param-reassign -- driver.js owns this node
+ popover.nextButton.style.display = isWaiting(stops[index]) ? "none" : "";
+ },
+ onNextClick: async (_el, _step, { driver: instanceApi }) => {
+ const current = stops[index];
+ if (isWaiting(current)) {
+ return;
+ }
+ tourCtl.clearAnchorClickHandler();
+ if (current?.nextClicksAnchor) {
+ const anchor = resolvedAnchors.get(current.id);
+ if (anchor instanceof HTMLElement) {
+ anchor.click();
+ await wait(280);
+ }
+ }
+ await tourCtl.advanceFrom(instanceApi, index + 1);
+ },
+ onPrevClick: async (_el, _step, { driver: instanceApi }) => {
+ const prevStop = stops[index - 1];
+ if (!prevStop) {
+ return;
+ }
+ clearSetupStepListener();
+ tourCtl.clearAnchorClickHandler();
+ await prepareStop(prevStop, nav);
+ if (!isCurrent()) {
+ return;
+ }
+ index -= 1;
+ setInteractive(prevStop);
+ instanceApi.movePrevious();
+ window.setTimeout(() => {
+ if (!isCurrent()) {
+ return;
+ }
+ instanceApi.refresh();
+ tourCtl.bindInteractiveStop(instanceApi);
+ }, 30);
+ },
+ onCloseClick: (_el, _step, { driver: instanceApi }) => {
+ instanceApi.destroy();
+ },
+ onDestroyed: () => {
+ tourCtl.clearAnchorClickHandler();
+ if (!isCurrent()) {
+ return;
+ }
+ clearSetupStepListener();
+ setInteractive(undefined);
+ activeDriver = null;
+ resolvedAnchors.clear();
+ setTourActive(false);
+ },
+ });
+
+ activeDriver = instance;
+ setTourActive(true);
+ setInteractive(stops[0]);
+ instance.drive();
+ window.setTimeout(() => {
+ if (!isCurrent()) {
+ return;
+ }
+ instance.refresh();
+ tourCtl.bindInteractiveStop(instance);
+ }, 40);
+}
diff --git a/src/components/features/setup-guide/tour/tour-theme.css b/src/components/features/setup-guide/tour/tour-theme.css
new file mode 100644
index 0000000000..c56e8b5ff8
--- /dev/null
+++ b/src/components/features/setup-guide/tour/tour-theme.css
@@ -0,0 +1,181 @@
+/* The enterprise app's tour popover, with Canvas's theme tokens. */
+.oh-setup-tour-popover.driver-popover {
+ background: var(--oh-color-base-secondary);
+ color: var(--oh-foreground);
+ color-scheme: dark;
+ border: 1px solid var(--oh-border);
+ border-radius: 12px;
+ box-shadow: 0 12px 40px rgb(0 0 0 / 45%);
+ min-width: 300px;
+ max-width: 400px;
+ padding: 18px 20px 16px;
+}
+
+.oh-setup-tour-popover .driver-popover-arrow {
+ border-width: 6px;
+}
+
+.oh-setup-tour-popover .driver-popover-arrow::after {
+ content: "";
+ position: absolute;
+ border: 6px solid transparent;
+}
+
+.oh-setup-tour-popover .driver-popover-arrow-side-left {
+ border-left-color: var(--oh-border);
+}
+
+.oh-setup-tour-popover .driver-popover-arrow-side-left::after {
+ top: -6px;
+ left: -7px;
+ border-left-color: var(--oh-color-base-secondary);
+}
+
+.oh-setup-tour-popover .driver-popover-arrow-side-right {
+ border-right-color: var(--oh-border);
+}
+
+.oh-setup-tour-popover .driver-popover-arrow-side-right::after {
+ top: -6px;
+ left: -5px;
+ border-right-color: var(--oh-color-base-secondary);
+}
+
+.oh-setup-tour-popover .driver-popover-arrow-side-top {
+ border-top-color: var(--oh-border);
+}
+
+.oh-setup-tour-popover .driver-popover-arrow-side-top::after {
+ top: -7px;
+ left: -6px;
+ border-top-color: var(--oh-color-base-secondary);
+}
+
+.oh-setup-tour-popover .driver-popover-arrow-side-bottom {
+ border-bottom-color: var(--oh-border);
+}
+
+.oh-setup-tour-popover .driver-popover-arrow-side-bottom::after {
+ top: -5px;
+ left: -6px;
+ border-bottom-color: var(--oh-color-base-secondary);
+}
+
+.oh-setup-tour-popover .driver-popover-title {
+ color: var(--oh-foreground);
+ font-size: 17px;
+ line-height: 1.3;
+ font-weight: 600;
+ letter-spacing: -0.2px;
+}
+
+.oh-setup-tour-popover .driver-popover-description {
+ color: var(--oh-muted);
+ font-size: 14px;
+ line-height: 1.5;
+}
+
+.oh-setup-tour-popover .driver-popover-progress-text {
+ color: var(--oh-muted);
+ font-size: 12px;
+}
+
+.oh-setup-tour-popover .driver-popover-footer {
+ margin-top: 16px;
+}
+
+.oh-setup-tour-popover .driver-popover-footer button {
+ padding: 8px 14px;
+ font-size: 13px;
+ line-height: 1.3;
+ font-weight: 500;
+ border-radius: 8px;
+ text-shadow: none;
+}
+
+.oh-setup-tour-popover .driver-popover-next-btn {
+ background: var(--oh-foreground);
+ color: var(--oh-color-base);
+ border: 1px solid var(--oh-foreground);
+}
+
+.oh-setup-tour-popover .driver-popover-next-btn:hover {
+ opacity: 0.9;
+}
+
+.oh-setup-tour-popover .driver-popover-prev-btn {
+ background: transparent;
+ color: var(--oh-foreground);
+ border: 1px solid var(--oh-border);
+}
+
+.oh-setup-tour-popover .driver-popover-prev-btn:hover {
+ background: var(--oh-surface-raised);
+}
+
+.oh-setup-tour-popover .driver-popover-prev-btn:disabled {
+ color: var(--oh-muted);
+ opacity: 0.5;
+}
+
+.oh-setup-tour-popover .driver-popover-close-btn {
+ top: 8px;
+ right: 8px;
+ width: 32px;
+ height: 32px;
+ font-size: 20px;
+ background: transparent;
+ color: var(--oh-muted);
+ border: none;
+ box-shadow: none;
+ outline: none;
+ text-shadow: none;
+}
+
+.oh-setup-tour-popover .driver-popover-close-btn:hover,
+.oh-setup-tour-popover .driver-popover-close-btn:focus {
+ background: transparent;
+ color: var(--oh-foreground);
+ border: none;
+ box-shadow: none;
+ outline: none;
+}
+
+/*
+ * driver.js puts its state classes on <body>, but Canvas scopes every rule
+ * under [data-agent-server-ui], which is on <body> itself, so driver.css's
+ * `.driver-active …` rules never match. They are restated here on the body.
+ * Selectors that name the scope attribute are left as written.
+ */
+[data-agent-server-ui].driver-active .driver-overlay,
+[data-agent-server-ui].driver-active * {
+ pointer-events: none;
+}
+
+[data-agent-server-ui].driver-active .driver-active-element,
+[data-agent-server-ui].driver-active .driver-active-element *,
+[data-agent-server-ui].driver-active .driver-popover,
+[data-agent-server-ui].driver-active .driver-popover * {
+ pointer-events: auto;
+}
+
+[data-agent-server-ui].driver-fade .driver-overlay {
+ animation: animate-fade-in 0.2s ease-in-out;
+}
+
+[data-agent-server-ui].driver-fade .driver-popover {
+ animation: animate-fade-in 0.2s;
+}
+
+/*
+ * A stop on a form keeps the whole page usable. driver.js otherwise turns off
+ * pointer events outside the highlighted element, which would also block a
+ * dropdown's option list rendered in a portal.
+ */
+[data-agent-server-ui].oh-setup-tour-interactive .driver-overlay {
+ display: none;
+}
+
+[data-agent-server-ui].oh-setup-tour-interactive.driver-active * {
+ pointer-events: auto;
+}
diff --git a/src/components/features/setup-guide/tour/tour-types.ts b/src/components/features/setup-guide/tour/tour-types.ts
new file mode 100644
index 0000000000..b16869896a
--- /dev/null
+++ b/src/components/features/setup-guide/tour/tour-types.ts
@@ -0,0 +1,43 @@
+import type { SuperAdminSetupStepId } from "../super-admin-setup-guide.constants";
+
+export type GuidedTourSide = "top" | "right" | "bottom" | "left";
+
+export interface GuidedTourStop {
+ id: string;
+ /**
+ * The Canvas route the stop is on. Left out for a stop the admin reaches
+ * by the previous stop's click, such as a setup page for the chosen entry.
+ */
+ route?: string;
+ /** CSS selector of the element the stop points at. */
+ anchor: string;
+ title: string;
+ body: string;
+ side?: GuidedTourSide;
+ /** Next clicks the anchor first, e.g. to open a form from its button. */
+ nextClicksAnchor?: boolean;
+ /**
+ * Hide Next; move on when the admin clicks an element matching this
+ * selector inside the anchor, such as one template card in a list.
+ */
+ advanceOnClick?: string;
+ /** Hide Next; end the stop when this setup step reports success. */
+ waitForComplete?: SuperAdminSetupStepId;
+ /**
+ * Keep the whole page usable: no dimmed overlay, and controls outside the
+ * anchor (such as a dropdown's option list) still take clicks.
+ */
+ interactive?: boolean;
+}
+
+export interface GuidedTour {
+ id: string;
+ stops: GuidedTourStop[];
+}
+
+/** Translated button labels for the tour popover. */
+export interface GuidedTourLabels {
+ next: string;
+ previous: string;
+ done: string;
+}
diff --git a/src/components/features/setup-guide/use-super-admin-setup-guide.ts b/src/components/features/setup-guide/use-super-admin-setup-guide.ts
index 34f4877dde..fe1e09d38f 100644
--- a/src/components/features/setup-guide/use-super-admin-setup-guide.ts
+++ b/src/components/features/setup-guide/use-super-admin-setup-guide.ts
@@ -31,6 +31,13 @@ function isStepDone(
return guideSteps[step.completion];
}
+/** The first required step the server does not report as done, if any. */
+export function getNextSetupStep(
+ guideSteps: CloudSetupGuideSteps | null,
+): SuperAdminSetupStep | null {
+ return REQUIRED_STEPS.find((step) => !isStepDone(step, guideSteps)) ?? null;
+}
+
/**
* The enterprise Super Admin setup guide for the active cloud backend.
*
@@ -82,8 +89,7 @@ export function useSuperAdminSetupGuide() {
const completedCount = REQUIRED_STEPS.filter((step) =>
isStepDone(step, guideSteps),
).length;
- const nextStep =
- REQUIRED_STEPS.find((step) => !isStepDone(step, guideSteps)) ?? null;
+ const nextStep = getNextSetupStep(guideSteps);
const guideOrgId = setupState?.guide_org_id ?? null;
// Only the first Super Admin's guide has an organization; it stays until dismissed.
const active = Boolean(guideOrgId) && !setupState?.guide_dismissed;
diff --git a/src/hooks/mutation/use-add-mcp-server.ts b/src/hooks/mutation/use-add-mcp-server.ts
index c597433c44..c23550539c 100644
--- a/src/hooks/mutation/use-add-mcp-server.ts
+++ b/src/hooks/mutation/use-add-mcp-server.ts
@@ -11,6 +11,7 @@ import {
SETTINGS_QUERY_KEYS,
SUPER_ADMIN_SETUP_QUERY_KEYS,
} from "#/hooks/query/query-keys";
+import { notifySuperAdminSetupStep } from "#/components/features/setup-guide/super-admin-setup-step-event";
// @spec MCP-001 — Sparse mutations preserve sibling servers
export function useAddMcpServer() {
@@ -45,6 +46,7 @@ export function useAddMcpServer() {
queryClient.invalidateQueries({
queryKey: SUPER_ADMIN_SETUP_QUERY_KEYS.all,
});
+ notifySuperAdminSetupStep("add-integration");
},
});
}
diff --git a/src/i18n/translation.json b/src/i18n/translation.json
index 8416cda60c..50d3909f04 100644
--- a/src/i18n/translation.json
+++ b/src/i18n/translation.json
@@ -43196,6 +43196,159 @@
"tr": "Başla",
"uk": "Почати"
},
+ "ONBOARDING$SETUP_GUIDE_TOUR_TEMPLATE_TITLE": {
+ "en": "Choose a template",
+ "ja": "テンプレートを選択",
+ "zh-CN": "选择模板",
+ "zh-TW": "選擇範本",
+ "ko-KR": "템플릿 선택",
+ "no": "Velg en mal",
+ "ar": "اختر قالبًا",
+ "de": "Vorlage auswählen",
+ "fr": "Choisissez un modèle",
+ "it": "Scegli un modello",
+ "pt": "Escolha um modelo",
+ "es": "Elige una plantilla",
+ "ca": "Tria una plantilla",
+ "tr": "Bir şablon seçin",
+ "uk": "Виберіть шаблон"
+ },
+ "ONBOARDING$SETUP_GUIDE_TOUR_TEMPLATE_BODY": {
+ "en": "Pick an automation to start from. Its setup opens next.",
+ "ja": "最初に使う自動化を選んでください。次にその設定画面が開きます。",
+ "zh-CN": "选择一个自动化作为起点。接下来会打开它的设置。",
+ "zh-TW": "選擇一個自動化作為起點。接著會開啟它的設定。",
+ "ko-KR": "시작할 자동화를 선택하세요. 다음으로 설정 화면이 열립니다.",
+ "no": "Velg en automatisering å starte med. Oppsettet åpnes deretter.",
+ "ar": "اختر أتمتة لتبدأ بها. سيُفتح إعدادها بعد ذلك.",
+ "de": "Wählen Sie eine Automatisierung als Ausgangspunkt. Danach öffnet sich ihre Einrichtung.",
+ "fr": "Choisissez une automatisation pour commencer. Sa configuration s'ouvre ensuite.",
+ "it": "Scegli un'automazione da cui partire. Subito dopo si apre la sua configurazione.",
+ "pt": "Escolha uma automação para começar. A configuração dela abre em seguida.",
+ "es": "Elige una automatización para empezar. Después se abre su configuración.",
+ "ca": "Tria una automatització per començar. Després s'obre la seva configuració.",
+ "tr": "Başlamak için bir otomasyon seçin. Ardından kurulumu açılır.",
+ "uk": "Виберіть автоматизацію, з якої почнете. Далі відкриється її налаштування."
+ },
+ "ONBOARDING$SETUP_GUIDE_TOUR_AUTOMATION_TITLE": {
+ "en": "Set up the automation",
+ "ja": "自動化を設定",
+ "zh-CN": "设置自动化",
+ "zh-TW": "設定自動化",
+ "ko-KR": "자동화 설정",
+ "no": "Sett opp automatiseringen",
+ "ar": "إعداد الأتمتة",
+ "de": "Automatisierung einrichten",
+ "fr": "Configurez l'automatisation",
+ "it": "Configura l'automazione",
+ "pt": "Configure a automação",
+ "es": "Configura la automatización",
+ "ca": "Configura l'automatització",
+ "tr": "Otomasyonu kurun",
+ "uk": "Налаштуйте автоматизацію"
+ },
+ "ONBOARDING$SETUP_GUIDE_TOUR_AUTOMATION_BODY": {
+ "en": "Fill in the details, review them and create the automation. The guide moves on once it is created.",
+ "ja": "詳細を入力して確認し、自動化を作成してください。作成されるとガイドは次に進みます。",
+ "zh-CN": "填写详细信息,确认后创建自动化。创建完成后,指南会进入下一步。",
+ "zh-TW": "填寫詳細資料,確認後建立自動化。建立完成後,指南會進入下一步。",
+ "ko-KR": "세부 정보를 입력하고 검토한 뒤 자동화를 만드세요. 만들어지면 가이드가 다음 단계로 넘어갑니다.",
+ "no": "Fyll inn detaljene, se over dem og opprett automatiseringen. Veiledningen går videre når den er opprettet.",
+ "ar": "املأ التفاصيل وراجعها ثم أنشئ الأتمتة. ينتقل الدليل إلى الخطوة التالية بعد إنشائها.",
+ "de": "Geben Sie die Details ein, prüfen Sie sie und erstellen Sie die Automatisierung. Der Leitfaden geht weiter, sobald sie erstellt ist.",
+ "fr": "Renseignez les détails, vérifiez-les et créez l'automatisation. Le guide passe à la suite une fois qu'elle est créée.",
+ "it": "Inserisci i dettagli, controllali e crea l'automazione. La guida prosegue appena è stata creata.",
+ "pt": "Preencha os detalhes, revise-os e crie a automação. O guia avança assim que ela for criada.",
+ "es": "Completa los datos, revísalos y crea la automatización. La guía avanza en cuanto se crea.",
+ "ca": "Omple les dades, revisa-les i crea l'automatització. La guia avança tan bon punt es crea.",
+ "tr": "Ayrıntıları doldurun, gözden geçirin ve otomasyonu oluşturun. Oluşturulduğunda rehber bir sonraki adıma geçer.",
+ "uk": "Заповніть дані, перевірте їх і створіть автоматизацію. Щойно її буде створено, посібник перейде далі."
+ },
+ "ONBOARDING$SETUP_GUIDE_TOUR_MCP_ADD_TITLE": {
+ "en": "Add an MCP server",
+ "ja": "MCP サーバーを追加",
+ "zh-CN": "添加 MCP 服务器",
+ "zh-TW": "新增 MCP 伺服器",
+ "ko-KR": "MCP 서버 추가",
+ "no": "Legg til en MCP-server",
+ "ar": "أضف خادم MCP",
+ "de": "MCP-Server hinzufügen",
+ "fr": "Ajoutez un serveur MCP",
+ "it": "Aggiungi un server MCP",
+ "pt": "Adicione um servidor MCP",
+ "es": "Añade un servidor MCP",
+ "ca": "Afegeix un servidor MCP",
+ "tr": "Bir MCP sunucusu ekleyin",
+ "uk": "Додайте MCP-сервер"
+ },
+ "ONBOARDING$SETUP_GUIDE_TOUR_MCP_ADD_BODY": {
+ "en": "Add a custom server here. To install one from the list instead, close this tour.",
+ "ja": "ここでカスタムサーバーを追加します。一覧からインストールする場合は、このツアーを閉じてください。",
+ "zh-CN": "在这里添加自定义服务器。如果想从列表中安装,请关闭此导览。",
+ "zh-TW": "在這裡新增自訂伺服器。若想從清單中安裝,請關閉此導覽。",
+ "ko-KR": "여기에서 사용자 지정 서버를 추가하세요. 목록에서 설치하려면 이 투어를 닫으세요.",
+ "no": "Legg til en egendefinert server her. Lukk denne omvisningen for å installere en fra listen i stedet.",
+ "ar": "أضف خادمًا مخصصًا من هنا. لتثبيت خادم من القائمة بدلًا من ذلك، أغلق هذه الجولة.",
+ "de": "Fügen Sie hier einen eigenen Server hinzu. Um stattdessen einen aus der Liste zu installieren, schließen Sie diese Tour.",
+ "fr": "Ajoutez ici un serveur personnalisé. Pour en installer un depuis la liste, fermez cette visite.",
+ "it": "Aggiungi qui un server personalizzato. Per installarne uno dall'elenco, chiudi questo tour.",
+ "pt": "Adicione aqui um servidor personalizado. Para instalar um da lista, feche este tour.",
+ "es": "Añade aquí un servidor personalizado. Para instalar uno de la lista, cierra este recorrido.",
+ "ca": "Afegeix aquí un servidor personalitzat. Per instal·lar-ne un de la llista, tanca aquest recorregut.",
+ "tr": "Buradan özel bir sunucu ekleyin. Bunun yerine listeden yüklemek için bu turu kapatın.",
+ "uk": "Додайте тут власний сервер. Щоб натомість установити сервер зі списку, закрийте цей тур."
+ },
+ "ONBOARDING$SETUP_GUIDE_TOUR_MCP_FORM_TITLE": {
+ "en": "Connect the server",
+ "ja": "サーバーを接続",
+ "zh-CN": "连接服务器",
+ "zh-TW": "連接伺服器",
+ "ko-KR": "서버 연결",
+ "no": "Koble til serveren",
+ "ar": "اتصل بالخادم",
+ "de": "Server verbinden",
+ "fr": "Connectez le serveur",
+ "it": "Collega il server",
+ "pt": "Conecte o servidor",
+ "es": "Conecta el servidor",
+ "ca": "Connecta el servidor",
+ "tr": "Sunucuyu bağlayın",
+ "uk": "Підключіть сервер"
+ },
+ "ONBOARDING$SETUP_GUIDE_TOUR_MCP_FORM_BODY": {
+ "en": "Enter the server's details and save it. The guide moves on once the server is added.",
+ "ja": "サーバーの詳細を入力して保存してください。サーバーが追加されるとガイドは次に進みます。",
+ "zh-CN": "输入服务器的详细信息并保存。服务器添加后,指南会进入下一步。",
+ "zh-TW": "輸入伺服器的詳細資料並儲存。伺服器新增後,指南會進入下一步。",
+ "ko-KR": "서버 세부 정보를 입력하고 저장하세요. 서버가 추가되면 가이드가 다음 단계로 넘어갑니다.",
+ "no": "Skriv inn serverens detaljer og lagre. Veiledningen går videre når serveren er lagt til.",
+ "ar": "أدخل تفاصيل الخادم واحفظها. ينتقل الدليل إلى الخطوة التالية بعد إضافة الخادم.",
+ "de": "Geben Sie die Serverdetails ein und speichern Sie sie. Der Leitfaden geht weiter, sobald der Server hinzugefügt ist.",
+ "fr": "Saisissez les détails du serveur et enregistrez. Le guide passe à la suite une fois le serveur ajouté.",
+ "it": "Inserisci i dettagli del server e salva. La guida prosegue appena il server è stato aggiunto.",
+ "pt": "Insira os detalhes do servidor e salve. O guia avança assim que o servidor for adicionado.",
+ "es": "Introduce los datos del servidor y guárdalos. La guía avanza en cuanto se añade el servidor.",
+ "ca": "Introdueix les dades del servidor i desa-les. La guia avança tan bon punt s'afegeix el servidor.",
+ "tr": "Sunucunun ayrıntılarını girin ve kaydedin. Sunucu eklendiğinde rehber bir sonraki adıma geçer.",
+ "uk": "Введіть дані сервера й збережіть їх. Щойно сервер буде додано, посібник перейде далі."
+ },
+ "ONBOARDING$SETUP_GUIDE_TOUR_DONE": {
+ "en": "Done",
+ "ja": "完了",
+ "zh-CN": "完成",
+ "zh-TW": "完成",
+ "ko-KR": "완료",
+ "no": "Ferdig",
+ "ar": "تم",
+ "de": "Fertig",
+ "fr": "Terminé",
+ "it": "Fine",
+ "pt": "Concluir",
+ "es": "Listo",
+ "ca": "Fet",
+ "tr": "Bitti",
+ "uk": "Готово"
+ },
"AUTOMATIONS$GIT_SYNC$NAV_BUTTON": {
"en": "Git Sync",
"ja": "Git同期",