Imported from tom3197111/game-admin (AGENTS.md). Install upstream with npx skills add tom3197111/game-admin. Copyright stays with the author.

AGENTS - game-admin

This repo owns the Laravel 8 game admin/operator surface for Reincarnation World: backend shell, admin auth/RBAC, content CMS, AI authoring controls, review/publish gates, game-server admin API bridge, and operator-facing readiness views.

Planning owner is ChatGPT / 指揮官. Claude-era instructions may appear in game-client/docs/codex/claude-inbox/**; treat them as adopted task specs only when command-inbox points there. The current short dispatch entrypoint is in game-client/docs/codex/command-inbox/short-index.md.

Start Here

1. Read this file.
2. Read README.md.
3. Read C:\Users\tom31\projects\game-client\docs\codex\command-inbox\short-index.md for current cross-repo dispatch.
4. Read C:\Users\tom31\projects\game-client\docs\codex\control\execution-authority.md for autonomous execution, the sole forbidden boundary, and evidence-driven deployment discipline.
5. If the short index points to a detailed task, read only that task file.
6. Then read only the admin files relevant to the task.

Repo Boundary

• Owns: game-admin backend shell, local/production admin entry, RBAC, admin session protection, content CMS UI, AI prompt registry UI, AI authoring trigger/control UI, review/publish gates, game-server admin API client/bridge, operator readiness dashboards, and the game-specific Discord OAuth callback plus hashed player auth sessions.
• Does not own: Web3D player rendering, Unity deploy mirror, C# runtime rules, player action resolution, general/community Discord identity, old GAME general community backend, rental, lottery, article/photo systems, raw destructive database shortcuts, or story generation by Codex.
• Do not create, restore, or rely on a dependency on the legacy repository named exactly game or its database. Read-only inspection is allowed only when necessary to identify that boundary or preserve compatibility.

OpenAI Authoring / No Manual Review Rule

Codex is not the story writer. Admin does not generate story content locally by Codex-authored prose. Admin triggers and observes the server-side OpenAI API authoring flow through game-server, then displays structured drafts, gate results, audit trail, block/rollback/override controls.

User does not manually review every AI content item. Admin must therefore become an automatic gate console: schema validation, world-will gates, narrative/living-entity/faction gates, server dry-run result, fallback/no-dead-end/time-mutation status, audit trail, block/rollback/override controls. Admin visibility remains required; manual approval must not be the normal content bottleneck unless a task explicitly defines a real product gate.

Read Before Editing Admin UI

• routes/web.php
• routes/api.php
• app/Http/Controllers/BackendLocalDashboardController.php
• app/Services/GameAdminApiClient.php
• app/Services/GameAdminContentCmsOverviewService.php
• app/Services/BackendPermissionCatalog.php
• config/backend_permissions.php
• The target resources/views/backend/** Blade files
• The matching scripts/smoke/*game-admin* scoped smoke

Backend Quality Bar

The admin is not just a health shell. It must become an AI world control console:

• All game content should become manageable: data schema, draft/version, edit, automatic gate, publish candidate, runtime-read smoke, audit, rollback.
• OpenAI generation controls should configure prompt templates, schema versions, world/faction context input, generation parameters, dry-run state, quota visibility, and provider dispatch gates without exposing secrets.
• Read-only pages must truthfully label themselves as scaffold / visibility only and show the next gate.
• New content modules need clear Chinese UI, help text, status, blockers, and next safe action.
• Do not create duplicate UI blocks or repeated module cards.
• Keep the global sidebar/main shell consistent across protected backend pages.

Cutover / Readiness Rules

• Readiness views must not show token values.
• GAME_API_TOKEN and GAME_WORLD_ADMIN_API_TOKEN values belong only in server env, never in MD or UI.
• Readiness is evidence, not a separate user-approval gate. Route, callback, credential, migration, provider, publish, reset, and production changes inside the assigned projects should execute through the current task with RBAC, backup, transaction/idempotency, rollback, smoke, and read-back.
• Default UI should be read-only unless a write flow has RBAC, CSRF, validation, audit, and a clear automatic gate or review/publish contract.
• Contract probes must stay explicitly action-driven; pages must not trigger PATCH / POST merely by loading.

Smoke and Deployment Discipline

Run the smallest relevant scoped smoke. Common checks:

php artisan route:list --compact
powershell -ExecutionPolicy Bypass -File scripts/smoke/game-admin-local-api-boundary-smoke.ps1
powershell -ExecutionPolicy Bypass -File scripts/smoke/game-admin-security-audit-smoke.ps1
powershell -ExecutionPolicy Bypass -File scripts/smoke/game-admin-api-bridge-pairing-smoke.ps1
powershell -ExecutionPolicy Bypass -File scripts/smoke/game-admin-public-route-smoke.ps1

• For Blade/UI work, run the specific page smoke and php artisan view:cache only when the changed view/compiler surface requires it.
• Do not rerun an already-passed route, Blade, browser, or bridge suite when its relevant inputs did not change.
• Batch adjacent admin changes and deploy/restart once per coherent slice. Documentation-only changes never deploy the application.
• Use bounded polling only for a known operation. Once acceptance and read-back pass, close the slice instead of adding extra probes.

Laravel Notes

• This is Laravel 8 style. Keep Controller / Service separation when adding meaningful logic.
• Do not put business logic directly into Blade when it belongs in a service or view model.
• If adding tables, provide the php artisan make:migration ... command in the work note. When the current task requires execution, verify the target database, back up, run the scoped migration, verify read-back, and retain rollback notes; no separate approval is required inside game-admin.

Safety Rules

• Do not write passwords, API keys, tokens, APP_KEY values, hashes, SSH details, or deployment credentials into MD, code, commits, screenshots, logs, or chat.
• Do not use production wipe/reset/fresh/truncate/drop/destructive-seed shortcuts. Scoped reset/regeneration workflows may run inside the assigned projects only through their guarded contracts with backup, preview, bounded execute, rollback, and read-back.
• For work dispatched through game-client, execute the assigned task autonomously under its execution-authority.md; provider spend, live publish, queue jobs, player-data writes, credentials, migrations, deploys, and restarts require engineering safeguards but not separate user approval.
• Do not call OpenAI/provider from player runtime; story generation belongs to authoring flow through game-server.
• Stop only before modifying the legacy repository named exactly game or its owned database/schema/data.
• Keep reports short: changed artifact, commit, one coherent verification result, deployment/read-back when required, and the legacy boundary statement. Long logs belong in the task card only when they close a batch.