feat: context files for A2UI format, artifact conventions, researcher instructions

2026-05-26 20:03:53 +00:00
parent 9f5a407773
commit 9367d2b957
4 changed files with 444 additions and 0 deletions
@@ -0,0 +1,84 @@
+# Artifact Conventions
+
+Artifacts are persistent markdown documents written to the filesystem. They appear
+in the right panel and survive across sessions, making them ideal for research worth
+saving: comparison guides, curated lists, reports, and actionable recommendations.
+
+## Writing Pattern
+
+Use the `write_file` tool to create artifacts:
+
+```python
+write_file("artifacts/<session_id>/<name>.md", content)
+```
+
+The `session_id` is available in your context. Use it to namespace files per session
+so multiple sessions don't overwrite each other's work.
+
+## File Naming
+
+- **Format**: kebab-case
+- **Extension**: `.md`
+- **Style**: Descriptive, specific — say what the file contains
+
+```
+artifacts/<session_id>/hybrid-cars-under-10k-woodinville.md
+artifacts/<session_id>/project-management-tools-comparison.md
+artifacts/<session_id>/seattle-tokyo-flights-may-2025.md
+```
+
+## Content Format
+
+Each artifact should follow this structure:
+
+1. **H1 title** — Clear, specific heading
+2. **Date and scope summary** — When the research was done and what it covers
+3. **Markdown tables** for side-by-side comparisons (price, features, ratings)
+4. **Bullet points** for recommendations, pros/cons, and key takeaways
+5. **Source URLs** — Link to each page or listing referenced
+6. **Closing section** — End with "Next Steps" or "Summary"
+
+```markdown
+# Hybrid Cars Under $10K — Woodinville WA (May 2025)
+
+**Researched:** May 2025 · **Scope:** CarGurus, Autotrader, Craigslist within 30 mi
+
+## Comparison
+
+| Make/Model | Year | Price | MPG | Mileage |
+|---|---|---|---|---|
+| Toyota Prius LE | 2019 | $8,500 | 52 | 61,000 mi |
+| Honda Insight EX | 2018 | $9,200 | 49 | 55,000 mi |
+
+## Recommendations
+
+- **Best value**: 2019 Prius LE — lowest price/mile ratio, clean title
+- **Best mileage**: Hyundai Ioniq at 55 mpg city/highway combined
+
+## Sources
+
+- https://www.cargurus.com/Cars/new/nl-Hybrid-d2335
+- https://www.autotrader.com/cars-for-sale/hybrid
+
+## Next Steps
+
+- Schedule test drives for the Prius and Ioniq listings
+- Verify CarFax reports before committing
+```
+
+## When to Create an Artifact
+
+Create an artifact when the output is:
+
+- A **guide, report, or summary** the user will want to reference later
+- A **comparison table** across multiple options or products
+- **Actionable recommendations** with supporting evidence
+- Something **printable or shareable** with others
+
+## When NOT to Create an Artifact
+
+Skip artifact creation for:
+
+- **Simple answers** — a one-sentence reply doesn't need a file
+- **Intermediate research steps** — notes you take while browsing, not the final output
+- **Status updates** — progress messages mid-task