feature/Skills-offer-method-graphhtml · L-260926-14cb83

CHANGELOG.md

@@ -8,7 +8,7 @@
 
 ### Changed
 
-- **`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.
+- **`pipelex-explain`, `pipelex-design` and `pipelex-run` point 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 these skills now give that page's path before their text flow — `pipelex-explain` in every explanation of a bundle on disk, `pipelex-design` when it hands over a method, and `pipelex-run` on a dry run — so the whole method can be opened in a browser. `pipelex-explain` still writes nothing of its own, and the page is the one file it 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.
 
 ### Fixed
 

CLAUDE.md

@@ -55,7 +55,8 @@ templates/                     # SOURCE OF TRUTH — all .j2 templates live here
 │       ├── saved-copy-notice.md.j2    # The linked saved method does not have this change; `/pipelex-catalog` compares the two and updates it (include-only)
 │       ├── catalog-id-pointer.md.j2   # The pointer design, edit and organize place at a catalog id, with the bridge's two guards (include-only)
 │       ├── catalog-id-bridge.md.j2    # How a file-based skill reaches a catalog id: the linked directory, or the pull (include-only; included by shared/catalog-id.md alone)
-│       └── pipefunc-warning.md.j2     # PipeFunc is experimental on the hosted plane (include-only)
+│       ├── pipefunc-warning.md.j2     # PipeFunc is experimental on the hosted plane (include-only)
+│       └── graph-page.md.j2           # The method graph page's path, before the text flow: explain, design's delivery and run's dry run (include-only)
 ├── hooks/
 │   ├── hooks.json.j2                # Claude PostToolUse hook config
 │   ├── codex-hooks.json.j2          # Codex PostToolUse hook config (plugin-bundled)

docs/build-targets.md

@@ -284,6 +284,7 @@ So the bump procedure is: edit `[vars.floors]`, run `make build`, run `make chec
 | `catalog-id-pointer.md.j2` | the pointer a file-based skill places where it meets a catalog id or a published address, sending the model to `shared/catalog-id.md` before any file is read, with the bridge's two guards beside it — for design, edit and organize | none |
 | `catalog-id-bridge.md.j2` | how a file-based skill reaches a catalog id: the search over the link files, the several-hits question, the pull, and the refusal of a published address. Included by the rendered shared reference `catalog-id.md.j2` alone, which `pipelex-design`, `pipelex-edit` and `pipelex-organize` point at | `catalog_id_bridge_resume` (the step the skill resumes at, interpolated mid-sentence; the shared reference sets `the skill that sent you here, just after its pointer to this file`) |
 | `pipefunc-warning.md.j2` | that `PipeFunc` is experimental on the hosted plane and runs its Python in a network-blocked sandbox | none |
+| `graph-page.md.j2` | the path of the method graph page `mthds_validate` writes beside a bundle validated by path, given before the text flow, with the page's first-write note and its error in one line — for explain, design's delivery and run's dry run, the three places a skill presents a method's flow | none |
 | `project-root.md.j2` | where a project starts — the nearest directory holding one of the project markers — for design, integrate and catalog | none |
 | `git-ignore.md.j2` | how a path that holds the user's data is kept out of version control before it is written: `git check-ignore -q`, an entry in the nearest `.gitignore` relative to that file's directory, the check again, and the guard that a path git still does not ignore, which a tracked one never is, waits for the user. Included after each skill's own bold subject, by `pipelex-inputs` for the copies of the user's files, `pipelex-lab` for a case of them and `pipelex-run` for the `runs/` folder a save writes into | `git_ignore_paths` (what is checked and when, following `git check-ignore -q`), `git_ignore_entry` (the entry written); neither has a default |
 | `skill-dir.md.j2` | on Codex and Vibe, the sentence defining the `<skill-dir>` placeholder as the directory of the `SKILL.md` the harness loaded; nothing on Claude, where `${CLAUDE_SKILL_DIR}` is substituted. Included just before the first sentence that uses `{{ skill_dir }}` | none |

docs/decisions.md

@@ -682,15 +682,16 @@ 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: `pipelex-explain` shows it, the catalog's check turns it off (2026-09-26)
+## The workshop's method graph page: the skills that present a flow show 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` 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 from those skills is a change of its own.
+- **`pipelex-design` and `pipelex-run` show the page where they present the flow**, ruled by Louis on 2026-09-26, the same day as explain. Design gives it at delivery, replacing "the interactive method graph where the host rendered it", which the plugin's workshop, having no views, never gave. Run gives it on a dry run alone: a real run's reply is the run, and a user who wants the flow asks for a dry run or for `pipelex-explain`. The three skills say it in one sentence, the include `templates/skills/shared/graph-page.md.j2`, which speaks of "a summary" calling the page new because design's page is new at the construction loop's first validation, long before delivery. Both skills sat at the size ceiling, so the room came from wording: the reason `runs/` is excluded left the shared submission partial, since the artifacts bullet above records it, run's opening stopped restating where a dry run lives, and a few sentences were tightened; no guard moved. The skills name a path that opens in a browser and assume no host preview, so whether Codex's HTML preview runs the page's CDN scripts was not checked, and nothing depends on it.
+- **The other skills that validate by path leave the page without a word.** `pipelex-edit`, `pipelex-inputs`, `pipelex-integrate`, `pipelex-organize` and a real run let the workshop write it and present no flow. `TestSharedSkillIncludes` pins which skills include the sentence, so a skill that starts or stops naming the page changes this ruling on purpose.
 
 ## A local workshop is one make target, and touches no tracked file (2026-09-26)
 

docs/skills.md

@@ -4,7 +4,7 @@ What each skill of the Pipelex plugin does, what it needs, and the tools it call
 
 ## Build a method
 
-**`pipelex-design`** designs a method contract-first and writes it as `.mthds` files. A method whose whole graph is understood and shallow is written directly as a coherent, runnable bundle; deep, uncertain, staged or resumable work goes through signature-driven refinement, validated at each step. A structural or contract change to an existing method, such as a new step or a new input, comes back here too, and the skill re-enters the affected region directly or through signatures according to its complexity.
+**`pipelex-design`** designs a method contract-first and writes it as `.mthds` files. A method whose whole graph is understood and shallow is written directly as a coherent, runnable bundle; deep, uncertain, staged or resumable work goes through signature-driven refinement, validated at each step. A structural or contract change to an existing method, such as a new step or a new input, comes back here too, and the skill re-enters the affected region directly or through signatures according to its complexity. When the method is ready, the skill presents its flow, giving first the path of the flowchart page the Pipelex tools write beside the bundle.
 
 **`pipelex-edit`** makes the edits that keep a method's contract: a prompt, a model reference, a mechanical rename. It proves each one with a validation before and after, and sends a structural or contract change to `/pipelex-design`.
 
@@ -22,7 +22,7 @@ Those three work on files, and each also takes a saved method's catalog id (`mt_
 
 ## Run and save
 
-**`pipelex-run`** runs a method and follows a run, and does nothing else. It starts a run from a bundle directory, a catalog id or a published method's address, with inputs that are already run-ready, and prints the run id the moment the run starts. A pipe other than the main one is named by its qualified reference, its code prefixed by the domain of the file that defines it, as `domain.pipe_code`. Every completed run is saved into `runs/<run_id>/`, under the directory the agent was started in: its whole output as `main_stuff.json`, beside each file it produced, named after the field it fills. That output carries what the run read in your files, so in a git repository the skill makes sure `runs/` is ignored before it saves there, adding it to the nearest `.gitignore` when it is not and saying so; a path git still does not ignore waits for your say-so, and outside a repository nothing is done. It follows a run by its id alone, to its status, its results or a save of it, which works days later. A run of a directory linked to a saved method is filed under that method, so it appears in the method's history. A failure goes back to the skill that owns the repair. The skill never starts a run nobody asked for, and a dry run shows the method's flow and spends nothing.
+**`pipelex-run`** runs a method and follows a run, and does nothing else. It starts a run from a bundle directory, a catalog id or a published method's address, with inputs that are already run-ready, and prints the run id the moment the run starts. A pipe other than the main one is named by its qualified reference, its code prefixed by the domain of the file that defines it, as `domain.pipe_code`. Every completed run is saved into `runs/<run_id>/`, under the directory the agent was started in: its whole output as `main_stuff.json`, beside each file it produced, named after the field it fills. That output carries what the run read in your files, so in a git repository the skill makes sure `runs/` is ignored before it saves there, adding it to the nearest `.gitignore` when it is not and saying so; a path git still does not ignore waits for your say-so, and outside a repository nothing is done. It follows a run by its id alone, to its status, its results or a save of it, which works days later. A run of a directory linked to a saved method is filed under that method, so it appears in the method's history. A failure goes back to the skill that owns the repair. The skill never starts a run nobody asked for, and a dry run shows the method's flow, with the path of its flowchart page when the tools wrote one, and spends nothing.
 
 **`pipelex-catalog`** carries a method between a bundle directory and your organization's Pipelex catalog: it lists what is saved, saves a directory as a new method or updates the one its `pipelex-method.json` link names, and pulls a saved method's files back to disk. A save validates and stores the bundle in a single call. It sends the bundle's files by path, because the tools write the `pipelex-method.json` link only beside files they read from disk, and that link is what makes the next save an update rather than a second method; for a bundle outside the directory the agent was started in, which the tools cannot read by path, the skill says the link cannot be written and saves without it only if you say yes. On an update, that leaves the link behind the catalog, so the directory's next save is refused as a conflict with that save, which the skill recognises as its own; a pull into the same directory, once the tools can write there, brings the link up to date. Before an update, the skill says that the update reaches every caller of that id. It refuses to overwrite a change it has not seen, and it never deletes.
 
@@ -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` 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.
+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`, `pipelex-design` when it hands over a method and `pipelex-run` on a dry run tell you where the page is, the other skills leave it without a word, 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.