Create rich file artifacts (documents, code, reports, HTML pages) that appear as interactive cards in chat when placed in .user-visible/.
Activate when the user asks for standalone files that are better as viewable/downloadable outputs than inline chat text:
Files are shown to the user only when they are in .user-visible/ for the current session.
Use: vfs_write(".user-visible/file-name.ext", content)
This auto-resolves to the session-scoped location.
If vfs_write is not already available, bind it before proceeding:
retrieve_tools(exact_tool_names=["vfs_write", "vfs_cmd"])
For substantial work, use a two-step flow:
files/ or notes/.user-visible/Example:
vfs_write("files/draft-plan.md", draft_content)
# iterate, refine, validate
vfs_cmd("mv files/draft-plan.md .user-visible/final-plan.md")
This ensures users only see final artifacts, not intermediate drafts.
.user-visible/.user-visible/.html) by default for user-facing artifacts that should look polished.md) only when the user asks for Markdown or plain docs.txt) only when formatting is unnecessaryWhen generating HTML artifacts, prioritize quality over speed:
header, main, section, article, footer)After creating an artifact, briefly tell the user:
Keep this concise and practical.