makeables 0.4.0 → 0.5.0

package/README.md

@@ -15,7 +15,7 @@ makeables skills get core
 
 Ask: “Use the makeables guide. Make an experimental badge from my photo at ~/Pictures/me.png. Show me both sides, then let’s refine it here.”
 
-For personalized badges, the guide asks for a photo if one is missing and asks before installing agent-browser for visual inspection. Cards and stickers do not need a portrait. It offers ai-cli only when a requested image transformation needs it. Image generation uses your own AI Gateway credentials and credits.
+For personalized badges, the guide asks for a photo if one is missing. It prefers native widget or browser inspection; agent-browser is optional. Cards and stickers do not need a portrait. It offers ai-cli only when a requested image transformation needs it. Image generation uses your own AI Gateway credentials and credits.
 
 ## Cards from the terminal
 
@@ -48,13 +48,52 @@ makeables doctor --json
 
 The installed skill is a small discovery stub maintained in [makeables-community](https://github.com/crafter-station/makeables-community). These guides and image-transfer helpers are bundled into the CLI, so no repository checkout or external skill script is required. Report bugs and feature requests in the [community issue tracker](https://github.com/crafter-station/makeables-community/issues).
 
-## One live preview
+## Embedded MCP App
+
+The skill chooses **MCP Apps → built-in browser → CLI + inline PNG**, based on
+capabilities actually available in the coding session. It does not open an
+external browser or install another integration to produce a preview.
+
+To connect the optional stdio server, use your host's MCP configuration with an
+existing directory dedicated to your designs:
+
+```json
+{
+  "mcpServers": {
+    "makeables": {
+      "command": "makeables",
+      "args": ["mcp", "--root", "/absolute/path/to/designs"]
+    }
+  }
+}
+```
+
+The exact configuration location depends on the host. Start a new host session
+if required; having the CLI installed does not register its MCP tools.
+`makeables_preview` exposes a self-contained MCP App: front/back, text and
+sticker-finish controls, plus host-mediated PNG, JSON and portable-package
+exports. The file is the state, shared with the CLI. Revisions reject stale
+edits. File access stays inside `--root`; there is no cloud service, login,
+localhost fetch or publication tool. Cards and badges show flat artwork;
+stickers use the same material PNG renderer as the website. A personalized
+badge opens from a complete package containing its portrait and participant.
+
+Hosts without MCP Apps receive text and a PNG from the same preview tool. A host
+without downloads can keep the local file and use CLI exports. To inspect the
+full layer editor or animated materials, continue with the same design in the
+built-in browser.
+
+`makeables render --file design.makeables.json --out preview.png` also exports
+the validated PNG from an editable portable package, keeping its portrait and
+other assets intact.
+
+## One live browser preview
 
 ```sh
 makeables studio start
 ```
 
-This opens your operating system’s default browser. An agent with a built-in browser panel should use `makeables studio start --no-open --json` and open the returned URL there. Keep the process running and reuse that tab while iterating.
+This prints a local URL without opening a browser. An agent with a built-in browser panel opens that URL there. Keep the process running and reuse that tab while iterating. `--open` explicitly opts into the operating system’s default browser; `--no-open` remains supported. If there is no built-in browser, use CLI rendering and show the resulting image in the conversation.
 
 The local preview embeds the real [badge editor](https://makeables.dev/make/badge) [card editor](https://makeables.dev/make/card) or [sticker editor](https://makeables.dev/make/sticker). Its local connection uses the same tools, revision checks and validation as native WebMCP. It works without native WebMCP in the preview browser. One tab owns a session; no separate browser-state synchronization is implied.
 
@@ -167,7 +206,7 @@ See [the portable format](../../docs/submission-format.md) for package limits an
 
 ### Stickers
 
-`makeables studio start --product sticker` opens the same Design Studio and CLI bridge.
+`makeables studio start --product sticker` prints the URL for the same Design Studio and CLI bridge.
 `makeables new sticker --style good-energy --out sticker.json` creates the shared document.
 Use `makeables skills get stickers` for material editing, PNG/JSON export and the common
 `submit --dry-run` / consent / review lifecycle. Sticker packages contain a transparent