docs: surface attachments in README + note vision-model / [visual] gotchas#535
Merged
Merged
Conversation
…gotchas Attachment support (url/image/document/html on an instrument's attachment bank) is well covered in docs/cookbook/with-attachments.md, but the README never mentions it — the prominent run_panel/instrument examples only show a text stimulus, so it reads as "panels are text-only." Add an Attachments subsection under "Defining Instruments" that links the cookbook. Also document two gotchas that aren't called out anywhere and are easy to hit when dogfooding a URL/screenshot panel: - image/screenshot attachments require a vision-capable model; text-only models (e.g. claude-3.5-haiku) fast-fail. - fetch_mode: screenshot needs the `[visual]` extra (Playwright). Docs only — no code or behavior change. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
claude-dataviking
requested review from
openclaw-dv and
the-data-viking
as code owners
the-data-viking
approved these changes
Jun 3, 2026
the-data-viking
added a commit
that referenced
this pull request
Jun 3, 2026
Cuts the patch release containing the four bug fixes merged today (#540 cost hint, #541 mcp-install path, #542 dry-run vision guard, #543 report synthesize hint) plus the attachments docs (#535). Pre-bumps __version__.py and re-renders the version artifacts (render_site.py, render_site_markdown.py, render_server_card.py) so auto-tag.yml hits its "nothing to commit" path and only tags v1.5.6 — its direct version-bump push to main is currently rejected by branch protection (GH013), which is why applying semver:patch to a regular fix PR (#543) failed to release. Filing that pipeline issue separately. Co-authored-by: Wesley Johnson <wesley@dataviking.tech> Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
While dogfooding SynthPanel against a live site (passing the published page as a
urlattachment), I initially concluded attachments weren't supported — because the README never mentions them. The prominentrun_panel/ "Defining Instruments" examples only show a textstimulus, so it reads as "panels are text-only." The feature is actually well-documented indocs/cookbook/with-attachments.md— it's purely a discoverability gap.Then, building the run, I hit two things that aren't called out anywhere:
image/screenshotattachments require a vision-capable model. Aclaude-3.5-haikurun fast-failed (good guard!) with "model … does not support image or document attachments." The fix (useclaude-haiku-4.5etc.) isn't documented.fetch_mode: screenshotneeds the[visual]extra (Playwright) — not mentioned near the attachment docs.What
url+fetch_modeexample, the two gotchas, and a link to the cookbook recipe.with-attachments.md): two bullets in Notes for the vision-model requirement and the[visual]extra.Docs only — no code/behavior change.
Related friction (filing separately as issues)
panel run --dry-runvalidates "OK" even when the instrument has image attachments but the chosen model is text-only — it could warn there.panel run --savepersists raw Q&A but the report showsSynthesis: Not run(synthesis is the headline value).synthpanel report's "Next" hint suggestssynthpanel cost <result-id>, butcostonly acceptssummary.synthpanel mcp installwrote a barecommand: synthpanelfrom a venv (not the resolved abs path), which won't launch if synthpanel isn't on PATH.🤖 Generated with Claude Code