docs: require yaml first hwpod deployment

.agents/skills/unidesk-hwpod-ops/SKILL.md

@@ -15,6 +15,7 @@ description: UniDesk HWLAB HWPOD 节点运维技能，覆盖 Windows 单文件 P
 - Secret 只通过 YAML `sourceRef`/`targetKey` 和受控入口下发。状态、日志和 issue 只披露 presence、fingerprint 和脱敏摘要。
 - Windows 节点使用主动出站 WebSocket；不要为用户 PC 增加入站端口或 direct-url fallback。
 - Windows Python UI node 必须优先用目标 Windows 交互用户可见的原生 `python.exe` 启动。不要用 WSL Python、SSH helper 自带解释器、Bun runner 或非交互 Windows service 替代；解释器路径/版本必须进入 node profile 与状态证据。
+- HWPOD node 部署必须是 YAML-first + repo-owned CLI。只支持 owning YAML 已声明且 `trans` route 可解析、可访问的 node；CLI 可以在内部使用 `trans` 作为 transport，但操作者不得用手写 `trans`/PowerShell/cmd 完成安装、更新、配置或自启动。受控 CLI 缺失时先实现 CLI，不把手工部署当临时完成态。
 - 调查可只读访问现场。安装、注册、更新、停止旧 runner 或改 MDTODO source 属于运行面变更，必须先加载 `$dad-dev`；部署/rollout 同时加载 `$unidesk-cicd`，YAML 变更同时加载 `$unidesk-ymalops`。
 - 远端操作走 `$unidesk-trans`。普通 `trans` 保持短连接；GUI 进程不得作为透传子进程长挂。
 - Python node 当前若没有 workspace allowlist/规范化、注册认证或 capability parity，不得把“WebSocket 已连接”报告为 HWPOD/MDTODO 可用。
@@ -44,8 +45,8 @@ Read [references/python-ui-node.md](references/python-ui-node.md) for the curren
 
 1. Observe the selected HWLAB node/lane, public origin, Python release metadata, Windows user/session, current node process, task/Run key, config presence and legacy runners.
 2. Update the owning spec first when node identity, workspace root, resource binding, authentication, capabilities or MDTODO source changes.
-3. Render/validate config before touching Windows. Keep nodeId, URL, workspace and retry/update settings out of generated helper code.
-4. Install or update the published Python artifact by verified SHA. Resolve the target interactive user's Windows `python.exe`, record its path/version, and use it to launch the file in that Windows session so GUI and tray are visible; use a login-start mechanism only when declared by YAML.
+3. Use the repo-owned `hwlab nodes hwpod-node` plan/status/apply command family selected by current CLI help. Require its preflight to resolve the YAML node profile and prove the node's `trans` route is reachable before mutation. If this command family does not exist, implement it before deployment.
+4. Let the controlled CLI render/validate config, fetch the published Python artifact, verify SHA, resolve the target interactive user's Windows `python.exe`, install files and apply the YAML-declared login-start policy. Keep nodeId, URL, workspace and retry/update settings out of generated helper code.
 5. Prove one active authority, expected version/nodeId, registration, `node.health`, `node.inventory`, bounded workspace read and structured diagnostics.
 6. Validate MDTODO through the HWLAB Web-equivalent path: source save, probe, reindex, files/tasks visible. Direct `trans cat` is only P1 diagnosis.
 7. Record source commit, artifact SHA, nodeId, workspace fingerprint/path summary, registration state, operation request/trace IDs and MDTODO source/reindex result. Never record raw Markdown or credentials by default.
@@ -53,6 +54,7 @@ Read [references/python-ui-node.md](references/python-ui-node.md) for the curren
 ## Stop Conditions
 
 - Stop before mutation if the selected lane/source authority is unclear or stale.
+- Stop before deployment if the target is absent from owning YAML, has no resolvable/reachable `trans` route, or the repo-owned plan/status/apply CLI is missing.
 - Stop before starting a second runner if an existing process controls the same nodeId/resource.
 - Stop before MDTODO write/reindex if workspace containment is not enforced or the source can escape its declared root.
 - Treat node mismatch, auth failure, missing workspace, capability mismatch, legacy drift and source projection failure as different blockers.

.agents/skills/unidesk-hwpod-ops/references/python-ui-node.md

@@ -46,6 +46,20 @@ $root = Join-Path $HOME ".hwlab"
 
 Read config fields only when needed and redact any unknown future Secret-bearing field. Prefer cloud `node.health`, `node.version`, `node.inventory` and `node.diagnostics` results for registration/runtime evidence.
 
+## Controlled Deployment
+
+Deployment belongs to a YAML-first UniDesk CLI command family, not to an operator recipe. The command family must provide bounded `plan`, `status` and confirmed `apply` actions and must:
+
+- resolve node/lane, Windows route, interactive user, pythonPath, runtime root, artifact/update origin, nodeId, SecretRefs, allowed workspace roots and login-start policy from owning YAML/configRefs;
+- reject targets without a resolvable and reachable `trans` route;
+- use `trans` only inside the CLI transport adapter;
+- verify downloaded artifact SHA before writing;
+- make apply idempotent and report written file fingerprints, config fingerprint, interpreter version, start registration, process/registry state and redacted blockers;
+- avoid launching the GUI as a child of the short SSH/trans request;
+- preserve an interactive Windows user session for GUI/tray and distinguish "installed" from "visible and registered".
+
+Until this command family exists, only read-only discovery is allowed. Manual download, remote PowerShell file writes, ad hoc Scheduled Tasks and direct process launch are diagnostics, not deployment evidence.
+
 ## Known Gaps To Check
 
 Never assume the newest published file has solved these items; inspect the selected source/version:

.agents/skills/unidesk-hwpod-ops/references/workspace-mdtodo.md

@@ -19,12 +19,13 @@ For a Windows Python UI node, `workspaceRootRef` must use the Windows path visib
 1. Confirm the Windows path exists, is a directory and contains the intended MDTODO root.
 2. Allocate a nodeId distinct from D601 and all existing nodes.
 3. Add YAML declarations for desktop node, HWPOD resource/workspace policy and MDTODO source.
-4. Ensure the Python node enforces declared workspace roots with canonical-path containment; reject absolute paths outside them, `..`, symlink/junction escape and undeclared roots.
-5. Configure registration authentication from SecretRef without printing credentials.
-6. Install the SHA-verified Python artifact and launch in the selected interactive Windows user session.
-7. Prove cloud registration and expected capabilities.
-8. Run `node.inventory` against the declared root, then bounded `workspace.ls`/`workspace.cat` under the MDTODO root.
-9. Save/probe/reindex the Project Management source and verify files/tasks in HWLAB Web.
+4. Add a resolvable `trans` Windows route to the node profile and prove it is reachable with the controlled CLI preflight.
+5. Ensure the Python node enforces declared workspace roots with canonical-path containment; reject absolute paths outside them, `..`, symlink/junction escape and undeclared roots.
+6. Configure registration authentication from SecretRef without printing credentials.
+7. Use the repo-owned YAML-first CLI to install the SHA-verified Python artifact and apply the selected interactive Windows login-start policy.
+8. Prove cloud registration and expected capabilities.
+9. Run `node.inventory` against the declared root, then bounded `workspace.ls`/`workspace.cat` under the MDTODO root.
+10. Save/probe/reindex the Project Management source and verify files/tasks in HWLAB Web.
 
 ## MDTODO Acceptance