docs(sdk): schéma project-plugins.json v1 + assignation skills/tools agents — #283 (project-plugin-assignments: workflow install→enable→assign→relaunch, schéma complet plugins/agents/skills/tools camelCase, ordre d'injection natif puis plugin, tombstones inertes uninstall/reinstall, validation UI/API idempotente vs édition manuelle, reload plugin ≠ relance agent; liens croisés manifest/codex-skills/README; QA verte: npm run build, liens docs vérifiés)

README.md

@@ -17,6 +17,7 @@ exports `activate(ctx)`.
 - [Services](docs/services.md): workspace, tasks, tooling, events, config, terminal and windows facades.
 - [Packaging And Distribution](docs/packaging-distribution.md): build output, archive layout, hot reload and dependency rules.
 - [Codex Skills And IdeA Plugins](docs/codex-skills-and-idea-plugins.md): separate IdeA-native plugin skills from Codex plugin discovery.
+- [Project Plugin Assignments](docs/project-plugin-assignments.md): enable plugins per project and assign skills and MCP tools to agents.
 
 The installable example lives in [`examples/hello-plugin`](examples/hello-plugin).
 It demonstrates a menu command, storage, background-task feedback, a React layout

docs/codex-skills-and-idea-plugins.md

@@ -40,7 +40,9 @@ loading.
 For multi-harness IdeA agent skills, declare `contributes.skills` in
 `idea-plugin.json`, ship the referenced Markdown files inside the package,
 install the plugin in IdeA, enable it in the target project, and assign the
-skills to the target agents.
+skills to the target agents. See
+[Project Plugin Assignments](project-plugin-assignments.md) for the project
+settings schema and the complete install, enable, assign, and relaunch workflow.
 
 For Codex-specific plugin skills, install the Codex plugin through the Codex
 plugin mechanism for the intended scope, then assign or enable those skills

docs/manifest.md

@@ -177,6 +177,10 @@ Skill contribution rules:
 - Installing a plugin globally is not enough: a project must enable the plugin,
   then assign the skill to the target agent.
 
+See [Project Plugin Assignments](project-plugin-assignments.md) for the
+`.ideai/project-plugins.json` schema, validation rules, assignment order, and
+agent relaunch requirements.
+
 `contributes.layouts` is the only surface for plugin layouts. The same layout
 contribution can be mounted inside an IdeA layout cell or opened in a detached OS
 window. Do not add a separate manifest contribution type for windows.

docs/project-plugin-assignments.md

@@ -0,0 +1,154 @@
+# Project Plugin Assignments
+
+IdeA installs plugin packages globally, but enables their capabilities per
+project and assigns agent-facing capabilities per agent. Project choices are
+stored in the project-owned `.ideai/project-plugins.json` file.
+
+The normal workflow is:
+
+1. Install the plugin globally in IdeA.
+2. Enable the installed plugin for the target project.
+3. Assign selected plugin skills and MCP tools to each target agent.
+4. Relaunch the agent so its capability snapshot includes the new assignments.
+
+Installation alone does not enable a plugin in a project. Enabling a plugin does
+not automatically grant all of its capabilities to every agent.
+
+## Version 1 Schema
+
+The current schema version is `1`. A complete example is:
+
+```json
+{
+  "version": 1,
+  "plugins": [
+    {
+      "pluginId": "com.example.unity-plugin",
+      "enabled": true
+    }
+  ],
+  "agents": [
+    {
+      "agentId": "2a0e42e2-3c5f-4f30-a679-034b460cd59e",
+      "skills": [
+        {
+          "pluginId": "com.example.unity-plugin",
+          "skillId": "unity.build-debug"
+        }
+      ],
+      "tools": [
+        {
+          "pluginId": "com.example.unity-plugin",
+          "serverId": "unity-editor",
+          "toolName": "unity_build"
+        }
+      ]
+    }
+  ]
+}
+```
+
+The top-level fields are:
+
+- `version`: required schema version. It must currently be `1`; unsupported
+  versions are rejected.
+- `plugins`: project activation entries. Each entry contains the stable global
+  `pluginId` and an `enabled` boolean.
+- `agents`: per-agent assignments. Each entry identifies an IdeA project agent
+  by `agentId` and contains ordered `skills` and `tools` arrays.
+
+An agent skill reference contains:
+
+- `pluginId`: the id from the owning plugin's `idea-plugin.json`.
+- `skillId`: the stable `contributes.skills[].id` within that plugin.
+
+An agent MCP tool reference contains:
+
+- `pluginId`: the id from the owning plugin's `idea-plugin.json`.
+- `serverId`: the stable `contributes.mcpServers[].id` within that plugin.
+- `toolName`: the exact tool name advertised by that MCP server. The UI accepts
+  this name as text because a dynamic MCP tool catalogue is not yet available.
+
+Missing `plugins`, `agents`, `skills`, or `tools` arrays default to empty arrays
+when IdeA reads the document. Prefer writing them explicitly for clarity and
+forward-compatible review.
+
+## Assignment And Injection Order
+
+Array order is significant. IdeA keeps plugin skill assignments in the order in
+which they were added. At agent launch, IdeA resolves the agent's native skills
+first, in agent-manifest order, then its plugin skills in the order stored in
+`agents[].skills`. Unavailable assignments are skipped without reordering the
+remaining skills.
+
+The resolved skill catalogue is injected into the agent's orchestration context
+before the agent persona. Each supported harness receives the same ordered
+IdeA-native capability snapshot. The skill body remains read-only package
+content and is available through `idea_skill_read` only when that skill was
+resolved for the launched agent.
+
+## Tombstones
+
+Plugin activation entries and agent assignments are intentionally retained when
+a plugin, skill, or MCP server is temporarily missing. These dangling entries
+are tombstones: they preserve project intent across uninstall/reinstall or a
+temporary manifest change.
+
+A tombstone is inert. IdeA skips it when resolving capabilities, and the project
+settings UI marks stale skill or server references as missing or obsolete. The
+UI lets users remove those references explicitly. Reinstalling and activating a
+matching plugin makes a retained assignment resolvable again.
+
+Disabling a plugin also keeps its assignments. They become effective again only
+after the plugin is enabled and runtime-active for the project.
+
+## UI And API Validation
+
+Prefer the project plugin settings UI or its backing API commands over manual
+editing. They apply the following rules:
+
+- Enabling requires the plugin package to be installed globally. Disabling a
+  missing plugin is allowed so a retained activation can be cleared.
+- Assigning a skill requires an existing project agent, an enabled and
+  runtime-active plugin, and a matching `contributes.skills[].id`.
+- Assigning a tool requires an existing project agent, an enabled and
+  runtime-active plugin, a matching `contributes.mcpServers[].id`, and a
+  non-empty `toolName`.
+- Assign and unassign operations are idempotent. Assigning an existing reference
+  does not duplicate it; unassigning a missing reference is harmless.
+- Unassign operations remain available for tombstones, so stale references can
+  be removed even when their plugin capability no longer resolves.
+
+The project settings read API returns both the persisted document and the
+currently installed plugin manifests. The UI uses this catalogue to offer only
+skills and MCP servers from plugins enabled for the project, while still
+surfacing persisted tombstones.
+
+## Manual Editing
+
+The file is project-owned and may be edited manually, for example in version
+control or automation. Stop or relaunch affected agents around the edit, keep
+the document valid JSON, preserve `version: 1`, use the real project agent UUID,
+and copy plugin, skill, and server ids exactly from the plugin manifest.
+
+Manual editing bypasses the mutation checks described above. A syntactically
+valid document may therefore contain duplicates, unknown agents, disabled or
+missing plugins, unknown capability ids, or an invalid tool name. Such entries
+may remain inert or fail later operations. Use the UI/API whenever possible to
+receive immediate validation and idempotent updates.
+
+## Reloading Plugins And Relaunching Agents
+
+These actions solve different problems:
+
+- Reload the plugin after rebuilding or replacing its installed package. Reload
+  refreshes the plugin manifest, runtime bundle, contributions, and packaged
+  skill Markdown. It does not change project activation or agent assignments.
+- Relaunch the agent after enabling or disabling a project plugin, changing its
+  skill/tool assignments, or manually editing `.ideai/project-plugins.json`.
+  Agent capabilities are resolved into a launch-time snapshot, so an already
+  running agent does not acquire assignment changes retroactively.
+
+When both package content and assignments changed, reload the plugin first,
+confirm it is enabled for the project, update the assignments, then relaunch the
+agent.