# 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