evomeme 0.1.9 → 0.1.10-beta.13

package/dist/skills/en-US/evomeme-game-maker/SKILL.md

@@ -0,0 +1,288 @@
+---
+name: evomeme-game-maker
+description: Guide the Agent in creating evomeme mobile-platform games, applying portrait touch controls, project structure, public/config.json, asset hosting, and production build requirements during development, and using platform capabilities such as publishing, covers, native capabilities, and login recovery as needed by the game. Use when creating, migrating, extending, or publishing mobile games for evomeme.
+---
+
+# evomeme Mobile Game Creation
+
+## Goal
+
+Guide the Agent in creating portrait touch-control mobile games that meet evomeme platform requirements, and in selecting corresponding platform capabilities during development according to current needs.
+
+**Concrete game development plan**: when formulating, breaking down, or updating a concrete game development plan, MUST refer to the `game-maker` development skill. This skill provides only evomeme platform-specific requirements for games. If the user needs to publish to the EvoMeme platform, the game MUST meet the requirements in this skill.
+
+**Required platform UI and responsive-layout reading**: When developing any game intended to run, launch, or be published on evomeme, MUST read and follow [`evomeme-ui`](../evomeme-ui/SKILL.md). Before designing or coding game UI or responsive adaptation, the Agent MUST load that skill and follow its container sizing, safe-area rules, and test matrix.
+
+## Platform Requirements
+
+### Game Form
+
+The evomeme platform supports ONLY portrait mobile games. Developed games MUST adapt to portrait UI layout and support touch controls.
+
+#### Portrait Full-Screen Adaptation
+
+The mobile gameplay interface MUST adapt to the different portrait WebView sizes and aspect ratios provided by the host, and always fill the actual game container. "Full-screen" means the available WebView area; MUST NOT lay out the game using the phone's full screen height or subtract host bars and safe areas again. Follow [`evomeme-ui`](../evomeme-ui/SKILL.md) for implementation and acceptance checks:
+
+- MUST NOT use fixed-aspect-ratio containers, black borders, top/bottom or left/right letterboxing, or similar methods to maintain the design-draft ratio.
+- The game root container, render canvas, and background MUST cover the entire WebView game area; the page MUST NOT produce uncovered areas due to default margins, fixed dimensions, or parent-container constraints.
+- When the screen aspect ratio differs from the design draft, complete adaptation through responsive layout, camera scaling, background `cover`, or expandable regions that allow cropping; MUST NOT uniformly shrink the entire gameplay image and leave black borders.
+- HUD, buttons, and key interaction content MUST lay out dynamically according to the actual container dimensions. Internal game padding is allowed, but MUST NOT subtract phone safe areas already handled by the host or shrink the coverage of the game image or background.
+- The Web page SHOULD set the correct mobile viewport and maintain a complete `100%` height chain through `html`, `body`, the app root node, and the game container. When the container changes size, update the layout, rendering dimensions, and input mapping together.
+- After development, MUST verify across multiple portrait sizes and aspect ratios: gameplay area covers the full screen, no black borders, no page scrollbars, and key UI is not clipped or obscured.
+
+### Demo Image Assets
+
+When making an evomeme game Demo, all required game image assets MUST be obtained through image generation and actually integrated:
+
+- MUST NOT use any SVG assets, including SVG files, inline SVG, and `data:image/svg+xml`.
+- MUST NOT use Canvas, Phaser, or CSS lines, geometric outlines, or procedural drawing to impersonate game image assets such as characters, scenes, props, icons, or effects.
+- MUST NOT use large solid-color blocks or solid-color backgrounds as formal game assets or visual placeholders.
+- Backgrounds, characters, enemies, props, tiles, decorations, icons, visual effects, and other image assets required by the Demo MUST use image generation. Code work may proceed in parallel with image generation, but the required generated images MUST be integrated before the first visible delivery.
+- If assets are not yet complete, continue generating or reduce the Demo asset scope. MUST NOT temporarily substitute SVG, line drawing, or large solid colors.
+- The first batch of generated images may be used as iterative assets, then gradually replaced later while keeping asset configuration and loading interfaces stable.
+
+### Project Structure
+
+The submitted game project contains the following files and directories:
+
+```text
+/
+├── dist/
+├── public/
+│   └── config.json
+├── src/
+└── index.html
+```
+
+- `dist/`: stores the latest production build artifacts and is submitted together with the game project.
+- `public/config.json`: centrally records binary asset links used by the game and other runtime configuration.
+- `src/`: stores the main development code.
+- `index.html`: serves as the web entry for the game project.
+
+#### Code Dependencies and Publication Paths
+
+**Mandatory delivery gate:** The game task is considered complete ONLY when the production build command (usually `npm run build`) completes with exit code `0`, generates a real and non-empty `dist/` containing `dist/index.html` and all referenced local files, and passes the post-build path checks in this section. Merely modifying source code, having the development server run, having a normal screenshot, or guessing that it "should build" MUST NOT be used as delivery results. If any condition is not met, MUST continue fixing, rebuild, and recheck.
+
+The final `dist/` may be deployed under any URL subpath and is not guaranteed to be at the domain root. All local runtime references MUST be relative to the current document or build artifact:
+
+- In-project code dependencies use `./` or `../`; MUST NOT write local-machine absolute paths, workspace absolute paths, `file://` addresses, or source URLs that can only be resolved by the development server.
+- Local `src`, `href`, `poster`, and `srcset` in HTML, local `url(...)` in CSS, and JavaScript `fetch()`, dynamic `import()`, Worker, audio, and other local resource addresses MUST use `./...` or equivalent relative paths.
+- Any local root-absolute path starting with a single `/`, such as `/assets/...`, `/asset/...`, `/config.json`, or `/src/...`, is strictly forbidden. They should be written as `./assets/...`, `./asset/...`, `./config.json`, `./src/...`, respectively.
+- MUST NOT reconstruct root-absolute local addresses through `location.origin`, `new URL(path, location.origin)`, or other string-concatenation methods.
+- Publicly accessible `http://` and `https://` remote URLs are not restricted by the local relative-path rules.
+- When modifying an existing project, preserve architecture unrelated to the task, but as long as the final `dist/` still contains root-absolute local references, MUST make the minimal fix and MUST NOT deliver.
+
+##### Vite Base (Mandatory)
+
+New Vite projects MUST create a Vite configuration and explicitly set `base: './'`; MUST NOT rely on Vite's default value `/`. React project example:
+
+```js
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+
+export default defineConfig({
+  plugins: [react()],
+  base: './',
+});
+```
+
+Other build tools MUST set an equivalent relative publication base path.
+
+##### Complete `index.html` for New React + Vite Projects (Mandatory)
+
+New React + Vite projects MUST use the following source entry format. JavaScript projects use `./src/main.jsx`; TypeScript projects replace ONLY that with `./src/main.tsx`. The entry is forbidden from being written as `/src/main.jsx` or `/src/main.tsx`.
+
+```html
+<!doctype html>
+<html lang="zh-CN">
+<head>
+  <meta charset="UTF-8" />
+  <meta
+    name="viewport"
+    content="width=device-width,initial-scale=1,viewport-fit=cover,user-scalable=no"
+  />
+  <meta name="theme-color" content="#000000" />
+  <title>Game Name</title>
+</head>
+<body>
+  <div id="root"></div>
+  <script type="module" src="./src/main.jsx"></script>
+</body>
+</html>
+```
+
+CSS SHOULD be imported from the entry module through a relative path such as `import './style.css'`; DO NOT prewrite or guess hashed build filenames in source `index.html`. The `dist/index.html` after Vite build MUST use relative build asset paths, for example:
+
+```html
+<script type="module" crossorigin src="./assets/index-HASH.js"></script>
+<link rel="stylesheet" crossorigin href="./assets/index-HASH.css">
+```
+
+`HASH` represents the hash actually generated by Vite and MUST NOT be hard-coded.
+
+##### `dist/` Integrity and Path Checks (Blocks Delivery)
+
+After every production build completes and before announcing success, MUST directly check `dist/index.html` and the JavaScript, CSS, and other text artifacts it references:
+
+1. Confirm the build command exit code is `0`.
+2. Confirm `dist/` truly exists and is non-empty, and confirm `dist/index.html` exists.
+3. Parse or check one by one the local references in `dist/index.html`, and confirm each target file truly exists inside `dist/`.
+4. Scan `dist/index.html`, built JavaScript, and CSS. MUST NOT contain local-resource references in `src="/`, `src='/`, `href="/`, `href='/`, `poster="/`, `poster='/`, `url(/`, `fetch('/`, `fetch("/`, `import('/`, `import("/`, `new Worker('/`, `new Worker("/`, or equivalent root-absolute forms.
+5. Explicitly check and forbid `/assets/...`, `/asset/...`, `/config.json`, `/src/...`; they MUST be changed to `./assets/...`, `./asset/...`, `./config.json`, `./src/...`, or another correct relative path.
+6. Check that `dist/` contains no runtime dependencies on `src/`, `public/`, the project root, workspace files, `localhost`, the Vite development server, `.ts`, `.tsx`, or other unbuilt source.
+7. If any violating reference, missing file, or incomplete artifact is found, the build is judged invalid; after fixing, MUST run the production build again and recheck from step 1. MUST NOT skip rechecking just because the build command previously exited with code `0`.
+
+`dist/` MUST be a complete runtime directory that can be deployed independently. `dist/index.html`, built JavaScript, CSS, and configuration may depend ONLY on files inside `dist/` or public remote URLs. Images, videos, audio, fonts, models, and other binary files are forbidden inside `dist/`; these assets MUST be integrated through public URLs. MUST NOT bypass the build by copying source code into `dist/`; source dependencies MUST be correctly resolved and bundled in the production build.
+
+Before publication, MUST also start a preview with `dist/` as the static service root, and verify startup, resource loading, and the complete core flow at that address. The development server may be used for development, but MUST NOT be used as publication acceptance evidence.
+
+#### `/public/config.json` Rules
+
+`/public/config.json` is the external runtime configuration file for the game. After build, it is output unchanged as `/dist/config.json`.
+
+##### Storage Rules
+
+1. Write all user-adjustable colors, gameplay parameters, balance values, and asset URLs to `/public/config.json` or `game/content`.
+2. Game code reads configuration through `fetch("./config.json")` or the project's wrapped `loadConfig()`.
+3. Keep `/public/config.json` as a runtime external file; code in `src` accesses configuration only through runtime loading.
+4. Centralize user-adjustable values in a single configuration source, and have React, Phaser, and CSS use the same configuration data.
+
+##### Visible Parameters
+
+Keys that do not start with `_` are exposed for user editing and remain flat:
+
+```json
+"player_speed": {
+  "value": 220,
+  "type": "int",
+  "label": "Move Speed",
+  "max": 400,
+  "min": 50
+}
+```
+
+Rules:
+
+- `type` values are `int`, `float`, `color`, `bool`, `string`, `audio`, `image`, `video`.
+- `label` uses the user's language and is no longer than 10 characters.
+- `max` and `min` are dedicated to `int` and `float` types.
+- `type: "color"` uses a hexadecimal color string.
+- `type: "image"` MUST declare `image_type: "Asset"`.
+- `image_type: "Asset"` MUST additionally declare `size`, in the format `"widthxheight"`, for example `"1440x2560"`.
+
+##### Parameter Type Examples
+
+Visible parameters in `/public/config.json` are written according to the following structure. Actual projects choose parameter types and keys as needed, and keep the same schema when generating configuration.
+
+```json
+{
+  "_game_name": "Example Game",
+  "_config_version": 1,
+  "move_speed": {
+    "value": 220,
+    "type": "int",
+    "label": "Move Speed",
+    "min": 50,
+    "max": 400
+  },
+  "gravity_scale": {
+    "value": 1.2,
+    "type": "float",
+    "label": "Grav Scale",
+    "min": 0.2,
+    "max": 3
+  },
+  "theme_background_color": {
+    "value": "#10131f",
+    "type": "color",
+    "label": "BG Color"
+  },
+  "enable_shake": {
+    "value": true,
+    "type": "bool",
+    "label": "Shake"
+  },
+  "start_button_text": {
+    "value": "Start Game",
+    "type": "string",
+    "label": "Start Text"
+  },
+  "bgm_main": {
+    "value": "https://example.com/bgm.mp3",
+    "type": "audio",
+    "label": "BGM"
+  },
+  "image_background": {
+    "value": "https://example.com/background.png",
+    "type": "image",
+    "image_type": "Asset",
+    "size": "1440x2560",
+    "label": "BG Image"
+  },
+  "image_player": {
+    "value": "https://example.com/player.png",
+    "type": "image",
+    "image_type": "Asset",
+    "size": "1024x1024",
+    "label": "Character"
+  },
+  "video_intro": {
+    "value": "https://example.com/intro.mp4",
+    "type": "video",
+    "label": "Intro Vid"
+  }
+}
+```
+
+When generating official project configuration:
+
+- `value` for `audio`, `image`, and `video` uses real URLs. When an image is generated asynchronously upstream, a URL briefly returning 404 does not mean the asset is invalid.
+- `image` types specify size metadata. `Asset` uses `size`, allowing Codex to infer display dimensions when it cannot read the real image.
+- `string` is used for user-editable copy, theme names, asset keys, and other short text.
+- `bool` is used for switches, with values `true` or `false`.
+- `int` uses integers, and `float` can use decimals; both include `min` and `max`.
+- Internal fields such as `_game_name`, `_config_version`, and `_comment` store internal values directly and do not use the visible-parameter schema.
+
+##### Invisible Parameters
+
+Keys starting with `_` are used for internal configuration, asset mappings, version numbers, and debug switches, and are not exposed for user editing.
+
+### File Submission
+
+The submitted file collection consists of UTF-8 text files. Binary assets such as images, audio, video, fonts, models, and archives are integrated into the game through evomeme TOS links and referenced through `public/config.json`. The corresponding local binary file paths are recorded in `.evomemeignore`.
+
+`dist/` is always within submission scope and contains the latest production build after asset-link replacement is complete.
+
+### Pre-Publication Check
+
+Check the following ONLY when preparing to submit or publish the game:
+
+- [ ] The game uses a portrait UI layout and supports touch controls.
+- [ ] `evomeme-ui` has been read and followed, including validation at game container sizes of 375×524, 402×646, and 412×732 and during a runtime size change.
+- [ ] Across different portrait sizes and aspect ratios, the gameplay interface fills the host WebView without black borders or uncovered areas. Native bars and safe areas are not deducted twice, and key UI remains visible and operable.
+- [ ] The Demo contains no SVG, line drawing, or large solid-color game assets; all required game images have been obtained through image generation and actually integrated.
+- [ ] The root directory contains `dist/`, `public/config.json`, `src/`, and `index.html`.
+- [ ] `public/config.json` parses, conforms to the configuration schema, and is output unchanged as `dist/config.json` after build.
+- [ ] `public/config.json` records binary assets used by the game as public links.
+- [ ] Local binary file paths have been added to `.evomemeignore`.
+- [ ] `.evomemeignore` keeps `dist/` within submission scope.
+- [ ] `dist/` comes from the latest production build after asset-link replacement is complete.
+- [ ] The production build command completes with exit code `0`, and `dist/` is non-empty and contains `dist/index.html`.
+- [ ] New Vite projects explicitly set `base: './'`; source `index.html` uses `./src/main.jsx` or `./src/main.tsx`.
+- [ ] Every local file referenced in `dist/index.html` truly exists inside `dist/`.
+- [ ] `dist/index.html` and its referenced JavaScript and CSS have been scanned; there is no `src="/`, `href="/`, `url(/`, `fetch('/`, `fetch("/`, `/assets/`, `/asset/`, `/config.json`, `/src/`, or equivalent root-absolute local reference.
+- [ ] The build uses a relative publication base path; runtime configuration and assets use `./...` or equivalent relative URLs, do not depend on the domain root path, and do not reconstruct the root path through `location.origin`.
+- [ ] `dist/` can be deployed independently, and it has no runtime dependencies on `src/`, `public/`, the project root, `localhost`, development server, or unbuilt source.
+- [ ] Preview has been completed with `dist/` as the static service root, and the game can start, load resources, and run through the core flow.
+- [ ] The submitted file collection contains only UTF-8 text files.
+- [ ] The publication process follows `evomeme-cloud-fs`.
+
+## Platform Capabilities
+
+Select required capabilities according to the current task. Each capability takes effect independently:
+
+- **Binary asset hosting**: when local images, audio, video, fonts, or models need to be converted to public links, load and follow [`evomeme-tos-upload`](../evomeme-tos-upload/SKILL.md). The obtained `asset_url` can be written to `public/config.json`, and local binary file paths can be written to `.evomemeignore`.
+- **Game publication**: when preparing the workspace, checking submission contents, or publishing the game, load and follow [`evomeme-cloud-fs`](../evomeme-cloud-fs/SKILL.md).
+- **Game cover**: when adding a game cover or providing `cover_url`, load and follow [`evomeme-cover`](../evomeme-cover/SKILL.md).
+- **Mobile native capabilities**: when the game needs to use camera, album, microphone, gyroscope, vibration, or other host capabilities, load and follow [`evomeme-native-bridge-sdk`](../evomeme-native-bridge-sdk/SKILL.md).
+- **Login recovery**: after an evomeme operation returns a login or authentication error, load and follow [`evomeme-login`](../evomeme-login/SKILL.md), then continue the original operation after login is restored.

package/dist/skills/en-US/evomeme-game-maker/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "evomemeGame Maker"
+  short_description: "Create portrait touch-control mobile games that follow platform specifications, with project configuration and publication adaptation complete"
+  default_prompt: "Use $evomeme-game-maker to create a portrait touch-control mobile game for me, including the required project configuration, asset integration, and platform adaptation."

package/dist/skills/en-US/evomeme-login/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: evomeme-login
+description: Restore evomeme authentication after an evomeme_* MCP or init login / token error. Use ONLY after authentication has already failed; DO NOT load preventively before calling business tools.
+---
+
+# evomeme Login Recovery
+
+| Tool | Actual action and result | When to use |
+| --- | --- | --- |
+| `evomeme_check_login` (Check Login Status) | Check existing credentials and return login status; creates no asset or project files. | After authentication has failed, follow the flow below to determine whether credentials need recovery. |
+| `evomeme_login` (Log In) | Start browser login, save credentials locally on success and return the login result. | Credentials are missing, expired or invalid and tool authentication needs recovery. |
+
+## When to Use (Gate)
+
+Load this skill and execute the flow below **ONLY after a login / authentication-related failure has already occurred**.
+
+Typical triggers (when a tool returns `isError` or the error body contains the following meanings):
+
+- token invalid or expired (business error code **40100**, text such as "token invalid" or "please log in again")
+- login session timed out or was rejected (**40010**, text such as "login session has expired or was rejected")
+- MCP / init explicitly says not logged in, credentials are invalid, or login again is required
+- `evomeme_login` itself fails (timeout, user did not complete login in the browser, etc.)
+
+**DO NOT** load this skill or proactively call the login tool in the following situations:
+
+- "preventively checking login" before normal startup, image generation, upload, submission, or model creation
+- proactively running login once when the user has not encountered any authentication error
+- treating login as a routine step in the game creation flow
+
+For normal business work, call the `evomeme_*` tools directly; the client will handle credentials itself when needed. Use this skill ONLY after an error occurs.
+
+## Goal
+
+Guide the user to complete evomeme re-login in the system browser so subsequent `evomeme_*` tools can continue to be used, then **return to the original failed business operation** and retry it once.
+
+## Guide the User to Log In Again (Execute in Order)
+
+### 1. Explain the Situation to the User (Say It Before Acting)
+
+Tell the user briefly in natural language, for example:
+
+> The evomeme cloud operation just failed because the login credentials are invalid. Next we need to log in again: the system will open a browser. Please complete login on the page, then come back here and I will continue the previous operation.
+
+MUST explain three points:
+
+1. **Why**: the previous operation was interrupted due to login/authentication failure  
+2. **What will happen**: the **system default browser** will open, and the user needs to complete login on the page  
+3. **What happens afterward**: after login succeeds, the step that just failed will be retried  
+
+DO NOT call `evomeme_login` before completing the explanation above.
+
+### 2. (Optional) Confirm Current Status
+
+If the error message is not clear enough, first call the read-only tool **`evomeme_check_login`** (**does not** open the browser):
+
+- Returns "logged in" -> this may be a transient/other error; tell the user the original error text, DO NOT force-open the browser again, and you may directly retry the original business tool once  
+- Returns "not logged in" or "credentials invalid" -> continue to step 3  
+
+### 3. Start Re-Login
+
+Call **`evomeme_login`** (no arguments).
+
+- It will force the full browser login flow and overwrite `~/.evomeme/auth.json`  
+- Ask the user to complete login on the opened page; the Agent waits for the tool to return  
+
+### 4. Branch by Result
+
+**Login succeeded**
+
+1. Confirm briefly: "Login is complete."  
+2. **Immediately retry** the business MCP that just failed (image generation / upload / submission / model, etc.); DO NOT stop at "logged in".  
+3. If the original flow requires delivery wrap-up, continue the original flow after the retry succeeds, and complete the necessary `evomeme_submit_game_code` according to `../evomeme-cloud-fs/SKILL.md`.
+
+**Login failed** (timeout, rejection, network error, etc.)
+
+1. Show the user the **exact original error text** returned by the tool  
+2. Ask the user to confirm whether it is convenient to try again (for example, whether the browser was blocked or whether they clicked reject)  
+3. After the user agrees, tell them "the browser will open again", then call `evomeme_login` again  
+4. **DO NOT** loop browser popups without telling the user and getting confirmation  
+
+## Tool Notes
+
+| Tool | Purpose | Opens Browser? |
+| --- | --- | --- |
+| `evomeme_check_login` | Read-only check of whether local credentials are still valid | No |
+| `evomeme_login` | Force browser login and write `~/.evomeme/auth.json` | Yes (MUST tell the user before calling) |
+
+## Non-Goals
+
+- Does not replace `npx -y evomeme@latest init` (workspace ignore rules / copying skills, etc. still follow `../evomeme-cloud-fs/SKILL.md`)
+- Does not expand game planning, image generation, or submission flows inside this skill; after login recovery, return to the original task skill and continue
+- Does not treat every "network connection failed" as a login problem; use this skill ONLY when the error clearly points to authentication / login
+
+## References
+
+- Main entry: `../game-director/SKILL.md`
+- Cloud file system (init / submission / upload): `../evomeme-cloud-fs/SKILL.md`

package/dist/skills/en-US/evomeme-login/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "evomemeLogin"
+  short_description: "Guide re-login after a cloud operation has a login or credential error, then continue the original task"
+  default_prompt: "Use $evomeme-login to restore the login state that just failed, then continue the original cloud operation after login completes."
+
+policy:
+  allow_implicit_invocation: false

package/dist/skills/en-US/evomeme-mcp/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: evomeme-mcp
+description: Install, start, update, or troubleshoot evomeme MCP. Agents must read this skill when configuring evomeme MCP or investigating startup failure, closed connections, missing tools, or ineffective updates. Restore the MCP connection and verify tool visibility; use asset skills for normal generation.
+---
+
+# evomeme MCP startup and troubleshooting
+
+## Purpose and when to use
+
+Guide the agent through configuring the IDE to launch evomeme, diagnosing connection failures, and verifying its tool list. The results are an installed or repaired IDE MCP configuration and an evidence-based connection status. This skill itself does not generate images, videos, or projects.
+
+- Read this skill when the user requests MCP installation, startup, or updates, or when tools are missing or the process cannot start.
+- Normal asset calls do not require repeated installation or login checks. If a tool already returned a business error, diagnose that error category first.
+- `init` copies this skill into the workspace in the selected language. `install` configures MCP only and does not copy skills. Preserve existing skill names.
+
+## Terms
+
+- **MCP (Model Context Protocol)**: the protocol between an IDE agent and an external tool server. evomeme is a local server process exposing `evomeme_*` tools.
+- **stdio**: the IDE starts a child process and exchanges protocol messages through standard input and output. evomeme MCP does not need an HTTP listening port. Its backend API URL is not an MCP connection address; ordinary log text must not enter MCP standard output.
+- **Launcher**: the `command` executable and the `args` array of separate arguments in the config. Node.js runs JavaScript, npm manages packages, and npx / npm exec obtains and runs a package. The Windows installer may use absolute Node and npm script paths.
+- **initialize / tools/list**: the protocol handshake and discovery of available tools. Success proves that child process can communicate, not that the IDE loaded the same configuration or that cloud generation works.
+- **Configuration and workspace**: the MCP config tells the IDE how to launch the server; the workspace contains the game project. A skill is documentation for the agent. Copying it does not start MCP.
+
+## Install and start
+
+Supported targets are `codex`, `cursor`, `claude` (Claude Code), `workbuddy`, and `trae` (this installer's default is Trae SOLO China). Identify the user's actual IDE, configuration file, and release channel first.
+
+```powershell
+npx -y evomeme@latest install --ide cursor
+```
+
+The installer first starts a temporary MCP process for handshake and tool-list checks, then merges the IDE configuration. Other MCP entries are preserved. Before changing an existing file, it backs up the file to the same path with `.evomeme-cli.bak.latest` appended. The existing `evomeme` entry is refreshed.
+
+For a custom configuration location, specify the **full configuration file path**:
+
+```powershell
+npx -y evomeme@latest install --ide cursor --config-path "D:\MyConfig\mcp.json"
+npx -y evomeme@latest install --ide codex --config-path "D:\MyConfig\config.toml"
+```
+
+- Select the file the IDE actually reads, not its executable directory or executable. Moving the IDE program does not necessarily move its configuration.
+- Absolute paths and paths relative to the current terminal directory are supported. Quote paths containing spaces. Missing files and parent directories are created; this does not change how the IDE selects its config file.
+- `--config-path` requires exactly one IDE; run separate commands for multiple IDEs. Omit it to retain the default path. The override applies only to this invocation, so supply it again on later reinstalls.
+- Codex writes TOML; the other installers write JSON. Do not target the same file with installers for different formats.
+- Before reinstalling, inspect the existing evomeme launcher and environment. Preserve the user's pinned version/local package supplied through `--package` and custom backend supplied through `--api-base-url`. Omitting the backend option refreshes the entry to use the packaged default backend.
+
+After installation, restart the IDE or reconnect its MCP server, then verify that the IDE lists the required `evomeme_*` tools. A successful config write alone does not prove the IDE is connected.
+
+The server entry must run the package with **no subcommand**, without `install`, `init`, or `version`. Running the following in a terminal waits for protocol input; silence alone is not a hang. Normally let the IDE manage this process:
+
+```powershell
+npx -y evomeme@latest
+```
+
+## init and skill distribution
+
+To initialize a workspace or refresh its skills, run this in the intended project:
+
+```powershell
+npx -y evomeme@latest init --ide cursor
+```
+
+`init` validates login, creates or reuses a cloud project binding, establishes ignore rules, and copies packaged skills. It is not a connection-only check. Omitting `--ide` copies to every supported IDE's workspace skill directory. The current package replaces matching packaged skills, adds new skills, and preserves other user skills.
+
+Skill locations: `.codex/skills/evomeme-mcp/` for Codex, `.cursor/skills/evomeme-mcp/` for Cursor, `.claude/skills/evomeme-mcp/` for Claude Code, `.codebuddy/skills/evomeme-mcp/` for WorkBuddy, and `.trae/skills/evomeme-mcp/` for Trae. The MCP `--config-path` option does not change these workspace skill directories.
+
+## When something fails
+
+Read the relevant sections of [Troubleshooting](references/troubleshooting.md). First collect the actual config path, launcher, running process version, IDE MCP error, and today's logs. Validate once after each evidence-based fix. When the same error repeats, stop blind reinstalls and report the confirmed cause and missing evidence.
+
+Use handshake and tool discovery to verify connectivity; do not launch paid generation as a connectivity test. Once restored, continue the user's original task. If a previous generation may already have been submitted, check its existing task status before resubmitting.

package/dist/skills/en-US/evomeme-mcp/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "evomeme MCP setup and troubleshooting"
+  short_description: "Configure evomeme MCP and diagnose startup or missing tools"
+  default_prompt: "Use $evomeme-mcp to configure or troubleshoot evomeme MCP, identify the actual config file, and verify the IDE tool connection."
+
+policy:
+  allow_implicit_invocation: true

package/dist/skills/en-US/evomeme-mcp/references/troubleshooting.md

@@ -0,0 +1,55 @@
+# evomeme MCP troubleshooting
+
+## 1. Find the actual configuration
+
+These are **this installer's paths when `--config-path` is omitted**. `~` is the current operating-system user's home directory, not the IDE installation directory.
+
+| IDE | Default configuration file |
+| --- | --- |
+| Cursor | `~/.cursor/mcp.json` |
+| Codex | `~/.codex/config.toml` |
+| Claude Code | `~/.claude.json` |
+| WorkBuddy | `~/.workbuddy/mcp.json` |
+| Trae SOLO China / Windows | `%APPDATA%/TRAE SOLO CN/User/mcp.json`; without APPDATA, fall back to `AppData/Roaming` under the user home |
+| Trae SOLO China / macOS | `~/Library/Application Support/TRAE SOLO CN/User/mcp.json` |
+| Trae SOLO China / Linux | `$XDG_CONFIG_HOME/TRAE SOLO CN/User/mcp.json`; otherwise `~/.config/TRAE SOLO CN/User/mcp.json` |
+
+The current Codex installer does not automatically use `CODEX_HOME`. Portable editions, custom config directories, and other IDE product variants also cannot be inferred from default paths alone. Confirm the file through the IDE settings or actual startup configuration, then pass `--config-path`. Do not scan entire drives or write to multiple guessed locations.
+
+Inspect only fields relevant to the failure; avoid printing credentials belonging to other MCP servers. Writers preserve other MCP entries and settings. Invalid JSON aborts installation; do not delete the file to start over. The TOML installer replaces the evomeme tables and checks them for duplicates; it is not a full TOML syntax validator. Diagnose other syntax errors using the IDE's messages.
+
+## 2. Diagnose by symptom
+
+| Symptom | Check and action |
+| --- | --- |
+| Missing `--config-path` value, a directory path, or multiple IDEs | Supply the full configuration file path for one IDE. Run separate commands for multiple IDEs. Argument errors stop before self-check or config writes. |
+| Installation succeeds but the IDE has no tools | Compare the printed destination with the file the IDE actually reads. Check whether evomeme is enabled or needs user activation in the IDE. Reconnect or restart, then inspect tools. Self-check uses the install terminal's environment, which may differ from the IDE's. |
+| `spawn ... ENOENT`, missing `node` / `npx` | Run `node --version` and `npm --version`, and inspect executable paths in the config. On Windows use `Get-Command node,npm,npx`; on macOS/Linux use `command -v node npm npx`. Moving or upgrading Node/npm may invalidate saved absolute paths. Rerun install from a working environment while preserving custom options. |
+| PowerShell blocks `npx.ps1` | Verify `npx.cmd` exists and use it for the same install command; there is no need to weaken the global PowerShell execution policy. |
+| `Connection closed` or initialize fails | Read child stderr and startup logs. Distinguish a missing executable/package, runtime crash, wrong subcommand, and polluted protocol output. The message alone does not establish a network failure. |
+| Installer says network failure but details show ENOENT | The current installer maps some startup failures to that message. Follow the concrete exception and stderr; first fix executable or file paths. |
+| npm timeout, DNS/proxy/certificate error, missing package or version | Inspect npm stderr, network conditions, `npm config get registry`, and the requested package/version. For a local tgz, verify it exists and the IDE can access it. Follow the evidence; do not routinely clear npm caches, disable certificate verification, or switch the global registry. |
+| Permission denied or invalid JSON/TOML | Check access and syntax in the actual config file. Compare `.evomeme-cli.bak.latest` when repairing. Before restoring a whole backup, compare subsequent changes and preserve other MCP entries and user additions. |
+| Unrecognized `--config-path` or the default path is still written | Check the executing version and whether `npx -y evomeme@latest help` lists the option. Old versions may silently ignore unknown options. Confirm the printed destination before declaring the custom path effective. |
+| Old or missing tools after an update | Inspect whether the IDE is pinned to an old package, tgz, or local development build. Compare the actual process version in logs with its tool list. Restart MCP after updating its installation. `init` refreshes workspace content; it does not replace an already running MCP process. |
+| Development mode cannot find `dist/index.js` | `install --dev` uses `dist/index.js` under the directory where installation runs. Build in the plugin source directory and reinstall. Do not add `--dev` for ordinary user installations. |
+| Connected server returns not logged in or 40100 | Follow login recovery; the distributed `evomeme-login` skill provides guidance when available. Explain the browser login before starting it. Reinstallation does not fix a credential error on an otherwise working connection. |
+| Tool returns HTTP 404, 413, 502, timeout, or an incompatible response | Check endpoint, status, actual release channel, and `EVOMEME_API_BASE_URL` in logs/config. `--api-base-url` selects the cloud HTTP API root, not a local stdio address. Diagnose the backend error; an incompatible response alone does not prove the client is outdated. |
+| An image/video supplier fails or response fields are missing | Preserve local task ID, remote task ID, and the exact error. Working local tool calls do not prove the supplier chain works; client logs alone cannot prove NewAPI forwarded parameters. State when backend evidence is needed. Do not arbitrarily change supplier settings or repeat paid requests in a loop. |
+| Agent times out while generation may still run | Inspect existing records in workspace `.evomeme/tasks/` and logged status changes first. Client timeout does not establish remote failure; do not delete task data to reset the server. |
+
+## 3. Logs and evidence
+
+Runtime logs use `~/.evomeme/logs/YYYY-MM-DD.jsonl`; on Windows this is usually `C:\Users\<username>\.evomeme\logs\`. One file per local date, retained for today plus the previous six days, without size-based file truncation. JSONL means one JSON record per line.
+
+| Evidence | Fields or events |
+| --- | --- |
+| Actual running version | `process.started`, plus `version`, `channel`, `pid`, `sessionId`, and `fields.nodeVersion` |
+| CLI failure | `cli.failed`, `cli.error`, `process.failed` |
+| A tool call | `mcp.call_started`, `mcp.call_completed`, `mcp.call_failed`, `mcp.tool_error`; correlate through `fields.callId` |
+| Network or backend error | endpoint, status, durationMs, and error in `http.failed`; successful requests use `http.completed` |
+| Background execution | `task.created`, `task.updated`, `task.execution_failed`, `task.worker_exited`; correlate by taskId, stepId, and remoteJobId |
+
+Workspace paths and call/task correlation fields exist only where the corresponding context is available. Logs include client exception stacks, not complete request/response bodies, raw supplier responses, or internal server traces. No logs may mean the process never started, an older package lacks logging, or a write failed; an empty directory alone does not diagnose the cause.
+
+Report the failing layer, confirmed evidence, which config file was repaired, and whether the handshake and IDE tool list were each verified. Share only relevant redacted excerpts, not auth.json, complete environments, or credentials from other services.