deepclause-pi 0.1.4 → 0.2.0

package/dist/index.js

@@ -1,14 +1,22 @@
-import { readdir } from "node:fs/promises";
+import { readFile, readdir } from "node:fs/promises";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
 import { StringEnum } from "@earendil-works/pi-ai";
 import { Type } from "typebox";
 import { buildInitialMessages } from "./context.js";
 import { loadConfig, setModelToolEnabled } from "./config.js";
+import { renderDml, renderSequence } from "./diagram/extract.js";
+import { polishDiagram, resolveGrade } from "./diagram/grade.js";
+import { findChrome, validateMermaid } from "./diagram/validate.js";
+import { buildViewer, openViewerInBrowser, writeSidecar, } from "./diagram/viewer.js";
+import { collectDiagramTargets, diagramNameFor, displayPath, ensureDiagramDir, resolveDiagramSource, } from "./diagram/workspace.js";
+import { completeTextWithPiModel } from "./model.js";
 import { executeDml } from "./runtime.js";
 import { getPaths, initializeWorkspace, resolveDmlPath } from "./workspace.js";
 import { assemblePlanDml, buildPlanningPrompt, DC_PLAN_COMMIT_TOOL, isContextualPlan, PI_AGENT_STEP_TOOL, readPlanRequiredTools, validateGeneratedPlan, validatePlanSpec, writePlanNonDestructively, } from "./planner.js";
 const DC_RUN_TOOL = "dc_run";
-const AUTHORING_INSTRUCTION = `DeepClause programs live in .pi/deepclause/skills/ and executable generated plans live in .pi/deepclause/plans/. You may create and edit DML skills directly after consulting .pi/deepclause/AGENTS.md and DML_REFERENCE.md. Use /dc-plan when the user asks pi to design a contextual executable plan; finish that planning turn with dc_plan_commit. DeepClause compilation is unavailable, so generated content must already be valid DML. Users execute programs through /dc-run. If the opt-in dc_run tool is active, you may execute an ordinary skill with it, but contextual plans requiring pi_agent_step must be started by the user. Never invoke a compiler or create .deepclause/.`;
+const DC_DIAGRAM_TOOL = "dc_diagram";
+const AUTHORING_INSTRUCTION = `DeepClause programs live in .pi/deepclause/skills/ and executable generated plans live in .pi/deepclause/plans/. You may create and edit DML skills directly after consulting .pi/deepclause/AGENTS.md and DML_REFERENCE.md. Use /dc-plan when the user asks pi to design a contextual executable plan; finish that planning turn with dc_plan_commit. When the user asks for a diagram, flowchart, or visual of a .dml file, call the dc_diagram tool with the exact path and the requested grade (presentation or specification); it writes the viewer under .pi/deepclause/diagrams/ and opens it, so do not hand-write Mermaid. DeepClause compilation is unavailable, so generated content must already be valid DML. Users execute programs through /dc-run. If the opt-in dc_run tool is active, you may execute an ordinary skill with it, but contextual plans requiring pi_agent_step must be started by the user. Never invoke a compiler or create .deepclause/.`;
 const STATUS_KEY = "deepclause";
 const WIDGET_KEY = "deepclause-stream";
 export function splitArguments(input) {
@@ -170,6 +178,12 @@ async function listDmlFiles(directory, prefix = "") {
 function modelLabel(ctx) {
     return ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : "none selected";
 }
+async function bundledViewerTemplate() {
+    return readFile(fileURLToPath(new URL("./assets/viewer.template.html", import.meta.url)), "utf8");
+}
+function viewerVendorAssetPath() {
+    return fileURLToPath(new URL("./assets/vendor/mermaid.min.js", import.meta.url));
+}
 function publishResult(pi, content, details) {
     pi.sendMessage({ customType: "deepclause-result", content, display: true, details });
 }
@@ -177,6 +191,7 @@ export default function deepClauseExtension(pi) {
     let activeController;
     let activeDescription;
     let modelToolRegistered = false;
+    let diagramToolRegistered = false;
     let planCommitRegistered = false;
     let planningTransaction;
     let pendingAgentStep;
@@ -468,9 +483,131 @@ export default function deepClauseExtension(pi) {
                 : activeTools.filter((name) => name !== DC_RUN_TOOL));
         }
     };
+    const setDiagramToolActive = () => {
+        if (!diagramToolRegistered) {
+            pi.registerTool({
+                name: DC_DIAGRAM_TOOL,
+                label: "Create DeepClause Diagram",
+                description: "Create a presentation-grade or specification-grade Mermaid diagram from any .dml file, write a self-contained offline viewer under .pi/deepclause/diagrams/, and open it.",
+                promptSnippet: "Create a presentation- or specification-grade diagram from a DML file",
+                promptGuidelines: [
+                    "Use dc_diagram whenever the user asks for a diagram, flowchart, or visual of a .dml file; pass the exact path the user named.",
+                    "Choose grade=presentation for slides and overviews and grade=specification for engineering detail; use grade=both only when the user asks for both.",
+                    "Do not hand-write Mermaid or run diagram tools yourself; call dc_diagram and report the viewer result.",
+                ],
+                parameters: Type.Object({
+                    dml: Type.String({ description: "Path to a .dml file, relative to the workspace or absolute. A leading @ is ignored." }),
+                    grade: Type.Optional(Type.String({ description: "presentation (default), specification, or both. Synonyms such as detailed or technical map to specification." })),
+                    view: Type.Optional(StringEnum(["flow", "sequence"], { description: "Base layout used to seed the grade; default flow." })),
+                }),
+                async execute(_toolCallId, params, signal, onUpdate, ctx) {
+                    if (activeController) {
+                        return {
+                            content: [{ type: "text", text: "Another DeepClause operation is already active; wait for it to finish." }],
+                            details: { success: false, error: "execution_already_active" },
+                        };
+                    }
+                    const requested = resolveGrade(String(params.grade ?? "")) ?? "presentation";
+                    const grades = requested === "both" ? ["presentation", "specification"] : [requested];
+                    const view = params.view === "sequence" ? "sequence" : "flow";
+                    let sourcePath;
+                    try {
+                        sourcePath = await resolveDiagramSource(ctx.cwd, params.dml);
+                    }
+                    catch (error) {
+                        const message = error instanceof Error ? error.message : String(error);
+                        return { content: [{ type: "text", text: `dc_diagram failed: ${message}` }], details: { success: false, error: message } };
+                    }
+                    if (!ctx.model) {
+                        return {
+                            content: [{ type: "text", text: "dc_diagram requires an active pi model. Select one and try again." }],
+                            details: { success: false, error: "no_model" },
+                        };
+                    }
+                    const config = await loadConfig(getPaths(ctx.cwd).config);
+                    const source = await readFile(sourcePath, "utf8");
+                    const display = displayPath(ctx.cwd, sourcePath);
+                    const seed = view === "sequence"
+                        ? renderSequence(display, source)
+                        : renderDml(display, source, { hideOutput: true });
+                    const targets = await collectDiagramTargets(ctx.cwd, [sourcePath]);
+                    const name = diagramNameFor(sourcePath, targets, ctx.cwd);
+                    const { diagrams, vendor } = await ensureDiagramDir(ctx.cwd, viewerVendorAssetPath());
+                    const templateText = await bundledViewerTemplate();
+                    const controller = new AbortController();
+                    const cancel = () => controller.abort(signal?.reason ?? new Error("dc_diagram cancelled"));
+                    if (signal?.aborted)
+                        cancel();
+                    else
+                        signal?.addEventListener("abort", cancel, { once: true });
+                    activeController = controller;
+                    activeDescription = `diagram ${name} (${grades.join("+")})`;
+                    const run = (command, args, options) => pi.exec(command, args, options);
+                    let chrome;
+                    let chromeResolved = false;
+                    try {
+                        for (const grade of grades) {
+                            const result = await polishDiagram({
+                                grade,
+                                view,
+                                source,
+                                seed,
+                                maxTokens: config.maxTokens,
+                                signal: controller.signal,
+                                complete: (options) => completeTextWithPiModel(ctx, options),
+                                validate: async (code) => {
+                                    if (!chromeResolved) {
+                                        chrome = await findChrome(run);
+                                        chromeResolved = true;
+                                    }
+                                    const outcome = await validateMermaid(code, view, { run, vendorDir: vendor, chrome: chrome ?? null });
+                                    return outcome.result;
+                                },
+                                onProgress: (message) => onUpdate?.({
+                                    content: [{ type: "text", text: message }],
+                                    details: { dml: display, grades, name },
+                                }),
+                            });
+                            await writeSidecar(diagrams, name, grade, result.code);
+                        }
+                        const build = await buildViewer({
+                            cwd: ctx.cwd,
+                            templateText,
+                            vendorAssetPath: viewerVendorAssetPath(),
+                            extraPaths: [sourcePath],
+                        });
+                        const opened = ctx.hasUI
+                            ? await openViewerInBrowser(pi, build.viewerPath, name, grades[0] ?? "presentation")
+                            : false;
+                        const viewer = displayPath(ctx.cwd, build.viewerPath);
+                        const text = `Created ${grades.join(" + ")}-grade diagram for ${display}. Viewer: ${viewer}${opened ? " (opened in your browser)" : ""}`;
+                        return {
+                            content: [{ type: "text", text }],
+                            details: { success: true, dml: display, grades, name, viewer, opened, chrome: Boolean(chrome) },
+                        };
+                    }
+                    catch (error) {
+                        const message = error instanceof Error ? error.message : String(error);
+                        return { content: [{ type: "text", text: `dc_diagram failed: ${message}` }], details: { success: false, error: message } };
+                    }
+                    finally {
+                        signal?.removeEventListener("abort", cancel);
+                        activeController = undefined;
+                        activeDescription = undefined;
+                    }
+                },
+            });
+            diagramToolRegistered = true;
+        }
+        const activeTools = pi.getActiveTools();
+        if (!activeTools.includes(DC_DIAGRAM_TOOL)) {
+            pi.setActiveTools([...activeTools, DC_DIAGRAM_TOOL]);
+        }
+    };
     pi.on("session_start", async (_event, ctx) => {
         const config = await loadConfig(getPaths(ctx.cwd).config);
         setModelToolActive(config.modelToolEnabled);
+        setDiagramToolActive();
     });
     pi.on("tool_execution_start", (event) => {
         if (pendingAgentStep && !pendingAgentStep.toolsUsed.includes(event.toolName)) {
@@ -547,6 +684,9 @@ export default function deepClauseExtension(pi) {
                 `Plans: ${path.relative(ctx.cwd, paths.plans)}`,
                 `Context: ${config.contextMode} (verbose default: ${config.verbose})`,
                 `Model tool (${DC_RUN_TOOL}): ${config.modelToolEnabled && pi.getActiveTools().includes(DC_RUN_TOOL) ? "enabled" : "disabled"}`,
+                `Model tool (${DC_DIAGRAM_TOOL}): ${pi.getActiveTools().includes(DC_DIAGRAM_TOOL) ? "enabled" : "disabled"}`,
+                "Ask pi for a presentation-grade or specification-grade diagram of any .dml file;",
+                "it writes the viewer under .pi/deepclause/diagrams/ and opens it.",
                 "Commands:",
                 "  /dc-list",
                 "  /dc-plan <request> [--name=slug]   create an executable contextual DML plan",

package/dist/model.d.ts

@@ -0,0 +1,16 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { Usage } from "@earendil-works/pi-ai";
+export interface TextCompletion {
+    text: string;
+    usage?: Usage;
+}
+/**
+ * One-shot text completion through pi's active model and credentials. Used by
+ * diagram grading; it never requests API keys or mutates provider state.
+ */
+export declare function completeTextWithPiModel(ctx: ExtensionContext, options: {
+    systemPrompt?: string;
+    prompt: string;
+    maxTokens: number;
+    signal?: AbortSignal;
+}): Promise<TextCompletion>;

package/dist/model.js

@@ -0,0 +1,28 @@
+/**
+ * One-shot text completion through pi's active model and credentials. Used by
+ * diagram grading; it never requests API keys or mutates provider state.
+ */
+export async function completeTextWithPiModel(ctx, options) {
+    const model = ctx.model;
+    if (!model)
+        throw new Error("Select a pi model before generating a diagram grade");
+    if (!ctx.modelRegistry.hasConfiguredAuth(model)) {
+        throw new Error(`Pi has no configured authentication for ${model.provider}/${model.id}`);
+    }
+    const response = await ctx.modelRegistry.complete(model, {
+        systemPrompt: options.systemPrompt,
+        messages: [{ role: "user", content: options.prompt, timestamp: Date.now() }],
+    }, {
+        signal: options.signal,
+        maxTokens: options.maxTokens,
+        cacheRetention: "none",
+    });
+    if (response.stopReason === "error" || response.stopReason === "aborted") {
+        throw new Error(response.errorMessage || `Pi model request ${response.stopReason}`);
+    }
+    const text = response.content
+        .filter((content) => content.type === "text")
+        .map((content) => content.text)
+        .join("");
+    return { text, usage: response.usage };
+}

package/docs/BLOG_POST_PI_EXTENSION.md

@@ -0,0 +1,253 @@
+# DeepClause meets pi: executable agent plans inside your coding session
+
+### DML orchestration with pi’s models, tools and context
+
+`tldr;` I built a [pi](https://github.com/badlogic/pi-mono) extension for [DeepClause](https://github.com/deepclause/deepclause-sdk). It runs DML programs with pi’s active model, credentials and session context. It can also turn a normal planning request into an executable DML plan. The plan can delegate individual steps back to pi, with a fixed set of tools for each step.
+
+The extension is available here: [https://github.com/deepclause/deepclause-pi](https://github.com/deepclause/deepclause-pi)
+
+[The following is mostly written by a real person ;-]
+
+I have spent quite a bit of time using DeepClause as a standalone agent runtime. That works well for benchmarks and self-contained workflows, but it leaves out something useful: the environment of a coding agent that is already running.
+
+A coding agent such as pi already has:
+
+- a selected model and working authentication
+- the current conversation and compacted session history
+- repository instructions and loaded skills
+- file, shell and extension tools
+- a terminal UI, cancellation and usage accounting
+
+Reimplementing all of that in DeepClause would make little sense. The more useful option is to let pi remain the host and use DeepClause for the part it is good at: explicit orchestration.
+
+This is what the new extension does.
+
+[Image: `/dc` status and command overview]
+
+### Running DML inside pi
+
+The basic case is simple. DML programs live in `.pi/deepclause/skills/` and can be executed with a slash command:
+
+```text
+/dc-run example --debug
+```
+
+The extension uses the model currently selected in pi. It does not ask for another API key or try to guess the provider. Model calls, cancellation, input prompts and usage stay connected to the current pi session.
+
+A minimal skill still looks like ordinary DML:
+
+```prolog
+agent_main(Topic) :-
+    system("You are a concise technical analyst."),
+    format(string(Request),
+           "Explain ~w. Store the final explanation in Summary.",
+           [Topic]),
+    task(Request, string(Summary)),
+    answer(Summary).
+```
+
+Run it as follows:
+
+```text
+/dc-run skills/explain.dml "constraint logic programming"
+```
+
+There are three context modes:
+
+- `turn` imports the current request and its immediate context
+- `branch` imports a bounded part of the active session branch
+- `isolated` starts without pi conversation history
+
+For example:
+
+```text
+/dc-run skills/explain.dml "constraint logic programming" --context=isolated
+```
+
+Pi remains the session owner. DeepClause does not create another chat history next to it.
+
+### Tools are deliberately boring
+
+Ordinary DML programs do not receive pi’s complete tool registry. They start with two narrow host operations:
+
+- `pi_workspace_list` lists one directory level inside the workspace
+- `pi_bash` runs an approved command inside the workspace
+
+Every `pi_bash` call requires user confirmation. Paths are checked against the active workspace, including resolved symlinks.
+
+A DML program can wrap these operations in a more useful tool predicate:
+
+```prolog
+tool(bing_search(Query, Results),
+     "Search Bing RSS and return the response body") :-
+    format(string(QueryArg), "q=~w", [Query]),
+    exec(pi_bash("curl", [
+        "--fail", "--silent", "--show-error", "--location", "--get",
+        "--data-urlencode", QueryArg,
+        "https://www.bing.com/search?format=rss&count=8"
+    ]), Result),
+    get_dict(stdout, Result, Results).
+```
+
+The repository includes a small deep-research example built on this pattern. It asks the user to review a search plan through pi’s input UI, runs approved `curl` requests and produces a cited report.
+
+I intentionally did not expose all coding tools directly through `exec/2`. Pi extensions can describe their tools, but there is no public generic API for another extension to invoke any tool by name. More importantly, copying tool execution into DeepClause would bypass behavior owned by pi or another extension, such as approval dialogs and policy checks.
+
+This becomes relevant for planning.
+
+### DML is the plan
+
+The extension adds this command:
+
+```text
+/dc-plan <request> [--name=slug]
+```
+
+For example:
+
+```text
+/dc-plan build a small Three.js Space Invaders game and verify it --name=threejs-space-invaders
+```
+
+This starts a normal pi turn. The planner can inspect the repository, read its instructions, see loaded skills and consider the currently active tools. It does not directly return a Markdown checklist and it does not generate arbitrary DML source in one shot.
+
+Instead, the planning turn finishes by calling a temporary tool named `dc_plan_commit`. The tool accepts a typed plan specification with:
+
+- a title and objective
+- ordered steps
+- an executor for each step
+- exact required tool names
+- relevant pi skills
+- an expected result for every step
+- a fallback message
+
+The extension validates this object and shows a preview. After user confirmation, it deterministically assembles the DML file, parses the generated program and writes it under `.pi/deepclause/plans/` without overwriting an existing file.
+
+This follows the same general idea as the planner used in my DeepPlanning experiments: ask the model for a constrained intermediate representation and let normal code produce the executable DML. This is simpler and more reliable than asking the model to get every comma, variable and fallback clause right.
+
+A generated plan looks like this:
+
+```prolog
+agent_main :-
+    output("Step 1/3: Inspect the workspace"),
+    exec(pi_agent_step(
+        instruction: "Inspect repository instructions and identify the target app.",
+        tools: ["bash", "read"],
+        expected: "A target directory and concrete implementation baseline.",
+        skills: []
+    ), Step1Summary),
+    Step1Summary \= "",
+
+    output("Step 2/3: Implement the application"),
+    exec(pi_agent_step(
+        instruction: "Implement the agreed application and keep changes scoped.",
+        tools: ["read", "write", "edit"],
+        expected: "A runnable implementation with a concise change summary.",
+        skills: []
+    ), Step2Summary),
+    Step2Summary \= "",
+
+    output("Step 3/3: Validate the result"),
+    exec(pi_agent_step(
+        instruction: "Run the relevant checks and fix implementation failures.",
+        tools: ["bash", "read", "write", "edit"],
+        expected: "Passing checks or a precise account of remaining failures.",
+        skills: []
+    ), Step3Summary),
+    Step3Summary \= "",
+
+    answer([Step1Summary, Step2Summary, Step3Summary]).
+```
+
+The full file is executable. There is no Markdown-to-DML compilation step in the pi integration.
+
+[Image: generated DML plan in the editor]
+
+### What `pi_agent_step` does
+
+`pi_agent_step` is the bridge between DML orchestration and a normal pi coding turn.
+
+When the DML runtime reaches one of these calls, the extension:
+
+1. checks that every named tool is installed and currently active
+2. rejects DeepClause control tools to prevent recursive planning or execution
+3. saves pi’s current active-tool set
+4. temporarily activates only the tools named by the step
+5. sends the bounded instruction through a normal pi turn
+6. captures the final textual summary and tool failures
+7. restores the previous active-tool set on success, failure or cancellation
+
+The important point is that pi still executes the turn. A third-party extension tool therefore keeps its own UI, approvals and policy. DeepClause only controls which tools are available to that particular step and what should happen next.
+
+The user must start such a plan explicitly:
+
+```text
+/dc-run plans/threejs_space_invaders.dml
+```
+
+Before execution, the extension shows the required tools and asks for confirmation.
+
+The optional model-callable `dc_run` tool cannot execute contextual plans. Allowing an agent turn to start a plan that starts more agent turns would make recursion and session ownership needlessly difficult. For this first version, the boundary is simple: reusable self-contained skills may be model-called after explicit enablement; contextual plans are user-called.
+
+### A concrete example
+
+I used `/dc-plan` to create a five-step plan for a small Three.js Space Invaders game. The generated DML fixes the execution order:
+
+1. inspect the workspace and choose the integration boundary
+2. create the browser application foundation
+3. implement deterministic game state and collision logic
+4. connect the state to rendering, controls and UI
+5. run tests and build the production bundle
+
+Each step has a different tool set. Inspection gets `bash` and `read`. Pure implementation steps get `read`, `write` and `edit`. Validation gets all four. The plan records these requirements before any work starts.
+
+This does not guarantee a correct game. The model can still write bad code, misunderstand an API or produce an incomplete summary. What it does guarantee is a more explicit execution structure. The agent cannot quietly skip from initial inspection to a confident final answer without the intervening DML goals succeeding.
+
+This is the same reason I find DML useful with smaller models. Long context alone does not make long-running execution reliable. An explicit program can carry the sequence, checks, retries and fallback while the model deals with the parts that actually require judgment.
+
+### Installation
+
+The current release is `0.1.2` and depends on `deepclause-sdk` `0.0.87`.
+
+Install directly from GitHub:
+
+```sh
+pi install git:github.com/deepclause/deepclause-pi
+```
+
+Or install it for one project:
+
+```sh
+pi install git:github.com/deepclause/deepclause-pi -l
+```
+
+For a project-local installation, start pi in the directory containing `.pi/settings.json`. The startup screen should list the DeepClause extension. If it does not, `/dc-run` will be treated as an ordinary message and sent to the model.
+
+Useful commands:
+
+```text
+/dc
+/dc-list
+/dc-plan inspect this repository and propose a safe migration --name=migration
+/dc-run plans/migration.dml
+/dc-tool enable
+/dc-cancel
+```
+
+`dc_run` is disabled by default. `/dc-tool enable` makes it available to the model for that workspace. This does not grant ordinary DML programs access to all pi tools.
+
+### Some more thoughts and notes
+
+1. This is an early integration. The main execution path works and has tests for plan creation, tool preflight, contextual delegation, cancellation and tool restoration. There are still plenty of rough edges to find in real repositories.
+
+2. `task/N` supports stream events, but the current pi model adapter receives a completed model response and forwards it as one chunk. Tool activity, DML progress, input requests and usage are already live.
+
+3. Generated plans currently record tool names, but not stable hashes of their schemas. A tool can change between planning and execution. The runtime catches missing or inactive tools, while deeper schema-drift checks can be added later.
+
+4. DML backtracking does not undo external effects. If a plan writes a file and later fails, Prolog can try another clause, but the file is still there. Generated coding plans therefore use ordered steps and explicit summaries rather than pretending that side effects are transactional.
+
+5. Does this produce better coding results than an unconstrained pi turn? I have some good examples, but no benchmark yet. The useful claim for now is narrower: it gives us an executable, inspectable plan with a clear boundary around context and tools. Please try it and report what breaks.
+
+Repository: [https://github.com/deepclause/deepclause-pi](https://github.com/deepclause/deepclause-pi)
+
+DeepClause SDK: [https://github.com/deepclause/deepclause-sdk](https://github.com/deepclause/deepclause-sdk)

package/docs/DIAGRAM_INTEGRATION_PROPOSAL.md

@@ -0,0 +1,154 @@
+# DML diagrams in `deepclause-pi` — minimal design
+
+## Goal
+
+> The user asks pi to turn a DML file into a diagram — **presentation grade** or
+> **specification grade**. When it's done, a viewer opens.
+
+That's the whole feature. No command suite, no manual build/edit/check/clean
+ritual. Pi does the work; the user just asks.
+
+## How the user experiences it
+
+```text
+User:  “Make me a presentation-grade diagram of
+        skills/deep_research.dml”
+
+pi:    (calls the dc_diagram tool)
+       Creating a presentation-grade diagram for deep_research.dml…
+       (viewer opens in the browser at the Presentation view)
+
+User:  “Now a specification-grade one for the same file”
+
+pi:    (calls dc_diagram with grade=specification)
+       (viewer opens at the Specification view)
+```
+
+The DML file can live **anywhere** — a relative path, an absolute path, or a
+path outside `.pi/deepclause/`. Pi points at it; the tool reads it.
+
+Grade is inferred from the request, or passed explicitly:
+`presentation` / `presentation-grade` → Presentation; `specification` /
+`spec` / `detailed` / `technical` → Specification. If the user says "both",
+produce both views.
+
+## What the extension exposes
+
+Exactly **one model-callable tool**:
+
+```text
+dc_diagram
+  dml   : string                      // path to any .dml file (relative or absolute)
+  grade : "presentation" | "specification" | "both"   // default: presentation
+  view  : "flow" | "sequence"         // optional, default: flow
+```
+
+- Registered on startup (it is a safe, read-and-generate operation — it does not
+  execute the DML, unlike `dc_run`, so it does not need the `/dc-tool` opt-in).
+- `promptGuidelines` tell pi to call it whenever the user asks for a diagram /
+  flowchart / visual of a DML file, to infer the grade from the wording, and not
+  to hand-write Mermaid itself.
+- A short line in `AUTHORING_INSTRUCTION` / `.pi/deepclause/AGENTS.md` mentions
+  the tool and where diagrams live.
+
+Optional, only if we want manual triggering: a single `/dc-diagram <path>
+[--grade=...]` command that does exactly the same thing. Not required.
+
+## What the tool does (one call, end to end)
+
+1. Resolve the input path: relative to the workspace or absolute; require an
+   existing `.dml` file (`realpath` + extension check). No `.pi/deepclause/`
+   restriction on input.
+2. Read the DML and compute a deterministic Mermaid **seed** in-process
+   (`renderDml` / `renderSequence`, ported from `dml_flow.mjs`). Always valid.
+3. If a grade is requested, ask the active pi model to rewrite the seed in that
+   grade (reusing pi's model backend — no `pi_bash`, no API keys), then validate
+   and retry up to ~3 rounds:
+   - **Presentation**: ~8–12 nodes, plain language, headline numbers, 1–2
+     callouts, no function names or framework jargon.
+   - **Specification**: keep function names, `task`/`tool` roles,
+     post-conditions, seed data; precise for an engineer.
+   - Validation: structural checks always; real Mermaid parser via headless
+     Chrome only if Chrome is available. A broken result never reaches the
+     viewer.
+4. Write the sidecar(s) under the active workspace's
+   `.pi/deepclause/diagrams/`: `<name>.presentation.mmd` and/or
+   `<name>.specification.mmd`.
+5. (Re)build `viewer.html` (embedded manifest + vendored Mermaid).
+6. **Open the viewer** at that diagram and view:
+   `xdg-open .pi/deepclause/diagrams/viewer.html?view=presentation#<name>`
+   (fixed argv via `pi.exec`, TUI/interactive only; otherwise just return the
+   path).
+7. Return a one-line result: file, grade, and viewer path.
+
+Progress and cancellation reuse the existing `/dc-run` UI plumbing
+(`setWidget`/`setStatus`, a local `AbortController` wired to the active
+execution so `/dc-cancel` still works).
+
+## Names and collisions
+
+The viewer is keyed by the DML **file name** (without `.dml`). If two DML files
+with the same base name are diagrammed, disambiguate with a short path hash
+(e.g. `deep_research-3f9a`) so sidecars and viewer entries never collide. The
+full source path is always shown in the viewer.
+
+## Artifacts
+
+```text
+.pi/deepclause/diagrams/              # in the active workspace, regardless
+├── viewer.html                       # of where the DML source lives
+├── index.json                        # manifest (also handy for tests/scripts)
+├── <name>.md                         # Mermaid fences for editors
+├── <name>.presentation.mmd           # presentation-grade sidecar
+└── <name>.specification.mmd          # specification-grade sidecar
+```
+
+- Created lazily on first use; `initializeWorkspace()` stays untouched.
+- Output always stays under `.pi/deepclause/`; no `.deepclause/`, no `docs/`.
+- Regenerating a grade overwrites only that sidecar (the user asked for it);
+  the other grade and other diagrams are preserved.
+
+## Viewer
+
+Reuse the handbook `viewer.template.html` nearly verbatim, with the sidebar
+list, theme picker, split pane (editable Mermaid + read-only DML), SVG/PNG
+export and hash deep-links. The view dropdown becomes:
+
+`Presentation → Specification → Flow → Sequence`
+
+Fallback order for the default view: Presentation → Specification → Flow.
+
+## Code changes
+
+```text
+src/diagram/extract.ts     # TS port of dml_flow.mjs (renderDml, renderSequence)
+src/diagram/grade.ts       # model rewrite + validation/retry loop
+src/diagram/viewer.ts      # write sidecars, build viewer.html, open browser
+src/assets/viewer.template.html   # adapted; Presentation/Specification labels
+src/assets/vendor/mermaid.min.js  # vendored, written on first build
+src/runtime.ts             # export a small completeWithPiModel() helper
+src/index.ts               # register dc_diagram + authoring note
+```
+
+## Policy
+
+- No compiler, no `.deepclause/`, no DML execution.
+- Input may be any readable `.dml` path; **output** is confined to the active
+  workspace's `.pi/deepclause/diagrams/`.
+- Does not register runtime tools and does not widen `pi_bash`/approval scope.
+- Browser opening uses a fixed command, not a shell string.
+
+## Validation
+
+- Asking pi for a diagram in natural language results in a `dc_diagram` call and
+  an opened viewer.
+- A DML file outside `.pi/deepclause/` (including an absolute path) works.
+- Presentation vs specification wording selects the right grade; "both"
+  produces both.
+- Chrome present → real-parser gate; Chrome absent → structural gate, viewer
+  still opens.
+- Invalid/partial model output is retried and never written as a final sidecar.
+- Missing file / non-`.dml` input is rejected.
+- Same-name DML files do not collide in the viewer.
+- No approval prompts are raised.
+- No files appear outside `.pi/deepclause/diagrams/`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "deepclause-pi",
-  "version": "0.1.4",
+  "version": "0.2.0",
   "description": "Pi-hosted runtime for DeepClause DML programs",
   "type": "module",
   "license": "MIT",
@@ -25,11 +25,15 @@
   "files": [
     "dist",
     "docs",
-    "src"
+    "src",
+    "skills"
   ],
   "pi": {
     "extensions": [
       "./src/index.ts"
+    ],
+    "skills": [
+      "./skills"
     ]
   },
   "scripts": {