UI Preview Quick-Deploy Protocol + MOW Canvas v2 Scaffold

Date: 2026-05-29 · Status: ✅ PASS (protocol defined; v2 scaffold deployed; review-log schema upgraded). No v2 fabricated (no Cowork HTML provided). No PG/Directus/Qdrant mutation; no production Nuxt; v1 not overwritten (md5 verified).

Builds on knowledge/dev/reports/architecture/ai-shared-ui-workspace-preview-pipeline-2026-05-29/. KB = technical SoT; VPS /ui-preview = visual SoT; Drive = human/Cowork drafting.

---

1. Quick-deploy convention

Input: a single index.html, or an HTML/CSS/JSON bundle from Cowork (chat paste or files).

host dir : /opt/incomex/docker/nginx/static/ui-preview/mow/unified-canvas/vN/
URL      : https://vps.incomexsaigoncorp.vn/ui-preview/mow/unified-canvas/vN/

• vN = next integer (v2, v3, …). Never overwrite a prior version.
• nginx route location /ui-preview/ already exists → no nginx change needed for a new version.
• Generic form for any surface: …/ui-preview/<project>/<surface>/vN/.

Required files per version

File	Required	Notes
index.html	✅	the preview (no business logic, no secrets)
styles.css	optional	if not inlined
mock-data.json	optional	fixture matching the data contract
preview.meta.json	✅	machine-readable status/links (schema below)
CHANGELOG.md	✅	one entry per version, newest first

preview.meta.json (required keys)

{
  "project":"mow","surface":"unified-canvas","version":"vN","previous_version":"v(N-1)",
  "status":"draft","preview_url":"https://vps.incomexsaigoncorp.vn/ui-preview/mow/unified-canvas/vN/",
  "spec_path":"knowledge/dev/ui/mow/unified-canvas/spec.md",
  "review_log_path":"knowledge/dev/ui/mow/unified-canvas/review-log.md",
  "created_by":"claude_code","change_summary":"...",
  "constraints":["no production UI","no business logic","no backend mutation","no secrets","must not overwrite prior version"],
  "approval_status":"pending_user_review"
}

---

2. Deploy steps (Claude Code)

# 0. choose vN = (latest existing version) + 1 ; confirm it does NOT exist yet
ssh contabo 'ls -d /opt/incomex/docker/nginx/static/ui-preview/mow/unified-canvas/v* 2>/dev/null'

# 1. build files locally under /tmp/incomex-preview-vN/mow/unified-canvas/vN/
#    (index.html [+ styles.css/mock-data.json] + preview.meta.json + CHANGELOG.md)

# 2. capture v1..v(N-1) fingerprints (immutability guard)
ssh contabo 'md5sum /opt/incomex/docker/nginx/static/ui-preview/mow/unified-canvas/v*/index.html'

# 3. deploy ONLY the new version dir (tar preserves the path; never touches siblings)
cd /tmp/incomex-preview-vN && tar -cf - . | ssh contabo \
  'tar -C /opt/incomex/docker/nginx/static/ui-preview -xf -'

# 4. re-check prior fingerprints == step 2 (must be identical → no overwrite)
# 5. verify HTTP 200 + content-type
curl -sS -o /dev/null -w "%{http_code} %{content_type}\n" \
  https://vps.incomexsaigoncorp.vn/ui-preview/mow/unified-canvas/vN/

# 6. update KB review-log.md: bump current_version, set previous_version, change_summary,
#    approval_status=pending_user_review; append a per-version block + a Log entry.

No nginx edit, no reload, no DB touch. Rollback for a bad version = rm -rf …/vN (prior versions are independent).

---

3. review-log.md schema (upgraded — applied this session)

Front-matter now carries: current_version, preview_url, previous_version, protocol_path, status, approval_status, next_requested_changes, source_refs. Plus a per-version YAML block with current_version / preview_url / previous_version / change_summary / reviewer_notes / approval_status / next_requested_changes, and a Versions table. (See knowledge/dev/ui/mow/unified-canvas/review-log.md, rev 2.)

approval_status values: awaiting_cowork_html → pending_user_review → changes_requested ⇄ draft → approved → nuxt_shell_authorized. Only the User sets approved (Đ37, no self-approval).

---

4. v2 scaffold status

Deployed at https://vps.incomexsaigoncorp.vn/ui-preview/mow/unified-canvas/v2/ — scaffold only.

• Files: index.html (scaffold landing), preview.meta.json (status: scaffold, approval_status: awaiting_cowork_html), CHANGELOG.md.
• No final v2 designed by an agent (GPT direction). v1 verified unchanged (md5 identical before/after).
• Planned v2 changes (to be implemented by Cowork): (a) progressive disclosure for T1 Task Card; (b) clearer proposal-mode transition; (c) expandable sub-list overflow.
• Carry-forward from v1 (must keep): one-frame/six-tier, tabs T6→T1, breadcrumb, Proposal Mode, traffic-light colors, light theme, no direct-edit, no business logic.

---

5. Copy-paste deploy prompt template

Bạn là Claude Code. Deploy HTML Cowork sau đây thành preview phiên bản vN cho MOW Unified Canvas.

VERSION: vN            (vN = phiên bản hiện có lớn nhất + 1; KHÔNG ghi đè v cũ)
SURFACE: mow/unified-canvas
SOURCE (Cowork HTML/CSS/JSON — dán bên dưới):
<<<
[ ... dán HTML (và CSS/JSON nếu có) ở đây ... ]
>>>
CHANGE_SUMMARY: [1-2 câu Cowork đổi gì so với v(N-1)]

CÁC BƯỚC:
1. Xác nhận thư mục vN CHƯA tồn tại (ls .../ui-preview/mow/unified-canvas/v*).
2. Ghi file local: index.html (+ styles.css/mock-data.json nếu có) + preview.meta.json + CHANGELOG.md.
3. md5sum các version cũ → deploy CHỈ thư mục vN bằng tar|ssh → md5sum lại (phải y hệt = không ghi đè).
4. curl verify HTTP 200 + content-type.
5. Cập nhật review-log.md: current_version=vN, previous_version=v(N-1), change_summary,
   approval_status=pending_user_review, thêm block + Log entry. Cập nhật CHANGELOG.md.

RÀNG BUỘC: chỉ static; KHÔNG PG/Directus/Qdrant; KHÔNG secrets; KHÔNG business logic;
KHÔNG production Nuxt; KHÔNG ghi đè v cũ; versioned bắt buộc. KHÔNG tự approve (Đ37).
Nếu SOURCE trống → DỪNG, chỉ giữ scaffold, không bịa v2.

---

6. Next action for Cowork

Build v2 HTML implementing changes a/b/c (keep the v1 philosophy + interaction model + tokens; light theme; desktop-first), then paste it into the template above (or drop a bundle). Claude Code deploys it to /ui-preview/mow/unified-canvas/v2/ (replacing the scaffold in the v2 slot) and flips approval_status to pending_user_review. Optionally set PHU-LUC Drive files to "anyone with link" to host originals verbatim.

---

7. Forbidden compliance

Forbidden	Status
Production Nuxt	✅ none
PG/Directus/Qdrant mutation	✅ none
Overwrite v1	✅ md5 identical before/after
Unversioned preview	✅ v2 path versioned
Secrets	✅ none
Business logic	✅ scaffold has none
Hardcoded production workflow as final	✅ scaffold is a placeholder, labelled
Fabricate final v2	✅ not done — scaffold only, awaiting_cowork_html