PluginOS 0.5.0: TYPO3 Bootstrap feedback sweep

INSTALL.md

@@ -1,32 +1,33 @@
 # Installing PluginOS
 
-PluginOS has two halves: **the Figma plugin** (runs inside Figma) and **the MCP server** (runs alongside your agent tool). Install both — it takes about 60 seconds combined.
+PluginOS has two halves: **the Figma plugin** (runs inside Figma) and **the MCP server** (runs alongside your agent tool). Install both.
 
----
+| You're using       | Install method                                            | Time |
+| ------------------ | --------------------------------------------------------- | ---- |
+| Claude Desktop     | [Double-click `pluginos.dxt`](#claude-desktop)            | 30 s |
+| Claude Code        | [`/plugin marketplace add LSDimi/pluginos`](#claude-code) | 30 s |
+| Cursor             | [`npx pluginos install --with-agent cursor`](#cursor)     | 45 s |
+| Any other MCP host | [`npx pluginos install`](#any-other-mcp-host)             | 60 s |
 
-## Step 1 — Install the Figma plugin
+---
 
-1. Go to the [latest release](https://github.com/LSDimi/pluginos/releases/latest) on GitHub.
-2. Download `pluginos-bridge-v<version>.zip` and unzip it anywhere on your disk.
-3. In Figma Desktop, open: **Menu → Plugins → Development → Import plugin from manifest…**
-4. Select the `manifest.json` inside the unzipped folder.
-5. PluginOS Bridge now appears under **Plugins → Development → PluginOS Bridge**. Run it once to open the panel.
+## Claude Desktop
 
-The plugin works in any Figma file. You can keep it open while switching files.
+1. Download [`pluginos.dxt`](https://github.com/LSDimi/pluginos/releases/latest) from the latest release.
+2. Double-click the file. Claude Desktop opens an install dialog — confirm.
+3. Restart Claude Desktop.
 
----
+The MCP server auto-starts. To install the bridge plugin in Figma:
 
-## Step 2 — Install the MCP server in your agent tool
-
-Pick the path that matches your setup:
+```bash
+npx pluginos install
+```
 
-### Claude Desktop — recommended, one click
+Then in Figma: **Plugins → Development → Import plugin from manifest** → `~/.pluginos/bridge/manifest.json`.
 
-1. Download `pluginos.dxt` from the [latest release](https://github.com/LSDimi/pluginos/releases/latest).
-2. Double-click the `.dxt` file. Claude Desktop opens an install prompt — accept it.
-3. Restart Claude Desktop. The PluginOS MCP server auto-starts on launch.
+---
 
-### Claude Code
+## Claude Code
 
 Paste both commands into Claude Code:
 
@@ -35,39 +36,56 @@ Paste both commands into Claude Code:
 /plugin install pluginos
 ```
 
-The MCP server runs whenever Claude Code is open.
+The MCP server registers automatically. To install the bridge plugin in Figma:
+
+```bash
+npx pluginos install
+```
+
+Then in Figma: **Plugins → Development → Import plugin from manifest** → `~/.pluginos/bridge/manifest.json`.
+
+---
+
+## Cursor
+
+```bash
+npx pluginos install --with-agent cursor
+```
+
+This installs the bridge plugin AND writes the MCP server entry into `~/.cursor/mcp.json` (preserving any other servers you have). Restart Cursor.
 
-### Cursor / other MCP-compatible agents
+Then in Figma: **Plugins → Development → Import plugin from manifest** → `~/.pluginos/bridge/manifest.json`.
 
-1. Make sure Node 18+ is available (`node -v`).
-2. Add this to your agent's MCP config (Cursor: **Settings → MCP Servers**, or edit `~/.cursor/mcp.json` directly):
+---
+
+## Any other MCP host
 
-   ```json
-   {
-     "mcpServers": {
-       "pluginos": { "command": "npx", "args": ["-y", "pluginos@latest"] }
-     }
-   }
-   ```
+```bash
+npx pluginos install --with-agent generic
+```
 
-3. Restart the agent. It spawns the MCP server on first use.
+This installs the bridge plugin and prints the MCP config JSON for you to copy into your agent's config file. Restart your agent.
+
+Then in Figma: **Plugins → Development → Import plugin from manifest** → `~/.pluginos/bridge/manifest.json`.
 
 ---
 
 ## Verifying the install
 
 1. Open the PluginOS Bridge plugin in Figma. The status pill should turn green ("Connected") within a few seconds.
-2. In your agent, ask: "list available pluginos operations". You should get a list of 39 operations.
+2. In your agent, ask: "list available pluginos operations". You should get a list of operations and their categories.
 
 ---
 
 ## Troubleshooting
 
 **Plugin shows "Not connected" forever.**
-The MCP server isn't running. Confirm your agent tool is open (Claude Desktop, Claude Code, or Cursor) and that Step 2 above is complete. The Bridge plugin cannot start the server itself — it's sandboxed.
+The MCP server isn't running. Confirm your agent tool is open and the install above is complete. The bridge plugin cannot start the server itself — it's sandboxed.
 
 **Plugin shows "Update needed".**
-Bridge plugin and MCP server are on incompatible major versions. Reinstall the latest of both (see steps above).
+Bridge plugin and MCP server are on incompatible versions. Click the **Copy** button next to the update command in the plugin pane, paste it into a terminal, and re-run.
+
+Manual equivalent: `npx pluginos@latest install` to refresh both halves.
 
 **Port conflict — "All PluginOS ports in use".**
 PluginOS scans ports 9500–9510. If all are in use, free one (`lsof -i :9500` then kill the process).
@@ -82,7 +100,7 @@ The MCP server tracks files by Figma's `fileKey`. The Bridge plugin in each file
 To make PluginOS Bridge available to every designer in your org without manual install:
 
 1. In Figma, open **Organization Settings → Plugins**.
-2. Upload the contents of the unzipped `pluginos-bridge-v<version>.zip` as a private plugin.
+2. Upload `~/.pluginos/bridge/` contents (or the contents of `pluginos-bridge-v<version>.zip` from GitHub releases) as a private plugin.
 3. All org members see it under their Plugins menu.
 
 The MCP server still installs per user — that's the part that runs locally next to the agent.

README.md

@@ -101,7 +101,7 @@ The agent calls write operations to create frames, set text, and modify fills 
 
 ```
 Agent ── MCP (stdio) ──> PluginOS Server ── WebSocket ──> Bridge Plugin ──> Figma
-         5 tools           thin router        localhost      26 operations    full API
+         5 tools           thin router        localhost      many operations  full API
          ~600 tokens       routes by name     ports 9500-    executes locally figma.*
          per turn          + params only      9510           returns summaries
 ```