Diagnosis-to-Tool Mapping
Preflight uses a diagnosis-to-tool contract so every diagnostic can drive deterministic remediation across app UI, MCP/ACP, and CLI.
Mapping Fields
Section titled “Mapping Fields”Each diagnosis may include:
manualGuidance: operator guidance and expected “right” statetoolRecommendation: recommended tool/actionfixAction: direct surgical action when availableconverterRecipe: conversion recipe when transcode/resize is preferred
Texture Matrix
Section titled “Texture Matrix”| Diagnosis ID | Severity | Preferred Tool Path | Fix Type |
|---|---|---|---|
texture.missing_file | error | preflight_diagnose(action=texture) then preflight_fix(action=texture_convert) or fix:setTexture | Tool + Manual |
texture.unreadable_or_corrupt | error | preflight_fix(action=texture_convert) | Tool |
texture.unsupported_container_or_encoding_for_target | warning | preflight_fix(action=texture_convert) | Tool |
texture.exceeds_target_budget | warning | preflight_fix(action=texture_convert, max_dimension=...) | Tool |
texture.colorspace_mismatch | warning | preflight_fix(action=texture_convert, gamut_out=sRGB) | Tool |
texture.no_mips_for_large_textures | advisory/warning | preflight_fix(action=texture_convert, generate_mipmaps=true) | Tool |
texture.npot_or_alignment_risk | advisory | preflight_fix(action=texture_convert) | Tool/Manual |
Workflow-to-Backend Defaults
Section titled “Workflow-to-Backend Defaults”| Workflow Profile | Validation Scope | Recommended Backend |
|---|---|---|
OpenUSD | Core-only | openSource or automatic |
RealityKit | Core + RealityKit extension | automatic (optionally appleTextureConverter for KTX2 flows) |
appleTextureConverter remains optional and capability-gated. Core OpenUSD validation/remediation remains available without it.
Surface Parity
Section titled “Surface Parity”The same diagnosis IDs and recommendations are exposed in:
- App diagnostics UI
- MCP/ACP tool responses
- CLI JSON output (
preflighttool validate,preflighttool texture analyze)