feat: add browserless Penpot MCP operations

SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: corp-v1-channel-ui-ux
 description: "Use when operating or synchronizing a Corp v1 project's UI/UX channel. Maintains project frontend design work, Penpot artifacts, design-system decisions, accessibility evidence, and implementation handoffs while correlating verified activity across the project's seven channels."
-version: 1.0.0
+version: 1.1.0
 author: Hermes Agent
 license: MIT
 metadata:
@@ -85,6 +85,39 @@ Proposed work may be explored before all inputs are final, but it must remain vi
 
 Penpot is the editable source of truth for interface design at this time.
 
+### Dual MCP design plane
+
+Hermes uses two complementary Penpot MCP servers. Treat their configured `enabled` state and per-tool include list as an operational safety boundary, not as proof that a target file is ready:
+
+```yaml
+mcp_servers:
+  penpot-zcube-v1:
+    enabled: true
+    # Local stdio, browserless Penpot RPC operations.
+    tools:
+      include: [explicitly approved tools only]
+  penpot:
+    enabled: true
+    # Penpot Plugin API; requires the intended file to be open and attached.
+```
+
+- **`penpot-zcube-v1`** is the preferred browserless path for authenticated team/project/file discovery and approved page, frame, shape, text, component, alignment, media, snapshot, library-read, and export operations. It runs as a local stdio child of Hermes and uses the Bitwarden-managed Penpot API credential. It must remain pinned, production-audited, restricted to the approved Penpot instance, and fail-closed through `tools.include`.
+- **`penpot`** is the Plugin API path for richer live-file operations such as native token, variant, library-asset, flex/grid-layout, interaction, selection, and visual inspection workflows. It is usable only when its MCP token is valid and the exact intended file is actively attached in Penpot.
+
+Set `mcp_servers.<name>.enabled` to `true` or `false` through the supported Hermes configuration command or UI, then start a fresh agent session or restart the gateway for the change to take effect. Use `hermes mcp configure <name>` to toggle individual tools. Never interpret disabling one server as permission to broaden the other server's tool set. Keep sampling disabled for the community server.
+
+Before browserless mutation through `penpot-zcube-v1`:
+
+1. verify the exact team, project, file, and page IDs;
+2. inspect the current file revision and target objects;
+3. create and lock a snapshot when the change is material and the tool is enabled;
+4. apply one coherent change batch within the project boundary;
+5. read back object identity, parentage, geometry, style/content, and resulting revision;
+6. stop on revision conflict or ambiguous duplicate names rather than retrying blindly;
+7. use the backend API or a separately approved cleanup path for destructive file/project/team operations, which remain disabled in the community MCP allowlist.
+
+If the Plugin API is disconnected, use `penpot-zcube-v1` for supported browserless work instead of reporting a blanket Penpot blocker. If work requires native tokens, variants, flex/grid layout, live selection, or another capability absent from the browserless server, report that narrower plugin-attachment requirement honestly.
+
 For every governed design package:
 
 - use a project-owned Penpot project/file rather than a personal or unrelated workspace;
@@ -177,14 +210,15 @@ Link each design package from its authoritative Feature record and relevant Arch
 
 1. Resolve the exact project code and seven same-project channel IDs.
 2. Read enough channel and repository evidence to establish current Scope, Architecture, design, Delivery, and release state without duplicating prior work.
-3. Verify the Penpot file belongs to the intended project and the referenced pages/boards exist.
+3. Verify the Penpot file belongs to the intended project and the referenced pages/boards exist; select `penpot-zcube-v1` for supported browserless work or `penpot` for native live-file capabilities.
 4. Review the complete user flow, responsive states, component variants, content rules, and accessibility expectations.
 5. Confirm proposed versus approved status and immutable approval evidence.
 6. Update durable project documentation using the adopted Docusaurus skill.
 7. Validate documentation structure, links, typecheck, production build, and deployed readback when documentation changes.
 8. Read back the exact remote artifact and any posted Discord guidance.
 9. Verify that no Corp project cronjob or scheduler job exists.
-10. Report exact Penpot links, documentation paths, commit/PR/CI evidence, approval status, remaining gates, and any inaccessible Penpot surface.
+10. Verify each configured Penpot MCP server's `enabled` state, selected tools, credential presence without disclosure, and the exact readback appropriate to the chosen server.
+11. Report exact Penpot links, documentation paths, commit/PR/CI evidence, approval status, remaining gates, and any inaccessible Penpot surface.
 
 ## Common Pitfalls
 
@@ -199,6 +233,9 @@ Link each design package from its authoritative Feature record and relevant Arch
 9. Inspecting another project's channels.
 10. Creating or retaining a cronjob or scheduler job for this channel.
 11. Exposing Penpot credentials, session data, private tokens, or authorization headers.
+12. Treating a disconnected Plugin API as proof that browserless `penpot-zcube-v1` design work is impossible.
+13. Enabling all community-server tools, especially destructive team/project/file administration, instead of maintaining a fail-closed include list.
+14. Retrying a low-level `update-file` mutation after an uncertain response without revision and object readback.
 
 ## Verification Checklist
 
@@ -212,3 +249,5 @@ Link each design package from its authoritative Feature record and relevant Arch
 - [ ] Implementation handoff links exact tasks, dependencies, and acceptance evidence.
 - [ ] Project documentation and remote/deployed artifacts were verified when changed.
 - [ ] No Corp project cronjob or scheduler job exists.
+- [ ] The selected Penpot MCP server was enabled, capability-appropriate, and restricted to its approved tools.
+- [ ] Browserless mutations include exact file/page/object/revision readback; Plugin API mutations include exact active-file verification.