sap-ai-dev-toolkit 0.9.9922 → 0.9.9924

package/.github/skills/process-automation-development/SKILL.md

@@ -0,0 +1,113 @@
+---
+description: Inspect, test and operate SAP Build Process Automation with the sap-ai-process-automation MCP server: process definitions, workflow instances, contexts, logs and errors, stuck instances, user tasks and the user inbox, decisions, API triggers, automations, process visibility, administration jobs, process triggers and business events.
+name: process-automation-development
+---
+
+# SAP Build Process Automation development
+
+## Tool shortlist
+
+Use the live MCP `tools/list` result as authoritative. Call only the exact schemas exposed by the `sap-ai-process-automation` server (51 tools):
+
+Connection
+- `bpa_connection_info` — `api_host`, `uaa_host`, `auth`, `source`, `task_attribution`, `api_key_configured`, `environment_id`; `verify: true` checks Workflow API access.
+
+Workflow definitions
+- `bpa_list_process_definitions`, `bpa_get_process_definition` — deployed definitions with optional `model`, `sample_start_context`, `versions`.
+- `bpa_list_task_definitions` — user-task definitions, optionally with attribute definitions.
+- `bpa_delete_process_definition` — undeploy a classic workflow definition (async, `job_id`); requires confirmation `DELETE BPA DEFINITION <definition_id>`.
+- `bpa_delete_form` — undeploy a classic form; requires confirmation `DELETE BPA FORM <form_id>`.
+
+Instances
+- `bpa_list_instances` — filtered by definition, status (repeated = OR), business key, text, subject, starter, time ranges, root/parent, project.
+- `bpa_get_instance` — includes `context` (or `context_path`), `outputs`, `execution_logs`, `error_messages`, `attributes`, `roles`.
+- `bpa_find_stuck_instances` — erroneous (with error messages), suspended, and long-running instances.
+- `bpa_trace_process` — instances by id, business key, or text with error messages, tasks, and recent logs.
+- `bpa_start_instance` — requires confirmation `START BPA PROCESS <definition_id>`.
+- `bpa_change_instance_status` — actions `cancel`, `suspend`, `resume`, `retry` require confirmation `CANCEL BPA INSTANCE <instance_id>`, `SUSPEND BPA INSTANCE <instance_id>`, `RESUME BPA INSTANCE <instance_id>`, or `RETRY BPA INSTANCE <instance_id>`.
+- `bpa_update_instance_context` — requires confirmation `MERGE BPA CONTEXT <instance_id>` or `REPLACE BPA CONTEXT <instance_id>`.
+- `bpa_update_instance_roles` — requires confirmation `UPDATE BPA ROLES <instance_id>`.
+- `bpa_delete_instances` — permanent, async for larger sets; requires confirmation `DELETE BPA INSTANCES <count>`.
+- `bpa_send_message` — classic intermediate message events only; requires confirmation `SEND BPA MESSAGE <message_definition_id>`.
+
+User tasks
+- `bpa_list_tasks`, `bpa_get_task` — user-task queues (what My Inbox / Fiori Task Center shows) and task context/attributes.
+- `bpa_complete_task` — requires confirmation `COMPLETE BPA TASK <task_id>`.
+- `bpa_update_tasks` — bulk admin update (async, `job_id`); requires confirmation `UPDATE BPA TASKS <count>`.
+- `bpa_update_task_context` — requires confirmation `UPDATE BPA TASK CONTEXT <task_id>`.
+
+Administration / jobs
+- `bpa_export_workflow_data` — ZIP export to a new local file.
+- `bpa_purge_workflow_data` — erases all workflow data of the tenant (async); requires confirmation `PURGE ALL BPA WORKFLOW DATA`.
+- `bpa_get_job` — status of an asynchronous workflow job.
+
+Inbox (user-centric)
+- `bpa_inbox_list_tasks`, `bpa_inbox_get_task`, `bpa_inbox_list_task_definitions`, `bpa_inbox_list_substitution_rules` — read the signed-in user's inbox.
+- `bpa_inbox_task_action` — requires confirmation `CLAIM BPA INBOX TASK <instance_id>`, `RELEASE BPA INBOX TASK <instance_id>`, or `FORWARD BPA INBOX TASK <instance_id>`.
+- `bpa_inbox_create_substitution_rule` — requires confirmation `CREATE BPA SUBSTITUTION FOR <user>`.
+- `bpa_inbox_change_substitution_rule` — requires confirmation `ENABLE BPA SUBSTITUTION <rule_id>`, `DISABLE BPA SUBSTITUTION <rule_id>`, or `DELETE BPA SUBSTITUTION <rule_id>`.
+
+Decisions
+- `bpa_invoke_decision`, `bpa_test_decision` — evaluate a deployed rule service and compare results with expected outputs.
+
+API triggers (Unified)
+- `bpa_list_api_triggers`, `bpa_get_api_trigger` — process API triggers of an environment.
+- `bpa_execute_api_trigger` — start a process, or resume a "Wait for an API Call" step with `execution_id`; requires confirmation `EXECUTE BPA TRIGGER <trigger_uid>`.
+
+Automations (execution + monitoring; environment API key required)
+- `bpa_list_automation_triggers`, `bpa_get_automation_trigger`, `bpa_list_automation_jobs` — automation triggers and their jobs.
+- `bpa_start_automation` — requires confirmation `START BPA AUTOMATION <trigger_uid>`.
+- `bpa_export_automation_data` — BAM data or archived jobs as CSV, inline or to a new local file.
+
+Visibility scenarios
+- `bpa_list_visibility_scenarios`, `bpa_get_visibility_scenario` — scenario definitions, model, recent executions.
+- `bpa_list_visibility_events` — acquired events, or `kind: errors` for data-acquisition errors.
+- `bpa_process_visibility_scenario` — requires confirmation `PROCESS BPA VISIBILITY <scenario_id>`.
+- `bpa_clear_visibility_data` — requires confirmation `CLEAR BPA VISIBILITY DATA <scenario_id>`.
+- `bpa_push_visibility_events` — requires confirmation `PUSH BPA VISIBILITY EVENTS <count>`.
+
+Visibility workspace
+- `bpa_list_visibility_workspace_scenarios`, `bpa_list_visibility_instances`, `bpa_get_visibility_instance` — scenario instances with phases, paths and steps.
+
+Business events
+- `bpa_send_business_event` — requires confirmation `SEND BPA EVENT <type>`.
+
+## Procedure
+
+1. Call `bpa_connection_info` first. Compare API host, `auth`, `task_attribution`, `api_key_configured`, and `environment_id` against the request. If the target is missing or mismatched, stop and report; never ask the user to paste credentials.
+2. Query live `tools/list`, use the returned tool names and schemas exactly, and invoke the chat-attached tools directly. Direct MCP invocation is mandatory. Do not launch `sap-ai-dev` or `sap-ai-process-automation` for MCP operations, handcraft JSON-RPC in a terminal, or use a CLI fallback when chat tools are unavailable; report a host/session binding issue. Always call the exact names returned by `tools/list`.
+3. Inspect: `bpa_list_process_definitions`, `bpa_get_process_definition` (`sample_start_context` before a start), `bpa_list_instances`, `bpa_get_instance`, `bpa_list_tasks`, `bpa_get_task`; for a user's view, `bpa_inbox_list_tasks` under interactive auth.
+4. Diagnose stuck or erroneous instances with `bpa_find_stuck_instances` and `bpa_get_instance` (`error_messages`, then `execution_logs`/`context`). Fix the cause first (if data is wrong: suspend, `bpa_update_instance_context`), then `bpa_change_instance_status` with action `retry`.
+5. Test decisions with `bpa_test_decision`, giving explicit `expected` outputs per case; use `bpa_invoke_decision` to inspect raw results. Rule-service ids come from the deployed project; there is no list API.
+6. Start a process with `bpa_start_instance`, `bpa_execute_api_trigger`, or event-trigger it with `bpa_send_business_event`, using a test payload. Resume a process waiting in a "Wait for an API Call" step with `bpa_execute_api_trigger` and `execution_id` (the process instance id); `bpa_send_message` only serves classic workflows.
+7. API-key-gated tools: `bpa_list_automation_triggers`, `bpa_get_automation_trigger`, `bpa_list_automation_jobs`, `bpa_start_automation`, and `bpa_export_automation_data` fail before any tenant call when `api_key_configured` is false; ask the user to set `PROCESS_AUTOMATION_API_KEY` or rerun `sap-ai-dev --setup-process-automation`. Unified API trigger tools and `bpa_start_instance` send the key only when configured and default `environment_id` to `PROCESS_AUTOMATION_ENVIRONMENT_ID`.
+8. Visibility troubleshooting: when a scenario dashboard misses data, check `bpa_get_visibility_scenario` with `include: ["executions"]`, then `bpa_list_visibility_events` with `kind: "errors"` (data-acquisition errors) and `kind: "events"` for the process instance; reprocess with `bpa_process_visibility_scenario` once fixed and verify with `bpa_list_visibility_instances` / `bpa_get_visibility_instance`.
+9. Track asynchronous operations (definition undeploy, purge, bulk instance delete, bulk task update) through the returned `job_id` with `bpa_get_job` until it finishes.
+10. Trace the result with `bpa_trace_process` (by instance id, business key, or text) and verify statuses, tasks, and logs.
+
+## Rules
+
+- Technical auth attributes starts, status changes, and task completions to the service key's technical client. User auth needs the `ProcessAutomationAdmin` role collection for administration or `ProcessAutomationParticipant` (as task recipient) for task completion and the inbox.
+- Workflow API status filters are sent as repeated parameters and are OR-combined; other filters are AND-combined. Task statuses are `READY`, `RESERVED`, `COMPLETED`, `CANCELED`.
+- The Inbox (TCM OData) is user-centric: with technical auth it shows the technical client's inbox (normally empty); use interactive auth for a real user's inbox.
+- Automation Execution/Monitoring need an environment API key (`irpa-api-key`) with scopes `TRIGGER_READ`, `TRIGGER_EXECUTE`, `BAM_DOWNLOAD`, or `JOB_DATA_DOWNLOAD` as required by the tool. Unified API triggers optionally use `api-key` plus `environmentId`.
+- Visibility roles: `PVAdmin` (scenario definitions, executions, clear data, acquisition reads), `PVEventSender` (push events), `PVOperator`/`PVRestrictedOperator` (workspace instances).
+- Exports (`bpa_export_workflow_data` ZIP, `bpa_export_automation_data` CSV) write to a new local file: absolute path, never overwritten, mode 0600.
+- `bpa_complete_task` `decision` is the form button identifier.
+- Context payloads over 48 KiB are truncated (`context_truncated: true` with keys); call `bpa_get_instance` with a single include or a `context_path` to narrow the response.
+- Interactive (user) mode withholds SAP error bodies, so read the HTTP status:
+  - 400: task already in final status
+  - 403: missing ProcessAutomationAdmin/ProcessAutomationParticipant role or not the task recipient
+  - 404: unknown id
+  - 409: `decision` is not a button id of the form
+  - 422: invalid status transition
+
+  Technical mode shows SAP's error message.
+
+## Safety boundaries
+
+- Writes are confirmation-gated only: never call a write tool without its exact confirmation string, and never guess one.
+- `bpa_purge_workflow_data`, `bpa_delete_instances`, and `bpa_delete_process_definition` are destructive and irreversible: never run them without explicit user instruction naming the scope.
+- Never store credentials in `mcp.json` or echo secrets (client secrets, refresh tokens, access tokens, API keys) into results, files, or chat.
+- Never complete tasks, forward inbox tasks, or create substitution rules that represent real approvals without explicit user instruction.
+- Do not invent tools or handcraft JSON-RPC; if a needed tool is absent from `tools/list`, report a host/session binding issue.

package/NOTICE

@@ -3,7 +3,8 @@ Third-party notices for sap-ai-dev-toolkit
 This package includes patched VSP (vibing-steampunk) binaries built from upstream commit
 9886d2727f47506368b0a3c2f1c1766f1200f747. The BAS proxy-auth change is documented in
 patches/vsp-bas-proxy-auth.patch; the namespaced class-include EditSource fix is documented in
-patches/vsp-namespaced-class-include-edit.patch. The following upstream notice is reproduced from VSP:
+patches/vsp-namespaced-class-include-edit.patch; the shared-logon fix for concurrent ADT requests is
+documented in patches/vsp-single-logon.patch. The following upstream notice is reproduced from VSP:
 
 vibing-steampunk (vsp)
 Copyright (c) 2025-2026 Alice Vinogradova and contributors

package/README.md

@@ -67,7 +67,7 @@ After setup, connect a selected BAS destination or local SAP GUI system from you
 1. Open the Command Palette.
 2. Run **MCP: List Servers**.
 3. Start the server named after your selected destination (the lowercase slug, for example `demo-abap` for destination `DEMO_ABAP`).
-4. In your AI assistant's chat, choose the best-fit bundled agent from the agent picker (GitHub Copilot, Claude Code, and opencode install the agents) or invoke the matching Pi prompt template (`/sap-solution-architect`, `/abap-developer`, `/abap-runtime-debugger`, `/rap-service-developer`, `/hana-cloud-hdi-specialist`, `/sap-integration-architect`, or `/sap-integration-developer`): **SAP Solution Architect**, **ABAP Developer**, **ABAP Runtime Debugger**, **RAP Service Developer**, **HANA Cloud/HDI Specialist**, **SAP Integration Architect**, or **SAP Integration Developer**.
+4. In your AI assistant's chat, choose the best-fit bundled agent from the agent picker (GitHub Copilot, Claude Code, and opencode install the agents), ask OMP to delegate to the matching task agent (for example "use the `abap-developer` agent"), or invoke the matching Pi prompt template (`/sap-solution-architect`, `/abap-developer`, `/abap-runtime-debugger`, `/rap-service-developer`, `/hana-cloud-hdi-specialist`, `/sap-integration-architect`, or `/sap-integration-developer`): **SAP Solution Architect**, **ABAP Developer**, **ABAP Runtime Debugger**, **RAP Service Developer**, **HANA Cloud/HDI Specialist**, **SAP Integration Architect**, or **SAP Integration Developer**.
 5. In the Chat tools picker, enable the server for that destination.
 6. Ask the agent to inspect, build, test, or verify something in your SAP landscape.
 
@@ -75,9 +75,19 @@ Use the attached destination-prefixed tools directly in chat. Do not launch `sap
 
 **Prerequisite:** Node.js 20 or newer. The pinned runtime ships with the package; no Go toolchain is installed or required.
 
+## 🆕 What's new
+
+| Version | Change |
+| --- | --- |
+| 0.9.9924 | **One SAP logon per runtime, shared by parallel tool calls.** AI assistants fire many tool calls at once; each used to reach SAP before the first security-session cookie came back, so every call logged on again and SM04 / the SAP GUI "already logged on" list filled with dozens of sessions. Now the first request logs on, the parallel ones wait for it and reuse its `SAP_SESSIONID` cookie (Basic, SSO and local SAP GUI entries alike); after an expired session the next burst again shares one fresh logon. |
+| 0.9.9923 | **Oh My Pi (OMP) receives all twelve agents** as task agents (`~/.omp/agent/agents/<id>.md`, dispatched by kebab-case id) next to the twenty-two skills. **Four new companion MCP servers:** SAP Datasphere (`sap-ai-datasphere`, incl. BW → Datasphere migration), SAP Build Process Automation (`sap-ai-process-automation`, all eight BPA APIs), SAP BTP platform administration (`sap-ai-btp`, on your own `btp login --sso`), and SAP Cloud ALM (`sap-ai-cloud-alm`), each with its own agent, skills and `--setup-*` wizard. |
+| 0.9.9922 | `EditSource` no longer double-encodes namespaced class names (`/NS/CL_…`) on class-include writes. |
+| 0.9.9921 | Simpler Integration Suite setup wizard: shorter intro, clearer status lines, and a single credential menu. |
+| 0.9.9920 | **Integration Suite companion** (`sap-ai-integration`, since 0.9.9914) expanded across the lifecycle: API Management content, documentation, runtime and monitoring reads, confirmation-gated cleanup and delete tools, and asynchronous Cloud Integration monitoring. |
+
 ## 🤖 Available agents and skills
 
-**Agents:** Seven user-invocable custom agents are included. Select the best fit from the agent picker in your harness's chat (GitHub Copilot, Claude Code, or opencode), or use the matching Pi prompt command, as shown in Quick start. Harnesses without custom agents (OpenAI Codex, Cursor, Gemini CLI, OMP, Cline, Roo Code, Windsurf / Devin Desktop) get the same workflows as skills, for example `sap-integration-architect` and `integration-suite-delivery`.
+**Agents:** Twelve user-invocable custom agents are included. Select the best fit from the agent picker in your harness's chat (GitHub Copilot, Claude Code, or opencode), dispatch the matching OMP task agent by its kebab-case id, or use the matching Pi prompt command, as shown in Quick start. Harnesses without custom agents (OpenAI Codex, Cursor, Gemini CLI, Cline, Roo Code, Windsurf / Devin Desktop) get the same workflows as skills, for example `sap-integration-architect` and `integration-suite-delivery`.
 
 | | Agent | Best for |
 | --- | --- | --- |
@@ -88,18 +98,23 @@ Use the attached destination-prefixed tools directly in chat. Do not launch `sap
 | 🗃️ | **HANA Cloud/HDI Specialist** | Read-only HANA Cloud container inspection, CAP/HDI artifact generation, local validation, and user-run deployment handoffs |
 | 🏗️ | **SAP Integration Architect** | SAP Integration Suite design: API Management vs Cloud Integration vs both, connectivity, per-hop security, error handling, and an approved build plan |
 | 🔌 | **SAP Integration Developer** | Building that plan with the Integration Suite companion: iFlows, value mappings, security material, deployment and monitoring in CPI; API providers, proxies, policies, products and key value maps in APIM |
+| 🗄️ | **SAP Datasphere Developer** | Modeling, deploying, loading, and administering Datasphere content end to end with the Datasphere companion: CSN objects, packages, task chains, replication flows, data products, consumption queries and Open SQL |
+| 🚚 | **SAP BW Datasphere Migration Specialist** | Migrating BW models and data products to Datasphere: read-only BW inventory, Data Product Generator or rebuild path, object creation, loads, and BW-versus-Datasphere reconciliation |
+| ⚙️ | **SAP Process Automation Developer** | Inspecting, testing and operating SAP Build Process Automation with the Process Automation companion: process definitions, workflow instances, stuck and failed instances, user-task queues, decisions, process triggers and business events |
+| ☁️ | **SAP BTP Infrastructure Admin** | Auditing and operating SAP BTP core platform setup with the BTP companion: account hierarchy, entitlements and quotas, Service Manager instances and service keys, destinations, trust, Cloud Connectors and principal propagation checks |
+| 📡 | **SAP DevOps & Observability Specialist** | Monitoring SAP landscapes with the Cloud ALM companion: Integration & Exception Monitoring, health and alert hotspots per DEV/TEST/PROD tier, incident triage correlated with CPI message logs and SLG1, and feature/transport status |
 
-**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` · `sap-integration-architect` · `integration-suite-delivery`
+**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` · `sap-integration-architect` · `integration-suite-delivery` · `datasphere-development` · `datasphere-administration` · `bw-datasphere-migration` · `process-automation-development` · `btp-platform-administration` · `cloud-alm-operations`
 
 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, Pi Coding Agent, Oh My Pi (OMP), Cline, Roo Code, and Windsurf / Devin Desktop. 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 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.
+`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. Optional companion servers from the same package reach the rest of the landscape: HANA Cloud, Integration Suite, Datasphere, Build Process Automation, the BTP platform, and Cloud ALM. Instead of manually switching between chat, terminal commands, repository searches, ADT screens, cockpits, 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>
 
-The workflow covers ABAP, CDS, RAP, repository analysis, table and query access, testing, ATC, application logs, transports, and controlled source changes. The live MCP tool list remains the source of truth for what your connected SAP system and active runtime mode expose.
+The workflow covers ABAP, CDS, RAP, repository analysis, table and query access, testing, ATC, application logs, transports, and controlled source changes, plus integration, data, process and platform operations through the companions. The live MCP tool list remains the source of truth for what your connected SAP system and active runtime mode expose.
 
 ## 🌟 Feature highlights
 
@@ -111,6 +126,13 @@ The workflow covers ABAP, CDS, RAP, repository analysis, table and query access,
 | 🧩 | **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. |
 | ☁️ | **Read-only HANA Cloud inspection** | Inspect an environment-bound HDI schema, object metadata, and capped query results without exposing deployment credentials. |
+| 🔌 | **Integration Suite lifecycle** | Build, release, deploy, monitor, diagnose and recover Cloud Integration and API Management content with retained releases and confirmation-gated writes. |
+| 🗄️ | **Datasphere and BW migration** | Model, deploy, load and administer Datasphere content; inventory BW models and reconcile BW against Datasphere after migration. |
+| ⚙️ | **Build Process Automation operations** | Inspect definitions and instances, unstick failed workflows, work user-task queues, test decisions, and trace business events across all eight BPA APIs. |
+| 🏛️ | **BTP platform administration** | Audit account hierarchy, entitlements and quotas, service instances and keys, destinations, trust and Cloud Connectors on your own `btp` CLI login. |
+| 📡 | **Cloud ALM observability** | Find exception and alert hotspots per DEV/TEST/PROD tier and correlate them with live CPI message logs and SLG1. |
+| 🧩 | **Agents in eleven AI harnesses** | Copilot, Claude Code, opencode and OMP get native agents, Pi gets prompt commands, and every harness gets the skills. |
+| 🔁 | **One logon per runtime** | Parallel tool calls share a single SAP security session instead of opening one per call. |
 | ✍️ | **Edit ABAP safely** | Update supported source, stage reviewed change sets, create transport requests, and run syntax checks before requested activation. |
 | ✅ | **Quality built into the flow** | Pair local ABAP linting with SAP syntax checks, ABAP Unit, ATC, editor diagnostics, and formatting. |
 | 🐞 | **Debug with system context** | Investigate dumps, traces, application logs, runtime failures, capabilities, and installed components. |
@@ -161,9 +183,9 @@ The catalog below covers source inspection, data, editing, quality, transports,
 - Read SLG1 application logs
 - Review and create transport requests
 
-## 🧠 Seven agents, sixteen focused skills
+## 🧠 Twelve agents, twenty-two focused skills
 
-The package ships with seven custom agents plus sixteen task-focused Agent Skills:
+The package ships with twelve custom agents plus twenty-two task-focused Agent Skills:
 
 | | Skill | Best for |
 | --- | --- | --- |
@@ -183,20 +205,26 @@ The package ships with seven custom agents plus sixteen task-focused Agent Skill
 | ✅ | `hana-cloud-validation` | Run local CAP/HANA builds and prepare a reviewed, user-run deployment handoff |
 | 🏗️ | `sap-integration-architect` | Integration Suite pattern choice, connectivity, per-hop security, naming/versioning rules, and an approvable build plan |
 | 🔌 | `integration-suite-delivery` | Building iFlows, API proxies, gateway policies, API products and key value maps step by step, deploying, and troubleshooting with message logs |
+| 🗄️ | `datasphere-development` | Modeling, deploying, loading, and verifying Datasphere content: CSN objects, packages, task chains, replication flows, data products, consumption queries and Open SQL |
+| 🛡️ | `datasphere-administration` | Administering Datasphere: spaces and space users, database users, workload priorities, roles, users, connections, TLS certificates, and task-scheduling consent |
+| 🚚 | `bw-datasphere-migration` | Planning and running BW → Datasphere migrations: BW inventory, Data Product Generator or rebuild path, object mapping, BW baselines, and Datasphere reconciliation |
+| ⚙️ | `process-automation-development` | Inspecting, testing and operating SAP Build Process Automation: definitions, instances, contexts, logs and errors, stuck instances, user tasks, decisions, process triggers and business events |
+| ☁️ | `btp-platform-administration` | Auditing and operating SAP BTP core platform setup: account hierarchy, entitlements and quotas, Service Manager instances and service keys, destinations, identity and destination trust, Cloud Connectors and principal propagation checks |
+| 📡 | `cloud-alm-operations` | Monitoring, triaging and tracking SAP landscapes with Cloud ALM: monitoring records and analytics, tier hotspots, CPI/SLG1 correlation, feature and transport status, confirmation-gated alert closing |
 
 ## 🗺️ How it fits together
 
-Each selected BAS destination becomes its own isolated MCP server identity. The MCP client discovers the live tools and schemas, the add-on routes calls to the correct runtime process, and the process reaches SAP ADT through the selected BAS destination.
+Each selected BAS destination or local SAP GUI system becomes its own isolated MCP server identity. The MCP client discovers the live tools and schemas, the add-on routes calls to the correct runtime process, and that process reaches SAP ADT through the selected route over one shared SAP logon. Companion servers (HANA, Integration Suite, Datasphere, Process Automation, BTP, Cloud ALM) are separate stdio MCP processes with their own user-only credentials, so an agent can combine them — for example a Cloud ALM alert, the matching CPI message log, and the ABAP SLG1 entry.
 
 ## 🧰 Optional full-stack companion MCP servers
 
-ABAP/RAP backend access is provided by this add-on's BAS proxy. For end-to-end SAP development, setup can also add managed companion MCP entries for frontend, CAP, browser validation, and read-only HANA inspection:
+ABAP/RAP backend access is provided by this add-on's destination-scoped runtime. For end-to-end SAP development, setup can also add managed companion MCP entries for frontend, CAP, browser validation, read-only HANA inspection, Integration Suite, Datasphere, Build Process Automation, BTP platform administration, and Cloud ALM:
 
 ```sh
 sap-ai-dev --setup --tools
 ```
 
-The companion entries are optional and are launched through `npx` only when the MCP client starts them. They are marked as managed by `sap-ai-dev-toolkit`, so rerunning setup can update or remove them without touching unrelated MCP servers. The HANA and Integration Suite companions use `--ignore-scripts` so the toolkit postinstall wizard cannot run during MCP startup.
+The companion entries are optional and are launched through `npx` only when the MCP client starts them. They are marked as managed by `sap-ai-dev-toolkit`, so rerunning setup can update or remove them without touching unrelated MCP servers. The companions shipped in this package (HANA, Integration Suite, Datasphere, Process Automation, BTP, Cloud ALM) use `--ignore-scripts` so the toolkit postinstall wizard cannot run during MCP startup. Each has a dedicated wizard: `sap-ai-dev --setup-integration`, `--setup-datasphere`, `--setup-process-automation`, `--setup-btp`, and `--setup-cloud-alm`.
 
 | MCP entry | Package | Launches | Use when the agent needs to |
 | --- | --- | --- | --- |
@@ -206,6 +234,10 @@ The companion entries are optional and are launched through `npx` only when the
 | `browser-validation` | `@playwright/mcp` | `playwright-mcp` | Open BAS previews, smoke-test Fiori/UI flows, collect screenshots, and verify browser runtime behavior |
 | `hana-cloud-inspector` | `sap-ai-dev-toolkit` | `sap-ai-hana` | Inspect a bound HANA Cloud HDI schema using read-only catalog tools and capped row reads |
 | `integration-suite` | `sap-ai-dev-toolkit` | `sap-ai-integration` | Build, deploy, undeploy, and monitor Cloud Integration content (iFlows, value mappings, script collections, security material, Partner Directory) and manage API Management providers, proxies, policies, products, and key value maps |
+| `datasphere` | `sap-ai-dev-toolkit` | `sap-ai-datasphere` | Model and administer SAP Datasphere: spaces, users, roles, database users, connections, modeling objects and packages, task chains, replication flows, Data Marketplace, consumption queries and Open SQL |
+| `process-automation` | `sap-ai-dev-toolkit` | `sap-ai-process-automation` | Inspect and operate SAP Build Process Automation across all eight BPA APIs: process definitions, workflow instances with contexts, logs and errors, stuck instances, user tasks and the user inbox, decisions, API triggers, automations, process visibility, administration jobs, process starts and business events |
+| `sap-btp` | `sap-ai-dev-toolkit` | `sap-ai-btp` | Audit and operate the BTP core platform through your own `btp login --sso`: account hierarchy, entitlements and quotas, Service Manager instances and service keys, destinations, trust, and Cloud Connectors |
+| `cloud-alm` | `sap-ai-dev-toolkit` | `sap-ai-cloud-alm` | Observe and triage SAP landscapes with SAP Cloud ALM: health, exception and alert hotspots per tier, Integration & Exception Monitoring records, monitoring events with CPI and SLG1 handoffs, analytics, feature and transport status, and confirmation-gated alert closing |
 
 Recommended profiles:
 
@@ -304,6 +336,136 @@ This separate checker permits configured-management GETs and exact OAuth token P
 Lifecycle release changes: signed bounded collections and precise access evidence; continuable release validation/deployment and private configuration-bound recovery; server-side API analytics; native monitoring/promotion readiness; guarded policy/consumer changes; separately credentialed optional metadata adapters and complete native handoffs.
 Live AnalyticsService compatibility uses distinct derived aliases and an explicit source-record count. A zero-record aggregate with null sums is `no_data`, not a failed request or healthy traffic; null metrics with nonzero records remain partial.
 
+### SAP Datasphere
+
+For direct CLI use with your Datasphere user, run **`sap-ai-dev --datasphere objects views list --space MY_SPACE`**. The first command asks for your tenant URL and opens SAP's browser sign-in. On the first run, provide two fresh temporary codes: one to download the command catalog, then one to run the requested command. Later commands reuse the tenant URL and catalog and ask only for one fresh code. SAP's CLI is bundled; no OAuth client or separate CLI installation is required for this flow.
+
+From a source checkout, use `npm run datasphere -- objects views list --space MY_SPACE`. Supply `--host https://<tenant>.eu20.hcs.cloud.sap` to choose a tenant explicitly; a copied Datasphere page URL or a bare tenant host also works. The tenant URL is saved in `~/.config/sap-ai-dev-toolkit/datasphere-cli.json`, and discovery metadata is cached privately per tenant and CLI version. Codes stay in private temporary files removed when the command finishes. Native SAP command options, exit codes, and write confirmations apply. `--datasphere --help` and `--datasphere --version` work without signing in. In a remote terminal, use the printed browser URL; after the catalog is initialized, `--passcode-stdin` reads a code through standard input without opening a browser. For a fresh automation environment, first initialize with `--datasphere config cache init --host <tenant URL> --passcode-stdin`, then supply a new code to the requested command. Use Node.js 20–24, as supported by the bundled SAP CLI.
+
+The separate `datasphere` stdio MCP server covers the whole Datasphere surface reachable from outside the UI: spaces, space users, database users, workload, global and scoped roles, users, objects of every type (including packages, task chains, replication flows and data access controls), connections, TLS certificates, the Data Marketplace, the Consumption catalog/relational/analytical APIs, the Tasks API, and read/execute access to the space Open SQL schema through a Datasphere database user (including the `"DWC_GLOBAL"` data-lake procedures). Typed tools cover the frequent flows; discovery-driven generic tools cover every other — and future — `datasphere` CLI command. All writes require exact confirmation strings; secrets are write-only.
+
+Sign in once with **`sap-ai-dev --setup-datasphere`**: a **Technical user** OAuth client (client credentials) covers objects, tasks, Data Marketplace, connections, certificates and consumption data; **Your user** (Interactive Usage, redirect URI `http://localhost:8080`) additionally covers spaces, users, roles, database users and workload. Credentials are verified online and stored only for you in `~/.config/sap-ai-dev-toolkit/datasphere.json` (0600) — never in `mcp.json`; environment variables (`DATASPHERE_URL`, `DATASPHERE_TOKEN_URL`, `DATASPHERE_CLIENT_ID`, `DATASPHERE_CLIENT_SECRET`, optionally `DATASPHERE_AUTH`, `DATASPHERE_AUTHORIZATION_URL`, `DATASPHERE_REFRESH_TOKEN` and `DATASPHERE_SQL_*`) always win. `sap-ai-datasphere --check` verifies catalog, CLI and SQL access.
+
+#### Tool catalog
+
+The server registers 32 tools by default; the two Open SQL tools appear only when a Datasphere database user is configured. The live `tools/list` response is authoritative; full contracts live in [tools.md](tools.md#separate-optional-sap-datasphere-server). Every state-changing tool requires its exact confirmation string before any tenant call, and all results pass through secret redaction.
+
+**Connection, consumption and reconciliation**
+
+| Tool | Behavior |
+| --- | --- |
+| `datasphere_connection_info` | Report the connected tenant, auth mode, credential source, CLI package version and Open SQL configuration; optional online verification, never returns credentials. |
+| `datasphere_list_spaces` | List the spaces visible to the OAuth client (Consumption catalog API). |
+| `datasphere_list_assets` | List assets exposed for consumption — all visible assets or one space's. |
+| `datasphere_get_asset_metadata` | Fetch the `$metadata` document of a relational or analytical asset (XML, capped at 64 KiB). |
+| `datasphere_query_relational` | Read rows of a relational asset: projection, filter, ordering, paging and count. |
+| `datasphere_query_analytical` | Read aggregated data from an analytic model; `$select` names the requested measures and dimensions. |
+| `datasphere_reconcile` | Compare an asset against expected figures — row count for relational assets, measure totals for analytic models, each with a tolerance. |
+
+**Object lifecycle**
+
+| Tool | Behavior |
+| --- | --- |
+| `datasphere_list_objects` | List objects of one type in a space: technical/business name, type, semantic usage, status, deployment and change dates. |
+| `datasphere_read_object` | Read one object: design-time definition, run-time state, or the complete object. |
+| `datasphere_create_object` | Create an object from a CSN definition and read it back. Confirmation `CREATE DATASPHERE <OBJECT_TYPE> <SPACE>.<TECHNICAL_NAME>`. |
+| `datasphere_update_object` | Update an object from a CSN definition, guarded by `expected_changed_on`. Confirmation `UPDATE DATASPHERE <OBJECT_TYPE> <SPACE>.<TECHNICAL_NAME>`. |
+| `datasphere_delete_object` | Delete an object from a space. Confirmation `DELETE DATASPHERE <OBJECT_TYPE> <SPACE>.<TECHNICAL_NAME>`. |
+| `datasphere_export_package` | Export a package from a space. Confirmation `EXPORT DATASPHERE PACKAGE <SPACE>.<TECHNICAL_NAME>`. |
+| `datasphere_build_local_table_csn` | Convert a BW/Data-Dictionary-style field list (name, label, ddic type, length, decimals, key) into a local-table CSN definition. Pure conversion, no tenant call. |
+
+**Connections, task chains and replication flows**
+
+| Tool | Behavior |
+| --- | --- |
+| `datasphere_list_connections` | List the connections of a space. |
+| `datasphere_validate_connection` | Validate one connection of a space. |
+| `datasphere_list_task_logs` | List the task logs of one object (task chain, replication flow) through the Tasks REST API. |
+| `datasphere_get_task_log` | Read one task log by id; detail level `status`, `details` or `extended`. |
+| `datasphere_run_task_chain` | Start a task chain run and return its log id. Confirmation `RUN DATASPHERE TASK CHAIN <SPACE>.<TASK_CHAIN>`. |
+| `datasphere_retry_task_chain` | Retry the last failed run of a task chain. Confirmation `RETRY DATASPHERE TASK CHAIN <SPACE>.<TASK_CHAIN>`. |
+| `datasphere_cancel_task_chain` | Cancel one run by log id. Confirmation `CANCEL DATASPHERE TASK CHAIN RUN <SPACE>.<LOG_ID>`. |
+| `datasphere_replication_flow` | Run, pause, resume, stop or inspect a replication flow — or pause/resume/restart a single object within it. State changes require `<ACTION> DATASPHERE REPLICATION FLOW <SPACE>.<TECHNICAL_NAME>`. |
+
+**Data Marketplace**
+
+| Tool | Behavior |
+| --- | --- |
+| `datasphere_list_data_providers` | List the Data Marketplace providers visible to the tenant. |
+| `datasphere_list_data_products` | List Data Marketplace products. |
+| `datasphere_read_data_product` | Read one product definition by uuid — the template for `datasphere_create_data_product`. |
+| `datasphere_create_data_product` | Create a data product in status Draft from a definition. Confirmation `CREATE DATASPHERE DATA PRODUCT`. |
+| `datasphere_set_data_product_status` | List, delist or deactivate a product. Confirmation `SET DATASPHERE DATA PRODUCT <UUID> <LIFECYCLE_STATUS>`. |
+| `datasphere_install_data_product` | Install a product into a space. Confirmation `INSTALL DATASPHERE DATA PRODUCT <UUID> INTO <SPACE>`. |
+
+**Generic Datasphere CLI commands**
+
+| Tool | Behavior |
+| --- | --- |
+| `datasphere_list_commands` | List the CLI command catalog discovered from the tenant, optionally filtered by prefix, with the auth mode each command supports. Compact by default; use `include_parameters` with a prefix for parameter lists. |
+| `datasphere_describe_command` | Show the authoritative `--help` text of one CLI command from the tenant catalog. |
+| `datasphere_run_read_command` | Run any discovered read-only CLI command (spaces list, objects read, marketplace, tasks status, ...) with validated options. |
+| `datasphere_run_command` | Run any discovered CLI command; changing commands require confirmation `RUN DATASPHERE <COMMAND>` (deletions `DELETE DATASPHERE <COMMAND>`). |
+
+**Open SQL schema** — only with `DATASPHERE_SQL_*` configured
+
+| Tool | Behavior |
+| --- | --- |
+| `datasphere_sql_query` | Run one read-only `SELECT` against the space Open SQL schema of the database user; rows capped by `max_rows`. |
+| `datasphere_sql_execute` | Execute one SQL statement (DDL, DML, or a documented `"DWC_GLOBAL"` data-lake procedure call). Confirmation `EXECUTE DATASPHERE SQL AS <USER>`. |
+
+The **SAP Datasphere Developer** agent plus the `datasphere-development` and `datasphere-administration` skills drive modeling and administration; the **SAP BW Datasphere Migration Specialist** agent plus `bw-datasphere-migration` plan and run BW → Datasphere migrations (Data Product Generator path or rebuild path), using the read-only ABAP destination server (`GetTable`, `GetTableContents`, `RunQuery`, `SearchObject`) for the BW inventory and `datasphere_reconcile` for BW-versus-Datasphere figures.
+
+### SAP Build Process Automation
+
+The separate `process-automation` stdio MCP server covers all eight SAP Build Process Automation APIs of the Business Accelerator Hub package (Workflow, Inbox, Decisions, Unified API triggers, Automation Execution, Automation Monitoring, Visibility Scenarios, Visibility Workspace) plus business events with 51 tools. It connects through a service key of a `process-automation-service` instance (plan `standard`; client-secret key). It reads process definitions, workflow instances with their contexts, outputs, execution logs, error messages, attributes and roles, finds erroneous, suspended and long-running instances, lists the user-task queue behind My Inbox / SAP Fiori Task Center, evaluates and regression-tests deployed decisions, and traces a business key from an ABAP/RAP event or CPI message to the workflow instance and its open tasks. Every write requires an exact confirmation string; asynchronous operations return a `job_id` for `bpa_get_job`.
+
+| API family | Tools |
+|---|---|
+| Connection | `bpa_connection_info` |
+| Workflow definitions | `bpa_list_process_definitions`, `bpa_get_process_definition`, `bpa_delete_process_definition`, `bpa_list_task_definitions`, `bpa_delete_form` |
+| Instances | `bpa_list_instances`, `bpa_get_instance`, `bpa_find_stuck_instances`, `bpa_trace_process`, `bpa_start_instance`, `bpa_change_instance_status`, `bpa_update_instance_context`, `bpa_update_instance_roles`, `bpa_delete_instances`, `bpa_send_message` |
+| User tasks | `bpa_list_tasks`, `bpa_get_task`, `bpa_complete_task`, `bpa_update_tasks`, `bpa_update_task_context` |
+| Administration / jobs | `bpa_export_workflow_data`, `bpa_purge_workflow_data`, `bpa_get_job` |
+| Inbox (Task Consumption Model, user-centric) | `bpa_inbox_list_tasks`, `bpa_inbox_get_task`, `bpa_inbox_list_task_definitions`, `bpa_inbox_task_action`, `bpa_inbox_list_substitution_rules`, `bpa_inbox_create_substitution_rule`, `bpa_inbox_change_substitution_rule` |
+| Decisions | `bpa_invoke_decision`, `bpa_test_decision` |
+| API triggers (Unified) | `bpa_list_api_triggers`, `bpa_get_api_trigger`, `bpa_execute_api_trigger` |
+| Automations (execution + monitoring; environment API key) | `bpa_list_automation_triggers`, `bpa_get_automation_trigger`, `bpa_list_automation_jobs`, `bpa_start_automation`, `bpa_export_automation_data` |
+| Visibility scenarios | `bpa_list_visibility_scenarios`, `bpa_get_visibility_scenario`, `bpa_process_visibility_scenario`, `bpa_clear_visibility_data`, `bpa_list_visibility_events`, `bpa_push_visibility_events` |
+| Visibility workspace | `bpa_list_visibility_workspace_scenarios`, `bpa_list_visibility_instances`, `bpa_get_visibility_instance` |
+| Business events | `bpa_send_business_event` |
+
+The Inbox shows the signed-in user's tasks (with technical auth the technical client's inbox, normally empty). Automation triggers, jobs and BAM/archived-job exports need an environment API key (`irpa-api-key`, scopes such as `TRIGGER_READ`, `TRIGGER_EXECUTE`, `BAM_DOWNLOAD`, `JOB_DATA_DOWNLOAD`); Unified API triggers and process starts send it as `api-key` when configured. Exports are written to a new local file (absolute path, never overwritten, mode 0600).
+
+Set it up with **`sap-ai-dev --setup-process-automation`**: paste the service key (or the path to its `.json` file) and choose **Technical client** (client credentials; actions run as the key's technical user) or **Your user** (authorization code with the same client; actions are attributed to you and need `ProcessAutomationAdmin` or `ProcessAutomationParticipant`). After verification the wizard optionally asks for an environment API key (Control Tower > Environments > API Keys) and a default environment id for API triggers and process starts; press Enter to skip either. Credentials are verified online and stored only for you in `~/.config/sap-ai-dev-toolkit/process-automation.json` (0600) — never in `mcp.json`. Environment variables win: `PROCESS_AUTOMATION_URL`, `PROCESS_AUTOMATION_TOKEN_URL`, `PROCESS_AUTOMATION_CLIENT_ID`, `PROCESS_AUTOMATION_CLIENT_SECRET` (all four together), else `PROCESS_AUTOMATION_SERVICE_KEY`; optionally `PROCESS_AUTOMATION_AUTH` and `PROCESS_AUTOMATION_REFRESH_TOKEN`. `PROCESS_AUTOMATION_API_KEY` and `PROCESS_AUTOMATION_ENVIRONMENT_ID` are optional and override the stored values. `sap-ai-process-automation --check` verifies Workflow API access. Full tool contracts and confirmation strings live in [tools.md](tools.md#separate-optional-sap-build-process-automation-server).
+
+The **SAP Process Automation Developer** agent plus the `process-automation-development` skill drive inspection, decision testing, confirmed operations, asynchronous job tracking and end-to-end tracing.
+
+### SAP BTP platform administration
+
+The separate `sap-btp` stdio MCP server (`sap-ai-btp`) wraps your installed SAP BTP CLI and uses your own `btp login --sso` session (sessions last at most 12 hours); the toolkit stores no credentials. Every subaccount-scoped tool takes the subaccount GUID explicitly; the server never runs `btp target`.
+
+| Area | Tools |
+| --- | --- |
+| Connection | `btp_connection_info` |
+| Accounts, entitlements and quotas | `btp_get_account_hierarchy`, `btp_list_entitlements`, `btp_check_quota` |
+| Service Manager instances and service keys | `btp_list_service_instances`, `btp_get_service_instance`, `btp_list_service_keys`, `btp_get_service_key`, `btp_create_service_instance`, `btp_create_service_key` |
+| Destinations, trust and Cloud Connectors | `btp_list_destinations`, `btp_get_destination`, `btp_get_trust`, `btp_list_cloud_connectors`, `btp_check_destination` |
+
+Service-key credentials, instance parameters and destination secrets are always redacted; fetch a full key in your own terminal with `btp get services/binding --name <key> --subaccount <id>`. Creating an instance (`CREATE BTP SERVICE INSTANCE <name>`, after a quota check) or a service key (`CREATE BTP SERVICE KEY <name>`) requires the exact confirmation string; creation parameters go through a private temporary file, never the command line. Cloud Connector data comes from the BTP-side Connectivity API and needs a Connectivity `api_access` instance with a client-secret service key. `btp_check_destination` reports pass/warn/fail/unknown checks; principal-propagation items only visible in the Cloud Connector or backend (system and CA certificates, synchronized trust, X.509 principal type, CERTRULE) are reported as `unknown`. There are no delete, entitlement-assignment, destination, trust or role-collection write tools.
+
+Set it up with **`sap-ai-dev --setup-btp`**: the wizard locates `btp` on PATH (or `BTP_CLI`), checks the session, offers to run `btp login --sso` when it expired, and saves only the CLI location to `~/.config/sap-ai-dev-toolkit/btp.json` (0600). `BTP_CLI` and `BTP_CLIENTCONFIG` in the MCP host environment win. `sap-ai-btp --check` verifies the CLI and the session from the shell.
+
+The **SAP BTP Infrastructure Admin** agent plus the `btp-platform-administration` skill drive account and entitlement audits, instance and key automation, and destination/trust/Cloud Connector verification.
+
+### SAP Cloud ALM
+
+The separate `cloud-alm` stdio MCP server connects to SAP Cloud ALM for operations through a service key of a "SAP Cloud ALM API" instance (plan `standard`, client-secret binding; client credentials only). Its 11 tools read landscape objects and their role tiers, summarize exception, health and alert hotspots per DEV/TEST/PROD tier, read raw Integration & Exception Monitoring records, monitoring events and job runs, run analytics queries, and report feature lifecycle status with transport ids. `calm_triage_incident` returns ready-to-use arguments for the Integration Suite companion's `cpi_list_message_logs` and the ABAP destination's `get_application_log`, so the agent can correlate a Cloud ALM alert with live CPI message processing logs and SLG1. The only write, `calm_close_event_situation`, needs `CLOSE CALM EVENT SITUATION <event_situation_id>` (or `… BY EXTERNAL ID <external_id>`).
+
+Set it up with **`sap-ai-dev --setup-cloud-alm`**: paste the service key (or the path to its `.json` file); it is verified against the Landscape and Analytics APIs and stored only for you in `~/.config/sap-ai-dev-toolkit/cloud-alm.json` (0600) — never in `mcp.json`. Environment variables win: `CLOUD_ALM_SERVICE_KEY`, or `CLOUD_ALM_URL` + `CLOUD_ALM_TOKEN_URL` + `CLOUD_ALM_CLIENT_ID` + `CLOUD_ALM_CLIENT_SECRET`. `sap-ai-cloud-alm --check` verifies access from the shell.
+
+The **SAP DevOps & Observability Specialist** agent plus the `cloud-alm-operations` skill drive hotspot finding, triage across Cloud ALM, CPI and ABAP, and deployment tracking. Cloud ALM exposes no per-system transport import status, so the agent never infers TEST/PROD arrival from Features data.
+
 ## 💡 Example requests
 
 Once the destination server is enabled in your chat's tools picker, ask for outcomes instead of manually orchestrating individual SAP operations:
@@ -502,12 +664,12 @@ During npm postinstall, or after interactive `sap-ai-dev --setup` in BAS or on a
 | Gemini CLI | `$HOME/.gemini/skills/` | — | `$HOME/.gemini/settings.json` |
 | opencode | `$XDG_CONFIG_HOME/opencode/skills/` (default `$HOME/.config/opencode/skills/`) | `$XDG_CONFIG_HOME/opencode/agents/<id>.md` (as subagents) | Not changed automatically |
 | Pi Coding Agent | `$PI_CODING_AGENT_DIR/skills/` (default `$HOME/.pi/agent/skills/`) | `$PI_CODING_AGENT_DIR/prompts/<id>.md` (as `/` prompt commands) | `$PI_CODING_AGENT_DIR/mcp.json` (default `$HOME/.pi/agent/mcp.json`) |
-| Oh My Pi (OMP) | `$HOME/.omp/agent/skills/` (overridden by `PI_CONFIG_DIR` or `PI_CODING_AGENT_DIR`) | — | `$HOME/.omp/agent/mcp.json` (same overrides) |
+| Oh My Pi (OMP) | `$HOME/.omp/agent/skills/` (overridden by `PI_CONFIG_DIR` or `PI_CODING_AGENT_DIR`) | `$HOME/.omp/agent/agents/<id>.md` (as task agents named `<id>`; same overrides) | `$HOME/.omp/agent/mcp.json` (same overrides) |
 | Cline | `$HOME/.cline/skills/` | — | Not changed automatically |
 | Roo Code | `$HOME/.roo/skills/` | — | Not changed automatically |
 | Windsurf / Devin Desktop | `$XDG_CONFIG_HOME/devin/skills/` (default `$HOME/.config/devin/skills/`); Windows: `$HOME/.codeium/windsurf/skills/` | — | `$XDG_CONFIG_HOME/devin/mcp_config.json` (default `$HOME/.config/devin/mcp_config.json`); Windows: `%APPDATA%\devin\mcp_config.json` |
 
-All 14 skills use the portable `SKILL.md` format and are installed verbatim. The 5 agents use Copilot's `.agent.md` format, so they are installed as native custom agents for harnesses with a custom-agent mechanism (GitHub Copilot, Claude Code, opencode), with frontmatter adapted where needed. Pi receives equivalent prompt templates (`/abap-developer`, `/sap-solution-architect`, and so on) because Pi exposes reusable personas through prompts rather than a separate custom-agent file type. Selecting several harnesses duplicates the small markdown payloads on disk.
+All 22 skills use the portable `SKILL.md` format and are installed verbatim. The 12 agents use Copilot's `.agent.md` format, so they are installed as native custom agents for harnesses with a custom-agent mechanism (GitHub Copilot, Claude Code, opencode, OMP), with frontmatter adapted where needed. OMP receives them as task agents named after their file id (`abap-developer`, `sap-solution-architect`, and so on), with Copilot-specific tool-picker wording rewritten for OMP's MCP tool inventory. Pi receives equivalent prompt templates (`/abap-developer`, `/sap-solution-architect`, and so on) because Pi exposes reusable personas through prompts rather than a separate custom-agent file type. Selecting several harnesses duplicates the small markdown payloads on disk.
 
 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.
 
@@ -950,6 +1112,8 @@ If `GetSystemInfo` or `RunQuery` reports a CSRF-token fetch failure, the runtime
 
 **`MCP config ... contains invalid JSON`** usually means one of three things, all healed automatically by setup: the file starts with a byte-order mark (Windows PowerShell `>` redirection, `Set-Content`, or Notepad's "UTF-8 with BOM" mode — invisible in editors and terminals), it contains comments or trailing commas (VS Code reads `mcp.json` as JSONC), or setup raced an editor save and read a torn file (retried once before healing). Unrecoverable content is backed up as `mcp.json.<kind>-<timestamp>.bak` and replaced; the backup path is printed in the setup warning. On older versions, re-save the file as UTF-8 without BOM (VS Code: "Change File Encoding → Save with Encoding → UTF-8") and rerun `sap-ai-dev --setup`.
 
+**SAP shows "You are already logged on to the system in the following sessions" with dozens of entries** (or SM04 fills with HTTP sessions of your user): runtimes before 0.9.9924 opened one SAP security session per parallel tool call until the first session cookie came back. Upgrade and restart the MCP server; each runtime process now logs on once and shares that session. Sessions left by older processes expire with the system's HTTP session timeout, or end them with **Cancel all existing logons** at the next SAP GUI logon. Every MCP server start (editor reload, `/mcp reload`, a second editor) is still one process with one logon of its own.
+
 If automatic runtime provisioning fails, check network access and the package's supported platform. You can install Go manually or set `GO_BINARY` as an explicit fallback. A trusted prebuilt executable can be supplied with `SAP_AI_DEV_TOOLKIT_BINARY`.
 
 ## 🧑‍💻 Development
@@ -962,6 +1126,8 @@ npm test
 
 Install the checkout globally with `npm run install:local`, or use `npm run install:local -- --link` for a live workspace link. Verify without reinstalling using `npm run install:local -- --verify`: it checks the installed package version and, for a link, the actual workspace target, and refuses an outdated snapshot or a different checkout. After installation, exercise the installed executable with `sap-ai-integration --check`; npm-linked commands resolve their real entrypoint before starting the server.
 
+The ABAP runtime is upstream VSP pinned to one commit and patched with `patches/*.patch` (applied in the order listed in `scripts/build-vsp.mjs`). `npm run build:vsp` clones it into `.build/vibing-steampunk`, applies the patches, and builds `dist/`; run `go test ./pkg/adt/ ./internal/...` there to exercise a patch. To change a patch, commit the patched tree in `.build`, edit, and write `git diff` back to the patch file.
+
 The package repository is [grknylmz/sap-ai-dev-toolkit](https://github.com/grknylmz/sap-ai-dev-toolkit).
 
 ## 🚀 Publishing to npm

package/dist/checksums.txt

@@ -1,5 +1,5 @@
-31902921b0d2b5349be8e392aae3632ca8c3dee26950ea30c412ec83271722f3  vsp-linux-x64
-df39b324fe419348f5157954d56c5f8d60e5bac28edc04a56e90c380b67de10d  vsp-linux-arm64
-754338fbbbe66260cac722677753b16a0a2f23127b947bf1f3a189044fa66c32  vsp-darwin-x64
-ac153052b5d02b2f19a536623c957369af3412f5bbe2eed0f6a43e8597ed0f1b  vsp-darwin-arm64
-722c6de352719dd9374932b56546189a75c29800e74da3bdcb0308b2034248ac  vsp-win32-x64.exe
+8666b8126f460a6b1b3c64c5523eb5b942d2c1a795f406936cfb9e0f1c62e68c  vsp-linux-x64
+e920aa3fda3b3b5020893e0869737c8a2ca049db9eafdd9e19dfca021cefe24b  vsp-linux-arm64
+e56bf5a23cdbf889bff499a399b53fd247b2ef26b44e0d4affa6a20382303abd  vsp-darwin-x64
+3c794b489af29237480a27353cb3e98af35de1d81ad03761304da10fdb5df89d  vsp-darwin-arm64
+0c35ddd18c2edfb10486a056143ad438d79a737f55839e3adfb882b29438fa1a  vsp-win32-x64.exe

package/inventory.md

@@ -293,3 +293,63 @@ Confirmations are checked before network access but do not replace user approval
 
 Read-only connected verification: `node scripts/check-live-integration.mjs --window-minutes 60 --top 3 --json`. Its GET-only management guard is separate from the mutating `test:live:integration` runner. Missing optional credentials remain `live_unverified`; successful reads are not health, continuous delivery or native promotion proof.
 
+
+## Separate optional SAP Datasphere server
+
+The standalone `sap-ai-datasphere` companion is not a BAS-proxy child and never destination-prefixed. It exposes 34 distinct possible tool names; actual `tools/list` is authoritative because the two SQL tools register only when a Datasphere database user is configured (`DATASPHERE_SQL_*`). Writes require exact confirmation strings; CLI/REST results are secret-redacted.
+
+Authentication is one Datasphere OAuth client, either **technical** (client credentials) or **interactive** (authorization code + refresh token, stored user-only in `~/.config/sap-ai-dev-toolkit/datasphere.json`). Technical clients may run only `configuration certificates`, `marketplace`, `objects`, `spaces connections` and `tasks` CLI commands; every other command needs interactive auth and is flagged per command by `datasphere_list_commands` (`usable_with_current_auth`).
+
+| Group | Tools | Behavior |
+|---|---|---|
+| Connection | `datasphere_connection_info` | Tenant/token host, auth mode, credential source, CLI package version, SQL summary, admin availability; optional read-only verification. |
+| Consumption | `datasphere_list_spaces`, `datasphere_list_assets`, `datasphere_get_asset_metadata`, `datasphere_query_relational`, `datasphere_query_analytical`, `datasphere_reconcile` | Consumption catalog/relational/analytical reads; parameters become `(Name='value')/Set` segments; reconciliation compares row counts or measure totals with tolerances. |
+| Objects | `datasphere_list_objects`, `datasphere_read_object`, `datasphere_create_object`, `datasphere_update_object`, `datasphere_delete_object`, `datasphere_export_package` | CSN lifecycle through the pinned `@sap/datasphere-cli` child runner; updates guarded by `expected_changed_on`; create/update return a read-back. |
+| Connections & tasks | `datasphere_list_connections`, `datasphere_validate_connection`, `datasphere_list_task_logs`, `datasphere_get_task_log`, `datasphere_run_task_chain`, `datasphere_retry_task_chain`, `datasphere_cancel_task_chain`, `datasphere_replication_flow` | Connections via CLI; task chains and logs via the Tasks REST API; replication flow actions incl. per-object pause/resume/restart. |
+| Data Marketplace | `datasphere_list_data_providers`, `datasphere_list_data_products`, `datasphere_read_data_product`, `datasphere_create_data_product`, `datasphere_set_data_product_status`, `datasphere_install_data_product` | Provider/product discovery, Draft creation from a definition, lifecycle status changes, installation into a space. |
+| CSN | `datasphere_build_local_table_csn` | Pure field-list → local-table CSN conversion (BW `/BIC/` stripping, DDIC type mapping, duplicate detection). No tenant call. |
+| Generic CLI | `datasphere_list_commands`, `datasphere_describe_command`, `datasphere_run_read_command`, `datasphere_run_command` | Tenant-discovery-driven catalog of every CLI command with exact `--help`; read-only or confirmed execution with managed-option rejection and automatic `--force` for `x-user-to-confirm` operations. |
+| Open SQL | `datasphere_sql_query`, `datasphere_sql_execute` | Single-SELECT reads wrapped with `LIMIT` on the configured database user's schema; confirmation-gated single-statement executes (incl. `"DWC_GLOBAL"` data-lake procedures). Grants of the database user are the boundary. |
+
+## Separate optional SAP Build Process Automation server
+
+The standalone `sap-ai-process-automation` companion is not a BAS-proxy child and never destination-prefixed. It exposes 51 tools covering all eight SAP Build Process Automation APIs of the Business Accelerator Hub package (81 operations) plus business events. Authentication is a `process-automation-service` service key, either **technical** (client credentials) or **interactive** (authorization code + refresh token with the same client, stored user-only in `~/.config/sap-ai-dev-toolkit/process-automation.json`). Optional `PROCESS_AUTOMATION_API_KEY` / `PROCESS_AUTOMATION_ENVIRONMENT_ID` (or the optional setup prompts) supply an environment API key and default environment. Writes require exact confirmation strings; results are secret-redacted; asynchronous operations return a `job_id`; exports write to a new local file (0600, never overwritten).
+
+| Group | Tools | Behavior |
+|---|---|---|
+| Connection | `bpa_connection_info` | API/UAA host, auth mode, credential source, task attribution, API key configured, default environment; optional read-only verification. |
+| Workflow definitions | `bpa_list_process_definitions`, `bpa_get_process_definition`, `bpa_delete_process_definition`, `bpa_list_task_definitions`, `bpa_delete_form` | Deployed definitions with model, sample start context and versions; task definitions. Classic definition undeploy (async) `DELETE BPA DEFINITION <definition_id>`; classic form undeploy `DELETE BPA FORM <form_id>`. |
+| Instances | `bpa_list_instances`, `bpa_get_instance`, `bpa_find_stuck_instances`, `bpa_trace_process`, `bpa_start_instance`, `bpa_change_instance_status`, `bpa_update_instance_context`, `bpa_update_instance_roles`, `bpa_delete_instances`, `bpa_send_message` | Filtered lists (repeated status = OR); context (capped at 48 KiB or one fragment), outputs, logs, errors, attributes, roles; stuck instances; tracing by id, business key or text. Writes: `START BPA PROCESS <definition_id>`, `<ACTION> BPA INSTANCE <instance_id>` (CANCEL/SUSPEND/RESUME/RETRY, status checked first), `MERGE BPA CONTEXT <instance_id>` / `REPLACE BPA CONTEXT <instance_id>`, `UPDATE BPA ROLES <instance_id>`, `DELETE BPA INSTANCES <count>` (async), `SEND BPA MESSAGE <message_definition_id>` (classic workflows). |
+| User tasks | `bpa_list_tasks`, `bpa_get_task`, `bpa_complete_task`, `bpa_update_tasks`, `bpa_update_task_context` | The task queue behind My Inbox / Fiori Task Center; one task with context and attributes. `COMPLETE BPA TASK <task_id>` (open tasks only), `UPDATE BPA TASKS <count>` (async), `UPDATE BPA TASK CONTEXT <task_id>`. |
+| Administration / jobs | `bpa_export_workflow_data`, `bpa_purge_workflow_data`, `bpa_get_job` | ZIP export to a new local file; irreversible tenant purge (async) `PURGE ALL BPA WORKFLOW DATA`; async job status. |
+| Inbox | `bpa_inbox_list_tasks`, `bpa_inbox_get_task`, `bpa_inbox_list_task_definitions`, `bpa_inbox_task_action`, `bpa_inbox_list_substitution_rules`, `bpa_inbox_create_substitution_rule`, `bpa_inbox_change_substitution_rule` | User-centric TCM OData (`ProcessAutomationParticipant`; technical auth shows the technical client's inbox). `<ACTION> BPA INBOX TASK <instance_id>` (CLAIM/RELEASE/FORWARD), `CREATE BPA SUBSTITUTION FOR <user>`, `<ACTION> BPA SUBSTITUTION <rule_id>` (ENABLE/DISABLE/DELETE). |
+| Decisions | `bpa_invoke_decision`, `bpa_test_decision` | Rule-service evaluation and subset-match test cases; no side effects. |
+| API triggers (Unified) | `bpa_list_api_triggers`, `bpa_get_api_trigger`, `bpa_execute_api_trigger` | Process API triggers per environment (optional `api-key`); start a process or resume a "Wait for an API Call" step via `execution_id`; `EXECUTE BPA TRIGGER <trigger_uid>`. |
+| Automations | `bpa_list_automation_triggers`, `bpa_get_automation_trigger`, `bpa_list_automation_jobs`, `bpa_start_automation`, `bpa_export_automation_data` | Automation Execution/Monitoring with a required environment API key (`TRIGGER_READ`, `TRIGGER_EXECUTE`, `BAM_DOWNLOAD`, `JOB_DATA_DOWNLOAD`); `START BPA AUTOMATION <trigger_uid>`; BAM/archived-job CSV inline or to a new local file. |
+| Visibility scenarios | `bpa_list_visibility_scenarios`, `bpa_get_visibility_scenario`, `bpa_process_visibility_scenario`, `bpa_clear_visibility_data`, `bpa_list_visibility_events`, `bpa_push_visibility_events` | Scenario definitions, executions, acquired events and acquisition errors (`PVAdmin`); `PROCESS BPA VISIBILITY <scenario_id>`, `CLEAR BPA VISIBILITY DATA <scenario_id>`; `PUSH BPA VISIBILITY EVENTS <count>` (`PVEventSender`). |
+| Visibility workspace | `bpa_list_visibility_workspace_scenarios`, `bpa_list_visibility_instances`, `bpa_get_visibility_instance` | Workspace scenarios, scenario instances with OData options, one instance with phases, paths and steps (`PVOperator`/`PVRestrictedOperator`). |
+| Business events | `bpa_send_business_event` | CloudEvents to `/internal/be/v1/events` for event-triggered processes; `SEND BPA EVENT <type>`. |
+
+## Separate optional SAP BTP platform administration server
+
+The standalone `sap-ai-btp` companion is not a BAS-proxy child and never destination-prefixed. It exposes 15 tools over the user's installed SAP BTP CLI and their own `btp login --sso` session; the toolkit stores no credentials (only the CLI location in `~/.config/sap-ai-dev-toolkit/btp.json`, written by `sap-ai-dev --setup-btp`; `BTP_CLI` / `BTP_CLIENTCONFIG` win). Writes are limited to two confirmation-gated creates; results are secret-redacted and service-key credentials are always redacted.
+
+| Group | Tools | Behavior |
+|---|---|---|
+| Connection | `btp_connection_info` | CLI path and source, config file, acting user; optional `btp --version` and global-account check. |
+| Accounts and entitlements | `btp_get_account_hierarchy`, `btp_list_entitlements`, `btp_check_quota` | Directories and subaccounts; entitlements at global-account, directory or subaccount scope; quota verdict `available` / `not_entitled` / `insufficient_quota` / `assignment_not_ready`. |
+| Instances and keys | `btp_list_service_instances`, `btp_get_service_instance`, `btp_list_service_keys`, `btp_get_service_key`, `btp_create_service_instance`, `btp_create_service_key` | Service Manager instances with offering/plan names, last operation and keys; redacted parameters and credentials. `CREATE BTP SERVICE INSTANCE <name>` (after a quota check), `CREATE BTP SERVICE KEY <name>`; parameters via a private temporary file. |
+| Destinations, trust, Cloud Connectors | `btp_list_destinations`, `btp_get_destination`, `btp_get_trust`, `btp_list_cloud_connectors`, `btp_check_destination` | Destinations without secrets; IdP and destination trust with certificate expiry; Cloud Connectors and exposed systems via a Connectivity `api_access` key; pass/warn/fail/unknown destination and principal-propagation checks. |
+
+## Separate optional SAP Cloud ALM server
+
+The standalone `sap-ai-cloud-alm` companion is not a BAS-proxy child and never destination-prefixed. It exposes 11 tools over the SAP Cloud ALM API (Landscape, Analytics, Raw Data Outbound Logs, Features, Event Situations). Authentication is a service key of a "SAP Cloud ALM API" instance (plan `standard`, client-secret binding) with client credentials only, from `CLOUD_ALM_SERVICE_KEY` / `CLOUD_ALM_URL` + `CLOUD_ALM_TOKEN_URL` + `CLOUD_ALM_CLIENT_ID` + `CLOUD_ALM_CLIENT_SECRET` or stored user-only in `~/.config/sap-ai-dev-toolkit/cloud-alm.json` by `sap-ai-dev --setup-cloud-alm`. All tools are read-only except the confirmation-gated alert close; results are secret-redacted.
+
+| Group | Tools | Behavior |
+|---|---|---|
+| Connection | `calm_connection_info` | API/token host, auth, credential source; optional read-only Landscape and Analytics verification. |
+| Landscape | `calm_list_landscape`, `calm_get_landscape_health` | Landscape objects with LMS id, tenant role, service type, system number and logical systems; exceptions (EXM), critical/warning Health Monitoring metrics and EVENTS alerts for at most 30 services grouped by role tier, each source failing independently. |
+| Records and triage | `calm_list_monitoring_records`, `calm_triage_incident` | Raw OTLP records for `im`, `exm.im`, `exm.jam`, `iep`, `jam.run`, `bsm` (60-minute windows, `bsm` up to 31 days, `next_offset` paging); per-service triage with alert counts, events, errors, messages and `cpi_list_message_logs` / `get_application_log` handoff arguments. |
+| Analytics | `calm_list_analytics_providers`, `calm_describe_analytics_provider`, `calm_query_analytics` | Authorized providers, provider fields and attribute values, one query summed/maxed per dimension combination or raw. |
+| Features | `calm_list_features`, `calm_get_feature` | Feature lifecycle status with transport ids; one feature by UUID or display id, or the features linked to a transport id. No per-system import status. |
+| Event situations | `calm_close_event_situation` | Close an alert by id or external id (mapped tickets closed unless `notify_ticketing: false`); `CLOSE CALM EVENT SITUATION <event_situation_id>` or `CLOSE CALM EVENT SITUATION BY EXTERNAL ID <external_id>`. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sap-ai-dev-toolkit",
-  "version": "0.9.9922",
+  "version": "0.9.9924",
   "description": "SAP AI development toolkit for BAS, ABAP, RAP, CAP, HANA Cloud, Fiori, UI5, and MCP",
   "author": "Gurkan Yilmaz",
   "type": "module",
@@ -10,6 +10,7 @@
   "dependencies": {
     "@abaplint/core": "2.119.0",
     "@modelcontextprotocol/sdk": "1.32.1",
+    "@sap/datasphere-cli": "2026.22.0",
     "@sap/hana-client": "2.30.27",
     "fflate": "0.8.3",
     "terminal-kit": "^3.1.4",
@@ -20,12 +21,17 @@
     "sap-ai-dev": "src/launcher.mjs",
     "sap-ai-dev-toolkit": "src/launcher.mjs",
     "sap-ai-hana": "src/hana-inspector.mjs",
-    "sap-ai-integration": "src/integration-server.mjs"
+    "sap-ai-integration": "src/integration-server.mjs",
+    "sap-ai-datasphere": "src/datasphere-server.mjs",
+    "sap-ai-process-automation": "src/process-automation-server.mjs",
+    "sap-ai-btp": "src/btp-server.mjs",
+    "sap-ai-cloud-alm": "src/cloud-alm-server.mjs"
   },
   "scripts": {
     "postinstall": "node scripts/postinstall.mjs",
     "install:local": "node scripts/install-local.mjs",
     "test": "node --test --test-force-exit test/*.test.mjs",
+    "datasphere": "node src/launcher.mjs --datasphere",
     "test:live:s4h": "node scripts/run-live-s4h.mjs",
     "test:live:integration": "node scripts/run-live-integration.mjs",
     "test:visibility": "node --test test/setup.test.mjs test/terminal-ui.test.mjs",