---
name: artifact-presenter
description: Present local artifacts for review: use Browser Harness for interactive web artifacts, Orca for editor-friendly text in Orca-managed sessions, and mcat for other non-web files.
---

# Artifact presenter

Present reviewable files and substantial generated content through the appropriate viewer 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.

Choose the presentation path:

- **Interactive web artifacts, especially `.html`:** use the Browser Harness/Browser Use-backed workflow.
- **Non-web artifacts:** run this skill's presenter helper. It opens editor-friendly UTF-8 text directly in Orca when the harness is running in an Orca-managed terminal; otherwise it uses mcat in the reusable Herdr pane. Binary and media files stay on the mcat path.

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 non-web 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 interactive web artifacts

Load and follow the [`browser-harness`](../browser-harness/SKILL.md) skill. Open the local artifact URL in a real browser through the Browser Harness/Browser Use-backed workflow, then verify the browser target reports the artifact URL and page title. When normal Chrome attachment is unavailable, use browser-harness's documented local HTML fallback.

Completion criterion: the active browser target reports the local artifact URL and page title.

## Present non-web artifacts

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

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

The helper detects an Orca-managed harness from Orca's terminal environment markers (`TERM_PROGRAM=Orca` or scoped `ORCA_*` workspace, worktree, pane, or terminal IDs). For editor-friendly UTF-8 text, it resolves the session's version-appropriate CLI and runs `orca file open <artifact-path> --json`. Orca only opens paths inside its selected worktree, so a rejected path falls through to the normal non-web fallback.

The fallback 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 neither Orca nor the Herdr/mcat path can present the file.

Completion criterion: capture whether Orca opened the file, the helper opened or reused an mcat pane, or presentation fell back to the artifact path only.

## 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 matching presentation path above when the user needs to review it.

## Respond concisely

Return:

- a one- to three-sentence result summary;
- the artifact path;
- for interactive web artifacts, that Browser Harness presented the artifact and verified its URL/title;
- for other artifacts, whether Orca opened the file, 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.