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-verify.yml

@@ -0,0 +1,45 @@
+name: Offline API documentation
+
+on:
+  pull_request:
+    paths:
+      - 'src/**'
+      - 'phpdoc.dist.xml'
+      - 'scripts/docs/**'
+      - 'docs/api-build.md'
+      - '.github/workflows/docs-verify.yml'
+
+permissions:
+  contents: read
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.pull_request.head.sha }}
+
+      - uses: shivammathur/setup-php@v2
+        with:
+          php-version: '8.4'
+          extensions: iconv, mbstring
+          coverage: none
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+
+      - name: Verify pinned phpDocumentor
+        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 source reference without bot bootstrap
+        run: php phpDocumentor.phar --config phpdoc.dist.xml --no-interaction
+
+      - name: Check links, search and exact-head development provenance
+        run: |
+          node scripts/docs/finalize.mjs
+          node scripts/docs/verify.mjs "${{ github.event.pull_request.head.sha }}"

.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

@@ -2,9 +2,17 @@ name: Local profile offline contracts
 on:
   pull_request:
     paths:
+      - 'composer.json'
+      - 'composer.lock'
       - 'src/Civ13/Local/**'
+      - 'src/Civ13/Server/**'
       - 'src/Civ13/RestartPolicy.php'
       - 'src/Civ13/Civ13.php'
+      - 'src/Civ13/GameServer.php'
+      - 'src/Civ13/Slash.php'
+      - 'src/Civ13/Panels.php'
+      - 'src/Civ13/MessageCommand/Commands/AdminListUpdate.php'
+      - 'src/Civ13/MessageCommand/Commands/Civ13GameServerMapSwap.php'
       - 'src/Civ13/HttpServiceManager.php'
       - 'local-bot.php'
       - 'tests/local/**'
@@ -30,15 +38,30 @@ jobs:
       - run: php tests/local/run.php
       - run: php -l local-bot.php
   supervision:
+    strategy:
+      fail-fast: false
+      matrix:
+        php: ['8.3', '8.4', '8.5']
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
       - uses: shivammathur/setup-php@v2
         with:
-          php-version: '8.4'
+          php-version: ${{ matrix.php }}
           tools: composer
           coverage: none
       - 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/restart-command.php vendor/autoload.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
+        timeout-minutes: 2
+      - run: php tests/local/relay.php vendor/autoload.php
+        timeout-minutes: 2
+      - 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
+      - run: php tests/local/adminlist-consumers.php vendor/autoload.php
+      - run: php tests/local/lifecycle-consumers.php vendor/autoload.php

.github/workflows/portable.yml

@@ -30,6 +30,14 @@ jobs:
       - run: php tests/windows/ready.php
       - run: php tests/windows/ready.php vendor/autoload.php --hosted
       - run: php tests/windows/ready.php vendor/autoload.php --unconfigured
+      - name: Windows file IPC and role-list contracts
+        if: runner.os == 'Windows'
+        timeout-minutes: 2
+        run: php tests/local/server-compatibility.php vendor/autoload.php
+      - name: Windows durable relay contracts
+        if: runner.os == 'Windows'
+        timeout-minutes: 2
+        run: php tests/local/relay.php vendor/autoload.php
       - run: php -l bot.php
       - run: php -l src/Civ13/Civ13.php
       - run: php -l src/Civ13/GameServer.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

.github/workflows/verifier-integration.yml

@@ -4,6 +4,7 @@ on:
   push:
     paths:
       - 'composer.json'
+      - 'composer.lock'
       - 'src/**'
       - 'tests/verifier-integration.php'
       - 'tests/http-dependency.php'
@@ -19,6 +20,7 @@ on:
   pull_request:
     paths:
       - 'composer.json'
+      - 'composer.lock'
       - 'src/**'
       - 'tests/verifier-integration.php'
       - 'tests/http-dependency.php'
@@ -49,8 +51,8 @@ jobs:
           php-version: ${{ matrix.php }}
           extensions: mbstring, pdo_sqlite
           coverage: none
-      # composer.lock is intentionally ignored here. Resolve dependencies for
-      # each supported PHP runtime while retaining the explicit verifier pin.
+      # Install the reviewed lock on each supported PHP runtime. Dependency
+      # updates require an explicit manifest/lock change and fresh CI evidence.
       - run: composer install --no-scripts --no-plugins --prefer-dist --no-interaction
       - run: composer validate --no-check-publish
       - run: composer check-platform-reqs

.gitignore

@@ -10,7 +10,6 @@ token.php
 /json
 botlog.txt
 .env
-composer.lock
 /html
 output.log
 ranking.txt
@@ -28,6 +27,7 @@ test.php
 /tools/
 /phive.xml
 /.phive/
+/tooling/mcp/node_modules/
 
 # Standalone directory dependencies are CI-built; its minimal lock is reviewed.
 /packaging/directory/vendor/

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.

README.MD

@@ -108,32 +108,35 @@ This sets up a timer to change the bot's status every 120 seconds.
 ### Offline verifier integration
 
 `vzgcoders/verifier-server` is pinned to the reviewed upstream commit in
-`composer.json`. This repository intentionally ignores `composer.lock`; preserve
-local locks and any intentional path repositories. In an existing installation,
-update only that package with `composer update vzgcoders/verifier-server`.
+`composer.json`. The v5 development branch tracks a reviewed `composer.lock`;
+fresh isolated checkouts use `composer install --no-scripts --no-plugins`.
+Preserve intentional local path repositories and review their lock differences
+before updating an existing installation. Dependency changes belong in a
+reviewed manifest/lock update with fresh CI.
 
 Run `php tests/verifier-integration.php` after installing dependencies. The runner
 uses temporary filesystem storage and injected endpoint setup, bypassing the
 usual test bootstrap and all `.env` loading. It exercises the bot's in-process
 registration/unverify calls against the installed verifier, plus form decoding,
 status codes, authorization, duplicate rejection, Discord-only deletion, lookup
 invalidation and restart persistence. It never starts the bot, listens on a
-socket or sends a live Discord/HTTP request. CI resolves dependencies separately
+socket or sends a live Discord/HTTP request. CI installs the reviewed lock separately
 for PHP 8.3, 8.4 and 8.5; the installed verifier reference must match the manifest pin.
 
 ### Dependency and HTTP checks
 
-For an existing local lock, update the patched HTTP package and pinned verifier
-with `composer update react/http vzgcoders/verifier-server`; preserve any local
-path repositories. Then run `composer check-platform-reqs`,
+Install the committed dependency lock in an isolated checkout; preserve any local
+path repositories when preparing a dependency update. Run `composer check-platform-reqs`,
 `composer audit --locked`, and `php tests/http-dependency.php`.
 The HTTP runner uses injected in-memory connections and streams, with bounded
 malformed inputs and legitimate response controls; it never opens a socket.
-CI resolves the full dependency set, including development tools, on each
+CI installs the full locked dependency set, including development tools, on each
 supported runtime, checks platform requirements and audit results, parses all
 bot source, and runs the HTTP, verifier and disabled-economy offline suites.
-The ignored-lock convention is unchanged. Updating deployment dependencies and
-restarting the live bot are separate operational actions.
+Updating deployment dependencies and restarting the live bot are separate
+operational actions. The source marker is `Civ13::VERSION = 5.0.0-dev`; see the
+[development acceptance and migration ledger](docs/releases/v5.0.0.md) before
+any release or deployment.
 
 Contributions are welcome! Please open an issue or submit a pull request on GitHub.
 

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
         }