hermes-creative

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.

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:

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

Generate 5 brand directions for Magi from the current vault.

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

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

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:

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:

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:

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.
8. 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:

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:

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

Canonical folders:

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:

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.
11. 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.
12. 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.
16. 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:

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.