docs(sdk): feedback visible via windows.open + séparation Codex skills documentées — commands-and-feedback (surface normative + exemple), layouts-react (type↔contributes.layouts, capacité ui), manifest (exemple complet menu+layout+ui), windows (contrat ui, retour structuré), packaging-distribution (idea_plugin_install_from_directory, sémantique plugin_reloaded/ESM), nouveau codex-skills-and-idea-plugins, README (lien) — #280 QA verte

docs/windows.md

@@ -10,9 +10,18 @@ await ctx.services?.windows.open({
 });
 ```
 
+`windows.open` is the public API for commands that need to make feedback visible
+to a human. A command handler may still return structured data, but menu clicks
+do not currently guarantee that return value is displayed.
+
 ## Contract
 
 - `layoutType` must match a layout type declared by the calling plugin.
+- The plugin must declare `capabilities: ["ui"]` when it relies on plugin
+  layouts/windows as a human-facing surface. Add `"tooling"` only when the
+  plugin also uses tooling/workspace/task services.
+- There is no `contributes.windows` manifest key. Windows always host an
+  existing `contributes.layouts` layout.
 - The host validates the plugin is runtime-active and the layout exists before
   opening or focusing the window.
 - Reopening the same plugin/layout pair focuses the existing window.
@@ -38,9 +47,13 @@ The returned `label` is a host-owned window identity. Treat it as opaque.
 
 ```ts
 ctx.commands?.registerCommand("hello-plugin.open-dashboard", async () => {
-  return ctx.services?.windows.open({
+  const win = await ctx.services?.windows.open({
     layoutType: "hello-plugin.dashboard",
     state: { source: "menu" }
   });
+
+  return win
+    ? { status: "opened", message: "Opened dashboard.", alreadyOpen: win.alreadyOpen }
+    : { status: "skipped", reason: "ui-service-unavailable", message: "UI service unavailable." };
 });
 ```