# HWLAB Cloud Workbench Reference

Cloud Workbench is the default user-facing frontend at
`http://74.48.78.17:16666/`. It must serve the #99 workbench direction and the
#108 UX constraints while respecting the M3 boundary from
`DC-DCSN-P0-2026-003`.

## Default Route

- `/` must show the Cloud Workbench, not Gate, status, help, or diagnostics.
- The default first screen must not show Gate, `BLOCKED`, `M0-M5`, or
  acceptance-review copy. Those terms may remain in hidden/internal views.
- Gate and diagnostics are secondary routes or right-panel support views.
- `/gate` and `/diagnostics/gate` are internal diagnostic aliases served by the
  same Cloud Web app router. They may carry Gate, blocker, and M0-M5 evidence
  because they are not the default homepage.
- `http://74.48.78.17:16667/` remains the API/edge boundary.
- Browser data sources are same-origin `/v1`, read-only `/json-rpc`, source
  reports, gate reports, and blocked reports.

## Required Layout

The default workbench follows the #99 VS Code-style structure:

| Region | Required role |
| --- | --- |
| Left | Activity rail, project/function/resource navigation, hardware resources. |
| Center top | Agent messages, execution process, trace, selected operation context. |
| Center bottom | Agent input or equivalent command composer. |
| Right top | BOX-SIMU, Gateway-SIMU, and patch-panel hardware state. |
| Right bottom | Controls, wiring, trusted records, Audit, and Diagnostics tabs. |

Unavailable or future controls must be disabled with blocker context. The
frontend must not imply generic direct hardware control.

## UX Constraints

The #108 constraints are current baseline:

- no page-level vertical scroll on the outer shell; scrolling belongs inside
  workbench panels;
- user-visible UI text is Chinese except machine identifiers, protocol names,
  API paths, IDs, commits, endpoints, and source labels that need their exact
  spelling;
- an internal help page exists, but it is not the homepage;
- help content is maintained as `web/hwlab-cloud-web/help.md` and rendered by
  the frontend instead of being only a JS string.

## Evidence And Labels

Visible runtime or evidence state must keep `SOURCE`, `LOCAL`, `DRY-RUN`,
`DEV-LIVE`, and `BLOCKED` distinct. Loading the page from `16666` proves only
that Cloud Web is reachable. It does not prove DB readiness, M3, M4, M5, or a
hardware loop.

The frontend may show read-only DEV observations when they are tied to the
exact route or component. It must not upgrade source fixtures, dry-run output,
front-end state, or edge-only health into M3 DEV-LIVE.

## Lightweight Checks

Use the existing lightweight checks unless a task explicitly authorizes a
heavier browser run:

```sh
node web/hwlab-cloud-web/scripts/check.mjs
node web/hwlab-cloud-web/scripts/build.mjs
node scripts/dev-cloud-workbench-smoke.mjs --static
```

The static smoke checks both sides of the route contract: `/` remains the
user-facing workbench, while `/gate` and `/diagnostics/gate` remain available
for internal diagnostics. This PR-class check is intentionally source-only and
does not deploy, restart services, or run browser e2e.

Live checks against `http://74.48.78.17:16666/` are read-only and must report
blocked/skip instead of false green when the browser or network path is not
available.

## Stable Sources

- [pikasTech/HWLAB#99](https://github.com/pikasTech/HWLAB/issues/99): default
  Cloud Workbench direction.
- [pikasTech/HWLAB#108](https://github.com/pikasTech/HWLAB/issues/108): no
  outer scroll, Chinese UI, internal Markdown help.
- [docs/cloud-web-workbench.md](../cloud-web-workbench.md): detailed frontend
  contract.
- [docs/dev-deploy-apply.md](../dev-deploy-apply.md): Cloud Web manual rollout
  path.