sap-ai-dev-toolkit 0.8.2 → 0.8.4

package/README.md

@@ -33,7 +33,7 @@
 SAP AI Dev Toolkit connects your AI coding assistant to the SAP development tools available for each selected destination. Agents can inspect ABAP and CDS, propose changes, run checks, and return the evidence—without losing sight of which SAP system each operation targets.
 
 <p align="center">
-  <strong>Agent chat</strong> → <strong>destination-scoped MCP</strong> → <strong>VSP + BAS destination</strong> → <strong>SAP ADT</strong> → <strong>your SAP system</strong><br>
+  <strong>Agent chat</strong> → <strong>destination-scoped MCP</strong> → <strong>VSP + configured route (BAS, CF, or local SAP GUI)</strong> → <strong>SAP ADT</strong> → <strong>your SAP system</strong><br>
   <em>results and diagnostics flow back along the same path</em>
 </p>
 
@@ -52,7 +52,7 @@ To also add optional full-stack SAP companion MCP servers for Fiori, UI5, CAP, a
 sap-ai-dev --setup --tools
 ```
 
-Then connect a destination in SAP Business Application Studio, or run the same setup locally to discover SAP GUI systems and create VS Code MCP entries:
+After setup, connect a selected BAS destination or local SAP GUI system from your MCP-capable editor:
 
 1. Open the Command Palette.
 2. Run **MCP: List Servers**.
@@ -79,11 +79,11 @@ Use the attached destination-prefixed tools directly in chat. Do not launch `sap
 
 **Included skills:** `abap-development` · `abap-testing-quality` · `cds-development` · `rap-development` · `abap-debugging` · `abap-runtime-analysis` · `rap-service-delivery` · `sap-standard-api-analysis` · `clean-core-extensibility` · `sap-sdlc-orchestration` · `sap-transport-release` · `hana-cloud-inspection` · `hana-cloud-native-development` · `hana-cloud-validation`
 
-Agents and skills install for the harnesses you pick during global installation: a multi-select offers GitHub Copilot and Claude Code pre-checked, plus OpenAI Codex, Cursor, Gemini CLI, opencode, and Pi Coding Agent. In non-interactive installs they are installed for GitHub Copilot only. Repository-scoped installation instructions appear below.
+Agents and skills install for the harnesses you pick during global installation: a multi-select offers GitHub Copilot and Claude Code pre-checked, plus OpenAI Codex, Cursor, Gemini CLI, opencode, and Pi Coding Agent. In non-interactive installs they are installed for GitHub Copilot only; run `sap-ai-dev --setup` afterwards to configure destinations or local SAP GUI systems. Repository-scoped installation instructions appear below.
 
 ## ✨ Your SAP development cockpit, inside your AI assistant
 
-`sap-ai-dev-toolkit` installs `sap-ai-dev`, discovers your BAS destinations, and exposes a curated SAP development toolset through MCP. Instead of manually switching between chat, terminal commands, repository searches, ADT screens, and SAP checks, describe the outcome you want and let the appropriate bundled agent coordinate the available tools.
+`sap-ai-dev-toolkit` installs `sap-ai-dev`, discovers your BAS destinations or local SAP GUI systems, and exposes a curated SAP development toolset through MCP. Instead of manually switching between chat, terminal commands, repository searches, ADT screens, and SAP checks, describe the outcome you want and let the appropriate bundled agent coordinate the available tools.
 
 <p align="center"><strong>💬 Request → 🔎 Inspect → 🧠 Reason → 🧑‍💻 Implement → 🧪 Verify → 📋 Report</strong></p>
 
@@ -94,7 +94,7 @@ The workflow covers ABAP, CDS, RAP, repository analysis, table and query access,
 | | Feature | What it gives you |
 | --- | --- | --- |
 | 🤖 | **AI-driven ABAP development** | Describe the outcome; a task-fit agent coordinates inspection, implementation, validation, and a clear report. |
-| 🧭 | **Destination-aware by design** | Discover BAS destinations and connect each MCP server to one selected SAP system. |
+| 🧭 | **Destination-aware by design** | Discover BAS destinations or local SAP GUI systems and connect each MCP server to one selected SAP system. |
 | 🔎 | **Understand before editing** | Trace source, callers, definitions, package contents, dependencies, and CDS impact in one workflow. |
 | 🧩 | **CDS + RAP development** | Explore models and dependencies, then build RAP business objects and services with system context. |
 | 🗃️ | **Ground decisions in SAP data** | Inspect DDIC structures, read table contents, and run controlled ABAP SQL queries. |
@@ -278,7 +278,7 @@ The installer handles VSP provisioning automatically:
 
 Setup detects where it is running. With `H2O_URL` set, it treats the environment as SAP Business Application Studio and opens a checkbox picker for BAS destinations, with no destinations selected by default. Use **Space** to choose destinations and **Enter** to confirm. Press **a** to toggle all destinations (select all if any are unchecked; otherwise clear the selection). Confirming with none selected removes this add-on's managed MCP entries. When the `cf` CLI 8.18 or newer is authenticated to a targeted space, setup first offers an optional import from that space's Destination service; type **y** then **Enter** to include it, or press **Enter** to skip. Accepted CF and BAS destinations appear together in the picker.
 
-Without `H2O_URL`, interactive setup looks for local SAP GUI system configuration on macOS and Windows (for example SAP GUI landscape XML and `saplogon.ini`). SAP GUI landscape files describe SAP GUI/DIAG connectivity, not the ADT HTTP(S) endpoint or a complete ABAP client catalog, so setup asks for the SAP client or comma-separated clients to configure for each selected system (for example `100,200`), proposes an ADT URL from the SAP GUI host and instance when it can, and asks you to confirm or edit that value. Multiple entered clients create separate isolated MCP entries, one per system/client pair. When the ADT URL uses an IP address, setup automatically inspects the SAP HTTPS certificate, extracts DNS subjectAltName entries, and offers to enable secure TLS self-healing with a simple yes/no confirmation; you do not need to type certificate names. The generated MCP entry uses VS Code input prompts for the SAP user and password at server start; raw SAP credentials are not stored in `mcp.json`. On Windows, setup can instead write an experimental `SAP_AUTH_MODE=windows-sso` entry without username/password prompts; this requires the ADT endpoint to support HTTP Negotiate/SPNEGO. Runtime uses the bundled Windows Negotiate helper by default, or a trusted custom helper configured with `SAP_AI_DEV_TOOLKIT_NEGOTIATE_HELPER`. npm may run its install hook without an interactive terminal, even when the shell is interactive; in that case, destination selection is skipped without changing MCP config, and you should run `sap-ai-dev --setup` afterwards.
+Without `H2O_URL`, interactive setup looks for local SAP GUI system configuration on macOS and Windows (for example SAP GUI landscape XML and `saplogon.ini`). SAP GUI landscape files describe SAP GUI/DIAG connectivity, not the ADT HTTP(S) endpoint or a complete ABAP client catalog, so setup asks for the SAP client or comma-separated clients to configure for each selected system (for example `100,200`), proposes an ADT URL from the SAP GUI host and instance when it can, and asks you to confirm or edit that value. Multiple entered clients create separate isolated MCP entries, one per system/client pair. Local SAP GUI MCP server keys use the SAP system ID and client (for example `t4d-100`) instead of the longer SAP GUI description, while `SAP_AI_DEV_TOOLKIT_DESTINATION` still preserves the display name. When the ADT URL uses an IP address, setup automatically inspects the SAP HTTPS certificate, extracts DNS subjectAltName entries, and offers to enable secure TLS self-healing with a simple yes/no confirmation; you do not need to type certificate names. The generated MCP entry uses VS Code input prompts for the SAP user and password at server start; raw SAP credentials are not stored in `mcp.json`. On Windows, setup can instead write an experimental `SAP_AUTH_MODE=windows-sso` entry without username/password prompts; this requires the ADT endpoint to support HTTP Negotiate/SPNEGO. Runtime uses the bundled Windows Negotiate helper by default, or a trusted custom helper configured with `SAP_AI_DEV_TOOLKIT_NEGOTIATE_HELPER`. npm may run its install hook without an interactive terminal, even when the shell is interactive; in that case, destination selection is skipped without changing MCP config, and you should run `sap-ai-dev --setup` afterwards.
 
 ### 🖥️ Local machine SAP GUI support
 
@@ -290,7 +290,7 @@ Supported discovery and runtime behavior:
 - **Client selection:** SAP GUI entries may contain one default client but cannot reliably list every ABAP client available through ADT. Setup asks for one or more 3-digit clients per selected system; enter comma-separated values such as `100,200` to create separate MCP servers for each client.
 - **ADT endpoint derivation:** SAP GUI entries usually contain DIAG/router information, not the HTTP(S) ADT endpoint. Setup derives the common ADT port from the SAP instance when possible, for example instance `00` → `https://host:44300`, and asks for confirmation only when configuring the selected entry.
 - **Credential handling:** username/password local entries use VS Code MCP input prompts (`${input:...}`) at server start. Plain SAP credentials are not written to `mcp.json`.
-- **Windows SSO:** local Windows entries can use `SAP_AUTH_MODE=windows-sso` instead of username/password prompts when the ABAP ADT endpoint supports HTTP Negotiate/SPNEGO. The runtime starts a loopback ADT proxy and uses the bundled Windows SSPI helper unless `SAP_AI_DEV_TOOLKIT_NEGOTIATE_HELPER` points to a trusted custom helper. NTLM fallback is rejected.
+- **Windows SSO / smart-card Windows logon:** local Windows entries can use `SAP_AUTH_MODE=windows-sso` instead of username/password prompts when the ABAP ADT endpoint supports HTTP Negotiate/SPNEGO. The runtime starts a loopback ADT proxy and uses the bundled Windows SSPI helper with the current Windows logon session, including smart-card-backed Windows logon. The toolkit does not prompt for, store, or accept manually pasted bearer/SAML tokens. Use `SAP_AI_DEV_TOOLKIT_NEGOTIATE_HELPER` only to point to a trusted custom SSPI/Negotiate helper. NTLM fallback is rejected.
 - **IP-address HTTPS self-healing:** if the confirmed ADT URL is `https://<ip>:<port>` and the certificate is issued to DNS names, setup reads the certificate DNS SANs automatically and stores them as `SAP_TLS_SERVER_NAMES`. At runtime a loopback proxy dials the IP address but verifies TLS against those discovered DNS names, trying them one by one. Certificate verification stays enabled; there is no `--insecure` mode.
 - **Private CAs:** if the SAP HTTPS certificate chains to an internal CA that is not trusted by the local Node runtime, set `SAP_TLS_CA_FILE` or `SAP_AI_DEV_TOOLKIT_TLS_CA_FILE` to a PEM CA bundle. This adds trust roots for the self-healing proxy without disabling certificate validation.
 - **Redirect and request safety:** local loopback proxies reject cross-origin forward-form requests and rewrite same-origin SAP redirects back through the loopback listener, so VSP stays on the safe route.
@@ -308,9 +308,9 @@ sap-ai-dev --setup
 5. Choose password or Windows SSO when the prompt is available.
 6. Start each generated MCP server from VS Code's **MCP: List Servers** command.
 
-The same postinstall offers the bundled agents and skills for several AI coding harnesses in a checkbox picker. **GitHub Copilot** and **Claude Code** start pre-checked, so pressing **Enter** alone installs both; **Space** selects or deselects a harness, **a** toggles all seven, and confirming with none selected skips the step without changing files. When destination MCP setup succeeds, the generated managed MCP servers are also mirrored into selected harnesses that have a stable user-level JSON MCP configuration (Claude Code, Cursor, Gemini CLI, and Pi Coding Agent). GitHub Copilot continues to use the BAS/VS Code MCP configuration written during destination setup. With no interactive terminal, the assets are installed for GitHub Copilot only; set `SAP_AI_DEV_TOOLKIT_HARNESSES` to a comma-separated list of harness ids (`github-copilot`, `claude-code`, `codex`, `cursor`, `gemini-cli`, `opencode`, `pi-coding-agent`) to choose non-interactively.
+The same postinstall offers the bundled agents and skills for several AI coding harnesses in a checkbox picker. **GitHub Copilot** and **Claude Code** start pre-checked, so pressing **Enter** alone installs both; **Space** selects or deselects a harness, **a** toggles all seven, and confirming with none selected skips the step without changing files. When MCP setup succeeds, the generated managed MCP servers are also mirrored into selected harnesses that have a stable user-level JSON MCP configuration (Claude Code, Cursor, Gemini CLI, and Pi Coding Agent). GitHub Copilot continues to use the VS Code/BAS MCP configuration written during setup. With no interactive terminal, the assets are installed for GitHub Copilot only; set `SAP_AI_DEV_TOOLKIT_HARNESSES` to a comma-separated list of harness ids (`github-copilot`, `claude-code`, `codex`, `cursor`, `gemini-cli`, `opencode`, `pi-coding-agent`) to choose non-interactively.
 
-Some current npm versions also require install hooks to be approved. If npm reports that `sap-ai-dev-toolkit`'s `postinstall` was blocked, allow it during a fresh install with `npm install --global --allow-scripts=sap-ai-dev-toolkit sap-ai-dev-toolkit`, or run `sap-ai-dev --setup` from an interactive BAS terminal after installation.
+Some current npm versions also require install hooks to be approved. If npm reports that `sap-ai-dev-toolkit`'s `postinstall` was blocked, allow it during a fresh install with `npm install --global --allow-scripts=sap-ai-dev-toolkit sap-ai-dev-toolkit`, or run `sap-ai-dev --setup` from an interactive terminal after installation.
 
 The setup report uses icons and terminal colors; set `NO_COLOR=1` to disable ANSI colors. The table is a weather report, not a bouncer: green **PASS** means the ADT probe responded, red **FAIL** means it failed, and yellow **SKIPPED** means it was skipped. Probe failures do not block MCP registration or startup for destinations you select.
 
@@ -379,13 +379,13 @@ The package includes five user-invocable custom agents (**SAP Solution Architect
 | 🧱 | `hana-cloud-native-development` | Create CAP CDS or required native HDI source artifacts while avoiding duplicate models. |
 | ✅ | `hana-cloud-validation` | Build locally, review deployment risks, and hand off deployment to the user. |
 
-### 📥 Install for your BAS user
+### 📥 Install agents and skills for your user
 
-After destination setup, the installer prints a 🤖 notice and a checkbox picker asking which AI coding harnesses should receive the bundled agents and skills. **Space** selects or deselects, **a** toggles all, **Enter** confirms. **GitHub Copilot** and **Claude Code** are pre-checked, so pressing **Enter** without changes installs both; confirming with none selected skips the step and leaves your files unchanged.
+During npm postinstall, after the destination or local SAP GUI setup step, the installer prints a 🤖 notice and a checkbox picker asking which AI coding harnesses should receive the bundled agents and skills. **Space** selects or deselects, **a** toggles all, **Enter** confirms. **GitHub Copilot** and **Claude Code** are pre-checked, so pressing **Enter** without changes installs both; confirming with none selected skips the step and leaves your files unchanged.
 
 | Harness | Skills land in | Agents land in | MCP auto-wiring |
 | --- | --- | --- | --- |
-| GitHub Copilot | `$HOME/.copilot/skills/` | `$HOME/.copilot/agents/*.agent.md` | Uses the BAS/VS Code `mcp.json` written by destination setup |
+| GitHub Copilot | `$HOME/.copilot/skills/` | `$HOME/.copilot/agents/*.agent.md` | Uses the VS Code/BAS `mcp.json` written by setup |
 | Claude Code | `$HOME/.claude/skills/` | `$HOME/.claude/agents/<id>.md` (frontmatter reduced to `name` and `description`) | `$HOME/.claude.json` |
 | OpenAI Codex | `$HOME/.agents/skills/` | — | Not changed automatically |
 | Cursor | `$HOME/.cursor/skills/` | — | `$HOME/.cursor/mcp.json` |
@@ -397,13 +397,13 @@ All 14 skills use the portable `SKILL.md` format and are installed verbatim. The
 
 MCP auto-wiring preserves unrelated servers in each harness config and replaces only entries previously managed by `sap-ai-dev-toolkit`. Generated entries carry `SAP_AI_DEV_TOOLKIT_MANAGED=true` in their server environment so future reinstalls can reconcile them without touching user-owned MCP servers.
 
-These user-level customizations are available across workspaces opened by the same BAS user in the same dev space. The harness must be available in BAS and may need a window reload to discover new files. A non-interactive install skips the picker and installs for GitHub Copilot only; override with `SAP_AI_DEV_TOOLKIT_HARNESSES` (comma-separated harness ids). `npm install --ignore-scripts` skips the postinstall wizard entirely.
+These user-level customizations are available across workspaces opened by the same OS user (or the same BAS user in a dev space). The harness may need a window reload to discover new files. A non-interactive install skips the picker and installs for GitHub Copilot only; override with `SAP_AI_DEV_TOOLKIT_HARNESSES` (comma-separated harness ids). `npm install --ignore-scripts` skips the postinstall wizard entirely.
 
 On reinstall or package upgrade, unchanged add-on-managed files are updated per harness. Existing customizations and files edited since the previous install are preserved; postinstall reports paths that need manual review instead of overwriting them.
 
 ### 🗂️ Add the agents and skills to a repository
 
-To commit repository-scoped customizations, copy the packaged files from the BAS workspace root without overwriting existing files:
+To commit repository-scoped customizations, copy the packaged files from the installed package without overwriting existing files:
 
 ```sh
 ADDON_ROOT="$(npm root -g)/sap-ai-dev-toolkit"
@@ -423,7 +423,7 @@ Review skipped or conflicting files and merge changes manually. `LintABAP` analy
 If the `cf` CLI is version 8.18 or newer and authenticated to a targeted space, setup offers an opt-in import from that space's SAP Destination service. It does not create service keys unless you accept. The imported records are limited to the current space and are merged with BAS destinations for selection. OnPremise destinations require choosing a Connectivity service instance; runtime traffic uses that service's proxy, and PrincipalPropagation uses the current CF user's token. Internet destinations use the configured HTTP(S) proxy environment. Setup stores only service-instance/key references in `mcp.json`, not the service-key credentials. At runtime the generated entry verifies the active CF space and resolves those references. Setup removes an add-on-created key only when no remaining CF entry references it and the CLI is targeted to the key's recorded space; keys are left untouched when the space cannot be verified.
 Cloud Foundry HTTP destination probes use forward-form HTTP requests, not CONNECT tunnels; SAP Connectivity requires HTTP from the application to its proxy. OnPremise requests are canceled when the client disconnects or the runtime route closes.
 
-Interactive npm install and `sap-ai-dev --setup` both use a checkbox picker with no destinations selected by default. Use **Space** to choose destinations, **Enter** to confirm, and **a** to toggle all (select all if any are unchecked; otherwise clear the selection). Confirming with none checked removes this package's generated MCP entries. Non-interactive installs skip destination selection without changing MCP config. Run the interactive setup command above; add `--npx` when the package is not installed globally.
+Interactive npm install and `sap-ai-dev --setup` both use a checkbox picker with no destinations selected by default. Use **Space** to choose destinations, **Enter** to confirm, and **a** to toggle all (select all if any are unchecked; otherwise clear the selection). Confirming with none checked removes this package's generated MCP entries. Non-interactive installs skip destination or local SAP GUI system selection without changing MCP config. Run the interactive setup command above; add `--npx` when the package is not installed globally.
 
 Setup tidies its own footprint: it reconciles MCP entries managed by this package and removes legacy `sapAiDev_*` / `basVspMcp_*` entries from earlier releases. Existing unrelated MCP servers and top-level configuration such as `inputs` stay untouched.
 
@@ -528,9 +528,9 @@ The file must be strict JSON with an object-valued `servers` property. Existing
 
 With `H2O_URL` set, the normal command starts the MCP proxy. Each generated entry supplies one `SAP_AI_DEV_TOOLKIT_DESTINATION`, so each server stays in its own lane and exposes only its selected SAP system.
 
-The proxy exposes a curated subset of VSP tools, plus local `LintABAP`, destination-scoped workflow tools, and the convenience `GetApplicationLog` mapping when the VSP SAP router is available. Hidden VSP tools remain available only behind local workflow chaining where required; they are not advertised or directly callable through the proxy. Direct VSP invocation remains unchanged.
+The proxy exposes a curated subset of VSP tools, plus local `LintABAP`, destination-scoped workflow tools, and the convenience `GetApplicationLog` mapping when the VSP SAP router is available. Hidden VSP tools remain available only behind local workflow chaining where required; they are not advertised or directly callable through the proxy. Direct VSP invocation remains available outside BAS when you pass an explicit VSP argument.
 
-Without `H2O_URL`, the command passes arguments directly to the installed VSP binary—no BAS proxy detour.
+Without `H2O_URL`, generated local SAP GUI entries start a destination-scoped local MCP server. In an interactive local terminal with no arguments, `sap-ai-dev` starts local setup. Other non-setup arguments are passed directly to the installed VSP binary—no BAS proxy detour.
 
 ### 🔄 How an MCP tool call reaches SAP
 
@@ -684,7 +684,7 @@ The proxy starts VSP with `--enable-transports` and omits `--transport-read-only
 - `messages: true` adds BALDAT details and T100 message text; otherwise, the tool returns log headers only.
 - The proxy maps this convenience tool to the single upstream `SAP(action="analyze", type="application_log")` operation. The general-purpose `SAP` router itself is hidden from direct calls.
 
-The proxy intentionally does not expose the full child VSP process. Object deletion, broad trace surfaces, arbitrary SAP router/RFC calls, debugger helper/delete-breakpoint routes, and transport release/delete tools are hidden from direct MCP calls. The curated debugger tools (`SetBreakpoint`, `GetBreakpoints`, `DebuggerAttach`, `DebuggerGetStack`, `DebuggerGetVariables`, `DebuggerStep`, and `DebuggerDetach`) remain available when VSP and the target system expose them. Direct VSP invocation without `H2O_URL` retains the VSP binary's own tool surface.
+The proxy intentionally does not expose the full child VSP process. Object deletion, broad trace surfaces, arbitrary SAP router/RFC calls, debugger helper/delete-breakpoint routes, and transport release/delete tools are hidden from direct MCP calls. The curated debugger tools (`SetBreakpoint`, `GetBreakpoints`, `DebuggerAttach`, `DebuggerGetStack`, `DebuggerGetVariables`, `DebuggerStep`, and `DebuggerDetach`) remain available when VSP and the target system expose them. Direct VSP invocation without `H2O_URL` retains the VSP binary's own tool surface; in an interactive local terminal, use an explicit VSP argument because plain `sap-ai-dev` starts local setup.
 
 ### 🚀 Ready to put the tools to work from chat?
 
@@ -738,9 +738,9 @@ The MCP client discovers the schemas; callers do not need to memorize every argu
 | What to inspect | How |
 | --- | --- |
 | Add-on command options | `sap-ai-dev --help` |
-| BAS destinations and probe status | `sap-ai-dev --list-destinations --json` |
+| BAS destinations and probe status | `sap-ai-dev --list-destinations --json` (BAS only) |
 | Destination availability only | `sap-ai-dev --check` |
-| Generated server names and destination mapping | **MCP: Open User Configuration**; look for lowercase slug entries (for example `demo-abap`) whose `SAP_AI_DEV_TOOLKIT_DESTINATION` names the BAS destination. |
+| Generated server names and destination mapping | **MCP: Open User Configuration**; look for lowercase slug entries (for BAS, for example `demo-abap`; for local SAP GUI, system/client slugs such as `t4d-100`) whose `SAP_AI_DEV_TOOLKIT_DESTINATION` names the BAS destination or local SAP GUI system. |
 | Running server | **MCP: List Servers**; select the server and choose **Start Server**. |
 | Tools and exact schemas | Expand that server in the Chat tools picker. The MCP host requests `tools/list`, whose entries include `name`, `description`, and `inputSchema`; the agent should call those tools through chat, not reproduce the protocol in a terminal. |
 | Runtime and tool-call logs | Select the MCP server in the Output view. Startup, call lifecycle, and child stderr logs are written to stderr; child MCP log notifications are forwarded to the client. Tool arguments and result contents are not logged. |
@@ -782,11 +782,11 @@ The response contains a `tools` array. A `RunQuery` entry resembles this excerpt
 | `SAP_AI_DEV_TOOLKIT_DESTINATION` | Comma-separated destination allowlist for normal runtime discovery. Setup clears this temporarily so it can display all eligible systems. |
 | `SAP_AI_DEV_TOOLKIT_MODE` | VSP child mode (`expert` by default; `focused` omits `ActivateMultiple`, `GetUserTransports`, and `GetTransportInfo`). The proxy exposes its curated tool subset and local workflow tools, including `LintABAP`. |
 | `SAP_ALLOW_TRANSPORTABLE_EDITS` | Generated MCP entries set this to `true` to permit source edits in transportable packages; VSP safety checks and SAP authorizations still apply. |
-| `SAP_AUTH_MODE=windows-sso` | Local SAP GUI entry mode for experimental Windows Integrated Authentication. Runtime starts a loopback ADT proxy and does not pass SAP username/password credentials to VSP. |
+| `SAP_AUTH_MODE=windows-sso` | Local SAP GUI entry mode for experimental Windows Integrated Authentication over HTTP Negotiate/SPNEGO. Runtime starts a loopback ADT proxy, uses the current Windows logon session (including smart-card-backed Windows logon), and does not pass SAP username/password credentials or manual bearer/SAML tokens to VSP. |
 | `SAP_TLS_SERVER_NAMES` / `SAP_AI_DEV_TOOLKIT_TLS_SERVER_NAMES` | Comma-separated local SAP GUI TLS self-healing names, normally auto-discovered during setup from the SAP HTTPS certificate when `SAP_URL` uses an IP address. Runtime tries them one by one while keeping certificate validation enabled. |
 | `SAP_TLS_SERVER_NAME` / `SAP_AI_DEV_TOOLKIT_TLS_SERVER_NAME` | Single-name compatibility form of the local SAP GUI TLS self-healing override. Prefer the auto-discovered plural variable written by setup. |
 | `SAP_TLS_CA_FILE` / `SAP_AI_DEV_TOOLKIT_TLS_CA_FILE` | Optional PEM CA bundle for the local TLS self-healing proxy when the SAP HTTPS certificate chains to a private CA that is not in the OS/Node trust store. Certificate verification remains enabled. |
-| `SAP_AI_DEV_TOOLKIT_NEGOTIATE_HELPER` / `SAP_AI_DEV_TOOLKIT_SSPI_HELPER` | Optional trusted Windows helper executable used by the local Windows SSO proxy to convert an HTTP `WWW-Authenticate: Negotiate` challenge into a Kerberos/SPNEGO token. NTLM fallback is rejected because it is connection-oriented and unsafe for this proxy shape. When unset on Windows, the bundled PowerShell SSPI helper is used. A custom helper receives one JSON line on stdin (`url`, `challenge`, `mechanism`) and prints the base64 token on stdout. |
+| `SAP_AI_DEV_TOOLKIT_NEGOTIATE_HELPER` / `SAP_AI_DEV_TOOLKIT_SSPI_HELPER` | Optional trusted Windows helper executable used by the local Windows SSO proxy to answer an HTTP `WWW-Authenticate: Negotiate` challenge with the current Windows SSPI/Kerberos/SPNEGO credentials. It is not a prompt for a user-entered token; the helper must obtain credentials from Windows. NTLM fallback is rejected because it is connection-oriented and unsafe for this proxy shape. When unset on Windows, the bundled PowerShell SSPI helper is used. A custom helper receives one JSON line on stdin (`url`, `challenge`, `mechanism`) and prints the base64 Negotiate response on stdout. |
 | `SAP_AI_DEV_TOOLKIT_HTTP_PROXY` | Egress proxy for BAS discovery and probe traffic. Takes precedence over `HTTP_PROXY`/`http_proxy`; unset means the default BAS proxy for `.dest` hosts, empty means direct. |
 | `SAP_AI_DEV_TOOLKIT_REQUEST_TIMEOUT_MS` | Per-request timeout for calls forwarded to a VSP child (default 600000 = 10 minutes; `0` disables). A stalled request fails with a timeout error; the child is left running. |
 | `SAP_AI_DEV_MCP_CONFIG` | Explicit MCP configuration path; highest precedence. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sap-ai-dev-toolkit",
-  "version": "0.8.2",
+  "version": "0.8.4",
   "description": "SAP AI development toolkit for BAS, ABAP, RAP, CAP, HANA Cloud, Fiori, UI5, and MCP",
   "author": "Gurkan Yilmaz",
   "type": "module",

package/src/launcher.mjs

@@ -195,6 +195,7 @@ async function configuredLocalSapGuiDestination(env) {
       url: route.url,
       backendUrl: env.SAP_URL,
       client: env.SAP_CLIENT || '001',
+      systemId: env.SAP_SYSTEM_ID || '',
       authentication: 'WindowsSSO',
       childEnv: {},
       close: () => closeRoute(route),
@@ -207,6 +208,7 @@ async function configuredLocalSapGuiDestination(env) {
     url: adtUrl,
     backendUrl: tlsRoute ? env.SAP_URL : undefined,
     client: env.SAP_CLIENT || '001',
+    systemId: env.SAP_SYSTEM_ID || '',
     authentication: 'Basic',
     childEnv: {
       SAP_USER: env.SAP_USER || env.SAP_USERNAME || '',

package/src/local-sap-gui.mjs

@@ -1,7 +1,12 @@
 import { platform, homedir } from 'node:os';
-import { join } from 'node:path';
+import { promisify } from 'node:util';
+import { execFile } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { basename, dirname, extname, join } from 'node:path';
 import { readdir, readFile, stat } from 'node:fs/promises';
 
+const execFileAsync = promisify(execFile);
+
 function text(value) { return value == null ? '' : String(value).trim(); }
 function decodeXml(value) {
   return text(value)
@@ -18,25 +23,88 @@ async function exists(path) {
 }
 
 function unique(values) {
-  return [...new Set(values.filter(Boolean))];
+  const seen = new Set();
+  return values.map(pathFromEnv).filter(Boolean).filter(value => {
+    const key = String(value).toLowerCase();
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+
+function pathFromEnv(value) {
+  const candidate = text(value);
+  if (!candidate) return '';
+  if (/^file:\/\//i.test(candidate)) {
+    try { return fileURLToPath(candidate); } catch { return candidate.replace(/^file:\/\/\/?/i, ''); }
+  }
+  return candidate;
+}
+
+const WINDOWS_LANDSCAPE_FILES = [
+  'SAPUILandscape.xml',
+  'SAPUILandscapeGlobal.xml',
+  'SAPGUILandscape.xml',
+  'SAPGUILandscapeGlobal.xml',
+  'SAPLogonTree.xml',
+  'SAPLogonTreeGlobal.xml',
+  'saplogon.ini'
+];
+
+const WINDOWS_EXPLICIT_PATH_ENV = [
+  'SAP_AI_DEV_SAP_GUI_LANDSCAPE',
+  'SAP_AI_DEV_SAP_GUI_CONFIG',
+  'SAPUILANDSCAPE',
+  'SAPGUI_LANDSCAPE',
+  'SAPLOGON_LSXML_FILE',
+  'SAPLOGON_INI_FILE'
+];
+
+function addWindowsSapGuiFiles(candidates, directory) {
+  if (!directory) return;
+  for (const name of WINDOWS_LANDSCAPE_FILES) candidates.push(join(directory, name));
+}
+
+function addSapGuiJavaFiles(candidates, directory) {
+  if (!directory) return;
+  candidates.push(join(directory, 'connections'));
+  addWindowsSapGuiFiles(candidates, directory);
 }
 
 export function sapGuiLandscapeCandidates(env = process.env) {
   const home = env.HOME || env.USERPROFILE || homedir();
-  const appData = env.APPDATA || (env.USERPROFILE ? join(env.USERPROFILE, 'AppData', 'Roaming') : '');
-  const candidates = [];
-  if (platform() === 'win32' || appData) {
+  const userProfile = env.USERPROFILE || home;
+  const appData = env.APPDATA || (userProfile ? join(userProfile, 'AppData', 'Roaming') : '');
+  const localAppData = env.LOCALAPPDATA || (userProfile ? join(userProfile, 'AppData', 'Local') : '');
+  const programData = env.PROGRAMDATA || (platform() === 'win32' ? 'C:\\ProgramData' : '');
+  const publicProfile = env.PUBLIC || (platform() === 'win32' ? 'C:\\Users\\Public' : '');
+  const windir = env.WINDIR || env.SystemRoot || (platform() === 'win32' ? 'C:\\Windows' : '');
+  const candidates = WINDOWS_EXPLICIT_PATH_ENV.map(name => env[name]);
+  if (platform() === 'win32' || appData || localAppData || programData) {
+    for (const base of [appData, localAppData, programData, publicProfile]) {
+      if (!base) continue;
+      addWindowsSapGuiFiles(candidates, join(base, 'SAP', 'Common'));
+      addWindowsSapGuiFiles(candidates, join(base, 'SAP'));
+    }
     candidates.push(
-      join(appData || '', 'SAP', 'Common', 'SAPUILandscape.xml'),
-      join(appData || '', 'SAP', 'Common', 'SAPUILandscapeGlobal.xml'),
-      join(appData || '', 'SAP', 'Common', 'saplogon.ini')
+      join(windir || '', 'saplogon.ini'),
+      join(windir || '', 'SAPLogon.ini'),
+      join(userProfile || '', 'saplogon.ini'),
+      join(userProfile || '', 'SAPLogon.ini')
     );
+    addSapGuiJavaFiles(candidates, join(userProfile || '', '.SAPGUI'));
+    addSapGuiJavaFiles(candidates, join(appData || '', 'SAPGUI'));
+    addSapGuiJavaFiles(candidates, join(localAppData || '', 'SAPGUI'));
+    if (env.ProgramFiles) addWindowsSapGuiFiles(candidates, join(env.ProgramFiles, 'SAP', 'FrontEnd', 'SAPgui'));
+    if (env['ProgramFiles(x86)']) addWindowsSapGuiFiles(candidates, join(env['ProgramFiles(x86)'], 'SAP', 'FrontEnd', 'SAPgui'));
   }
   candidates.push(
     join(home, 'Library', 'Preferences', 'SAP', 'SAPGUILandscape.xml'),
     join(home, 'Library', 'Preferences', 'SAP', 'SAPUILandscape.xml'),
     join(home, 'Library', 'Preferences', 'SAP', 'connections'),
-    join(home, '.SAPGUI', 'SAPGUILandscape.xml')
+    join(home, '.SAPGUI', 'SAPGUILandscape.xml'),
+    join(home, '.SAPGUI', 'SAPUILandscape.xml'),
+    join(home, '.SAPGUI', 'connections')
   );
   return unique(candidates);
 }
@@ -162,6 +230,113 @@ async function readGuiFile(path) {
   return bytes.toString('utf8').replace(/^\uFEFF/, '');
 }
 
+function sapGuiSearchRoots(env = process.env) {
+  const home = env.HOME || env.USERPROFILE || homedir();
+  const userProfile = env.USERPROFILE || home;
+  return unique([
+    env.APPDATA && join(env.APPDATA, 'SAP'),
+    env.APPDATA && join(env.APPDATA, 'SAPGUI'),
+    userProfile && join(userProfile, 'AppData', 'Roaming', 'SAP'),
+    userProfile && join(userProfile, 'AppData', 'Roaming', 'SAPGUI'),
+    env.LOCALAPPDATA && join(env.LOCALAPPDATA, 'SAP'),
+    env.LOCALAPPDATA && join(env.LOCALAPPDATA, 'SAPGUI'),
+    userProfile && join(userProfile, 'AppData', 'Local', 'SAP'),
+    userProfile && join(userProfile, 'AppData', 'Local', 'SAPGUI'),
+    env.PROGRAMDATA && join(env.PROGRAMDATA, 'SAP'),
+    env.PUBLIC && join(env.PUBLIC, 'SAP'),
+    userProfile && join(userProfile, '.SAPGUI'),
+    home && join(home, 'Library', 'Preferences', 'SAP'),
+    home && join(home, '.SAPGUI')
+  ]);
+}
+
+async function findSapGuiFilesUnder(root, { maxDepth = 4, maxEntries = 500 } = {}) {
+  const wanted = new Set(WINDOWS_LANDSCAPE_FILES.map(value => value.toLowerCase()).concat(['connections']));
+  const found = [];
+  let visited = 0;
+  async function walk(directory, depth) {
+    if (depth < 0 || visited >= maxEntries) return;
+    let entries;
+    try { entries = await readdir(directory, { withFileTypes: true }); } catch { return; }
+    for (const entry of entries) {
+      if (++visited > maxEntries) return;
+      const child = join(directory, entry.name);
+      if (entry.isFile() && wanted.has(basename(entry.name).toLowerCase())) found.push(child);
+      else if (entry.isDirectory()) {
+        if (basename(entry.name).toLowerCase() === 'connections') found.push(child);
+        await walk(child, depth - 1);
+      }
+    }
+  }
+  await walk(root, maxDepth);
+  return found;
+}
+
+const SAP_GUI_REGISTRY_ROOTS = [
+  'HKCU\\Software\\SAP\\SAPLogon',
+  'HKCU\\Software\\SAP\\SAPLogon\\Options',
+  'HKCU\\Software\\WOW6432Node\\SAP\\SAPLogon',
+  'HKCU\\Software\\WOW6432Node\\SAP\\SAPLogon\\Options',
+  'HKLM\\Software\\SAP\\SAPLogon',
+  'HKLM\\Software\\SAP\\SAPLogon\\Options',
+  'HKLM\\Software\\WOW6432Node\\SAP\\SAPLogon',
+  'HKLM\\Software\\WOW6432Node\\SAP\\SAPLogon\\Options'
+];
+
+function registryPathCandidates(value) {
+  const raw = pathFromEnv(value);
+  if (!raw) return [];
+  const lower = raw.toLowerCase();
+  if (/\.(?:xml|ini)$/i.test(lower)) return [raw];
+  if (/\\|\//.test(raw) && !extname(raw)) {
+    const result = [];
+    addWindowsSapGuiFiles(result, raw);
+    result.push(join(raw, 'connections'));
+    return result;
+  }
+  if (/\.(?:xml|ini)(?:\s|$)/i.test(lower)) return [raw.split(/\s+/)[0]];
+  return [];
+}
+
+async function windowsRegistrySapGuiCandidates(env = process.env) {
+  if (platform() !== 'win32') return [];
+  const candidates = [];
+  for (const root of SAP_GUI_REGISTRY_ROOTS) {
+    try {
+      const { stdout } = await execFileAsync('reg.exe', ['query', root, '/s'], { windowsHide: true, timeout: 2000, maxBuffer: 256 * 1024 });
+      for (const line of stdout.split(/\r?\n/)) {
+        const match = line.match(/^\s*\S+\s+REG_(?:SZ|EXPAND_SZ)\s+(.+?)\s*$/i);
+        if (!match) continue;
+        candidates.push(...registryPathCandidates(match[1].replace(/%([^%]+)%/g, (_, name) => env[name] || env[name.toUpperCase()] || `%${name}%`)));
+      }
+    } catch {
+      // Registry access can be blocked by policy or absent on non-standard installs.
+    }
+  }
+  return unique(candidates);
+}
+
+async function selfHealingSapGuiCandidates(env, candidates) {
+  const expanded = [...candidates, ...await windowsRegistrySapGuiCandidates(env)];
+  for (const root of sapGuiSearchRoots(env)) {
+    expanded.push(...await findSapGuiFilesUnder(root));
+  }
+  return unique(expanded);
+}
+
+function broadSapGuiSearchRoots(env = process.env) {
+  const home = env.HOME || env.USERPROFILE || homedir();
+  return unique([home, env.USERPROFILE, env.APPDATA, env.LOCALAPPDATA, env.PROGRAMDATA, env.PUBLIC]);
+}
+
+async function broadSelfHealingSapGuiCandidates(env) {
+  const expanded = [];
+  for (const root of broadSapGuiSearchRoots(env)) {
+    expanded.push(...await findSapGuiFilesUnder(root, { maxDepth: 6, maxEntries: 5000 }));
+  }
+  return unique(expanded);
+}
+
 async function parseConnectionsFile(path) {
   const content = await readGuiFile(path);
   if (content.includes('<')) return parseLandscapeXml(content, path);
@@ -172,9 +347,9 @@ async function parseConnectionsFile(path) {
   }).filter(Boolean);
 }
 
-export async function discoverSapGuiSystems({ env = process.env, paths = sapGuiLandscapeCandidates(env) } = {}) {
+async function parseSapGuiCandidatePaths(candidatePaths) {
   const systems = [];
-  for (const path of unique(paths)) {
+  for (const path of unique(candidatePaths)) {
     if (!path) continue;
     try {
       if (!await exists(path)) continue;
@@ -197,6 +372,13 @@ export async function discoverSapGuiSystems({ env = process.env, paths = sapGuiL
       // Ignore unreadable or unfamiliar SAP GUI files; discovery is best-effort.
     }
   }
+  return systems;
+}
+
+export async function discoverSapGuiSystems({ env = process.env, paths } = {}) {
+  const candidatePaths = paths ? unique(paths) : await selfHealingSapGuiCandidates(env, sapGuiLandscapeCandidates(env));
+  let systems = await parseSapGuiCandidatePaths(candidatePaths);
+  if (!systems.length && !paths) systems = await parseSapGuiCandidatePaths(await broadSelfHealingSapGuiCandidates(env));
   const seen = new Set();
   return systems.filter(system => {
     const key = `${system.name}\0${system.host}\0${system.systemId}\0${system.instance}\0${system.client}`.toLowerCase();

package/src/mcp-config.mjs

@@ -129,6 +129,15 @@ export function generatedServerName(destinationName) {
   return slugifyDestination(destinationName);
 }
 
+export function generatedDestinationServerName(destination) {
+  if (destination?.source === 'sap-gui-local') {
+    const systemId = String(destination.systemId || '').trim();
+    const client = String(destination.client || '001').trim() || '001';
+    if (systemId) return generatedServerName(`${systemId}-${client}`);
+  }
+  return generatedServerName(destination?.source === 'cloud-foundry' ? destination.serverName : destination?.name);
+}
+
 export function buildSapDevelopmentMcpEntries(serverIds = SAP_DEVELOPMENT_MCP_SERVERS.map(server => server.id), { packageVersions = {}, packageManager = 'npx' } = {}) {
   const selected = new Set(serverIds);
   const entries = Object.create(null);
@@ -159,7 +168,7 @@ export function buildMcpEntries(destinations, env = process.env) {
   for (const destination of selected) {
     const isCf = destination.source === 'cloud-foundry';
     const isLocalSapGui = destination.source === 'sap-gui-local';
-    const name = generatedServerName(isCf ? destination.serverName : destination.name);
+    const name = generatedDestinationServerName(destination);
     if (Object.hasOwn(entries, name)) throw new Error(`Duplicate MCP destination server name: ${name} (two destination names normalize to the same lowercase server name)`);
     const entryEnv = {
       ...(h2oUrl ? { H2O_URL: String(h2oUrl) } : {}),
@@ -402,9 +411,9 @@ export async function repairManagedMcpConfig(discoveredDestinations, { env = pro
   for (const [serverName, entry] of Object.entries(config.servers)) {
     if (!isManagedBasDestinationEntry(entry)) continue;
     const destinationName = destinationValue(entry.env);
-    const expectedName = generatedServerName(destinationName);
     const destination = basDestinations.get(destinationName);
     if (!destination) continue;
+    const expectedName = generatedDestinationServerName(destination);
     if (expectedName !== serverName) {
       // Legacy mixed-case entries migrate to the normalized lowercase key.
       // A user-owned entry on the target key blocks the rename; merging is

package/src/setup.mjs

@@ -2,7 +2,7 @@ import { createInterface } from 'node:readline/promises';
 import { stdin, stdout } from 'node:process';
 import { platform } from 'node:os';
 import { isIP } from 'node:net';
-import { checkboxPrompt, colorText, formatStatus, textPrompt } from './terminal-ui.mjs';
+import { checkboxPrompt, colorText, formatStatus, selectPrompt, textPrompt } from './terminal-ui.mjs';
 import { discoverDestinations, remediation } from './bas-discovery.mjs';
 import { defaultAdtUrl, discoverSapGuiSystems } from './local-sap-gui.mjs';
 import { discoverCloudFoundryDestinations, getCloudFoundryTarget, deleteManagedCloudFoundryServiceKeys, findOrphanedCloudFoundryServiceKeys } from './cf-destination.mjs';
@@ -15,23 +15,55 @@ function print(output, message) {
   output.write(`${message}\n`);
 }
 
+function startSapGuiLandscapeAnimation(output, env = process.env) {
+  if (!output?.isTTY || !Number.isFinite(output?.columns)) return () => {};
+  if (env.TERM === 'dumb' || env.CI || env.SAP_AI_DEV_TOOLKIT_DISABLE_SCAN_ANIMATION === 'true') return () => {};
+  const frames = [
+    '=^.^=                         ~(o:>',
+    '  =^.^=                    ~(o:>',
+    '     =^.^=              ~(o:>',
+    '        =^.^=        ~(o:>',
+    '           =^.^=  ~(o:>',
+    '             =^.^= caught it!'
+  ];
+  let index = 0;
+  let active = false;
+  const render = () => {
+    active = true;
+    const columns = Math.max(20, output.columns || 80);
+    const frame = frames[index % frames.length];
+    index += 1;
+    const line = `Scanning SAP GUI landscapes ${frame}`.slice(0, Math.max(1, columns - 1));
+    output.write(`\r\u001b[2K${line}`);
+  };
+  const delay = setTimeout(() => {
+    render();
+    interval = setInterval(render, 160);
+    if (typeof interval.unref === 'function') interval.unref();
+  }, 150);
+  if (typeof delay.unref === 'function') delay.unref();
+  let interval;
+  return () => {
+    clearTimeout(delay);
+    if (interval) clearInterval(interval);
+    if (active) output.write('\r\u001b[2K');
+  };
+}
+
 function windowsSsoSetupAvailable(env = process.env) {
   return platform() === 'win32' || env.SAP_AI_DEV_TOOLKIT_ENABLE_WINDOWS_SSO_SETUP === 'true';
 }
 
 async function chooseLocalAuthMode(destination, { input = stdin, output = stdout, env = process.env } = {}) {
   if (!windowsSsoSetupAvailable(env)) return 'basic';
-  const answer = await textPrompt({
-    message: `Authentication for ${destination.name} (password/sso)`,
-    placeholder: 'password',
-    required: false,
-    validate: value => {
-      const candidate = String(value || 'password').trim().toLowerCase();
-      return ['password', 'basic', 'sso', 'windows-sso'].includes(candidate) || 'Enter password or sso.';
-    }
+  return await selectPrompt({
+    message: `Authentication for ${destination.name}`,
+    defaultValue: 'basic',
+    choices: [
+      { name: 'password', value: 'basic', shortcut: 'p' },
+      { name: 'windows-sso (Kerberos/SPNEGO, including smart-card Windows logon)', value: 'windows-sso', shortcut: 's' }
+    ]
   }, { input, output });
-  const normalized = String(answer || 'password').trim().toLowerCase();
-  return ['sso', 'windows-sso'].includes(normalized) ? 'windows-sso' : 'basic';
 }
 
 async function confirmCloudFoundryImport({ input = stdin, output = stdout } = {}) {
@@ -214,10 +246,13 @@ export async function runSetup({
     destinations = basDestinations.map(safeBasDestination);
   } else {
     let localSystems;
+    const stopScanAnimation = startSapGuiLandscapeAnimation(output, env);
     try {
       localSystems = await discoverLocalSapGui({ env });
     } catch (error) {
       throw new Error(`SAP GUI discovery failed: ${error.message}`);
+    } finally {
+      stopScanAnimation();
     }
     destinations = localSystems.map(safeLocalSapGuiDestination);
   }
@@ -349,7 +384,7 @@ export async function runSetup({
     print(output, '');
     print(output, formatStatus('SAP GUI landscapes do not contain ADT HTTP(S) endpoints or a complete client catalog. Confirm the SAP client(s), ADT URL, and authentication for each selected system.', 'step', output, 'Local SAP GUI'));
     print(output, '  Enter multiple clients as comma-separated 3-digit values, for example 100,200. Setup creates one isolated MCP server per system/client pair.');
-    if (windowsSsoSetupAvailable(env)) print(output, '  Windows SSO is experimental and only applies to ADT systems configured for HTTP Integrated Authentication. Username/password remains the default.');
+    if (windowsSsoSetupAvailable(env)) print(output, '  Windows SSO is experimental and only applies to ADT systems configured for HTTP Integrated Authentication (Negotiate/SPNEGO). It uses the current Windows logon session, including smart-card-backed Windows logon; the toolkit cannot prompt for or accept manual bearer/SAML tokens. Username/password remains the default.');
     const selectedNameCounts = selected.reduce((counts, destination) => {
       const key = String(destination.name).toLowerCase();
       counts.set(key, (counts.get(key) || 0) + 1);

package/src/terminal-ui.mjs

@@ -115,6 +115,102 @@ function checkboxPageSize(output, choiceCount) {
   return clamp(Math.min(choiceCount, rows - 7), 1, Math.max(1, choiceCount));
 }
 
+export async function selectPrompt({ message, choices, defaultValue } = {}, { input = process.stdin, output = process.stdout } = {}) {
+  if (!Array.isArray(choices) || !choices.length) return undefined;
+  let cursor = choices.findIndex(choice => !choice.disabled && (choice.value === defaultValue || choice.checked));
+  if (cursor === -1) cursor = firstEnabledIndex(choices);
+  let top = 0;
+  let renderedLines = 0;
+  let done = false;
+  let previousRawMode;
+
+  const write = text => output.write(text);
+  const clearRendered = () => {
+    if (!renderedLines) return;
+    write(`\u001b[${renderedLines}A\u001b[J`);
+    renderedLines = 0;
+  };
+  const ensureVisible = pageSize => {
+    if (cursor < top) top = cursor;
+    if (cursor >= top + pageSize) top = cursor - pageSize + 1;
+    top = clamp(top, 0, Math.max(0, choices.length - pageSize));
+  };
+  const render = () => {
+    const columns = Number.isFinite(output?.columns) ? output.columns : 80;
+    const pageSize = checkboxPageSize(output, choices.length);
+    ensureVisible(pageSize);
+    const lines = [];
+    lines.push(truncateToColumns(`${message} (↑/↓: choose, Enter: confirm)`, columns));
+    const end = Math.min(choices.length, top + pageSize);
+    for (let index = top; index < end; index += 1) {
+      const choice = choices[index];
+      const pointer = index === cursor ? '❯' : ' ';
+      const marker = index === cursor ? colorText('●', 'green', output) : '○';
+      const disabled = choice.disabled ? ` — ${choice.disabled}` : '';
+      const label = `${pointer}${marker} ${choice.name}${disabled}`;
+      lines.push(truncateToColumns(label, columns));
+    }
+    if (choices.length > pageSize) {
+      lines.push(truncateToColumns(colorText(`  Showing ${top + 1}-${end} of ${choices.length}; use ↑/↓ to scroll.`, 'cyan', output), columns));
+    }
+    clearRendered();
+    write(`${lines.join('\n')}\n`);
+    renderedLines = physicalRows(lines, columns);
+  };
+
+  return new Promise((resolve, reject) => {
+    const cleanup = () => {
+      input.off('keypress', onKeypress);
+      if (typeof input.setRawMode === 'function' && previousRawMode !== undefined) input.setRawMode(previousRawMode);
+      if (typeof input.pause === 'function') input.pause();
+      write('\u001b[?25h');
+    };
+    const finish = choice => {
+      if (done) return;
+      done = true;
+      clearRendered();
+      write(`${stripAnsi(message)} ${choice?.name || choice?.value || ''}\n`);
+      cleanup();
+      resolve(choice?.value);
+    };
+    const fail = error => {
+      if (done) return;
+      done = true;
+      cleanup();
+      reject(error);
+    };
+    const onKeypress = (chunk, key = {}) => {
+      if (key.ctrl && key.name === 'c') return fail(new Error('Prompt interrupted'));
+      if (key.name === 'up' || key.name === 'k') cursor = nextEnabledIndex(choices, cursor, -1);
+      else if (key.name === 'down' || key.name === 'j') cursor = nextEnabledIndex(choices, cursor, 1);
+      else if (key.name === 'return' || key.name === 'enter') return finish(choices[cursor]);
+      else if (chunk) {
+        const typed = String(chunk).toLowerCase();
+        const match = choices.findIndex(choice => !choice.disabled && (
+          String(choice.shortcut || '').toLowerCase() === typed ||
+          String(choice.value || '').toLowerCase().startsWith(typed) ||
+          String(choice.name || '').toLowerCase().startsWith(typed)
+        ));
+        if (match !== -1) cursor = match;
+        else return;
+      } else return;
+      render();
+    };
+
+    try {
+      readline.emitKeypressEvents(input);
+      previousRawMode = input.isRaw;
+      if (typeof input.setRawMode === 'function') input.setRawMode(true);
+      if (typeof input.resume === 'function') input.resume();
+      write('\u001b[?25l');
+      input.on('keypress', onKeypress);
+      render();
+    } catch (error) {
+      fail(error);
+    }
+  });
+}
+
 export async function checkboxPrompt({ message, choices, required = false, shortcuts = { all: 'a' }, validate } = {}, { input = process.stdin, output = process.stdout } = {}) {
   if (!Array.isArray(choices) || !choices.length) return [];
   const selectable = enabledChoices(choices);

package/src/windows-sso-adt-proxy.mjs

@@ -122,7 +122,7 @@ function execHelper(helper, payload, execFileImpl = nodeExecFile, env = process.
       env: { ...process.env, ...env }
     }, (error, stdout) => {
       // execFile errors can contain helper stdout/stderr, including tokens.
-      if (error) return reject(safeError('Windows SSO helper failed; verify the helper and Windows Kerberos configuration.'));
+      if (error) return reject(safeError('Windows SSO helper failed; verify the ADT endpoint supports HTTP Negotiate/SPNEGO for the signed-in Windows identity (including smart-card-backed Windows logon) and that Kerberos/SPN configuration is correct. The toolkit cannot prompt for or accept manually pasted bearer/SAML tokens.'));
       const token = String(stdout || '').trim();
       if (!/^[A-Za-z0-9+/=_-]+$/.test(token)) return reject(safeError('Windows SSO helper returned an invalid Negotiate token'));
       if (tokenLooksLikeNtlm(token)) return reject(safeError('Windows SSO helper returned an NTLM token. ADT SSO requires Kerberos/SPNEGO; verify the backend SPN and Kerberos configuration, or rerun sap-ai-dev --setup and choose username/password.'));
@@ -135,7 +135,7 @@ function execHelper(helper, payload, execFileImpl = nodeExecFile, env = process.
 async function acquireNegotiateToken({ targetUrl, challenge, env, execFileImpl }) {
   const helper = helperCommand(env);
   if (!helper) {
-    throw safeError('Windows SSO requires an SSPI/Negotiate helper. Set SAP_AI_DEV_TOOLKIT_NEGOTIATE_HELPER to a trusted helper executable, or rerun sap-ai-dev --setup and choose username/password.');
+    throw safeError('Windows SSO requires an SSPI/Negotiate helper that uses the current Windows logon session (including smart-card-backed logon). Set SAP_AI_DEV_TOOLKIT_NEGOTIATE_HELPER to a trusted helper executable, or rerun sap-ai-dev --setup and choose username/password. Manual token entry is not supported.');
   }
   return execHelper(helper, { url: targetUrl, challenge, mechanism: 'Negotiate' }, execFileImpl, env);
 }