@evref-bl/pharo-mcp 2.3.0 → 3.1.0

package/README.md

@@ -32,6 +32,22 @@ Metacello new
    load.
 ```
 
+The baseline groups are:
+
+- `Core`: the server, its transport and schema machinery, and the catalog
+  tools it dispatches through
+- `IDE`: the image tools — classes, methods, packages, tests, critiques,
+  repositories, change history, debugging
+- `UI`: the world-menu server list
+- `Telemetry`: the OpenTelemetry backend
+- `default`: `Core`, `IDE`, `UI` and their tests
+
+A project embedding the server and serving tools of its own loads `Core` alone,
+which leaves out the image tools and everything behind them. Loading its package
+is all its tools need: a tool that names itself is in the catalog.
+[Building on MCP](docs/user/building-on-mcp.md) walks through
+a tool, a resource and a prompt of your own.
+
 Start the Streamable HTTP server:
 
 ```smalltalk
@@ -43,17 +59,16 @@ again after a restart is safe. `MCP allServers` lists what the image holds, and
 `Library → MCP Servers` in the world menu shows the same list.
 
 Connect a local MCP client to `http://127.0.0.1:4000`. Client configuration
-formats differ; see [Getting started](templates/pharo-references/getting-started.md) for setup
+formats differ; see [Getting started](docs/user/getting-started.md) for setup
 and first calls.
 
 ## Documentation
 
 - [Documentation index](docs/README.md)
-- [Getting started](templates/pharo-references/getting-started.md)
-- [Using MCP from an agent](templates/pharo-references/using-pharo-mcp.md)
+- [Getting started](docs/user/getting-started.md)
+- [Building on MCP](docs/user/building-on-mcp.md)
+- [Observability and UI](docs/user/observability.md)
 - [Tool reference](templates/pharo-references/tool-reference.md)
-- [Safety and ecosystem integration](templates/pharo-references/safety-and-ecosystem.md)
-- [Troubleshooting](templates/pharo-references/troubleshooting.md)
 - [Developing MCP](docs/developing-mcp.md)
 
 ## Agent Templates

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evref-bl/pharo-mcp",
-  "version": "2.3.0",
+  "version": "3.1.0",
   "description": "Pharo MCP agent-host templates",
   "license": "MIT",
   "type": "module",

package/templates/pharo-references/pharo-coding.md

@@ -0,0 +1,105 @@
+# Pharo Coding
+
+What is particular to Pharo, for writing, reviewing or refactoring its code
+with whatever tool is at hand: through MCP, through a source projection, or in
+the files themselves.
+
+General programming practice is not repeated here, and neither are the smells a
+rule recognises: Pharo's own critiques report those.
+
+## Dispatch Over Inspection
+
+Pharo code communicates through messages and protocols. Send a domain message
+to the receiver, or add the protocol to the object that owns the behavior,
+rather than asking what the receiver is.
+
+The reflective escapes are not equally defensible:
+
+- `respondsTo:` as control flow is almost never right. It asks whether a send
+  would work instead of sending it. Keep it for genuinely reflexive code that
+  reads a protocol as data.
+- `isKindOf:` and `isMemberOf:` are fine where a type really must be checked
+  and nothing else can say it, such as a boundary receiving foreign objects.
+- `perform:` is fine where the selector is data rather than a disguised
+  switch, such as turning a transport message into a send.
+- `class = ...`, method dictionary and instance-variable reflection belong to
+  tools, proxies and compatibility shims.
+
+Keep reflective behavior isolated and named as tooling or boundary behavior;
+do not spread it through ordinary domain logic.
+
+## The Main Send
+
+A Pharo conditional is an expression, so the send can stand outside it. When
+both branches perform the same operation, lift it out and let the conditional
+answer only the receiver or argument that varies.
+
+```smalltalk
+result := self transform: (condition ifTrue: [ selectedValue ])
+```
+
+This applies to return expressions, assigned values, message arguments, and
+nested expressions.
+
+## Nil
+
+- Use `ifNotNil:` for local nil traversal when a boundary API can genuinely
+  return `nil` and the next step is asking the non-nil object for a value.
+- Keep simple boolean predicates simple. Expressions such as
+  `value isNotNil and: [ value isReady ]` are idiomatic when the result is a
+  boolean. Do not rewrite them into `ifNil:`/`ifNotNil:` only to return a
+  boolean literal from one branch.
+
+## Intermediate Objects
+
+A step that builds a collection or a string only to hand it to the next step
+allocates something nobody asked for. Pharo's fused messages exist for that:
+`collect:as:` rather than `collect:` and a conversion, `select:thenDo:` rather
+than a filtered copy to iterate over, `String streamContents:` rather than a
+chain of `,`, where every comma copies everything to its left.
+
+Sorting is the usual case. `sorted` and `sorted:` answer a sorted copy as an
+Array; `sort` and `sort:` sort a `SequenceableCollection` in place and answer
+it. So `values sorted` says what `values asSortedCollection asArray` says, with
+no `SortedCollection` in between. One earns its keep when a collection must
+*stay* sorted as things are added to it — not for sorting something once.
+
+## Initialization
+
+- Initialize sensible defaults in `initialize`.
+- Do not redefine class-side `new` just to call `initialize`.
+- Use class-side creation messages such as `on:`, `with:`, or domain-specific
+  constructors when required data exists.
+- Use `basicNew` only when deliberately bypassing initialization.
+
+## Selectors
+
+- The getter selector is the variable name; the setter selector is `name:`.
+  Not `getName` or `setName:`.
+- Predicates read as predicates: `isReady`, `hasErrors`, `canHandle:`.
+- Action selectors use verbs: `parseRequest:`, `addTool:`, `writeResponseOn:`.
+- Conversion selectors start with `as`.
+
+## Collections
+
+- Prefer collection protocol such as `collect:`, `select:`, `reject:`,
+  `detect:ifNone:`, `inject:into:`, `anySatisfy:`, and `allSatisfy:`.
+- Do not mutate a collection while iterating it unless iterating a copy is
+  intentional.
+- Do not rely on `add:` answering the collection; use a variable, or cascade
+  with `yourself`.
+
+## Class Extensions
+
+Be conservative with extensions on broad system classes such as `Object`,
+`Behavior`, `String`, or `Exception`. They should model a real boundary
+protocol, not hypothetical defense against wrong callers.
+
+## Tests
+
+- Use `assert:equals:` for comparisons, and `deny:` for negative assertions.
+- Use `should:raise:` and `shouldnt:raise:` with blocks for exception
+  behavior.
+- Use memory filesystems, fakes, or injected collaborators where a unit test
+  would otherwise reach outside the image.
+- Keep live-image and external-state tests separate from source-only checks.

package/templates/pharo-references/tool-reference.md

@@ -1,193 +1,113 @@
 # Tool Reference
 
-MCP exposes tools through `tools/list` and `tools/call`. Common tools can be
-advertised directly; less common tools can be found through the catalog tools.
-Tool names use `snake_case` names that generally put the domain before the
-action.
-
-Every tool returns MCP call `content` as the canonical response for LLMs, in
-plain text: the summary first, then any warnings, then the payload as lines.
-The fields that identify one record share a line as `key=value` pairs, and a
-value carrying spaces is quoted, as in `protocol="private - results"`. A record
-that names a method opens with the method, written the way Pharo writes it:
-`MCPTool>>batchSummaryNoun`, or `MCPTool class>>toolName` on the class side. A
-list of plain values is bracketed, as in `required: [name, slotName]`, and a
-list of records is named before its entries. Text with its own lines, such as
-method source, follows under its own label. `tool_get` answers a tool's
-contract as YAML.
+How this server answers, and what it does when a call is not simply a success.
+What a tool takes is in its own schema: read that with `tool_get`, not from
+here.
 
-A result does not repeat itself: what the summary states in prose, and what a
-record already says another way, is left out of the lines.
-
-The same payload is also carried as `structuredContent`:
+## Reading An Answer
 
-```text
-summary: human-readable summary
-warnings: array of warning strings
-data: structured success payload
-error: structured error payload
-```
-
-`data` is present on success. `error` is present on failure, where the call is
-also flagged with the protocol's own `isError`.
+A call answers text: the summary first, then any warnings, then the payload as
+lines. The fields that identify one record share a line as `key=value` pairs,
+and a value carrying spaces is quoted, as in `protocol="private - results"`. A
+record that names a method opens with the method, written the way Pharo writes
+it: `MCPTool>>batchSummaryNoun`, or `MCPTool class>>toolName` on the class side.
+A list of plain values is bracketed, as in `required: [name, slotName]`, and
+text with its own lines follows under its own label.
 
-For clients or integrations that need programmatic payloads, configure the
-server response fields before `start`:
+A result does not repeat itself: what the summary states in prose, and what a
+record already says another way, is left out of the lines.
 
-```smalltalk
-mcp useContentOnlyToolResponses. "default"
-mcp useStructuredContentOnlyToolResponses.
-mcp useContentAndStructuredContentToolResponses.
-```
+The same payload is carried as `structuredContent` where the server is
+configured to send it, with `data` on success and `error` on failure, the call
+then also carrying the protocol's own `isError`.
 
-## Compact Paging
+## Paging
 
-List and search tools are optimized for low token usage. A page is the tool's
-own size, chosen for what one of its entries costs to read: fifty classes,
-twenty-five methods or packages, twenty critique hits, ten repositories. When
-another page exists, `data` includes `nextOffset`; call the same tool again
-with that `offset` to continue.
+A page is the tool's own size, chosen for what one of its entries costs to
+read, so a page of classes is shorter than a page of repositories. When another
+page exists, `data` carries `nextOffset`; call the same tool again with that
+`offset`.
 
 A search answers what identifies each hit, not everything known about it.
 `repository_search` says how many packages a repository holds rather than
-naming them, which `package_search` answers; `critique_run` names the rule
-rather than restating its documentation on every hit.
-
-## Naming Several Targets
+naming them, which `package_search` answers.
 
-Four tools act on several targets in one call. The argument that names the
-target holds either one value or a list of them, and every other argument
-applies to all of them:
+## Several Targets At Once
 
-| Tool | Argument | One call covers |
-| --- | --- | --- |
-| `method_get` | `selector` | Methods of one class, on one side. |
-| `method_compile` | `source` | Sources compiled into one class, under one protocol. |
-| `class_get` | `name` | Classes read with the same options. |
-| `class_create` | `name` | Classes sharing a superclass, package and slots. |
+Some tools take either one value or a list where they name their target, and
+every other argument then applies to all of them: `method_get` and
+`method_compile` by `selector` and `source`, `class_get` and `class_create` by
+`name`.
 
-Every target is attempted. The summary states how many succeeded, each target
-then reads as it would have read on its own, and `data` carries one entry per
-target under `results`, in request order. An entry that failed carries its
-`error`. The call is flagged `isError` only when every target failed.
+Every target is attempted. The summary says how many succeeded, `data` carries
+one entry per target under `results` in request order, and an entry that failed
+carries its own `error`. The call is flagged `isError` only when every target
+failed.
 
-A call naming one target answers exactly what it answers when the argument
-holds a single value.
+`class_update` and `method_update` are the opposite case: they take the whole
+change to one target and stop at the first part that fails, rather than leaving
+half a definition nobody asked for.
 
-## Changing A Class Or A Method
+## Warnings Are Not Failures
 
-`class_update` and `method_update` take the whole change rather than one
-property each. Every property is optional and at least one is required;
-omitted ones are left alone.
+Pharo signals a notification for a remark rather than a fault, and every
+`Warning` is one. The tool boundary resumes them with the value the image would
+have produced and the call proceeds, so a deprecated send, or an undeclared
+variable during a load, does not fail it.
 
-Scalar properties are replaced by value, and so are the collections that hold
-no state:
+`RBRefactoringWarning` is the exception. It reports a change that breaks
+something, so it stops the call, and the error carries `impactMessages`,
+`howToProceed` and `forceSupported`. Read the impact, then send the same request
+with `force=true` only when the warning is acceptable; forced warnings come back
+in the normal `warnings` array.
 
-```text
-class_update   name, and any of newName, superclass, package, tag, comment,
-               layout, traits, classTraits, sharedVariables, sharedPools
-```
-
-Slots are patched instead, through `slots` and `classSlots`, because they hold
-the instance's values. A replacement list cannot tell a rename from a
-remove-plus-add, and the two differ in whether the value survives; it also has
-to be complete, so a stale one silently drops a slot the caller did not know
-about.
-
-```text
-slots: { add:      [names]
-         remove:   [names]
-         rename:   { current: new }
-         pullUp:   [names]      moves them to the superclass
-         pushDown: [names]      moves them to every direct subclass
-         replace:  [names] }    the whole list; prefer add and remove
-```
+A method can compile and still answer critiques. They are review evidence about
+code that now exists, not a transport failure.
 
-`method_update` takes `class` and `selector`, then `protocol`, `newSelector`
-or both. A selector change is classified by arity, so the one argument renames,
-adds or removes arguments and updates senders. Name the new argument list in
-`arguments` and the index map is worked out: names that match the current ones
-are kept, new names are added arguments needing `argumentValueExpressions`, and
-current names left out are removed. `permutation` is only for reordering, which
-names cannot express.
+## Rewriting
 
-The changes are applied in dependency order, not the order they were written:
-a superclass change first, because it decides what the rest validates against,
-slots added before anything refers to them and removed last, and a rename last,
-because every other change resolves the target by the name the caller wrote.
+`method_rewrite` takes Smalltalk AST patterns, not regex, and a scope is
+required: rewriting everything is something a caller asks for by naming the
+packages, not by leaving an argument out.
 
-A change that fails stops the ones after it. This is the opposite of a batch
-over several targets, and deliberately so: these all land on one class or one
-method, so carrying on would leave half a definition nobody asked for. The
-error names the change that failed, the ones already applied, and the ones not
-attempted.
+A metavariable starts with a backquote and stands for whatever is in its place,
+however big, so one rule rewrites `anObject notNil` and `(anObject foo) notNil`
+alike. The names must be the same on both sides; a name that appears only in
+the replacement is bound to nothing. `confirm` is false by default, and the
+preview carries the old and new source of every change.
 
-## The Advertised Surface
-
-Fifteen tools are advertised directly: `tool_search`, `tool_get`, `tool_call`, `class_search`, `class_get`, `class_create`, `class_remove`, `method_search`, `method_source_search`, `method_reference_search`, `method_get`, `method_compile`, `method_remove`, `test_run` and `image_evaluate`. Every other tool is found with `tool_search` and called by name like any other; `tool_call` does the same for a client that will only send a name its own list holds.
-
-A server chooses its own surface before `start`:
-
-```smalltalk
-mcp advertiseTools: #( 'tool_search' 'tool_get' 'tool_call' 'method_get' ).
+```json
+{
+  "rules": [{ "match": "`@receiver notNil", "replacement": "`@receiver isNotNil" }],
+  "scope": { "packages": ["MyPackage"] }
+}
 ```
 
-## Finding A Tool
-
-The server answers for its own catalogue. `tool_search` ranks it by keyword,
-best match first, and answers the closest tools even when none matches every
-word; add words to narrow the ranking. With no query it answers the catalogue's
-size and its groups. `tool_get` returns one tool's metadata and input schema,
-and `tool_call` invokes a tool by nesting its arguments, for a client that cannot
-send a name outside its own list.
-
-Search before calling anything less common or high-risk, and read the schema
-before invoking it.
-
-Tools are named `domain_action`, and the domains are:
-
-| Group | Covers |
-| --- | --- |
-| `classes` | Defining classes and changing their slots, traits, shared variables, pools, layout, package and comment, including the slot refactorings. |
-| `methods` | Compiling, reading, removing and rewriting methods, renaming selectors and protocols, and searching by source, metadata, senders, implementors, references or equivalence. |
-| `repositories` | What the image knows about its Iceberg repositories: identity, package membership, working-copy changes, export, commit, and reloading the image from the files. Branches, remotes and transfers are git's, and belong in a shell. |
-| `debugging` | Reading the debuggers a person opened, with their exceptions and nearest frames, and watching what variables hold while an expression runs. Neither attaches to a debugger or leaves a session behind. |
-| `history` | Epicea change history: locating files, listing entries, and applying or reverting them. |
-| `tests` | Running tests and running them under coverage. |
-| `packages` | Searching packages. |
-| `runtime` | `image_evaluate`, the escape hatch. |
-| `ui` | Reading what is on screen, as a tree of windows and the presenters or morphs inside them, or as a screenshot. Either one can take a single window instead of the whole world, for a fraction of the cost. |
-| `tool-catalog` | `tool_search`, `tool_get` and `tool_call`. |
-
-## Scripting
-
-Use `image_evaluate` only when no dedicated tool fits. A successful evaluation
-can mutate the running image.
+Any rewrite rule stands for its own patterns, Pharo's own included, so
+`ruleClasses` can name one instead of writing its patterns out. A rule that
+reports a critique is never applied by the tool that compiles: reporting is
+that tool's job, changing it is this one's, and the caller asks.
 
 ## Mutation And Saving
 
 No tool saves the image. Mutating tools change the running image only, so
 closing it discards every change since its last save, and a mistake costs the
-session rather than the image file. Saving is the caller's responsibility:
-evaluate `Smalltalk saveSession` when a change should survive, or leave it to
-whoever owns the image lifecycle.
+session rather than the image file. Evaluate `Smalltalk saveSession` when a
+change should survive, or leave it to whoever owns the image lifecycle.
 
-Use `history_entry_list` to see what changed and `history_entry_revert` to undo
-a change in the running image; both preview first and perform with
-`confirm=true`.
+`history_entry_list` shows what changed and `history_entry_revert` undoes it in
+the running image; both preview, and perform with `confirm=true`.
 
-`repository_identity_verify` and `repository_change_list` are read-only.
+## The Escape Hatch
 
-## Refactoring Warnings
+`image_evaluate` runs arbitrary Smalltalk. Prefer a dedicated tool when one
+exists: it validates its input and answers structured data.
 
-For edit tools that use refactoring operations, `force=false` is the default.
-When Pharo raises `RBRefactoringWarning`, the tool returns an error with:
-
-```text
-impactMessages
-howToProceed
-forceSupported: true
-```
+Compiling is the case that bites. Method source separates lines with CR, and
+`method_compile` normalizes what it is given, while a bare `compile:` from
+`image_evaluate` stores whatever it receives, so source written with LF compares
+unequal to every other method in the image.
 
-Rerun with `force=true` only after reviewing the impact. Forced warnings are
-returned as normal warnings in the successful result.
+A debugger somebody opened is theirs. Read it, act on what it shows with the
+ordinary class and method tools, and leave stepping, resuming and terminating
+to the person at the debugger.

package/templates/pharo-skills/pharo-ci-repro/references/pharo-smalltalkci.md

@@ -56,30 +56,6 @@ SmalltalkCISpec {
 
 Adjust the baseline, directory, and class for the project under test.
 
-## Pharo 13 / Iceberg / libgit2 Pattern
-
-In a Pharo MCP investigation on 2026-05-16, a P13 flaky CI crash reproduced
-locally inside Docker. It was not a dependency download issue: loading
-completed and testing had started.
-
-Crash signatures included:
-
-- C stack in `libgit2.so.1.4.4`
-- `git_repository_head_unborn`
-- `git_commit_lookup`
-- Smalltalk frames through `IceLibgitRepository`, `IceRepository>>headCommit`,
-  or `IceRepository>>validateCanCommit`
-- Test frames in a repository-management test
-
-The practical mitigation was to avoid unnecessary test-side `repository
-headCommit` reads and skip a P13 test that deliberately forced empty libgit2
-config values for a P12-only fallback path.
-
-General lesson: if a Pharo 13 Linux CI segfault points into libgit2 while
-testing fresh temporary repositories, treat it as a native stability surface.
-Avoid poking Iceberg head/commit metadata in tests unless the assertion is
-essential.
-
 ## Interpreting Common Noise
 
 - `fatal: not a git repository`: often harmless when running smalltalkCI from a
@@ -95,8 +71,8 @@ essential.
 
 After a fix:
 
-- Run the failing Pharo platform full suite.
-- Run adjacent supported platforms, usually P12 and P13 for MCP.
-- Run focused repeats for the flaky class/method if the original failure was
-  intermittent.
+- Run the failing Pharo platform's full suite.
+- Run the adjacent versions in the project's matrix.
+- Run focused repeats for the flaky class or method when the original failure
+  was intermittent.
 - Keep the captured failing log path in the report.

package/templates/pharo-skills/pharo-code-profiling/SKILL.md

@@ -52,10 +52,9 @@ String streamContents: [ :stream | tally report: stream cutoff: 2 ]
 ## Choosing The Cutoff
 
 The cutoff is the percentage of all samples a node must hold to be printed, in
-the tree and in the leaves alike. Use 2 and read the report once. Over a
-2400-sample run of the same workload it printed 79 lines where 5% printed 52
-and 1% printed 84, so it is close enough to the whole tree that a second look
-rarely pays, and still under a thousand tokens.
+the tree and in the leaves alike. Use 2 and read the report once: over a 2400-sample
+run it printed 79 lines where 1% printed 84, close enough to the whole tree
+that a second look rarely pays.
 
 Raise it when the report is larger than the question. Rendering again costs no
 new run, because the tally is still in hand:
@@ -74,10 +73,9 @@ The one that decides the report is on `report:cutoff:`.
 
 ## Profiling A Workload Longer Than The Call
 
-Fork the run, write the report to a file, and come back for it. The fork
-returns the call immediately and leaves the image answering, so the profile can
-take as long as the workload needs. Keep the report out of a global: a file
-survives, is readable from outside the image, and needs no cleanup inside it.
+Fork the run and write the report to a file. The fork returns the call at
+once and leaves the image answering, so the profile can take as long as the
+workload needs.
 
 ```smalltalk
 | path |
@@ -99,26 +97,13 @@ path writeStreamDo: [ :out |
 path fullName
 ```
 
-The file is written only once the run ends, so `path exists` answers whether it
-is done. To tell a slow run from a dead one, look for the process by the name
-it was forked under:
-
-```smalltalk
-Process allInstances anySatisfy: [ :each |
-	each name = 'pharo-profile' and: [ each isTerminated not ] ]
-```
-
-Pharo writes CR line endings, so convert to LF as above, or the report arrives
-as a single line everywhere outside the image.
-
-The tally dies with the fork, so this report is written once and cannot be
-rendered again at another cutoff. The file costs nothing to keep, and it can be
-read in parts rather than whole.
-
-Forking at `userBackgroundPriority` keeps the image answering calls while the
-profile runs. The samples it loses to those calls are charged to another
-process and dropped from the report, which lowers every percentage by the same
-factor: read the proportions between nodes, not their absolute values.
+The file appears only when the run ends, so `path exists` answers whether it
+is done; a forked process that is still alive is found by the name it was
+forked under. Convert CR to LF as above, or the report arrives as a single
+line outside the image. The tally dies with the fork, so this report cannot
+be rendered again at another cutoff. Forking at `userBackgroundPriority`
+keeps the image answering, and the samples lost to those calls lower every
+percentage by the same factor: read the proportions, not the values.
 
 ## Reading The Report
 
@@ -145,8 +130,6 @@ Process: (60) ...
   defined on `SequenceableCollection`.
 - `primitives` is not a method. It is the part of the parent's time no child
   accounts for: its own work, primitives and inlined code included.
-- The `|` bars are tree drawing. A node gets one when a sibling follows it at
-  that level, and carries it down its subtree. They mean nothing else.
 - `**Leaves**` ranks by own time and is usually what to act on. The tree says
   who is responsible, the leaves say what is expensive.
 - `**Memory**` is the allocation delta over the run and `**GCs**` the
@@ -167,11 +150,9 @@ String streamContents: [ :stream | profiler report: stream cutoff: 2 ]
 ```
 
 Never send `spyOn:` to the class: it ends in `doReport`, which opens a window.
-The instance-side `spyOn:` is the headless path.
-
-Its tree is rooted at the image, so a report taken through MCP opens with the
-frames of the server handling the call. Find the workload's entry method and
-read the percentages from that node down.
+Its tree is rooted at the image, so a report taken through a tool call opens
+with the frames of the server handling it; read from the workload's entry
+method down.
 
 ## Measuring Instead Of Profiling
 
@@ -200,6 +181,6 @@ mean: the minimum is the run least disturbed by GC and scheduling.
 
 ## Report
 
-Report the workload and how long it ran, the sampler and cutoff, the top tree
-nodes and leaves with their percentages, the change made, the before-and-after
-comparison, and the tests that showed behavior unchanged.
+Report the workload, the sampler and cutoff, the top tree nodes and leaves with
+their percentages, the change made, the before-and-after comparison, and the
+tests that showed behavior unchanged.

package/templates/pharo-skills/pharo-image-sync/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: pharo-image-sync
+description: Move code between a live Pharo image and its Tonel files, and tell the two apart. Use before exporting image changes, after a checkout moves under the image, and whenever Iceberg, the image and the files disagree.
+---
+
+# Pharo Image Sync
+
+The image holds objects, the repository holds files, and Iceberg holds its own
+idea of both. A clean `git status` does not mean the image is clean, and an
+Iceberg diff does not mean anything was written to disk.
+
+Git itself is ordinary shell work. These tools only cross the boundary between
+the image and the files.
+
+## Out Of The Image
+
+1. Verify which repository you are about to write to: `repository_search` for
+   its location, branch and packages, then `repository_identity_verify` with
+   what you expect, which fails rather than guessing.
+2. Read the image-side diff with `repository_change_list` before writing
+   anything.
+3. `repository_export` writes the changed packages to Tonel and updates the
+   Iceberg index. It stages and commits nothing.
+4. Read the files it touched with `git diff`. Export writes what the image
+   holds, which includes anything loaded into it that you did not put there.
+
+## Into The Image
+
+A checkout that moves under a running image leaves it running the old code.
+After a branch switch, a pull, a merge or a rebase, `repository_reload` loads
+the packages from the files again.
+
+Reloading can leave classes behind in `Undeclared` when a superclass moved,
+with subclasses still parented to an obsolete one. The symptom is tests failing
+on classes nobody edited. Load that package again by name to repair it.
+
+## Stop And Ask
+
+Stop when two registrations claim the same packages, when the branch, source
+directory or package membership is not what you expect, when a head is detached
+or missing, or when Iceberg and the files disagree for no reason you can name.
+Resolving real divergence, or discarding image changes, is the user's call.
+
+## Report
+
+Say what the image held, what was written, which files changed, and what you
+did not verify.

package/templates/pharo-skills/pharo-image-sync/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Pharo Image Sync"
+  short_description: "Move code between image and files"
+  default_prompt: "Use $pharo-image-sync to move these changes between the Pharo image and its Tonel files."

package/templates/pharo-skills/pharo-mcp-recovery/SKILL.md

@@ -19,7 +19,7 @@ standalone image without a safer environment-specific recovery surface.
 4. Create a replacement image only after preserving the original. Use
    `pharo-project-load` to restore MCP and the target project.
 5. Recover changes by inspecting Epicea history before confirmed application.
-   Use `pharo-image-git-handoff` before repository attachment or Tonel export.
+   Use `pharo-image-sync` before repository attachment or Tonel export.
 6. Verify the recovered behavior with focused inspection or tests.
 
 ## Stop And Ask