Serena project upgrade (#816)

* Serena project upgrade

* Apply two suggestions from Copilot code review

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* Update Serena config and setup guidance

---------

Co-authored-by: papeh <hasso_pape@sil.org>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Author: 3 people

.serena/.gitignore

@@ -1,2 +1,3 @@
 /cache
 /logs
+/project.local.yml

.serena/project.yml

@@ -1,27 +1,28 @@
+
+
 # list of languages for which language servers are started; choose from:
-#   al               bash             clojure          cpp              csharp           csharp_omnisharp
-#   dart             elixir           elm              erlang           fortran          go
-#   haskell          java             julia            kotlin           lua              markdown
-#   nix              perl             php              python           python_jedi      r
-#   rego             ruby             ruby_solargraph  rust             scala            swift
-#   terraform        typescript       typescript_vts   zig
+#   al                  bash                clojure             cpp                 csharp
+#   csharp_omnisharp    dart                elixir              elm                 erlang
+#   fortran             fsharp              go                  groovy              haskell
+#   java                julia               kotlin              lua                 markdown
+#   matlab              nix                 pascal              perl                php
+#   php_phpactor        powershell          python              python_jedi         r
+#   rego                ruby                ruby_solargraph     rust                scala
+#   swift               terraform           toml                typescript          typescript_vts
+#   vue                 yaml                zig
+#   (This list may be outdated. For the current list, see values of Language enum here:
+#   https://github.com/oraios/serena/blob/main/src/solidlsp/ls_config.py
+#   For some languages, there are alternative language servers, e.g. csharp_omnisharp, ruby_solargraph.)
 # Note:
 #   - For C, use cpp
 #   - For JavaScript, use typescript
-# Language Server Details (Serena AUTO-DOWNLOADS these on first startup):
-#   - csharp: Uses Microsoft.CodeAnalysis.LanguageServer (Roslyn) - same engine as VS Code's C# extension
-#     Downloads from Azure NuGet feed; also downloads .NET 9 runtime if needed
-#     ⚠️ KNOWN ISSUE: Fails on T-Mobile Home Internet due to IPv6 routing issues to Azure blob storage
-#   - csharp_omnisharp: Uses OmniSharp (alternative) - also auto-downloads
-#   - cpp: Uses clangd (auto-downloads v19.1.2 on Windows/Mac; Linux needs `apt install clangd`)
+#   - For Free Pascal/Lazarus, use pascal
 # Special requirements:
-#   - csharp: Requires the presence of a .sln file in the project folder.
+#   Some languages require additional setup/installations.
+#   See here for details: https://oraios.github.io/serena/01-about/020_programming-languages.html#language-servers
 # When using multiple languages, the first language server that supports a given file will be used for that file.
 # The first language is the default language and the respective language server will be used as a fallback.
 # Note that when using the JetBrains backend, language servers are not used and this list is correspondingly ignored.
-#
-# T-Mobile IPv6 workaround: Use csharp_omnisharp instead of csharp if you see Azure NuGet download errors.
-# The issue is that Python urllib prefers IPv6, and T-Mobile's IPv6 routing to Azure blob storage is broken.
 languages:
 - csharp_omnisharp
 - cpp
@@ -30,14 +31,12 @@ languages:
 # For a list of possible encodings, see https://docs.python.org/3.11/library/codecs.html#standard-encodings
 encoding: "utf-8"
 
-# whether to use the project's gitignore file to ignore files
-# Added on 2025-04-07
+# whether to use project's .gitignore files to ignore files
 ignore_all_files_in_gitignore: true
 
-# list of additional paths to ignore
-# same syntax as gitignore, so you can use * and **
-# Was previously called `ignored_dirs`, please update your config if you are using that.
-# Added (renamed) on 2025-04-07
+# list of additional paths to ignore in this project.
+# Same syntax as gitignore, so you can use * and **.
+# Note: global ignored_paths from serena_config.yml are also applied additively.
 ignored_paths:
 - Output/**
 - Obj/**
@@ -52,7 +51,20 @@ ignored_paths:
 # Added on 2025-04-18
 read_only: false
 
-# list of tool names to exclude. We recommend not excluding any tools, see the readme for more details.
+# initial prompt for the project. It will always be given to the LLM upon activating the project
+# (contrary to the memories, which are loaded on demand).
+initial_prompt: |
+  FieldWorks (FLEx) is a Windows/x64 linguistics suite by SIL International.
+  Key repo facts:
+  - Build with .\build.ps1; test with .\test.ps1.
+  - FieldWorks.proj and FieldWorks.sln are the main build and solution entry points.
+  - The codebase mixes native C++ and managed .NET; native builds must succeed before managed projects.
+  - FieldWorks uses registration-free COM; do not add global COM registration hacks.
+  - Keep localization in .resx and follow .github/instructions/*.instructions.md plus nearby AGENTS.md files.
+
+# list of tool names to exclude.
+# This extends the existing exclusions (e.g. from the global configuration)
+#
 # Below is the complete list of tools for convenience.
 # To make sure you have the latest list of tools, and to view their descriptions,
 # execute `uv run scripts/print_tool_overview.py`.
@@ -86,20 +98,15 @@ read_only: false
 #  * `restart_language_server`: Restarts the language server, may be necessary when edits not through Serena happen.
 #  * `search_for_pattern`: Performs a search for a pattern in the project.
 #  * `summarize_changes`: Provides instructions for summarizing the changes made to the codebase.
-# initial prompt for the project. It will always be given to the LLM upon activating the project
-# (contrary to the memories, which are loaded on demand).
-initial_prompt: |
-  FieldWorks (FLEx) is a Windows-first linguistics suite by SIL International.
-  Key build facts:
-  - Uses MSBuild Traversal SDK via FieldWorks.proj (21 ordered phases, 110+ projects)
-  - Native C++ (Phase 2) must build before managed code (Phases 3+)
-  - Build command: .\build.ps1 or msbuild FieldWorks.proj /p:Configuration=Debug /p:Platform=x64 /m
-  - Check .github/instructions/*.instructions.md for coding guidelines (managed, native, testing, etc.)
-  - Per-folder AGENTS.md files describe component contracts and dependencies
-# project_name: Intentionally left out so that the folder name will be used and worktrees will not conflict
+#  * `switch_modes`: Activates modes by providing a list of their names
+#  * `think_about_collected_information`: Thinking tool for pondering the completeness of collected information.
+#  * `think_about_task_adherence`: Thinking tool for determining whether the agent is still on track with the current task.
+#  * `think_about_whether_you_are_done`: Thinking tool for determining whether the task is truly completed.
+#  * `write_memory`: Writes a named memory (for future reference) to Serena's project-specific memory store.
 excluded_tools: []
 
-# list of tools to include that would otherwise be disabled (particularly optional tools that are disabled by default)
+# list of tools to include that would otherwise be disabled (particularly optional tools that are disabled by default).
+# This extends the existing inclusions (e.g. from the global configuration).
 included_optional_tools: []
 
 # list of mode names to that are always to be included in the set of active modes
@@ -120,9 +127,10 @@ default_modes:
 # fixed set of tools to use as the base tool set (if non-empty), replacing Serena's default set of tools.
 # This cannot be combined with non-empty excluded_tools or included_optional_tools.
 fixed_tools: []
-# the name by which the project can be referenced within Serena
-project_name: FieldWorks
 
+# project_name is intentionally omitted in shared config so Serena falls back to the
+# worktree folder name and multiple FieldWorks worktrees stay distinct.
+# If you need an explicit local override, put it in .serena/project.local.yml.
 
 # time budget (seconds) per tool call for the retrieval of additional symbol information
 # such as docstrings or parameter information.
@@ -136,3 +144,26 @@ symbol_info_budget:
 # Note: the backend is fixed at startup. If a project with a different backend
 # is activated post-init, an error will be returned.
 language_backend:
+
+# line ending convention to use when writing source files.
+# Possible values: unset (use global setting), "lf", "crlf", or "native" (platform default)
+# This does not affect Serena's own files (e.g. memories and configuration files), which always use native line endings.
+line_ending:
+
+# list of regex patterns which, when matched, mark a memory entry as read-only.
+# Extends the list from the global configuration, merging the two lists.
+read_only_memory_patterns: []
+
+# list of regex patterns for memories to completely ignore.
+# Matching memories will not appear in list_memories or activate_project output
+# and cannot be accessed via read_memory or write_memory.
+# To access ignored memory files, use the read_file tool on the raw file path.
+# Extends the list from the global configuration, merging the two lists.
+# Example: ["_archive/.*", "_episodes/.*"]
+ignored_memory_patterns: []
+
+# advanced configuration option allowing to configure language server-specific options.
+# Maps the language key to the options.
+# Have a look at the docstring of the constructors of the LS implementations within solidlsp (e.g., for C# or PHP) to see which options are available.
+# No documentation on options means no options are available.
+ls_specific_settings: {}

Build/Agent/Setup-Serena.ps1

@@ -70,6 +70,53 @@ function Set-EnvVar {
 	}
 }
 
+function Get-ConfiguredLanguages {
+	param([string]$ConfigContent)
+
+	$languages = @()
+	$inLanguagesBlock = $false
+
+	foreach ($line in ($ConfigContent -split "`r?`n")) {
+		if (-not $inLanguagesBlock) {
+			if ($line -match '^\s*languages:\s*$') {
+				$inLanguagesBlock = $true
+			}
+			continue
+		}
+
+		if ($line -match '^\s*-\s*(.+?)\s*$') {
+			$languages += $matches[1].Trim()
+			continue
+		}
+
+		if ($line -match '^\s*$' -or $line -match '^\s*#') {
+			continue
+		}
+
+		break
+	}
+
+	return $languages
+}
+
+function Get-ConfiguredProjectName {
+	param(
+		[string]$ConfigContent,
+		[string]$DefaultProjectName
+	)
+
+	foreach ($line in ($ConfigContent -split "`r?`n")) {
+		if ($line -match '^\s*project_name:\s*(.+?)\s*$') {
+			$value = $matches[1].Trim()
+			if ($value) {
+				return $value.Trim('"', "'")
+			}
+		}
+	}
+
+	return $DefaultProjectName
+}
+
 # ============================================================================
 # MAIN SCRIPT
 # ============================================================================
@@ -135,21 +182,39 @@ Write-Host "--- Step 2: Serena Configuration ---" -ForegroundColor Cyan
 if (Test-Path $serenaConfig) {
 	Write-Status "Found .serena/project.yml" -Status "OK"
 
-	# Show configured languages
+	# Show configured languages and project identity
 	$configContent = Get-Content $serenaConfig -Raw
-	if ($configContent -match 'programming_languages:\s*\[([^\]]+)\]') {
-		$languages = $matches[1]
-		Write-Status "Configured languages: $languages"
+	$languages = Get-ConfiguredLanguages -ConfigContent $configContent
+	$defaultProjectName = Split-Path -Leaf $repoRoot
+	$projectName = Get-ConfiguredProjectName -ConfigContent $configContent -DefaultProjectName $defaultProjectName
+
+	if ($languages.Count -gt 0) {
+		Write-Status ("Configured languages: {0}" -f ($languages -join ', '))
+	}
+	else {
+		Write-Status "No languages found in .serena/project.yml" -Status "WARN"
+	}
+
+	if ($configContent -match '^\s*project_name:\s*' -and $projectName) {
+		Write-Status "Configured project name: $projectName"
+	}
+	else {
+		Write-Status "Project name defaults to worktree folder: $projectName"
 	}
 }
 else {
 	Write-Status "Missing .serena/project.yml - Serena not configured" -Status "ERROR"
 	Write-Host ""
 	Write-Host "Create .serena/project.yml with:" -ForegroundColor Yellow
 	Write-Host @"
-name: FieldWorks
-project_root: .
-programming_languages: [csharp_omnisharp, cpp]
+languages:
+- csharp_omnisharp
+- cpp
+"@
+	Write-Host ""
+	Write-Host "Optional per-worktree override (.serena/project.local.yml):" -ForegroundColor Yellow
+	Write-Host @"
+project_name: $(Split-Path -Leaf $repoRoot)
 "@
 	exit 1
 }

Docs/mcp.md

@@ -53,7 +53,7 @@ each worktree contains its own `.serena/project.yml` file (shared via git). This
 issues when Serena auto-discovers projects:
 
 ### Symptoms
-- `get_current_config` shows multiple projects named "FieldWorks"
+- `get_current_config` shows multiple FieldWorks worktrees registered, or a project name that does not match the current folder
 - Language server errors that don't match your current worktree
 - Serena loads projects from worktrees you're not currently working in
 
@@ -62,8 +62,12 @@ VS Code's user-level MCP config (`%APPDATA%\Code\User\mcp.json`) may have a Sere
 server that auto-discovers projects by scanning for `.serena` folders. Combined with
 workspace-level `mcp.json`, this creates duplicate project registrations.
 
+This repo's shared `.serena/project.yml` intentionally leaves `project_name` unset so
+Serena falls back to the worktree folder name by default. That keeps worktrees easier
+to distinguish when multiple registrations exist.
+
 ### Solution
-**Use only workspace-level Serena**
+**Use only workspace-level Serena, and keep project names local to the worktree**
 
 Remove or disable the Serena entry from your user-level MCP config:
 ```powershell
@@ -73,6 +77,10 @@ code "$env:APPDATA\Code\User\mcp.json"
 Remove the `"oraios/serena"` entry. The workspace `.vscode/mcp.json` provides Serena
 with explicit project targeting.
 
+If you want a friendlier project name than the folder name, set it in
+`.serena/project.local.yml` for that worktree instead of committing a shared
+`project_name` in `.serena/project.yml`.
+
 ## Best-practice profile for this repo
 
 - Keep repo-level MCP servers minimal: `github` + `serena` only.
@@ -85,6 +93,7 @@ with explicit project targeting.
 - Open one VS Code window per worktree; let that window use its own workspace `.vscode/mcp.json`.
 - Keep only one Serena server definition active (workspace-level), and remove user-level Serena.
 - Keep Serena pinned to the active workspace via `--project ${workspaceFolder}` (already configured).
+- If you want an explicit Serena project name, set it in `.serena/project.local.yml`; do not commit a shared `project_name` in `.serena/project.yml`.
 - After switching worktrees, run **MCP: Reset Cached Tools** if tool lists or capabilities look stale.
 - No extra GitHub MCP worktree settings are required beyond OAuth sign-in.