git:20261016.cf84037 to git:20261017.26864a9
26 added, 24 removed. Audit A to A.
# AGENTS.md — Godot-AI-Tools-Template
- **Template repo** for Godot-MCP extension packages (the Godot analog of `Unity-AI-Tools-Template`).
- `commands/init.ps1` / `init.py` turn its placeholder boilerplate into a real extension, so every change
- here propagates to future extensions — keep placeholder tokens consistent.
+ **Template** for Godot-MCP extension packages (the Godot analog of `Unity-AI-Tools-Template`). An extension
+ is an **RQL module**: it teaches the core `rql-query` / `rql-mutate` / `rql-schema` tools about a Godot feature
+ (adapters, sources, methods, a guide) instead of adding MCP tools. `scripts/new_extension.py` (monorepo) or
+ `commands/init.ps1` / `init.py` turn the placeholder boilerplate into a real extension, so every change here
+ propagates to future extensions — keep placeholder tokens consistent.
## Placeholders (replaced by `init`)
| Token | Example value | Used in |
| --- | --- | --- |
- | `YOUR_FEATURE` | `Particles` | namespaces, `Tool_<Feature>`, folder/file names, the package id suffix |
- | `YOUR_TOOL_PREFIX` | `particles` | tool ids (`<prefix>-echo`, …) |
- | `YOUR_DISPLAY_NAME` | `Particles Tools` | package `Title`, docs |
- | `YOUR_DESCRIPTION` | `AI MCP tools for Godot Particles.` | package `Description` |
+ | `YOUR_FEATURE` | `Particles` | namespaces, `<Feature>Module` / `Guide` / `Api`, folder/file names, the package id suffix |
+ | `YOUR_SOURCE` | `particles` | the RQL source name of the sample module (`--source-name` / `-SourceName`) |
+ | `YOUR_DISPLAY_NAME` | `Particles Tools` | package `Title`, the guide topic, docs |
+ | `YOUR_DESCRIPTION` | `RQL module for Godot Particles.` | package `Description` |
| `YOUR_GITHUB_USERNAME_REPOSITORY` | `IvanMurzak/Godot-AI-Particles` | repo URLs |
The package id is always `com.IvanMurzak.Godot.MCP.<Feature>`, written literally as
`com.IvanMurzak.Godot.MCP.YOUR_FEATURE`. `init` also renames `build/<id>.props` and activates CI
(`*.yml-sample` → `*.yml`).
## Layout
- `src/Godot-AI-YOUR_FEATURE/` — the source-only package (`Godot.NET.Sdk`).
- - `Runtime/Tools/` — `[AiToolType]` root + pure-managed tools (outside `#if TOOLS`, unit-testable).
- - `Editor/Tools/` — editor-driving tools (behind `#if TOOLS`, main-thread-marshalled, E2E-verified only).
+ - `Editor/Rql/YOUR_FEATUREModule.cs` — the `IRqlModule` (behind `#if TOOLS`): adapters, sources, guide.
+ - `Editor/Rql/YOUR_FEATUREApi.cs` — the sample `YOUR_SOURCE` source (a view object, `#if TOOLS`).
+ - `Editor/Rql/YOUR_FEATUREGuide.cs` — the agent guide; pure strings, NOT behind `#if TOOLS` (unit-tested).
- `build/com.IvanMurzak.Godot.MCP.YOUR_FEATURE.props` — source-injection props (must stay `<PackageId>.props`).
- - `tests/Godot-AI-YOUR_FEATURE.Tests/` — xUnit specs for pure-managed sources only; add each new one to
- the test csproj `<Compile Include>` list.
- - `tests/e2e/` — live `run-tool` E2E driver (`run_tool_e2e.py`) + per-extension tool list (`e2e-tools.json`).
+ - `tests/Godot-AI-YOUR_FEATURE.Tests/` — xUnit over the module sources (`TOOLS` defined, GodotSharp metadata only); the
+ guide checks come from `extensions/Shared/Tests/GuideExampleTests.cs`, linked by the test csproj.
+ - `tests/e2e/e2e-tools.json` — the live calls that run every guide example (driver: `scripts/extension_e2e.py`).
- `testbed/` — consumer `Godot.NET.Sdk` project restoring the local-packed package (injection proof).
- `commands/` — `init`, `bump-version`, `update-core` (`.ps1` + `.py`), `get-version.ps1`.
- `.github/workflows/*.yml-sample` — CI, inert until `init`. Never commit live `.github/workflows/*.yml` here.
- - `docs/` — `source-only-nuget-recipe.md` (the packaging recipe, the centerpiece, + consumer story);
- `ci.md` (workflows, version gate, multi-Godot matrix, the NuGet Trusted Publishing).
- - `README.md` — user walkthrough: scaffold → init → write → build/test → publish → install.
+ - `docs/` — `source-only-nuget-recipe.md` (the packaging recipe + consumer story); `ci.md`.
## Build / test (no Godot binary)
```bash
- dotnet build src/Godot-AI-YOUR_FEATURE/Godot-AI-YOUR_FEATURE.csproj # source-only package compiles tools
+ dotnet build src/Godot-AI-YOUR_FEATURE/Godot-AI-YOUR_FEATURE.csproj # the module compiles (Debug: #if TOOLS too)
dotnet test tests/Godot-AI-YOUR_FEATURE.Tests/Godot-AI-YOUR_FEATURE.Tests.csproj
dotnet pack src/Godot-AI-YOUR_FEATURE/Godot-AI-YOUR_FEATURE.csproj -p:Version=0.0.0-ci -o local-nuget
dotnet build testbed/YOUR_FEATURE-Testbed.csproj # consumes the local package (injection proof)
```
- `Godot.NET.Sdk` supplies GodotSharp from NuGet, so build/test/pack and the source-injection proof need no
- Godot install (the testbed build is a faithful proxy for `godot --build-solutions`).
-
## Conventions
- - Root namespace `com.IvanMurzak.Godot.MCP.<Feature>` (mirrors the core addon).
- - One `[AiToolType] partial class Tool_<Feature>`; one `[AiTool]` method per partial-class file.
- - Core MCP pins (`com.IvanMurzak.McpPlugin`, `com.IvanMurzak.ReflectorNet`) must match the core Godot-MCP
- addon; bump everywhere with `commands/update-core.ps1`. GodotSharp must never become a package dep (see
- the recipe; CI asserts it).
+ - Root namespace `com.IvanMurzak.Godot.MCP.<Feature>`. One adapter per file, named `Godot_<Type>_Adapter`.
+ - The module uses only Godot, `com.IvanMurzak.Rql` and the BCL — never core-addon types: the authoring build
+ compiles without the core, and the core discovers the module by `IRqlModule` in the consumer assembly.
+ - Undo and saving come from the core: a `set` or a call on a node / resource records its stored Godot
+ properties, so put a method on the object it changes. Validate values in adapters (`validate:`) instead of
+ clamping them: a rejected value fails the whole mutation.
+ - Every guide example runs in `tests/e2e/e2e-tools.json` (xUnit-asserted, in order); keep them runnable.
+ - Core pins (`McpPlugin`, `ReflectorNet`, `Rql`) equal the core addon's (`core_pin_drift` fails CI otherwise); bump with
+ `commands/update-core.ps1`. GodotSharp must never become a package dep (see the recipe; CI asserts it).