@ebay-dt/bonfire-cli 0.1.0-alpha.4 → 0.1.0

package/templates/instance/context/PROTOTYPE.md

@@ -0,0 +1,108 @@
+## Prototype patterns and practices
+
+### General principles
+
+- Optimize for coherent, understandable prototype code—not production-scale architecture.
+- Prefer the simplest implementation that faithfully demonstrates the intended experience while preserving responsive behavior and repository conventions.
+- Do not over-engineer for speculative reuse, but do not concentrate an entire experience into one large component when clear local boundaries exist.
+- To minimize implementation friction, the `app.tsx` prototype entrypoint is intentionally a Client Component. Components imported by `app.tsx` generally do not need their own `'use client'` directive.
+
+### Prototype scope
+
+Keep every change inside the current prototype directory.
+
+Do not modify shared application infrastructure, other prototypes, repository configuration, dependencies, or the repository's local design-system components. If the prototype appears to require a shared change, stop and explain what is needed. Ask the user to have the repository owner make that change separately.
+
+If a design-system component needs different presentation:
+
+1. Prefer its supported props and variants.
+2. If necessary, apply a prototype-local CSS override.
+3. As a last resort, copy the component into the prototype and adapt the local copy.
+
+Do not alter the shared component to satisfy the needs of one prototype.
+
+### Design-system components
+
+Prefer existing design-system components over recreating equivalent controls from scratch.
+
+When Evo MCP provides component guidance, use that guidance for API and behavior. Prefer supported components from `@evo-web/react/...`; use direct `@ebay/ui-core-react/...` imports when Evo does not provide a suitable component.
+
+Evo component entrypoints load their own component CSS. The application root
+loads the published `@ebay-dt/bonfire-preset-ebay` stylesheet, which supplies
+shared Skin/Core UI CSS and theme tokens. Do not add direct `@ebay/skin` imports
+or duplicate global CSS for Evo components.
+
+Preserve the component's intended semantics and accessibility behavior. Do not replace a design-system component with custom markup solely to make styling easier. Import icons directly from the selected library:
+
+```ts
+import { EvoIconSettings16 } from '@evo-web/react/icons/settings-16'
+import { EbayIconArrowRight16 } from '@ebay/ui-core-react/icons/ebay-icon-arrow-right-16'
+```
+
+Keep prototype-specific composition helpers—such as item-tile price, media, or treatment mappings—inside the prototype that owns them. They may compose upstream components, but they must not become shared compatibility wrappers or substitute exports for the design-system packages.
+
+### Prototype organization
+
+Keep components focused and files easy to navigate. When a section has its own behavior, repeated markup, or substantial styling, extract it into a prototype-local component rather than allowing the main prototype file to grow indefinitely.
+
+Place extracted prototype-local components under the prototype's `components` directory:
+
+```
+components/
+  my-component/
+    index.tsx
+    styles.module.css
+```
+
+Keep a component's implementation, types, and styles together when they are only used by that component. Avoid extracting tiny one-use wrappers that make the interaction harder to follow.
+
+### Data fetching
+
+Use the published item hooks instead of fetching their backing API routes directly from prototype components.
+
+- Import `useItemsSearch`, `useInfiniteItemsSearch`, and `useItemById` from `@ebay-dt/bonfire-preset-ebay/data/items/react`.
+- Import normalized item types such as `SearchItem` and `ItemDetail` from `@ebay-dt/bonfire-preset-ebay/data/items`.
+- Mount `QueryProvider` from the `/data/items/react` entrypoint around the prototype's item UI. The application root does not supply a query provider; reuse an existing prototype-local provider rather than nesting another one.
+
+Before implementing item search, infinite loading, item selection, or item details, load and follow the `item-data` skill. Treat the installed package's exports, type declarations, and documentation as the canonical API. Gateway endpoints, credentials, and wire schemas belong to the instance server adapter, not prototype code.
+
+### Viewport sizing
+
+The sandbox exposes `--app-header-block-size` globally. It resolves to the development editor bar height when editor UI is enabled and to `0px` in production.
+
+When a prototype should fill the viewport without extending beneath the editor bar, account for it rather than hard-coding a header size:
+
+```css
+.prototype {
+  min-block-size: calc(100svh - var(--app-header-block-size));
+}
+```
+
+Use the variable for viewport-height calculations even though production has no editor bar; the same CSS will then resolve to the full viewport in production.
+
+### Visitor color-scheme controls
+
+Before implementing a visitor-facing Light/Dark control, load and follow the `color-scheme` skill.
+
+Controls must use `useColorSchemeToggle` from `@ebay-dt/bonfire-react` within the shared layout's `PrototypeEnvironment`. Check the prototype's current theme settings first; if they do not permit switching, get user confirmation before changing `metadata.json`. Never enable switching autonomously.
+
+Do not bypass the hook by accessing `localStorage`, calling `matchMedia`, or manipulating `data-color-scheme`. Keep server-rendered control markup hydration-stable and use a scheme-neutral accessible name.
+
+### Styling
+
+Keep prototype styles local. Prefer CSS Modules and existing design tokens over global selectors, hard-coded theme values, or changes to shared stylesheets.
+
+Use logical properties where practical and ensure layouts work at both narrow and wide viewport sizes. Account for the sandbox editor header in viewport-height layouts as described in the viewport-sizing section.
+
+Avoid `!important` unless it is required for a narrowly scoped design-system override. Keep overrides under a prototype-specific class so they cannot affect other prototypes.
+
+### Prototype validation
+
+Do not add automated tests for prototype-specific code unless the user requests them. Prototypes prioritize iteration speed over production-level test coverage.
+
+Before finishing:
+
+- Run the relevant check and lint commands, and format only files changed in the current prototype.
+- Confirm that all changes are confined to the current prototype directory.
+
+Do not spend substantial time repairing unrelated pre-existing failures outside the current prototype. Report them separately.

package/templates/instance/context/ROOT.md

@@ -0,0 +1,23 @@
+## Code Standards
+
+**When working in React:**
+
+- Prefer straightforward React composition and derived values over duplicated state or unnecessary effects.
+- Follow React 19 conventions. Treat `ref` as a regular prop instead of using `forwardRef`, and use `useEffectEvent` when an Effect needs stable access to non-reactive logic.
+- Keep state as close as practical to the components that use it.
+- Do not store values in state when they can be derived during rendering.
+
+**When working in TypeScript:**
+
+- Prefer inferred function return types, including for exported functions.
+- When a returned value should be checked against a contract, prefer `satisfies` so TypeScript validates the value without replacing its inferred type.
+- Add an explicit function return type only when inference cannot express the required contract or TypeScript requires one (e.g., type guards, recursive functions).
+- Avoid creating types that merely restate values TypeScript can already infer.
+- Treat type assertions as a last resort. Do not use `as any` to bypass type errors.
+
+**In general:**
+
+- Run the relevant check, format, and lint commands after making changes.
+- Do not start or restart the development server. Assume the user manages the running development environment.
+- When asking questions, ask them one at a time and offer a recommendation.
+- Use dependencies and utilities already available in the repository. Do not add a package unless the user explicitly requests or approves it.

package/templates/instance/context/hooks/block-env-reads.mjs

@@ -0,0 +1,144 @@
+#!/usr/bin/env node
+/**
+ * Block agent reads of .env files, except committed example templates.
+ * Allowed: .env.example, .env.local.example, .env.*.example
+ *
+ * Compatible with:
+ * - Cursor: beforeReadFile, beforeShellExecution, preToolUse
+ * - Claude Code: PreToolUse (Read / Bash)
+ *
+ * Reads hook JSON from stdin and prints a decision JSON to stdout.
+ */
+
+import path from 'node:path'
+
+const DENY_MESSAGE =
+  'Reading .env files is blocked by a project hook. Use an .env*.example template instead.'
+
+/** .env.example, .env.local.example, .env.development.local.example, etc. */
+function isAllowedEnvExampleBasename(basename) {
+  return /^\.env(\.[A-Za-z0-9_-]+)*\.example$/.test(basename)
+}
+
+function isBlockedEnvBasename(basename) {
+  if (isAllowedEnvExampleBasename(basename)) return false
+  // .env, .env.local, .env.development, etc. — not .environment
+  return /^\.env($|\.)/.test(basename)
+}
+
+function isBlockedEnvPath(filePath) {
+  if (!filePath || typeof filePath !== 'string') return false
+  return isBlockedEnvBasename(path.basename(filePath))
+}
+
+function commandTouchesBlockedEnv(command) {
+  if (!command || typeof command !== 'string') return false
+  // Match .env and .env.* tokens; allow .env.example / .env.*.example
+  for (const match of command.matchAll(
+    /(?<![A-Za-z0-9_-])\.env(?:\.[A-Za-z0-9_-]+)*/g
+  )) {
+    if (!isAllowedEnvExampleBasename(match[0])) return true
+  }
+  return false
+}
+
+function collectCandidatePaths(input) {
+  const paths = []
+  if (typeof input.file_path === 'string') paths.push(input.file_path)
+
+  const toolInput = input.tool_input
+  if (toolInput && typeof toolInput === 'object') {
+    if (typeof toolInput.file_path === 'string') paths.push(toolInput.file_path)
+    if (typeof toolInput.path === 'string') paths.push(toolInput.path)
+  }
+
+  return paths
+}
+
+function collectCandidateCommands(input) {
+  const commands = []
+  if (typeof input.command === 'string') commands.push(input.command)
+
+  const toolInput = input.tool_input
+  if (
+    toolInput &&
+    typeof toolInput === 'object' &&
+    typeof toolInput.command === 'string'
+  ) {
+    commands.push(toolInput.command)
+  }
+
+  return commands
+}
+
+function shouldDeny(input) {
+  for (const filePath of collectCandidatePaths(input)) {
+    if (isBlockedEnvPath(filePath)) return true
+  }
+  for (const command of collectCandidateCommands(input)) {
+    if (commandTouchesBlockedEnv(command)) return true
+  }
+  return false
+}
+
+function isClaudeStyle(input) {
+  return (
+    typeof input.hook_event_name === 'string' &&
+    /^[A-Z]/.test(input.hook_event_name)
+  )
+}
+
+function denyResponse(input) {
+  if (isClaudeStyle(input)) {
+    return {
+      hookSpecificOutput: {
+        hookEventName: input.hook_event_name || 'PreToolUse',
+        permissionDecision: 'deny',
+        permissionDecisionReason: DENY_MESSAGE,
+      },
+    }
+  }
+
+  return {
+    permission: 'deny',
+    user_message: DENY_MESSAGE,
+    agent_message: DENY_MESSAGE,
+  }
+}
+
+function allowResponse(input) {
+  if (isClaudeStyle(input)) {
+    return {}
+  }
+  return { permission: 'allow' }
+}
+
+async function main() {
+  const chunks = []
+  for await (const chunk of process.stdin) chunks.push(chunk)
+  const raw = Buffer.concat(chunks).toString('utf8').trim()
+
+  if (!raw) {
+    process.stdout.write(JSON.stringify({ permission: 'allow' }))
+    return
+  }
+
+  let input
+  try {
+    input = JSON.parse(raw)
+  } catch {
+    // Fail open on malformed input unless the host sets failClosed.
+    process.stdout.write(JSON.stringify({ permission: 'allow' }))
+    process.exit(0)
+  }
+
+  const response = shouldDeny(input)
+    ? denyResponse(input)
+    : allowResponse(input)
+  process.stdout.write(JSON.stringify(response))
+}
+
+main().catch(() => {
+  process.stdout.write(JSON.stringify({ permission: 'allow' }))
+  process.exit(0)
+})

package/templates/instance/context/mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "evomcp": {
+      "type": "http",
+      "url": "https://evomcp2.vip.qa.ebay.com/mcp"
+    }
+  }
+}

package/templates/instance/context/settings.json

@@ -0,0 +1,19 @@
+{
+  "enableAllProjectMcpServers": true,
+  "permissions": {
+    "allow": ["mcp__evomcp__*"]
+  },
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Read|Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"{{BONFIRE_REPO_ROOT}}\"/context/hooks/block-env-reads.mjs"
+          }
+        ]
+      }
+    ]
+  }
+}

package/templates/instance/context/skills/color-scheme/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: color-scheme
+description: Implement visitor-facing Light and Dark color-scheme controls in Design Sandbox prototypes using useColorSchemeToggle. Use when adding theme toggles, appearance controls, sun/moon controls, or prototype UI that lets visitors switch the active color scheme.
+---
+
+# Visitor color-scheme controls
+
+Use the published Bonfire hook for prototype-authored controls that let visitors switch between Light and Dark:
+
+```tsx
+'use client'
+
+import { useColorSchemeToggle } from '@ebay-dt/bonfire-react'
+
+export function ColorSchemeToggle() {
+  const { canToggle, toggle } = useColorSchemeToggle()
+
+  return (
+    <button
+      type="button"
+      aria-label="Toggle color scheme"
+      onClick={toggle}
+      disabled={!canToggle}
+    >
+      Toggle color scheme
+    </button>
+  )
+}
+```
+
+This is a client hook and must be called from a Client Component inside `PrototypeEnvironment`. The shared prototype layout supplies that boundary; do not add a second provider or independent theme state. The installed `@ebay-dt/bonfire-react` exports, type declarations, and README are the canonical API.
+
+## Check settings before implementation
+
+First inspect the prototype's `metadata.json`, especially:
+
+- `theme.defaultColorScheme`
+- `theme.allowedColorSchemes`
+
+If the current settings do not permit Light/Dark switching, ask the user to confirm that the settings should be changed. Do not modify `metadata.json` or any other prototype settings and do not enable switching autonomously.
+
+If settings remain unchanged and permit only the current outcome, `canToggle` is `false` and `toggle` is a no-op. The control should respect `canToggle`, normally by being disabled or omitted when the product requirement allows it.
+
+Theme-family switching is outside this hook's scope.
+
+## Hook contract
+
+`useColorSchemeToggle()` returns:
+
+- `colorScheme` — the currently rendered `'light' | 'dark'` scheme
+- `canToggle` — whether the configured settings allow switching
+- `toggle()` — switches the rendered scheme when allowed; otherwise a no-op
+
+The hook deliberately does not expose the internal System/default/override state. It automatically:
+
+- follows the configured prototype default;
+- resolves and tracks the OS preference when the default is System;
+- persists explicit visitor overrides per prototype;
+- returns to configured-default behavior when appropriate;
+- discards stored overrides after relevant prototype theme policy or instance registry changes; and
+- keeps multiple controls on the same page synchronized.
+
+Do not reimplement any of this behavior. In particular, do not read or write `localStorage`, call `matchMedia`, or manipulate `data-color-scheme` directly.
+
+## Hydration stability
+
+The server cannot read a persisted browser override or resolve the visitor's System preference. Keep the initial server-rendered control markup identical regardless of `colorScheme`.
+
+Do not conditionally render initial:
+
+- button text;
+- accessible names or other ARIA attributes; or
+- different icon elements
+
+from `colorScheme`. Doing so can produce a hydration mismatch even though the theme boundary is restored before paint.
+
+Use a scheme-neutral accessible name such as `Toggle color scheme`.
+
+If the visual icon must reflect the active scheme before hydration:
+
+1. Render both visual states with identical React markup on the server and client.
+2. Hide the inactive state with CSS scoped to the ancestor `data-color-scheme` attribute.
+3. Include the appropriate `prefers-color-scheme` CSS fallback for a System default.
+4. Hide decorative icons from assistive technology.
+
+The hook's `colorScheme` remains appropriate for client-side behavior that does not alter the initially hydrated markup.
+
+## Implementation checklist
+
+- Inspect theme settings before writing the control.
+- Ask before changing settings that do not currently allow switching.
+- Use `useColorSchemeToggle`; do not create independent theme state.
+- Respect `canToggle`.
+- Use a scheme-neutral accessible name.
+- Keep initial markup independent of `colorScheme`.
+- Verify Light and Dark visuals and keyboard operation.
+- Verify the page hydrates without warnings with a System default.
+- If this hook's contract or theme settings format changes, update this skill and the pointer in `context/PROTOTYPE.md`, then run `pnpm context:sync` from the repository root to regenerate `AGENTS.md` and the skill projections.

package/templates/instance/context/skills/item-data/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: item-data
+description: Implement item search, paginated or infinite item results, item selection, and item detail experiences in prototypes using the repository's supported React Query hooks. Use whenever a prototype needs to find, list, load more, paginate, select, or retrieve details for items.
+---
+
+# Item data
+
+Use the published item hooks rather than calling `/api/items` directly. They own request cancellation, validation, caching, retries, search normalization, and search debouncing.
+
+These are client hooks. Call them only from a Client Component (`'use client'`). The installed preset's exports, type declarations, and README are the canonical API; inspect them when behavior or types matter.
+
+## Hook inventory
+
+All three hooks are exported from `@ebay-dt/bonfire-preset-ebay/data/items/react`:
+
+| Need                         | Hook                     |
+| ---------------------------- | ------------------------ |
+| Numbered pages               | `useItemsSearch`         |
+| Load more / infinite results | `useInfiniteItemsSearch` |
+| Full details for one item    | `useItemById`            |
+
+Normalized types such as `SearchItem`, `ItemSearchPage`, and `ItemDetail` are exported from `@ebay-dt/bonfire-preset-ebay/data/items`. These are presentation contracts, not raw gateway response types.
+
+## Query provider
+
+The application root does not supply a React Query provider. Mount the preset's `QueryProvider` around the prototype's item UI, normally in its `page.tsx`:
+
+```tsx
+import { QueryProvider } from '@ebay-dt/bonfire-preset-ebay/data/items/react'
+import App from './app'
+
+export default function Page() {
+  return (
+    <QueryProvider>
+      <App />
+    </QueryProvider>
+  )
+}
+```
+
+Reuse an existing prototype-local provider rather than nesting another one. The provider owns one stable Query Client for its subtree and defaults to `refetchOnWindowFocus: false`. It accepts `clientConfig` for query defaults or a host-owned `client` when explicit cache ownership is needed.
+
+Gateway endpoints, GraphQL documents, credentials, wire schemas, and normalization belong to the instance's server adapter in `src/lib/items/server.ts` and `gateway-schemas.ts`. Do not copy those concerns into a prototype or modify shared infrastructure to implement an item UI.
+
+## Search behavior shared by both search hooks
+
+- Pass the visitor's raw query to the hook; do not add another debounce layer.
+- Queries are trimmed; subsequent query changes are debounced by 300 ms. A valid initial query can fetch immediately.
+- Search results use a 30-second stale time and retry once.
+- A trimmed query shorter than two characters is idle and does not fetch. Use `isIdle` to render search guidance instead of a loading or empty state.
+- `data` can temporarily contain the previous result while a new request is fetching. Compare `resultQuery` with `debouncedQuery` when UI behavior must apply only to the current query.
+- Render distinct idle, initial loading, error, empty, and populated states. Use the returned `error` and `refetch()` for retry UI.
+- Search result objects are summaries. Use `useItemById` when an experience needs complete item data.
+
+## Numbered pagination
+
+```tsx
+'use client'
+
+import { useItemsSearch } from '@ebay-dt/bonfire-preset-ebay/data/items/react'
+
+export function Results({ query, page }: { query: string; page: number }) {
+  const search = useItemsSearch(query, { page, pageSize: 20 })
+  const items = search.data ?? []
+  const isCurrentResult = search.resultQuery === search.debouncedQuery
+
+  // Render search.isIdle, search.isPending, search.isError, and items here.
+  // Use search.hasPreviousPage, search.hasNextPage, and search.totalPages
+  // for controls. Disable or label controls while !isCurrentResult.
+  return null
+}
+```
+
+`useItemsSearch(query, options?)` accepts:
+
+- `page` — one-based, defaults to `1`
+- `pageSize` — defaults to `20`; the API supports at most `50`
+
+In addition to standard React Query fields, it returns `data`, `page`, `pageSize`, `resultPage`, `total`, `totalPages`, `hasPreviousPage`, `hasNextPage`, `debouncedQuery`, `resultQuery`, and `isIdle`.
+
+Keep page state in the component or URL. Reset it to page 1 when a current query result shows that the requested page is out of range. The API's maximum offset is 10,000, so do not offer pages beyond that boundary.
+
+## Infinite results
+
+```tsx
+'use client'
+
+import { useInfiniteItemsSearch } from '@ebay-dt/bonfire-preset-ebay/data/items/react'
+
+export function Results({ query }: { query: string }) {
+  const search = useInfiniteItemsSearch(query, { pageSize: 20 })
+  const items = search.data ?? []
+
+  // Render items, then call search.loadMore() from a button or observer.
+  // Disable the trigger while search.isLoadingMore or when !search.hasMore.
+  return null
+}
+```
+
+`useInfiniteItemsSearch(query, options?)` accepts `pageSize`, defaulting to `20`. It returns a deduplicated flat `data` array plus `total`, `loadMore`, `hasMore`, `isLoadingMore`, `debouncedQuery`, `resultQuery`, and `isIdle`, along with standard infinite-query fields.
+
+Prefer an explicit, accessible “Load more” button unless the prototype specifically calls for automatic infinite scrolling. Do not call `loadMore` when `hasMore` is false or while `isLoadingMore` is true.
+
+## Item details
+
+```tsx
+'use client'
+
+import { useItemById } from '@ebay-dt/bonfire-preset-ebay/data/items/react'
+
+export function ItemDetails({ itemId }: { itemId: string | null }) {
+  const detail = useItemById(itemId)
+
+  if (!itemId) return null
+  if (detail.isPending) return <p role="status">Loading item details…</p>
+  if (detail.isError) {
+    return (
+      <div role="alert">
+        <p>{detail.error.message}</p>
+        <button type="button" onClick={() => detail.refetch()}>
+          Try again
+        </button>
+      </div>
+    )
+  }
+
+  return detail.data ? <h2>{detail.data.title}</h2> : null
+}
+```
+
+`useItemById(itemId, options?)` accepts a string, `null`, or `undefined`. It does not fetch without an ID. Options are:
+
+- `enabled` — defaults to `true`; combined with the presence of an ID
+- `staleTime` — defaults to 30 seconds
+
+Use the selected search item's summary as immediate fallback content where helpful, then replace or augment it with detail data. Do not assume summary-only fields and detail fields are identical.
+
+## Maintaining this skill
+
+Whenever the supported package version or item-data API changes:
+
+1. Update the hook inventory and relevant guidance here.
+2. Keep examples aligned with the published exports and return shapes.
+3. Keep the short pointer in `context/PROTOTYPE.md` accurate, then run `pnpm context:sync` from the repository root to regenerate `AGENTS.md` and the skill projections.
+4. Prefer adding related item hooks to this skill rather than creating a skill for each hook.

package/templates/instance/context/skills/setup-evomcp/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: setup-evomcp
+description: Set up the hosted Evo MCP server for Cursor or Claude Code in the design sandbox. Registers the unauthenticated remote endpoint for prototype-only sessions and verifies that its design-system tools are available. Use when Evo MCP tools are missing, when onboarding to the design sandbox, or when the user mentions setting up evomcp, Evo MCP, or Evo design system tools.
+disable-model-invocation: true
+---
+
+# Set up Evo MCP
+
+Evo MCP is hosted at `https://evomcp2.vip.qa.ebay.com/mcp`. It does not require
+user authentication, a local `evomcp` checkout, Yarn, or a local server build.
+
+## Compatibility
+
+- **Claude Code:** the committed repo `.mcp.json` is sufficient. Claude Code
+  discovers it through the git root, including from a prototype directory.
+  Approve the project server if prompted, then verify its tools.
+- **Cursor:** prototype directories are opened as workspace roots, so the repo
+  `.mcp.json` is not visible to those sessions. Register the same definition in
+  Cursor's global MCP config using the workflow below.
+
+## Cursor workflow
+
+```
+- [ ] Step 1: Locate the sandbox repo
+- [ ] Step 2: Register the hosted server
+- [ ] Step 3: Approve or enable it in Cursor
+- [ ] Step 4: Verify the tools
+```
+
+### Step 1: Locate the sandbox repo
+
+Find `design-sandbox-next`, which contains `context/mcp.json`, the canonical
+MCP definition.
+
+### Step 2: Register the hosted server
+
+```bash
+cd <design-sandbox-next> && pnpm context:install
+```
+
+This merges the committed HTTP server definition into `~/.cursor/mcp.json` and
+installs the shared skills. No token or other secret is written to disk.
+
+### Step 3: Approve or enable it
+
+If Cursor does not show the server, run `Cmd+Shift+P` → **View: Open MCP
+Settings** and toggle `evomcp` on.
+
+A server discovered only by editing the config file may initially be disabled.
+Installation is once per machine because the global config gives the hosted
+server a stable identity from every prototype folder.
+
+### Step 4: Verify
+
+Confirm the `evomcp` entry points to:
+
+```text
+https://evomcp2.vip.qa.ebay.com/mcp
+```
+
+Then list or call the server's tools. A working connection exposes
+`search-components`, `search-tokens`, `get-token`, and `search-icons`, among
+others. If the endpoint is reachable but Cursor does not show the tools, reload
+the Cursor window and check MCP settings again.
+
+## Troubleshooting
+
+- The endpoint uses Streamable HTTP and expects POST requests. A GET response
+  saying SSE streams are unsupported does not indicate an authentication
+  failure.
+- No Evo-specific login is required. Do not add authorization headers or ask
+  the user to generate a token.
+- If the host cannot be reached, check eBay network/BPN connectivity and retry.

package/templates/instance/next.config.ts

@@ -0,0 +1,10 @@
+import type { NextConfig } from 'next'
+
+const nextConfig: NextConfig = {
+  /* Bonfire discovers prototype metadata from the filesystem at request time. */
+  outputFileTracingIncludes: {
+    '/*': ['./src/app/(prototypes)/**/metadata.json'],
+  },
+}
+
+export default nextConfig

package/templates/instance/src/actions/agents.ts

@@ -0,0 +1,15 @@
+'use server'
+
+import type {
+  OpenInAgentInput,
+  OpenInClaudeCodeInput,
+} from '@ebay-dt/bonfire-core'
+import { bonfire } from '@/bonfire'
+
+export async function openInCursor(input: OpenInAgentInput) {
+  return bonfire.prototypes.agents.openInCursor(input)
+}
+
+export async function openInClaudeCode(input: OpenInClaudeCodeInput) {
+  return bonfire.prototypes.agents.openInClaudeCode(input)
+}