---
name: hermes-creative-telegram-review
description: Telegram-first review workflow for Hermes Creative assets, briefs, draft outputs, and automation approvals.
version: 0.1.0
author: Hermes Agent
tags: [hermes-creative, telegram, review, approval, media-vault, automation]
---

# Hermes Creative Telegram Review

Use this skill when Alex asks to review, approve, reject, or understand Hermes Creative items from Telegram.

## Purpose

Telegram should be a first-class review cockpit for Hermes Creative. The agent should show the item, explain exactly what approval will do, and accept a simple approve/reject/delete decision from Telegram without forcing Alex into the web UI.

## Review object types and effects

- `asset` / image asset
  - Show native Telegram media when `media_url` or `file_path` is available.
  - Approval means: mark the image/reference approved for the trusted media vault and future briefs/drafts.
  - Approval does **not** start an agent run.
  - Suggested next action after approval: offer to create a creative brief using this asset or a selected batch.

- `creative_brief`
  - Show the brief goal, channel, task type, constraints, recommended assets, avoid patterns, and timestamps.
  - Approval means: trigger a local-only draft agent run.
  - Approval does **not** publish or spend.

- `creative_output`
  - Show draft title/body, source brief id, source run id, channel, status, and timestamps.
  - Approval means: mark the generated draft usable for export/handoff.
  - Approval does **not** publish or schedule.

- `direction` / `brand_strategy`
  - Show strategy/direction summary and rationale.
  - Approval means: save as usable brand/creative context.

## Default Telegram response format

For each item, keep it compact:

```text
Review item <id> · <Type>
Created: <date/time>
Updated: <date/time>
Source: <brief/run/asset source if known>

What this is: <one sentence>
What approval does: <one sentence>
Safety: local-only / no publish / no spend, if applicable.

<Question>
Reply: approve <id>, reject <id> <reason>, delete <id>, or more <id>.
```

If media exists, send it as `MEDIA:/absolute/path` or markdown image URL before/with the text.

## Tool/API pattern

App path: `/home/avalon/apps/hermes-creative`
Base URL: `http://127.0.0.1:4030`

List pending review items:

```bash
curl -fsS http://127.0.0.1:4030/api/projects/<slug>/review
```

Decide an item:

```bash
curl -fsS -X POST http://127.0.0.1:4030/api/review/<review_id>/decision \
  -H 'Content-Type: application/json' \
  --data '{"decision":"approved","note":"Telegram approval"}'
```

Delete from review:

```bash
curl -fsS -X DELETE http://127.0.0.1:4030/api/review/<review_id> \
  -H 'Content-Type: application/json' \
  --data '{"note":"Telegram delete"}'
```

## Critical UX rules

1. Always state the item type before asking for approval.
2. Always include created/updated timestamps when available.
3. Always explain the effect of approval.
4. Never imply asset approval starts an agent run.
5. Never imply output approval publishes/schedules.
6. For images, send the image natively in Telegram, not just a link.
7. For video outputs, send native Telegram video media when available and include an edit/open link, not just text.
8. If the user approves an asset and seems to expect a run, explain that the next step is creating/approving a creative brief.
9. If a brief approval triggers a run, report the run id and generated output ids.

## Video Story export review cards

When a Video Story export is registered as a `creative_output`, treat the MP4 as reviewable content:

- Copy/own the final MP4 in the Hermes Creative media vault and use that path/URL for review previews.
- Create a pending `creative_output` review row; approval means usable for downstream handoff only.
- **Immediately send** the Telegram review card from the registration path. Do not assume a later watcher/cron will pick it up, and do not answer the user with only a manual link/file when the official approval flow is expected.
- Telegram card should include native video preview plus Approve / Reject / More buttons.
- Include an **Edit in Video Story** URL button. Prefer path-style project links (`https://video-story.apps.poofc.com/project/<project_id>`) over query-only links; verify the app actually opens the project, not just the homepage.
- Include Video Story-specific callback buttons when the gateway supports them: `vsedit:start:<review_id>` for Telegram edit mode and `vsedit:review:<review_id>` for overlay review video assembly.
- After changing any inline-button URL, send a fresh Telegram card — existing Telegram inline buttons keep their original URL.
- See `references/video-story-output-review-deeplinks.md`, `references/video-story-output-direct-telegram-send.md`, and `references/video-story-direct-review-card-routing.md` for session-derived deep-link/direct-send/routing checklists.

10. If a brief approval triggers a run, report the run id and generated output ids.

## Routing and direct-send pitfalls

- If Alex expects a review card “here in Telegram,” treat the current chat/topic as part of the delivery requirement. A successful Telegram API response to Alex's DM or a different topic is not success.
- App-originated review sends should prefer an explicit Hermes Creative delivery target (`HERMES_CREATIVE_TELEGRAM_CHAT_ID` plus optional `HERMES_CREATIVE_TELEGRAM_THREAD_ID`) or request/origin context before falling back to `TELEGRAM_HOME_CHANNEL`.
- When debugging a missing card, check both halves separately: (1) review row creation/status, and (2) actual Telegram destination/message id. Do not describe existing gateway callbacks as “missing integration”; the more common failure is missing registration trigger or wrong destination.
- For a manual test of the approve/reject buttons, choose an existing `pending` review item, send it to the active topic, then let Alex click the inline buttons. Do not pre-approve or reject it via API unless the user specifically asks for that.

## Telegram button contract

Hermes Creative review callbacks in the Telegram gateway use compact callback data:

- `hc:approve:<review_id>` — approve review item.
- `hc:reject:<review_id>` — reject review item.
- `hc:more:<review_id>` — fetch/show expanded detail.

URL-only actions such as **Edit in Video Story** should be regular Telegram URL buttons, not callback buttons. If adding new callback verbs such as social/ads handoff, update the gateway callback allowlist and handler before emitting them.

## Future app integration target

A complete Telegram implementation should add a server-side endpoint that returns Telegram-ready review payloads, including:

- review id
- item type label
- created/updated timestamps
- title/body
- approval effect copy
- media file path or URL
- source ids (`source_brief_id`, `run_id`, `asset_id`)
- suggested next actions

Then a Telegram gateway/bot layer can render inline Approve / Reject / More buttons that call the review decision endpoint.

## Video Story export review pattern

When a Video Story export becomes a Hermes Creative `creative_output`, make the Creative review item own the review lifecycle:

1. Register/copy the final MP4 into the Creative media vault, rather than only posting the transient Video Story upload path.
2. Create a pending `creative_output` review row with `preview_kind: video` / video media metadata.
3. Telegram review card should include native video preview, approve/reject/more callbacks, and an **Edit in Video Story** URL action.
4. Approval should mean “usable for downstream handoff” only; it must not publish, schedule, or spend.
5. Social/Ads handoff buttons should be approval-gated unless the user explicitly asks to bypass review. After approval, prefer a follow-up card/action row such as **Create Social draft** / **Prepare Ads draft** rather than publishing or spending directly.
6. The Video Story registration endpoint itself should push the Telegram review card as soon as it creates the review item; this is not a watcher-only concern.
7. Before adding the editor URL to Telegram, verify the target app actually honors the project deep link. A URL like `https://video-story.apps.poofc.com/?project=<uuid>` is only useful if the React app reads `URLSearchParams`, fetches `/api/projects/:id`, and opens the project after PIN/auth; otherwise it just lands on the homepage.

Pitfall: Telegram gateway restarts only load callback-handler code; they do not fix target-app deep links. If a URL button opens the app homepage, debug the target PWA/router/deep-link handling, not the Telegram button rendering first.