browser/openspec/changes/implement-platform-observability-and-config-read/specs/platform-observability-and-config-read/spec.md

ADDED Requirements

Requirement: Platform exposes resource usage metrics

The platform SHALL expose a bounded platform resource usage endpoint for the management console.

Scenario: Platform metrics loaded

• WHEN an authorized platform administrator requests platform resource usage
• THEN the platform MUST return CPU, memory, disk, source, and timestamp metadata in a named DTO response

Scenario: Platform metrics remain safe

• WHEN the platform returns resource usage data
• THEN the response MUST NOT include host paths, raw credentials, direct sockets, storage backend credentials, or raw AI provider keys

Requirement: Platform exposes per-server metrics

The platform SHALL expose bounded per-server metrics for server management and overview pages.

Scenario: Server metrics listed

• WHEN an authorized user requests server metrics
• THEN the platform MUST return only metrics for server instances visible to that user

Scenario: Pending metrics are bounded

• WHEN a server does not have current metrics
• THEN the platform MUST return a bounded missing/pending representation rather than unsafe fallback internals

Requirement: Server config read is safe and role scoped

The platform SHALL expose a server config read endpoint that returns logical config content for an authorized server instance.

Scenario: Owner reads server config

• WHEN a server owner requests config for their server instance
• THEN the platform MUST return config content, config version, server instance ID, and bounded metadata

Scenario: Unauthorized config read rejected

• WHEN a user without access requests server config
• THEN the platform MUST reject the request and MUST NOT return config content

Scenario: Config response hides run internals

• WHEN the platform returns server config
• THEN the response MUST NOT expose run credentials, raw host paths, direct sockets, or raw secret values

Requirement: Console uses API-backed observability and config reads

The frontend SHALL prefer API-backed platform metrics, server metrics, and server config content over hardcoded production data.

Scenario: API config suppresses fallback

• WHEN the server config API returns content
• THEN ServerDetailPage MUST render that content and MUST NOT display the local sample config label

Scenario: Metrics render from API

• WHEN metrics APIs return data
• THEN HomePage and server cards MUST render API metric values with safe loading/error states

Scenario: Fallback is explicit

• WHEN a development fallback is used because an API is unavailable
• THEN the UI MUST label it as local/demo fallback and MUST NOT present it as persisted platform data