Skip to content

Figure surfaces (Mermaid/SVG/Markdown) in the skill and examples; bundled grill-with-docs - #4

Merged
YuniqueUnic merged 4 commits into
mainfrom
feat/rich-content-figures-and-grill-skill
Sep 24, 2026
Merged

YuniqueUnic merged 4 commits into
mainfrom
feat/rich-content-figures-and-grill-skill

Conversation

@YuniqueUnic

Copy link
Copy Markdown
Owner

Summary

Brings the skill up to date with schemaui 0.16's figure rendering, so agents write forms that show instead of tell — and ships an interview skill so fresh installs can grill without installing anything else.

1. Figure surfaces in SKILL.md

  • x-content — a Mermaid diagram, inline SVG, or sanitised Markdown block rendered above a question, for context a sentence can't carry.
  • x-options — each enum option (aligned by index) can carry label, description and a figure; the user picks a topology by recognising the picture. radio/select show them; segmented has no room and is rejected.
  • x-control: "mermaid" — the answer itself is a diagram, edited in a source editor with a live preview.
  • The cheat sheet gains the four new rows; the version note separates the 0.14 control hints from the 0.16 figure surfaces; the hard rules (non-empty source, index-aligned lengths, no figures on "none" options, a figure explains but is never the value) are stated up front.

2. Bundled skills/grill-with-docs

Open-ended designs need an interview before they become a schema. The bundled skill keeps the grill-me discipline — one question at a time, every question with a recommended answer, explore instead of asking, stop when converged — and adds grounding: read the cheat sheet, the examples and the engine's galleries before drafting. The main SKILL.md defers to whatever grilling skill the user already has and only falls back to the bundled one when none exists.

3. Examples and screenshots

  • New examples/deployment-architecture.schema.json (中文): three topologies, three rollout strategies and two data layers, each option with its own diagram; a node-level x-content figure on the network section; a figure-free escape hatch on purpose; a mermaid control whose answer is the call graph itself.
  • web-research-brief gains the two non-editor surfaces: a process figure above the depth slider and an editable report-flow diagram.
  • READMEs embed three new screenshots (control gallery, figure-bearing options, live mermaid editor) and document the new surfaces, the bundled grill skill and the new example.

Test plan

  • Every example in examples/ loads clean through schemaui web-snapshot (engine ≥ 0.16)
  • Real-browser walkthrough of the new example: option figures, section figure, escape hatch, and the mermaid editor render correctly (screenshots in this PR are taken from it)
  • pytest tests/: 21 passed; the 6 pre-existing e2e failures reproduce on main without these changes (environment, not this PR)

schemaui ≥ 0.16 renders figures, and the skill now teaches the agent
when to reach for them: x-content puts a Mermaid diagram, an inline SVG
or sanitised Markdown above a question; x-options attaches a figure to
each enum option (aligned by index, radio/select only — segmented has
no room for one); x-control: "mermaid" makes the answer itself a
diagram edited with a live preview. The cheat sheet gains the four
rows, the version note distinguishes the 0.14 control hints from the
0.16 figure surfaces, and the hard rules (non-empty source, aligned
lengths, no figures on "none" options, figure explains but is never
the value) are stated where the agent will actually read them.

Open-ended designs need an interview before they become a schema, so a
grill-with-docs skill ships bundled: one question at a time, every
question carrying a recommended answer, every question grounded in the
project docs and the galleries. The main skill defers to whatever
grilling skill the user already has and only falls back to the bundled
one when none exists — a convenience for fresh installs, never an
override.
deployment-architecture.schema.json is the figure-surfaces reference:
three topologies, three rollout strategies and two data layers each
carry their own Mermaid diagram (radio and select both shown), the
network section explains itself with a node-level x-content figure, an
escape-hatch select stays figure-free on purpose, and a mermaid control
lets the user edit the call graph as the answer.

web-research-brief gains the two non-editor surfaces: a process figure
above the depth slider (x-content) and an editable report-flow diagram
(mermaid control).

READMEs embed three screenshots — the control gallery, figure-bearing
options, and the live mermaid editor — and document the new surfaces,
the bundled grill skill, and the new example.
The e2e helpers probed /api/session and /api/exit — routes that existed
before the engine versioned its API at /api/v1/*, and cargo-binstall
installs the latest release, so every round-trip test 404'd the moment
a CI job picked up a modern engine. Both the shared drive_session
helper and the two inline session reads now try /api/v1 first and fall
back to the unversioned routes, so old and new engines both pass.

The web-research-brief showcase contract also covers the two new
surfaces from this branch: the mermaid x-content above the depth
slider, and /report_flow's mermaid control in the hinted-controls map.
@YuniqueUnic
YuniqueUnic merged commit c6734fc into main Sep 24, 2026
4 checks passed
@YuniqueUnic
YuniqueUnic deleted the feat/rich-content-figures-and-grill-skill branch September 24, 2026 06:36
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant