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, direct 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 declared file read/write dispatch for logical file keys. A completed files.read job may be projected through a Platform-owned declared-file snapshot endpoint, which accepts only a declared logical file key, returns no host path or job payload, and redacts secret-like assignment values before returning content. Modeled edits and optional raw config edits require a visible diff preview before the Platform queues a declared files.write job.
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.
6. Treat the SCUM workbench as one selected logical file at a time. The left pane contains only declared directories and files. The right pane presents either modeled fields or an optional raw mode for an editable configuration file, and a read-only log view for a log file. Selection changes must not trigger unbounded polling or path-based requests.
7. Render the plugin bundle in embedded mode when it is mounted under a server-detail section. The generic plugin page frame and host-context diagnostics remain available for direct plugin routes, but must not be nested inside the file-management tab.
8. Keep Companion player, reward, state, vehicle, and trajectory controls out of this page. Those remain available through their separately scoped plugin-control experiences and must not obscure the file workflow.

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.
• [A raw file has not completed an authorized read] → show an explicit pending or empty state rather than an invented template or stale file content.
• [A declared file contains a secret-like assignment] → redact its value in the snapshot while retaining the surrounding file structure for operational review.

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.