Refactor Update-MDSection to improve error handling; replace warnings with exceptions for missing markers. Update AGENTS.md references to point to canonical guidance in PSModule/docs.

Author: MariusStorhaug

.github/actions/update-index/src/Helper.psm1

@@ -98,35 +98,18 @@ function Update-MDSection {
     $startSegment = "<!-- $Name`_START -->"
     $endSegment = "<!-- $Name`_END -->"
 
-    function Write-UpdateWarning {
-        param([string] $Message)
-
-        Write-Warning $Message
-        if ($env:GITHUB_ACTIONS -eq 'true') {
-            Write-Output "::warning::$Message"
-        }
-    }
-
-    if (-not (Test-Path -Path $Path)) {
-        Write-UpdateWarning "[$Name] Skipping update because target file was not found: $Path"
-        return
-    }
-
     $currentContent = Get-Content -Path $Path
     $startIndex = $currentContent.IndexOf($startSegment)
     $endIndex = $currentContent.IndexOf($endSegment)
 
     if ($startIndex -lt 0) {
-        Write-UpdateWarning "[$Name] Skipping update because the start marker was not found in: $Path"
-        return
+        throw "[$Name] The start comment segment was not found in the file."
     }
     if ($endIndex -lt 0) {
-        Write-UpdateWarning "[$Name] Skipping update because the end marker was not found in: $Path"
-        return
+        throw "[$Name] The end comment segment was not found in the file."
     }
     if ($endIndex -lt $startIndex) {
-        Write-UpdateWarning "[$Name] Skipping update because marker order is invalid in: $Path"
-        return
+        throw "[$Name] The end comment segment was found before the start comment segment."
     }
 
     $updatedContent = $currentContent[0..$startIndex] + $Content + $currentContent[($endIndex)..($currentContent.Length - 1)]

.github/actions/update-index/src/main.ps1

@@ -1,6 +1,6 @@
 Import-Module -Name (Join-Path $PSScriptRoot 'Helper.psm1')
 
 Show-RepoList
-Update-ActionList
-Update-FunctionAppList
+# Update-ActionList
+# Update-FunctionAppList
 Update-ModuleList

src/docs/Modules/Repository-Defaults.md

@@ -68,7 +68,7 @@ Module repositories use the PSModule framework layout:
 | `SECURITY.md` | Security support policy and private vulnerability reporting instructions. |
 | `SUPPORT.md` | Support expectations and where users ask for help. |
 | `CODE_OF_CONDUCT.md` | Community conduct expectations. |
-| `AGENTS.md` | Agent onboarding entry point. Points agents to the PSModule and MSX documentation for the why, how, and what. |
+| `AGENTS.md` | Agent onboarding entry point. Points agents to the canonical guidance in `PSModule/docs`. |
 | `CLAUDE.md` | Claude Code entry point. Imports `AGENTS.md` so Claude reads the same instructions. |
 | `.github/copilot-instructions.md` | VS Code and GitHub Copilot repository instructions. Points to the same documentation. |
 | `.github/PSModule.yml` | Module workflow configuration overrides. |
@@ -111,7 +111,7 @@ Required baseline files for module repositories:
 | `SECURITY.md` | Private vulnerability reporting and latest-version support policy. |
 | `SUPPORT.md` | Support channel and issue-routing expectations. |
 | `CODE_OF_CONDUCT.md` | Community participation rules. |
-| `AGENTS.md` | Cross-tool agent instructions pointing to the PSModule and MSX documentation. |
+| `AGENTS.md` | Cross-tool agent instructions pointing to the canonical guidance in `PSModule/docs`. |
 | `CLAUDE.md` | Claude Code entry point that imports `AGENTS.md`. |
 | `.github/copilot-instructions.md` | VS Code and GitHub Copilot repository instructions pointing to the documentation. |
 | `.github/dependabot.yml` | Supply-chain maintenance for GitHub Actions and PowerShell dependencies. |
@@ -132,7 +132,7 @@ Each repository must stand on its own. It carries its own copy of every file abo
 
 Every repository must be usable by an agent that has never seen it before, without special configuration. Each repository carries its own agent entry points that point to the authoritative documentation instead of restating it:
 
-- `AGENTS.md`: the cross-tool entry point, read by the GitHub Copilot coding agent, VS Code, and other AGENTS.md-aware tools. It names what the repository is in a line or two and points to the PSModule documentation (`https://psmodule.io`, source in [`PSModule/docs`](https://github.com/PSModule/docs)) for the module's why/how/what, and to the MSX documentation (`https://msxorg.github.io/docs`, source in [`MSXOrg/docs`](https://github.com/MSXOrg/docs)) for organization-level principles and ways of working.
+- `AGENTS.md`: the cross-tool entry point, read by the GitHub Copilot coding agent, VS Code, and other AGENTS.md-aware tools. It names what the repository is in a line or two and points to the canonical agent guidance in [`PSModule/docs`](https://github.com/PSModule/docs).
 - `CLAUDE.md`: a thin file that imports `AGENTS.md` with `@AGENTS.md` so Claude Code reads the same instructions. Claude-specific notes, if any, go below the import.
 - `.github/copilot-instructions.md`: repository instructions for VS Code and GitHub Copilot that point to the same documentation.