cue-ai 0.3.0

package/resources/skills/skills/medusa/gh-submodule-publish/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: gh-submodule-publish
+description: >-
+  Use when user says "publish submodule" or "Medusa submodule publish". Repo state, commits, push, references, validation.
+---
+
+# Gh Submodule Publish
+
+## Overview
+
+Publish an already-initialized parent repo plus one or more submodule repos to GitHub. Preserve the local commits, push submodule repositories before the parent, and finish with remote-ref and clean-tree evidence.
+
+## Workflow
+
+1. Inspect local truth first.
+
+```bash
+# Always resolve repo root dynamically — repos can move mid-session
+PARENT="$(git rev-parse --show-toplevel)"
+cd "$PARENT"
+rtk git status
+rtk proxy git submodule status
+rtk proxy git remote -v
+cat .gitmodules
+rtk proxy git -C <submodule> status --short --branch
+rtk proxy git -C <submodule> remote -v
+```
+
+Record expected commit SHAs from `git submodule status` and parent `git rev-parse --short HEAD`. Do not change commits unless the user asks.
+
+**1a. Validate `.gitmodules` URLs before any push.** Real-world failure mode: typos like `marva_storefornt` instead of `marva_storefront`, or the wrong owner (e.g. `NagyVikt/...` when the canonical is `Webu-PRO/...`). For each submodule URL in `.gitmodules`:
+
+```bash
+# Confirm each declared URL resolves to a real repo
+for sm_url in $(git config --file .gitmodules --get-regexp '^submodule\..*\.url$' | awk '{print $2}'); do
+  owner_repo="$(echo "$sm_url" | sed -E 's#.*github\.com[/:]([^/]+/[^/.]+).*#\1#')"
+  rtk proxy gh repo view "$owner_repo" --json nameWithOwner,url 2>&1 | head -3
+done
+```
+
+If a URL fails with `Could not resolve to a Repository`, do not assume the repo is missing — first try alternative owners (the user's personal account, the org account, recently-used owners from `gh repo list`). Only after exhausting candidates create a new repo. When the canonical owner differs from `.gitmodules`, fix the URL there, then run:
+
+```bash
+rtk proxy git submodule sync         # propagates .gitmodules → .git/modules/*/config
+```
+
+Without `submodule sync`, edits to `.gitmodules` look correct on disk but submodule pushes still hit the old URL.
+
+2. Verify GitHub auth by API, not only status.
+
+```bash
+rtk gh auth status
+rtk proxy gh api user --jq .login
+```
+
+If `gh auth status` says the token is invalid but `gh api user --jq .login` succeeds, continue and note the false-negative status. If the API cannot connect in sandbox, retry with network escalation. If the API still fails because auth is invalid, stop and ask for `gh auth login -h github.com`.
+
+3. Create missing repos.
+
+Check first:
+
+```bash
+rtk proxy gh repo view <owner>/<repo> --json nameWithOwner,visibility,url
+```
+
+If missing, create them, usually private unless the user requested public:
+
+```bash
+rtk proxy gh repo create <owner>/<repo> --private
+```
+
+For submodules, `gh repo create --source .` may fail because submodules use gitfile indirection. Prefer create-by-name, then push with `git -C`.
+
+4. Push submodules before the parent.
+
+Try configured SSH remote first only if it is already configured:
+
+```bash
+rtk proxy git -C <submodule> push -u origin main
+```
+
+If SSH fails with `git@github.com: Permission denied (publickey).`, set up the GitHub CLI helper and push HTTPS directly without rewriting remotes unless needed:
+
+```bash
+rtk proxy gh auth setup-git
+rtk proxy git -C <submodule> push https://github.com/<Owner>/<repo>.git main:main
+```
+
+5. Push the parent last.
+
+```bash
+rtk proxy git push https://github.com/<Owner>/<parent-repo>.git main:main
+```
+
+If GitHub rejects `.github/workflows/*` with missing `workflow` scope, run:
+
+```bash
+rtk proxy gh auth refresh -h github.com -s workflow
+```
+
+This may require device auth. Give the exact URL and one-time code to the user, wait for completion, then retry the parent push.
+
+6. Verify remote refs and clean local state.
+
+```bash
+rtk proxy git ls-remote https://github.com/<Owner>/<parent-repo>.git refs/heads/main
+rtk proxy git ls-remote https://github.com/<Owner>/<submodule-repo>.git refs/heads/main
+rtk git status
+rtk proxy git -C <submodule> status --short --branch
+```
+
+**6a. Submodule sync proof (lifted pattern).** Print a small table comparing local submodule HEADs against their remotes — the canonical evidence that the parent's gitlinks are pointing at commits that actually exist upstream:
+
+```bash
+for sm in $(git config --file .gitmodules --get-regexp path | awk '{print $2}'); do
+  local_head=$(cd "$sm" && git rev-parse HEAD)
+  remote_head=$(cd "$sm" && git ls-remote origin refs/heads/main | awk '{print $1}')
+  match=$([ "$local_head" = "$remote_head" ] && echo "✓" || echo "✗")
+  printf '%-25s local=%.8s  remote=%.8s  %s\n' "$sm" "$local_head" "$remote_head" "$match"
+done
+```
+
+Every row must show `✓` before the parent commit lands. A `✗` means the submodule's HEAD isn't in the remote — push the submodule first or the parent's gitlink will dangle for anyone cloning recursively.
+
+Final answer must include repo URLs, pushed branch refs, matching SHAs, any auth fallback used, and remaining risk if any.
+
+7. Parent push blocked by an auto-classifier or sandbox?
+
+Some agent harnesses block direct pushes to `main`. If `git push origin main` is denied, **do not invent a workaround** (no `--force`, no temp branch rename). Stage and commit locally, then surface the exact one-liner for the user to paste:
+
+```text
+! cd <parent-repo-path> && git push origin main
+```
+
+Report: branch ahead-by N, commit SHA, and which command they need to run.
+
+## Guardrails
+
+- Do not delete or rewrite local history to make a push work.
+- Do not remove workflow files to avoid `workflow` scope; refresh token scope instead.
+- Prefer private repo creation unless the user explicitly asks public.
+- Push submodule repos first so parent gitlinks resolve remotely.
+- Resolve repo root via `git rev-parse --show-toplevel` at every step. Never assume the path the session started in still exists — repos can be relocated mid-task (Documents/X → Documents/Y), and any hardcoded path will dead-end with `cd: No such file or directory`.
+- Validate every URL in `.gitmodules` against `gh repo view` before pushing. A typo (`storefornt`) or wrong owner (`NagyVikt` vs `Webu-PRO`) silently routes the push to the wrong destination — or worse, creates a duplicate empty repo.
+- After editing `.gitmodules`, always run `git submodule sync` before any push. The on-disk file change is meaningless to the active push pipeline until sync propagates URLs to `.git/modules/*/config`.
+- If a command fails because of sandboxed network access, rerun with network escalation instead of declaring auth broken.

package/resources/skills/skills/medusa/gh-submodule-publish/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "GH Submodule Publish"
+  short_description: "Create GitHub repos and push submodule trees"
+  default_prompt: "Use $gh-submodule-publish to create missing GitHub repos, push submodule repos first, then push the parent repo with verification."

package/resources/skills/skills/medusa/higgsfield-to-medusa-products/SKILL.md

@@ -0,0 +1,315 @@
+---
+name: higgsfield-to-medusa-products
+description: >-
+  Use when user says "Higgsfield to Medusa", "generate product photos", or "import AI product assets". Asset generation → product mapping → import.
+allowed-tools: Bash(aws:*), Bash(curl:*), Bash(higgsfield:*), Bash(jq:*)
+---
+
+# Higgsfield → Medusa Product Images
+
+One-shot pipeline that generates product shots with Higgsfield, hosts them on
+the shop's S3 bucket, and updates Medusa products. Replaces the manual
+sequence of `higgsfield product-photoshoot create` → `aws s3 cp` →
+`curl -X POST /admin/products/{id}` that became the prototype while shipping
+compastor.hu.
+
+Pairs with `provision-medusa-s3-bucket` (which sets up the bucket + public-read
+policy on `<prefix>products/*`) and lives downstream of
+`higgsfield-product-photoshoot` (which owns prompt enhancement and CLI usage).
+
+## When to use
+
+User says any of:
+- "generate product images for `<shop>`"
+- "refresh `<shop>` product photos"
+- "képeket generálni a `<shop>` termékekhez"
+- supplies a manifest of product slugs/IDs + prompts and wants them on a Medusa shop
+
+## Inputs
+
+### Required: a shop name
+
+`<shop>` is a short slug, e.g. `compastor`, `lifted`, `munchi`. The skill uses
+it to:
+- locate the per-shop env file: `~/.config/medusa-image-pipeline/<shop>.env`
+- key the future bouncer-MCP scope: `mcp__recodee__vault_get_secret(scope="<shop>")`
+
+### Required: a manifest
+
+Either pass `<manifest.json>` as second arg, or place it at
+`~/.config/medusa-image-pipeline/<shop>.manifest.json`. Schema in
+`assets/manifest.example.json`. Each entry:
+
+```jsonc
+{
+  "slug": "compastor-komposztolto",
+  "product_id": "prod_01KR6T96D1JDVAVHN6CWR9AHVK",   // optional — looked up from slug if omitted
+  "shots": [
+    { "variant": "hero",      "mode": "product_shot",     "prompt": "neutral studio shot, single product front-facing, soft daylight" },
+    { "variant": "lifestyle", "mode": "lifestyle_scene",  "prompt": "garden compost bin in use, autumn light, hands adding leaves" }
+  ]
+}
+```
+
+`variant` is free-form but `hero` + `lifestyle` is the convention (the first
+becomes `thumbnail`, all of them become `images[]`).
+
+### Required: env file (or vault — see Secret resolution)
+
+`~/.config/medusa-image-pipeline/<shop>.env`:
+
+```sh
+# Per-shop config — gitignored, chmod 600
+MEDUSA_BACKEND_URL="https://admin.compastor.hu"
+MEDUSA_SECRET_KEY="sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
+
+S3_BUCKET="compastor-medusa"
+S3_REGION="eu-central-1"
+S3_PREFIX="medusa/products/"
+S3_PUBLIC_BASE="https://compastor-medusa.s3.eu-central-1.amazonaws.com/medusa/products"
+
+AWS_ACCESS_KEY_ID="AKIA..."
+AWS_SECRET_ACCESS_KEY="..."
+```
+
+Bootstrap once per shop:
+
+```sh
+mkdir -p ~/.config/medusa-image-pipeline
+chmod 700 ~/.config/medusa-image-pipeline
+$EDITOR ~/.config/medusa-image-pipeline/compastor.env
+chmod 600 ~/.config/medusa-image-pipeline/compastor.env
+```
+
+## Secret + operation resolution
+
+Two execution modes — pick by who's running the skill.
+
+### Mode A: Agent-driven (Claude / Codex with `secret-mcp` registered)
+
+For providers that already have bouncer-MCP wrappers, the agent calls the
+bouncer tool directly — the secret never enters context. Bouncer state as
+of 2026-05-10:
+
+| Provider | Status | recodee PR |
+| --- | --- | --- |
+| Higgsfield | ✅ landed | #1655 (Phase 1 PoC) |
+| AWS S3 | 🟡 in review | #1660 (Phase 2 first follow-up) |
+| Medusa-admin-API | ❌ not yet wrapped | future Phase-2 PR |
+| Coolify, Hostinger, GitHub, Stripe, Supabase | ❌ not yet wrapped | future Phase-2 PRs |
+
+Available bouncer tools (registered in `tools/secret-mcp/`):
+
+```
+# Higgsfield (PR #1655)
+mcp__secret-mcp__higgsfield_submit_generation({model, prompt, mode?, ...})
+  -> {job_id, status}
+mcp__secret-mcp__higgsfield_get_job({job_id})
+  -> {id, status, result_url?, thumbnail_url?, error?}
+
+# AWS S3 (PR #1660 — pending merge)
+mcp__secret-mcp__aws_s3_head_object({bucket, key, region})
+  -> {exists, size?, etag?, content_type?}
+mcp__secret-mcp__aws_s3_get_presigned_put_url({bucket, key, region,
+  expires_in?, content_type?, cache_control?})
+  -> {url, expires_at, required_headers}
+mcp__secret-mcp__aws_s3_copy_from_url({bucket, key, region, source_url,
+  content_type?, cache_control?, max_bytes?})
+  -> {etag?, size, public_url}
+mcp__secret-mcp__aws_s3_delete_object({bucket, key, region}) -> {ok: true}
+```
+
+Vault-stored secrets (Infisical):
+- `HIGGSFIELD_WORKSPACE_TOKEN` — the only Higgsfield credential.
+- `AWS_SECRET_ACCESS_KEY` — the secret half of the AWS credential pair.
+  The access key id is non-secret and held in env (`AWS_ACCESS_KEY_ID`),
+  per PR #1660's per-credential split rationale. Bouncer also reads
+  `AWS_S3_BUCKETS_ALLOWED` and `AWS_S3_COPY_FROM_URL_ALLOWLIST` from env
+  for blast-radius caps; populate per shop.
+
+There is **no** `vault.get(name)` operation by spec design — vault
+introspection is forbidden (`design.md` §"No introspection tools"). The
+agent cannot fetch the secret value; it can only invoke wrapped operations.
+
+Bootstrap once per developer:
+
+1. Get the per-developer Infisical service-account token via the vault
+   dashboard UI (recodee PR #1656).
+2. Save it: `install -m 600 /dev/stdin ~/.config/recodee/infisical-token` then
+   paste the token + Enter + Ctrl-D.
+3. Make sure recodee `.mcp.json` is in the agent's MCP search path (it is by
+   default when the agent runs in the recodee repo).
+
+Agent-driven full-pipeline flow (per manifest entry):
+
+```
+# 1. Generate via Higgsfield bouncer
+job = mcp__secret-mcp__higgsfield_submit_generation(
+    model="gpt_image_2", prompt=shot.prompt, ...)
+while True:
+    s = mcp__secret-mcp__higgsfield_get_job(job_id=job["job_id"])
+    if s["status"] in ("succeeded", "failed"): break
+
+# 2. Move bytes Higgsfield CDN → S3 via AWS bouncer (NO bytes in agent ctx)
+res = mcp__secret-mcp__aws_s3_copy_from_url(
+    bucket="compastor-medusa", region="eu-central-1",
+    key=f"medusa/products/{slug}-{variant}.jpg",
+    source_url=s["result_url"],
+    content_type="image/jpeg",
+    cache_control="public, max-age=31536000, immutable")
+public_url = res["public_url"]
+
+# 3. Patch product (Medusa not yet bouncer-wrapped — falls through to Mode B
+#    or to a future mcp__secret-mcp__medusa_patch_product call)
+```
+
+For **Medusa-admin-API** (not yet bouncer-wrapped — future Phase-2 PR), the
+agent falls through to Mode B's env-resolution for the `POST /admin/products/{id}`
+leg. Same applies to Coolify, Hostinger, GitHub. Mixed Mode A + Mode B is
+expected during the migration window — each provider migrates independently.
+
+### Mode B: Shell-driven (`run-pipeline.sh`)
+
+The bash script cannot call MCP tools; the bouncer MCP is agent-only by
+design. Shell flows resolve secrets the traditional way, in order, first hit
+wins:
+
+1. **Process env vars** (`MEDUSA_BACKEND_URL`, `MEDUSA_SECRET_KEY`,
+   `HIGGSFIELD_*`, `AWS_*`, …).
+2. **Per-shop env file**: `~/.config/medusa-image-pipeline/<shop>.env`.
+
+The resolver is `scripts/load-env.sh`. Higgsfield in Mode B uses the
+`higgsfield` CLI (which holds its own auth via `higgsfield auth login`) —
+this is the path for CI / cron / non-agent runs.
+
+**Never** echo secret values, **never** put them in git, **never** ask the
+user to paste them into chat.
+
+## What the pipeline does
+
+For each manifest entry, in order:
+
+1. **Generate** — calls
+   `higgsfield product-photoshoot create --mode <mode> --prompt "<prompt>" --count 1 --aspect_ratio <hint> --resolution 2k`
+   for each `shot`. Polls until the job completes. Captures the resulting
+   image URL on Higgsfield CDN. (Owned by the `higgsfield-product-photoshoot`
+   skill — this skill does not write prompts.)
+
+2. **Download** — `curl -fL` the Higgsfield CDN URL into a per-run cache:
+   `~/.cache/medusa-image-pipeline/<shop>/<run-id>/<slug>-<variant>.png`.
+
+3. **Optimize** (optional, on by default) — converts to JPEG via
+   `magick convert <png> -quality 86 -strip <jpg>` if `magick`/`convert` is
+   available. Skipped silently if not installed; PNGs upload as-is.
+
+4. **Upload** — `aws s3 cp` to
+   `s3://<S3_BUCKET>/<S3_PREFIX><slug>-<variant>.<ext>` with
+   `--content-type image/jpeg` (or png) and a long `Cache-Control` header
+   (`public, max-age=31536000, immutable`). Verifies HTTP 200 on the public
+   URL before continuing.
+
+5. **Resolve product ID** — if `product_id` was omitted in the manifest,
+   `GET /admin/products?handle=<slug>` and use the first result.
+
+6. **Patch product** — `POST <MEDUSA_BACKEND_URL>/admin/products/<id>` with
+   `{"thumbnail": "<first-shot-url>", "images": [{"url": "<each-shot-url>"}]}`.
+   Authentication is HTTP Basic with the Medusa secret API key
+   (`Authorization: Basic <base64(secret:)>`).
+
+7. **Verify** — `GET <MEDUSA_BACKEND_URL>/store/products?handle=<slug>` (no
+   auth) and confirm the new URLs appear on `thumbnail` and `images[].url`.
+
+8. **Report** — print one line per product:
+   `ok    compastor-komposztolto (prod_01KR…) — 2 images`
+   or `err   compastor-komposztolto — generate failed at shot 1`.
+
+The orchestration is in `scripts/run-pipeline.sh`. Read it before invoking;
+override behavior via flags rather than editing the script.
+
+## Usage
+
+```bash
+# Default — reads ~/.config/medusa-image-pipeline/<shop>.env
+# and ~/.config/medusa-image-pipeline/<shop>.manifest.json
+bash <skill>/scripts/run-pipeline.sh compastor
+
+# Explicit manifest path
+bash <skill>/scripts/run-pipeline.sh compastor ./custom-manifest.json
+
+# Dry-run — generates + uploads but skips the product patch
+DRY_RUN=1 bash <skill>/scripts/run-pipeline.sh compastor
+```
+
+## Idempotency
+
+- S3 keys are deterministic (`<slug>-<variant>.<ext>`) — re-runs overwrite
+  the same object. Old version is retained because the bucket has versioning
+  on (`provision-medusa-s3-bucket` enables it).
+- Product patches are unconditional — re-running with a new manifest replaces
+  `thumbnail` + `images[]` wholesale. There is no merge with existing images;
+  if you want to keep prior images, list them in the manifest as additional
+  `shots` with a `url` field instead of a `prompt`.
+- If a Higgsfield generation fails for one shot, the entry is skipped and the
+  product is left untouched. Other entries in the manifest still run.
+
+## Bootstrap (first time per workstation)
+
+1. Higgsfield CLI:
+   ```bash
+   curl -fsSL https://raw.githubusercontent.com/higgsfield-ai/cli/main/install.sh | sh
+   higgsfield auth login    # interactive, the user runs this
+   ```
+2. AWS CLI authenticated for the target bucket. Either:
+   - Set `AWS_ACCESS_KEY_ID` + `AWS_SECRET_ACCESS_KEY` in the `<shop>.env`, OR
+   - Run `aws configure --profile <shop>` and add `AWS_PROFILE=<shop>` to the env file.
+3. `jq` and `curl` on `$PATH`. (`magick` optional, only used if installed.)
+
+## Pitfalls
+
+- **Wrong region in `aws s3 cp`** — for AWS S3, `S3_REGION` must be the actual
+  bucket region, not `auto`. The `medusa-config.ts` of compastor previously
+  hardcoded `region: "auto"` which is R2-specific; the file provider 500'd
+  on AWS until that was fixed (commit `e0d9700`). Same lesson here: don't
+  copy the value blindly between providers.
+- **CORS** — the bucket needs `https://admin.<shop>.hu` in `AllowedOrigins`
+  if you ever upload via Medusa admin UI. `provision-medusa-s3-bucket` sets
+  this; if you run the pipeline against a hand-rolled bucket, verify with
+  `aws s3api get-bucket-cors --bucket <bucket>`.
+- **Public-read prefix** — the bucket policy from `provision-medusa-s3-bucket`
+  permits `s3:GetObject` only on `<prefix>products/*`. The pipeline uploads
+  to that exact path. If you change `S3_PREFIX`, also update the bucket
+  policy or the public URLs return 403.
+- **Higgsfield CDN expiry** — the CDN URLs returned by `higgsfield
+  product-photoshoot create` are not durable. Always run step 2–4 (download +
+  upload) before step 6 (patch); never paste a `cdn.higgsfield.ai/...` URL
+  directly into Medusa.
+- **Secret rotation** — when the Medusa secret key is revoked (e.g. via
+  `revoke-secret-key.sh` or admin UI), update `<shop>.env`. Rotation cadence
+  is the user's call; the pipeline does not rotate keys.
+
+## Verification
+
+After a successful run:
+
+```bash
+# Public store API — no auth, confirms storefront sees the new images
+curl -s "https://admin.<shop>.hu/store/products?handle=<slug>" \
+  -H "x-publishable-api-key: <pub-key>" | jq '.products[0] | {handle, thumbnail, images: .images | map(.url)}'
+
+# S3 public URL responds 200
+curl -I "https://<bucket>.s3.<region>.amazonaws.com/<prefix><slug>-hero.jpg"
+```
+
+Expected: `HTTP/2 200`, `thumbnail` and `images[].url` point to the
+`<bucket>.s3.<region>.amazonaws.com` host.
+
+## What this skill does NOT do
+
+- Does not provision the S3 bucket — use `provision-medusa-s3-bucket`.
+- Does not create Medusa products — products must already exist (use
+  `woocommerce-to-medusa-import` or the admin UI).
+- Does not write Higgsfield prompts — the user supplies them in the manifest;
+  prompt enhancement is owned by the `higgsfield-product-photoshoot` backend.
+- Does not rotate or revoke Medusa secret keys — separate concern, separate
+  scripts.
+- Does not store secrets in repos or in the skill itself.

package/resources/skills/skills/medusa/higgsfield-to-medusa-products/assets/manifest.example.json

@@ -0,0 +1,39 @@
+[
+  {
+    "slug": "compastor-komposztolto",
+    "product_id": "prod_01KR6T96D1JDVAVHN6CWR9AHVK",
+    "shots": [
+      {
+        "variant": "hero",
+        "mode": "product_shot",
+        "aspect_ratio": "1:1",
+        "prompt": "compostor garden bin, neutral studio backdrop, soft daylight, 3/4 angle, packshot for product page"
+      },
+      {
+        "variant": "lifestyle",
+        "mode": "lifestyle_scene",
+        "aspect_ratio": "4:3",
+        "prompt": "compostor bin in a Hungarian garden, autumn leaves, hands adding kitchen scraps, golden hour"
+      }
+    ]
+  },
+  {
+    "slug": "compastor-giliszta",
+    "shots": [
+      {
+        "variant": "hero",
+        "mode": "product_shot",
+        "prompt": "small jar of red compost worms, clean white background, soft top-down light"
+      },
+      {
+        "variant": "lifestyle",
+        "mode": "closeup_product_with_person",
+        "prompt": "hands cradling earthworms over rich dark soil, vermicomposting tray visible, warm natural light"
+      },
+      {
+        "variant": "preserved",
+        "url": "https://compastor-medusa.s3.eu-central-1.amazonaws.com/medusa/products/compastor-giliszta-old-keep.jpg"
+      }
+    ]
+  }
+]

package/resources/skills/skills/medusa/higgsfield-to-medusa-products/scripts/load-env.sh

@@ -0,0 +1,69 @@
+#!/usr/bin/env bash
+# load-env.sh — secret + config resolver for the bash pipeline (Mode B in
+# SKILL.md). Sourced by run-pipeline.sh.
+#
+# IMPORTANT — the recodee bouncer MCP (Phase 1, PR #1655) is agent-only by
+# spec design: vault introspection (`vault.get(name)`) is forbidden, so there
+# is no shell-side fetch path. Agent-driven runs (Claude / Codex) call the
+# bouncer MCP directly and skip this script entirely for wrapped providers.
+# This script handles non-agent runs (CI / cron / manual) and unwrapped
+# providers (AWS-S3, Medusa-admin-API — Phase 2, not yet landed).
+#
+# Resolution order (first hit wins, per env var):
+#   1. process env (already exported)
+#   2. ~/.config/medusa-image-pipeline/<shop>.env  (chmod 600)
+#
+# Usage:
+#   SHOP="$1" source "$(dirname "$0")/load-env.sh"
+#
+# Required exports after sourcing:
+#   MEDUSA_BACKEND_URL, MEDUSA_SECRET_KEY,
+#   S3_BUCKET, S3_REGION, S3_PREFIX, S3_PUBLIC_BASE,
+#   AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY  (or AWS_PROFILE)
+
+set -euo pipefail
+
+SHOP="${SHOP:-${1:-}}"
+[[ -z "$SHOP" ]] && { echo "load-env: SHOP arg required" >&2; return 2 2>/dev/null || exit 2; }
+
+CONFIG_FILE="${MEDUSA_PIPELINE_CONFIG:-$HOME/.config/medusa-image-pipeline/$SHOP.env}"
+
+# --- Step 1: process env vars stay as-is ---
+# Nothing to do; bash already has them.
+
+# --- Step 2: per-shop config file ---
+if [[ -f "$CONFIG_FILE" ]]; then
+  perm=$(stat -c "%a" "$CONFIG_FILE" 2>/dev/null || stat -f "%Lp" "$CONFIG_FILE")
+  if [[ "$perm" != "600" && "$perm" != "400" ]]; then
+    echo "load-env: refusing to read $CONFIG_FILE (perms $perm — must be 600 or 400)" >&2
+    return 3 2>/dev/null || exit 3
+  fi
+  set -a
+  # shellcheck source=/dev/null
+  . "$CONFIG_FILE"
+  set +a
+fi
+
+# --- Validate required vars (without echoing values) ---
+missing=()
+for v in MEDUSA_BACKEND_URL MEDUSA_SECRET_KEY S3_BUCKET S3_REGION S3_PREFIX S3_PUBLIC_BASE; do
+  [[ -z "${!v:-}" ]] && missing+=("$v")
+done
+
+# AWS auth: either explicit keys OR an AWS_PROFILE
+if [[ -z "${AWS_ACCESS_KEY_ID:-}" && -z "${AWS_PROFILE:-}" ]]; then
+  missing+=("AWS_ACCESS_KEY_ID or AWS_PROFILE")
+fi
+
+if (( ${#missing[@]} > 0 )); then
+  echo "load-env: missing required config: ${missing[*]}" >&2
+  echo "load-env: set in env or in $CONFIG_FILE" >&2
+  return 4 2>/dev/null || exit 4
+fi
+
+# Normalize: trailing slash on prefix, no trailing slash on public base
+S3_PREFIX="${S3_PREFIX%/}/"
+S3_PUBLIC_BASE="${S3_PUBLIC_BASE%/}"
+export S3_PREFIX S3_PUBLIC_BASE
+
+return 0 2>/dev/null || true