Prepare v5.0.0 server compatibility

.agents/skills/CATALOG.md

@@ -0,0 +1,8 @@
+# Repository skills
+
+- [bot-architecture](bot-architecture/SKILL.md): trace bootstrap, services and authority boundaries before structural changes.
+- [bot-commands](bot-commands/SKILL.md): change message/slash routing without registration or live interactions.
+- [server-compatibility](server-compatibility/SKILL.md): native BYOND/OpenDream lifecycle, Topic and file IPC compatibility.
+- [bot-release](bot-release/SKILL.md): exact-head offline verification, dependency migration and release closeout.
+
+These skills describe repository workflows. They do not authorize live Discord, game control, credentials or deployment.

.agents/skills/bot-architecture/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: bot-architecture
+description: Trace CivilizationBot services and authority boundaries when changing bootstrap, storage, verification or local profiles.
+---
+
+Start with `src/Civ13/Civ13.php` and the affected service constructor. `bot.php` is the ambient official bootstrap; inspecting it is safe, executing it is not an offline test. `local-bot.php` is a separate explicit profile bootstrap, not a substitute for the full router.
+
+For local isolation read `src/Civ13/Local/Profile.php`, `ControlEndpoint.php`, `Replica.php` and `OpenDreamControl.php`. The replica is authenticated read-only verification data; it cannot grant game authority or mutate official roles. Controls need their own enabled gate and loopback authentication. Missing adapters fail closed rather than falling back to legacy server paths.
+
+Resolve installed signatures through the selected checkout's `vendor/autoload.php` and Composer dependencies. Existing primary path repositories may be intentional; never rewrite them to make an isolated test pass. Use `tests/local/run.php` for dependency-free contracts and `tests/local/library.php <autoload>` for actual dependency behavior. Report which dependency tree was used.

.agents/skills/bot-commands/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: bot-commands
+description: Maintain CivilizationBot message and slash commands using offline routing and interaction checks without live command registration.
+---
+
+Trace message commands through `src/Civ13/MessageHandler.php`, `MessageServiceManager.php` and `MessageCommand/Commands/`. Trace slash desired command schema and listeners separately in `src/Civ13/Slash.php`: a listener alone does not prove a registered command or permission scope.
+
+Inspect the installed DiscordPHP interaction and Promise signatures before changing replies. Await asynchronous lifecycle outcomes; distinguish accepted work, process observation, readiness and durable game completion. Rejections and pending results must not produce success messages.
+
+Use injected interaction/transport doubles and temporary state. Include forbidden destination, permission denial, unavailable adapter, concurrent operation and failed transport controls relevant to the change. Do not execute the normal bootstrap, register desired schemas or send test messages. Preserve unrelated existing commands and nullable optional channels.

.agents/skills/bot-release/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: bot-release
+description: Prepare CivilizationBot version migrations and exact-head release evidence, including API docs, local contracts and recoverable worktree closeout.
+---
+
+Use `docs/releases/v5.0.0.md` as the acceptance ledger and inspect actual `.github/workflows/` triggers. Verify fresh isolated Composer dependencies before claiming compatibility; distinguish primary-vendor baseline checks from fresh installation and supported PHP CI.
+
+Run the smallest affected versioned tests, then required CI at the exact pushed head. Record source SHA, command, result and unrun limits. Developer API docs must exclude vendor, secrets and runtime data; verify useful public links/search/assets after authorized Pages publication. Documentation publication is not bot/game deployment.
+
+Keep incomplete PRs draft. Do not tag or call a release ready while required ledger gates remain. Review outgoing changes, migration examples, exact-head checks and independent review before a permitted merge. Remove a completed worktree only after clean and ignored-file inspection, owned-process checks and confirmation that commits and needed artifacts are recoverable. Preserve other worktrees, including ongoing safehouse work.

.agents/skills/server-compatibility/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: server-compatibility
+description: Verify CivilizationBot native BYOND and OpenDream server controls, Topic and file relay contracts using isolated adapters.
+---
+
+Read `src/Civ13/GameServer.php`, `Server/Ipc.php`, `Server/FileRelay.php`, `Local/OpenDreamControl.php` and `Local/AsyncProcess.php`. OpenDream uses the trusted Python controller profile; no DreamDaemon, git update or native kill fallback is permitted. Process status and Topic readiness are separate observations.
+
+Runtime SQL is `<runtime_dir>/SQL`; server metadata is `<runtime_dir>/serverdata.txt`. Gameplay and Topic ports are distinct. Map IDs come from the configured allowlist, never arbitrary user paths or shell text. Coordinate Python/DM contract changes with the Civ13 owner before editing shared contracts.
+
+Run `tests/local/server-compatibility.php <autoload>`, `tests/local/opendream.php <autoload>` and `tests/local/controls.php <autoload>` as applicable. These use temporary files and injected effects or bounded synthetic PHP children, not game servers. Check record framing, denied writes, empty revocation, partial relay lines, failed delivery and lifecycle concurrency. Queueing an IPC record does not prove its application by the game. Actual server probes require separately authorized ports and ownership.

.github/workflows/docs.yml

@@ -27,18 +27,29 @@ jobs:
         with:
           php-version: '8.4'
           extensions: iconv, mbstring
-          tools: phive
 
       - name: Install phpDocumentor
-        run: phive install phpDocumentor --trust-gpg-keys 67F861C3D889C656,6DA3ACC4991FFAE5
+        run: |
+          curl --fail --location --output phpDocumentor.phar https://github.com/phpDocumentor/phpDocumentor/releases/download/v3.10.0/phpDocumentor.phar
+          echo 'fe1e7c23ba3329aa6f19ac3c807446159a431a195ec5d9163b0c281a15105207  phpDocumentor.phar' | sha256sum --check
 
       - name: Build class reference
-        run: ./tools/phpDocumentor --config phpdoc.dist.xml --no-interaction
+        run: php phpDocumentor.phar --config phpdoc.dist.xml --no-interaction
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+
+      - name: Validate links, search and source provenance
+        run: |
+          node scripts/docs/finalize.mjs
+          node scripts/docs/verify.mjs "${{ github.sha }}"
 
       - name: Publish to gh-pages
         uses: JamesIves/github-pages-deploy-action@v4
         with:
           token: ${{ secrets.GITHUB_TOKEN }}
           branch: gh-pages
-          folder: build
+          folder: build/v5
+          target-folder: v5
           clean: true

.github/workflows/local-profile.yml

@@ -41,4 +41,10 @@ jobs:
       - run: composer install --no-interaction --prefer-dist --no-progress
       - run: php tests/local/library.php
       - run: php tests/local/opendream.php
+      - run: php tests/local/lifecycle.php vendor/autoload.php
       - run: php tests/local/controls.php
+      - run: php tests/local/server-compatibility.php vendor/autoload.php
+      - run: php tests/local/relay.php vendor/autoload.php
+      - run: php tests/local/message-delivery.php vendor/autoload.php
+      - run: php tests/local/ooc-webhook.php vendor/autoload.php
+      - run: php tests/local/unban-commands.php vendor/autoload.php

.github/workflows/source-mcp.yml

@@ -0,0 +1,22 @@
+name: Read-only source MCP
+on:
+  pull_request:
+    paths: ['tooling/mcp/**', '.github/workflows/source-mcp.yml']
+  workflow_dispatch:
+permissions:
+  contents: read
+jobs:
+  protocol:
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: npm
+          cache-dependency-path: tooling/mcp/package-lock.json
+      - run: npm ci --prefix tooling/mcp --ignore-scripts --no-audit --no-fund
+      - run: npm test --prefix tooling/mcp

.gitignore

@@ -28,3 +28,4 @@ test.php
 /tools/
 /phive.xml
 /.phive/
+/tooling/mcp/node_modules/

AGENTS.md

@@ -0,0 +1,7 @@
+# CivilizationBot working guide
+
+Read the relevant skill in [.agents/skills/CATALOG.md](.agents/skills/CATALOG.md) before changing its runtime boundary. Work from this repository, preserve intentional Composer path repositories, and use isolated worktrees for concurrent work.
+
+Tests must use temporary storage and injected Discord, HTTP, file and process effects. Do not bootstrap `bot.php`, load `.env`, register commands, launch game servers or send Discord messages for offline verification. Separate local credentials and destinations from the official installation; a verification replica is never authority.
+
+Feature branches have corresponding PRs. Check the exact head, actual tests and configuration migration before release. Developer documentation publication has a separate workflow from bot deployment; a merged PR or published API site does not activate the bot.

composer.json

@@ -46,6 +46,9 @@
     "minimum-stability": "dev",
     "prefer-stable": true,
     "config": {
+        "platform": {
+            "php": "8.3.0"
+        },
         "allow-plugins": {
             "wyrihaximus/composer-update-bin-autoload-path": true
         }