Medusa × EVE integration pattern (2026-10-13)

Young's synthesis direction: Medusa + EVE is a great match. Verified every claim in the brief against live sources — all check out, including two I initially doubted and then confirmed wrong. This note registers the combined architecture on top of hermes-eve-cohosting-study and medusa-hosting-docker-study.

Verification ledger (all live-probed 2026-10-13)

• Correction on record: my earlier "beta-churn" caution stands, but the beta label should not read as "claims unverified" — EVE's own docs are consistent and the framework scaffold (init/extension/add) matches them.

Combined architecture — the product stack

tenant commerce stack (per-tenant Docker compose, MIT, on our Oracle ARM node)
├── Medusa backend  (server + worker split, Postgres + Redis)  ← Admin API
├── Next.js storefront + useEveAgent() chat UI
└── EVE agent (self-hosted Nitro, eve build → eve start)
    ├── instructions.md     sales/support persona, tenant-tuned
    ├── tools/              Medusa Store API wrappers (/store/products, carts,
    │                       checkout) — typed, read-scope publishable key
    ├── connections/        medusa.ts — key handling via EVE config schema (zod),
    │                       secrets from environment (0600 fleet hygiene carries)
    ├── skills/             refund-playbook.md, checkout-flow.md, gift-card.md
    │                       (load-on-demand = variant-catalogue context isolation)
    └── workflows           durable: order-status watcher, HIL gates on
                            refund/bulk-pricing → pause → admin approval
                            → fire against Admin API with scoped app token

• Why it holds up: Medusa's Store API is modular and stable (v2.21.2, active); EVE's tool/skill/connections conventions map 1:1 onto it without glue code; the storefront channel is first-party (useEveAgent), and Nuxt/Next hosting is already our docs-site pattern.
• HIL + keys are the trust layer: publishable key (read) for storefront-agent tools; Admin API writes only through HIL-approved workflows, per-tenant app token stored via EVE config from env — never in sources. This is APL-discipline from the Saleor study, imported into the Medusa+nestjs's EVE lane. 1st-class patterns verified in 10-13 hermes-eve study.

Product assembly (three lanes converge)

1. Medusa hosting (per-tenant compose, Oracle ARM ~2–3 tenants pilot): medusa-hosting-docker-study
2. POS lane: Agilo POS fork (MIT) — medusa-nextjs-commerce-study; POS payments = manual plugin now, terminal roadmap later
3. Agent lane: per-tenant EVE agent (support/sales), co-hosted ~agent-size RAM, channels = storefront chat + optional Slack/Telegram (hermes-eve-cohosting-study; EVE has a Telegram integration channel too)

Hosting product = "e-commerce website + POS + AI staff" — the AI-staff part is what Medusa Cloud does not bundle, and it rides on Apache-2.0 licensed EVE.

Build sequencing (Ace lane, off this note)

1. Tenant template: Medusa prod compose + shared image pipeline (already specced).
2. EVE agent template: eve init, medusa.ts connection + 4 starter tools (products/carts/checkout/order-status) + 2 skills; HIL workflow skeleton; version-pinned @workflow/* line.
3. One demo tenant: storefront + chat + one skill live, gated on /health + /eve/v1/health both OK.
4. POS app pointing at the same tenant backend.

Sources

• Live probes (2026-10-13): vercel.com KB Medusa guide, Vercel Medusa template page, mindstudio posts, both YouTube videos — all 200.
• eve.dev /docs/guides/frontend/overview.md — useEveAgent confirmation; /docs/integrations — channels incl. Telegram; full corpus search — connections/ layout slot found in extension scaffold docs (extension/connections/api.ts).
• GitHub API: vercel/eve 5,541★ Apache-2.0; medusajs/medusa v2.21.2 MIT.
• hermes-eve-cohosting-study, medusa-hosting-docker-study, medusa-nextjs-commerce-study — sizing, licences, POS gaps.