docs: document admin-only governance & slnx upkeep rule

.claude/skills/prepare-release/SKILL.md

@@ -6,9 +6,15 @@ description: Prepare a new NuGet release of this repository (version bump, relea
 # Prepare release
 
 Prepare a new release of this NuGet package. You decide the next version
-yourself. The NuGet publish itself is a **manual** GitHub Actions trigger
-(`deploy-nuget.yml`, `workflow_dispatch`) and is NOT part of your job — you
-prepare the repository and open the PR.
+yourself. You **prepare the repository and open the release PR — then stop.**
+Reviewing, merging, and publishing are **admin-only** and not part of your job:
+
+- You do **not** merge the release PR (or enable auto-merge). The admin reviews
+  and merges every PR manually.
+- You do **not** trigger `deploy-nuget.yml`. The NuGet publish is a manual
+  `workflow_dispatch` the admin runs **after** merging the release PR.
+
+This skill must only be run by the admin (auto-opening PRs is admin-only).
 
 ## Workflow
 
@@ -54,12 +60,16 @@ prepare the repository and open the PR.
 11. **Release notes** — copy `.claude/skills/prepare-release/assets/release-notes.md` to
     `release-notes/v<version>.md`, fill in the `{{VERSION}}`/`{{DATE}}` placeholders
     and the **Added / Changed / Fixed / Removed** sections (omit empty ones).
+    Add the new file to `OpenTelemetryExtension.slnx` (it tracks loose files
+    explicitly — see AGENTS.md).
 
-12. **Commit** (no tag) — stage csproj(s), docs, release notes; message `release: v<version>`.
+12. **Commit** (no tag) — stage csproj(s), docs, release notes, `.slnx`; message `release: v<version>`.
 
-13. **Push & PR to main**
+13. **Push & open PR to main — then stop. Do NOT merge it.**
     - `git push -u origin release/v<version>`
     - `gh pr create --base main --head release/v<version> --title "release: v<version>" --body <notes>`
+    - The admin reviews and merges the PR. You never merge it or enable auto-merge.
 
-14. **Report** the PR link and remind: after merge, trigger **Deploy Nuget** manually
-    (Actions → Deploy Nuget → Run workflow) — it tags `v<version>` and publishes.
+14. **Report** the PR link and remind the admin: after **they** merge it, **they**
+    trigger **Deploy Nuget** manually (Actions → Deploy Nuget → Run workflow) —
+    it tags `v<version>` and publishes. You do not trigger it.

AGENTS.md

@@ -26,6 +26,12 @@ release-notes/                                   # v{VERSION}.md per release
 OpenTelemetryExtension.slnx                      # Solution file (repo root)
 ```
 
+`OpenTelemetryExtension.slnx` lists projects **and** loose files (docs, helm
+charts, release notes) explicitly. Whenever you **add, rename, move, or delete**
+a tracked file — including a new `release-notes/v{VERSION}.md` — update the
+`.slnx` to match, or the solution will reference a missing path or miss the new
+file.
+
 ## Branches & CI
 
 The repository follows **GitHub Flow**: `main` is the only long-lived branch and
@@ -46,6 +52,23 @@ is always releasable.
   Packages, tags `v{VERSION}` and creates a GitHub Release from
   `release-notes/v{VERSION}.md`.
 
+## Roles & permissions (admin-only actions)
+
+`main` is protected (PR required, `build` check must pass, `enforce_admins` on —
+**nobody pushes to `main` directly, including the admin**). On top of that, the
+following are reserved for the repository **maintainer (admin)** and an AI agent
+must **never** do them on its own initiative:
+
+- **Reviewing & merging PRs into `main`.** The admin manually reviews **every**
+  PR and performs the merge. An agent prepares branches and **opens** PRs, then
+  **stops** — it does not merge them, does not enable auto-merge, and does not
+  merge its own PRs.
+- **Opening PRs automatically.** An agent may open a PR only while explicitly
+  operated by the admin (e.g. the admin running the `prepare-release` skill).
+- **Triggering `deploy-nuget.yml`.** Publishing (NuGet + GitHub Packages + the
+  `v{VERSION}` tag + GitHub Release) is a manual, admin-only `workflow_dispatch`,
+  run **after** the admin has merged the release PR. An agent never triggers it.
+
 ## Public API (2 classes, minimal surface)
 
 ```csharp
@@ -172,14 +195,18 @@ API to confirm the data was ingested.
   `src/OpenTelemetryExtension.Configuration/OpenTelemetryExtension.Configuration.csproj`
   (`<Version>`)
 - Do not change `<Version>` without also creating `release-notes/v{VERSION}.md`
-  — the GitHub Release body is taken from that file
+  (and adding it to `OpenTelemetryExtension.slnx`) — the GitHub Release body is
+  taken from that file
 - NuGet publish is **manual** (`workflow_dispatch` on `deploy-nuget.yml`) —
-  never triggered automatically; it also creates the `v{VERSION}` git tag
+  never triggered automatically; it also creates the `v{VERSION}` git tag. Only
+  the admin triggers it, **after** merging the release PR (see
+  [Roles & permissions](#roles--permissions-admin-only-actions))
 - The full release-prep workflow (decide SemVer, bump, update deps, build/test,
   end-to-end smoke test, release notes, PR to `main`) is encoded in the
   **`prepare-release`** skill at `.claude/skills/prepare-release/`. Run it via
-  Claude Code (`/prepare-release`) when cutting a release; it only prepares the
-  PR — publishing stays the manual `deploy-nuget.yml` trigger.
+  Claude Code (`/prepare-release`) when cutting a release; it only prepares and
+  **opens** the PR — the admin reviews and merges it, then the admin triggers
+  `deploy-nuget.yml`. The skill never merges or publishes.
 
 ## What NOT to do
 
@@ -190,6 +217,10 @@ API to confirm the data was ingested.
 - Do not add new public API surface without a corresponding test in
   `TelemetryOptionsTests.cs` or `TelemetryServiceCollectionExtensionsTests.cs`
 - Do not add test classes without a `Category` trait (see [Tests](#tests))
+- Do not merge PRs into `main`, enable auto-merge, or trigger `deploy-nuget.yml`
+  — those are admin-only (see [Roles & permissions](#roles--permissions-admin-only-actions))
+- Do not add, rename, or delete a tracked file without updating
+  `OpenTelemetryExtension.slnx`
 
 ## Adding a new instrumentation option