From 5f9c2f919335c590e01c23016658f6a5ccfbc473 Mon Sep 17 00:00:00 2001
From: Blomios <blomios@gmail.com>
Date: Tue, 8 Sep 2026 17:19:57 +0200
Subject: [PATCH] =?UTF-8?q?docs(sdk):=20clarify=20pluginRoot=20scope=20for?=
 =?UTF-8?q?=20runtime=20plugins=20=E2=80=94=20#285=20(activation-context:?=
 =?UTF-8?q?=20ActivateContext=20n'expose=20ni=20r=C3=A9pertoire=20d'instal?=
 =?UTF-8?q?lation=20ni=20racine=20package=20ni=20file=20URL;=20commands-an?=
 =?UTF-8?q?d-feedback=20+=20services:=20runCommand=20project/workspace-sco?=
 =?UTF-8?q?ped,=20aucune=20r=C3=A9solution=20package-relative=20des=20scri?=
 =?UTF-8?q?pts=20packag=C3=A9s;=20manifest:=20substitution=20${pluginRoot}?=
 =?UTF-8?q?/${appDataDir}=20=C3=A9tendue=20par=20l'h=C3=B4te=20uniquement?=
 =?UTF-8?q?=20dans=20contributes.mcpServers=20command/args/env/cwd;=20QA?=
 =?UTF-8?q?=20verte:=20npm=20run=20build,=20coh=C3=A9rence=20champs=20vs?=
 =?UTF-8?q?=20types=20SDK=20v=C3=A9rifi=C3=A9e)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/activation-context.md    |  8 +++++++-
 docs/commands-and-feedback.md | 20 ++++++++++++++++++++
 docs/manifest.md              | 12 ++++++++++++
 docs/services.md              |  7 +++++++
 4 files changed, 46 insertions(+), 1 deletion(-)

diff --git a/docs/activation-context.md b/docs/activation-context.md
index e8217bc..afe2175 100644
--- a/docs/activation-context.md
+++ b/docs/activation-context.md
@@ -27,7 +27,7 @@ focused project at invocation/render time.
 
 ## Context Fields
 
-- `pluginId`, `pluginDisplayName`, `version`: host-provided identity.
+- `pluginId`: host-provided plugin identity.
 - `logger`: `debug`, `info`, `warn`, `error`.
 - `subscriptions`: push disposables returned by command/layout/watch
   registrations.
@@ -41,6 +41,12 @@ focused project at invocation/render time.
 The context never exposes internal IdeA gateways or Tauri commands. Use
 `ctx.services` and the registration APIs instead.
 
+`ActivateContext` does not expose the plugin installation directory, package
+root, archive root or a file URL that plugins can convert into a local path.
+Plugin runtime code must treat packaged files as unavailable to
+`ctx.services.tasks.runCommand()` unless a dedicated public SDK API documents
+otherwise. Workspace services resolve project-owned paths only.
+
 ## Disposal
 
 Push every returned disposable to `ctx.subscriptions`:
diff --git a/docs/commands-and-feedback.md b/docs/commands-and-feedback.md
index 6b349d0..c86dde9 100644
--- a/docs/commands-and-feedback.md
+++ b/docs/commands-and-feedback.md
@@ -43,6 +43,9 @@ Check preconditions before calling `runCommand()`:
 - `ownerAgentId` is a real agent id when the work is owned by an agent workflow.
   Do not use all-zero placeholders in production.
 - `cwd` is relative to the project root.
+- `command`, `args` and `cwd` do not resolve package-relative plugin resources.
+  Do not use `runCommand()` to launch scripts shipped inside the plugin package;
+  there is no public runtime `pluginRoot` path in `activate(ctx)`.
 - `command` and `args` are separate values. Do not shell-join user input.
 
 If any required precondition fails, return a skipped result:
@@ -196,3 +199,20 @@ await ctx.services?.tasks.runCommand({
 
 This creates misleading Work history, uses a placeholder owner and turns a
 precondition failure into a fake task. Return `status: "skipped"` instead.
+
+Do not try to reach packaged plugin scripts through workspace-relative paths:
+
+```ts
+await ctx.services?.tasks.runCommand({
+  projectId: project.id,
+  ownerAgentId,
+  label: "Run packaged tests",
+  command: "scripts/run-unity-tests.sh",
+  cwd: "."
+});
+```
+
+`scripts/run-unity-tests.sh` above is resolved like any other executable visible
+from the project task environment; it is not resolved relative to the plugin
+package. Use a project-owned script or an executable available on `PATH` until a
+dedicated packaged-resource API exists.
diff --git a/docs/manifest.md b/docs/manifest.md
index 9eb579a..98bccaa 100644
--- a/docs/manifest.md
+++ b/docs/manifest.md
@@ -247,6 +247,18 @@ Contribution ids are part of the runtime contract:
 - `services.windows.open({ layoutType })` only accepts a layout type declared by
   the calling plugin.
 
+## MCP Server Paths
+
+`contributes.mcpServers` entries are resolved by the host before starting a
+declared MCP server. In `command`, `args`, `env` and `cwd`, the host expands:
+
+- `${pluginRoot}` to the installed plugin package root.
+- `${appDataDir}` to the host-owned application data directory.
+
+This substitution is limited to manifest-declared MCP server startup. It is not
+available from `activate(ctx)`, `ctx.services.workspace` or
+`ctx.services.tasks.runCommand()`.
+
 ## Validation
 
 Use the SDK validator in tests or build tooling:
diff --git a/docs/services.md b/docs/services.md
index bbe2969..3371aad 100644
--- a/docs/services.md
+++ b/docs/services.md
@@ -37,6 +37,13 @@ Key APIs:
 Use `runCommand()` only after preconditions are satisfied. `ownerAgentId` must be
 a real agent id when work belongs to an agent workflow.
 
+`runCommand()` is project/workspace scoped. Its `cwd` option is a relative path
+under the project root, and `command`/`args` are not resolved against the
+calling plugin's package. The SDK does not currently provide a public
+`pluginRoot` or package-path resolver for runtime command handlers. Packaged
+scripts cannot be launched through `runCommand()` by referring to their
+package-relative path.
+
 ## Tooling
 
 `services.tooling.diagnose()` checks executables, environment values and files