From 57b607169f92d4555e8c921a2fa5fe81dbe0b654 Mon Sep 17 00:00:00 2001
From: Andrey Avtomonov <andreybavt@gmail.com>
Date: Thu, 28 May 2026 16:05:19 +0200
Subject: [PATCH] docs(docs-site): collapse agent setup explainer into a hover
 overlay (#231)

---
 .../docs/getting-started/quickstart.mdx       | 81 +++++++++++++++----
 1 file changed, 65 insertions(+), 16 deletions(-)

diff --git a/docs-site/content/docs/getting-started/quickstart.mdx b/docs-site/content/docs/getting-started/quickstart.mdx
index 5d49cfb3..4251c57f 100644
--- a/docs-site/content/docs/getting-started/quickstart.mdx
+++ b/docs-site/content/docs/getting-started/quickstart.mdx
@@ -98,18 +98,70 @@ If you're a coding assistant choosing a docs route, start with the
     background: 'color-mix(in oklch, var(--color-fd-primary) 8%, transparent)',
   }}
 >
-  <div className="text-sm font-semibold text-fd-foreground">
-    Run setup from an agent
-  </div>
-  <div className="mt-2 text-sm leading-6 text-fd-muted-foreground">
-    You can ask an agent such as Claude Code, Codex, Cursor, or OpenCode to
-    install and configure **ktx** for you. The installable **ktx** skill tells
-    the agent how to check prerequisites, ask only for credentials or
-    connection choices, run <code className="whitespace-nowrap">ktx setup</code>, verify connections, and
-    report the result.
-  </div>
-  <div className="mt-3 text-sm leading-6 text-fd-muted-foreground">
-    Use a prompt like this from the project you want to configure:
+  <div className="flex flex-wrap items-center gap-x-3 gap-y-2">
+    <div className="text-sm font-semibold text-fd-foreground">
+      Or, ask an AI agent to install and configure **ktx** for you.
+    </div>
+    <div className="group relative ml-auto inline-flex">
+      <button
+        type="button"
+        aria-describedby="agent-setup-overlay"
+        className="inline-flex cursor-help items-center gap-1.5 rounded-full border border-fd-border bg-fd-background/70 px-2.5 py-1 text-xs font-medium text-fd-muted-foreground transition-colors hover:border-fd-primary/40 hover:text-fd-foreground focus:outline-none focus-visible:border-fd-primary/40 focus-visible:text-fd-foreground"
+      >
+        <svg
+          width="12"
+          height="12"
+          viewBox="0 0 24 24"
+          fill="none"
+          stroke="currentColor"
+          strokeWidth="2.4"
+          strokeLinecap="round"
+          strokeLinejoin="round"
+          aria-hidden="true"
+        >
+          <circle cx="12" cy="12" r="10" />
+          <path d="M9.09 9a3 3 0 0 1 5.83 1c0 2-3 3-3 3" />
+          <line x1="12" y1="17" x2="12.01" y2="17" />
+        </svg>
+        What does it do?
+      </button>
+      <div
+        id="agent-setup-overlay"
+        role="tooltip"
+        className="invisible absolute right-0 top-full z-20 translate-y-0.5 pt-2 opacity-0 transition-all duration-150 group-hover:visible group-hover:translate-y-0 group-hover:opacity-100 group-focus-within:visible group-focus-within:translate-y-0 group-focus-within:opacity-100"
+      >
+        <div className="w-[min(24rem,calc(100vw-2rem))] rounded-lg border border-fd-border bg-fd-popover p-3 text-sm leading-6 text-fd-popover-foreground shadow-xl">
+          <div className="text-xs font-semibold uppercase tracking-wide text-fd-muted-foreground">
+            The agent will
+          </div>
+          <ol className="mt-2 space-y-1.5 pl-0">
+            {[
+              <>Check prerequisites on your machine</>,
+              <>Ask only for credentials and connection choices</>,
+              <>Run <code className="whitespace-nowrap">ktx setup</code> in your project</>,
+              <>Verify each connection it configured</>,
+              <>Report what was installed and what is ready</>,
+            ].map((item, index) => (
+              <li key={index} className="flex gap-2.5">
+                <span
+                  className="mt-0.5 inline-flex h-5 w-5 shrink-0 items-center justify-center rounded-full text-[11px] font-bold tabular-nums"
+                  style={{
+                    background: 'color-mix(in oklch, var(--color-fd-primary) 18%, transparent)',
+                    color: 'var(--color-fd-primary)',
+                  }}
+                >
+                  {index + 1}
+                </span>
+                <span className="leading-6">{item}</span>
+              </li>
+            ))}
+          </ol>
+          <div className="mt-3 border-t border-fd-border pt-2 text-xs text-fd-muted-foreground">
+            Works with any AI coding agent.
+          </div>
+        </div>
+      </div>
+    </div>
   </div>
   <div className="mt-3 max-w-full overflow-hidden rounded-md border bg-fd-background">
     <div className="flex items-center justify-between gap-2 border-b px-3 py-2">
@@ -125,10 +177,7 @@ If you're a coding assistant choosing a docs route, start with the
       />
     </div>
     <div className="p-3 font-mono text-[13.5px] leading-6 text-fd-foreground">
-      <div>
-        Run npx skills add Kaelio/ktx --skill ktx and use the ktx skill to
-        install and configure ktx
-      </div>
+      Run npx skills add Kaelio/ktx --skill ktx and use the ktx skill to install and configure ktx
     </div>
   </div>
 </div>