pikasTech-HWLAB/docs/cloud-web-workbench.md

HWLAB Cloud Workbench Frontend Contract

This document is the review contract for DC-DCSN-P0-2026-003, pikasTech/HWLAB#99, and pikasTech/HWLAB#78. It defines the Cloud Workbench frontend design and acceptance surface for later implementation. It is documentation-only: it does not authorize deployment, service restart, PROD access, heavyweight browser automation, or hardware mutation.

The default Cloud Web experience may be rebuilt from scratch to satisfy this contract. Existing Gate or M3 diagnostics screens from #59 are not the default homepage contract.

Product Position

Cloud Workbench is the default browser entry at http://74.48.78.17:16666. It should feel like a VS Code-style operator workbench for HWLAB DEV: resources on the left, agent conversation and trace in the center, evidence and hardware context on the right, and commands at the bottom.

The workbench is a read-only or dry-run coordination surface until a later contract explicitly enables a narrow write path. It must not become a generic hardware control panel.

Route Structure

The frontend route model must keep the workbench as the default route and move diagnostics under secondary routes:

Route	Purpose	Default	Source boundary
/	Cloud Workbench default. Shows agent conversation, trace, selected resource context, hardware/evidence side panel, and command input.	Yes	Same-origin /v1, read-only /json-rpc, source/gate report, blocked report.
/workbench	Explicit alias for the default workbench.	Yes, alias	Same as /.
/gate	Internal static alias for the read-only gate diagnostics view.	No	Same as /diagnostics/gate; source/gate report and same-origin read-only diagnostics only.
/diagnostics	Secondary diagnostics hub that links to status and gate views.	No	Same-origin /v1 and report fixtures only.
/diagnostics/status	Read-only DEV status: edge, router, API, web, DB readiness, agent service health, and artifact identity.	No	Same-origin /v1/status or equivalent read-only status endpoint.
/diagnostics/gate	Read-only gate and M3 diagnostics inherited from #59: topology, route, health, blockers, and evidence summary.	No	Gate report and blocked report; read-only /json-rpc only when already defined.
/agents	Agent sessions, workers, skills, trace timeline, and cleanup status. Can be a focused view or a left-rail activity inside /.	No	Same-origin /v1 agent summaries and source report.
/hardware	Hardware resources, gateway sessions, patch-panel topology, box simulators, capabilities, and blockers.	No	Read-only /json-rpc status/list methods and same-origin /v1 summaries.
/records	Trusted records: evidence, audit, trace, operation IDs, artifact tag/commit/digest, and report links.	No	Gate report, source report, blocked report, and same-origin /v1 summaries.

The route relationship is:

• / and /workbench are the primary product surface.
• /gate is a short internal alias for the same hidden gate view as /diagnostics/gate; it must not become the default route.
• diagnostics/status and diagnostics/gate are auxiliary views for troubleshooting and acceptance review.
• Agent, hardware resources, and trusted records are first-class workbench domains. They may be implemented as routes, tabs, or focused activity-rail modes, but the default route must show how they relate to each other.
• #59 diagnostics remain available under /diagnostics/gate; they must not define the default homepage.

Layout Structure

The default workbench layout must use four stable regions:

Region	Required content	Required behavior	sourceKind labels
Left activity rail and resource tree	Activity icons for Workbench, Agent, Hardware, Records, Diagnostics; resource tree for project, gateway sessions, patch-panel, box resources, capabilities, agent sessions, workers, and reports.	Selecting an item changes the center and right-panel context without implying mutation. Unknown or blocked items remain visible with disabled actions.	SOURCE, DRY-RUN, DEV-LIVE, BLOCKED.
Center agent conversation and trace	Agent conversation stream, plan/trace events, selected operation timeline, agent/worker/session IDs, and blocker messages.	Conversation input defaults to no-mutation guidance. Any future action that could mutate hardware is disabled unless a later contract explicitly enables it. Trace rows are clickable and open evidence context.	SOURCE, LOCAL, DRY-RUN, DEV-LIVE, BLOCKED.
Right hardware/evidence side panel	Selected hardware resource, patch-panel wiring, gateway/box status, evidence record, audit record, operation ID, artifact commit/tag/digest, and report provenance.	Panel is read-only. It explains why an item is blocked, dry-run, source-only, or live. It must not expose generic hardware write controls.	SOURCE, DRY-RUN, DEV-LIVE, BLOCKED.
Bottom command/input area	Command composer, dry-run preview, selected scope, source boundary, and disabled live controls.	Default mode is read-only or dry-run. Live hardware execution controls are disabled with an explicit blocker reason until a separate acceptance contract permits them.	DRY-RUN, BLOCKED, optionally DEV-LIVE for read-only observations only.

The UI may use a full rewrite of web/hwlab-cloud-web. It should preserve the public :16666 entrypoint and same-origin API assumptions rather than the old diagnostics-first component structure.

Data Sources

Every visible panel must display or carry a sourceKind value. The frontend must keep these data sources separate:

Source	Use	Allowed calls	sourceKind
Same-origin /v1	Cloud API summaries for status, agents, records, health, artifact identity, and read-only workbench aggregation.	GET or documented read-only RPC wrappers through the same origin as the web bundle.	DEV-LIVE only when observed from the real DEV route; otherwise BLOCKED or SOURCE.
Read-only /json-rpc	Hardware/gateway/patch-panel status, capabilities, topology, and evidence lookups already defined as safe reads.	Only list/status/get/describe methods. No generic write, no direct box mutation, no bypass of patch-panel ownership.	DEV-LIVE for read-only real DEV observations; DRY-RUN for fixture-backed previews.
Source report	Checked-in contracts, manifests, schemas, service IDs, and documentation.	Static fetch or bundled build asset only.	SOURCE.
Gate report	reports/dev-gate gate summaries, DEV layer status, artifact identity, and M3/M4/M5 readiness.	Read-only local report content or same-origin report endpoint.	SOURCE, DRY-RUN, DEV-LIVE, or BLOCKED exactly as reported.
Blocked report	Open blockers for DB, M3, M4, edge/route, artifacts, registry, and evidence gaps.	Read-only report content or same-origin summary endpoint.	BLOCKED.

The frontend must not infer DEV-LIVE from successful page load on :16666. DEV-LIVE requires an observation from the real DEV route for the specific thing being displayed.

Status Labels

Use these labels consistently:

Label	Meaning	UI rule
SOURCE	Repository documentation, schemas, source fixtures, manifests, or checked-in reports.	May be shown as design/contract readiness only. Never claim live state.
LOCAL	Localhost or in-process smoke result.	May appear in trace or acceptance summaries, but not as live DEV evidence.
DRY-RUN	Fixture-backed or no-mutation preview.	Command previews and agent plans default here. Must state that no DEV/PROD state changed.
DEV-LIVE	Read-only observation from the real DEV route for the exact component, record, or route shown.	May mark edge, API, DB, artifact, agent, or hardware status only when supported by specific evidence.
BLOCKED	Missing, stale, unsafe, or not-yet-authorized evidence or action.	Must show blocker reason and keep unsafe or unproven controls disabled.

The UI must never upgrade SOURCE, LOCAL, DRY-RUN, edge-only, or front-end-only observations into M3 or M4 DEV-LIVE.

Interaction Boundaries

Allowed interactions for this contract:

• Navigate routes and activity rail modes.
• Select project, gateway, box, patch-panel, capability, agent, worker, evidence, audit, trace, operation, and report records.
• Refresh read-only /v1 status, read-only /json-rpc status/list/get methods, source reports, gate reports, and blocked reports.
• Compose a command and view a dry-run preview with selected scope, expected evidence, and blocker reasons.
• Copy IDs, links, commands, and report references.

Disabled in the first workbench implementation:

• Run live agent hardware operations.
• Change patch-panel wiring.
• Write box, gateway, simulator, or hardware state.
• Start or stop gateway, worker, tunnel, edge, router, API, web, DB, or PROD services.
• Deploy images, apply manifests, restart services, read secrets, or run heavyweight e2e/Playwright flows.
• Mark M3, M4, or M5 accepted from the browser.

Future buttons may be visible only if they are disabled and explain the required contract, for example BLOCKED: live command requires M0-M5 gate, DEV-only authorization, and patch-panel-owned operation evidence.

Do not add a generic hardware command form. Any future write path must be narrow, named, patch-panel owned, audited, evidenced, DEV-only, and covered by a new acceptance contract.

Relationship To #59

#59 defined a read-only diagnostics console for M3 topology, route, health, blockers, and evidence summary. For #99, that surface is retained as /diagnostics/gate and may also appear as a Diagnostics activity in the left rail.

#59 must not define /, /workbench, product navigation, or the default homepage. The default homepage is the Cloud Workbench described here.

The npm run web:m3-readonly guard remains useful as a safety check for the diagnostics route and same-origin read-only boundary. A later implementation may update the script to reflect the new workbench route model, but it must continue to fail on hardware write APIs, public endpoint drift, and evidence misclassification.

DEV Acceptance Contract

Acceptance for the frontend design and later implementation is:

Area	Acceptance
Default page	http://74.48.78.17:16666/ opens the Cloud Workbench, not the Gate/M3 Diagnostics dashboard; its first screen does not show Gate, BLOCKED, M0-M5, or acceptance-review copy.
API status	http://74.48.78.17:16667 remains the DEV API/edge/status boundary; browser code uses same-origin /v1 for workbench data and only read-only /json-rpc methods for diagnostics/hardware status.
Routes	/, /workbench, /gate, /diagnostics, /diagnostics/status, /diagnostics/gate, Agent, hardware resources, and trusted records are represented in navigation or route aliases.
Layout	Left activity rail/resource tree, center agent conversation/trace, right hardware/evidence side panel, and bottom command/input area are present on the default workbench.
Labels	SOURCE, LOCAL, DRY-RUN, DEV-LIVE, and BLOCKED labels are visible where evidence state is shown and follow the rules above.
Read-only boundary	Hardware resources and diagnostics are read-only. Live controls are disabled with blocker reasons.
Browser smoke	A lightweight screenshot/manual browser smoke may verify that the default page loads, the workbench regions are visible, diagnostics is secondary, and no text or controls imply generic hardware writes.
Artifact identity	Acceptance notes must include web image tag, commit, digest or not_applicable reason, build source, deploy environment, and health timestamp when runtime evidence is claimed.
Blocker display	DB, M3, and M4 blockers must be displayed separately when present. DB readiness cannot green M3/M4; edge route live cannot green DB, M3, or M4.

This document does not require a heavy check or browser e2e run. For the documentation PR, the minimum validation is git diff --check and an rg scan for the task terms and frozen labels.