comark-ui 0.7.1 → 0.7.4

package/dist/skills/comark-ui/references/lint.md

@@ -5,7 +5,7 @@ comark-linter reports what Comark forgives, such as a `::` block never closed, a
 ## Run the command
 
 ```sh
-npx lint-comark "docs/**/*.md" --format json --check-urls
+vp exec lint-comark "docs/**/*.md" --format json --check-urls
 ```
 
 - Pass files or globs. Quote a glob so the shell passes it as written; lint-comark expands it and skips `node_modules` and `dist`.

package/dist/skills/comark-ui/references/outline.md

@@ -30,7 +30,15 @@ The redesign moves the filters into one row and adds an empty state.
 - Every `::toc` lists the whole document, wherever it sits. With no heading from h2 to `depth`, it renders nothing, and the plugin reports it.
 - Write `::toc` where other tools use `[[toc]]`, which Comark reads as a span.
 
+## Side outline
+
+The `rail` option adds an "On this page" outline beside the text of every document with two headings or more to list, and marks the section being read. It isn't Markdown: a document can't turn it on, and `::toc` still works beside it. Write short h2 and h3 headings, since they become its links.
+
+- Options: `rail: true`, or `{ title, depth }` (default "On this page" and 3).
+- The page sets `--comark-inset-end` on `:root` for a panel that covers its right edge. While the outline keeps a column beside wide blocks, it sets `data-comark-rail` and `--comark-rail-width` on `<html>`, and the page shrinks `--comark-wide-end` by it, so wide blocks move toward the room before the text.
+- It hides where it doesn't fit, and rather than narrow a diagram.
+
 ## Register
 
-- In `comark-ui`: on in every entry, with no options.
+- In `comark-ui`: on in every entry; `outline: { rail: true }` adds the side outline.
 - Alone: `pnpm add comark @comark/html comark-outline`, then `createHtmlRenderer({ plugins: [outline()], components })` with both from `comark-outline/html`. `comark-outline/vue`, `/react`, and `/svelte` render it too. It reads the headings itself, so it works in any plugin order and without Comark's toc plugin, which only fills `meta.toc` for a sidebar. The npm name is `comark-outline` because npm refused `comark-toc`.

package/dist/skills/comark-ui/references/quiz.md

@@ -37,7 +37,7 @@ Promise callbacks are microtasks, and a timer's callback is a task.
 
 A question uses radios when one option is marked `[x]`; `multiple` makes it a checkbox question. Options are shuffled deterministically unless `shuffle="false"`. Questions and recall cards share numbering, while polls are not numbered. A missing id is derived from the block content. Use `#hint` and `#explain` on questions, and `#answer` on recall cards. Polls accept `multiple` and a date in `closes`.
 
-The HTML renderer inlines the quiz script and styles. Hosts can listen for `comark-quiz:answer` and `comark-quiz:ready`, and restore answers or results with `comark-quiz:state`; see the package [getting started guide](../../packages/quiz/docs/getting-started.md) for the event shapes and storage behavior.
+The HTML renderer inlines the quiz script and styles. Hosts can listen for `comark-quiz:answer` and `comark-quiz:ready`, and restore answers or results with `comark-quiz:state`; see [Saving answers](https://comark-ui.onmax.me/quiz/#saving-answers) on its page for the event shapes and storage behavior.
 
 ## Register
 

package/dist/skills/comark-ui/references/ui.md

@@ -36,7 +36,7 @@ comarkUi({
 | `@comark/react` | `comark-ui/react` |
 | `@comark/svelte` | `comark-ui/svelte` |
 
-The Vue, React, and Svelte entries leave out annotate and diff, which render only to HTML. Screenshots, compares, diffs, and the marks on charts need `comark-ui/html`.
+The Vue, React, and Svelte entries leave out annotate, comments, diff, and quiz, which render only to HTML. Screenshots, compares, diffs, suggestions and comments, and the marks on charts need `comark-ui/html`.
 
 To use another renderer, install it in place of `@comark/html`, such as `pnpm add comark @comark/vue comark-ui`, and pass it `plugins` and `components` as you would one package's. The preset needs Vue 3.5, React 18, or Svelte 5.20 or later. Every entry exports the `PresetOptions` type, and `comark-ui` itself exports `preset(renderer, options)`, which builds the same pair from renderer entries you pass.
 

package/dist/skills/review-document/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: review-document
+description: Turns a review's findings into one short Markdown document a reader can act on, with the verdict first and each finding ranked, located, backed by evidence, and paired with its fix. Use when writing up a code review, a design or QA review, an audit, or any report whose reader must decide what to do next.
+license: MIT
+---
+
+# Review document
+
+A review's reader has one question: what do I do now? Answer it in the first two lines, then give each finding just enough evidence that the reader trusts it without redoing your work. This skill organizes findings you already have; finding them is the review itself.
+
+Length is the usual failure. A reader who has to dig through praise, process, and restated findings misses the one that blocks the merge. Every line below the verdict either supports a finding or says what you didn't check.
+
+## 1. Decide the verdict
+
+Pick one: **approve**, **approve with changes**, **request changes**, or **blocked** on a named thing. Under it, write the reason in one sentence that names the finding behind it.
+
+Done when someone who reads only the verdict knows what to do.
+
+## 2. Keep the findings that change the decision
+
+- Keep a finding when fixing it, or not, changes what the reader should do.
+- Merge findings with one root cause into one, and list every place it appears.
+- Rank each one: **blocking** (wrong results, lost data, a security hole, broken for users), **should fix** (a real cost that can wait), or **nit**, only when the reader asked for them.
+
+Order them blocking first. Done when every finding has a rank and no two share a cause.
+
+## 3. Back each finding
+
+Each finding is four parts, in this order:
+
+1. **A title that states the consequence**, for whom: "Small avatars load the 512px image", not "Cache key issue".
+2. **Where**: the file and line, linked when there's a URL.
+3. **Evidence**, the strongest you have: a failing test or command you ran (`::tests`, a fenced block of output), a screenshot of the wrong state (measured as the before-after-evidence skill describes), the lines that cause it (a fence with the line highlighted), then reasoning. Say which it is: a finding you reproduced reads differently from one you read in the code.
+4. **The fix**: a `::diff` of the smallest change, or one sentence when the fix is a decision for the reader.
+
+Done when every blocking finding has evidence you ran or captured, or says plainly that it comes from reading the code.
+
+## 4. Say what you checked
+
+End with two short lists: what you checked and how, and what you didn't check. A review that implies more coverage than it had loses the reader's trust in the parts that were real.
+
+## 5. Write it
+
+Follow [references/example.md](references/example.md):
+
+- The verdict in a callout: `> [!CAUTION]` for request changes or blocked, `> [!WARNING]` for approve with changes, `> [!TIP]` for approve.
+- One `##` heading per finding, numbered, with its rank in the heading. About a dozen lines each, evidence included.
+- No summary that repeats the findings, no section for an empty rank, no list of what's good unless the reader asked.
+
+[references/blocks.md](references/blocks.md) has the syntax for the callout, `::tests`, `::diff`, and highlighted lines.
+
+## 6. Check the render
+
+1. Lint it, and fix until it reports no problems:
+
+   ```sh
+   vp dlx --package comark-linter --package comark-ui lint-comark review.md
+   ```
+
+   These commands use the [global Vite+ CLI](https://viteplus.dev/guide/global-cli). Without it, `pnpm dlx` takes the same arguments.
+
+2. Open the rendered page where it will be read and read it top to bottom as the reader would. Each finding's evidence should be visible without expanding anything except a long log, and each `::diff` should start at the line its finding names.
+
+Done when the page renders without problems and you've read it once as the reader.

package/dist/skills/review-document/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: "Review document"
+  short_description: "Write findings as a verdict, evidence, and fixes"

package/dist/skills/review-document/references/blocks.md

@@ -0,0 +1,69 @@
+# Blocks for a review document
+
+These blocks come with `comark-ui`, or alone with `comark-github`, `comark-tests`, `comark-diff`, and `comark-code`. The comark-ui skill (`vp dlx skills add onmax/comark-ui`) documents every block in full.
+
+## The verdict: a callout
+
+```md
+> [!CAUTION] Request changes
+> One blocking finding: after a large avatar loads, every smaller one shows the large image.
+```
+
+The text after the marker is the title. `[!CAUTION]` fits request changes or blocked, `[!WARNING]` approve with changes, `[!TIP]` approve, and `[!NOTE]` context the reader needs before the findings. Any other marker stays a plain quote and is reported.
+
+## A test run: `::tests`
+
+Paste the JUnit XML the runner wrote, unedited, so the counts are the run's own:
+
+````md
+::tests{title="pnpm test src/avatars"}
+```xml
+<testsuite name="cache.test.ts" time="0.18">
+  <testcase classname="cache.test.ts" name="returns a cached avatar"/>
+  <testcase classname="cache.test.ts" name="returns a 32px avatar after a 512px one">
+    <failure message="expected 512 to be 32">AssertionError: expected 512 to be 32</failure>
+  </testcase>
+</testsuite>
+```
+::
+````
+
+It shows the passed, failed, and skipped counts and each failure's message and stack. Most runners write the report with a flag: `vitest run --reporter=junit --outputFile=junit.xml`, `pytest --junitxml=junit.xml`, `jest --reporters=jest-junit`. For a command that isn't a test run, paste its output in a `txt` or `sh` fence instead.
+
+## The lines that cause it: a fence with `mark`
+
+````md
+```ts [src/avatars/cache.ts] mark={1}
+const cache = new Map<string, Blob>();
+```
+````
+
+`mark={1}` highlights the block's first line; ranges look like `{3-4}` or `{1, 3-4}`. Copy a few lines from the file, the ones your text names.
+
+## The fix: `::diff`
+
+````md
+::diff{line=18 label="Fix"}
+```ts [src/avatars/cache.ts]
+const key = user.id;
+```
+```ts
+const key = `${user.id}:${size}`;
+```
+::
+````
+
+Two fenced blocks, before then after, starting at the file's line `line`. One file per diff, a few lines each.
+
+## A long log: `<details>`
+
+```md
+<details>
+<summary>Full test output</summary>
+
+…
+
+</details>
+```
+
+Fold away anything the reader may skip, such as a full log under the failure that matters.

package/dist/skills/review-document/references/example.md

@@ -0,0 +1,51 @@
+# Review: avatar cache
+
+> [!CAUTION] Request changes
+> One blocking finding: after a large avatar loads, every smaller one on the page shows the large image. The fix is one line.
+
+Reviewed [acme/web#418](https://github.com/acme/web/pull/418) at `9f3c2e1`.
+
+## 1. Small avatars load the 512px image (blocking)
+
+`src/avatars/cache.ts:18`. The cache key is the user's id alone, so once the profile header loads someone's 512px avatar, the 32px avatars in comments get the same file. Reproduced with a test:
+
+::tests{title="pnpm test src/avatars"}
+```xml
+<testsuite name="cache.test.ts" time="0.18">
+  <testcase classname="cache.test.ts" name="returns a cached avatar" time="0.01"/>
+  <testcase classname="cache.test.ts" name="returns a 32px avatar after a 512px one" time="0.02">
+    <failure message="expected 512 to be 32">AssertionError: expected 512 to be 32
+    at cache.test.ts:27:31</failure>
+  </testcase>
+</testsuite>
+```
+::
+
+::diff{line=18 label="Fix"}
+```ts [src/avatars/cache.ts]
+const key = user.id;
+```
+```ts
+const key = `${user.id}:${size}`;
+```
+::
+
+## 2. The cache never evicts (should fix)
+
+`src/avatars/cache.ts:9`. Read in the code, not measured: the map grows by one entry per user and size for as long as the tab stays open, which on the team directory is thousands of images.
+
+```ts [src/avatars/cache.ts] mark={1}
+const cache = new Map<string, Blob>();
+```
+
+Cap it, such as an LRU of 500 entries, or decide the tab's lifetime is short enough not to.
+
+## Checked
+
+- Ran `pnpm test src/avatars`: one failure, above.
+- Opened a profile on the preview at 1440px and watched the comment avatars after the header loaded.
+
+## Not checked
+
+- Server rendering: the cache only runs in the browser, and I didn't confirm the server skips it.
+- Safari's memory use.

package/dist/skills/teach-lesson/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: teach-lesson
+description: Write a short lesson on one concept, with simplified English, a worked example, and an application question. Use for a lesson, a self-check, or onboarding on one idea.
+license: MIT
+---
+
+# Teach lesson
+
+A lesson teaches one concept through a worked example and an application question. Keep it short enough to finish in five minutes.
+
+## 1. Pin the concept and the outcome
+
+Infer the reader's purpose and existing knowledge from the conversation. Focus on the gap their question reveals.
+
+Name one concept and write a testable outcome, such as "Predict what happens when two people save the same record." Use a verb such as predict, explain, choose, or spot.
+
+If the outcome depends on another concept, link to its prerequisite lesson or teach that prerequisite first.
+
+Done when one sentence names the action the reader will perform and the situation they will apply it to.
+
+## 2. Find a worked example
+
+Pick a case from the reader's world where the concept prevents a visible failure. Trace it in three or four moves with concrete names, status codes, or numbers. Label invented values as illustrative.
+
+Verify behavior against a primary source, such as code or a specification. For an existing design, find recorded reasons when available. Distinguish verified behavior, recorded reasons, and inferred reasons. Preserve uncertainty such as "likely", and say when a reason is unknown.
+
+Done when each move has a concrete value, its behavior matches the source, and each design reason is sourced or qualified.
+
+## 3. Write the lesson
+
+Read [references/example.md](references/example.md) as a model for the complete lesson. Write these parts in order:
+
+1. **The outcome**, one sentence under the title.
+2. **Why it matters**: the failure the concept prevents, told as the worked example's problem. Three or four sentences.
+3. **The idea**: give the smallest complete explanation in at most four sentences. Start with a plain definition, connect it to the reader's case, and explain how it solves the problem.
+4. **The worked example**: add the supporting detail, one move per step, showing the value that changed. For text and code, use [`::steps`](references/blocks.md#the-worked-example-steps). When diagrams help explain interacting parts, use the [diagram series guidance](references/blocks.md#build-a-diagram-across-steps).
+5. **The check**, below.
+6. **Read next**: one primary source, linked to the exact section, and the lesson that naturally follows.
+
+### Use STE 100 writing rules
+
+Apply [ASD-STE100 Simplified Technical English](https://asd-ste100.org/) writing rules to the whole lesson, including the example, question, hints, and answer explanations.
+
+- Give each sentence one idea. Give each instruction one action.
+- Keep instructions within 20 words and descriptive sentences within 25 words. Use short paragraphs.
+- Use common words and active voice. Write instructions as direct commands.
+- Define each technical term in bold at first use. Use one term for each concept and keep its meaning consistent.
+- Keep technical names, code, units, and UI labels exact.
+- Put a condition before the action it controls. Make each pronoun refer to one clear subject.
+- Use literal wording and explain abbreviations. Split long noun groups into phrases.
+- State the mechanism directly, with the detail needed to follow it.
+
+Done when the outcome, problem, idea, worked example, and source link are present. Each term must have a definition before use, and each sentence must meet the applicable word limit. Preserve the example's behavior and evidence confidence.
+
+## 4. Write the check
+
+Use [`::question`](references/blocks.md#the-check-question) to test the outcome. Change one input of the worked example and ask the reader to predict, explain, choose, or spot the result.
+
+- Make each wrong option a real misconception, and give it a `>` rationale that says why it's tempting and why it's wrong.
+- Keep the options parallel, one idea each and close in length, so their shape gives no clue to the answer.
+- Add `#explain` for the one thing the reader should take away whatever they picked.
+- For a fact worth remembering a week later, optionally add a [`::recall` card](references/blocks.md#the-fact-to-keep-recall).
+
+Done when the question tests the stated outcome with one changed input, every option has a rationale, and the shared explanation resolves each misconception.
+
+## 5. Check the render
+
+1. Lint it, and fix until it reports no problems:
+
+   ```sh
+   vp dlx --package comark-linter --package comark-ui lint-comark lesson.md
+   ```
+
+   These commands use the [global Vite+ CLI](https://viteplus.dev/guide/global-cli). Without it, `pnpm dlx` takes the same arguments.
+
+2. Open the rendered page where it will be read. Select each option and check its rationale and the shared explanation.
+
+Done when lint reports no problems, every worked step and diagram is visible, and each option reveals the expected result and rationale. Confirm that the correct answer follows from the example and that the lesson fits a five-minute read.

package/dist/skills/teach-lesson/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: "Teach lesson"
+  short_description: "Teach one concept with a worked example and a check"

package/dist/skills/teach-lesson/references/blocks.md

@@ -0,0 +1,91 @@
+# Blocks for a lesson
+
+These blocks come with `comark-ui`. The steps and questions also come separately with `comark-steps` and `comark-quiz`.
+
+## The worked example: `::steps`
+
+````md
+::steps
+### Both load version 7
+
+Ana and Ben each `GET /articles/42`, and both get `ETag: "v7"`.
+
+### Ana saves first
+
+```http
+PUT /articles/42
+If-Match: "v7"
+```
+::
+````
+
+Each `###` heading starts a step that holds everything up to the next one, code blocks included. Put any introduction above the block, since a paragraph before the first heading is reported. For steps of one line each, a numbered list inside `::steps` works too.
+
+## Build a diagram across steps
+
+Use a `mermaid` fence when a diagram helps explain interacting parts. Redraw the previous diagram and add one part or relationship at each move. Keep existing labels and participant order consistent.
+
+Use numbered Markdown headings for the worked example. Mermaid fences currently disappear inside `::steps`, so place them directly under these headings:
+
+````md
+### 1. The client requests the article
+
+```mermaid
+sequenceDiagram
+  participant Client
+  participant Server
+  Client->>Server: GET /articles/42
+```
+
+### 2. The server returns a version label
+
+```mermaid
+sequenceDiagram
+  participant Client
+  participant Server
+  Client->>Server: GET /articles/42
+  Server-->>Client: ETag v7
+```
+````
+
+These paths and version labels are illustrative. Use `sequenceDiagram` for messages or `flowchart LR` for a flow. comark-ui renders Mermaid as SVG, so the reader needs no diagram script.
+
+## The check: `::question`
+
+```md
+::question{#etag-no-if-match}
+Ben's editor sends his `PUT` with no `If-Match` header. What happens?
+
+- [x] The server saves Ben's version and Ana's fix is lost
+  > Without `If-Match` there's no condition to fail.
+- [ ] The server refuses the save with a 412 status code
+  > A 412 needs a condition that failed.
+
+#hint
+What does the server compare the label against?
+
+#explain
+`If-Match` is opt-in.
+::
+```
+
+- Mark the right option `[x]`. One `[x]` makes radio buttons; add `multiple` to the block for checkboxes with several right options.
+- The `>` quote under an option is its rationale, shown once the reader answers.
+- `#hint` is optional, shown on request; `#explain` shows after any answer.
+- Options are shuffled the same way on every render; write `shuffle="false"` only when their order means something, such as numbers in order.
+- Give the block an `#id` so a host can store the answer. Without one, the id comes from the question's text and changes when you edit it.
+
+Without its script, the question and an answer disclosure still render as plain HTML.
+
+## The fact to keep: `::recall`
+
+```md
+::recall{#etag-412}
+What does a server answer when `If-Match` names an old version?
+
+#answer
+`412 Precondition Failed`, and it leaves the resource unchanged.
+::
+```
+
+The reader answers in their head, then reveals `#answer`.

package/dist/skills/teach-lesson/references/example.md

@@ -0,0 +1,70 @@
+# Keep both writers' changes
+
+After this lesson, you can predict how a server handles two changes to the same record, with or without a version check.
+
+## Why it matters
+
+In this example, Ana and Ben open the same help article. Ana corrects a spelling error and saves the article. Ben adds a paragraph to his older copy and saves it. His save removes Ana's correction without a warning. This is a **lost update**.
+
+## The idea
+
+An **ETag** is a version label, such as `"v7"`, that the server sends with a resource. The **If-Match** header carries that label back to require the same version before saving a change. If the labels match, the server saves the change. If the labels differ, the server returns `412 Precondition Failed` and keeps the resource unchanged.
+
+## Worked example
+
+::steps
+### Both load version 7
+
+Ana and Ben each `GET /articles/42`, and both get `ETag: "v7"`.
+
+### Ana saves first
+
+```http
+PUT /articles/42
+If-Match: "v7"
+```
+
+The article is still at `"v7"`. The server saves Ana's change and returns `200 OK` with `ETag: "v8"`.
+
+### Ben saves second
+
+```http
+PUT /articles/42
+If-Match: "v7"
+```
+
+The article is now at `"v8"`. The labels differ, so the server returns `412 Precondition Failed`. Ana's correction stays.
+
+### Ben reloads and merges
+
+Ben's editor fetches `"v8"` and shows Ana's correction. Ben adds his paragraph to that version. He saves again with `If-Match: "v8"`.
+::
+
+## Check yourself
+
+::question{#etag-no-if-match}
+This API accepts requests without `If-Match`. Ben's editor sends his `PUT` without that header. The article is at `"v8"`. What happens?
+
+- [x] The server saves Ben's version and removes Ana's correction
+  > Without `If-Match`, the server has no version condition to check. The server saves Ben's version. This removes Ana's correction.
+- [ ] The server refuses the save with a 412 status code
+  > A 412 response requires a condition that failed. Ben sent no condition, so the server has no labels to compare.
+- [ ] The server merges Ben's paragraph into version 8
+  > The server does not combine the two versions. After a 412 response, the client must get the current version and combine the changes.
+
+#explain
+The client must send its original version label for `If-Match` to protect the change. An API can require that header. If the header is absent, that API can return `428 Precondition Required`.
+::
+
+::recall{#etag-412}
+What does a server answer when `If-Match` names an old version?
+
+#answer
+`412 Precondition Failed`, and it leaves the resource unchanged.
+::
+
+## Read next
+
+[RFC 9110, section 13.1.1](https://www.rfc-editor.org/rfc/rfc9110#name-if-match) defines `If-Match`.
+
+The next lesson explains weak ETags and why `W/"v7"` never matches `If-Match`.

package/dist/skills/visual-explanation/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: visual-explanation
+description: Explains how something works with the smallest visual that answers the question, such as a sequence diagram, a call tree, a file tree, or a marked-up screenshot, placed beside the sentence it supports. Use when someone asks to be shown how a system, a flow, or a change works, or when the answer would otherwise take paragraphs of prose.
+license: MIT
+---
+
+# Visual explanation
+
+A good explanation answers one question with one picture the reader can check against the code. Prose carries the reasoning, and the visual carries the shape: what happens in what order, what calls what, what lives where. Each visual stands next to the sentence that tells the reader what to look for.
+
+## 1. Name the question
+
+Write the question in one sentence, in the reader's words: "What happens between `parseMarkdown` and the HTML?" If it's two questions, answer the one they asked and offer the other.
+
+Done when the question fits on one line.
+
+## 2. Pick the view
+
+Choose by the shape of the answer:
+
+| The answer is… | Draw |
+| --- | --- |
+| The order of events between parts | A `mermaid` sequence diagram or flowchart |
+| Who calls whom | A call tree in a `text` fence, indented by call depth |
+| Where code lives, or which files a change touches | `::file-tree`, with `+`, `-`, and `~` marks |
+| The states something moves between | A `mermaid` `stateDiagram-v2` |
+| Something on screen | `::screenshot` with measured marks |
+| What a few lines do, line by line | A code fence with `// <1>` notes |
+| How a number changed | `::chart` or a two-row table |
+
+Use one primary view. Add a second only when it answers the question the first one raises, such as "where is that in my code?" after a flow diagram. [references/blocks.md](references/blocks.md) has the syntax of each.
+
+Done when you can say, in one sentence, what the reader will see in the view.
+
+## 3. Draw it from the source
+
+Read the code, the product, or the data before you draw. Every box, arrow, file, and label in the view is something the reader can find: a real function name, a real file path, a state the code really has. Leave out the parts that don't bear on the question; a diagram of everything answers nothing.
+
+Keep a diagram to about eight nodes or participants. Past that, split it by stage or zoom into the part the question is about.
+
+Done when every label in the view exists in the source, and nothing in it is there only for completeness.
+
+## 4. Write around it
+
+[references/example.md](references/example.md) shows the shape:
+
+1. A title that is the question, or its answer.
+2. Two or three sentences with the answer in plain words, ending on what to look at in the view.
+3. The view.
+4. One or two sentences for what the view can't show, such as a rule that applies at every step.
+5. A second view only if step 2 allowed one, with a sentence before it saying why it's there.
+
+Done when the explanation reads top to bottom in under a minute and every visual has a sentence beside it.
+
+## 5. Check the render
+
+1. Lint it, and fix until it reports no problems:
+
+   ```sh
+   vp dlx --package comark-linter --package comark-ui lint-comark explanation.md
+   ```
+
+   These commands use the [global Vite+ CLI](https://viteplus.dev/guide/global-cli). Without it, `pnpm dlx` takes the same arguments.
+
+2. Open the rendered page where it will be read and look at each view at the width the reader has. A diagram whose labels are too small to read needs fewer nodes, not a wider page.
+
+Done when you've looked at the render and every label reads at its size.

package/dist/skills/visual-explanation/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: "Visual explanation"
+  short_description: "Explain how something works with one checkable visual"

package/dist/skills/visual-explanation/references/blocks.md

@@ -0,0 +1,89 @@
+# Blocks for a visual explanation
+
+These blocks come with `comark-ui`. The comark-ui skill (`vp dlx skills add onmax/comark-ui`) documents every block in full.
+
+## Diagrams: a `mermaid` fence
+
+````md
+```mermaid
+sequenceDiagram
+  participant Browser
+  participant Worker
+  participant Assets
+  Browser->>Worker: GET /zoom/
+  Worker->>Assets: zoom/index.html
+  Assets-->>Browser: prerendered page
+```
+````
+
+comark-ui draws Mermaid as SVG while parsing, so the page needs no script to show it. Use `flowchart LR` for a pipeline, `sequenceDiagram` for messages between parts, and `stateDiagram-v2` for states. Write labels as the code names them. For a diagram in another language, `d2`, `dot`, `plantuml`, `dbml`, `goat`, and `svgbob` fences draw through comark-diagrams.
+
+## A call tree: a `text` fence
+
+````md
+```text
+renderPage
+  parseMarkdown
+    plugins' post
+  renderHtmlFromDocument
+    components
+```
+````
+
+Indent by call depth, two spaces a level. Name functions as the code does.
+
+## Files: `::file-tree`
+
+````md
+::file-tree
+```
+docs/
+  build.ts  # renders every page
+  ~ style.css
+  + pages/
+    + skills/
+...
+```
+::
+````
+
+Two spaces nest an entry, a trailing `/` makes a folder, `+`, `-`, and `~` mark added, removed, and changed, and ` # ` starts a note. `...` stands for entries left out. Write the tree in a fence; a Markdown list renders names like `__init__.py` as bold.
+
+## Line notes: `// <1>` and a list
+
+````md
+```ts
+const document = await parseMarkdown(source, { plugins }); // <1>
+const html = await renderHtmlFromDocument(document, { components }); // <2>
+```
+
+1. Every plugin runs here.
+2. Components only draw.
+````
+
+A numbered list right after the fence becomes the notes. The marker goes in a line-end comment in the block's language, such as `# <1>` in Python.
+
+## On screen: `::screenshot`
+
+```md
+::screenshot{src="https://example.com/settings.png" alt="Settings page with the Save button" viewport="1280x800"}
+:::annotation{x=71.2 y=84.1 w=12.4 h=6.3}
+**Save** writes all three tabs at once.
+:::
+::
+```
+
+Measure `x y w h` from the page as percentages of the image. The before-after-evidence skill explains how.
+
+## Numbers: `::chart`
+
+```md
+::chart{type="bar" title="Build time, seconds"}
+| Step | Before | After |
+| --- | --: | --: |
+| Parse | 4.1 | 1.2 |
+| Render | 2.3 | 2.2 |
+::
+```
+
+The chart draws from the table, so the numbers in your text and the chart can't disagree.