@mcuste/pi-diagram 0.0.0 → 0.2.0

package/README.md

@@ -16,8 +16,7 @@ If any of those names are new to you:
 
 > **Status: images, text, and files work.** In a terminal that supports inline images the diagram
 > itself is shown; everywhere else it is box drawing or plain ASCII. Files land outside the
-> repository unless a destination is named. The design being followed is
-> [docs/terminal_diagram_tool_proposal.md](docs/terminal_diagram_tool_proposal.md).
+> repository unless a destination is named.
 
 ## Why
 
@@ -124,6 +123,19 @@ language.
 | `formats` | Files to produce: `source`, `svg`, `png`, `txt`. Written outside the repository |
 | `save` | Also copy them into the repository. `dir` is required |
 
+## When the model draws
+
+A described tool gets called when the user asks for a diagram, not when a diagram is the clearer
+answer. So the extension adds a short block to the host system prompt: draw when structure, flow,
+or relationships are easier to see than to read, call the tool before explaining, keep the prose
+to what the picture does not show, and never hand-write ASCII art or a Mermaid block. The block
+also maps a question to a diagram, so components go to `architecture`, message order to a sequence
+diagram, tables to `data`, a hierarchy to `tree`, and so on.
+
+The result is fewer walls of text: an answer about how parts connect arrives as a picture with a
+few lines around it. The block is appended to whatever the host built, is added once, and is left
+out when the `diagram` tool is not active.
+
 ## What a profile changes
 
 The model says what a diagram is for, and the tool decides how it looks:
@@ -161,6 +173,12 @@ to forward the protocol: tmux needs `allow-passthrough`, and herdr needs
 The image never enters the model's context. It is written to a private temporary directory and
 read back when the row is displayed.
 
+The row is bounded to 80 by 30 character cells, so a dense diagram is drawn small. Where the
+terminal supports OSC 8 hyperlinks, the title above the diagram links to that file: click it and
+the diagram opens in the image viewer of the machine, which zooms and pans. A diagram with no
+title shows the linked file name under the image instead. Ghostty, Kitty, WezTerm, and iTerm2 all
+open such a link, some of them on a modified click.
+
 D2 exports PNG by driving a headless browser it downloads on first use, which this tool will not
 do during a call. Instead the SVG it already produces is rasterized locally by
 [resvg](https://github.com/yisibl/resvg-js), which needs no browser and no network. Labels are
@@ -231,7 +249,6 @@ and a model given those knobs spends tokens on styling and produces a different
 ## Documentation
 
 - [Safety model](docs/safety.md)
-- [Design proposal](docs/terminal_diagram_tool_proposal.md)
 - [Development and release](docs/development.md)
 - [Changelog](CHANGELOG.md)
 

package/dist/display.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"display.d.ts","sourceRoot":"","sources":["../src/display.ts"],"names":[],"mappings":"AAgBA,MAAM,WAAW,SAAS;IACxB,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;CACjC;AAED,MAAM,WAAW,YAAY;IAC3B,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;CACzC;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,8EAA8E;IAC9E,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACzC;AAED,UAAU,YAAY;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAiBD;;;GAGG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAS9D;AAED,4EAA4E;AAC5E,wBAAgB,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC,CAY5C;AAED,kGAAkG;AAClG,wBAAgB,eAAe,IAAI,OAAO,GAAG,SAAS,CAErD;AAED,4FAA4F;AAC5F,wBAAgB,aAAa,IAAI,OAAO,CAEvC;AAWD,MAAM,WAAW,eAAe;IAC9B,8EAA8E;IAC9E,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,qEAAqE;IACrE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,uFAAuF;AACvF,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,eAAe,EAAE,KAAK,EAAE,YAAY,GAAG,SAAS,CASvF;AAED,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,WAAW,EACjB,KAAK,EAAE,YAAY,EACnB,OAAO,EAAE,cAAc,GACtB,SAAS,CAuCX;AAUD,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,KAAK,EAAE,YAAY,GAAG,SAAS,CAAC;IACzC,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,8EAA8E;IAC9E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,mFAAmF;IACnF,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC"}
+{"version":3,"file":"display.d.ts","sourceRoot":"","sources":["../src/display.ts"],"names":[],"mappings":"AAiBA,MAAM,WAAW,SAAS;IACxB,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;CACjC;AAED,MAAM,WAAW,YAAY;IAC3B,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;CACzC;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,8EAA8E;IAC9E,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACzC;AAED,UAAU,YAAY;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAqBD;;;GAGG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAS9D;AAED,4EAA4E;AAC5E,wBAAgB,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC,CAY5C;AAED,kGAAkG;AAClG,wBAAgB,eAAe,IAAI,OAAO,GAAG,SAAS,CAErD;AAED,4FAA4F;AAC5F,wBAAgB,aAAa,IAAI,OAAO,CAEvC;AAWD,MAAM,WAAW,eAAe;IAC9B,8EAA8E;IAC9E,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,qEAAqE;IACrE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,uFAAuF;AACvF,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,eAAe,EAAE,KAAK,EAAE,YAAY,GAAG,SAAS,CASvF;AAED,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,WAAW,EACjB,KAAK,EAAE,YAAY,EACnB,OAAO,EAAE,cAAc,GACtB,SAAS,CA4CX;AAoBD,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,KAAK,EAAE,YAAY,GAAG,SAAS,CAAC;IACzC,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,8EAA8E;IAC9E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,mFAAmF;IACnF,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC"}

package/dist/display.js

@@ -1,5 +1,6 @@
 import { readFileSync } from "node:fs";
 import { createRequire } from "node:module";
+import { basename, isAbsolute } from "node:path";
 import { pathToFileURL } from "node:url";
 /**
  * Turns a diagram result into terminal components. Both the image and the text are drawn here
@@ -71,10 +72,11 @@ export function renderDiagramResult(view, theme, context) {
     const line = (text) => {
         container.addChild(new module.Text(theme.fg("toolOutput", text), 0, 0));
     };
+    const image = drawable(module, view.image, context) ? view.image : undefined;
+    const url = image === undefined ? undefined : openable(module, image);
     if (view.title !== undefined) {
-        line(view.title);
+        line(url === undefined ? view.title : module.hyperlink(view.title, url));
     }
-    const image = drawable(module, view.image, context) ? view.image : undefined;
     if (image === undefined) {
         line(view.text);
     }
@@ -85,6 +87,10 @@ export function renderDiagramResult(view, theme, context) {
                 maxHeightCells: MAX_HEIGHT_CELLS,
                 filename: image.path,
             }, { widthPx: image.widthPx, heightPx: image.heightPx }));
+            if (view.title === undefined && url !== undefined) {
+                const name = module.hyperlink(basename(image.path), url);
+                container.addChild(new module.Text(theme.fg("muted", name), 0, 0));
+            }
         }
         catch {
             // The picture is gone from the temp store, so show the text instead.
@@ -97,12 +103,21 @@ export function renderDiagramResult(view, theme, context) {
     }
     return container;
 }
+/**
+ * The picture as a link, so a click opens it where it can be zoomed. The row is bounded to keep
+ * the transcript readable, so the file is the only way to see a dense diagram in full.
+ */
+function openable(module, image) {
+    return module.getCapabilities().hyperlinks && isAbsolute(image.path)
+        ? pathToFileURL(image.path).href
+        : undefined;
+}
 function drawable(module, image, context) {
     return image !== undefined && context.showImages && module.getCapabilities().images !== null;
 }
 /** Reads the image once per result row: the host calls the renderer again on every redraw. */
 function read(image, context) {
-    const cached = context.state["diagramImage"];
+    const cached = context.state.diagramImage;
     if (typeof cached === "object" && cached !== null) {
         const { path, encoded } = cached;
         if (path === image.path && typeof encoded === "string") {
@@ -114,7 +129,7 @@ function read(image, context) {
         throw new Error(`The image at ${image.path} is ${bytes.length} bytes.`);
     }
     const encoded = bytes.toString("base64");
-    context.state["diagramImage"] = { path: image.path, encoded };
+    context.state.diagramImage = { path: image.path, encoded };
     return encoded;
 }
 //# sourceMappingURL=display.js.map

package/dist/display.js.map

@@ -1 +1 @@
-{"version":3,"file":"display.js","sourceRoot":"","sources":["../src/display.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"display.js","sourceRoot":"","sources":["../src/display.ts"],"names":[],"mappings":"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"}

package/dist/guidance.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The prompt block that makes the model draw by itself. The tool description alone gets the tool
+ * called when the user asks for a diagram, not when a diagram is the clearer answer.
+ */
+export declare const DIAGRAM_GUIDANCE: string;
+/** Pi hands over one prompt string; Oh My Pi hands over ordered blocks. */
+type HostSystemPrompt = string | readonly string[];
+interface AgentStartEvent {
+    readonly systemPrompt?: HostSystemPrompt;
+    /** Only Pi reports what it built the prompt from. */
+    readonly systemPromptOptions?: {
+        readonly selectedTools?: readonly string[];
+    };
+}
+interface AgentStartResult {
+    readonly systemPrompt: HostSystemPrompt;
+}
+export interface GuidanceExtensionApi {
+    on?(event: "before_agent_start", handler: (event: AgentStartEvent) => AgentStartResult | undefined): void;
+}
+export declare function registerDiagramGuidance(pi: GuidanceExtensionApi): void;
+/**
+ * The hook replaces the prompt, so returning the guidance alone would drop everything the host
+ * built. A prompt that cannot be read is left as it is.
+ */
+export declare function withGuidance(event: AgentStartEvent): AgentStartResult | undefined;
+export {};
+//# sourceMappingURL=guidance.d.ts.map

package/dist/guidance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guidance.d.ts","sourceRoot":"","sources":["../src/guidance.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,eAAO,MAAM,gBAAgB,QAqBjB,CAAC;AAEb,2EAA2E;AAC3E,KAAK,gBAAgB,GAAG,MAAM,GAAG,SAAS,MAAM,EAAE,CAAC;AAEnD,UAAU,eAAe;IACvB,QAAQ,CAAC,YAAY,CAAC,EAAE,gBAAgB,CAAC;IACzC,qDAAqD;IACrD,QAAQ,CAAC,mBAAmB,CAAC,EAAE;QAAE,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;KAAE,CAAC;CAC/E;AAED,UAAU,gBAAgB;IACxB,QAAQ,CAAC,YAAY,EAAE,gBAAgB,CAAC;CACzC;AAED,MAAM,WAAW,oBAAoB;IACnC,EAAE,CAAC,CACD,KAAK,EAAE,oBAAoB,EAC3B,OAAO,EAAE,CAAC,KAAK,EAAE,eAAe,KAAK,gBAAgB,GAAG,SAAS,GAChE,IAAI,CAAC;CACT;AAED,wBAAgB,uBAAuB,CAAC,EAAE,EAAE,oBAAoB,GAAG,IAAI,CAEtE;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,eAAe,GAAG,gBAAgB,GAAG,SAAS,CAcjF"}

package/dist/guidance.js

@@ -0,0 +1,54 @@
+/**
+ * The prompt block that makes the model draw by itself. The tool description alone gets the tool
+ * called when the user asks for a diagram, not when a diagram is the clearer answer.
+ */
+export const DIAGRAM_GUIDANCE = [
+    "Diagrams:",
+    "- Call the diagram tool when structure, flow, or relationships are easier to see than to read.",
+    "- Draw instead of writing a wall of text: three or more connected parts means a diagram.",
+    "- Call the tool before you explain, then write only what the picture does not show.",
+    "- Do not repeat the diagram in prose. The user already sees it.",
+    "- Never hand-write ASCII art or a Mermaid block. Call the tool.",
+    "- Do not draw one fact, a short list, a list of commands, or code that reads better as code.",
+    "- Match the diagram to the question:",
+    "  - components and their connections: profile architecture",
+    "  - the order of messages in time: a sequence diagram, shape: sequence_diagram",
+    "  - tables, columns, and keys: profile data, shape: sql_table",
+    "  - a hierarchy, such as a call tree or a file layout: profile tree",
+    "  - an import, module, or package graph: profile dependency",
+    "  - C4 levels, when the reader expects that convention: profile c4",
+    "  - a diagram to keep in the repository: profile docs, with save",
+    "  - a data flow, a state change, or a request path in an answer: profile explain, the default",
+    "- Keep one idea per diagram, about 5 to 15 nodes. Split a bigger picture into more calls.",
+    "- Label every edge with what moves or what happens.",
+    "- Fix the source and call again when the tool reports an error in it.",
+    "- Pass save only when the user asks to keep the diagram.",
+].join("\n");
+export function registerDiagramGuidance(pi) {
+    pi.on?.("before_agent_start", withGuidance);
+}
+/**
+ * The hook replaces the prompt, so returning the guidance alone would drop everything the host
+ * built. A prompt that cannot be read is left as it is.
+ */
+export function withGuidance(event) {
+    const prompt = event.systemPrompt;
+    if (!toolActive(event)) {
+        return undefined;
+    }
+    if (typeof prompt === "string") {
+        return prompt === "" || prompt.includes(DIAGRAM_GUIDANCE)
+            ? undefined
+            : { systemPrompt: `${prompt}\n\n${DIAGRAM_GUIDANCE}` };
+    }
+    if (!Array.isArray(prompt) || prompt.length === 0 || prompt.includes(DIAGRAM_GUIDANCE)) {
+        return undefined;
+    }
+    return { systemPrompt: [...prompt, DIAGRAM_GUIDANCE] };
+}
+/** Telling the model to draw with a tool the user turned off would waste a turn. */
+function toolActive(event) {
+    const tools = event.systemPromptOptions?.selectedTools;
+    return tools === undefined || tools.includes("diagram");
+}
+//# sourceMappingURL=guidance.js.map

package/dist/guidance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"guidance.js","sourceRoot":"","sources":["../src/guidance.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,WAAW;IACX,gGAAgG;IAChG,0FAA0F;IAC1F,qFAAqF;IACrF,iEAAiE;IACjE,iEAAiE;IACjE,8FAA8F;IAC9F,sCAAsC;IACtC,4DAA4D;IAC5D,gFAAgF;IAChF,+DAA+D;IAC/D,qEAAqE;IACrE,6DAA6D;IAC7D,oEAAoE;IACpE,kEAAkE;IAClE,+FAA+F;IAC/F,2FAA2F;IAC3F,qDAAqD;IACrD,uEAAuE;IACvE,0DAA0D;CAC3D,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAsBb,MAAM,UAAU,uBAAuB,CAAC,EAAwB;IAC9D,EAAE,CAAC,EAAE,EAAE,CAAC,oBAAoB,EAAE,YAAY,CAAC,CAAC;AAC9C,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,KAAsB;IACjD,MAAM,MAAM,GAAG,KAAK,CAAC,YAAY,CAAC;IAClC,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC;QACvB,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;QAC/B,OAAO,MAAM,KAAK,EAAE,IAAI,MAAM,CAAC,QAAQ,CAAC,gBAAgB,CAAC;YACvD,CAAC,CAAC,SAAS;YACX,CAAC,CAAC,EAAE,YAAY,EAAE,GAAG,MAAM,OAAO,gBAAgB,EAAE,EAAE,CAAC;IAC3D,CAAC;IACD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,IAAI,MAAM,CAAC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,CAAC;QACvF,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,OAAO,EAAE,YAAY,EAAE,CAAC,GAAG,MAAM,EAAE,gBAAgB,CAAC,EAAE,CAAC;AACzD,CAAC;AAED,oFAAoF;AACpF,SAAS,UAAU,CAAC,KAAsB;IACxC,MAAM,KAAK,GAAG,KAAK,CAAC,mBAAmB,EAAE,aAAa,CAAC;IACvD,OAAO,KAAK,KAAK,SAAS,IAAI,KAAK,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;AAC1D,CAAC"}

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+import { type GuidanceExtensionApi } from "./guidance.js";
 import { type DiagramExtensionApi } from "./tools.js";
-export default function piDiagram(pi: DiagramExtensionApi): void;
+export default function piDiagram(pi: DiagramExtensionApi & GuidanceExtensionApi): void;
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,mBAAmB,EAAwB,MAAM,YAAY,CAAC;AAE5E,MAAM,CAAC,OAAO,UAAU,SAAS,CAAC,EAAE,EAAE,mBAAmB,GAAG,IAAI,CAE/D"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,oBAAoB,EAA2B,MAAM,eAAe,CAAC;AACnF,OAAO,EAAE,KAAK,mBAAmB,EAAwB,MAAM,YAAY,CAAC;AAE5E,MAAM,CAAC,OAAO,UAAU,SAAS,CAAC,EAAE,EAAE,mBAAmB,GAAG,oBAAoB,GAAG,IAAI,CAGtF"}

package/dist/index.js

@@ -1,5 +1,7 @@
+import { registerDiagramGuidance } from "./guidance.js";
 import { registerDiagramTools } from "./tools.js";
 export default function piDiagram(pi) {
     registerDiagramTools(pi);
+    registerDiagramGuidance(pi);
 }
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAA4B,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAE5E,MAAM,CAAC,OAAO,UAAU,SAAS,CAAC,EAAuB;IACvD,oBAAoB,CAAC,EAAE,CAAC,CAAC;AAC3B,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAA6B,uBAAuB,EAAE,MAAM,eAAe,CAAC;AACnF,OAAO,EAA4B,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAE5E,MAAM,CAAC,OAAO,UAAU,SAAS,CAAC,EAA8C;IAC9E,oBAAoB,CAAC,EAAE,CAAC,CAAC;IACzB,uBAAuB,CAAC,EAAE,CAAC,CAAC;AAC9B,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mcuste/pi-diagram",
-  "version": "0.0.0",
+  "version": "0.2.0",
   "description": "Terminal-native diagram rendering as one safe, model-callable tool for the Pi and Oh My Pi coding agents",
   "keywords": [
     "pi-package",

package/src/display.ts

@@ -1,5 +1,6 @@
 import { readFileSync } from "node:fs";
 import { createRequire } from "node:module";
+import { basename, isAbsolute } from "node:path";
 import { pathToFileURL } from "node:url";
 
 /**
@@ -36,7 +37,11 @@ interface DisplayImage {
 }
 
 interface TuiModule {
-  readonly getCapabilities: () => { readonly images: "kitty" | "iterm2" | null };
+  readonly getCapabilities: () => {
+    readonly images: "kitty" | "iterm2" | null;
+    readonly hyperlinks: boolean;
+  };
+  readonly hyperlink: (text: string, url: string) => string;
   readonly Text: new (text?: string, paddingX?: number, paddingY?: number) => Component;
   readonly Container: new () => Component & { addChild(child: Component): void };
   readonly Image: new (
@@ -128,11 +133,12 @@ export function renderDiagramResult(
   const line = (text: string): void => {
     container.addChild(new module.Text(theme.fg("toolOutput", text), 0, 0));
   };
+  const image = drawable(module, view.image, context) ? view.image : undefined;
+  const url = image === undefined ? undefined : openable(module, image);
   if (view.title !== undefined) {
-    line(view.title);
+    line(url === undefined ? view.title : module.hyperlink(view.title, url));
   }
 
-  const image = drawable(module, view.image, context) ? view.image : undefined;
   if (image === undefined) {
     line(view.text);
   } else {
@@ -150,6 +156,10 @@ export function renderDiagramResult(
           { widthPx: image.widthPx, heightPx: image.heightPx },
         ),
       );
+      if (view.title === undefined && url !== undefined) {
+        const name = module.hyperlink(basename(image.path), url);
+        container.addChild(new module.Text(theme.fg("muted", name), 0, 0));
+      }
     } catch {
       // The picture is gone from the temp store, so show the text instead.
       line(view.text);
@@ -163,6 +173,16 @@ export function renderDiagramResult(
   return container;
 }
 
+/**
+ * The picture as a link, so a click opens it where it can be zoomed. The row is bounded to keep
+ * the transcript readable, so the file is the only way to see a dense diagram in full.
+ */
+function openable(module: TuiModule, image: DisplayImage): string | undefined {
+  return module.getCapabilities().hyperlinks && isAbsolute(image.path)
+    ? pathToFileURL(image.path).href
+    : undefined;
+}
+
 function drawable(
   module: TuiModule,
   image: DisplayImage | undefined,
@@ -183,7 +203,7 @@ export interface DiagramView {
 
 /** Reads the image once per result row: the host calls the renderer again on every redraw. */
 function read(image: DisplayImage, context: DisplayContext): string {
-  const cached = context.state["diagramImage"];
+  const cached = context.state.diagramImage;
   if (typeof cached === "object" && cached !== null) {
     const { path, encoded } = cached as { path?: unknown; encoded?: unknown };
     if (path === image.path && typeof encoded === "string") {
@@ -196,6 +216,6 @@ function read(image: DisplayImage, context: DisplayContext): string {
     throw new Error(`The image at ${image.path} is ${bytes.length} bytes.`);
   }
   const encoded = bytes.toString("base64");
-  context.state["diagramImage"] = { path: image.path, encoded };
+  context.state.diagramImage = { path: image.path, encoded };
   return encoded;
 }

package/src/guidance.ts

@@ -0,0 +1,77 @@
+/**
+ * The prompt block that makes the model draw by itself. The tool description alone gets the tool
+ * called when the user asks for a diagram, not when a diagram is the clearer answer.
+ */
+
+export const DIAGRAM_GUIDANCE = [
+  "Diagrams:",
+  "- Call the diagram tool when structure, flow, or relationships are easier to see than to read.",
+  "- Draw instead of writing a wall of text: three or more connected parts means a diagram.",
+  "- Call the tool before you explain, then write only what the picture does not show.",
+  "- Do not repeat the diagram in prose. The user already sees it.",
+  "- Never hand-write ASCII art or a Mermaid block. Call the tool.",
+  "- Do not draw one fact, a short list, a list of commands, or code that reads better as code.",
+  "- Match the diagram to the question:",
+  "  - components and their connections: profile architecture",
+  "  - the order of messages in time: a sequence diagram, shape: sequence_diagram",
+  "  - tables, columns, and keys: profile data, shape: sql_table",
+  "  - a hierarchy, such as a call tree or a file layout: profile tree",
+  "  - an import, module, or package graph: profile dependency",
+  "  - C4 levels, when the reader expects that convention: profile c4",
+  "  - a diagram to keep in the repository: profile docs, with save",
+  "  - a data flow, a state change, or a request path in an answer: profile explain, the default",
+  "- Keep one idea per diagram, about 5 to 15 nodes. Split a bigger picture into more calls.",
+  "- Label every edge with what moves or what happens.",
+  "- Fix the source and call again when the tool reports an error in it.",
+  "- Pass save only when the user asks to keep the diagram.",
+].join("\n");
+
+/** Pi hands over one prompt string; Oh My Pi hands over ordered blocks. */
+type HostSystemPrompt = string | readonly string[];
+
+interface AgentStartEvent {
+  readonly systemPrompt?: HostSystemPrompt;
+  /** Only Pi reports what it built the prompt from. */
+  readonly systemPromptOptions?: { readonly selectedTools?: readonly string[] };
+}
+
+interface AgentStartResult {
+  readonly systemPrompt: HostSystemPrompt;
+}
+
+export interface GuidanceExtensionApi {
+  on?(
+    event: "before_agent_start",
+    handler: (event: AgentStartEvent) => AgentStartResult | undefined,
+  ): void;
+}
+
+export function registerDiagramGuidance(pi: GuidanceExtensionApi): void {
+  pi.on?.("before_agent_start", withGuidance);
+}
+
+/**
+ * The hook replaces the prompt, so returning the guidance alone would drop everything the host
+ * built. A prompt that cannot be read is left as it is.
+ */
+export function withGuidance(event: AgentStartEvent): AgentStartResult | undefined {
+  const prompt = event.systemPrompt;
+  if (!toolActive(event)) {
+    return undefined;
+  }
+  if (typeof prompt === "string") {
+    return prompt === "" || prompt.includes(DIAGRAM_GUIDANCE)
+      ? undefined
+      : { systemPrompt: `${prompt}\n\n${DIAGRAM_GUIDANCE}` };
+  }
+  if (!Array.isArray(prompt) || prompt.length === 0 || prompt.includes(DIAGRAM_GUIDANCE)) {
+    return undefined;
+  }
+  return { systemPrompt: [...prompt, DIAGRAM_GUIDANCE] };
+}
+
+/** Telling the model to draw with a tool the user turned off would waste a turn. */
+function toolActive(event: AgentStartEvent): boolean {
+  const tools = event.systemPromptOptions?.selectedTools;
+  return tools === undefined || tools.includes("diagram");
+}

package/src/index.ts

@@ -1,5 +1,7 @@
+import { type GuidanceExtensionApi, registerDiagramGuidance } from "./guidance.js";
 import { type DiagramExtensionApi, registerDiagramTools } from "./tools.js";
 
-export default function piDiagram(pi: DiagramExtensionApi): void {
+export default function piDiagram(pi: DiagramExtensionApi & GuidanceExtensionApi): void {
   registerDiagramTools(pi);
+  registerDiagramGuidance(pi);
 }