## Context

The platform already has a basic `GamePlugin` resource in `platform/` and an initial JSON Schema validator in `plugins/`. Those pieces are not yet enough for the plugin marketplace and server creation backlog because registration can still be assembled by hand instead of coming from a validated game management plugin manifest.

This change covers the first registry boundary between `plugins/` and `platform/`: plugin authors validate manifest files in the plugin workspace, while the platform accepts a structured manifest registration payload, validates the same safety constraints in backend validators, stores only registry metadata, and exposes that metadata through the existing game plugin APIs.

## Goals / Non-Goals

**Goals:**

- Define one concrete manifest contract for game management plugins.
- Reject unsafe manifest requests for raw run, host path, credential, socket, and raw AI key access.
- Register installed plugins from manifest metadata through platform DTO/service/API layers.
- Keep registry responses useful for plugin marketplace display without exposing raw paths, raw credentials, run internals, or AI provider keys.
- Add focused schema, validator, service, and API tests.

**Non-Goals:**

- Do not implement plugin page bridge runtime, plugin action execution, or SDK transport.
- Do not add billing, cloud host sales, provider marketplaces, or unrelated SaaS marketplace behavior.
- Do not make platform import TypeScript plugin validation code or plugin workspace files directly.
- Do not implement frontend plugin marketplace pages in this change.

## Decisions

### Decision 1: Use a copied manifest contract at the root boundary

`plugins/` owns the JSON Schema and TypeScript validation helper. `platform/` owns named DTOs and domain types that mirror the externally submitted manifest shape. The two roots are kept aligned by tests and OpenSpec requirements rather than direct imports.

Alternative considered: have platform read `plugins/manifests/game-plugin.manifest.schema.json` directly. Rejected because that would make the backend depend on the plugin workspace file layout and blur root ownership.

### Decision 2: Platform registration converts manifests to existing registry metadata

The platform will add a manifest registration service/API path that converts a validated manifest into `GamePlugin` registry metadata. The existing create/list/detail endpoints remain available for low-level metadata tests and future migration, while the new manifest endpoint is the supported installation boundary for plugin manifests.

Alternative considered: replace `GamePluginCreateRequest` with the manifest shape. Rejected because existing server-management tests and API contracts already use the metadata resource directly.

### Decision 3: Deny unsafe permissions by explicit allowlists and substring checks

Plugin manifests may declare scoped permissions such as server lifecycle, file, log, artifact, and platform-mediated AI permissions. They must not declare direct run sockets, raw host paths, raw credentials, raw AI keys, provider keys, or direct run credentials. `plugins/` catches these during schema/test validation and `platform/` repeats the safety validation before registry insertion.

Alternative considered: rely only on JSON Schema enum restrictions. Rejected because unsafe intent can appear in action paths, capability names, or future fields; backend validation still needs an explicit defense.

### Decision 4: Registry metadata is marketplace-ready but not commerce-oriented

Registry responses include identity, version, server type/display name, manifest/schema references, required run capabilities, permissions, pages, and AI purposes. They intentionally exclude pricing, cloud host purchase flows, and provider marketplace concepts.

Alternative considered: add a richer marketplace catalog model now. Rejected because the repository scope is game server management, and later UI can derive its first catalog view from registry metadata.

## Risks / Trade-offs

- [Risk] The plugin manifest contract may evolve when plugin bridge work starts. Mitigation: keep this change focused on registry metadata and add bridge-specific fields in the next OpenSpec change.
- [Risk] Duplicating contract shapes across TypeScript and Go can drift. Mitigation: tests cover the example manifest and platform manifest registration until a generated contract package is introduced.
- [Risk] Strict allowlists can reject useful future plugin capabilities. Mitigation: add new allowed capability/permission keys through explicit OpenSpec changes.

## Migration Plan

1. Add plugin schema restrictions, fixtures, and validation tests while keeping the development example valid.
2. Add platform manifest DTO/domain conversion, validators, service registration, and API route tests.
3. Keep existing `POST /api/v1/game-plugins` metadata creation working for current tests.
4. Validate the change with plugin tests, platform tests, structure check, and strict OpenSpec validation.

Rollback during this phase is straightforward: remove the manifest registration route and schema/test additions before downstream plugin bridge work depends on them.

## Open Questions

- Whether manifest contract generation should be added in the plugin bridge change or a later contract-generation change.
- Whether registry metadata should eventually support signed manifest artifacts before plugin publish/install workflows are implemented.