browser/openspec/changes/redesign-platform-web-interactions/specs/operation-feedback-and-safety/spec.md

ADDED Requirements

Requirement: User actions have visible lifecycle feedback

The platform web application SHALL show visible lifecycle feedback for user-triggered operations.

Scenario: Button enters pending state

• WHEN a user submits an operation from a button or form
• THEN the initiating control shows a pending or loading state and prevents accidental duplicate submission until the operation state is known

Scenario: Operation success is visible

• WHEN a submitted operation completes successfully
• THEN the UI shows a success result and provides relevant next actions such as viewing logs or operation history when available

Scenario: Operation failure is visible

• WHEN a submitted operation fails
• THEN the UI shows a failure result with an error reason and relevant retry or diagnostic actions when available

Requirement: Operations are traceable

The platform web application SHALL expose a traceable operation or job identity for operations that affect platform, run, plugin, server, or LLM systems.

Scenario: Operation detail includes trace data

• WHEN an operation is created or retrieved
• THEN the UI can display its operation/job ID, target, requester, status, timestamps, and error reason when available

Scenario: Failure includes diagnostic identifier

• WHEN an operation or data load fails with a diagnostic identifier
• THEN the UI displays the identifier or provides a copyable diagnostic summary for debugging

Requirement: One user intent maps to one visible business operation

The platform web application SHALL present each user-triggered action as one visible business operation even if the backend performs multiple internal steps.

Scenario: Complex action is tracked as one operation

• WHEN a user triggers a complex action such as restart server, send gift, apply plugin control, or write configuration
• THEN the UI displays one operation lifecycle for the user intent and tracks progress or result through one operation/job context

Scenario: Multi-step backend failure is debuggable

• WHEN an internal step of a complex action fails
• THEN the operation result identifies the failing stage or error reason when that information is available

Requirement: Empty states are actionable

The platform web application SHALL show actionable empty states instead of blank pages for expected no-data conditions.

Scenario: Server list is empty for server administrator

• WHEN a server administrator has no manageable servers
• THEN the server list shows an empty state explaining that no manageable servers are available and provides a refresh action

Scenario: Platform overview has no servers

• WHEN a platform administrator opens the platform overview and no server instances exist
• THEN the overview shows an empty state with a management-oriented next action rather than a blank page

Requirement: Loading states are scoped

The platform web application SHALL use scoped loading states so one slow module does not blank unrelated content.

Scenario: Dashboard module loads independently

• WHEN one platform overview module is loading slowly
• THEN the UI shows a loading state for that module while keeping already loaded modules visible

Scenario: Server card metrics load independently

• WHEN server metrics are still loading
• THEN the server card remains visible with stable placeholders for pending metrics

Requirement: Errors identify affected scope

The platform web application SHALL display errors with enough scope and recovery information for operators to act.

Scenario: Module load error is localized

• WHEN a dashboard module or server detail section fails to load
• THEN the error is shown within the affected module or section with retry and diagnostic information when available

Scenario: Full-page error preserves navigation

• WHEN a full-page error prevents rendering the requested workspace
• THEN the application preserves usable global navigation or a safe route back to an authorized workspace

Requirement: Dangerous actions require confirmation

The platform web application SHALL require explicit confirmation for destructive or disruptive operations.

Scenario: Restart or stop requires confirmation

• WHEN a user initiates a disruptive server action such as stop or restart
• THEN the UI asks for confirmation before submitting the operation

Scenario: Configuration write requires diff confirmation

• WHEN a user initiates a configuration write from manual edits or LLM output
• THEN the UI requires the user to review and confirm the diff before submission

Requirement: AI and run safety boundaries are preserved

The platform web application SHALL preserve platform AI provider and run communication safety boundaries in all redesigned interactions.

Scenario: AI keys are never exposed to frontend

• WHEN platform_web uses AI provider health or LLM assistance features
• THEN raw AI keys and provider secrets are not exposed to platform_web or plugin pages

Scenario: Run internals are not exposed to frontend

• WHEN platform_web displays server operations, logs, artifacts, or diagnostics
• THEN host paths, raw credentials, and direct run sockets are not exposed to platform_web or plugin pages