@evref-bl/pharo-agent 0.15.0 → 0.16.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pharo-agent",
   "displayName": "Pharo Agent",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "Terminal-first Pharo image setup for coding agents.",
   "author": {
     "name": "Evref-BL",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evref-bl/pharo-agent",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "private": false,
   "description": "Terminal-first Pharo integration for coding agents.",
   "license": "Apache-2.0",
@@ -32,8 +32,8 @@
     "test": "node --test"
   },
   "dependencies": {
-    "@evref-bl/pharo-mcp": "3.4.1",
-    "@evref-bl/plexus": "0.14.1",
+    "@evref-bl/pharo-mcp": "3.5.0",
+    "@evref-bl/plexus": "0.15.0",
     "@modelcontextprotocol/sdk": "1.32.2"
   },
   "devDependencies": {

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "pharo-agent",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "Terminal-first Pharo image setup for coding agents.",
   "author": {
     "name": "Evref-BL",

package/skills/pharo-feedback/SKILL.md

@@ -63,7 +63,7 @@ instead of a new issue.
 One issue per problem; findings that share a cause make one issue. Title it
 with what goes wrong, in the tool's own terms. Keep the body short:
 
-- **Tool:** its name; `pharo-agent 0.15.0`; the image's Pharo version, which
+- **Tool:** its name; `pharo-agent 0.16.0`; the image's Pharo version, which
   `image_list` gives; the host you run in.
 - **What happened:** what you asked for and what came back, the error quoted
   and trimmed.

package/skills/pharo-setup/SKILL.md

@@ -5,21 +5,20 @@ description: Enable or refresh Pharo image tooling in the current Pharo project.
 
 Run this only when the user asks to enable or refresh Pharo tooling in this project.
 
-From the project root, run the released CLI that matches this plugin:
+From the project root, run the released CLI that matches this plugin, naming
+the host this chat runs in: `--host claude` in Claude Code, `--host codex` in
+Codex, `--host opencode` in OpenCode.
 
 ```sh
-npx --yes @evref-bl/pharo-agent@0.15.0 init --host claude
+npx --yes @evref-bl/pharo-agent@0.16.0 init --host claude
 ```
 
-Name the host this chat runs in: `--host claude` in Claude Code,
-`--host codex` in Codex, `--host opencode` in OpenCode.
-The command writes no host configuration. It adds a conditional instruction
-block and this project's own files, so Pharo guidance stays out of unrelated
-work.
+It writes the project's Pharo guide, skills and references, and a block in the
+host's guide that points to them; no host configuration. Re-running it after
+an upgrade replaces those files and keeps image declarations and image code.
 
-To get the image's tools as MCP tools in Claude Code, enable this plugin for
-this project rather than configuring a server by hand. Commit
-`.claude/settings.json`:
+In Claude Code, enable the plugin for this project in `.claude/settings.json`;
+the next session gets the tools:
 
 ```json
 {
@@ -35,26 +34,11 @@ this project rather than configuring a server by hand. Commit
 }
 ```
 
-A host reads that file when a session starts, so the tools appear in the next
-one. Enabling it per project keeps every other project untouched.
-
-After upgrading the plugin/CLI, re-run the setup command from the project root
-with the same host to refresh the generated guide and copied skills/references.
-Those files are overwritten; keep project-specific guidance outside the host's
-managed block and outside generated/copied paths. Omit `--mount-root` to retain
-existing settings. Image declarations, runtime state, and live image code are
-preserved. This refresh does not install a newer package or upgrade image tools.
-
-Setup initializes the current directory, creating `plexus.json` with
-no image when it is absent. Register one before the first
-`pharo-agent image start`:
+Then declare the project's first image, its default:
 
 ```sh
 pharo-agent image templates
 pharo-agent image add dev --template '<launcher template name>'
 ```
 
-`image templates` names what the launcher offers, with the category of each.
-
-After setup, read `pharo.AGENTS.md` in this chat before doing Pharo work. A
-new chat picks up the conditional project guidance automatically.
+Read `pharo.AGENTS.md` before doing Pharo work.

package/src/help.js

@@ -3,75 +3,61 @@ import { hostChoices, hostIds } from "./hosts.js";
 const commands = {
   init: {
     usage: `init --host <${hostChoices()}> [--mount-root <path>]`,
-    description: "Initialize the current project for the required agent host. Write its managed instruction block,\n"
-      + "pharo.AGENTS.md, and workflow skills/references. Re-run to refresh those generated files.\n"
-      + "The mount root defaults to .pharo-agent/mounts; omit --mount-root to keep an existing setting.",
+    description: "Write this project's Pharo guide, skills and references for the host. Re-run to refresh\n"
+      + "them. --mount-root sets where sources mount, .pharo-agent/mounts by default.",
     example: `init --host ${hostIds[0]}`,
   },
   "image list": {
     usage: "image list",
-    description: "List the project's declared images and the default one, with the mount and\n"
-      + "projection port of each image this project has running. An image this project\n"
-      + "started that has since exited is listed as exited.",
+    description: "List the declared images, the default, and the mount and port of each running one.",
     example: "image list",
   },
   "image templates": {
     usage: "image templates",
-    description: "List available launcher templates and their categories. A name in several categories\n"
-      + "needs --category when passed to image add.",
+    description: "List the templates images can be made from, with their categories.",
     example: "image templates",
   },
   "image add": {
     usage: "image add <id> --template <name> [--category <name>] [--profile <id>]",
-    description: "Declare an image with a required id and template name; image start creates it later.\n"
-      + "Use --category for an ambiguous template name and --profile to choose a launcher profile.\n"
-      + "The first declared image becomes the default.",
-    example: "image add dev --template '<template name>'",
+    description: "Declare an image; image start creates it. Name it after what it is for, like a branch.\n"
+      + "The first declared image is the default. --category is for a name two categories offer.",
+    example: "image add pretty-print-formatter --template '<template name>'",
   },
   "image use": {
     usage: "image use <id>",
-    description: "Make the required declared image the project's default. It may already be running.",
+    description: "Make an image the default.",
     example: "image use dev",
   },
   "image remove": {
     usage: "image remove <id>",
-    description: "Remove the required image declaration. Stop the image first. Its image files are kept.\n"
-      + "Removing the default image clears the default selection.",
+    description: "Drop an image's declaration. Stop it first; its files are kept.",
     example: "image remove dev",
   },
   "image start": {
     usage: "image start [<id>]",
-    description: "Create if needed and start an image with its Pharo tools. Omit the id to use the\n"
-      + "project's default image. Images already running stay running. A source projection is\n"
-      + "mounted on macOS with fuse-t; elsewhere the image starts without one and says so.\n"
-      + "Pharo versions outside the MCP support range start without tools or a projection.",
+    description: "Create if needed and start an image, the default one without an id. Others keep running.\n"
+      + "On macOS with fuse-t its source mounts as files.",
     example: "image start dev",
   },
   "image stop": {
     usage: "image stop [<id>] [--all]",
-    description: "Stop the named image and any source projection it has, or the project's default\n"
-      + "image when no id is given. Use --all to stop every image this project started.",
+    description: "Stop an image and its source mount, the default one without an id, or --all of them.",
     example: "image stop dev",
   },
   mcp: {
     usage: "mcp [--image <id>]",
-    description: "Serve this project's images as a command-scoped stdio MCP server. Omit\n"
-      + "--image to use the project's default image. It starts whether or not an image\n"
-      + "is running: image_start starts one and the image's own tools join the list. The\n"
-      + "server exits with this command, and the plugin's .mcp.json starts it for a host.",
+    description: "Serve this project's images as a stdio MCP server, as the plugin does for a host.",
     example: "mcp --image dev",
   },
   "pharo list": {
     usage: "pharo list [--image <id>]",
-    description: "List a running image's advertised tools. Omit --image to use the project's default image.\n"
-      + "Use tool_search and tool_get to discover and inspect the rest of its catalogue.",
+    description: "List a running image's advertised tools. tool_search and tool_get find the rest.",
     example: "pharo list",
   },
   pharo: {
     usage: "pharo <tool> [arguments-json] [--image <id>]",
-    description: "Call a tool in a running image. Arguments must be a JSON object and default to {}.\n"
-      + "Omit --image to use the project's default image. Inspect the tool's schema with tool_get\n"
-      + "before calling it; a failed tool result makes the command exit unsuccessfully.",
+    description: "Call a tool in a running image with a JSON object of arguments, {} by default.\n"
+      + "Read its schema with tool_get first.",
     example: 'pharo tool_get \'{"name":"class_search"}\'',
   },
 };

package/src/init.js

@@ -110,64 +110,34 @@ function assertRoutingResolves(routing, templates) {
 function pharoGuide() {
   return `# Pharo project guide
 
-${generatedBy}. Edits here are replaced the next time it runs.
+${generatedBy}. Edits here are replaced the next time it
+runs: re-run it after upgrading the plugin, and keep your own instructions
+elsewhere.
 
-After upgrading the plugin/CLI, re-run \`pharo-agent init --host <host>\` from
-the project root with the same host to refresh this guide and the copied skills
-and references. Omit \`--mount-root\` to keep existing settings. Image declarations,
-runtime state, and live code are preserved. Keep project-specific instructions
-outside generated/copied files and outside the host guide's managed block.
-Refreshing project files does not install a newer package or upgrade image tools.
+## Images
 
-\`plexus.json\` declares this project's images. A freshly initialized
-project declares none; register one before the first image start. With the
-pharo-agent plugin enabled, that is \`image_templates\` and then \`image_add\`,
-with no shell. Otherwise:
+\`plexus.json\` declares this workspace's images. With the plugin, use the
+\`image_*\` tools; otherwise:
 
 \`\`\`sh
 pharo-agent image templates
-pharo-agent image list
-pharo-agent image add dev --template '<launcher template name>'
+pharo-agent image add <id> --template '<template name>'
+pharo-agent image start <id>
 \`\`\`
 
-\`image templates\` names the templates the launcher offers, with the category
-of each; a name two categories offer also needs \`--category <name>\`. Any
-version the launcher offers can be registered, and one outside the MCP range
-starts without MCP tools or a source projection, saying so.
+The first image declared is the default, the main line. An image takes one
+writer, and making one takes seconds: add a new one for each new subject or
+parallel agent rather than share one, named like a branch
+(\`pretty-print-formatter\`, not \`p15\`). A running image may be another
+session's. Stop an image and remove its declaration when its subject is done.
 
-\`image add\` makes the first registered image the default. \`pharo-agent image
-use <id>\` changes the default, and \`pharo-agent image remove <id>\` drops a
-declaration. Stop an image before removing its declaration.
+## Tools
 
-Use \`pharo-agent image start\` before live-image work. On macOS with fuse-t
-installed the image's source is also projected under \`.pharo-agent/mounts\`
-and can be edited as files; everywhere else the Pharo tools are the way in,
-and \`image start\` says so.
-
-With the pharo-agent plugin enabled for this project, this is all MCP tools:
-declare an image with \`image_add\`, start it with \`image_start\`, and call the
-image's own tools by name. Without it,
-call a tool with \`pharo-agent pharo <tool> [arguments-json]\`, and
-\`pharo-agent mcp\` serves the same surface as a command-scoped stdio MCP
-server.
-
-\`pharo-agent pharo list\` names the tools the image advertises, which are the
-common ones rather than all of it. Find the rest through the catalogue rather
-than guessing at a name, then call one the same way as any other:
-
-\`\`\`sh
-pharo-agent pharo tool_search '{"query":"repository commit"}'
-pharo-agent pharo tool_get '{"name":"repository_commit"}'
-pharo-agent pharo repository_commit '{"name":"MCP","message":"..."}'
-\`\`\`
-
-Several images can run at once. \`pharo-agent image start <id>\` and
-\`pharo-agent image stop <id>\` name their image, \`pharo\` and \`mcp\` take
-\`--image <id>\`, and without either the default image answers.
-\`pharo-agent image list\` says which are running, and
-\`pharo-agent image stop --all\` stops every one this project started.
-
-Image, Tonel, Iceberg, disk Git, and host processes are separate states.
+With the plugin, an image's tools are MCP tools. Otherwise call one with
+\`pharo-agent pharo <tool> [arguments-json] [--image <id>]\`, or serve them
+with \`pharo-agent mcp\`. An image lists its common tools; \`tool_search\` and
+\`tool_get\` find the rest. On macOS with fuse-t, \`image start\` also mounts
+the source under \`.pharo-agent/mounts\`.
 
 ${pharoRouting()}
 `;

package/src/live.js

@@ -22,7 +22,7 @@ import {
   writeRunningImages,
 } from "./runtime.js";
 
-export const pifsRelease = "v0.10.2";
+export const pifsRelease = "v0.10.3";
 
 // fuse-t ships as a macOS installer package, so it lands in /usr/local
 // whatever Homebrew's prefix is. The unversioned symlink is what the daemon

package/src/mcpServer.js

@@ -19,18 +19,18 @@ import { readRunningImage } from "./runtime.js";
 // defers the rest, so this is what decides whether Pharo tools are searched
 // for at all. It is the conditional guidance the generated guide gives,
 // written where the host can act on it.
-export const serverInstructions = `Live Pharo images for this project: reading and writing Smalltalk code in the
-image, running tests, finding senders and implementors, applying critiques,
-and projecting image source as files on disk.
+export const serverInstructions = `Live Pharo images for this project: reading and changing code, running tests,
+searching and critiquing it.
 
-Search these tools whenever the task involves Pharo, Smalltalk, a Tonel
-package, or a .st file. Start an image with image_start before calling the
-image's own tools, which are listed once an image answers; image_list says
-what is already running. A project that declares no image yet needs
-image_templates and image_add first.
+Search these tools for any Pharo, Smalltalk, Tonel or .st work. Start an
+image with image_start before calling its tools; a project with no image needs
+image_templates and image_add first. An image lists its common tools;
+tool_search and tool_get find the rest.
 
-The image advertises the common tools rather than all of it. Use tool_search
-and tool_get to find the rest, then call one by name like any other.`;
+An image takes one writer, and making one takes seconds: image_add a new one
+for each new subject or parallel agent rather than share one, named like a
+branch (pretty-print-formatter, not p15). The default image is the main line.
+A running image may be another session's.`;
 
 // This server's own tools, in the order a project meets them: declare an
 // image, start it, and the image's tools join the list. Listed whether or not
@@ -40,34 +40,28 @@ and tool_get to find the rest, then call one by name like any other.`;
 const projectTools = [
   {
     name: "image_templates",
-    description:
-      "List the images Pharo Launcher can create, with the category of each. "
-      + "A template name that two categories offer is flagged, and needs its "
-      + "category when it is declared.",
+    description: "List the templates images can be made from, with their categories.",
     inputSchema: { type: "object", properties: {} },
   },
   {
     name: "image_add",
     description:
-      "Declare an image in this project, from a template image_templates "
-      + "names. Declaring does not create the image: the first image_start "
-      + "does, from this template. The first image declared becomes the "
-      + "project's default.",
+      "Declare an image made from a template; image_start creates it. The "
+      + "first image declared is the default.",
     inputSchema: {
       type: "object",
       properties: {
         id: {
           type: "string",
-          description: "Short id this project calls the image by, such as dev.",
+          description: "What the image is for, named like a branch.",
         },
         template: {
           type: "string",
-          description: "Template name, exactly as image_templates gives it.",
+          description: "Template name, as image_templates gives it.",
         },
         category: {
           type: "string",
-          description:
-            "Template category. Needed only for a name two categories offer.",
+          description: "Template category, for a name two categories offer.",
         },
         profile: {
           type: "string",
@@ -80,42 +74,36 @@ const projectTools = [
   {
     name: "image_start",
     description:
-      "Start one of this project's Pharo images, creating it from its template "
-      + "when it does not exist yet. The image's own tools are listed once it "
-      + "answers. On macOS with fuse-t its source also mounts as files; "
-      + "elsewhere the image starts without that and says so.",
+      "Start an image, creating it the first time. Its tools are listed once "
+      + "it answers. On macOS with fuse-t its source also mounts as files.",
     inputSchema: {
       type: "object",
       properties: {
         image: {
           type: "string",
-          description: "Image id to start. Defaults to the project's default image.",
+          description: "Image id. Defaults to the default image.",
         },
       },
     },
   },
   {
     name: "image_list",
-    description:
-      "List this project's declared images, which are running, and the route "
-      + "and mount of each running one. An image that was started and has "
-      + "exited since is listed as exited; image_start starts it again.",
+    description: "List the declared images, which are running, and the route and mount of each.",
     inputSchema: { type: "object", properties: {} },
   },
   {
     name: "image_stop",
-    description:
-      "Stop a running image, and any source projection this project started for it.",
+    description: "Stop an image and its source mount.",
     inputSchema: {
       type: "object",
       properties: {
         image: {
           type: "string",
-          description: "Image id to stop. Defaults to the project's default image.",
+          description: "Image id. Defaults to the default image.",
         },
         all: {
           type: "boolean",
-          description: "Stop every image this project started, instead of one.",
+          description: "Stop every image this project started.",
         },
       },
     },