toastty-scratchpad

name

toastty-scratchpad

description

Use this skill to show the user anything visual — design mockups, UI/UX wireframes, layout or option comparisons, architecture and data-flow diagrams, charts, tables, dashboards, timelines, state machines, or any content clearer laid out spatially than as prose. Prefer it over screenshotting an HTML file to /tmp, handing the user an image path, or sketching ASCII in chat; it renders the artifact directly in the user's Toastty workspace. Also use it to read, review, summarize, or update an existing Scratchpad panel.

Toastty Scratchpad

Reach for the Scratchpad whenever you have something visual to show the user — not only when asked for one. If you produced a mockup, comparison, or diagram, present the result here rather than pointing the user at a file path. This includes artifacts you rendered and screenshotted with agent-browser to validate: the screenshot is for your verification, the Scratchpad is how the user sees it.

Use Scratchpad when a visual surface will communicate better than terminal prose. If the user asks to read or review an existing Scratchpad, export the current session-linked Scratchpad and answer from that content without replacing it. If the user asks to create or update a visual artifact, open the Scratchpad first with a quick loading screen, optionally replace it with meaningful intermediate valid HTML snapshots or exact targeted patches as the artifact takes shape, then publish the finished self-contained HTML artifact.

Read Existing Scratchpad

When the user asks to read, inspect, review, summarize, or propose changes based on the current Scratchpad, do not publish a loading screen and do not replace Scratchpad content.

The current Scratchpad is the one linked to the current managed agent session. Prefer the session-bound path; do not scan the workspace to guess which Scratchpad is relevant.

1. Confirm TOASTTY_CLI_PATH and TOASTTY_SESSION_ID are available.
2. Export the linked Scratchpad directly:

"$TOASTTY_CLI_PATH" --json action run panel.scratchpad.export \
  "sessionID=${TOASTTY_SESSION_ID}"

3. Read the returned filePath and answer from that content.
4. If diagnostics or runtime metadata are needed, query the returned panelID:

"$TOASTTY_CLI_PATH" --json query run panel.scratchpad.state \
  "panelID=<panel-id>"

Only fall back to panel/workspace targeting when TOASTTY_SESSION_ID is missing, the current session has no linked Scratchpad, or the user explicitly asks for a different Scratchpad. If panel.scratchpad.export is unavailable in the running app, say so briefly and use the best available panel-targeted fallback rather than guessing silently.

Open First

When creating or replacing a visual Scratchpad artifact and a Toastty-managed session is available, publish a quick loading screen before doing deeper analysis, reading large files, or building the final artifact. The loading screen tells the user that a visual artifact is being prepared.

The loading screen is intentionally minimal: a title (if known) and a subtle animated indicator. Do not pre-mock the structure of the final artifact. Pre-mocking biases the design toward the same look every time and flattens visual variety across runs.

Publish the loading screen:

~/.agents/skills/toastty-scratchpad/scripts/publish-scratchpad-outline.sh \
  "Architecture Map"

If the user explicitly asks for a new, separate, or additional Scratchpad rather than an update to the current one, pass --new on this first loading-screen publish only:

~/.agents/skills/toastty-scratchpad/scripts/publish-scratchpad-outline.sh \
  --new \
  "Architecture Map"

Then do the needed thread/file/prompt analysis and publish updates over the same session-linked Scratchpad.

Input Modes

• Thread context: publish a loading screen, then synthesize the visual from the current conversation, implementation plan, bug investigation, or decision tradeoff.
• File input: publish a loading screen before deep reading, then read the referenced file, extract the structure that matters, and create a visual representation. Do not dump a long file verbatim into the panel.
• Manual prompt: publish a loading screen from the prompt, then follow the prompt as the design brief. If the prompt is broad, choose a compact final visual that answers the likely need.
• Existing Scratchpad: export the Scratchpad linked to TOASTTY_SESSION_ID, read the exported HTML, and answer in chat unless the user explicitly asks you to republish an updated artifact.

Good Uses

• architecture maps and module boundaries
• data flow, request flow, lifecycle flow, and state machines
• data visualization, charts, tables, dashboards, metric cards, trend views, distributions, and ranked comparisons
• UI/UX wireframes, screen flows, layout comparisons, and interaction maps
• timelines, sequencing, dependency graphs, risk maps, and test matrices
• visual summaries of text when grouping, hierarchy, or spatial layout adds clarity

Avoid Scratchpad for ordinary logs, raw command output, long code listings, or prose that is already clearer in chat or a local document.

Design Direction

Reach for the simplest visual that communicates the structure. Restraint is the goal, not richness. Three boxes and two arrows on a clean background usually beats an ornate poster with the same information. Variety should emerge from picking the right structure for each subject, not from changing the decorative skin.

Match the visual to the structure of the content:

• Architecture or systems → labeled boxes with explicit connectors. Show boundaries, hide internals.
• Data or metrics → one well-annotated chart, or a ranked list with hierarchy. Annotate the points that matter; drop the rest.
• Flows or sequences → numbered steps or a swimlane. Linear beats radial unless the data is genuinely cyclic.
• Comparisons → side-by-side columns sharing rows, or a 2×2.
• Timelines → one horizontal track with proportional spacing.
• Wireframes → line drawings on a neutral background with sparse annotations.
• State machines → nodes and labeled transitions.
• Risk or tradeoffs → 2×2 or quadrant.

Default visual choices:

• Palette: two to four colors total. One background, one foreground for text, one accent for emphasis. Add a second accent only when the content has two real categories. Prefer light or neutral backgrounds; avoid saturated dark dashboards and full-bleed gradients. Let content-driven palettes (red for risk, sepia for archive) inform choice when relevant, but stay restrained.
• Typography: one typeface, with weight and size carrying hierarchy. Add a second face only with a real reason (mono for code or tabular data, a display weight for a single headline). Prefer system fonts by default. Remote HTTPS font files are allowed only through inline @font-face declarations; remote font CSS imports remain blocked.
• Layout: generous whitespace, clear alignment, deliberate negative space. Avoid auto-fit grids of identical cards (the AI-default look) and avoid magazine spreads or poster compositions that compete with the content.
• Visual primitives: thin clean strokes, simple boxes, plain arrows, real tick marks. Decorative texture (paper grain, halftone, blueprint grid, isometric stacks) only when the subject genuinely calls for it — never as default polish.

Two failure modes to avoid:

• AI-default dashboard: display: grid; grid-template-columns: repeat(auto-fit, minmax(...)) of identical cards on dark slate. Stop and pick a structure that expresses the content.
• Over-designed poster: heavy ornament, multiple typefaces, decorative textures, and high-saturation palettes that drown the actual information. If the artifact looks impressive before you read it, it is too loud.

Distill First

Concision is the second goal, alongside restraint. Even when the source is large or complex, the artifact should show the smallest set of nodes, lines, and labels that answers the user's question.

Before generating HTML:

1. State, in one sentence, what the artifact must communicate. Build around that and cut anything that does not serve it.
2. Cluster and group. If the source has thirty items, find the four or five groupings that explain the shape. Show the groupings; leave specifics to chat or a follow-up artifact.
3. Shorten labels. Three or four words per node usually beats a sentence. Move detail to small captions or a single side-margin block.
4. Prefer one tight diagram over a dashboard of small multiples, unless comparison across multiples is the point.
5. Drop decoration that does not encode meaning. Every line, color, and shape should carry information.

If the artifact starts to feel busy, the answer is almost always to remove elements, not to redesign them.

Build The Artifact

1. After the loading screen is visible, write the one-sentence purpose, pick the simplest visual form that captures it, and choose a restrained palette and typeface. Sketch the structure mentally first; do not start with a card grid by reflex, and do not start with poster ornament.
2. Generate one complete HTML document with inline CSS and optional inline JavaScript.
3. Keep it self-contained:
   • no remote scripts, stylesheets, images, or network fetches
   • use remote HTTPS font files only through inline @font-face declarations, and only when they materially improve the artifact
   • use inline SVG, CSS, HTML, and small inline data assets when useful
   • keep content under roughly 1 MB
4. Design for a resizable panel:
   • responsive layout
   • readable at narrow and wide widths
   • no text overlap
   • enough labels that the user can understand the artifact without chat context
5. Replace the initial loading screen by publishing again. If updating an existing topic in the same managed session, reuse the current Scratchpad instead of creating a separate artifact. If the first loading screen used --new, omit --new on later publishes so they update that newly linked Scratchpad.

Progressive Updates

Use whole-document publishing for the first Scratchpad update, full redesigns, major structure changes, or any case where you cannot form an exact unique oldText from the current HTML. To create a progressive-building effect, publish complete valid HTML snapshots at meaningful checkpoints while the artifact is being built, then publish the polished final version.

• Each update must be a full HTML document or complete renderable HTML snapshot, not a fragment or diff.
• Publish only at stable points where the content is useful and syntactically valid. Good checkpoints are a finalized layout shell, populated major sections, complete data visualization, and final polish.
• Avoid publishing every small edit or token stream. Each update reloads the generated iframe, which can reset scroll, focus, animation, and JavaScript state.
• Keep using the same helper and session. The helper sends the full content through panel.scratchpad.set-content, so repeated publishes update the existing Scratchpad instead of creating separate panels.
• Use --new only when the user explicitly asks for a new, separate, or additional Scratchpad, and only on the first publish for that artifact. Passing --new again intentionally creates another Scratchpad and unbinds the previous session-linked one.
• If an intermediate snapshot uses JavaScript, keep the no-blank-state and diagnostics guidance below in place just as you would for the final artifact.

Targeted Patch Updates

Use panel.scratchpad.patch-content only for small, exact edits to an existing session-linked Scratchpad. Before patching, export the current Scratchpad or query its state so you have the current revision; export whenever you do not already have the exact current HTML. Do not patch from stale memory.

Patch rules:

• expectedRevision is required and must match the current Scratchpad revision.
• patch is a JSON string, best passed with --stdin patch.
• Patch JSON is limited to 262,144 UTF-8 bytes.
• The top-level patch object only accepts replacements; each replacement object only accepts oldText and newText. Unknown fields are rejected.
• replacements must be non-empty.
• Each oldText must be non-empty and occur exactly once in the current intermediate HTML.
• Replacements apply sequentially, so earlier edits can affect later matches.
• A successful patch still reloads the generated iframe, so scroll, focus, animation, and JavaScript runtime state are not preserved.

Example:

"$TOASTTY_CLI_PATH" --json action run panel.scratchpad.export \
  "sessionID=$TOASTTY_SESSION_ID"

Read the exported filePath, choose a unique exact oldText, and use the returned revision:

cat > /tmp/scratchpad-patch.json <<'JSON'
{
  "replacements": [
    {
      "oldText": "<section id=\"risk\">Old copy</section>",
      "newText": "<section id=\"risk\">New copy</section>"
    }
  ]
}
JSON

"$TOASTTY_CLI_PATH" --json action run panel.scratchpad.patch-content \
  --stdin patch \
  "sessionID=$TOASTTY_SESSION_ID" \
  "expectedRevision=<revision>" < /tmp/scratchpad-patch.json

If oldText is missing, duplicated, hard to quote, or spread across unrelated regions, publish a complete replacement document instead.

Inline JavaScript

Scratchpad supports inline JavaScript, but the generated document runs in a sandboxed iframe with a strict content security policy. JavaScript can enhance the artifact, but the core information should remain visible without it whenever practical.

• Prefer pre-rendered HTML/SVG for charts, tables, metric cards, and other static data views.
• Use inline JavaScript for real interactivity such as filtering, sorting, expand/collapse, hover details, or client-side measurements.
• Put executable code in <script> blocks and wire interactions with addEventListener after the relevant DOM nodes exist.
• Inline event attributes such as onclick, onchange, and onload are blocked by CSP (script-src-attr 'none'), and javascript: URLs are unsupported. Do not use them.
• Do not rely on external scripts, imports, remote styles, CDN chart libraries, network fetches, XHR, websockets, workers, nested frames, forms, local storage, or remote assets other than HTTPS font files declared directly with inline @font-face.
• Embed all data inline, either directly in the script or in a local <script type="application/json"> block.
• Wrap startup/rendering code in try/catch. On failure, render a visible error message in the artifact and call console.error(...) with useful context.
• Avoid blank startup states where all data appears only after JavaScript runs. If JavaScript is required, include a visible loading/failure container that is replaced after successful render.

Diagnostics

If a published Scratchpad looks blank or incomplete, do not assume JavaScript is disabled. First inspect the panel state for generated-content diagnostics. Use the panelID returned by the publish helper:

"$TOASTTY_CLI_PATH" --json query run panel.scratchpad.state "panelID=<panel-id>"

The state response includes recentDiagnostics when the generated iframe reports console messages, JavaScript errors, unhandled promise rejections, or CSP violations. Pay attention to:

• source: generated-content means the agent-authored iframe reported it.
• kind: javascript-error, unhandled-rejection, csp-violation, or console-message.
• message and metadata: the failure detail, blocked URI/directive, source location, or stack when available.

Fix the artifact from those diagnostics before republishing. If recentDiagnostics is empty but the panel is still blank, confirm the current document/revision and content length in the same state response.

When debugging JavaScript, add short console.info(...) checkpoints around startup and event handlers, republish, and verify they appear as generated-content console-message diagnostics.

Read Current Scratchpad

When the user asks you to look at, read, inspect, use, or implement what is in the current Scratchpad, export the session-linked Scratchpad through Toastty before acting on it.

In a Toastty-managed agent terminal, run:

"$TOASTTY_CLI_PATH" --json action run panel.scratchpad.export "sessionID=$TOASTTY_SESSION_ID"

Read the returned filePath as the current Scratchpad HTML, then use that content as the source for the requested work. The response also includes panelID, documentID, revision, and title for diagnostics or follow-up state queries.

If export reports that the session has no linked Scratchpad, ask the user to bind the Scratchpad to this agent from the Scratchpad action menu or specify the relevant Scratchpad panel.

Publish

Pipe generated HTML into the helper:

~/.agents/skills/toastty-scratchpad/scripts/publish-scratchpad-html.sh \
  --title "Architecture Map" < /tmp/scratchpad.html

Or publish an already-generated HTML file:

~/.agents/skills/toastty-scratchpad/scripts/publish-scratchpad-html.sh \
  --title "Data Flow" \
  --file /tmp/data-flow.html

For an explicit new/separate Scratchpad, add --new to the first publish:

~/.agents/skills/toastty-scratchpad/scripts/publish-scratchpad-html.sh \
  --new \
  --title "Data Flow" \
  --file /tmp/data-flow.html

The helper requires TOASTTY_CLI_PATH and TOASTTY_SESSION_ID, which are present in Toastty-managed agent terminals. It sends content via panel.scratchpad.set-content using stdin so shell quoting is not part of the protocol.

After Publishing

• Tell the user what you put in the Scratchpad and summarize the key visual.
• Mention if the helper reported a panel/document/revision so the user knows the update succeeded.
• If the helper succeeds but the panel is not visible or appears incomplete, query panel.scratchpad.state for the returned panelID and inspect recentDiagnostics before republishing.