---
name: artifact-presenter
description: Present any single local file the user needs to review, including documents, source, archives, PDFs, images, and videos, through mcat in a reusable Herdr pane. Also use for structured long-form reports, plans, ADRs, reviews, and summaries unless the user requests inline chat.
---

# Artifact presenter

Present reviewable files and substantial generated content in a reusable terminal document pane instead of duplicating the complete artifact in chat.

## Choose the artifact

Use this workflow in either case:

- The user needs to review one local file, regardless of its length or format.
- The expected deliverable is a structured report, plan, ADR, review, or summary with several substantive sections or roughly 1,000 words.

Treat an explicit destination and format as authoritative. For generated content without a requested destination:

- Use `/tmp/pi-present/<descriptive-slug>.<extension>`.
- Default structured prose to Markdown when no other format is implied.
- Create `/tmp/pi-present/` when needed.
- Add a timestamp only when replacing an earlier artifact would lose useful information.

Keep ordinary explanations, code diffs, logs, multi-file comparisons, and user-requested inline responses in chat. Present a file only when it is a user-facing review artifact, not merely because the agent read it during investigation.

Completion criterion: select exactly one existing or generated artifact path before presentation.

## Prepare generated content

Write the complete deliverable to the selected path. Keep it self-contained: the reader must not need omitted chat text to understand it.

Preserve repository documentation conventions. Creating a presentation artifact under `/tmp` does not authorize editing repository files when the request is otherwise read-only.

When presenting an existing file, pass the original file directly to mcat. Do not create a converted copy merely for display.

Completion criterion: the selected file exists and contains the complete review artifact.

## Present with mcat

Run the helper using its absolute path resolved from this skill directory:

```bash
python3 <skill-directory>/scripts/present.py <artifact-path>
```

The helper reuses the pane labeled `artifact presenter` in the current Herdr workspace. It serializes pane discovery, creation, and replacement per workspace, with an additional per-pane lock during viewer handoff. When that pane is already displaying an artifact, it closes the active `mcat` viewer and waits for the pane shell before launching the replacement through a shell-neutral helper command with encoded path arguments. It confirms the helper started the viewer rather than trusting terminal input delivery alone. It leaves unrelated foreground programs untouched and creates a new viewer pane instead. When no reusable pane exists, it creates a right split without taking focus. It launches `mcat <artifact-path>` so mcat can infer and display documents, source, archives, PDFs, images, and videos. It falls back to artifact-only delivery when Herdr or mcat is unavailable.

Completion criterion: capture whether the helper opened, reused, or skipped the viewer pane.

## Convert only when requested

Use mcat's conversion pipeline when the user requests a derivative artifact:

```bash
mcat <input> --output md > <output.md>
mcat <input> --output html > <output.html>
mcat <input> --output image > <output.png>
```

Use an explicit output path and preserve the source file. Present the resulting single file through the helper when the user needs to review it.

## Respond concisely

Return:

- a one- to three-sentence result summary;
- the artifact path;
- whether the reusable mcat pane was opened or reused, or why presentation fell back to the file only.

Do not repeat the complete artifact in chat. Honor a later request to paste any section inline.