feature/Explain-shows-graph-page · L-260926-d89a39

CHANGELOG.md

@@ -2,9 +2,9 @@
 
 ## [Unreleased]
 
-### Fixed
+### Changed
 
-- **`pipelex-explain` leaves no method graph page behind**: the Pipelex tools are about to write a method's flowchart, `method-graph.html`, beside the files a validation reads by path, which would have left a file in the bundle every time `pipelex-explain`, a skill that writes nothing, checked a method on disk. The skill now asks the tools not to write the page, and so does `pipelex-catalog` when it checks whether a bundle would save, since that check is a question and writes no file either.
+- **`pipelex-explain` points at the method graph page**: the Pipelex tools are about to write a method's flowchart, `method-graph.html`, beside the files a validation reads by path, and `pipelex-explain` now gives that page's path before its text flow, so the whole method can be opened in a browser. The skill still writes nothing of its own, and the page is the one file an explanation of a bundle on disk leaves. `pipelex-catalog`'s check of whether a bundle would save asks the tools not to write the page, since that check is a question and writes no file.
 
 ## [0.9.2] - 2026-09-25
 

docs/decisions.md

@@ -276,7 +276,7 @@ Boxes F and M of `wip/plugin-skills-gaps/design.md`. The skill was written for a
 - **A `PipeSignature` is pending only when no concrete pipe of the same code exists anywhere in the files read** (Louis's precision at ratification). Signature-driven design is additive: it leaves the satisfied header behind in the file that declared it. That is the same judgement `/pipelex-organize` already makes when it drops one, so the two skills agree about what a leftover header means. Where the workshop answered, its `pending_signatures` is the authority and a disagreement is reported rather than smoothed over — it means a file was missed or a code is spelled two ways.
 - **The workshop is optional, and the skill is deliberately outside `MCP_SKILLS`.** That tuple asserts a hard stop, and this skill does not have one for a bundle on disk: the source is right there, so an absent tool costs the verdict line and nothing else. The stop exists only for a catalog id or a published address, where nothing is on disk — so both bullets of the shared requirements block are scoped with `mcp_absent_suffix` and `mcp_config_suffix` rather than left to read as unconditional.
 - **A remote method is explained at the level of its contract.** `mthds_validate` with `method_ref` or `method_id` gives the verdict and the `main_pipe` signature, and `mthds_inputs_template` with `explicit: true` gives the input shapes; no bundle enters the conversation, which is the platform's design (`pipelex-mcp/SPEC.md`, Method Selectors) and not a gap in this skill. The skill says so plainly, so that a user knows they have the contract rather than a walkthrough. Reading a saved method's source waits on `mthds_get_method`, which box P adds in the workshop release; until then a catalog id is contract-level too. **Superseded in part (2026-09-22)** — that release shipped, so a catalog id is now read in full and only a published address stays at contract level; see *A catalog id is a target in every skill*.
-- **Strictly read-only, amended at ratification.** The first draft wrote a `README.md` on request. It writes nothing now, and "document this pipeline" left the description because that phrase is what recruited the skill into writing files. The explanation stays in the conversation because that is where the user can read it, correct it and keep what they want of it.
+- **Strictly read-only, amended at ratification.** The first draft wrote a `README.md` on request. It writes nothing now, and "document this pipeline" left the description because that phrase is what recruited the skill into writing files. The explanation stays in the conversation because that is where the user can read it, correct it and keep what they want of it. *(Amended 2026-09-26: the workshop's method graph page is the one file an explanation of a bundle on disk leaves; see "The workshop's method graph page".)*
 
 **`allowed-tools` pre-approves; it does not restrict.** Checked against Claude Code's current documentation while implementing box M: listing a tool waives its permission prompt for the skill, and a tool left off the list stays callable and simply asks first. So the narrow `Read`/`Grep`/`Glob` list does not make a write impossible in `pipelex-explain` — it makes one stop for the user, which is the guarantee worth having and the one the prose already claims. The shared frontmatter takes the list as `skill_tools` and defaults to the writing set, so every other skill renders byte-identically.
 
@@ -682,15 +682,15 @@ Until the console's own release, the hosted console and the local workshop regis
 - **What the skills said of the console is corrected.** The shared submission include no longer calls the inline form "the only form the hosted console accepts", since the console takes no files at all, and `pipelex-explain`'s not-on-disk reference names one cause of an absent `mthds_get_method` where it named two: a workshop older than the release that brought it. The connection reference a skill reads when its tools are absent now tells the user that the plugin's MCP server is the one not connected, which a user who can see a connected Pipelex connector would otherwise doubt, and both references say that the connector's `pipelex_*` tools do not stand in for the workshop's.
 - **The README's quick-start paragraph is not changed here.** It lives in the onboarding region, which is generated from the workspace's onboarding source (the Claude Code sync block) and is replaced from there, so it moves when that block does.
 
-## The workshop's method graph page, and the two skills that turn it off (2026-09-26)
+## The workshop's method graph page: `pipelex-explain` shows it, the catalog's check turns it off (2026-09-26)
 
 `pipelex-mcp` made `mthds_validate` write the method's flowchart as a standalone page, `method-graph.html`, beside the files whenever every file is given as `{ path }`, whatever the verdict, and rewrite it on each validation; a caller turns it off with `graph_page: false` (`pipelex-mcp/SPEC.md`, "The method graph page"). The default is the workshop's to keep, because it is what gives a builder in a host with no views the graph at all, so a skill that must not leave a file behind is the one that opts out.
 
-- **`pipelex-explain` passes `graph_page: false`.** It promises to write nothing, and it validates a bundle on disk by path, as the shared submission convention prefers, so without the argument every explanation of a local method would have left the page in the user's tree. The argument goes on the skill's own step rather than in `shared/validate-call.md.j2`, since the writing skills want the page. It is a guard, registered in `tests/unit/test_skill_guards.py`, because skipping it breaks the promise silently: nothing in the verdict says a file was written.
-- **`pipelex-catalog`'s check of whether a bundle would save passes it too.** The skill writes no file itself and names the two the workshop writes for it, the pulled sources and the link; a page written by a question would have been a third. `mthds_save_method`'s own validation writes no page, so a save needs nothing.
-- **"Wherever the tool lists that argument."** A workshop older than the page lists no `graph_page` and writes no page. `@pipelex/mcp` 0.20.0, the release before the page, ignored the argument when it was sent from Claude Code on 2026-09-26 and answered the verdict as usual, but Codex and Mistral Vibe were not tried, and a host may hold the model to the advertised schema; so the skills name the argument only where the tool offers it rather than sending it blind.
+- **`pipelex-explain` keeps the page and says where it is**, ruled by Louis on 2026-09-26. The skill first passed `graph_page: false` (pipelex-plugins#88, `18a5101`) to keep its promise to write nothing, and the ruling reversed that the same day. Every other skill that validates by path already writes the page, so in most projects it is there anyway, and explain is the skill where a user most wants to see the flow. The read-only ruling above was about the skill writing its own documents, a README on request, and the page is not one: the workshop generates it, marks it, rewrites it on every validation and never replaces a file it did not write. So the promise now says that the skill writes nothing of its own and that the page is the one file it leaves, and the explanation gives the page's path before the text flow. That pointer is a guard, registered in `tests/unit/test_skill_guards.py`, because skipping it leaves a file in the user's tree without a word. `mthds_validate` is pre-approved in the skill's tool list, so the write takes no prompt, and the workshop's replacement policy is what bounds it. Only a bundle validated by path gets a page: a catalog id, a published address and inline files get none.
+- **`pipelex-catalog`'s check of whether a bundle would save passes `graph_page: false`.** The skill writes no file itself and names the two the workshop writes for it, the pulled sources and the link; a page written by a question would have been a third. `mthds_save_method`'s own validation writes no page, so a save needs nothing.
+- **"Wherever the tool lists that argument."** A workshop older than the page lists no `graph_page` and writes no page. `@pipelex/mcp` 0.20.0, the release before the page, ignored the argument when it was sent from Claude Code on 2026-09-26 and answered the verdict as usual, but Codex and Mistral Vibe were not tried, and a host may hold the model to the advertised schema; so the check names the argument only where the tool offers it rather than sending it blind.
 - **`pipelex-organize` is left as it is.** Its baseline validation writes the page before the layout changes, and its confirmation after the swap rewrites it from the new layout, so the page it leaves matches the files. Its promises are about the bundle's `.mthds` files, which the page is not, and it deletes only `.mthds` files. Where the confirmation fails and the original layout is restored, the page shows the rejected candidate until the next validation rewrites it; that is not worth another validation call.
-- **The writing skills keep the page.** `pipelex-design`, `pipelex-edit`, `pipelex-inputs`, `pipelex-run` and `pipelex-integrate` validate by path and let the workshop write it. Pointing the user at it is a change of its own.
+- **The writing skills keep the page.** `pipelex-design`, `pipelex-edit`, `pipelex-inputs`, `pipelex-run` and `pipelex-integrate` validate by path and let the workshop write it. Pointing the user at it from those skills is a change of its own.
 
 ## License & distribution
 

docs/skills.md

@@ -12,7 +12,7 @@ What each skill of the Pipelex plugin does, what it needs, and the tools it call
 
 Those three work on files, and each also takes a saved method's catalog id (`mt_…`): it finds the directory already linked to that method, or hands the pull to `/pipelex-catalog` first. Each ends by saying when the saved copy lacks the change it has made, and offers the update without making it.
 
-**`pipelex-explain`** explains a method in plain language: its contract, its flow and every pipe in it, saying first whether the method is complete or a scaffold with a backlog. It reads a bundle directory or a single file, fetches and explains a saved method's source the same way, since it belongs to the organization asking, and explains a published method's address at the level of its contract, since its internals stay in the repository it names. It is strictly read-only and writes nothing to disk. For a bundle on disk the Pipelex tools are optional: they add a validation verdict to the explanation.
+**`pipelex-explain`** explains a method in plain language: its contract, its flow and every pipe in it, saying first whether the method is complete or a scaffold with a backlog. It reads a bundle directory or a single file, fetches and explains a saved method's source the same way, since it belongs to the organization asking, and explains a published method's address at the level of its contract, since its internals stay in the repository it names. It changes nothing in the method and writes nothing of its own: the one file it leaves is the method's flowchart, which the Pipelex tools write beside a bundle on disk when they validate it, and the explanation says where it is. For a bundle on disk the Pipelex tools are optional: they add a validation verdict and that flowchart.
 
 ## Prepare inputs
 
@@ -44,7 +44,7 @@ The skills share one reference for MTHDS, the language a method is written in: `
 
 ## The Pipelex tools
 
-The tools reach the Pipelex API with your key, the same one the hook uses. Each tool that takes a method takes the files themselves, a saved method's catalog id as `method_id`, or a published method's address as `method_ref`; a call by id needs an API key, because the catalog belongs to an organization. The tools read a file by path only inside the directory the agent was started in, an absolute path included; for a bundle outside it, start the agent from a directory that holds the bundle, or the skills send the files' contents instead. A version of the tools that draws the method graph also writes the method's flowchart, `method-graph.html`, beside files it validates by path, and rewrites it on each validation; `pipelex-explain` and `pipelex-catalog`'s check of whether a bundle would save turn the page off, since neither writes files.
+The tools reach the Pipelex API with your key, the same one the hook uses. Each tool that takes a method takes the files themselves, a saved method's catalog id as `method_id`, or a published method's address as `method_ref`; a call by id needs an API key, because the catalog belongs to an organization. The tools read a file by path only inside the directory the agent was started in, an absolute path included; for a bundle outside it, start the agent from a directory that holds the bundle, or the skills send the files' contents instead. A version of the tools that draws the method graph also writes the method's flowchart, `method-graph.html`, beside files it validates by path, and rewrites it on each validation; `pipelex-explain` tells you where the page is, and `pipelex-catalog`'s check of whether a bundle would save turns it off, since a question writes no file.
 
 - **`mthds_validate`** validates a method. Its verdict carries the main pipe's signature, from which `/pipelex-integrate` types a call site.
 - **`mthds_inputs_template`** returns the input template of a pipe.