---
name: hermes-creative
description: Operate Hermes Creative — Alex's brand brain, media vault, creative direction, image ideation, campaign strategy, and Telegram-first handoff layer for Hermes Social and Hermes Ads.
version: 0.1.1
author: Hermes Agent
license: MIT
metadata:
  hermes:
    tags: [hermes-creative, brand, creative-direction, media-vault, telegram, social-strategy, paid-ads, image-generation]
    related_skills: [social-console, paid-ads-agent-platforms, vps-app-deployment]
---

# Hermes Creative Operator

Use for brand, vault, briefs, campaigns, and social/ads handoff. Local-business video pitches: `templates/local-business-video-outreach.md`.

## Creative intelligence and performance memory

Use a project-scoped evidence → pattern → approved-output variant → raw snapshot → server-derived insight chain. Archive instead of deleting, expose only active learning through the Creative Index, label small samples inconclusive, and preserve lineage through Social/Ads draft-only handoffs without granting publish, activation, or spend authority. Keep Create / Queue compact. See `references/creative-intelligence-performance-memory.md` for schema/API boundaries, metrics, lineage, workflow, and regressions.

## Visual-reference landing pages

When translating a reference landing page for a Hermes Creative brand, match the reference's *systems* before inventing: typography scale/proportions, scroll rhythm, section background changes, image treatment, spacing, grid, and subtle

For landing pages with generated or transparent line-art image systems, also consult `references/landing-page-image-direction-qa.md`. It captures the Astral Hermes pattern: separate color-theme and image-direction selectors, use CSS masks for recolorable gods/logos, lower opacity for heavier block/marginalia styles, and QA generated assets for fake checkerboards or solid background rectangles before shipping.

For brand/app landing previews, separate **color themes** from **image style directions** so Alex can compare visual systems cleanly. Reuse parallel vault asset families where available (e.g. minimal line, block ink, marginalia) before generating new art; run heavier block/dark-line versions through the same selector pipeline but with lower opacity/blending so they integrate rather than dominate. Prefer transparent SVG/PNG logo marks over JPGs, and render monochrome gods/logos as CSS masks for theme recoloring. If GPT-generated feature art is used, save it as a selectable direction rather than replacing the baseline set. See `references/astral-hermes-landing-visual-directions.md` for the concrete Astral Hermes/North Star pattern. background fields.

Practical loop for reference-page adaptation:

1. Open the reference in the browser and capture/inspect screenshots at the hero, mid-scroll, feature grid, and footer before making final visual claims.
2. Build the preview separately from production (for example `/landing-preview`) until Alex approves; do not replace the real homepage early.
3. Compare proportions, not just motifs: title scale, card title scale, image-to-heading gaps, grid density, button sizing, and section height.
4. When Alex says a title or section “feels too big,” reduce both typography and surrounding image/gap scale; otherwise the section can still read oversized.
5. For transparent brand art that needs color variants, prefer CSS masks or alpha-based recoloring so the non-transparent drawing pixels can be driven by theme variables instead of baking fixed dark/blue PNGs.
6. Keep theme palettes semantically separated. If there is a named “Blue Ink” / reference-blue mode, do not let that blue leak into default dark mode; dark should use dark tonal fields plus the brand’s thin contrast colors (often gold/cream/white).

Continue matching subtle motion/background motifs. For sites like Hermes Desktop, specifically inspect mid-scroll states and feature sections, not just the hero.

If the source brand has transparent PNG line-art assets and Alex wants recolorable illustration treatments, prefer CSS/SVG masking over plain `<img>` usage: set `mask` / `-webkit-mask` from the transparent asset and drive the visible ink with `background: var(--glyph)` or section-level tokens. This lets the same deity/etching asset recolor across dark, parchment, blue-ink, gold, etc. without regenerating files. Use the art style Alex requested exactly (e.g. hand-drawn minimal vs block-print vs archaic marginalia) and verify visually that the selected files match that style.

For North Star / Astral Hermes landing pages, look for the actual North Star logo mark in the vault before substituting generic wordmarks or generated marks. Current known pattern: `projects/north-star-3/assets/logos/*zodiac-wheel*`.

Reference: `references/astral-hermes-landing-reference-translation.md` captures a concrete Hermes Desktop → Astral Hermes translation pattern, including CSS mask recoloring for transparent deity PNGs and dark/parchment/blue-ink theme modes.

When translating an external reference site for a Hermes Creative brand, extract its layout, type, contrast, imagery, and CTA system first; then read the project context and use matching approved Vault assets. Treat this as brand translation, not a generic clone. If Alex asks for a preview, publish only a temporary review route and state that production was not replaced.

## Telegram Social/Ads handoff reliability

Creative Telegram review cards are a handoff control surface, not just review notifications. When fixing or testing Social/Ads handoff buttons, route actions through Hermes Creative backend handoff endpoints so Creative remains source of truth for `handoff_targets`, then verify downstream Hermes Social/Ads draft rows and send visible in-topic confirmations with draft IDs and links. Handoff buttons should expose IG Reel, IG Post, IG Story, Facebook Post, and Ads options, and must create local drafts only — no publish/schedule/Meta write/ad activation/spend. See `references/telegram-social-ads-handoff-callbacks-2026-06-01.md`.

## Hermes Creative UI copy preference

For Creative → Video Story bridge actions, keep labels compact and visual. The existing/open draft action should read `👁️ Video Story` (with an accessibility label like “Open Video Story draft”) rather than the longer visible copy `Open Video Story draft`.

Hermes Creative is the **upstream brand intelligence and creative studio** for Alex's Hermes ecosystem:

Video Story handoff rule: when turning Creative briefs into Video Story drafts, include a `video_story_workflow` recommendation rather than assuming Video Story should always use one hard-coded execution path. Default to `seedance_cinematic` for production social creative drafts, but preserve explicit treatments such as `seedance_storyboard_refs`, `seedance_storyboard_grid`, `seedance_prompt_batch`, or `seedance_dialogue`. Video Story is responsible for normalizing the workflow id into its own model/profile/strategy fields. Draft import remains draft-only; do not auto-run YOLO/rendering from a Creative handoff without explicit approval.

```text
Telegram capture + user intent
  → Hermes Creative brand/project context
  → Brand Architect / Creative Director / Strategists
  → Hermes Media Vault
  → Hermes Social organic drafts
  → Hermes Ads paid drafts
  → performance learnings back into strategy
```

## Current deployment target

- App path: `/home/avalon/apps/hermes-creative`
- URL: `https://hermes-creative.apps.poofc.com`
- PM2: `hermes-creative`
- Port: `4030`
- DB: `/home/avalon/apps/hermes-creative/data/hermes-creative.sqlite`
- Media vault root: `/home/avalon/hermes-media-vault`
- Repo: `firemountain/hermes-creative`

## Core posture

- **Hermes Creative is skills-first.** Hermes skills are the product/creative workforce; the web UI is a simple toolkit, cockpit, capture surface, and review utility over those skills.
- The app should feel like four clear surfaces: **Define Brand**, **Vault**, **Review**, and **Create / Queue**. Avoid letting implementation nouns like Architect, raw Brand Kit fields, generic Strategy, or vague “Automation” copy obscure this model.
- Telegram is fast capture, command, voice/text brand editing, and approval.
- Web UI is the compact studio surface: guided brand definition, vault browser, review board, and automation cockpit.
- Skills are the specialist employees/procedures.
- Media vault is durable creative memory.
- Hermes Social and Hermes Ads remain downstream execution arms, but they should query Creative for brand context, vault index, asset recommendations, and creative briefs rather than invent strategy independently.
- The Automation/Create surface should package the current creative index into **reviewable creative briefs** before downstream Social/Ads execution. In the UI, prefer the label **Create / Queue** over **Automation** unless Alex explicitly asks for automation language. Brief creation should create a `creative_brief` review item and remain draft-only until explicitly approved.
- Create / Queue cockpit UX: keep the page as status cards + focused modals, not a long inline form/history dump. Put Context pack, Agent runs, and Drafts awaiting review/export as top status cards (three columns where possible); clicking history/draft cards opens modals. Context pack details and refresh controls should live inside the Context pack modal, not as an inline expandable section. Brief creation should open a focused modal, matching other Hermes Creative create modes; the main-page action beside the **Creative briefs** heading should be a compact same-row button labeled **New Brief**, not a large full-width “Create queued brief” CTA. Avoid redundant explanatory copy on the Create / Queue landing surface. Place media reference readiness inside the context/preflight modal and label it explicitly as a live **Reference preflight** for the next brief: not a saved brief, not a master asset template, and each saved brief gets its own `brief_json.media_reference_plan`. See `references/create-queue-cockpit-modal-preflight-2026-05-31.md`.
- Create / Queue should be an execution-prep queue, not a legacy strategy-planning page: focus on creative briefs, agent/video-story runs, and final drafts awaiting review/export/handoff. Do not show old **Campaign planning** cards, generated campaign plan history, raw media-packet/debug CTAs, or test/internal labels like “GPT Image 2 composition packet” in the normal UI. Brief details should render formatted, wrapping markdown (headings/lists/paragraphs), not raw `<pre>` markdown that breaks the layout. Brief detail production references must come from the per-brief `brief_json.media_reference_plan.slots`, not a generic Creative Index `assets.by_role` slice; if the slot plan says Jupiter/Venus, do not show unrelated Mercury/Saturn/Moon “Recommended Assets” from legacy markdown. See `references/create-queue-declutter-brief-detail-ui-2026-05-31.md` and `references/creative-brief-reference-source-of-truth-2026-05-31.md`.
- The Automation/Create surface must make the workflow traceable as a timestamped chain: creative index/context pack → creative brief → review approval → agent run → local draft outputs → output review decisions. Do not leave generated artifacts as anonymous cards; show ids plus created/updated/checked date-times wherever Alex needs to tell what happened when. For inspection UX, use the pipeline-inspector pattern: a compact topbar icon opens a vertically scrolling node diagram, and each Create / Queue brief has an **Inspect pipeline** action that opens the same diagram scoped to that brief. Nodes involving prompts, injected context, media plans, run inputs/results, or outputs must be expandable and show the actual persisted/sanitized payload when available. See `references/pipeline-inspector-trace-ui-2026-05-31.md`.
- Phase 2 Vault reliability now includes a diagnostic hygiene API and stable taxonomy/metadata contracts. Use `GET/POST /api/projects/:slug/vault/hygiene` to find unclassified assets, missing analysis, failed enrichments, missing rights notes, and missing role/kind without mutating memory. Use `src/lib/creativeTaxonomy.mjs` and `src/lib/assetMetadataContract.mjs` patterns to normalize drifted asset kinds/relationships and canonical metadata while preserving unknown legacy fields under `extra`. See `references/phase-2-vault-taxonomy-hygiene-and-video-bridge-2026-05-30.md`.
- Creative approval is NOT publishing approval and NOT spend approval.
- Phase 2 / creative brief media planning: briefs that may produce final media should include a structured `media_reference_plan`, not just a flat list of assets. Static image/ad/post briefs should prepare a GPT Image 2 packet with ordered slots (`main_image`, `layout_reference`, `style_reference`, `logo_reference`, `typography_reference`, `product_reference`), exact copy/CTA/output requirements, and avoid patterns. Video briefs should prepare a video-story bridge packet with entity slots (`character_reference`, `set_reference`, `prop_reference`) plus style/logo/script context. Missing slots should be explicit (`needs_generation_or_upload`) with instructions for Hermes to generate/select/upload a fill before final execution. Reference slots are **many-to-many usage roles**, not exclusive asset categories: the same image can be used as main image + style ref + layout ref, or character ref + style ref, etc. Do not block duplicate use across slots; warn only when one reference may over-anchor a generation. Reference slots are **many-to-many usage roles**, not exclusive categories: the same Vault asset may be assigned to multiple slots in one brief/run (for example, a poster can be both `main_image` and `layout_reference`). Do not block reuse; at most show non-blocking over-anchoring warnings. See `references/phase-2-media-reference-slot-many-to-many-2026-05-30.md`. As of 2026-05-30, Hermes Creative has `POST /api/creative-briefs/:id/create-video-story-draft`, which requires an approved video brief (unless explicitly overridden), calls video-story `/api/hermes/creative-brief-drafts`, records a `video_story_draft_handoff` run, stores the public draft URL in run result, and does not start YOLO/rendering. As of 2026-05-31, completed Video Story exports should be registered back into Creative with `POST /api/creative-briefs/:id/register-video-story-output` (body may include `video_story_project_id` and `title`): this copies the MP4 into the project vault, creates/updates a `creative_outputs` row, creates a pending `creative_output` review item with `preview_kind='video'`, exposes a Telegram payload with media + **Edit in Video Story** action, and prepares downstream handoff metadata. For reruns/comparison tests, create a fresh Video Story draft with `force_new`, register the new export as a new `creative_output`, and send a fresh Telegram card; do not mutate the old review card/output. Prefer path-style Video Story edit URLs (`/project/<uuid>`) in Telegram cards because query-only links can appear in the address bar but still land on the PWA homepage if the client/router ignores them. Approved video outputs can then create downstream local drafts only: Hermes Social via `POST /api/creative-outputs/:id/handoff/social` and Hermes Ads via `POST /api/creative-outputs/:id/handoff/ads`. Both must reject unapproved outputs unless explicitly overridden. Social handoff must record `publish_status: not_published`; Ads handoff must create a paused local draft with safety metadata (`meta_write: false`, `publish: false`, `activate: false`, `spend: blocked`). Creative must not publish/schedule Social, write to Meta, activate ads, or spend. See `references/approved-output-social-ads-draft-handoffs-2026-06-01.md`. The Phase 2 prep loop also has `GET /api/creative-briefs/:id/media-packet`, `PATCH /api/creative-briefs/:id/media-slots`, and `POST /api/creative-briefs/:id/media-slots/:slot/generation-job`; use these to export the structured GPT Image 2/video packet, fill missing slots from existing Vault assets, or queue reference-generation jobs without auto-rendering or bypassing review. The broader Phase 2 Vault memory layer now also includes `POST /api/projects/:slug/creative-index/recommend` for task-specific agent recommendations, `GET/POST /api/projects/:slug/vault/hygiene` for diagnostic Vault cleanup reports, normalized asset taxonomy in `src/lib/creativeTaxonomy.mjs`, normalized metadata contract in `src/lib/assetMetadataContract.mjs`, and font upload support for `.ttf/.otf/.woff/.woff2` as `asset_kind='font-file'` without vision enrichment. See `references/phase-2-media-reference-slot-fill-and-generation-2026-05-30.md` and `references/phase-2-vault-memory-completion-2026-05-30.md`. Do not treat video brief approval as local text-draft execution; video briefs should route to draft-only Video Story social creative workspaces.
- Hermes Creative is first a **brand imagery and creative-direction system**, not just an app/UI generator. Most visual work may become media, content, campaign imagery, identity assets, motion/graphic language, and social/ads material. UI is only one downstream expression when the project calls for it.
- When developing visuals, separate the layers explicitly: **brand identity** (logo, marks, palette, typography), **brand imagery** (campaign/content visual language, generated media, illustrations, moodboards), **content system** (post/ad formats, recurring motifs), and **product/UI expression** (screens, components, interactions). Do not collapse brand imagery into UI unless Alex asks for UI.
- Visual design should feel like the Hermes Ads / Hermes Social suite unless Alex explicitly requests a divergent concept: warm cream/light background, soft white cards, dark navy/black primary controls, muted gold accents, rounded glassy panels, and compact mobile-first spacing. Avoid dark purple prototype styling for the production Hermes Creative UI.
- Hermes Creative is now **collections-first**, not package-driven. Avoid rigid Brand → Campaign → Set → Piece hierarchy unless Alex explicitly reintroduces it. The durable model is flexible `asset_collections` + many-to-many `collection_assets`, with logos, palettes, typography references, campaign images, imported boards, and generated assets represented as assets carrying agent-readable `metadata_json` and `asset_kind`.
- Trust/review model: user-supplied manual assets, app uploads, and imported reference images are trusted ingredients by default; do not create a review card for every uploaded image. Queue review at the **collection** level (`asset_collection`) for collection intent/context, keep **generated assets** reviewable as `asset`, and keep **final drafts** reviewable as `creative_output`. See `references/collection-trust-and-create-queue-2026-05-28.md`.
- Manual uploads/imports are trusted ingredients by default, but creative direction changes over time; the Vault needs maintenance controls to demote, unlink, or archive them without losing provenance. Status semantics for asset intelligence: `approved` = strong positive signal; `active` = trusted ingredient but not necessarily high-confidence style guidance; `rejected` = avoid memory / negative prompt signal; `pending` = unresolved review/enrichment; `deleted` = archived out of active agent context while preserving files/audit trail. Archive/deleted state is an active-memory boundary, not necessarily physical destruction: archived collections and deleted assets must not leak into creative-index summaries, prompt fragments, role counts, generation reference pools, or "What Hermes sees" unless explicitly requested in an archive/debug mode. Rejected/avoid material may influence negative guidance only when intentionally retained as active avoid memory and not archived/deleted. See `references/vault-intelligence-and-asset-maintenance-2026-05-28.md` and `references/vault-archive-memory-boundary-and-cleanup-2026-05-28.md`.
- The old Visual Packages wizard was intentionally disconnected from active navigation/API. Preserve reusable UI ideas for a future skill-like guided workflow, but do not rebuild `/visual-packages` endpoints or the Visual Packages tab by default. New work should route through Vault collections and asset metadata.
- Review queue items must be openable before approval. A card summary alone is insufficient context; include rationale, palette/typography/prompt language for directions, file/source/notes for assets/packages/drafts, and an explicit approval question.
- High-level review should stay focused on final posts/drafts, creative briefs that trigger agent work, and substantive media/content Hermes creates itself. Do **not** create review/approval flows for routine uploads, routine vision metadata, proposed brand-rule suggestions, or collection-analysis noise. Asset/collection analysis should enrich context quietly unless Alex explicitly asks for a strategy/rules review pass.
- Preferred Review UX: keep the queue as a compact scrollable list, but tapping an item should open a focused non-scrollable swipe-review overlay/deck. Prominent asset/content/package preview on top, approval question visible in the black question box, optional reason/context textbox, explicit Approve/Reject/Delete actions, swipe right approve, swipe left reject, and a separate scrollable “More info” panel for details. Do not make the focused overlay itself scroll into other review items.
- For image assets, the Review queue must show actual visual previews, not just titles, notes, or file paths. Asset review cards should include a thumbnail in the collapsed row and a large preview in the expanded detail. If Alex says images are not shown in Review, debug `review_items` + `assets.media_url` before assuming the assets are missing.

## Default agent roles

### Brand Architect

Senior brand strategist. Defines:
- positioning
- audience
- emotional territory
- story
- archetype
- brand promise
- enemy / what the brand refuses to be
- high-level visual territories

Ask questions like:
- What world does this product live in?
- Who is it for?
- What does it refuse to be?
- What emotional territory should it own?

### Creative Director

Turns brand direction into visual language:
- moodboards
- creative territories
- color/type/image rules
- image prompts
- visual do/don't examples

### Media Vault Librarian

Maintains vault organization:
- references
- generated assets
- approved/rejected folders
- metadata sidecars
- brand context exports
- decision history

### Concept Orchestrator

Missing-middle creative producer between raw intent and production briefs. Use whenever Alex gives a fuzzy idea, campaign goal, refinement note, or asks Hermes Creative to come up with concepts before briefing.

Responsibilities:
- Interpret Telegram/UI voice/text/image intent as concept capture, concept generation, or refinement.
- Pull the current creative index: brand context, Vault intelligence, approved/rejected history, prompt fragments, avoid patterns, and pending review state.
- Create/refine durable `creative_concepts` before jumping to `creative_briefs`.
- Make concepts reviewable (`item_type='creative_concept'`): approving a concept makes it trusted source material but does **not** start a draft run.
- Convert approved or selected concepts into one or more creative briefs using `source_concept_id`, preserving traceability: Telegram/input → concept → brief → review → local drafts/output review.

Operational endpoints:
- `GET /api/projects/:slug/creative-concepts`
- `POST /api/projects/:slug/creative-concepts`
- `POST /api/creative-concepts/:id/briefs`
- `POST /api/hermes/ingest` with `type:'concept'`, `intent:'concept'`, or `concept` creates a concept directly from Telegram-style ingest.

Concept ≠ brief: the concept is the creative thesis; the brief is the execution packet.

For transit-timed social/video concepts, use real global transit data first, then create the concept, then derive briefs. Preserve overlay/caption/voiceover as production data for Video Story, but do not claim burned-in text overlay rendering until the render path is verified. See `references/transit-timed-planetary-gods-social-video-2026-05-31.md`.

### Content Strategist

Turns brand + business goals + assets + stats into organic/paid plans:
- content pillars
- hook banks
- campaign concepts
- social draft ideas
- ad draft ideas
- testing matrix

### Paid Ads Strategist

Creates paid concepts for Hermes Ads only as local drafts unless Alex explicitly approves platform writes.

### Organic Social Strategist

Creates organic post/campaign concepts for Hermes Social as local drafts unless Alex explicitly approves publishing/scheduling.

### Performance Analyst

Reads Ads/Social stats and produces creative learnings and next tests.

## Telegram interaction patterns

Alex may write naturally. For brand-development sessions, use a **visual-first interview** style: generate/show a small number of visual cues, let Alex approve/reject/comment, then ask **one targeted question at a time** based on that feedback. Do not send long lists of abstract brand questions unless Alex explicitly asks for a worksheet.

For proactive review delivery, prefer the lightweight Hermes cron/no-agent watcher pattern before modifying the core Hermes gateway: a script under `~/.hermes/scripts/` reads pending `review_items`, tracks sent ids under `~/.hermes/state/`, prints nothing when idle, and emits one Telegram-native card with `MEDIA:/absolute/path` plus explicit approval-effect text when a new item appears. Use finite repeat counts while iterating to avoid permanent chat noise. See `references/telegram-review-cron-card-watcher-2026-05-28.md`.

For interactive Telegram review buttons, keep state changes centralized in Hermes Creative's API, not the gateway. Button callbacks should use `hc:<approve|reject|more>:<review_id>`, call `/api/review/:id/telegram` for details or `/api/review/:id/telegram-decision` for decisions, then send the next pending review card returned in `telegram.next_items` so Telegram behaves like the continuous web review deck. See `references/telegram-inline-review-callback-next-card-2026-05-28.md`.

Do **not** send Telegram approve/reject cards for routine image analysis / `asset_metadata` review rows. Alex corrected that image notes are useful in the Vault but do not need Telegram approval noise. Telegram review delivery should use an explicit allowlist of consequential item types (`asset`, `asset_collection`, `creative_brief`, `creative_output`, `direction`, `brand_strategy`) and exclude `asset_metadata` by default. See `references/telegram-review-asset-metadata-suppression-2026-05-29.md`.

Interpret messages into one of five intents:

1. **Capture** — save text/link/image/video/voice as a project reference.
2. **Analyze** — ask Brand Architect or Creative Director to interpret references.
3. **Generate** — create directions, prompts, images, strategies, or campaigns.
4. **Review** — approve/reject/compare directions/assets/drafts.
5. **Handoff** — create local drafts in Hermes Social/Hermes Ads.

Examples:

```text
Save this to Astro Mage references and have Brand Architect analyze the vibe.
```

```text
Generate 5 brand directions for Magi from the current vault.
```

```text
Approve direction 2 as primary. Reject 4 as too SaaS.
```

```text
Turn the approved direction into a 14-day organic content plan.
```

```text
Create paid campaign drafts in Hermes Ads, local only, do not push to Meta.
```

## UI response pattern

For Telegram responses, keep it compact:

1. What was saved/created.
2. Best recommendation.
3. What needs review.
4. Direct UI link.
5. Clear next actions.

Never dump huge galleries in Telegram. Use UI links for bulk review.

## App shell / project selector UI preferences

Hermes Creative should be tool-first and skills-first, not hero-first. Do **not** add or preserve a large repeated hero/marketing section across tabs. Alex explicitly asked to remove the old persistent “Brand Architect MVP” / “Brand Architect + Creative Director” style hero because it wastes vertical space and repeats on every tab.

Preferred shell pattern:

1. Put the Hermes Creative mark/logo and active project selector in a compact sticky top bar.
2. Keep the project selector globally available while moving through tabs.
3. Include “Create new project…” inside the selector/dropdown, not as a large Home-tab setup form.
4. Creating a project opens a modal/overlay. Cancel returns to the previous project/selection; successful create switches into the new project immediately.
5. Do **not** keep a generic Home tab. The app should open directly into the first real working surface. Current product language should be **Define Brand**, **Vault**, **Review**, and **Create / Queue** rather than the older raw Architect/Strategy/Automation framing.
6. Define Brand should not be a raw textarea grid by default. It should be a Typeform-style, one-question-at-a-time Hermes interview with text/voice input, a formatted strategy preview, and an advanced field editor only behind disclosure.
7. Add an inspection surface such as **What Hermes sees** for the agent-facing brand/vault index so Alex can verify the context skills are actually using.
- Preserve mobile safe-area padding and verify on an iPhone-sized viewport that the header remains compact, the selector/modal are usable, and no Home tab or workspace-summary copy remains.
- For mobile modals/drawers, treat overlays as viewport-rooted surfaces, not descendants of app-shell spacing. Use `visualViewport`-driven `--app-viewport-height` **and** `--app-viewport-top` CSS variables, force overlays to `position:fixed; top:var(--app-viewport-top); height:var(--app-viewport-height)`, lock `body.modal-open`/`body.review-modal-open` with a fixed-position scroll-preserving body lock (not only `overflow:hidden`), and put scrolling on one internal panel with `-webkit-overflow-scrolling:touch`. This prevents the recurring top gap and address-bar minimize scroll glitches. See `references/mobile-modal-viewport-gap-fix-2026-05-19.md`.
- PWA safe-area fixes must protect **internal overlay controls**, not just the overlay container or app chrome. Asset drawer, generation drawer, collection overlay, and review deck headers/action bars should use shared `env(safe-area-inset-top)` padding so close buttons do not sit under the iOS status bar. Bottom tabs should dock to the physical bottom with `env(safe-area-inset-bottom)`. See `references/mobile-safe-area-overlays-and-collection-delete-2026-05-28.md`.

See `references/compact-project-topbar-2026-05-17.md` for the implementation notes and verification recipe from the first app-shell overhaul. See `references/no-home-tab-app-shell-2026-05-17.md` for the follow-up removal pattern and verification notes.

## Vault UI design rules

The Vault section should feel compact and professional, not “jumbo.” It is now the active visual operating console and the agent-readable creative memory store. When adding reference/import/asset-management UI:

- Treat collections as the main organizing unit, not packages. Show collections as compact visual cards with asset thumbnails/previews. Tapping a collection should open a full-screen collection overlay with Close, Upload, collection metadata, and that collection's visual asset grid.
- Treat vault assets as structured creative inputs for Hermes skills, not just media files. Support clear asset roles such as style reference, layout reference, logo, logo reference, font file, font reference image, direct-use image, generated image, edited image, campaign/social/ad reference; and relationship roles such as primary-reference, secondary-reference, direct-use, avoid, inspiration, source, derivative.
- Maintain an agent-facing project creative index endpoint/view that **separates brand context from vault intelligence**. Brand context covers audience/offer/positioning/voice/visual direction; vault intelligence comes from collections and assets: approved creative inputs, active/trusted ingredients, style/layout/logo/font/direct-use role counts, prompt fragments, rejected/avoid patterns, collection purposes, asset relationship/status mix, assets needing analysis, and pending reviews. This is the contract Hermes Social, Hermes Ads, and generation skills should consume. Do not collapse this back into a single compressed “Hermes sees” paragraph. If dense agent-context text is shown in Vault, render it as human-legible labeled sections with line breaks/helper copy, not prompt sludge; explain chips like style reps / avoid patterns / pending reviews as diagnostics. **Refresh agent index** means recompute/refetch what agents will see from the current brand kit, collections, assets, metadata/statuses/relationships, and review state; it must not publish, create media, or make approval decisions. See `references/vault-agent-context-preview-2026-05-28.md`, `references/vault-intelligence-and-asset-maintenance-2026-05-28.md`, and `references/vault-agent-index-explainability-2026-05-28.md`.
- Keep collection-level context dynamic. Do not hard-code a `representative_assets` array into the agent-facing collection contract unless Alex explicitly marks specific assets as canonical representatives; prefer purpose, collection type, asset count, status mix, and relationship mix so the collection remains flexible.
- Provide a compact Vault asset-list maintenance view for ongoing curation: filter by collection/status, show small thumbnails plus asset kind/status/relationships, and support row actions to open, mark avoid (`rejected`), restore, remove from collection, and archive (`deleted`) while preserving file/provenance. The List view must render as a normal full-width admin table, not a narrow grid/sidebar card; keep rows short with fixed columns, smaller thumbnails, ellipsized titles/notes, nowrap action buttons, and horizontal scroll on small screens rather than wrapping buttons into tall stacks. The List view should feel like a normal admin table, not a narrow card or stacked mobile list: span the full Vault width, use fixed column sizing, truncate long asset text, keep thumbnails small, prevent action buttons from wrapping into tall stacks, and use horizontal scrolling on small screens rather than crushing columns. See `references/vault-list-and-deep-cleanup-2026-05-28.md`. The List view must behave like a normal full-width admin table, not a narrow card or visual grid: span the full Vault content width, use deliberate column sizing, keep rows short, truncate long text, and prevent action buttons from wrapping into tall vertical stacks. On mobile, prefer horizontal table scroll with a sane min-width over squeezing columns until every button wraps. See `references/vault-list-normal-table-layout-2026-05-28.md`.
- Keep the top-level Vault command area extremely compact: only New collection and Pinterest. These are disclosure actions: their forms/options should be hidden by default and only appear after tapping the matching button; tapping again may collapse. Do not leave New collection inputs open on initial Vault load. When the New Collection composer opens, the overlay/card should be visually opaque: use a dim/blur backdrop if desired, but the foreground card needs a solid warm cream surface so Vault logos/assets do not show through the modal.
- Do not expose Upload or Reference note at the top level; upload belongs inside the open collection overlay. Inside a collection, the default upload/generation UI should show only primary actions such as Upload and Generate. Detailed fields like upload notes, asset kind/logo classification, title overrides, and metadata should appear only after the user has chosen an upload and can see its preview.
- Any upload/generation/ingest action that may take noticeable time must surface a visible processing state in the UI (e.g. uploading spinner/banner, completion/failure status). Do not silently block after file selection.
- For AI generation/editing, use persisted `generation_jobs` as the source of truth for UI feedback. A local busy banner is not enough: the Vault should poll/list jobs from SQLite, show a compact job tray with status/errors/reference counts, and recover after page refresh. Do not globally disable upload/generate/edit while one job runs; users must be able to queue parallel work and see all active jobs. The job tray should be collapsed by default and visually subordinate to the asset grid; never let an expanded log panel dominate the collection header on mobile.
- Generation should open a focused overlay/session rather than stuffing a large inline form into the collection grid. Put the dynamic placeholder/preview above the prompt controls, show in-progress feedback on that preview, use `object-fit: contain` for arbitrary output dimensions, collapse completed job logs by default, and derive “running” spinners only from non-terminal persisted jobs. A fresh **Generate** click means a fresh session: do not fall back to the last completed job/result image when no active job is selected; show a neutral placeholder until the user enters a prompt or selects a job. Prompt textareas must be disclosed only after the user taps an action such as “Enter prompt” / “Edit with AI”, not shown everywhere by default. After a generation completes, “edit image” should stay in the same session and use the generated asset as the edit source/reference. See `references/parallel-generation-edit-analysis-ux-2026-05-18.md` and `references/minimal-disclosed-ai-generation-asset-ui-2026-05-19.md`.
- For asset edit/variation flows, default to a reference-capable edit model and include the source asset as the first reference. If an edit “does not use the reference image,” inspect `/api/assets/:id/edit`, `reference_asset_ids_json`, model selection, and `applyReferenceUrlsToFalBody()` before changing prompts.
- Asset **Edit with AI** must be a true image-edit session, not a disguised text-to-image generation session. Opening edit from an asset should show the source image in the overlay preview, present a single edit prompt plus edit-model picker, default to GPT Image 2/Codex where available, and keep the UI in edit mode while rendering/results arrive. Do not clear into “Preview will appear here,” “Describe the image,” Flux Pro Ultra, or “Queue another” after the user has already submitted an edit prompt. Edit jobs must remain visible in the open collection even when only `source_asset_id` is linked and no result asset is attached yet; after submit, keep a waiting/rendering state and show result actions (`Open result`, `Replace current`, `Save as new`, `Edit again`) when complete. See `references/asset-edit-overlay-and-destructive-action-ux-2026-05-29.md` and `references/asset-info-edit-job-debugging-2026-05-29.md`.
- Keep destructive asset actions visually demoted. **Delete from collection** / **Remove from collection** belongs behind a compact More/menu affordance in the asset drawer, with confirmation and provenance-preserving copy; it should not be a large primary-width red button beside common actions. Analysis actions should show visible busy feedback (`Analyzing…`) and open/fill Info when enrichment completes or surface setup/error state cleanly. See `references/asset-edit-overlay-and-destructive-action-ux-2026-05-29.md`.
- Keep add-reference forms in compact rows/columns with small labels, restrained padding, and shorter textarea heights.
- Prioritize the visual asset grid over form chrome; imported image assets should show thumbnails immediately.
- For large/high-asset collections, compact mode should remove text/actions chrome but **must not make imagery unreadable**. Do not force tiny 3-column mobile thumbnails for tall brand/reference assets; prefer 2 readable columns on phones, fixed square tile regions, `object-fit: contain`, and internal overlay scrolling. See `references/vault-large-collection-compact-grid-2026-05-17.md`.
- Collection overlay cards should be **clean visual tiles**, not review cards: show the image, not label clutter. Hide filename, path, notes, source URL, approve/reject actions, and confusing status/AI badge pairs such as `pending` + `Ready` in the collection grid. Approval/rejection belongs in the Review queue/deck, and status/details belong behind the asset drawer’s disclosed info panels. For agent-facing collection context, avoid fixed `representative_assets` lists; describe collection purpose and dynamic asset mix instead so collections do not become artificially pinned to a few assets. See `references/collection-overlay-and-fal-queue-2026-05-18.md`, `references/minimal-disclosed-ai-generation-asset-ui-2026-05-19.md`, and `references/vault-agent-context-preview-2026-05-28.md`.
- Collection asset removal should be scoped and provenance-preserving. The UI affordance should say **Delete from collection** / **Remove from collection**, confirm first, call `DELETE /api/collections/:id/assets/:assetId`, refresh, and explain that the asset file/audit trail remains in the vault. Do not delete the underlying asset row/media file just because Alex wants an image out of a collection. If Alex asks to "clean up everything connected", "get rid of this brand", or otherwise requests deep cleanup, treat that as an explicit admin/destructive workflow: back up SQLite first, distinguish shared vs exclusive assets, move/remove exclusive vault files, delete related KB/enrichment/version/review/generation rows, and verify no orphans. See `references/vault-archive-memory-boundary-and-cleanup-2026-05-28.md`.
- Use `media_url` from the assets API for thumbnails; do not make the frontend reconstruct filesystem paths.
- Asset detail/edit should expose `asset_kind`, status, notes, and JSON metadata so Hermes can later query assets like “approved dark-mode horizontal logo,” but **do not push raw metadata/JSON into the primary creative UI**. Default asset views should be clean and action-disclosed: image-first, minimal close/action controls, and no already-open edit forms, prompt boxes, raw metadata, or redundant labels unless the user explicitly taps **Edit details**, **Edit with AI**, **Analyze**, **Info**, or **Technical**. Show clean human-readable image notes, brand role, fit/mismatch notes, tags, and simple status chips only inside disclosed info surfaces; put raw JSON, paths, IDs, provider/model data, and errors behind a collapsed read-only `Technical` / `More info` disclosure.
- Prefer user-facing labels like “Analyze image”, “Image notes”, “Ready”, “Applied”, and “Needs setup” over developer-centric labels like “AI metadata”, “AI needs review”, or “technical fallback”. If real vision analysis is blocked, show a clear setup state rather than pretending fallback metadata is successful enrichment. Do not render empty structured Info sections or fake progress like `Needs setup 0%`; show the provider/setup error cleanly, keep raw technical detail behind Technical/More info, and only show `Apply latest notes` when real ready/completed notes exist. See `references/asset-info-edit-job-debugging-2026-05-29.md`.
- Prefer two-pane or stacked layouts where capture controls are secondary and the asset board is primary.
- Preserve the Hermes Creative visual tone: eggshell/graphite surfaces, muted gold accents, minimal linework, and compact mobile-first spacing.
- When fixing screenshot-reported Vault UI bugs, identify the exact visible failure first (for example overlap vs crop vs scroll clipping). Do not ship repeated approximate CSS fixes from inspection alone; Alex expects the screenshot symptom to be directly addressed.
- For dense/compact image grids on iPhone Safari, do not rely only on `aspect-ratio` on button-based thumbnails. Give the asset card a real height, force the preview button/image to `height:100%`, use `object-fit:contain`, and keep `overflow:hidden` so images cannot overlap into neighboring rows. Prefer 2 readable columns on mobile over 3 unreadable columns.

See `references/collections-first-vault-overhaul-2026-05-17.md` for the schema migration, API surface, UI pattern, smoke test, and pitfalls from the package-to-collections pivot. See `references/vault-disclosure-upload-flow-2026-05-17.md` for the follow-up correction: top-level New collection/Pinterest forms hidden by default, upload metadata shown only after file preview, and visible processing states. See `references/vault-compact-grid-overlap-2026-05-17.md` for the iPhone Safari compact-grid overlap root cause and durable CSS pattern.

## Reversible creative phase work

When Alex asks to move into a next phase after visual exploration, create a versioned/reversible work package before pushing further:

- Use a phase slug under `brand/phases/<phase-slug>/`.
- Write the main phase output under `brand/`.
- Include `manifest.json` with created files, approved seed assets, model/provider defaults, and timestamp.
- Include `rollback/rollback.sh` that removes/reverts only the files created by that phase.
- State what the rollback preserves (e.g. previously approved assets) vs. what it deletes/reverts.

This is a first-class workflow preference: Alex wants a clean, thorough retry path if he dislikes a direction.

## Review queue / swipe review implementation preference

For Hermes Creative UI work, the review queue should support focused review rather than forcing decisions inside a long page:

1. Keep the Review tab as a compact, scrollable list of pending items.
2. Tap an item to open a focused Tinder-style overlay/deck.
3. Lock background/body scrolling while the overlay is open.
4. Keep the asset/content preview prominent and the approval question visible without scrolling.
5. Provide optional reason/context text before approve/reject/delete.
6. Support swipe-right approve and swipe-left reject, plus explicit buttons.
7. Decisions must automatically advance to the next pending review item; approve/reject/delete should **not** close the overlay. Only the Close button exits back to the list.
8. Put detailed metadata in a separate scrollable More Info panel; the focused overlay itself should remain non-scrollable.
9. Delete from review should preserve audit/provenance and mark linked entities consistently.
10. Tune swipe feel for speed/smoothness: no transition while actively dragging, short ease-out after release, `will-change: transform`, and a short busy state to avoid double actions.

See `references/reversible-phases-and-swipe-review-2026-05.md` for the original implementation notes and `references/review-deck-and-media-url-pitfalls-2026-05.md` for deck-advance/media-preview debugging details.

See `references/reversible-phases-and-swipe-review-2026-05.md` for the session-specific implementation notes and pitfalls.

### Retired Visual Package wizard notes

The Visual Package wizard guidance below is historical. As of the collections-first pivot, do **not** expose a Visual Packages tab or rebuild the `/visual-packages` API by default. If Alex asks for the wizard again, reinterpret it as a future guided **skill/workflow** that creates/edits `asset_collections`, `collection_assets`, and asset metadata, not a revival of the old rigid package hierarchy.

When building or fixing a future collection-backed guided wizard:

1. A new Brand Visual Identity wizard should immediately `POST /api/projects/:slug/visual-packages` with `status='draft'`; do not wait until the last step to create the DB row, because Hermes chat, uploads, saved step state, and generation batches need a package id.
2. Final confirmation should complete the draft (typically set `status='in_review'` plus `structured_payload.export.confirmed=true`) rather than auto-approving or setting it primary. Only explicit “Set primary” should call `/set-primary`.
3. Hermes chat inside the wizard should be able to trigger generation when the prompt asks for “generate”, “variation(s)”, “batch”, “options”, or “selectable”. Show generated outputs as selectable batches attached to the active step, and persist selected asset ids in that step’s `structured_payload`.
4. Mobile wizard bottom actions should be a full-width bottom-docked bar, not an indented/floating pill. Use `position: fixed; left: 0; right: 0; width: 100vw; bottom: 0;` plus `env(safe-area-inset-bottom/left/right)` padding and enough card bottom padding so content is not hidden.
5. Mobile landing cards must aggressively prevent horizontal overflow: wrap long vault paths/badges/buttons, set `min-width:0` on cards/rows/grids, `overflow-x:hidden` on the app/body, and avoid single-line buttons that exceed the viewport.
6. **Do not call the mobile wizard fixed just because the footer is fixed.** Verify the active step's section controls and Hermes chat are actually visible/reachable on iPhone. A common regression is global mobile `.card { overflow:hidden }` overriding `.wizard-card { overflow:auto }`, clipping everything below the header/Save button. Force `.wizard-card { overflow-y:auto !important; -webkit-overflow-scrolling:touch !important; }` at mobile breakpoints when needed, and place `Save step` after the section-specific controls so the visible UI is not just a save button.
7. **For mobile, the Brand Visual Identity wizard should feel like a bottom-sheet app screen, not a nested desktop modal.** Remove redundant floating info/description panels inside the wizard, put the package name in the top bar alongside Close, make step selectors a horizontal scrolling pill list, anchor the wizard shell to the bottom of the viewport, and aggressively reduce nested card gutters/padding. The top-level card can keep a small edge margin, but the wizard content itself should not create multiple inset panels that waste phone width.
8. **Avoid `svh` + sticky/grid rows for the mobile wizard sheet.** This caused a huge top gap and vertically clipped step pills on iPhone even after the header was moved inside the sheet. Prefer a true bottom-sheet surface: fixed full-screen overlay, flex `align-items:flex-end`, shell height `calc(100dvh - max(8px, env(safe-area-inset-top)))`, card as a flex column with normal non-sticky topbar/steps, step row `min-height` around 54px, and step pills `height/min-height` around 38px. Verify geometry on a live mobile viewport, not just by inspecting CSS.

See `references/visual-package-wizard-draft-batches-mobile-2026-05.md` for the session-specific implementation diff and verification notes. See `references/visual-package-wizard-mobile-clipping-2026-05-17.md` for the clipped-controls follow-up. See `references/visual-package-wizard-bottom-sheet-mobile-2026-05-17.md` for Alex's bottom-sheet/no-gutters correction. See `references/visual-package-wizard-mobile-dvh-bottom-sheet-2026-05-17.md` for the final iPhone gap/clipped-step root cause and Playwright verification recipe.

## API quick reference

Base local URL: `http://127.0.0.1:4030`

Important endpoints:

```bash
GET  /api/health
GET  /api/projects
POST /api/projects
GET  /api/projects/:slug
GET  /api/projects/:slug/references
POST /api/projects/:slug/references
POST /api/projects/:slug/pinterest/import
GET  /api/projects/:slug/brand-kit
PATCH /api/projects/:slug/brand-kit
GET   /api/projects/:slug/brand-strategy/session/current
POST  /api/projects/:slug/brand-strategy/session
POST  /api/brand-strategy-sessions/:id/answer
POST  /api/brand-strategy-sessions/:id/generate
PATCH /api/projects/:slug/brand-strategy
GET   /api/projects/:slug/brand-context-pack
GET   /api/projects/:slug/creative-index
GET   /api/projects/:slug/vault/hygiene
POST  /api/projects/:slug/vault/hygiene
GET   /api/projects/:slug/creative-briefs
POST  /api/projects/:slug/creative-briefs
GET   /api/projects/:slug/creative-runs
GET   /api/projects/:slug/creative-outputs
POST  /api/creative-briefs/:id/execute
POST /api/projects/:slug/directions/generate

Pitfall: `PATCH /api/projects/:slug/brand-kit` behaves like a full-field update for brand-kit text fields in the current app; omitted fields may be blanked. Always GET the existing brand kit first, merge changes client-side, and send all core fields (`audience`, `offer`, `positioning`, `voice`, `visual_direction`, `colors`, `typography`, `dos`, `donts`, `notes`).
GET  /api/projects/:slug/directions
POST /api/directions/:id/approve
POST /api/directions/:id/reject
GET  /api/projects/:slug/assets
POST /api/projects/:slug/assets
PATCH /api/assets/:id
POST /api/assets/:id/approve
POST /api/assets/:id/reject
GET  /api/projects/:slug/collections
POST /api/projects/:slug/collections
PATCH /api/collections/:id
POST /api/collections/:id/upload
POST /api/collections/:id/assets
DELETE /api/collections/:id/assets/:assetId
POST /api/projects/:slug/strategy/generate
GET  /api/projects/:slug/review
GET  /api/projects/:slug/review/telegram?limit=10
GET  /api/review/:id/telegram
POST /api/review/:id/decision
POST /api/review/:id/telegram-decision
DELETE /api/review/:id
POST /api/hermes/ingest
```

Hermes ingest example:

```bash
curl -fsS -X POST http://127.0.0.1:4030/api/hermes/ingest \
  -H 'Content-Type: application/json' \
  --data '{
    "project_slug":"astro-mage",
    "type":"url",
    "title":"Reference landing page",
    "source_url":"https://example.com",
    "notes":"Premium but not the exact color direction."
  }'
```

Pinterest board import example:

```bash
curl -fsS -X POST http://127.0.0.1:4030/api/projects/north-star/pinterest/import \
  -H 'Content-Type: application/json' \
  --data '{"url":"https://www.pinterest.com/firemnt/celestial/","limit":12,"delay_ms":700}'
```

Use this for moodboards/reference boards when Alex wants vision AI analysis without hammering Pinterest. The importer caches board metadata, downloads images into the media vault, registers `reference-image` assets as trusted ingredients, links them to a collection, and should queue collection-level review rather than one review row per imported image. If a valid board imports 0 images, do not retry aggressively; some Pinterest boards expose no RSS/unauthenticated image data, so use an authenticated/browser fallback or ask for exported references.

## AI-assisted asset intelligence / KB / generation architecture

When Alex asks about upload metadata, vision models, Telegram-first asset capture, LLM Wiki/knowledge-base integration, or borrowing from the image generation app, treat this as a core Hermes Creative architecture task — not a manual form/UI tweak.

Current baseline as of commit `84b930f` plus the 2026-05-18 repair: Hermes Creative has durable technical metadata on upload, `asset_ai_enrichments`, project KB scaffold/pages, enrichment apply/reject endpoints, `generation_jobs`, `asset_versions`, fal generation/edit adapter plumbing, collection Generate UI, asset drawer AI/generation surfaces, and OpenAI/Codex subscription-backed vision enrichment. The real vision provider path should default to Hermes/OpenAI subscription auth (`openai-codex`, usually `gpt-5.5`) rather than direct `OPENAI_API_KEY` quota. Local/technical fallback must not be presented as successful visual enrichment.

Preferred target pattern:

1. Save uploaded media immediately and never block upload success on AI provider availability.
2. Queue AI vision enrichment that drafts title, kind, tags, visual semantics, brand role, collection placement, prompt fragments, negative prompt fragments, fit/mismatch against current brand context, and practical do/don’t observations. Do not generate proposed brand rules from routine asset analysis.
3. Store each AI attempt/proposal in `asset_ai_enrichments`, but on successful real vision analysis also merge the structured fields into canonical `assets.metadata_json` so future Hermes skills/agents can query assets directly without requiring a manual “apply” step. Proposed durable brand rules still require review/approval before updating brand memory.
4. Maintain project-scoped KB files (`kb/SCHEMA.md`, `kb/index.md`, `kb/log.md`, raw/assets/brand/concepts/comparisons/queries) so asset knowledge compounds like an LLM Wiki.
5. Automatically write asset KB pages, but only update durable brand rules/decisions after explicit approval.
6. Borrow fal Studio's server-side generation/edit adapter patterns, not its whole UI. Generated/edited media must become Hermes Creative vault files, assets, collection members, review items, KB pages, generation job records, and automatic vision-enriched asset metadata. FAL queue endpoints may return only `request_id`/`status_url`/`response_url` at first; poll the queue until a real image/video URL exists, treat “still in progress” as non-terminal, and clear stale `generation_jobs.error` on successful reruns. See `references/collection-overlay-and-fal-queue-2026-05-18.md`.
7. For editing current media, default to “Save as new asset”; “Replace current media” requires explicit confirmation and a version snapshot.
- For AI generation/edit jobs, the UI must be backed by `generation_jobs`, not temporary component state. Poll/list jobs from the project endpoint so active/failed/completed work survives refresh, and show all simultaneous jobs in a compact tray. Image analysis must follow the same durable-job UX: `asset_ai_enrichments` should be created and returned immediately, run server-side in the background, appear in the collection job tray alongside generation/edit jobs, survive drawer/overlay close, and allow parallel jobs. See `references/parallel-generation-edit-analysis-ux-2026-05-18.md` and `references/async-analysis-job-queue-and-codex-vision-2026-05-29.md`.
9. For asset edit/variation, default to **OpenAI subscription-backed GPT Image 2** (`openai-codex/gpt-image-2`) when Codex/ChatGPT OAuth is available, and include the source asset as reference id 1. The UI should expose a model picker so Alex can switch to GPT Image 2 High or FAL edit models. If OpenAI/Codex image generation fails, automatically fall back to a reference-capable FAL edit model (currently `fal-ai/nano-banana-2/edit`) and record both requested model and actual fallback provider/model in job/asset metadata. Verify reference images reach the provider: OpenAI/Codex uses `input_image` content, while FAL uses `image_urls`/`image_url` via `applyReferenceUrlsToFalBody()`.

### Transparent PNG / alpha-safe vision analysis

For transparent assets, do not send the raw PNG in a way that lets the provider flatten hidden transparent RGB to black. Some PNGs have black RGB under fully transparent alpha; provider alpha handling can make the model falsely describe a black background or infer bogus dark-background rules. Preserve the original file, but for vision analysis create an analysis-only warm-cream/checkerboard matte preview and pass technical context (`has_alpha`, `alpha_source`, `png_color_type`) into the prompt. Explicitly tell the model the matte is not the asset background and not to infer black/dark placement from hidden RGB. See `references/transparent-asset-analysis-and-review-scope-2026-05-29.md`.

### Proposed brand rules are retired

Do not request, store, display, review, or promote `proposed_brand_rules` from asset/collection analysis. Alex explicitly removed that workflow: routine asset intelligence should capture visual semantics, brand role/fit, risks, prompt fragments, tags, and suggested collections, but not generate brand-rule approval work. Durable brand rules belong in explicit brand-strategy/rules passes, not background image analysis. See `references/transparent-asset-analysis-and-review-scope-2026-05-29.md`.

### Vision analysis quality bar

Alex explicitly corrected that AI should **not** merely say “picture of a star” or provide a generic caption. The analysis must answer brand-system questions:

- What role does this image play in the brand system: logo reference, moodboard/reference, campaign image, UI/product expression, generated output, edit output, typography/color/texture reference, etc.?
- Does it fit or conflict with the current brand kit, and why?
- What collections should it belong to?
- What reusable prompt fragments and negative prompt fragments should be saved?
- What visual do/don’t rules does it imply?
- Should it become a proposed brand rule for review?

The implemented prompt version is `asset-enrichment-v2-brand-system` in `src/lib/ai/visionAdapter.mjs`; keep future provider adapters aligned with that contract. That contract should not include `proposed_brand_rules`; analysis should remain replaceable asset intelligence, not a durable-rule proposal workflow. See `references/asset-analysis-transparency-reanalysis-2026-05-29.md` for the transparency/re-analysis correction.

### Vision provider and “Needs setup” debugging

If generated/uploaded/edited images show **Needs setup**, inspect backend enrichment state before changing UI labels:

```bash
cd /home/avalon/apps/hermes-creative
node - <<'NODE'
import Database from 'better-sqlite3';
const db=new Database('./data/hermes-creative.sqlite');
console.log(db.prepare("select e.id,e.asset_id,e.status,e.provider,e.model,substr(e.error,1,180) error,a.title,json_extract(a.metadata_json,'$.ai.status') ai_status from asset_ai_enrichments e join assets a on a.id=e.asset_id order by e.id desc limit 20").all());
NODE
```

Known pitfall: direct OpenAI API quota failures (`OPENAI_API_KEY` / `gpt-4o-mini`) produce legitimate `provider_needed`/failed states even though Hermes has ChatGPT subscription access. The fix is to route vision through `openai-codex`/Codex OAuth (Python bridge if needed), then merge successful `proposedMetadata` into canonical `assets.metadata_json` and clear stale `ai.error`. See `references/openai-codex-vision-asset-enrichment-2026-05-18.md`.

See `references/ai-vision-kb-generation-architecture-2026-05-17.md` for the inspected current state, proposed tables, KB layout, brand-aware enrichment schema, generation/edit flow, and implementation order. A full repo-local plan also exists at `/home/avalon/apps/hermes-creative/docs/plans/2026-05-17-ai-vision-kb-generation-architecture.md` (commit `5c01d30`). See `references/asset-intelligence-foundation-2026-05-18.md` for the deployed foundation, exact verification recipe, and the brand-system analysis correction.

## Vault conventions

Vault root:

```text
/home/avalon/hermes-media-vault/projects/<project-slug>/
```

Canonical folders:

```text
brand/
references/uploads/
references/screenshots/
references/youtube/
moodboards/
generated/images/
approved/
rejected/
campaigns/
exports/
```

Every major asset/reference should preserve:
- source/provenance
- project
- direction/campaign if relevant
- prompt/model if generated
- status
- tags
- notes
- approval/rejection rationale

## Brand context pack

Each project should maintain:

```text
brand/brand-brief.md
brand/brand-context.md
brand/brand-glossary.md
brand/visual-rules.md
brand/voice-and-tone.md
brand/content-pillars.md
brand/decisions.md
```

The compact `brand-context.md` is the preferred context to inject into future Social/Ads/Creative tasks.

## Safety rules

- Do not publish social content from Hermes Creative.
- Do not push ads to Meta from Hermes Creative.
- Handoffs create local drafts only unless Alex explicitly requests execution in the downstream app.
- Creative output handoffs must stay downstream-draft-only: Social draft handoff records `publish_status: not_published`; Ads draft handoff creates a paused local draft and records `meta_write: false`, `publish: false`, `activate: false`, and `spend: blocked`.
- Handoff buttons must never feel dead: show an immediate busy/status message (`Creating Hermes Social draft…`, `Sending…`), catch and surface backend errors in the UI, and refresh the project after success so `draft_created` targets become Open buttons. For local VPS server-to-server handoffs, if Creative lacks a downstream API secret in its own PM2 env but the downstream app owns it, read the downstream `.env` server-side as a fallback; never expose or log the credential value. See `references/social-handoff-feedback-and-env-fallback-2026-06-01.md`.
- Telegram handoff buttons must also visibly confirm in the chat/topic, not just answer the inline callback. For `hc:social`/`hc:ads`, route through Creative's handoff endpoints, include platform/post-type args when present, then send a same-thread message with the draft id and Open button. See `references/telegram-creative-handoff-callbacks-2026-06-01.md`.
- Social handoff must make routing explicit before creating the draft: show a compact target selector (Instagram or Facebook) and, for Instagram, a format selector (Reel/Post/Story/Carousel). Persist the selection in the Hermes Social draft metadata (`publish_target`, `target_platform`, `post_type`, `instagram_post_type`) and attach an appropriate connected target account so downstream Social actions do not fail with `Connected target account required`. See `references/social-handoff-platform-target-options-2026-06-01.md`. 
- Social handoff must make routing explicit before creating the draft: show a compact target selector (Instagram or Facebook) and, for Instagram, a format selector (Reel/Post/Story/Carousel). Persist the selection in the Hermes Social draft metadata (`publish_target`, `target_platform`, `post_type`, `instagram_post_type`) and attach an appropriate connected target account so downstream Social actions do not fail with `Connected target account required`. See `references/social-handoff-platform-target-options-2026-06-01.md`. 
- Separate approvals:
  - Approve creative direction.
  - Approve asset.
  - Approve creative brief.
  - Create Video Story/local agent draft.
  - Approve final creative output.
  - Create Social/Ads local draft handoff.
  - Publish/schedule social in Hermes Social.
  - Push paused ad in Hermes Ads.
  - Activate/spend in Hermes Ads.
- Track provenance. External references are inspiration unless usage rights are clear.
- Never log or expose API tokens/secrets.
- For vision enrichment, real provider failure is not pseudo-success. If Venice/OpenAI/etc. is missing credentials, has no balance, or returns a provider error, mark the asset/enrichment as needing setup and keep the technical error in logs/details; do not merge local technical metadata as if it were a completed brand-system analysis.
- Transparent PNG analysis must account for alpha. Some provider/model paths flatten alpha or ignore it, exposing hidden black RGB in transparent pixels and causing false “black background” descriptions. Detect alpha in technical metadata, send an analysis-only warm-cream/white matte preview for vision, and tell the model the original background is transparent. Do not infer dark-background placement from hidden RGB under transparent pixels.
- Re-running Analyze on an asset replaces the prior analysis fields (`visual_semantics`, `brand_interpretation`, `organization`, and legacy flattened analysis fields) while preserving technical/provenance/transparency/manual metadata. Do not deep-merge stale visual interpretation into new results.
- Do not request, store, review, or promote `proposed_brand_rules` from asset/collection analysis. Alex corrected that high-level review is for final posts/drafts and substantive Hermes-created outputs, not routine analysis metadata or proposed rules. Asset analysis may store prompt fragments and practical do/don’t observations only.

## Preferred workflow

1. Create/select project.
2. Capture references via Telegram or UI.
3. For brand exploration, lead with visual cues and approval/rejection loops rather than questionnaires. Ask at most one focused question per turn, derived from the specific visual feedback just given.
4. Ask Brand Architect for synthesis.
5. Keep the current layer clear: if Alex is using Hermes Creative for brand work, stay in brand strategy / creative direction mode and do not drift into detailed app UX/build specs unless explicitly asked. First-open copy may be discussed as brand messaging, not implementation.
6. Generate creative directions.
7. Approve/reject direction.
8. Export/update brand context pack.
9. Generate or upload media assets.
10. Review/approve/reject generated assets, collection-level context, and final drafts. Do not require per-upload approval for every manual/imported ingredient; preserve provenance in metadata/audit and use `asset_collection` review for batch intent.
- When Alex approves/rejects a batch and asks what it means, analyze the actual DB decisions, create approved/rejected contact sheets for image sets, compare patterns, save a synthesis note under `brand/`, and create 3–5 new `creative_directions` plus review rows. Do not reduce the signal to a crude binary if approved/rejected sets share motifs; find the sharper boundary between approved and rejected executions.
12. When Alex asks to consolidate or clean up a project after clones/renames/iterations, make the intended slug canonical: compare duplicate projects for the strongest strategy/assets, back up SQLite, copy/merge the best strategy into the canonical project, archive stale collections rather than deleting by default, attach useful assets to clear active collections, suppress review spam for trusted/direct-use ingredients, and verify project/collections/creative-index/review APIs. If Alex explicitly asks to delete/remove collections/assets and clean up connected knowledge, treat it as deep memory cleanup: remove unkept asset rows, physical vault files (preserving backup), AI enrichments, asset versions, KB links/pages, review rows, generation jobs, and orphan joins; then verify no deleted catch-all/inbox collection is recreated by read-only collection APIs. See `references/north-star-canonical-project-cleanup-2026-05-28.md` and `references/vault-list-and-deep-cleanup-2026-05-28.md`.
13. For Social/Ads handoff, first create a **creative brief** from the creative index (`POST /api/projects/:slug/creative-briefs`) so the downstream agent receives brand strategy, approved assets, prompt fragments, avoid patterns, constraints, and an explicit review question. The brief should create a pending `creative_brief` review row and remain draft-only until approved. For briefs that may produce final media, include a `media_reference_plan`: static-image briefs should expose GPT Image 2 slot readiness (`main_image`, `layout_reference`, `style_reference`, `logo_reference`, `typography_reference`, `product_reference`), while video briefs should expose video-story slot readiness (`character_reference`, `set_reference`, `prop_reference`, `style_reference`, `logo_reference`). Missing slots are not failures; they are explicit prep work for Hermes to generate/select/upload a reference before final execution.
13. On `creative_brief` approval, create a **local draft agent run** and reviewable draft outputs. Persist run history in `creative_agent_runs`, generated drafts in `creative_outputs`, add `creative_output` review rows, and write a vault artifact under `campaigns/creative-run-<id>.md`. Manual `POST /api/creative-briefs/:id/execute` should use the same execution service. See `references/local-draft-execution-loop-2026-05-27.md`.
14. Generate campaign strategy.
15. Handoff approved creative outputs to Hermes Social/Hermes Ads as local drafts only. Social handoff should create an unpublished draft; Ads handoff should create a paused draft with no Meta write/activation/spend, and downstream apps own scheduling/publishing/spend approvals. See `references/approved-output-social-ads-draft-handoffs-2026-06-01.md`.
15. Pull performance learning later and update strategy.

## Visual branding approval loop

When Alex asks to move into visual branding/image generation from Hermes Creative:

0. First classify the requested visual layer before generating: **brand mark/logo**, **brand imagery/content system**, **campaign/social/ad creative**, **moodboard/reference**, or **UI/product expression**. If UI is not explicitly requested, keep outputs as brand imagery/media direction rather than app screens.
1. Create a compact set of visual directions in `creative_directions`, scoped to the active project.
2. Generate images for those directions. For brand imagery, prompt for reusable visual systems and media/content treatments, not just UI mockups.
3. Copy generated files into the project media vault, usually `generated/images/`.
4. Register generated images as `assets` rows with `direction_id`, `file_path`, and prompt/provenance notes; generated assets should create review queue rows. For user-provided uploads/imports, default to trusted active ingredients and queue collection-level review instead of one asset review per image.
5. Send Telegram-native `MEDIA:/absolute/path` images with short labels so Alex can approve/reject/comment.
6. Apply feedback to actual Hermes Creative asset/direction statuses before generating the next round.
7. Only translate approved brand imagery into UI screens/components when Alex asks for UI or when the project phase is explicitly product design.

Pitfall: do not treat generated images as detached chat artifacts. They must be tracked in Hermes Creative’s DB, media vault, and review queue so approvals/rejections become durable creative memory.

Pitfall: do not over-index on UI. Alex may be building a full brand where the primary visual output is content/media/identity; UI should be treated as a downstream expression of the brand system, not the center of the creative process.

- Pitfall: Review queue image assets can be present in `assets` with valid image files but still show no preview if `media_url` is not computed. Current app does **not** store `assets.media_url`; it computes it from `file_path`. The resolver must support both absolute vault paths and vault-relative paths like `projects/<slug>/generated/images/foo.png`. See `references/review-queue-image-assets-2026-05.md` and `references/review-deck-and-media-url-pitfalls-2026-05.md` for the debug/fix recipe.

## DB maintenance patterns

When Alex asks to remove generated project data shown in the app, act directly on the SQLite DB after inspecting schema and backing up when the change is broad:

- Creative direction cards live in `creative_directions`; their review queue rows live in `review_items` with `item_type='direction'` and matching `item_id`.
- To clear generated starter directions for a project, delete matching `review_items` first, then `creative_directions`, scoped by `project_id`; verify both counts are zero.
- When renaming a project, update `projects.slug`, `projects.name`, `projects.brief`, and `projects.vault_path`; rename the vault folder under `/home/avalon/hermes-media-vault/projects/<slug>` if present.
- Also replace old visible names/slugs in attached rows: `brand_kits`, `references`, `campaigns`, and `audit_events` payloads/text fields.
- If a duplicate old project exists, archive/rename it instead of leaving old branding active in the project list.
- Verify with `GET /api/projects`, `GET /api/projects/:new_slug/brand-kit`, and confirm the old slug returns 404.

## When generating media

If Alex provides many source/reference images, do not arbitrarily limit to 3. Use the full provided set or clearly state any provider/model cap first.

### North Star visual style — minimal organic line / block-print (Alex correction)

For the North Star project, the approved visual direction is **organic minimal line art with restrained block-print weight, minimal shading, and lots of negative space**. Earlier overly-ornate "modern talisman" demos were rejected. When generating for North Star:

- Start MINIMAL first. One small primary symbol (eight-point star) + at most one supporting element (hand OR sun circle OR crescent, not all).
- No borders, captions, rays, dot clusters, decorative micro-ornament, or "oracle card" framing unless explicitly requested.
- Slightly imperfect carved/handmade line. Warm cream/eggshell background, flat black ink, optional one muted ochre/rust accent.
- Negate aggressively: "no glossy vector, no detail flare, no captions, no extra symbols, no ornate rays."
- **Banned style words / framings:** Alex does not want the word **"folk"** (or "folkloric", "folk-art") used in prompts or descriptions for North Star or related brand work. Prefer "modern block print", "line art talisman", "minimal block print", or "organic minimal line art". When describing visuals back to Alex, mirror his vocabulary, not stock art-direction phrases.
- See `brand/visual-decision-synthesis.md` in the project vault for the full approval/rejection synthesis and the explicit correction note.

### DO NOT invent motif lists from scratch (Alex correction)

When Alex asks for "more talisman options" or "another round of brand imagery", **do not** open by inventing a list of stock motifs (eye+triangle, ouroboros, phoenix, wolf+moon phases, all-seeing eye, lotus halos, etc.) and fanning them across models. Alex has explicitly said this produces "cheesy and generic" results that betray the unique references he has already curated. This failure mode happens even when the prompt language sounds correct ("modern block print line art talisman") — because the *motif inventory* is the actual generic ingredient, not the surface adjectives.

Correct opening move for any "more options" or "different references" request on a project that already has approved assets:

1. Query the project's approved assets first: `sqlite3 .../hermes-creative.sqlite "SELECT a.file_path FROM assets a JOIN projects p ON p.id=a.project_id WHERE p.slug='<slug>' AND a.status='approved' ORDER BY RANDOM() LIMIT 12-15;"`
2. Surface a small contact sheet of those approved references (via the `/media/` URLs) and ask Alex to pick 2-3 as seeds.
3. Only then do reference-guided generation against those seeds. Never substitute "Hermes invents 10 fresh concepts" for "Hermes inherits from Alex's curation."

If Alex's reply is a frustration signal ("not liking", "generic", "rewind", "back to creative direction"), treat that as an order to stop generating and re-anchor on the vault — not to retry with different adjectives.

For the **seven classical planetary gods** workflow, avoid making Jupiter/Mars/Sun/Venus/Mercury/Moon by editing the approved Saturn image. That produces a coherent style but accidentally transfers Saturn's posture and silhouette into the other gods. Correct sequence: generate a fresh text-only base for each god using the compressed ancient-classical → isolated subject → simplified etching prompt, then apply the approved style variants to that god's own base image. See `references/planetary-god-fresh-base-correction-2026-05-16.md`.

When Alex reviews individual planetary gods, treat his character-direction notes as iconographic corrections, not just "style" tweaks. Known corrections: Zeus/Jupiter should read more powerful/kingly/thunderous; Sun should read as powerful Apollo/solar god; Venus should be more alluring/classically beautiful but provider prompts must use safe museum-classical wording; Luna should be lunar mother goddess first with Artemis/Diana cues second. For Luna specifically, avoid AI bow/hand artifacts: no bow in hand, no extra hand, no bow emerging from the dress; place a bow separately on the ground or omit it. See `references/planetary-god-v3-v4-feedback-2026-05-17.md`.

### Multi-engine image generation with vault references (preferred pattern)

This is the **default** pattern for any brand-imagery generation round on a project with approved references — not a fallback. Text-only prompts should be reserved for the very first exploration round on a brand-new project with no curated references yet.

When generating brand imagery from approved references, the strongest pattern is to feed real approved Hermes Creative assets to reference-capable edit endpoints rather than relying on text-only prompts.

1. Confirm the vault assets are publicly reachable at `https://hermes-creative.apps.poofc.com/media/projects/<slug>/...` (the server mounts `/media` on the vault root).
2. Pick 1-3 approved references that best embody the target style (filter on `assets.status='approved'`).
3. Submit in parallel to multiple engines for comparison:
   - **fal `nano-banana/edit`** — `image_urls` array, accepts up to multiple refs, best for multi-ref style transfer.
   - **fal `qwen-image-edit`** — single `image_url`, fast and obedient to minimal prompts.
   - **fal `flux-pro/kontext`** — single `image_url`, good for clean line preservation.
   - **Venice `/image/multi-edit`** — up to 3 images, but uses `modelId` (not `model`) and only certain model ids work (`qwen-edit`, not `qwen-image-2`).
4. Register every output as an asset row pointing into `generated/images/<batch-slug>/` with provenance in notes.

Provider quirks worth remembering:

- **OpenAI gpt-image-2** has three quality tiers — `low`, `medium`, `high` (set via `hermes config set image_gen.model gpt-image-2-high`). `medium` tends to over-decorate even when prompts say minimal; `high` is meaningfully more obedient. Codex auth shares a usage budget and will 429 — have FAL ready as a fallback.
- **Venice** requires balance on the account or all `/image/*` endpoints return 402 `Insufficient USD or Diem balance` — check before relying on it.
- **Replicate** requires `REPLICATE_API_TOKEN` in `~/.hermes/.env`; without it, skip Replicate entirely rather than guessing.

See `references/north-star-visual-branding-loop-2026-05.md` and the project vault's `brand/visual-decision-synthesis.md` for the full North Star approval/rejection mapping.

## Deployment notes

Build/restart:

```bash
cd /home/avalon/apps/hermes-creative
npm run build
PORT=4030 pm2 start /home/avalon/apps/hermes-creative/server.mjs --name hermes-creative --cwd /home/avalon/apps/hermes-creative
pm2 save
curl -sS http://127.0.0.1:4030/api/health
```

Pitfall: `pm2 restart hermes-creative --update-env` can preserve or reapply a stale `PORT` from another app if the process was previously started incorrectly. If `:4030` health fails after restart, check `pm2 env <id> | grep '^PORT'` and recreate the process with `PORT=4030 pm2 start ... --cwd ...`, then `pm2 save`.

PWA app shell should not rely on nginx Basic Auth; use app-level auth for sensitive APIs when added.

## References

- `references/telegram-creative-handoff-callbacks-2026-06-01.md` — Gateway callback fix pattern for Creative Telegram handoff buttons that look active but create no drafts: allow `hc:social`/`hc:ads` verbs with platform args, route through Creative handoff endpoints, send visible same-topic draft confirmations, and preserve no-publish/no-spend safety copy.
- `references/approved-output-social-ads-draft-handoffs-2026-06-01.md` — Create / Queue approval-to-handoff contract: brief approval unlocks draft-only production, Video Story exports register as reviewable creative outputs, approved outputs can create Social/Ads local drafts, Ads drafts stay paused with no Meta write/activation/spend, and UI actions live in the Drafts modal.
- `references/social-handoff-feedback-and-env-fallback-2026-06-01.md` — Debug/fix pattern for Send to Social appearing dead: verify Creative/Social logs and output handoff state, use server-side downstream `.env` fallback for local app API keys when Creative env lacks them, and always show busy/error/success UI feedback for handoff buttons.
- `references/telegram-approved-output-handoff-callbacks-2026-06-01.md` — Gateway-side correction for Telegram approved-output handoff callbacks: parse `hc:social|ads` extra args, route through Creative handoff endpoints, post visible same-topic confirmation messages with Open draft buttons, and use duplicate/retry cards with direct Social/Ads options for already-approved outputs.
- `references/pipeline-inspector-trace-ui-2026-05-31.md` — Hermes Creative pipeline inspector pattern: compact topbar diagram icon, per-brief Inspect pipeline action, vertical expandable nodes for context pack → brief input → prompt/media context → review gate → run/handoff → outputs, plus recommended future `pipeline_trace_events` persistence.
- `references/video-story-handoff-media-url-aspect-2026-05-31.md` — hardening follow-up for Creative→Video Story handoffs: downstream packet media URLs must be absolute Creative public URLs, Video Story defensively prefixes `/media/...`, reel/short/story channels should land as `9:16`, and existing relative-URL imports need DB backfill or draft recreation.
- `references/video-story-brief-rerun-review-loop-2026-05-31.md` — recipe for rerunning an existing Creative video brief through a fresh Video Story draft after generator-default changes, verifying social narration, registering the export back into Creative review, sending Telegram buttons, and testing the YOLO frame fallback/retry path (`generationConfig` scope pitfall). For Seedance reruns, also verify Video Story social-creative YOLO used `Voiceover:`-only audio parsing, check Atlas completed outputs under `data.outputs[]`, and remember Video Story export requires `video_status='complete'`.
- `references/vault-hygiene-api-2026-05-30.md` — Phase 2 Vault hygiene diagnostic endpoint: `GET/POST /api/projects/:slug/vault/hygiene` reports unclassified assets, missing analysis, failed enrichment, missing rights notes, and missing role/kind without destructive cleanup or review spam.
- `references/transit-timed-planetary-gods-social-video-2026-05-31.md` — Concept Orchestrator test pattern for astrology-timed social/video posts using real global transit data, approved transparent planetary-god assets, many-to-many media slot reuse, overlay/caption/voiceover preservation, and Video Story draft-only handoff caveats.
- `references/transparent-asset-analysis-and-review-scope-2026-05-29.md` — correction for alpha-safe vision analysis and review scope: transparent PNGs need matte previews plus explicit alpha context; remove `proposed_brand_rules` from asset/collection analysis and avoid review noise for routine analysis.
- `references/asset-edit-overlay-and-destructive-action-ux-2026-05-29.md` — correction for Vault asset drawer image-edit UX: Edit with AI must open a true source-image edit overlay with one prompt/model picker and persistent edit state; Delete from collection belongs behind More; Analyze needs visible busy/Info feedback.
- `references/vault-list-and-deep-cleanup-2026-05-28.md` — Vault List UI correction and deep cleanup recipe: full-width compact admin table, no wrapped action stacks, broad project/collection cleanup removes side tables/files/KB/review/jobs, and read-only collection APIs must not recreate deleted Inbox collections.
- `references/vault-archive-memory-boundary-and-cleanup-2026-05-28.md` — archive/deleted active-memory boundary and deep cleanup semantics: archived data may be preserved historically but must not leak into creative-index, prompt fragments, role counts, generation reference pools, or "What Hermes sees"; includes full cleanup recipe and Vault List/New Collection overlay UI corrections.
- `references/vault-agent-context-preview-2026-05-28.md` — Alex correction and implementation pattern for splitting Vault’s agent context preview into **Brand context** and **Vault intelligence**, including the important rule not to add static `representative_assets` arrays to collection context.
- `references/vault-agent-index-explainability-2026-05-28.md` — explanation/UI contract for the Vault “Hermes sees” / agent context preview, diagnostic chips, and **Refresh agent index** semantics: human-readable sections, not compressed prompt text; refresh recomputes/refetches what agents will see and has no publishing/generation side effects.
- `references/mobile-safe-area-overlays-and-collection-delete-2026-05-28.md` — mobile/PWA overlay safe-area contract: pad internal close/action bars with `env(safe-area-inset-top)`, cover asset/generation/review/collection overlays, and use provenance-preserving **Delete from collection** semantics.
- `references/collection-trust-and-create-queue-2026-05-28.md` — product/implementation correction for collections-first trust: manual uploads/imports are trusted ingredients, collection-level review replaces per-upload review spam, generated assets/final drafts remain reviewable, and the old Automation tab becomes Create / Queue.
- `references/north-star-canonical-project-cleanup-2026-05-28.md` — DB-safe canonical project cleanup recipe: compare duplicate projects for best strategy/assets, back up SQLite, copy/merge strategy into the canonical slug, archive stale collections, attach trusted/direct-use assets to active collections, and verify project/collections/creative-index/review APIs.
- `references/skills-first-product-roadmap-2026-05-27.md` — Alex's product clarification: Hermes Creative is a skills-first toolkit, UI is a utility/cockpit, Define Brand is Typeform-style Hermes interview, Vault is agent-readable creative memory, and Social/Ads should use Creative's brand/vault index plus metrics through approval-gated automation.
- `references/skills-first-brand-strategy-flow-implementation-2026-05-27.md` — deployed first implementation slice: brand strategy session/version schema, guided brand APIs, creative-index API, Define Brand/Vault/Automation UI changes, tests, verification commands, and pitfalls for future Social/Ads bridge work.
- `references/creative-brief-automation-flow-2026-05-27.md` — deployed second implementation slice: creative brief engine/API, Automation composer/list UI, review-gated `creative_brief` rows, contract tests, and Social/Ads bridge shape.
- `references/automation-flow-timestamps-and-traceability-2026-05-27.md` — Alex correction and deployed pattern for making Automation legible: timestamped context pack, gates, briefs, runs, outputs, and source ids so generated artifacts are traceable.
- `references/telegram-demo-brief-trigger-2026-05-27.md` — live-demo recipe for safely triggering Hermes Creative from Telegram: create a creative brief, approve the `creative_brief` review item, verify a local-only draft run plus `creative_output` review rows; includes response shape quirks for `creative-index` and `review` endpoints.
- `references/local-draft-execution-loop-2026-05-27.md` — deployed third implementation slice: approving a creative brief creates local draft agent runs, reviewable `creative_output` rows, Automation run history/output UI, and vault export artifacts while preserving no-publish/no-spend gates.
- `references/telegram-review-payload-api-2026-05-27.md` — Telegram-ready Review API contract: compact review payloads with native-media paths, safety/approval-effect text, and Telegram-sourced decisions that preserve no-publish/no-spend gates.
- `references/telegram-review-cron-card-watcher-2026-05-28.md` — lightweight proactive Telegram review-card delivery pattern: no-agent Hermes cron script reads pending `review_items`, emits one `MEDIA:` card for unseen items, stays silent when idle, and preserves explicit approval-effect semantics.
- `references/phase-2-media-reference-and-video-bridge-2026-05-30.md` — Phase 2 media-reference contract: creative briefs need explicit GPT Image 2 static composition packets or video-story bridge packets, with role-aware reference slots and missing-slot fill instructions.
- `references/hermes-creative-video-bridge-live-audit-2026-05-31.md` (in `ai-video-story-pipeline`) — live audit of the Creative→Video Story draft bridge. Key Creative-side lesson: external bridge packets should send fully-qualified `https://hermes-creative.apps.poofc.com/media/...` URLs, not relative `/media/...`, and reel/story/short video briefs should carry explicit `aspect_ratio: 9:16` rather than relying on downstream inference.
- `references/phase-2-vault-taxonomy-hygiene-and-video-bridge-2026-05-30.md` — consolidated follow-up for Phase 2: many-to-many media slots, GPT Image 2 media packets, Video Story `social_creative` draft bridge, Vault hygiene diagnostics, and taxonomy/metadata normalization.
- `references/creative-brief-media-packets-and-slot-fill-2026-05-30.md` — implementation detail for `GET /api/creative-briefs/:id/media-packet`, `PATCH /api/creative-briefs/:id/media-slots`, Create / Queue slot-fill UI, and Video Story draft handoff gating.
- `references/phase-2-media-reference-slot-many-to-many-2026-05-30.md` — Alex correction: reference slots are many-to-many brief/run usage roles, so the same Vault asset can be used as `main_image`, `style_reference`, `layout_reference`, logo/type/etc. in the same creative job; warn if useful but do not block reuse.
- `references/telegram-review-asset-metadata-suppression-2026-05-29.md` — Alex correction: image analysis / `asset_metadata` notes belong in the Vault, not Telegram approve/reject cards; Telegram review feeds/watchers should use an explicit consequential-item allowlist and exclude metadata rows.
- `references/telegram-inline-review-callback-next-card-2026-05-28.md` — gateway callback pattern for inline Telegram Approve/Reject/More buttons: route decisions through Creative API, send the next pending review card automatically, preserve topic/thread targeting, and verify after gateway restarts.
- `references/openai-codex-vision-asset-enrichment-2026-05-18.md` — Root-cause/fix recipe for assets stuck at **Needs setup** because vision used quota-exhausted direct OpenAI instead of Hermes/OpenAI Codex OAuth; includes Node→Python bridge pattern, canonical metadata merge, stale error clearing, and DB verification queries.
- `references/openai-codex-gpt-image-2-edit-default-2026-05-18.md` — Correction/pattern for making GPT Image 2 via OpenAI/Codex subscription the default image edit/variation model, while keeping a UI model picker and FAL automatic fallback with reference preservation.
- `references/parallel-generation-edit-analysis-ux-2026-05-18.md` — durable pattern for persisted `generation_jobs` UI feedback, parallel AI job trays, refresh recovery, edit-reference defaults, and clear image-analysis setup/status labels.
- `references/clean-asset-metadata-ui-and-venice-vision-2026-05-18.md` — UX and provider correction for asset intelligence: hide raw metadata/JSON behind read-only Technical details, use clean “Image notes” labels/status chips, wire Venice `qwen3-vl-235b-a22b`, and surface Venice billing/config errors as **Needs setup** rather than pseudo-success.
- `references/telegram-workflows.md` — Telegram capture/review/handoff examples.
- `references/ui-review-queue-2026-05.md` — design-system correction and expandable review queue pattern from the MVP launch.
- `references/north-star-brand-onboarding-2026-05.md` — North Star / North Star OS naming, language, and first-open onboarding direction from the former Astro Mage brand discussion.
- `references/north-star-visual-branding-loop-2026-05.md` — North Star visual-branding approval loop: directions → generated images → media vault/assets/review queue → Telegram approvals.
- `references/pinterest-board-import-2026-05.md` — Pinterest board import implementation, RSS/HTML fallback quirks, verification recipe, and PM2 `PORT` pitfall.
- `references/multi-engine-reference-guided-generation.md` — Multi-engine (FAL/Venice/OpenAI/Replicate) reference-guided image generation pattern: pick approved vault assets, expose via `/media/`, fan out to ref-capable edit endpoints, register outputs back as pending assets. Includes provider quirks and prompt rules for sparse/minimal output.
- `references/image-gen-provider-fallback-and-multimodel-comparison.md` — Codex 429 fallback recipe (`hermes config set image_gen.provider/model`), recommended FAL model ids per aesthetic (Flux Pro Ultra / Recraft v3 / Ideogram v3 / Seedream 4), and the multi-model comparison batch workflow with labeled galleries.
- `references/reference-seeded-generation-from-approved-vault-2026-05-16.md` — When Alex says "more options / different references / rewind", DO NOT invent motif lists; query approved vault assets, let Alex pick 2-3 seeds, fan across nano-banana/qwen-edit/flux-kontext. Includes FAL `.env` parsing gotcha and the asset-registration sequence.
- `references/review-queue-image-assets-2026-05.md` — Debug/fix recipe for Hermes Creative Review queue image assets: `review_items` vs `assets.media_url`, React preview rendering, CSS thumbnail/full-preview styles, and deploy verification.
- `references/reversible-brand-marketing-pipeline-and-continuous-review-deck-2026-05.md` — Reversible brand/marketing pipeline phase pattern plus continuous Tinder-style review deck implementation: advance-after-swipe behavior, smooth drag CSS, decision notes, delete semantics, and reviewable marketing concept registration.
- `references/classical-planetary-god-etching-pipeline.md` — Alex's iterative ChatGPT-style deity-image workflow for the seven classical planetary gods: ancient alchemical/classical image → isolate subject → minimal line sketch with subtle shading → etching; includes Mercury prompt and model-verification note.
- `references/planetary-god-v3-v4-feedback-2026-05-17.md` — targeted review corrections for the planetary gods: stronger Zeus/Apollo, safer Venus prompt wording, Luna mother-goddess direction, Luna bow/hand artifact avoidance, and batch idempotency lessons.
See `references/planetary-god-style-variation-transparent-assets-2026-05-16.md` — Saturn variation session: one-prompt vs edit-chain findings, rougher style prompts for block print/marginalia/leadpoint, direct OpenAI/Codex `gpt-image-2` edit invocation, and transparent square bottom-centered asset cleanup workflow. Helper: `scripts/line_art_transparent_square.py`.

See `references/planetary-god-fresh-base-correction-2026-05-16.md` — important correction for the seven planetary gods workflow: do not use Saturn as the reference image for the other gods; create a fresh text-only base per god first, then apply the approved style directives to that god's own base image.
- `references/approval-rejection-synthesis-2026-05.md` — workflow for turning asset approval/rejection batches into contact-sheet analysis, decision synthesis, and new reviewable creative directions.
- `references/visual-identity-packages-foundation-2026-05.md` — package-driven Hermes Creative architecture and implementation notes, including Alex’s correction that brand visual identity packages must be structured visual kits (logo/color/type/layout/inspiration), not copied Brand Kit prose; covers tables/APIs, Visual Packages tab, brand wizard, upload endpoint, dynamic lower-level packages, and next universal-review steps.
- `references/visual-package-wizard-draft-batches-mobile-2026-05.md` — follow-up correction for Visual Package wizard semantics: new wizard creates a live draft immediately; Hermes chat can trigger selectable variation batches; final confirm marks ready/in-review rather than primary; mobile footer and landing overflow CSS fixes.
- `references/visual-package-wizard-verification-smoke-2026-05.md` — historical/deprecated deploy/smoke verification recipe for the old wizard: build + PM2 + health checks, API-created temporary draft, final-confirm patch to `in_review` (not `approved`), archive cleanup, and browser-sandbox fallback checks. Do not use this as the default architecture after the collections pivot.
- `references/collections-first-vault-overhaul-2026-05-17.md` — package-to-collections pivot: schema migration from `visual_identity_packages`/`package_assets` into `asset_collections`/`collection_assets`, new collection APIs, Vault command/grid UI, richer asset metadata fields, smoke tests, and pitfalls.
- `references/project-clone-and-collection-seeding-2026-05-17.md` — workflow for creating a new Hermes Creative project from an existing project's brand kit/assets, cloning assets into the new vault, registering Telegram chat-uploaded logo images, and seeding flexible collections with provenance metadata.