summer-engine 2.8.2 → 3.1.0

package/integrations/gemini/README.md

@@ -0,0 +1,26 @@
+# Gemini CLI integration
+
+Generated by `scripts/generate-registry` from `library/**/resource.yaml`:
+
+- `registry/generated/gemini-extension.json` -> `gemini-extension.json`
+  (extension manifest: MCP server, GEMINI.md context file, settings; version
+  stamped from `package.json`). The `skills` array is emitted for parity with
+  the other manifests but Gemini has no such field — it discovers extension
+  skills from `<extension>/skills/<name>/SKILL.md` and ignores unknown keys.
+
+`summer setup gemini` writes `~/.gemini/extensions/summer-engine/`:
+
+- `gemini-extension.json` — the generated manifest above with install-time
+  overrides: `name` becomes `summer-engine` (Gemini requires the manifest name
+  to match the extension directory), `mcpServers.summer-engine` becomes the
+  standard launcher (`npx -y summer-engine@latest mcp`, `cmd.exe /c` wrapped on
+  Windows) because `${extensionPath}` holds no npm package, `skills` and the
+  `_generated` banner are dropped.
+- `GEMINI.md` and `AGENTS.md` (the context file and the file it imports).
+- `skills/<slug>/SKILL.md` for every library skill (via
+  `skills install --all --agent gemini`); Gemini extensions are user-scoped, so
+  `--scope project` falls back to user with a warning.
+
+Never edit the destination file by hand — edit `library/` resources or
+`scripts/generate-registry/manifests.ts`, then run
+`npm run generate:registry`. CI `--check` fails on any drift.

package/integrations/gemini/manifest-target.json

@@ -0,0 +1,5 @@
+{
+  "targets": [
+    { "generated": "gemini-extension.json", "destination": "gemini-extension.json" }
+  ]
+}

package/integrations/github-copilot/README.md

@@ -0,0 +1,12 @@
+# GitHub Copilot CLI integration
+
+No manifest file is generated in this repo for GitHub Copilot CLI — `manifest-target.json`
+is intentionally empty. Support is delivered at install time by
+`summer setup github-copilot` (aliases: `copilot`, `copilot-cli`, `github-copilot-cli`), which writes:
+
+- MCP config: `~/.copilot/mcp-config.json`; Windows `%USERPROFILE%/.copilot/mcp-config.json` (user); `.mcp.json` (project).
+  Shape: `mcpServers.summer-engine = { type: "local", command, args, tools: ["*"] }`.
+- Skills: `~/.copilot/skills` (user) or `.github/skills` (project) as `<skill>/SKILL.md`.
+- After: Restart Copilot CLI, or run /mcp reload and /skills reload in the active session.
+
+Source of truth: `src/installer/agent-table.ts` (one row per agent).

package/integrations/github-copilot/manifest-target.json

@@ -0,0 +1,3 @@
+{
+  "targets": []
+}

package/integrations/goose/README.md

@@ -0,0 +1,12 @@
+# Goose integration
+
+No manifest file is generated in this repo for Goose — `manifest-target.json`
+is intentionally empty. Support is delivered at install time by
+`summer setup goose` (aliases: `block-goose`, `codename-goose`), which writes:
+
+- MCP config: `~/.config/goose/config.yaml`; Windows `%APPDATA%/Block/goose/config/config.yaml` (user); user scope only (project requests fall back with a warning).
+  Shape: `extensions.summer-engine = { type: stdio, cmd, args, enabled, timeout }` (YAML).
+- Skills: `~/.config/agents/skills` (user) or `.agents/skills` (project) as `<skill>/SKILL.md`.
+- After: Restart Goose (CLI or Desktop); summer-engine is listed under Extensions.
+
+Source of truth: `src/installer/agent-table.ts` (one row per agent).

package/integrations/goose/manifest-target.json

@@ -0,0 +1,3 @@
+{
+  "targets": []
+}

package/integrations/grok-build/README.md

@@ -0,0 +1,12 @@
+# Grok Build integration
+
+No manifest file is generated in this repo for Grok Build — `manifest-target.json`
+is intentionally empty. Support is delivered at install time by
+`summer setup grok-build` (aliases: `grok`, `xai-grok`), which writes:
+
+- MCP config: `~/.grok/config.toml`; Windows `%USERPROFILE%/.grok/config.toml` (user); `.grok/config.toml` (project).
+  Shape: `[mcp_servers.summer-engine]` table (TOML).
+- Skills: `~/.grok/skills` (user) or `.grok/skills` (project) as `<skill>/SKILL.md`.
+- After: Restart Grok Build so it reloads config.toml (it also reads ~/.claude.json and .cursor/mcp.json).
+
+Source of truth: `src/installer/agent-table.ts` (one row per agent).

package/integrations/grok-build/manifest-target.json

@@ -0,0 +1,3 @@
+{
+  "targets": []
+}

package/integrations/hermes/README.md

@@ -0,0 +1,12 @@
+# Hermes Agent integration
+
+No manifest file is generated in this repo for Hermes Agent — `manifest-target.json`
+is intentionally empty. Support is delivered at install time by
+`summer setup hermes` (aliases: `hermes-agent`, `nous-hermes`), which writes:
+
+- MCP config: `~/.hermes/config.yaml`; Windows `%USERPROFILE%/.hermes/config.yaml` (user); user scope only (project requests fall back with a warning).
+  Shape: `mcp_servers.summer-engine = { command, args }` (YAML).
+- Skills: `~/.hermes/skills` (user) or `.hermes/skills` (project) as `<skill>/SKILL.md`. Project skills need `hermes skills trust` before Hermes loads them.
+- After: Run /reload-mcp in Hermes Agent (or restart it).
+
+Source of truth: `src/installer/agent-table.ts` (one row per agent).

package/integrations/hermes/manifest-target.json

@@ -0,0 +1,3 @@
+{
+  "targets": []
+}

package/integrations/junie/README.md

@@ -0,0 +1,12 @@
+# Junie integration
+
+No manifest file is generated in this repo for Junie — `manifest-target.json`
+is intentionally empty. Support is delivered at install time by
+`summer setup junie` (aliases: `jetbrains-junie`), which writes:
+
+- MCP config: `~/.junie/mcp/mcp.json`; Windows `%USERPROFILE%/.junie/mcp/mcp.json` (user); `.junie/mcp/mcp.json` (project).
+  Shape: `mcpServers.summer-engine = { command, args }`.
+- Skills: none. Junie has no skills folder; put project guidance in .junie/guidelines.md. The MCP server ships summer_get_agent_playbook for in-chat guidance.
+- After: Restart the JetBrains IDE so Junie reloads its MCP config.
+
+Source of truth: `src/installer/agent-table.ts` (one row per agent).

package/integrations/junie/manifest-target.json

@@ -0,0 +1,3 @@
+{
+  "targets": []
+}

package/integrations/kilo-code/README.md

@@ -0,0 +1,12 @@
+# Kilo Code integration
+
+No manifest file is generated in this repo for Kilo Code — `manifest-target.json`
+is intentionally empty. Support is delivered at install time by
+`summer setup kilo-code` (aliases: `kilo`, `kilocode`), which writes:
+
+- MCP config: `~/.config/kilo/kilo.json`; Windows `%APPDATA%/kilo/kilo.json` (user); `kilo.json` (project).
+  Shape: `mcp.summer-engine = { type: "local", command: [npx, ...], enabled: true }`.
+- Skills: `~/.kilo/skills` (user) or `.kilo/skills` (project) as `<skill>/SKILL.md`.
+- After: Restart Kilo (CLI or the VS Code extension) so it reloads kilo.json.
+
+Source of truth: `src/installer/agent-table.ts` (one row per agent).

package/integrations/kilo-code/manifest-target.json

@@ -0,0 +1,3 @@
+{
+  "targets": []
+}

package/integrations/kimi-code/README.md

@@ -0,0 +1,12 @@
+# Kimi Code CLI integration
+
+No manifest file is generated in this repo for Kimi Code CLI — `manifest-target.json`
+is intentionally empty. Support is delivered at install time by
+`summer setup kimi-code` (aliases: `kimi`, `kimi-cli`, `kimicode`), which writes:
+
+- MCP config: `~/.kimi-code/mcp.json`; Windows `%USERPROFILE%/.kimi-code/mcp.json` (user); `.kimi-code/mcp.json` (project).
+  Shape: `mcpServers.summer-engine = { command, args }`.
+- Skills: `~/.kimi-code/skills` (user) or `.kimi-code/skills` (project) as `<skill>/SKILL.md`.
+- After: Restart Kimi Code CLI so it reconnects its MCP servers.
+
+Source of truth: `src/installer/agent-table.ts` (one row per agent).

package/integrations/kimi-code/manifest-target.json

@@ -0,0 +1,3 @@
+{
+  "targets": []
+}

package/integrations/kiro/README.md

@@ -0,0 +1,12 @@
+# Kiro integration
+
+No manifest file is generated in this repo for Kiro — `manifest-target.json`
+is intentionally empty. Support is delivered at install time by
+`summer setup kiro` (aliases: `kiro-ide`, `aws-kiro`), which writes:
+
+- MCP config: `~/.kiro/settings/mcp.json`; Windows `%USERPROFILE%/.kiro/settings/mcp.json` (user); `.kiro/settings/mcp.json` (project).
+  Shape: `mcpServers.summer-engine = { command, args }`.
+- Skills: `~/.kiro/skills` (user) or `.kiro/skills` (project) as `<skill>/SKILL.md`.
+- After: Kiro reloads MCP config on save; open the MCP Servers view to confirm summer-engine is connected.
+
+Source of truth: `src/installer/agent-table.ts` (one row per agent).

package/integrations/kiro/manifest-target.json

@@ -0,0 +1,3 @@
+{
+  "targets": []
+}

package/integrations/lm-studio/README.md

@@ -0,0 +1,12 @@
+# LM Studio integration
+
+No manifest file is generated in this repo for LM Studio — `manifest-target.json`
+is intentionally empty. Support is delivered at install time by
+`summer setup lm-studio` (aliases: `lmstudio`, `lm_studio`), which writes:
+
+- MCP config: `~/.lmstudio/mcp.json`; Windows `%USERPROFILE%/.lmstudio/mcp.json` (user); user scope only (project requests fall back with a warning).
+  Shape: `mcpServers.summer-engine = { command, args }`.
+- Skills: none. LM Studio has no rules or skills folder. The MCP server ships summer_get_agent_playbook, so the model can pull Summer guidance in-chat.
+- After: Open LM Studio, toggle on the summer-engine MCP server in the Program tab, and raise the loaded model's context length to 32k or higher.
+
+Source of truth: `src/installer/agent-table.ts` (one row per agent).

package/integrations/lm-studio/manifest-target.json

@@ -0,0 +1,3 @@
+{
+  "targets": []
+}

package/integrations/mistral-vibe/README.md

@@ -0,0 +1,12 @@
+# Mistral Vibe integration
+
+No manifest file is generated in this repo for Mistral Vibe — `manifest-target.json`
+is intentionally empty. Support is delivered at install time by
+`summer setup mistral-vibe` (aliases: `vibe`, `mistral`), which writes:
+
+- MCP config: `~/.vibe/config.toml`; Windows `%USERPROFILE%/.vibe/config.toml` (user); `.vibe/config.toml` (project).
+  Shape: undefined.
+- Skills: `~/.vibe/skills` (user) or `.vibe/skills` (project) as `<skill>/SKILL.md`.
+- After: Restart Vibe so it reloads config.toml.
+
+Source of truth: `src/installer/agent-table.ts` (one row per agent).

package/integrations/mistral-vibe/manifest-target.json

@@ -0,0 +1,3 @@
+{
+  "targets": []
+}

package/integrations/opencode/README.md

@@ -0,0 +1,12 @@
+# OpenCode integration
+
+No manifest file is generated in this repo for OpenCode — `manifest-target.json`
+is intentionally empty. Support is delivered at install time by
+`summer setup opencode` (aliases: `open-code`), which writes:
+
+- MCP config: `~/.config/opencode/opencode.json`; Windows `%APPDATA%/opencode/opencode.json` (user); `opencode.json` (project).
+  Shape: `mcp.summer-engine = { type: "local", command: [npx, ...], enabled: true }`.
+- Skills: `~/.config/opencode/skills` (user) or `.opencode/skills` (project) as `<skill>/SKILL.md`. OpenCode loads skills from this folder on the next session. Summer 3.0 and earlier wrote markdown under agents/summer; `--force` removes those.
+- After: Restart OpenCode so it reloads opencode.json.
+
+Source of truth: `src/installer/agent-table.ts` (one row per agent).

package/integrations/opencode/manifest-target.json

@@ -0,0 +1,3 @@
+{
+  "targets": []
+}

package/integrations/qoder/README.md

@@ -0,0 +1,12 @@
+# Qoder CLI integration
+
+No manifest file is generated in this repo for Qoder CLI — `manifest-target.json`
+is intentionally empty. Support is delivered at install time by
+`summer setup qoder` (aliases: `qoder-cli`), which writes:
+
+- MCP config: `~/.qoder/settings.json`; Windows `%USERPROFILE%/.qoder/settings.json` (user); `.mcp.json` (project).
+  Shape: `mcpServers.summer-engine = { command, args }`.
+- Skills: `~/.qoder/skills` (user) or `.qoder/skills` (project) as `<skill>/SKILL.md`.
+- After: Restart Qoder CLI so it reloads its MCP settings (the Qoder IDE manages servers in its UI).
+
+Source of truth: `src/installer/agent-table.ts` (one row per agent).

package/integrations/qoder/manifest-target.json

@@ -0,0 +1,3 @@
+{
+  "targets": []
+}

package/integrations/qwen-code/README.md

@@ -0,0 +1,12 @@
+# Qwen Code integration
+
+No manifest file is generated in this repo for Qwen Code — `manifest-target.json`
+is intentionally empty. Support is delivered at install time by
+`summer setup qwen-code` (aliases: `qwen`, `qwencode`), which writes:
+
+- MCP config: `~/.qwen/settings.json`; Windows `%USERPROFILE%/.qwen/settings.json` (user); `.qwen/settings.json` (project).
+  Shape: `mcpServers.summer-engine = { command, args }`.
+- Skills: `~/.qwen/skills` (user) or `.qwen/skills` (project) as `<skill>/SKILL.md`.
+- After: Restart Qwen Code or run /mcp in a new session.
+
+Source of truth: `src/installer/agent-table.ts` (one row per agent).

package/integrations/qwen-code/manifest-target.json

@@ -0,0 +1,3 @@
+{
+  "targets": []
+}

package/integrations/roo-code/README.md

@@ -0,0 +1,14 @@
+# Roo Code integration
+
+> **Legacy.** Roo Code shut down on 2026-05-15. The extension may still run, but it is no longer maintained; consider Cline or Kilo Code.
+
+No manifest file is generated in this repo for Roo Code — `manifest-target.json`
+is intentionally empty. Support is delivered at install time by
+`summer setup roo-code` (aliases: `roo`, `roocode`), which writes:
+
+- MCP config: `~/Library/Application Support/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/cline_mcp_settings.json`; Linux `~/.config/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/cline_mcp_settings.json`; Windows `%APPDATA%/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/cline_mcp_settings.json` (user); user scope only (project requests fall back with a warning).
+  Shape: `mcpServers.summer-engine = { command, args }`.
+- Skills: `~/Documents/Roo/Rules` (user) or `.clinerules` (project) as rule files `summer-<skill>.md`.
+- After: Restart VS Code so Roo Code reloads its MCP config.
+
+Source of truth: `src/installer/agent-table.ts` (one row per agent).

package/integrations/roo-code/manifest-target.json

@@ -0,0 +1,3 @@
+{
+  "targets": []
+}

package/integrations/rovo-dev/README.md

@@ -0,0 +1,12 @@
+# Rovo Dev CLI integration
+
+No manifest file is generated in this repo for Rovo Dev CLI — `manifest-target.json`
+is intentionally empty. Support is delivered at install time by
+`summer setup rovo-dev` (aliases: `rovodev`, `rovo`, `atlassian-rovo-dev`), which writes:
+
+- MCP config: `~/.rovodev/mcp.json`; Windows `%USERPROFILE%/.rovodev/mcp.json` (user); user scope only (project requests fall back with a warning).
+  Shape: undefined.
+- Skills: `~/.rovodev/skills` (user) or `.rovodev/skills` (project) as `<skill>/SKILL.md`.
+- After: Restart Rovo Dev CLI so it reconnects its MCP servers.
+
+Source of truth: `src/installer/agent-table.ts` (one row per agent).

package/integrations/rovo-dev/manifest-target.json

@@ -0,0 +1,3 @@
+{
+  "targets": []
+}

package/integrations/trae/README.md

@@ -0,0 +1,12 @@
+# Trae integration
+
+No manifest file is generated in this repo for Trae — `manifest-target.json`
+is intentionally empty. Support is delivered at install time by
+`summer setup trae` (aliases: `trae-ide`, `bytedance-trae`), which writes:
+
+- MCP config: `.trae/mcp.json` (user); `.trae/mcp.json` (project).
+  Shape: `mcpServers.summer-engine = { command, args }`.
+- Skills: none. Trae documents no skills folder; the MCP server ships summer_get_agent_playbook for in-chat guidance.
+- After: Restart Trae and open the MCP settings; summer-engine should show as connected.
+
+Source of truth: `src/installer/agent-table.ts` (one row per agent).

package/integrations/trae/manifest-target.json

@@ -0,0 +1,3 @@
+{
+  "targets": []
+}

package/integrations/visual-studio/README.md

@@ -0,0 +1,12 @@
+# GitHub Copilot in Visual Studio integration
+
+No manifest file is generated in this repo for GitHub Copilot in Visual Studio — `manifest-target.json`
+is intentionally empty. Support is delivered at install time by
+`summer setup visual-studio` (aliases: `vs`, `vs2026`, `visual-studio-2026`, `visualstudio`), which writes:
+
+- MCP config: `~/.mcp.json`; Windows `%USERPROFILE%/.mcp.json` (user); `.mcp.json` (project).
+  Shape: `servers.summer-engine = { type: "stdio", command, args }`.
+- Skills: none. Visual Studio's Copilot has no skills folder yet; the MCP server ships summer_get_agent_playbook for in-chat guidance.
+- After: Restart Visual Studio, open Copilot Chat in Agent mode, and enable summer-engine in the tools picker.
+
+Source of truth: `src/installer/agent-table.ts` (one row per agent).

package/integrations/visual-studio/manifest-target.json

@@ -0,0 +1,3 @@
+{
+  "targets": []
+}

package/integrations/vscode-copilot/README.md

@@ -0,0 +1,12 @@
+# GitHub Copilot in VS Code integration
+
+No manifest file is generated in this repo for GitHub Copilot in VS Code — `manifest-target.json`
+is intentionally empty. Support is delivered at install time by
+`summer setup vscode-copilot` (aliases: `vscode`, `vs-code`, `vs-code-copilot`, `github-copilot-vscode`), which writes:
+
+- MCP config: `~/Library/Application Support/Code/User/mcp.json`; Linux `~/.config/Code/User/mcp.json`; Windows `%APPDATA%/Code/User/mcp.json` (user); `.vscode/mcp.json` (project).
+  Shape: `servers.summer-engine = { type: "stdio", command, args }`.
+- Skills: `~/.copilot/skills` (user) or `.github/skills` (project) as `<skill>/SKILL.md`.
+- After: Restart VS Code or run MCP: List Servers, then start summer-engine in Copilot Agent mode.
+
+Source of truth: `src/installer/agent-table.ts` (one row per agent).

package/integrations/vscode-copilot/manifest-target.json

@@ -0,0 +1,3 @@
+{
+  "targets": []
+}

package/integrations/warp/README.md

@@ -0,0 +1,12 @@
+# Warp integration
+
+No manifest file is generated in this repo for Warp — `manifest-target.json`
+is intentionally empty. Support is delivered at install time by
+`summer setup warp` (aliases: `warp-terminal`), which writes:
+
+- MCP config: `~/.warp/.mcp.json`; Windows `%USERPROFILE%/.warp/.mcp.json` (user); `.warp/.mcp.json` (project).
+  Shape: `mcpServers.summer-engine = { command, args }`.
+- Skills: `~/.warp/skills` (user) or `.warp/skills` (project) as `<skill>/SKILL.md`.
+- After: Warp detects the file and spawns the server; check Settings > AI > MCP servers.
+
+Source of truth: `src/installer/agent-table.ts` (one row per agent).

package/integrations/warp/manifest-target.json

@@ -0,0 +1,3 @@
+{
+  "targets": []
+}

package/integrations/windsurf/README.md

@@ -0,0 +1,12 @@
+# Devin Desktop (formerly Windsurf) integration
+
+No manifest file is generated in this repo for Devin Desktop (formerly Windsurf) — `manifest-target.json`
+is intentionally empty. Support is delivered at install time by
+`summer setup windsurf` (aliases: `devin`, `devin-desktop`, `devindesktop`), which writes:
+
+- MCP config: `~/.codeium/windsurf/mcp_config.json`; Windows `%USERPROFILE%/.codeium/windsurf/mcp_config.json` (user); user scope only (project requests fall back with a warning).
+  Shape: `mcpServers.summer-engine = { command, args }`.
+- Skills: `~/.codeium/windsurf/skills` (user) or `.windsurf/skills` (project) as `<skill>/SKILL.md`.
+- After: Restart Devin Desktop (formerly Windsurf) and refresh MCP servers from the agent settings. Devin's docs say mcp_config.json configures the Cascade agent; for the Devin agent add the server in the app's MCP settings with the same command.
+
+Source of truth: `src/installer/agent-table.ts` (one row per agent).

package/integrations/windsurf/manifest-target.json

@@ -0,0 +1,3 @@
+{
+  "targets": []
+}

package/integrations/zed/README.md

@@ -0,0 +1,12 @@
+# Zed integration
+
+No manifest file is generated in this repo for Zed — `manifest-target.json`
+is intentionally empty. Support is delivered at install time by
+`summer setup zed` (aliases: `zed-editor`), which writes:
+
+- MCP config: `~/.config/zed/settings.json`; Windows `%APPDATA%/zed/settings.json` (user); user scope only (project requests fall back with a warning).
+  Shape: `context_servers.summer-engine = { source: "custom", command, args, env }`.
+- Skills: `~/.agents/skills` (user) or `.agents/skills` (project) as `<skill>/SKILL.md`.
+- After: Zed reloads settings.json live; open the Agent panel and check summer-engine under MCP servers.
+
+Source of truth: `src/installer/agent-table.ts` (one row per agent).

package/integrations/zed/manifest-target.json

@@ -0,0 +1,3 @@
+{
+  "targets": []
+}

package/library/references/collaborative-protocol/resource.yaml

@@ -0,0 +1,24 @@
+id: reference/collaborative-protocol
+kind: reference
+version: 1.0.2
+summary: The "May I write?" protocol — before any user-visible write step, the agent states what it is about to do and asks permission.
+use_when:
+  - authoring a skill that creates or modifies project files
+  - deciding whether to ask the user before a write, deletion, or overwrite
+do_not_use_when:
+  - purely read-only inspection work with no user-visible writes
+facets:
+  lifecycle: [ build ]
+  domains:
+    - agent-workflow
+    - conventions
+compatibility:
+  engine: ">=4.6"
+related:
+  references:
+    - reference/summer-folder
+source: official
+license: MIT
+status: stable
+aliases:
+  - references/collaborative-protocol.md

package/library/references/gd-style/resource.yaml

@@ -0,0 +1,24 @@
+id: reference/gd-style
+kind: reference
+version: 1.0.2
+summary: GDScript style conventions for Summer — the tiebreaker where Godot's official style guide is silent; skills should produce code matching this.
+use_when:
+  - writing or reviewing GDScript in a Summer project
+  - authoring a skill that emits GDScript code
+do_not_use_when:
+  - writing C# (this covers GDScript conventions only)
+facets:
+  lifecycle: [ build ]
+  domains:
+    - scripting
+    - conventions
+compatibility:
+  engine: ">=4.6"
+source: official
+license: MIT
+status: stable
+aliases:
+  - references/gd-style.md
+lint_exceptions:
+  - url-allowlist
+lint_exception_reason: Body is migrated byte-identical from references/gd-style.md and cites the official Godot GDScript style guide on docs.godotengine.org (read-only documentation link).

package/{references → library/references/godot-version}/godot-version.md

@@ -10,12 +10,12 @@ Summer Engine is the product. Its current upstream technical base is **4.6.1**
 upstream continuously. These are compatibility and lineage facts. They are not
 the Summer product name or a permanent SDK version.
 
-The repository source of truth is
-`compatibility/summer-engine.json`. The running engine also reports its measured
-technical version:
+The repository source of truth is `src/core/summer-compatibility.ts`
+(`CURRENT_TECHNICAL_BASE_VERSION`, `plannedNextTechnicalBaseVersion`). The
+running engine also reports its measured technical version:
 
 ```bash
-<engineBinaryPath> --version      # measured: 4.6.1.stable.mono.custom_build.b708b1182
+<engineBinaryPath> --version      # e.g. 4.6.1.stable.mono.custom_build.<hash>
 ```
 
 Get `engineBinaryPath` from `summer_get_project_context`. Prefer live
@@ -39,7 +39,7 @@ routing, attribution, or licensing requires it.
 
 ## Summer-specific deltas from the upstream engine
 
-- Local API server runs on `localhost:6550` (set per machine via `~/.summer/api-token`).
+- Local API server runs on `localhost:6550` by default (the port increments when several editors are open; each live editor publishes its port in `~/.summer/instances/<id>.json`, and the shared token lives in `~/.summer/api-token`).
 - Engine ships a webview module in `modules/1summer_engine/`. Do not assume the
   unmodified upstream editor for UI patches.
 - Project root contains `.summer/` for project memory; do not delete it.
@@ -48,4 +48,4 @@ routing, attribution, or licensing requires it.
 
 1. Use Summer MCP tools (`summer_inspect_node`, `summer_inspect_resource`) to read live editor state instead of guessing.
 2. Use `summer_get_diagnostics` after every scene change.
-3. Check `references/mcp-tools-reference.md` for the canonical tool list.
+3. Check `library/references/mcp-tools-reference/mcp-tools-reference.md` for the canonical tool list.

package/library/references/godot-version/resource.yaml

@@ -0,0 +1,22 @@
+id: reference/godot-version
+kind: reference
+version: 1.0.2
+summary: Summer Engine compatibility facts — current upstream technical base, version-sensitive APIs, and what to check before version-sensitive code.
+use_when:
+  - writing shaders, rendering code, extensions, or export configuration
+  - deciding which engine APIs or features are safe to target
+facets:
+  lifecycle: [ build ]
+  domains:
+    - engine
+    - scripting
+compatibility:
+  engine: ">=4.6"
+related:
+  references:
+    - reference/mcp-tools-reference
+source: official
+license: MIT
+status: stable
+aliases:
+  - references/godot-version.md

package/library/references/headless-routing/headless-routing.md

@@ -0,0 +1,46 @@
+# Headless per-project routing
+
+> Full protocol contract: `docs/HEADLESS_ROUTING.md` in the Summer repo (implementation in `src/core/headless/`). This page is the agent-facing summary.
+
+## What it is
+
+An opt-in routing layer for Summer MCP tool calls. When a call targets a project, it is served by, in fixed order:
+
+1. **A live editor** that has the project open — always wins. Behavior is identical to routing being off.
+2. **A live headless worker** already registered for the project (engine-owned process registry, dead processes pruned on read).
+3. **A worker spawned on demand** — the engine binary launched in `--summer-worker` mode for that project, detached so it outlives the MCP session.
+
+Only file, import, scene-read, and game run/stop/logs/screenshot operations work on a worker. Editor-only tools (inspector, viewport snapshots, scene preview, project state) fail with a clear "not supported by the headless worker" result instead of faking an answer.
+
+## Ships dark
+
+- Enabled by `SUMMER_HEADLESS_ROUTING=1`. Unset, the module is not loaded at all and nothing changes.
+- Requires an engine build that ships the worker mode and process registry (Summer 4.7.x line). On older builds, leave the flag off.
+- With the flag on and an editor open, the editor path is used unchanged — caching, credential-drift reconnects, and identity binding all behave as before.
+
+## What an agent should expect
+
+- Errors from this layer are prefixed `[headless:<stage>]` where stage is one of `connect`, `auth`, `op`, `spawn`, so you can tell "could not reach the worker" from "the worker went quiet mid-import".
+- A first call with no editor and no worker can take up to two minutes while the worker starts and imports the project. Later calls are fast.
+- **No blind retries.** If a mutating operation (write, import, run, stop) times out or the worker connection drops, the outcome is reported as UNKNOWN and the connection is quarantined. Inspect the target (read the file, check the scene) before retrying. There is deliberately no automatic reconnect or replay.
+- Worker error strings start with a snake_case classifier (`sha256_mismatch`, `already_exists`, `needs_display`). `needs_display` on a screenshot means the machine has no display; open the project in the editor for screenshots.
+
+## Environment knobs
+
+| Variable | Purpose | Default |
+| --- | --- | --- |
+| `SUMMER_HEADLESS_ROUTING` | `1` enables the layer | unset (off) |
+| `SUMMER_ENGINE_BIN` | Engine binary to spawn workers from; this layer's own override, checked first (set but missing = no binary) | discovered |
+| `SUMMER_ENGINE_BINARY` | The shared engine-install override, honored next along with the standard install locations | discovered |
+| `SUMMER_CACHE_DIR` | Override the registry directory (test seam; both sides must honor it) | OS cache dir |
+| `SUMMER_WORKER_CONNECT_TIMEOUT_MS` | TCP connect budget | 5000 |
+| `SUMMER_WORKER_HELLO_TIMEOUT_MS` | Handshake budget | 3000 |
+| `SUMMER_WORKER_OP_TIMEOUT_MS` | Per-request inactivity budget | 30000 |
+| `SUMMER_WORKER_LONG_OP_TIMEOUT_MS` | Inactivity budget for import and game run | 300000 |
+| `SUMMER_WORKER_SPAWN_TIMEOUT_MS` | How long a spawned worker may take to register | 120000 |
+
+Timeouts are inactivity-based: an import that keeps reporting progress never times out; a silent hang still does.
+
+## Security posture (why you never see a token)
+
+The worker and the client authenticate each other with hashes over a per-connection nonce; the registry token never crosses the wire and never appears in any error or log. The registry file is trusted only if it is a regular file under 512KiB, and every entry is verified against the live process before use.

package/library/references/headless-routing/resource.yaml

@@ -0,0 +1,24 @@
+id: reference/headless-routing
+kind: reference
+version: 1.0.0
+summary: How MCP tool calls reach a project with no editor open — editor, then live headless worker, then spawned worker — behind SUMMER_HEADLESS_ROUTING=1.
+use_when:
+  - a Summer MCP tool call must run against a project that no editor has open (CI, servers, scripting loops)
+  - deciding whether SUMMER_HEADLESS_ROUTING should be enabled for a session and what changes when it is
+  - a tool result mentions a headless worker, a [headless:<stage>] error, or an outcome-unknown quarantine
+do_not_use_when:
+  - the project is already open in the Summer editor — routing is inert and the editor path serves the call unchanged
+  - looking up which MCP tool to call — that is the mcp-tools-reference
+facets:
+  lifecycle: [build]
+  domains: [mcp, engine, headless]
+compatibility:
+  engine: ">=4.7"
+related:
+  references:
+    - reference/mcp-tools-reference
+source: official
+license: MIT
+status: preview
+aliases:
+  - docs/HEADLESS_ROUTING.md