Document Figma handoff diagnostics

.github/workflows/developer-docs-agent.yml

@@ -33,7 +33,7 @@ jobs:
       run_kind: ${{ github.event.inputs.run_kind || 'maintenance' }}
       require_pr: ${{ github.event_name == 'workflow_dispatch' }}
       base_ref: trunk
-      docs_branch: docs-agent/build-with-wordpress-developer-docs
+      docs_branch: docs-agent/build-with-wordpress-developer-docs-v2
       writable_paths: README.md,docs/**,plugins/**/README.md
       bootstrap_contract: |
         {
@@ -51,7 +51,7 @@ jobs:
               "plugins/figma-to-wordpress-studio/src/ui.ts",
               "plugins/figma-to-wordpress-studio/tests/generate-artifact.test.mjs"
             ],
-            "requires_documentation_change": true
+            "requires_documentation_change": false
           }
         ]
       verification_commands: |

docs/README.md

@@ -20,7 +20,7 @@ Start here before changing skills, generator code, verification contracts, or ge
 | [Generated outputs](generated-outputs.md) | Generated package matrix, build pipeline, generated-output contracts, MCP config shape, telemetry MCP tool reference, verifier expectations, and Cursor export contract. | Change or review generated files under `plugins/`, add a surface, or reason about package artifacts. |
 | [Skills and integrations](skills-and-integrations.md) | Skill inventory, Studio integration concepts, MCP contracts, relationship to WordPress agent skills packaging, and safe extension boundaries. | Update shared skills, Studio guidance, or agent integration behavior. |
 | [Contributor workflows](contributor-workflows.md) | Setup, commands, change recipes, manual smoke testing, CI automation contracts, and pull request checklist. | Prepare, verify, and review a repository change. |
-| [Figma to WordPress Studio](figma-studio-runner.md) | Figma plugin handoff to the Studio CLI import path for Static Site Importer and Blocks Engine. | Review or test the Figma-to-HTML-to-WordPress integration path. |
+| [Figma to WordPress Studio](figma-studio-runner.md) | Figma plugin handoff to the Studio CLI import path for Static Site Importer and Blocks Engine, including the source payload and diagnostic logging contract. | Review or test the Figma-to-HTML-to-WordPress integration path. |
 
 ## Repository source inventory
 

docs/contributor-workflows.md

@@ -154,7 +154,7 @@ Manual documentation runs default to maintenance and should make the smallest so
 `developer-docs-agent.yml` calls the reusable `Automattic/docs-agent/.github/workflows/maintain-docs.yml` workflow for the technical documentation lane. The caller grants its `github.token` the publication permissions declared by the workflow and explicitly forwards `OPENAI_API_KEY` for live runs and the required `EXTERNAL_PACKAGE_SOURCE_POLICY` package allowlist.
 
 - `workflow_dispatch` offers `run_kind` choices of `maintenance` (the default) and `bootstrap`; pushes to `trunk` run with `run_kind: maintenance`.
-- `docs_branch` is `docs-agent/build-with-wordpress-developer-docs` and `base_ref` is `trunk`.
+- `docs_branch` is `docs-agent/build-with-wordpress-developer-docs-v2` and `base_ref` is `trunk`.
 - writable documentation paths are limited to `README.md`, `docs/**`, and `plugins/**/README.md`.
 - Docs Agent selects its native package from the reusable workflow revision pinned in this file: `Automattic/docs-agent/.github/workflows/maintain-docs.yml@7b67d341eea16b75b8e055507d36a8d8e69a1fe3`.
 - maintenance is bounded to the known Figma Studio handoff diagnostics drift from [PR #100](https://github.com/Automattic/build-with-wordpress/pull/100) and requires an evidence-backed documentation update; bootstrap requires `README.md`, `docs/README.md`, at least three topic pages, and a README link to the docs index.

docs/figma-studio-runner.md

@@ -44,6 +44,29 @@ Implemented now:
 - `blocks-engine/php-transformer/site-artifact/v1` retained as debug/diagnostic context.
 - A Figma UI client that posts the source payload to local Studio.
 
+## Source Payload Contract
+
+`toFigmaSourcePayload()` produces `wordpress-studio/figma-source/v1`. Studio receives it as the `source` property of a JSON request, alongside the Figma document name as `siteName`.
+
+The payload preserves the source needed for a Studio-side transform:
+
+- `source` identifies Figma, includes file and page metadata, and records the export timestamp.
+- `intent` records whether the user selected nodes or the current page, including the page and selected root node IDs.
+- `scenegraph` includes the normalized current page and selected nodes rather than only generated HTML.
+- `assets` carries the normalized exported assets.
+- `transform` requests the `static-site-importer/figma` route with a WordPress target, preserved source scenegraph, asset import, selection scope, page ID, and selected node IDs.
+- `debug` carries a per-request handoff ID, generated artifact context, diagnostics, and metadata.
+
+The debug summary is deterministic from the selected source and generated artifact. It reports the selection scope and page, selected-node count, recursive node count, asset count, and diagnostic, warning, and error counts. When no nodes are selected, node counting falls back to the current page. `generate-artifact.test.mjs` fixes this shape with a selected-node fixture and verifies the route, preservation options, handoff ID, generated artifact, and summary counts.
+
+## Handoff And Diagnostics
+
+The UI posts to `http://127.0.0.1:48732/figma-to-wordpress/import` with `Content-Type: application/json`. The Studio button remains disabled until normalized selection data is available and while a request is active.
+
+Each request receives a `figma-...` handoff ID. On success, Studio may return `requestId`, `siteName`, `siteUrl`, and `importSummary`; the UI displays the accepted site and logs those values with the handoff ID, payload schema, selection identity, source summary, and generated artifact file/entrypoint summary.
+
+A non-2xx response or a response without `success: true` is a failed handoff. The visible error uses Studio's response message when available, appends its request ID for correlation, and otherwise includes the HTTP status. Network and response failures are logged with the same handoff ID and source summary, so Studio and Figma logs can be correlated without treating the debug artifact as the primary import contract.
+
 Not implemented yet:
 
 - Post-import block validation and visual parity checks.

tests/docs-agent-workflows.test.mjs

@@ -50,7 +50,7 @@ const workflows = [
     revision: docsAgentRevision,
     writablePaths: "README.md,docs/**,plugins/**/README.md",
     driftCheck: "git diff --exit-code -- . ':(top,exclude)README.md' ':(top,glob,exclude)docs/**' ':(top,glob,exclude)plugins/**/README.md'",
-    sourceDelta: /"id": "figma-studio-handoff-diagnostics"[\s\S]*"https:\/\/github\.com\/Automattic\/build-with-wordpress\/pull\/100"[\s\S]*"requires_documentation_change": true/,
+    sourceDelta: /"id": "figma-studio-handoff-diagnostics"[\s\S]*"https:\/\/github\.com\/Automattic\/build-with-wordpress\/pull\/100"[\s\S]*"requires_documentation_change": false/,
     bootstrapContract: true,
   },
   {