>>> [!note] Migrated issue <!-- Drupal.org comment --> <!-- Migrated from issue #3588748. --> Reported by: [ajv009](https://www.drupal.org/user/3653917) >>> <h3 id="summary-problem-motivation">Problem/Motivation</h3> <p>Sprint 5 &mdash; Drupal Canvas Runtime Gotchas. This is a roll-up meta-issue tracking platform-level Acquia/Drupal Canvas behaviors that recur across every migration session. Each child gotcha has been independently encountered in 2+ recorded sessions. They cost debugging cycles on each re-encounter and are exactly the kind of hard-won technical fact that gets lost during context compaction (per Sprint 1 issue 1-07). Capturing them in sprint form ensures they get written into <code>component-builder.md</code>, the <code>component-authoring</code> skill, <code>media-handler.md</code>, <code>visual-verifier.md</code>, and <code>SKILL.md</code> before the next migration run.</p> <p>None of the five gotchas in this sprint require platform code changes. All five are documentation/skill-text-only changes. The vehicle for compaction survival across all of them is the <code>docs/migration/gotchas.md</code> artifact proposed in Sprint 1 issue 1-07; every child issue adds an entry to that file in addition to writing into the canonical agent/skill files.</p> <h4 id="summary-steps-reproduce">Steps to reproduce</h4> <p>See each child issue for the specific repro pattern.</p> <h3 id="summary-proposed-resolution">Proposed resolution</h3> <p>Land the five child issues in suggested order. Order rationale:</p> <ul> <li><strong>5-01 &rarr; 5-02 &rarr; 5-03</strong> (Mercury theme override, Canvas component import, FormattedText/JsonApiClient/getNodePath): bundle these &mdash; they all touch <code>.claude/agents/component-builder.md</code> and the <code>component-authoring</code> skill. Doing them consecutively lets the implementer open those files once and add all three rule blocks in a single pass.</li> <li><strong>5-04</strong> (CDN stale assets): independent, touches <code>SKILL.md</code> and <code>visual-verifier.md</code>. Can be done in parallel with the component-builder issues.</li> <li><strong>5-05</strong> (<code>drupal_internal__mid</code> not in JSON:API): independent, touches <code>media-handler.md</code> and any media upload script. Can be done in parallel.</li> </ul> <p>None of the five have ordering dependencies between them. Sprint priority is Major &mdash; the highest severity in this sprint is P1.</p> <h3 id="summary-remaining-tasks">Remaining tasks</h3> <ul> <li>5-01 &mdash; Mercury theme overrides Tailwind <code>md:</code> utilities site-wide (P1, Bug Report)</li> <li>5-02 &mdash; Canvas component cannot import another Canvas component (P1, Bug Report)</li> <li>5-03 &mdash; FormattedText / JsonApiClient / getNodePath broken in Canvas client-side runtime (P1, Bug Report)</li> <li>5-04 &mdash; CDN serves stale assets for hours after upload (P2, Bug Report)</li> <li>5-05 &mdash; <code>drupal_internal__mid</code> not in JSON:API by default &mdash; <code>target_id</code> lookup brittle (P2, Bug Report)</li> </ul> <h3 id="summary-ui-changes">User interface changes</h3> <p>None at the sprint level &mdash; see child issues.</p> <h3 id="summary-api-changes">API changes</h3> <p>None at the sprint level &mdash; see child issues.</p> <h3 id="summary-data-model-changes">Data model changes</h3> <p>No new artifacts. All five child issues append entries to the <code>docs/migration/gotchas.md</code> artifact proposed in Sprint 1 issue 1-07.</p> <h3 id="summary-definition-of-done">Definition of done</h3> <ul> <li>All five gotchas are documented verbatim in the canonical skill/agent files (not just in the sprint markdowns).</li> <li><code>component-builder.md</code> includes a "Canvas Runtime Hard Rules" block covering 5-02 and 5-03.</li> <li><code>component-builder.md</code> or the <code>component-authoring</code> skill includes a "Mercury Theme Awareness" block covering 5-01.</li> <li><code>SKILL.md</code> and <code>visual-verifier.md</code> both include a "Verification Discipline" block covering 5-04.</li> <li><code>media-handler.md</code> includes a <code>drupal_internal__mid</code> workaround note covering 5-05.</li> <li><code>docs/migration/gotchas.md</code> has a template entry for each gotcha (for compaction survival per Sprint 1 1-07).</li> <li>No gotcha in this sprint requires a new coding artifact &mdash; all five are documentation/skill-text changes.</li> </ul> <h3 id="summary-internal-references">Internal references</h3> <ul> <li>Sprint folder: <code>RESEARCH-2026-04-28/99-final/ISSUES/Sprint-5-Drupal-Canvas-Gotchas/</code></li> <li>Sprint README: <code>Sprint-5-Drupal-Canvas-Gotchas/README.md</code></li> <li>Top-level issues README: <code>RESEARCH-2026-04-28/99-final/ISSUES/README.md</code></li> <li>Gotcha catalog: <code>RESEARCH-2026-04-28/07-cross-cutting/acquia-cms-gotchas.md</code> &sect;&sect; G3, G4, G5, G7, G11, G13</li> <li>Recommendation source: <code>RESEARCH-2026-04-28/99-final/migrate-site-skill-recommendations.md</code></li> <li>Consolidated issues: <code>RESEARCH-2026-04-28/99-final/consolidated-issues.md</code> &sect;&sect; P1-5, P1-7, P1-8, P2-8, P2-10</li> </ul> <h3 id="summary-child-issues">Child issues</h3> <p>Linked child issues for this sprint (auto-rendered with status badges):</p> <ul> <li><span class="drupalorg-gitlab-issue-link project-issue-status-info project-issue-status-5"><a href="https://www.drupal.org/project/canvas_ai_migrations/issues/3588785" title="Status: Closed (won't fix)">#3588785: [Sprint 5] Mercury theme silently overrides Tailwind responsive utilities</a></span></li> <li><span class="drupalorg-gitlab-issue-link project-issue-status-info project-issue-status-7"><a href="https://www.drupal.org/project/canvas_ai_migrations/issues/3588786" title="Status: Closed (fixed)">#3588786: [Sprint 5] Canvas component cannot import another Canvas component</a></span></li> <li><span class="drupalorg-gitlab-issue-link project-issue-status-info project-issue-status-7"><a href="https://www.drupal.org/project/canvas_ai_migrations/issues/3588787" title="Status: Closed (fixed)">#3588787: [Sprint 5] FormattedText, JsonApiClient, getNodePath broken in Canvas client runtime</a></span></li> <li><span class="drupalorg-gitlab-issue-link project-issue-status-info project-issue-status-7"><a href="https://www.drupal.org/project/canvas_ai_migrations/issues/3588788" title="Status: Closed (fixed)">#3588788: [Sprint 5] CDN serves stale assets for hours after upload</a></span></li> <li><span class="drupalorg-gitlab-issue-link project-issue-status-info project-issue-status-7"><a href="https://www.drupal.org/project/canvas_ai_migrations/issues/3588789" title="Status: Closed (fixed)">#3588789: [Sprint 5] drupal_internal__mid not in JSON:API &mdash; target_id lookup brittle</a></span></li> </ul>