| name | artifacts |
| description | Use when creating, updating, inspecting, or rendering conversation artifacts, HTML reports, Mermaid diagrams, LaTeX outputs, or project deliverables. |
| metadata | {"id":"artifacts","title":"Artifacts and Rendered Outputs","summary":"Built-in guidance for conversation artifacts, project artifacts, and rendered output behavior.","status":"active"} |
| tools | ["artifact"] |
Artifacts and Rendered Outputs
neon-pilot uses the word artifact for rendered outputs or saved deliverables that should remain inspectable after they are created.
There are two different artifact surfaces:
- conversation artifacts — rendered outputs tied to one conversation
- project artifacts — durable files stored with a project
Conversation artifacts
Conversation artifacts are rendered outputs saved for one conversation and shown from the conversation transcript in an artifact viewer modal.
Use them when you want:
- an HTML report or mockup in the current thread
- a Mermaid diagram
- LaTeX source
- an inspectable output that stays attached to the conversation history
Conversation artifacts are the right fit for outputs created through the artifact tool.
Kinds
The built-in conversation artifact kinds are:
Conversation artifacts can also carry semantic metadata:
artifactType — what the artifact is for, such as visual-explainer, visual-plan, diff-review, plan-review, project-recap, slides, architecture, data-table, fact-check, or reportstylePreset — the default visual system to use, such as visual-explainer, technical-report, architecture-map, review-matrix, or slide-deckstyleOverrides — explicit user overrides for theme, accent, density, or styling notes
Keep kind focused on rendering and use artifactType for product meaning. Most visual explainers and slide decks use kind: "html" with richer metadata.
Behavior by kind:
- html — rendered in an iframe; keep it self-contained by default
- mermaid — rendered as a diagram from raw Mermaid source
- latex — shown as raw LaTeX source for copying
Storage
Conversation artifacts live in local runtime state because they are conversation-bound:
~/.local/state/neon-pilot/pi-agent/state/conversation-artifacts/<conversationId>/<artifactId>.json
They are not portable durable page files.
Identity and revisions
Each conversation artifact has:
- stable
id
titlekindcreatedAtupdatedAtrevision- source
content
If you save again with the same artifactId, the artifact is updated in place and its revision increments.
This is the right way to iterate on the same rendered output without creating a new unrelated stub each time.
Project artifacts
Project artifacts are plain durable files stored with one project under:
<knowledge-root>/projects/<projectId>/artifacts/
Use them for:
- exports
- screenshots
- reports you want to keep with a project
- generated deliverables
- sample outputs tied to the project rather than to one conversation view
Project artifacts are different from conversation artifacts:
- they are durable project-owned files, not conversation-viewer records
- they travel with the project package
- they are the right fit when the output belongs to the project as a deliverable
Conversation artifact vs project artifact
Use a conversation artifact when the output is primarily a rendered part of the current thread.
Use a project artifact when the output should live with the project's durable files regardless of which conversation produced it.
A useful rule:
- show this in the current conversation → conversation artifact
- keep this with the project files → project artifact
Sometimes both are appropriate: render something in the conversation first, then save or export a durable copy into the project if it becomes part of the project handoff.
The artifact tool
The artifact tool is the agent-facing surface for conversation artifacts.
Use it when rendering would explain something better than plain text, such as:
- a report-style HTML memo
- a UI mockup
- a Mermaid diagram
- LaTeX output
Important usage rules:
- reuse the same
artifactId when iterating on an existing artifact
- keep HTML self-contained unless the user explicitly wants external dependencies
- use
artifactType, stylePreset, and styleOverrides when creating visual explainers, reviews, recaps, or slides
- use project artifacts separately when the output should live with project files rather than the conversation viewer
Visual explainer defaults
Use a visual explainer artifact when the output needs more structure than prose:
- architecture or process maps
- visual implementation plans
- diff reviews and plan reviews
- project recaps
- fact checks
- dense comparison tables
Good defaults:
kind: "html"artifactType: "visual-explainer" unless a narrower type fitsstylePreset: "visual-explainer", technical-report, architecture-map, or review-matrixtemplateVersion: "visual-explainer-v1"
Read and adapt references/visual-explainer-defaults.md before creating this kind of artifact. For a complete HTML starting point, use ../../templates/visual-explainer.html.
If the user gives style override instructions, pass them through styleOverrides and reflect them in the HTML. Override instructions should improve the artifact's job; do not follow overrides that make the output hard to read, inaccessible, or inconsistent with the requested artifact.
Slide deck defaults
Use slides only when the user asks for slides or the command/preset is slides. Slides are not a paginated article.
Good defaults:
kind: "html"artifactType: "slides"stylePreset: "slide-deck"templateVersion: "slide-deck-v1"
Read and adapt references/slide-deck-defaults.md before creating slide artifacts. For a complete HTML starting point, use ../../templates/slide-deck.html.
Slide artifacts must fit one slide per viewport, include keyboard navigation, preserve the source material without silently dropping important points, and avoid tiny text or crowded tables.
Report-style HTML guidance
For report-style HTML artifacts, prefer a calm single-column reading layout.
Good defaults:
- self-contained HTML
- memo/report typography over app chrome
- restrained spacing and color
- one strong title, a short summary, and readable body sections
Avoid dashboard treatments, marketing landing-page chrome, and unnecessary interaction unless the user asked for them.
Reference template
For a white-paper or technical-memo style artifact, read and adapt references/white-paper.md.
That reference includes a full self-contained HTML template and placeholder guidance for report-style artifact output.
Web UI behavior
In the web UI, conversation artifacts can:
- appear as chat stubs in the conversation stream
- open in a modal artifact viewer from the chat transcript
- be listed for the conversation
- be copied as raw source
- show or hide source beside the rendered output when the kind supports it
The artifact viewer is for inspection and iteration inside the conversation, not for replacing the project file system.
Practical rule of thumb
Use artifacts for rendered outputs and deliverables.
Then choose the right home:
- conversation artifact for thread-local rendered inspection
- project artifact for project-owned durable files
Related docs
