[wass08]

What does this PR do?

• author_scene takes payloadFile: the fileId of a JSON project file (from upload_project_file) holding the payload. It's for a payload too large for one call, like a whole house with its modules. The server reads it through a new host hook, ProjectFileReader (readFile on createPascalMcpServer). After that it is handled exactly like an inline payload: it is stored, so replace: true writes it again.
• Refusals:
  • a file that is not JSON or does not match the schema answers payload_invalid with the issue paths;
  • payload together with payloadFile answers payload_twice;
  • edits with either one answer edits_with_payload;
  • a server without a reader answers files_unavailable.
• Paint's texture url description now says it can be artifact://<sha256> of an image stored with the project.
• The pascal-3d skill and the tool description tell agents to use payloadFile for large payloads.

How to test

1. cd packages/mcp && bun test src/tools/author-scene-sources.test.ts: the new case writes a house from a file, writes it again with replace: true, and checks the four refusals.
2. cd packages/core && bun test src/agent-tools src/contracts: the contract purity and notation tests pass with the new input.
3. bun run skills:validate.

Screenshots / screen recording

N/A — non-visual change

Checklist

• I've tested this locally with bun dev
• My code follows the existing code style (run bun check to verify)
• I've updated relevant documentation (if applicable)
• This PR targets the main branch

🤖 Generated with Claude Code

---

Note

Medium Risk
Extends the destructive author_scene conversion path with hosted file reads, though size limits and schema checks mirror the inline payload path.

Overview
author_scene can take payloadFile (a fileId from upload_project_file) instead of an inline payload, so large conversion JSON (e.g. a whole house with embedded modules) does not have to fit in one MCP call. The hosted server reads bytes through a new optional readFile / ProjectFileReader hook on createPascalMcpServer; after load, behavior matches an inline payload (including storage and replace: true rewrites).

New guardrails: payload + payloadFile → payload_twice; edits with either → edits_with_payload; no reader → files_unavailable; bad/missing file → payload_invalid or file_request_failed. Reads are capped at 32 MiB. Adapter/file payload validation is shared via a parsedPayload helper.

Docs only elsewhere: paint texture url may use artifact://<sha256>; pascal-3d skill/workflow text describes the upload + payloadFile path. MCP tests cover happy path, replace: true, and refusals.

^{Reviewed by Cursor Bugbot for commit 6e51b85. Bugbot is set up for automated code reviews on this repo. Configure here.}