docs(sdk): clarify pluginRoot scope for runtime plugins — #285 (activation-context: ActivateContext n'expose ni répertoire d'installation ni racine package ni file URL; commands-and-feedback + services: runCommand project/workspace-scoped, aucune résolution package-relative des scripts packagés; manifest: substitution ${pluginRoot}/${appDataDir} étendue par l'hôte uniquement dans contributes.mcpServers command/args/env/cwd; QA verte: npm run build, cohérence champs vs types SDK vérifiée)

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`:

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.

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:

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