auvrynt 1.0.2 → 1.0.5

package/guides/GODOT_AGENT_GUIDE.md

@@ -0,0 +1,298 @@
+# GODOT_AGENT_GUIDE.md
+
+## Scope
+
+This guide applies to Godot 4 game development projects. It covers C#, GDScript, and mixed C#/GDScript projects. The Godot project remains the primary project type whenever a `project.godot` file exists.
+
+Do not edit `.godot/imported` manually.
+Do not edit binary `.scn` or `.res` files directly.
+Do not use generic `.NET` tools (like `dotnet run`) to launch a Godot game; use Godot-specific tools.
+
+---
+
+## Language Routing
+
+Before modifying or inspecting files, identify the script language:
+
+- **`.gd` files:** Use GDScript diagnostics, GDScript editing rules, and GDScript debugger/LSP tools.
+- **`.cs` files:** Use Godot C# build, Roslyn/LSP, C# exception parser, and C# semantic definitions.
+- **Scenes and resource files (`.tscn`, `.tres`):** Use the shared Godot editor bridge and Inspector APIs.
+- **Mixed projects:** Validate both C# build and GDScript parsing when changes span both boundaries.
+
+---
+
+## Shared Godot Capabilities
+
+- Project and executable discovery.
+- Headless project validation & asset reimporting.
+- Persistent process management for running projects/scenes.
+- Runtime logs and error categorization.
+- Live editor bridge (connect, status, disconnect).
+- Edited/remote scene tree mutation and property editing (using UndoRedo).
+- Performance monitors (FPS, memory, nodes).
+- Input injection & visual gameplay assertions (screenshots, node existence).
+- Export presets listing and headless exporting.
+
+---
+
+## GDScript Development Rules
+
+### Editing & Syntax
+- Use Godot 4 syntax rules (e.g. `await` instead of `yield`, modern annotations like `@onready`, `@export`).
+- Preserve the existing indentation style (tabs vs spaces) and static typing conventions.
+- Use snake_case for methods/variables, PascalCase for `class_name` definitions.
+- Only add `@tool` or `class_name` when explicitly requested or necessary.
+- Avoid calling `get_node()` (or `$`) inside expensive callbacks like `_process()` or `_physics_process()`; cache them using `@onready` instead.
+- Use `_physics_process()` for frame-independent movement/physics updates.
+- Respect object lifetimes; use `is_instance_valid()` before accessing potentially freed objects.
+- Use deferred calls (`call_deferred()`) when mutating the scene tree inside signal handlers or physics callbacks.
+
+---
+
+## Godot C# Development Rules
+
+### Editing & Syntax
+- Use partial classes for nodes (e.g. `public partial class Player : CharacterBody2D`).
+- Preserve namespace structure and naming conventions.
+- Avoid calling `GetNode()` repeatedly inside `_Process()` or `_PhysicsProcess()`.
+- Use `_PhysicsProcess(double delta)` for physics updates.
+- Respect Godot object lifetimes and call `Dispose()` or `QueueFree()` when freeing nodes.
+- Do not translate GDScript API names blindly (e.g. GDScript `queue_free()` becomes C# `QueueFree()`).
+
+---
+
+## Prerequisites
+
+| Requirement | Notes |
+|---|---|
+| **Godot 4.2+ with .NET** | Must be the `mono`/`.NET`-enabled build (e.g. `Godot_v4.x.x-stable_mono_win64`) |
+| **.NET SDK 8.0+** | Required for C# compilation |
+| **Auvrynt server** | Running and connected to your AI client |
+| **Auvrynt workspace** | Opened via `open_workspace` pointing to your Godot project root |
+
+---
+
+## Environment Variables
+
+Set these to help Auvrynt find the right Godot executable:
+
+```sh
+# Preferred: Godot .NET-enabled executable
+set GODOT_DOTNET_EXECUTABLE=C:\Godot\Godot_v4.4_mono_win64.exe
+
+# Fallback if above is not set
+set GODOT_EXECUTABLE=C:\Godot\Godot_v4.4_stable_win64.exe
+```
+
+---
+
+## Quick Start — New Project
+
+```
+1. open_workspace({ path: "/path/to/my-godot-game" })
+2. godot_dotnet_environment({ workspaceId })        # verify setup
+3. inspect_godot_dotnet_project({ workspaceId })    # check project health
+4. godot_dotnet_restore({ workspaceId, projectPath: "." })
+5. godot_dotnet_build({ workspaceId, projectPath: "." })
+6. godot_run_project({ workspaceId, projectPath: ".", debug: true })
+7. godot_get_runtime_logs({ workspaceId, processId })
+```
+
+---
+
+## Editor Bridge Setup
+
+The editor bridge enables live scene-tree inspection and node mutation from Auvrynt while the Godot editor is open.
+
+### Setup
+
+1. **Copy the plugin** into your project:
+   ```
+   addons/auvrynt_bridge/auvrynt_bridge.gd
+   addons/auvrynt_bridge/plugin.cfg
+   ```
+
+2. **Enable the plugin** in Godot:
+   `Project → Project Settings → Plugins → AuvryntBridge → Enable`
+
+3. **Connect from Auvrynt**:
+   ```
+   godot_editor_connect({
+     workspaceId,
+     projectPath: ".",
+     token: "<printed in Godot Output panel>"
+   })
+   ```
+   The token is printed in the Godot **Output** panel when the plugin starts:
+   ```
+   [AuvryntBridge] Listening on 127.0.0.1:49322  token=12345678
+   ```
+
+4. **Verify connection**:
+   ```
+   godot_editor_status({ workspaceId })
+   ```
+
+### Bridge Methods
+
+| Tool | Method | Notes |
+|---|---|---|
+| `godot_get_scene_tree` | `scene.get_tree` | Edited scene tree |
+| `godot_get_scene_tree` (mode=remote) | `remote.get_scene_tree` | Running game tree |
+| `godot_get_runtime_property` | `remote.get_property` | Live runtime value |
+| `godot_get_performance_monitors` | `remote.get_performance_monitors` | FPS, memory, node count |
+| `godot_assert_node_exists` | `remote.get_node` | Pass/fail node check |
+| `godot_assert_property` | `remote.get_property` + comparison | Gameplay assertion |
+| `godot_press_action` | `input.press_action` | Input simulation |
+
+---
+
+## Complete Tool Reference
+
+### Environment & Project
+
+| Tool | What it does |
+|---|---|
+| `godot_dotnet_environment` | Detect executable, .NET SDK, architecture |
+| `inspect_godot_dotnet_project` | Inspect `.csproj`, `.sln`, autoloads, scripts |
+
+### Build & Restore
+
+| Tool | What it does |
+|---|---|
+| `godot_build_solutions` | Regenerate `.sln`/`.csproj` (run after adding C# files) |
+| `godot_dotnet_restore` | NuGet restore |
+| `godot_dotnet_build` | C# build, returns structured diagnostics |
+| `godot_dotnet_clean` | Remove `bin/` and `obj/` |
+
+### Running
+
+| Tool | What it does |
+|---|---|
+| `godot_run_project` | Launch project as tracked persistent process |
+| `godot_run_scene` | Launch a single `.tscn` scene |
+| `godot_stop` | Stop a tracked Godot process |
+| `godot_get_runtime_logs` | Structured runtime log categorization |
+
+### Validation & Import
+
+| Tool | What it does |
+|---|---|
+| `godot_validate_project` | Headless validation: imports, scripts, plugins |
+| `godot_import_assets` | Force headless reimport |
+
+### Editor Bridge
+
+| Tool | What it does |
+|---|---|
+| `godot_editor_connect` | Connect to Godot editor plugin |
+| `godot_editor_status` | Check connection |
+| `godot_editor_disconnect` | Disconnect |
+| `godot_get_scene_tree` | Scene tree (edited or remote) |
+| `godot_get_runtime_property` | Read live runtime property |
+| `godot_get_performance_monitors` | FPS, memory, physics timing |
+
+### C# Semantics
+
+| Tool | What it does |
+|---|---|
+| `godot_find_csharp_class` | Find class by name, get `[Export]`, `[Signal]`, overrides |
+| `godot_get_exported_properties` | List `[Export]` properties on a script |
+| `godot_get_csharp_diagnostics` | Scan for anti-patterns |
+
+### Project Settings & Configuration
+
+| Tool | What it does |
+|---|---|
+| `godot_get_project_settings` | Read all `project.godot` settings |
+| `godot_get_input_map` | List input actions |
+| `godot_get_autoloads` | List autoloads |
+| `godot_apply_pixel_art_import_preset` | Nearest-neighbour, lossless, no mipmaps |
+| `godot_generate_vscode_config` | Create `.vscode/tasks.json` + `.vscode/launch.json` |
+
+### Export
+
+| Tool | What it does |
+|---|---|
+| `godot_list_export_presets` | List export presets from `export_presets.cfg` |
+| `godot_export_project` | Export using named preset |
+
+### Testing & Assertions
+
+| Tool | What it does |
+|---|---|
+| `godot_assert_node_exists` | Assert node exists in remote scene tree |
+| `godot_assert_property` | Assert runtime property value (`eq`, `neq`, `gt`, `lt`, `approx`, `contains`, `exists`) |
+| `godot_run_test_sequence` | Automated gameplay sequence (max 50 steps, 30s) |
+| `godot_press_action` | Inject input action via bridge |
+
+### Visuals
+
+| Tool | What it does |
+|---|---|
+| `godot_capture_game` | Screenshot a running Godot window |
+| `view_image` | Load and inspect an image file |
+| `inspect_image` | Analyse pixel dimensions, palette, format |
+| `inspect_sprite` | Detect animation frames in sprite sheets |
+
+---
+
+## Recommended Workflow
+
+1. Open workspace and inspect project languages.
+2. If C# is present, compile C# using `godot_dotnet_build`.
+3. Run headless project validation using `godot_validate_project`.
+4. Inspect the active scene or node properties via the editor bridge.
+5. Make minimal changes to scripts. Validate syntax.
+6. Launch the project or active scene as a persistent process.
+7. Inject input or test gameplay behavior using assertions.
+8. Capture gameplay window screenshot to verify visually.
+9. Stop the game process when finished.
+
+---
+
+## Security Model
+
+- **Path resolution**: All file paths are resolved via `workspaces.resolvePath` — reading outside the opened workspace root is blocked.
+- **Process tracking**: Processes are tracked by `workspaceId` + `processId`. Stopping a process from a different workspace is not permitted.
+- **Editor bridge**: Runs on `127.0.0.1` only. Requires a per-session token printed in the Godot output panel. Never accepts external connections.
+- **NuGet restore**: Credentials are redacted from output before returning to the AI client.
+- **Export**: Output path must resolve inside the opened workspace.
+
+---
+
+## Serena (Semantic Code)
+
+Serena provides language-aware symbol navigation for Godot C# and GDScript source files.
+
+**Use Serena for:**
+- C# or GDScript source navigation when supported reliably
+- References and symbol structure
+- Code-level refactoring
+
+**Do not use Serena for:**
+- Scene tree, Inspector, resources, animations, TileMap, collision
+- Remote runtime tree, game input, screenshots, exports
+
+**Use:**
+- Godot editor bridge → scenes/resources/runtime
+- Serena → semantic source navigation (`serena_find_symbol`, `serena_find_referencing_symbols`, etc.)
+- Godot/.NET diagnostics → build/parser truth (`godot_dotnet_build`, `godot_get_gdscript_diagnostics`)
+
+Do not replace Godot's GDScript LSP integration with Serena unless tests prove equivalent behavior.
+
+---
+
+## Troubleshooting
+
+### `GODOT_DOTNET_EXECUTABLE not set`
+Set the env var (see above) or run `godot_dotnet_environment` to see what was auto-detected.
+
+### `Build failed: Godot.NET.Sdk not found`
+Run `godot_build_solutions` first to generate the `.csproj`. This requires the Godot editor executable to be available.
+
+### `Editor bridge: connection refused`
+Make sure the Auvrynt Bridge plugin is enabled and the Godot editor is open with the project loaded. Copy the token from the Godot Output panel.
+
+### `Node not found` errors
+The `nodePath` must be relative to the scene root (e.g. `Player/Sprite2D`), not absolute. For remote tree queries, the game must be running.

package/guides/PROJECT_ROUTER.md

@@ -0,0 +1,165 @@
+# PROJECT_ROUTER.md
+
+## Purpose
+
+Read this file first before any development work. Detect the active project or subproject, then load **only** the relevant guide. Do not load all guides by default.
+
+Available guides: `WEB_AGENT_GUIDE.md`, `SOFTWARE_AGENT_GUIDE.md`, `GODOT_AGENT_GUIDE.md`, `BLENDER_AGENT_GUIDE.md`, `ASEPRITE_AGENT_GUIDE.md`, `ROBLOX_AGENT_GUIDE.md` (all in this `guides/` directory).
+
+---
+
+## Project Detection
+
+Inspect the workspace root for these indicators:
+
+### Blender indicators (highest priority for 3D asset work)
+- `.blend`, `.blend1`
+- Python scripts importing `bpy`
+- `blender_manifest.toml`
+- `addons/` with `plugin.cfg` and `__init__.py`
+- Blender asset library directories
+- Explicit user request mentioning Blender, 3D modeling, rigging, rendering, or UV mapping
+
+### Aseprite indicators (highest priority for pixel-art asset work)
+- `.aseprite`, `.ase`
+- Aseprite Lua scripts
+- Explicit user request mentioning Aseprite, exact pixel drawing, sprite animation, palettes, layers, tags, or frame timing
+
+### Godot indicators
+- `project.godot`
+- `*.tscn`, `*.tres`, `*.gd`
+- `*.cs` (combined with `project.godot`)
+- `export_presets.cfg`
+- `.godot/`
+
+### Web indicators
+- `package.json`
+- `vite.config.*`, `next.config.*`, `nuxt.config.*`, `angular.json`, `astro.config.*`, `svelte.config.*`
+- `index.html` in root or `public/`
+- `src/` with `.tsx`, `.vue`, `.svelte` files
+
+### General software / .NET indicators
+- `*.sln`, `*.csproj`, `*.fsproj`, `*.vbproj`
+- `Directory.Build.props`, `Directory.Packages.props`, `global.json`
+- `src/` with `.cs` / `.fs` files (without `project.godot`)
+- `tests/`, `test/`
+
+---
+
+## Routing Rules
+
+### Rule 1 — Godot project
+If `project.godot` exists:
+- **Primary guide**: `GODOT_AGENT_GUIDE.md`
+- If `.cs` or `.csproj` also exists → use Godot C# sections of `GODOT_AGENT_GUIDE.md`
+- If `.gd` exists → use GDScript sections of `GODOT_AGENT_GUIDE.md`
+- If both → use mixed-language rules in `GODOT_AGENT_GUIDE.md`
+- `SOFTWARE_AGENT_GUIDE.md` is secondary only for generic .NET operations outside Godot
+- If source `.blend` files exist alongside → load `BLENDER_AGENT_GUIDE.md` **only for the Blender asset task**
+- Do not use browser tools unless the project has an actual web UI
+
+### Rule 2 — Web project (no `project.godot`)
+If project is clearly a website or web application:
+- **Primary guide**: `WEB_AGENT_GUIDE.md`
+- Do not load Godot tools
+- Load `SOFTWARE_AGENT_GUIDE.md` only for backend/service component of the same task
+- If `.blend` source assets exist → load `BLENDER_AGENT_GUIDE.md` only when editing that asset
+
+### Rule 3 — General software / .NET
+If project is a desktop app, CLI, API, service, library, or non-Godot .NET project:
+- **Primary guide**: `SOFTWARE_AGENT_GUIDE.md`
+- Do not use Godot tools
+- Do not use browser tools unless the app exposes a web interface
+
+### Rule 4 — Blender-only
+If primary task involves 3D modeling, rendering, material, rigging, animation, UV mapping, or export:
+- **Primary guide**: `BLENDER_AGENT_GUIDE.md`
+- Do not load web, Godot, or software tools unless the task explicitly crosses into those domains
+
+### Rule 5 — Aseprite / pixel-art assets
+If the primary task involves exact pixel editing, sprite animation, layers, palettes, tags, or Aseprite export:
+- **Primary guide**: `ASEPRITE_AGENT_GUIDE.md`
+- Use native `aseprite_*` tools rather than a GUI plugin unless live editor state is explicitly required.
+- If the sprite belongs to a Godot project, use `GODOT_AGENT_GUIDE.md` only for the engine-side import/runtime task.
+- Do not use image-generation tools as a substitute for exact pixel edits.
+
+### Rule 6 — Monorepo
+Identify the active subproject from the user request. Read only that subproject's guide. Refresh project state when switching subprojects.
+
+Example layout:
+```
+apps/web/          → WEB_AGENT_GUIDE.md
+games/rpg/         → GODOT_AGENT_GUIDE.md (contains project.godot)
+services/api/      → SOFTWARE_AGENT_GUIDE.md
+assets/characters/ → BLENDER_AGENT_GUIDE.md (.blend files)
+```
+
+### Rule 7 — Unclear
+Inspect only the smallest useful set of root files. State which guide was selected and why. Do not scan the entire repository.
+
+---
+
+## Context Efficiency
+
+- Never load all guides together for a single-project task.
+- Prefer one primary guide per task.
+- Add a secondary guide only when the task genuinely crosses project boundaries.
+- Keep irrelevant tool schemas out of context.
+
+---
+
+## Expected Agent Behavior
+
+> Before making changes, classify the active project or subproject.  
+> Load only the relevant development guide.  
+> Use the smallest set of tools needed for the current task.  
+> Never invent unavailable tools or claim unverified results.
+
+---
+
+## Routing Quick Reference
+
+| Evidence | Guide |
+|---|---|
+| `project.godot` | GODOT_AGENT_GUIDE.md |
+| `package.json` + `vite.config.*` | WEB_AGENT_GUIDE.md |
+| `*.sln` / `*.csproj` (no `project.godot`) | SOFTWARE_AGENT_GUIDE.md |
+| `.blend` / `bpy` scripts / explicit Blender request | BLENDER_AGENT_GUIDE.md |
+| `.aseprite` / `.ase` / explicit pixel-art animation request | ASEPRITE_AGENT_GUIDE.md |
+| Godot project + `.blend` source asset task | GODOT_AGENT_GUIDE.md primary, BLENDER_AGENT_GUIDE.md secondary |
+| Web project + `.blend` source asset task | WEB_AGENT_GUIDE.md primary, BLENDER_AGENT_GUIDE.md secondary |
+
+## Serena (Semantic Code Engine)
+
+Serena is a local semantic code analysis engine accessible through Auvrynt. It provides symbol-aware navigation and editing across supported languages.
+
+**Use Serena when:**
+- Locating symbols in a large codebase
+- Understanding class/function/component structure
+- Finding definitions and references
+- Tracing cross-file dependencies
+- Performing symbol-aware insertion or replacement
+- Safely renaming symbols
+- Navigating monorepos
+- Inspecting unfamiliar architecture
+
+**Do not use Serena for:**
+- Simple exact text replacement (use Auvrynt edit tools)
+- Reading a small known file (use Auvrynt read tools)
+- Starting servers, process logs, browser DOM, console errors, network requests, screenshots, visual comparison, image inspection
+- Godot scene-tree operations or Blender scene/object operations
+- Git commands
+
+**Routing:**
+- Need semantic code structure? → Start a Serena session with `serena_start_session`, then use `serena_find_symbol`, `serena_find_referencing_symbols`, etc.
+- Need ordinary file/config inspection? → Auvrynt workspace tools
+- Need runtime behavior? → Auvrynt process/browser/Godot/Blender tools
+- Need visual evidence? → Auvrynt screenshot/image tools
+
+To enable Serena, set `AUVRYNT_SERENA_ENABLED=true` or add `"serena": { "enabled": true }` to Auvrynt config.
+
+---
+
+## Nested Instruction Files
+
+If a subdirectory contains its own `AGENTS.md` or `CLAUDE.md`, those instructions override root-level guidance for that subdirectory.

package/guides/ROBLOX_AGENT_GUIDE.md

@@ -0,0 +1,75 @@
+# ROBLOX_AGENT_GUIDE.md
+
+## Scope
+
+Official **Roblox Studio MCP** proxy through Auvrynt (Option A).
+
+This is **not** a community HTTP plugin bridge. Auvrynt spawns Studio\'s built-in stdio MCP launcher and re-exports tools as `roblox_*`.
+
+## Prerequisites
+
+1. Latest **Roblox Studio** installed
+2. In Studio: **Assistant → … → Manage MCP Servers → Enable Studio as MCP server**
+3. Launcher present:
+   - Windows: `%LOCALAPPDATA%\Roblox\mcp.bat`
+   - macOS: `/Applications/RobloxStudio.app/Contents/MacOS/StudioMCP`
+4. Start Auvrynt with the Roblox profile:
+
+```bash
+auvrynt start roblox
+# aliases: robloxstudio, rbx
+# can combine: auvrynt start web,roblox
+```
+
+## Primary tools
+
+| Tool | Purpose |
+|------|--------|
+| `roblox_status` | Launcher path, connection, tool list probe |
+| `roblox_list_tools` | Full remote tool inventory + schemas |
+| `roblox_call` | Generic proxy (`tool` + `arguments`) |
+| `roblox_disconnect` | Close stdio session |
+| `roblox_<official_name>` | Convenience aliases for documented Studio tools |
+
+Documented Studio tools (prefix with `roblox_`): `script_read`, `multi_edit`, `script_search`, `script_grep`, `search_game_tree`, `inspect_instance`, `execute_luau`, `get_studio_state`, `start_stop_play`, `get_console_output`, `screen_capture`, `list_roblox_studios`, `set_active_studio`, asset/generation tools, input simulation, `http_get`, `skill`, etc.
+
+Official docs: https://create.roblox.com/docs/studio/mcp
+
+## Workflow
+
+1. Open the place in Roblox Studio (MCP enabled).
+2. Ensure Auvrynt is running with `roblox` profile.
+3. Call `roblox_status` — expect `ok: true` and a non-empty tool list.
+4. Use `roblox_list_tools` when argument shapes are unclear.
+5. Prefer specific `roblox_*` aliases or `roblox_call` for actions.
+6. Keep Studio open; reconnect with another status/call if Studio restarts.
+
+## Rules
+
+- Never invent Studio tool names beyond what `roblox_list_tools` / `roblox_status` report.
+- Studio owns the DataModel; Auvrynt only proxies MCP.
+- Multiple Studio windows: use `roblox_list_roblox_studios` + `roblox_set_active_studio`.
+- OAuth scope: `auvrynt:roblox`.
+
+## Troubleshooting
+
+- Launcher missing → update Studio; enable MCP in Assistant settings.
+- Tools fail → restart Studio and Auvrynt; confirm green MCP client indicator in Studio.
+- Linux → official Studio MCP is Windows/macOS oriented; status will say so.
+
+## Helper tools (Auvrynt, via execute_luau)
+
+| Tool | Purpose |
+|------|--------|
+| `roblox_create_instance` | Instance.new + optional props |
+| `roblox_destroy_instance` | Destroy by path |
+| `roblox_clone_instance` | Clone (+ optional parent/name) |
+| `roblox_set_parent` | Reparent |
+| `roblox_rename_instance` | Rename |
+| `roblox_set_properties` | Set properties |
+| `roblox_set_attribute` | SetAttribute |
+| `roblox_set_lighting` | Lighting service props |
+| `roblox_fill_terrain` | Terrain:FillBlock |
+| `roblox_clear_terrain` | Terrain:Clear |
+| `roblox_create_screen_gui` | ScreenGui under StarterGui |
+

package/guides/SOFTWARE_AGENT_GUIDE.md

@@ -0,0 +1,104 @@
+# SOFTWARE_AGENT_GUIDE.md
+
+## Scope
+
+This guide applies to general software development projects, including:
+- C#/.NET desktop applications, APIs, libraries, CLI tools, services, and background workers
+- Non-Godot projects using C#/.NET
+- General backend software tasks
+
+Do not use Godot scene-tree or inspector tools unless a `project.godot` exists and is active.
+Do not use web browser/screenshot tools unless the application exposes a web API/UI.
+
+---
+
+## Primary Tools
+
+**Workspace & Search**
+- open workspace, read file, edit file, write file
+- file search, text search, project inspection
+- C# symbol definitions, references, and definitions lookup
+
+**C#/.NET Core Tools**
+- `inspect_dotnet_project`
+- `dotnet_restore`
+- `dotnet_build`
+- `dotnet_test`
+- `dotnet_run`
+- `dotnet_format`
+- `get_csharp_diagnostics`
+
+**Serena Semantic Tools** (when Serena is enabled)
+- `serena_start_session` — start a Serena session for the workspace
+- `serena_find_symbol` — locate a symbol by name
+- `serena_find_referencing_symbols` — find all references to a symbol
+- `serena_get_symbols_overview` — overview of symbols in a file
+- `serena_search_for_pattern` — language-aware pattern search
+- `serena_find_implementations` — find implementations
+- `serena_find_declaration` — find declaration
+- `serena_get_diagnostics_for_file` — LSP diagnostics for a file
+- `serena_get_diagnostics_for_symbol` — diagnostics for a symbol
+- `serena_replace_symbol_body` — replace symbol body (controlled mutation)
+- `serena_insert_before_symbol` — insert code before a symbol
+- `serena_insert_after_symbol` — insert code after a symbol
+- `serena_rename_symbol` — rename symbol across the project
+- `serena_safe_delete_symbol` — delete symbol with safety checks
+
+**Process management**
+- start process (for persistent background services or long-running APIs)
+- get process logs
+- list processes
+- stop process
+
+---
+
+## Required Workflow
+
+1. **Inspect Solution/Project:** Read `.sln` or `.csproj` files to identify target frameworks, dependencies, and project structure.
+2. **Determine Target Frameworks:** Identify whether the project targets `.NET Core / Standard / Framework` or specific operating systems.
+3. **Restore Dependencies:** Run `dotnet_restore` when starting or when project references/dependencies change. Do not run repeatedly.
+4. **Compile & Build:** Execute `dotnet_build` to catch compilation errors. Fix diagnostics returned semantically.
+5. **Run Tests:** Execute targeted unit/integration tests using `dotnet_test` (with filter arguments to run specific tests if needed).
+6. **Lsp & Semantics:** Prefer Roslyn/LSP symbol definition and reference tracking over plain text search when navigating code.
+7. **Clean execution:** For long-running apps, use persistent process tools rather than blocking shell commands.
+
+---
+
+## Software-Specific Rules
+
+- **Do not rewrite entire project files** unless modifying configuration/dependencies is explicitly requested.
+- **Do not add packages** or dependencies without necessity.
+- **Do not change target frameworks** casually.
+- **Do not expose secrets** or credentials in code, environments, or logs.
+- **Do not claim tests passed** unless they were actually executed and returned a successful exit code.
+- Prefer semantic C# refactorings and structural symbol navigation over simple regex replacement.
+- For long-running processes, capture logs and check for stack traces or unhandled exceptions.
+
+---
+
+## Verification Checklist
+
+- [ ] Project restores without NuGet errors.
+- [ ] Build completes with 0 errors and warning counts checked.
+- [ ] Targeted tests run and pass.
+- [ ] Code formatting verified with linter or `dotnet_format`.
+- [ ] Process starts, listens on designated ports (if API), and logs are clean of exceptions.
+- [ ] Code compiles cleanly on target frameworks.
+
+---
+
+## Serena Routing
+
+Use Serena for semantic navigation when the backend supports the language.
+
+- Use Roslyn/Auvrynt .NET tools for authoritative C# diagnostics.
+- Avoid duplicate semantic edits from Serena and Roslyn in the same step.
+- Choose one semantic mutation owner per operation.
+- Refresh both services after edits when both are active.
+
+For C#:
+- Compiler/build truth → .NET tools (`dotnet_build`, `inspect_dotnet_project`)
+- Semantic navigation → Serena (`serena_find_symbol`, `serena_find_referencing_symbols`, etc.)
+- Debugger → DAP
+
+Do not claim Serena alone proves a C# build succeeds. Always run `dotnet_build` to verify.