browser/openspec/changes/add-scum-file-config-workbench/design.md

Context

The SCUM plugin already declares runtime config mappings and log sources, while Platform exposes safe configuration read/diff/approval APIs and a scoped file-operation dispatcher. Its current plugin page is an operations overview with semantic logs; this does not match the operator's configuration-first workflow.

Goals / Non-Goals

Goals:

• Make plugin-owned logical file declarations the single catalog for SCUM configuration and log file scopes.
• Model safe configuration fields separately from the raw INI content, then compose changes into the existing Platform diff-preview and approval flow.
• Present declared log files and their Platform log-stream contents in the same workbench.
• Redirect historical SCUM page keys to the default files-config page without breaking shared plugin routing.

Non-Goals:

• Arbitrary filesystem browsing, path entry, terminals, FTP/rsync controls, raw secrets, or host/socket exposure.
• Raw text as the default configuration editor, write access for unknown fields, or a new run-side protocol.
• Changing global server-list behavior or non-SCUM plugin pages.

Decisions

1. Add fileWorkspace to the plugin manifest/runtime projection. It contains safe logical directories/files and modeled fields, rather than host paths or unbounded schemas. This makes a page contract auditable and keeps ownership with the plugin.
2. Give every modeled field an owning logical file key, Chinese operational metadata, and constrained control details. The frontend uses only these fields to compose proposed INI content; unmapped lines remain visible as read-only field records.
3. Reuse GET /config, config diff preview, and config approval for the declared primary config file. Log-file selection maps declared logical files to existing Platform log streams; no new direct file-read API is introduced.
4. Move SCUM from operations to files-config; the route resolver redirects old overview, config, logs, and operations keys only for game.scum. Other plugins keep their declared page keys unchanged.
5. Build page content from existing shared console form/list/diff classes. No page-owned surface system or global decoration is added.

Risks / Trade-offs

• [A config document may contain extra keys] → preserve them in the proposed content and show them as read-only, unmodeled rows.
• [Existing installations still link old route keys] → normalize those keys in the common resolver before page lookup.
• [A declared log stream is absent] → show an explicit unavailable state and never fall back to a filesystem path.
• [INI parsing has formatting limits] → patch only declared simple key/value fields and rely on Platform preview before approval.

Migration Plan

1. Ship manifest and Platform declaration validation/projection with the SCUM files-config page.
2. Deploy the frontend route normalization and workbench; old SCUM links resolve to files-config.
3. Rollback by restoring the previous manifest page declaration; no persisted migration or write protocol needs reversal.

Open Questions

None. The first field catalog uses existing SCUM deployment mappings and can be expanded through manifest declarations later.