summer-engine 2.5.0 → 2.6.0

package/gemini-extension.json

@@ -1,7 +1,7 @@
 {
   "name": "summer",
-  "version": "2.5.0",
-  "description": "Superpowers for AI game dev. MCP bridge to the local Summer Engine plus a context primer that teaches Gemini the 60 Summer skills. Use with the npm CLI for skill files on disk.",
+  "version": "2.5.1",
+  "description": "Agent tooling for Summer Engine: MCP bridge, context primer, and game-dev skills. Use with the npm CLI for skill files on disk.",
   "contextFileName": "GEMINI.md",
   "mcpServers": {
     "summer-engine": {
@@ -13,7 +13,7 @@
   "settings": [
     {
       "name": "enable_pre_commit_doctor",
-      "description": "Block git commits on summer doctor FAIL (off by default)",
+      "description": "Block git commits when summer doctor needs attention (off by default)",
       "envVar": "SUMMER_PRE_COMMIT_DOCTOR",
       "sensitive": false
     }

package/package.json

@@ -1,20 +1,31 @@
 {
   "name": "summer-engine",
-  "version": "2.5.0",
-  "description": "Summer — superpowers for AI game dev. CLI, skills, and MCP tools for Summer Engine.",
+  "version": "2.6.0",
+  "description": "Summer CLI and MCP server for Summer Engine, the AI game engine. Install the engine, connect Claude Code, Cursor, Codex, Gemini, and other agents, and build real games. Skills, hooks, and plugins included.",
   "keywords": [
+    "summer-engine",
+    "summer-cli",
+    "summer-mcp",
+    "summer-agent",
+    "summer-engine-agent",
     "game-engine",
+    "ai-game-engine",
     "godot",
-    "ai",
+    "godot-ai",
     "mcp",
+    "mcp-server",
+    "claude-code",
+    "cursor",
+    "codex",
     "gamedev",
+    "game-development",
     "3d",
-    "summer-engine"
+    "ai"
   ],
   "homepage": "https://summerengine.com",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/SummerEngine/summer.git"
+    "url": "git+https://github.com/SummerEngine/summer-engine-agent.git"
   },
   "license": "MIT",
   "author": "Summer Engine <founders@summerengine.com>",

package/skills/3d-assets/character-model/SKILL.md

@@ -5,7 +5,7 @@ license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: 3d-assets
 user-invocable: true
-allowed-tools: Read Grep summer_search_assets summer_generate_image summer_generate_3d summer_import_from_url summer_add_node summer_set_prop summer_set_resource_property summer_inspect_node summer_inspect_resource summer_get_scene_tree summer_save_scene summer_check_job summer_generate_motion
+allowed-tools: Read Grep summer_search_assets summer_list_my_assets summer_get_asset summer_import_asset_by_id summer_generate_image summer_generate_3d summer_import_from_url summer_add_node summer_set_prop summer_set_resource_property summer_inspect_node summer_inspect_resource summer_get_scene_tree summer_save_scene summer_check_job summer_generate_motion
 paths: ["assets/characters/**", "assets/models/**", "**/*.tscn", "**/*.gd"]
 ---
 
@@ -26,6 +26,16 @@ The whole flow:
 
 The animation skill (`summer:animation/generate-motion`) requires a rigged humanoid; a static `.glb` won't drive motion.
 
+## Web Chat / Public Orchestrator Equivalent
+
+When this skill is running inside the PublicSummerEngine chat orchestrator, use the chat-native tools directly instead of sending the user to Studio:
+
+```
+generateImage -> createCharacter -> checkGenerationStatus/meshyJobStatus -> listUserAssets readiness -> rigModel if needed -> generateAnimation -> meshyJobStatus -> importAssets -> import-character
+```
+
+Use Studio only when the user explicitly asks for visual/manual picking or when chat-side generation fails. The recovered working flow used `createCharacter`, confirmed the rig had `hasMeshyRigTask` or `animationsReady:true`, then generated `idle`, `walk`, `run`, `jump`, and `attack`, imported the rig plus child animation GLBs into `res://characters/<slug>/`, then wired playback from the imported GLB AnimationPlayers/libraries. If `generateAnimation` returns `animations_preparing`, wait, poll/list the rig asset again, and retry instead of routing to Studio. Keep this path repeatable for "animated character", "3D character with animations", "walking enemy", and similar prompts.
+
 ## When to use
 
 - "Make a knight character for the player to control."
@@ -94,10 +104,15 @@ summer_generate_3d(
 )
 ```
 
-Returns `{ asset: { fileUrl } }` — an un-rigged static `.glb`. Import it for preview only:
+Returns a job result with `assetId` and `fileUrl` — an un-rigged static `.glb`.
+Use the asset ID as the stable handle. Import it for preview only:
 
 ```
-summer_import_from_url(url="<fileUrl>", path="res://assets/characters/knight_unrigged.glb")
+summer_get_asset(assetId="<assetId>")
+summer_import_asset_by_id(
+  assetId="<assetId>",
+  path="res://assets/characters/knight_unrigged.glb"
+)
 ```
 
 ### 3. ⛔ USER REVIEW GATE — DO NOT SKIP
@@ -122,12 +137,19 @@ summer_generate_3d({
 })
 ```
 
-Returns a job whose result includes `{ asset: { fileUrl }, rigAssetId }`. If you ran with `wait: false`, poll via `summer_check_job(jobId)`. The `rigAssetId` is the handle `summer:animation/generate-motion` needs — store it.
+Returns a job whose result includes `assetId`, `fileUrl`, and `rigAssetId`.
+If you ran with `wait: false`, poll via `summer_check_job(jobId)`. The
+`rigAssetId` is the handle `summer:animation/generate-motion` needs — store it.
+Resolve it before import so the agent has the viewer/download metadata:
 
 Import the rigged version, replacing the un-rigged file:
 
 ```
-summer_import_from_url(url="<rigged fileUrl>", path="res://assets/characters/knight.glb")
+summer_get_asset(assetId="<rigAssetId>")
+summer_import_asset_by_id(
+  assetId="<rigAssetId>",
+  path="res://assets/characters/knight.glb"
+)
 ```
 
 ### 5. ⚠️ Restart the editor

package/skills/3d-assets/environment-kit/SKILL.md

@@ -5,7 +5,7 @@ license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: 3d-assets
 user-invocable: true
-allowed-tools: Read Grep summer_search_assets summer_generate_3d summer_generate_image summer_import_from_url summer_add_node summer_set_prop summer_inspect_node summer_get_scene_tree summer_save_scene
+allowed-tools: Read Grep summer_search_assets summer_list_my_assets summer_get_asset summer_import_asset_by_id summer_generate_3d summer_generate_image summer_import_from_url summer_add_node summer_set_prop summer_inspect_node summer_get_scene_tree summer_save_scene
 paths: ["assets/kits/**", "assets/models/**", "**/*.tscn", "**/*.gd"]
 ---
 
@@ -82,7 +82,8 @@ summer_generate_3d(
   options={ target_polycount: 1500 },
   wait=true
 )
-summer_import_from_url(url="<fileUrl>", path="res://assets/kits/dungeon/wall.glb")
+summer_get_asset(assetId="<assetId>")
+summer_import_asset_by_id(assetId="<assetId>", path="res://assets/kits/dungeon/wall.glb")
 ```
 
 Show the result to the user. **Iterate the anchor until approved** — every other piece copies its style.
@@ -101,6 +102,10 @@ summer_generate_3d(prompt="A 3 meter tall stone dungeon pillar, square base, flu
 # Door, Corner, Arch — same pattern.
 ```
 
+For each completed generation, capture the returned `assetId`, then import that
+exact ID with `summer_import_asset_by_id`. Do not search for generated pieces by
+name after creating them; exact IDs are the production path.
+
 Polycount targets per kit piece: walls/floors 800–1500 tris (placed dozens of times), decorative (pillar, arch) 1500–3000, doors 2000–3000.
 
 ### 4. Import and stage in a kit scene

package/skills/3d-assets/organic-model/SKILL.md

@@ -5,7 +5,7 @@ license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: 3d-assets
 user-invocable: true
-allowed-tools: Read Grep summer_search_assets summer_generate_3d summer_generate_image summer_import_from_url summer_add_node summer_set_prop summer_inspect_node summer_get_scene_tree summer_save_scene
+allowed-tools: Read Grep summer_search_assets summer_list_my_assets summer_get_asset summer_import_asset_by_id summer_generate_3d summer_generate_image summer_import_from_url summer_add_node summer_set_prop summer_inspect_node summer_get_scene_tree summer_save_scene
 paths: ["assets/organic/**", "assets/models/**", "**/*.tscn", "**/*.gd"]
 ---
 
@@ -55,7 +55,7 @@ Generating a forest? Make 3 hero trees + 5 background trees + 3 rocks at low pol
 ### 1. Search before generating
 
 ```
-summer_search_assets(query="<organic type>", filter={ kind: "model" })
+summer_search_assets(query="<organic type>", assetType="3d_model", source="all")
 ```
 
 ### 2. Build the prompt
@@ -97,7 +97,8 @@ summer_generate_3d(
   options={ target_polycount: 2000 },
   wait=true
 )
-summer_import_from_url(url="<fileUrl>", path="res://assets/organic/pine_tree_01.glb")
+summer_get_asset(assetId="<assetId>")
+summer_import_asset_by_id(assetId="<assetId>", path="res://assets/organic/pine_tree_01.glb")
 ```
 
 ### 4. Generate variation, not duplication

package/skills/3d-assets/prop-model/SKILL.md

@@ -5,7 +5,7 @@ license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: 3d-assets
 user-invocable: true
-allowed-tools: Read Grep summer_search_assets summer_generate_3d summer_generate_image summer_import_from_url summer_add_node summer_set_prop summer_inspect_node summer_get_scene_tree summer_save_scene
+allowed-tools: Read Grep summer_search_assets summer_list_my_assets summer_get_asset summer_import_asset_by_id summer_generate_3d summer_generate_image summer_import_from_url summer_add_node summer_set_prop summer_inspect_node summer_get_scene_tree summer_save_scene
 paths: ["assets/models/**", "**/*.tscn", "**/*.gd"]
 ---
 
@@ -37,7 +37,7 @@ The backing tool is `summer_generate_3d`. Default model is `hunyuan` (Hunyuan 3D
 ### 1. Search before generating
 
 ```
-summer_search_assets(query="<prop name>", filter={ kind: "model" })
+summer_search_assets(query="<prop name>", assetType="3d_model", source="all")
 ```
 
 If a fitting model exists, propose reuse:
@@ -83,25 +83,33 @@ summer_generate_3d(
 )
 ```
 
-Returns `{ asset: { fileUrl }, ... }`.
+Returns a job result with `assetId` and `fileUrl`. Treat `assetId` as the
+stable handle and `fileUrl` as a fallback preview/import URL.
 
 ### 5. Import and wire
 
 ```
-summer_import_from_url(url="<fileUrl>", path="res://assets/models/viking_axe.glb")
-summer_add_node(parent="./World/Props", type="MeshInstance3D", name="VikingAxe")
-summer_set_prop(path="./World/Props/VikingAxe", property="mesh", value="res://assets/models/viking_axe.glb")
+summer_get_asset(assetId="<assetId>")
+summer_import_asset_by_id(
+  assetId="<assetId>",
+  path="res://assets/models/viking_axe.glb",
+  parent="./World/Props",
+  name="VikingAxe"
+)
 summer_save_scene
 ```
 
-For interactive props (chest the player opens, lantern the player picks up), wrap the MeshInstance3D in a `StaticBody3D` (or `RigidBody3D` for physics props) with a `CollisionShape3D` sibling — see `summer:scene-composition` for the parent-shape pattern.
+For interactive props (chest the player opens, lantern the player picks up),
+wrap the instantiated model in a `StaticBody3D` (or `RigidBody3D` for physics
+props) with a `CollisionShape3D` sibling — see `summer:scene-composition` for
+the parent-shape pattern.
 
 ## Anti-patterns
 
 - **Scene context in the prompt.** "A sword lying on a wooden table" → the table becomes geometry. Always say `isolated object`.
 - **Multi-object prompts.** "A sword and a shield" → fused single mesh. Generate separately.
 - **Skipping `target_polycount` for background props.** A 30k-tri barrel in the background tanks frame rate when the level has 50 of them.
-- **Forgetting to import.** `fileUrl` from `summer_generate_3d` is a remote URL — you MUST `summer_import_from_url` before referencing it as `res://...`.
+- **Forgetting to import.** `fileUrl` from `summer_generate_3d` is a remote URL — you MUST `summer_import_asset_by_id` or `summer_import_from_url` before referencing it as `res://...`.
 - **Generating before searching.** Reuse beats regenerate every time.
 - **Picking `meshy` by default.** It's legacy. `hunyuan` is better; `trellis` is faster.
 

package/skills/3d-assets/vehicle-model/SKILL.md

@@ -5,7 +5,7 @@ license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: 3d-assets
 user-invocable: true
-allowed-tools: Read Grep summer_search_assets summer_generate_3d summer_generate_image summer_import_from_url summer_add_node summer_set_prop summer_inspect_node summer_inspect_resource summer_get_scene_tree summer_save_scene
+allowed-tools: Read Grep summer_search_assets summer_list_my_assets summer_get_asset summer_import_asset_by_id summer_generate_3d summer_generate_image summer_import_from_url summer_add_node summer_set_prop summer_inspect_node summer_inspect_resource summer_get_scene_tree summer_save_scene
 paths: ["assets/vehicles/**", "assets/models/**", "**/*.tscn", "**/*.gd"]
 ---
 
@@ -69,7 +69,7 @@ If the user has reference images already (concept art, photos), prefer those —
 ### 1. Search before generating
 
 ```
-summer_search_assets(query="<vehicle type>", filter={ kind: "model" })
+summer_search_assets(query="<vehicle type>", assetType="3d_model", source="all")
 ```
 
 ### 2. Pick model and polycount
@@ -101,7 +101,8 @@ summer_generate_3d(
   options={ target_polycount: 25000 },
   wait=true
 )
-summer_import_from_url(url="<fileUrl>", path="res://assets/vehicles/race_car.glb")
+summer_get_asset(assetId="<assetId>")
+summer_import_asset_by_id(assetId="<assetId>", path="res://assets/vehicles/race_car.glb")
 ```
 
 ### 5. Inspect for hard-surface artifacts

package/skills/animation/animation-tree/SKILL.md

@@ -22,6 +22,8 @@ Character (CharacterBody3D)
 └── AnimationTree              # references AnimationPlayer, drives behavior
 ```
 
+Before adding the tree, prove direct `AnimationPlayer.play()` visibly moves the rig. Godot may import animation GLBs as `AnimationLibrary` resources or as `PackedScene`s with embedded `AnimationPlayer`s. If a copied clip appears in the list but the mesh T-poses, its tracks probably target a different root/skeleton path. Use the embedded player that came with the matching GLB, or remap/copy tracks only after confirming they target the active `Skeleton3D`. An inactive AnimationTree is also a no-op, so always set `AnimationTree.active = true`.
+
 ## When to use this skill
 
 - Character has 3+ clips and switching between them via `AnimationPlayer.play("walk")` is causing pops, T-poses, or "starts halfway through".

package/skills/animation/generate-motion/SKILL.md

@@ -5,7 +5,7 @@ license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: animation
 user-invocable: false
-allowed-tools: Read Grep summer_search_assets summer_generate_motion summer_inspect_resource summer_get_scene_tree summer_add_node summer_set_prop summer_set_resource_property summer_save_scene
+allowed-tools: Read Grep summer_search_assets summer_list_my_assets summer_get_asset summer_get_asset_download_url summer_generate_motion summer_inspect_resource summer_get_scene_tree summer_add_node summer_set_prop summer_set_resource_property summer_save_scene
 paths: ["**/*.tscn", "**/*.tres", "**/*.gd"]
 ---
 
@@ -17,6 +17,22 @@ The target must be a **Meshy-rigged humanoid** — a `rigAssetId` from a prior `
 
 > **Custom prompt-driven motion** (e.g. "drops to one knee, draws bow") is on the roadmap but not shipped yet. For one-off signature moves not on the curated list, fall back to hand-authoring in the Godot editor or importing from Mixamo. See the Edge cases section.
 
+## Web Chat / Public Orchestrator Equivalent
+
+In PublicSummerEngine chat, the equivalent direct tools are:
+
+```
+rigModel({ modelAssetId })
+generateAnimation({ rigAssetId, animationName })
+meshyJobStatus({ jobId })
+```
+
+If the character came from `createCharacter`, it may already be rigged and have `metadata.meshyRigTaskId`; generate animations directly against that rig asset. Verified animation names from the recovered production flow are `idle`, `walk`, `run`, `jump`, and `attack`. `fall` returned `invalid_animation`, so do not present it as a default.
+
+Before generating clips in PublicSummerEngine chat, confirm the rig asset listing/status exposes `hasMeshyRigTask` or `animationsReady:true`. If `generateAnimation` returns `animations_preparing`, wait, poll/list the rig again, and retry; this is the post-rig setup catching up, not a reason to send the user to Studio.
+
+After animation jobs complete, import the rig plus child animation assets together and wire them through `import-character`. Do not hand off to Studio unless the user asked for Studio/manual control or the direct chat tools fail.
+
 ## When to use this skill
 
 - "Add a walk animation to the goblin."
@@ -38,7 +54,7 @@ The target must be a **Meshy-rigged humanoid** — a `rigAssetId` from a prior `
 ### 1. Verify the target is a rigged humanoid
 
 ```
-summer_search_assets(query="<character name>", kind="model")
+summer_search_assets(query="<character name>", assetType="3d_model", source="my_assets")
 ```
 
 The result must include `rigAssetId: <id>` on a Meshy rig. If it shows `rigAssetId: null`, the model isn't rigged — stop, propose `summer_generate_3d({ kind: "image-to-3d", imageUrl: "...", options: { rig: true } })` first (the result includes `rigAssetId`), or route to `summer:asset-pipeline/asset-strategy`.
@@ -57,7 +73,12 @@ summer_generate_motion(
 )
 ```
 
-Returns `{ animationAssetId, durationSeconds, previewUrl }`.
+Returns `animationAssetId`, `durationSeconds`, and `previewUrl`. Resolve the
+asset before handoff so you have the stable file/download metadata:
+
+```
+summer_get_asset(assetId="<animationAssetId>")
+```
 
 ### 4. Attach to the character's AnimationPlayer
 
@@ -99,7 +120,7 @@ The full list is ~70 names. If the user asks for something not on the top-30, tr
 ## Anti-patterns
 
 - Calling `summer_generate_motion` on a `.glb` that wasn't rigged — wastes a generation; the API errors but only after 30s.
-- Generating the same clip twice because you forgot to save the `animationAssetId` from the first call. Search the asset library first: `summer_search_assets(query: "goblin run", kind: "animation")`.
+- Generating the same clip twice because you forgot to save the `animationAssetId` from the first call. Search the asset library first: `summer_search_assets(query: "goblin run", assetType: "animation", source: "my_assets")`.
 - Wiring clips into an AnimationTree inside this skill. That's the next skill's job. Generate, attach, hand off.
 - Asking the model to invent a `motionName` that isn't on the list. Quote from the list verbatim, or fall back to manual authoring.
 

package/skills/asset-pipeline/asset-strategy/SKILL.md

@@ -5,7 +5,7 @@ license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: asset-pipeline
 user-invocable: false
-allowed-tools: Read Grep Skill summer_search_assets
+allowed-tools: Read Grep Skill summer_search_assets summer_list_my_assets summer_get_asset summer_import_asset_by_id
 ---
 
 # Asset Strategy — Meta-Router for Asset Creation
@@ -117,7 +117,8 @@ VFX is **code, not generative** — recipes are shader + GDScript + node setup,
 
 - The user already named the specific skill — go straight there.
 - The user is debugging or running the game — route to `summer:debug` or `summer:play`.
-- The asset is being imported, not generated (existing `.glb` / `.wav` from Sketchfab, Quaternius, AmbientCG) — call `summer_import_from_url` directly.
+- The asset is an existing Summer asset ID — call `summer_get_asset`, then `summer_import_asset_by_id`.
+- The asset is being imported from a non-Summer URL (`.glb` / `.wav` from Sketchfab, Quaternius, AmbientCG) — call `summer_import_from_url` directly.
 - The user wants to plan the whole game's asset list — `summer:brainstorm-game` first, then this router on each item.
 
 ## Anti-patterns

package/skills/workflow/mcpupdate/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: mcpupdate
+description: Use when improving or maintaining the Summer Engine CLI, its MCP tools (summer_* / "ops"), or its prompt-engineering skills based on a real working session. Examples: the user types /mcpupdate, says "mcpskillify this", "log this as a skill/example", "this <feature> feels great, capture it", or notes that an agent went down a bad path with the Summer tools/skills and the prompts should be fixed. Works from ANY chat, not just inside the summer-cli repo.
+---
+
+# mcpupdate: turn a session into improvements to the Summer CLI / MCP / skills
+
+## What this is
+A bridge from *using* Summer Engine (in any game-project chat) back to *improving* it.
+When a session reveals something, such as a pattern that worked beautifully or prompt-engineering
+that sent the agent down a bad path, capture it into the CLI's tools, skills, or docs so the
+next agent benefits. Invokable from any chat; it jumps to the right repo files directly.
+
+## Where everything lives (skip the scanning)
+This skill lives in the **summer-cli** repo (the CLI + MCP + skills), normally at
+`<SummerEngine checkout>/tools/summer-cli/`. Paths below are relative to that repo root.
+
+- `src/mcp/tools/*.ts`: the `summer_*` MCP tool definitions ("ops": scene/asset/project/etc.)
+- `references/mcp-tools-reference.md`: human-readable tool reference
+- `src/mcp/tools/project-tools.ts` + `docs/MCP_FRESH_CHAT_PLAYBOOK.md`: the **agent playbook** returned by `summer_get_agent_playbook` (startup flow / defaults that steer agents)
+- `src/lib/skills-registry.ts`: how skills are discovered/surfaced to the agent
+- `skills/<category>/<name>/SKILL.md`: the **prompt-engineering skills** (e.g. `character-controllers/fps-controller`, `scene-and-project/make-game`, `level-design/design-level`, `visual-effects/*`)
+- `_persona/summer/SKILL.md`: the Summer persona
+- `skills/workflow/{skill-create,skill-improve,skill-test,gameskill,writing-skills}/`: **use these** to author/edit Summer skills
+- `commands/`, `hooks/`, `AGENTS.md`/`CLAUDE.md`/`GEMINI.md`: slash commands, hooks, agent instructions
+- `dist/` is built output: edit `src/` and `skills/`, not `dist/`
+
+**Public docs (separate Mintlify repo, the org `docs` repo, often a sibling checkout):** `docs.json` (nav), `cli/overview.mdx`, `ai-tools/operations.mdx`, `ai-tools/rag-search.mdx`, plus `guides/`, `api-reference/`, `art-system/`.
+
+> summer-cli changes are committed in **this repo** (the SummerEngine checkout), not in a game-project repo.
+
+## Public surface sync checklist
+
+Run this checklist when a tool, skill, setup target, license sentence, or count changes. Public trust is damaged more by obvious drift than by modest numbers.
+
+1. Count MCP tools from source:
+
+```bash
+rg "server\\.tool\\(" src/mcp/tools -g '*.ts' -g '!*.test.ts' | wc -l
+```
+
+2. Count skill surfaces separately. Do not collapse them into one public claim unless the sentence explains which surface it means:
+
+```bash
+find skills -name SKILL.md | wc -l
+npm run build
+node -e "import('./dist/lib/skills-registry.js').then(m=>{const r=m.SKILL_REGISTRY||[]; console.log({registry:r.length,recommended:r.filter(s=>s.recommended).length})})"
+```
+
+3. Update the CLI repo surfaces that readers and agents scan:
+   - `README.md`
+   - `.claude-plugin/plugin.json`
+   - `.codex-plugin/plugin.json`
+   - `AGENTS.md`
+   - `GEMINI.md`
+   - `references/mcp-tools-reference.md`
+   - `docs/DEVELOPMENT.md`
+   - `docs/SKILLS.md`
+
+4. Update sibling public docs and website surfaces when present:
+   - `docs` Mintlify pages, especially `cli/overview.mdx`, `ai-tools/operations.mdx`, `api-reference/`, and setup guides
+   - `PublicSummerEngine` guide data, `llms.txt` routes, README, and any blog post that mentions counts or openness
+   - `summer-strategy` if the change affects positioning, licensing, or launch strategy
+
+5. Prefer durable copy:
+   - Say "Summer agent layer" for this repo in prose.
+   - Say "`summer-engine` npm package" for the package.
+   - Say "Summer Engine app" for the closed desktop engine.
+   - Avoid brittle skill totals in public copy unless generated in the same change.
+   - Avoid red-looking doctor payloads in public README examples. Explain remediation without showing a scary JSON blob.
+
+## How to run it
+1. **Confirm the target.** Restate in one line what should change and which bucket it is:
+   1) **CLI / MCP tool behavior**, 2) **a skill (prompt-engineering)**, or 3) **logging a session learning** (good pattern to example, or bad path to fix). Ask only if genuinely ambiguous.
+2. **Open the exact file from the map above**. Do not scan the tree.
+3. **Make the change** using the existing maintenance skills:
+   - New skill: `skills/workflow/skill-create`. Edit/append: `skills/workflow/skill-improve`. Game-dev win: `skills/workflow/gameskill`.
+   - Tool behavior / playbook: edit `src/mcp/tools/*.ts` and/or `docs/MCP_FRESH_CHAT_PLAYBOOK.md`; keep `references/mcp-tools-reference.md` in sync. Check `src/mcp/tools/project-tools.test.ts` still passes.
+   - Public-facing change: update the matching file in the `docs` repo.
+4. **Keep it concrete**. Every captured pattern gets a real, runnable code block (below), not prose.
+5. **Verify + commit.** If you touched `src/`, run `npm test`. Commit on a branch and summarize.
+
+## "mcpskillify": capture a working pattern as an example
+Trigger: *"this player movement feels great, mcpskillify it"*, *"log this as how to do X"*.
+
+1. Identify the smallest self-contained code that produced the good result (the actual GDScript/C# from the session).
+2. Find the matching skill via the map (movement to `character-controllers/fps-controller`; a mechanic to `gameplay-mechanics/design-mechanic`; none fits to `skill-create` a new one in the right category).
+3. Append a focused example: what it does, the code, and *why it feels good* (the tunables). Shape:
+
+````markdown
+## Example: snappy first-person movement (proven)
+WHY it feels good: instant accel + short coyote time + air control; no float.
+
+```gdscript
+const SPEED := 6.0
+const ACCEL := 60.0          # high accel = snappy, no slide
+const COYOTE := 0.12         # forgiving jump after leaving a ledge
+func _physics_process(delta):
+    var dir := (transform.basis * Vector3(input.x, 0, input.y)).normalized()
+    velocity.x = move_toward(velocity.x, dir.x * SPEED, ACCEL * delta)
+    velocity.z = move_toward(velocity.z, dir.z * SPEED, ACCEL * delta)
+    move_and_slide()
+```
+````
+
+Keep one excellent example per pattern. Port it, don't pile on variants.
+
+## The behavior the skills/playbook should teach (the doctrine)
+Target agent workflow for building in a Summer project. When `/mcpupdate` reviews the playbook
+and skills, make them teach this, and flag where they don't:
+
+1. **Understand** what the user wants (one pass, no tool spelunking first).
+2. **Outline** the plan fast and briefly; proceed once it's clearly right.
+3. **Execute in pure code**. Write GDScript by default (C# only if the project already uses it). Edit `.gd`/`.tscn`/`.tres` as **text files**; that's the default medium.
+4. **Play & auto-iterate**. Run the scene/game, read console + script/debugger errors, fix, repeat until clean. Crucially: **play the scene you just made first**, so boot/parse crashes surface immediately instead of after the user navigates to the feature.
+
+## Known bad path to fix first (from real sessions)
+The MCP playbook over-steered agents into **ops-first** scene editing (open/save-as/inspect/
+instantiate) when plain **file editing** is simpler and safer for a headless agent, causing
+wasted turns, scene "rename"/save-as churn, and editor-tab clobbering. Keep these fixed:
+
+- **File-first for `.tscn`/`.tres`:** edit scene/resource files as text by default; use scene-ops
+  only for live-engine needs (navmesh/light bake, play/observe, runtime inspect) or instancing
+  into an already-open scene. The MCP `WriteFile` refusing `.tscn` means "use host file tools," not "use scene ops."
+- **Clobber gotcha:** a `.tscn` open in the editor can be overwritten by the editor's tab on save.
+  reload/close the tab after external writes.
+- **Constraint-based flow:** the playbook's flow is conditional (`buildFlow` for the default,
+  `liveEngineFlow` only when you need the running engine), not a prescriptive always-open-the-editor loop.
+
+## Red flags this skill is being skipped
+- You started scanning the engine repo to find the CLI: use the map above.
+- You captured a "great" pattern as prose with no runnable code: add the code block.
+- You edited `dist/`: edit `src/`/`skills/` instead.
+- You committed CLI changes in a game-project repo: commit in the SummerEngine checkout.