>>> [!note] Migrated issue <!-- Drupal.org comment --> <!-- Migrated from issue #3588793. --> Reported by: [ajv009](https://www.drupal.org/user/3653917) >>> <h3 id="summary-problem-motivation">Problem/Motivation</h3> <p>The migrate-site skill has no phase for setting up Canvas content templates for dynamic content types (events, blog posts, news items). Without this, a "migrated" events section requires a script to create a Canvas page entity for every new event &mdash; making the CMS not self-service. Content editors cannot add a new event from the Drupal admin UI and have it render correctly without re-running the migration script.</p> <p>The skill was built around the static-page migration pattern: all content is treated as Canvas page entities. Acquia Canvas actually supports two rendering modes: (1) Canvas page entities &mdash; explicit pages the migration creates &mdash; and (2) Canvas content templates &mdash; display modes attached to Drupal node bundles (<code>node.&lt;type&gt;.full</code>) that automatically render any node of a given type using a Canvas component with entity-field prop bindings. The skill only uses mode (1). When a site has dynamic content, mode (2) is the correct architecture because it is CMS-native and does not require scripting for new content creation.</p> <p>The breakthrough was discovered in a recorded session not through the agent's own documentation research, but through the user consulting an external contact &mdash; a clear signal that the skill's Acquia platform knowledge is incomplete on this topic. The post-mortem explicitly flags this as an architecture gap the skill must close. The user's first reaction to seeing an unstyled event page was not "fix the workaround script" but "why does this require a script at all?" A migrated CMS must be fully self-service for content editors.</p> <p>The Canvas content template approach requires a display mode (<code>node.&lt;type&gt;.full</code>) configured in Drupal, a Canvas template registered for that display mode, component props bound to entity-field sources (not hardcoded values), pathauto or a path-alias strategy so nodes get clean URLs, and verification that creating a new piece of content via the admin UI renders correctly. None of this is in the current skill.</p> <h4 id="summary-steps-reproduce">Steps to reproduce</h4> <ol> <li>Run the migrate-site skill against a source site that has dynamic content &mdash; for example an Events section with multiple similar events, or a Blog with multiple similar posts.</li> <li>Observe that the skill creates one Canvas page entity per event, with no Phase 4.5 for content templates.</li> <li>After migration, log into the Drupal admin UI and create a new event node.</li> <li>Navigate to the new event's URL &mdash; it renders without Canvas styles because no <code>node.event.full</code> template is registered.</li> <li>Observe that adding new content requires running a per-item script rather than being a CMS-native action.</li> </ol> <h3 id="summary-proposed-resolution">Proposed resolution</h3> <p>This is a 4-step implementation.</p> <p><strong>Step 1 &mdash; Phase 1 content-type detection.</strong> In SKILL.md Phase 1, add a content-type discovery step to the site-analyzer instructions:</p> <pre>CONTENT TYPE DETECTION (Phase 1, add to site-analyzer instructions): When analyzing the source site, identify any dynamic content types: - Blog/news sections with multiple similar articles - Events sections with multiple similar events - Team member directories with multiple similar profiles - Product/portfolio listings with multiple similar items For each detected content type: - Record in plan.md: "content_type: &lt;type&gt;, template_needed: true" - Note the fields visible on the source (title, date, image, body, categories, etc.)</pre><p><strong>Step 2 &mdash; Phase 4.5 content templates.</strong> In SKILL.md between Phase 4 (upload) and Phase 5 (media), add:</p> <pre>PHASE 4.5 &mdash; Canvas Content Templates (conditional: skip if plan.md has no content_type entries) For each content_type in plan.md where template_needed=true: 1. Check if a Canvas content template exists for this type: GET /api/canvas_page_template?filter[bundle]=&lt;type&gt; 2. If not found: dispatch canvas-content-template-agent for this type 3. Verify self-service: create a test node of this type in the Drupal admin UI. Navigate to the test node URL. Confirm it renders with the Canvas template styles. DO NOT proceed to Phase 5 if a content type's template is missing or broken. 4. Delete any old per-item Canvas pages created as temporary workarounds.</pre><p><strong>Step 3 &mdash; Create <code>.claude/agents/canvas-content-template-agent.md</code>.</strong> The agent should:</p> <ul> <li>Accept: content type name (e.g. <code>event</code>), component name to use as template (e.g. <code>event_detail</code>).</li> <li>Create the Canvas content template for the <code>node.&lt;type&gt;.full</code> display mode.</li> <li>Bind all component props to entity-field sources (not hardcoded values): title &rarr; <code>entity.title</code>, body &rarr; <code>entity.body.processed</code>, date &rarr; <code>entity.start_date</code>, image &rarr; <code>entity.featured_image</code>, etc.</li> <li>Verify by creating a test node in the admin UI and navigating to its URL.</li> <li>Write <code>workflow/content-template-&lt;type&gt;-complete.json</code> when done.</li> </ul> <p><strong>Transport choice (browser session vs. OAuth API):</strong> An empirical scope probe against a live Acquia Source instance on 2026-05-01 found that <code>page_template:administer</code> endpoints still return 404 &mdash; no <code>/api/page_template/*</code>, <code>/api/canvas_page_template/*</code>, or <code>/api/entity_view_display</code> path is available. Implement the agent using the browser-session path (admin cookie) until <code>scripts/verify-scopes.mjs</code> from Sprint 1 1-08 reports that the endpoints have landed. Once the scope probe detects the endpoints, the agent can be updated to use the OAuth API path.</p> <p><strong>Step 4 &mdash; Append to <code>docs/migration/gotchas.md</code></strong>: "Dynamic content types (events, blog, news) need Canvas content templates (<code>node.&lt;type&gt;.full</code>) for self-service CMS. Without this, new content requires manual scripts. See Phase 4.5 in SKILL.md."</p> <p>Note on cleanup: the recommended step is to delete (not archive) the old per-item Canvas pages created as temporary workarounds. Archiving via path-alias change creates stale <code>path_alias</code> entries and a permanent 301-redirect trap.</p> <h3 id="summary-remaining-tasks">Remaining tasks</h3> <ul> <li>Add the Phase 1 content-type detection step to SKILL.md.</li> <li>Add the Phase 4.5 Canvas content templates section to SKILL.md.</li> <li>Create <code>.claude/agents/canvas-content-template-agent.md</code> with the <code>node.&lt;type&gt;.full</code> workflow and entity-field prop bindings.</li> <li>Implement using the browser-session path (admin cookie) for template creation, since <code>page_template:administer</code> endpoints are not yet available on the live instance.</li> <li>Append the Canvas content template gotcha entry to <code>docs/migration/gotchas.md</code>.</li> <li>Coordinate implementation with Sprint 8 NEW-2 (canvas-content-templates-phase) &mdash; they share the same agent and Phase 4.5 surface.</li> <li>Verify on a content-type-bearing source site: creating a new node of a flagged type via the Drupal admin UI renders correctly without running any script.</li> </ul> <h3 id="summary-ui-changes">User interface changes</h3> <p>None at the skill level. Indirect: after Phase 4.5, the Drupal admin UI displays correctly-styled rendered nodes for flagged content types, where previously they rendered without styles.</p> <h3 id="summary-api-changes">API changes</h3> <p>None to the skill's external API. The new agent consumes the Canvas template-creation endpoint via browser session today, and via <code>page_template:administer</code>-scoped OAuth once the API surface is available on the target instance.</p> <h3 id="summary-data-model-changes">Data model changes</h3> <p>New artefact: <code>workflow/content-template-&lt;type&gt;-complete.json</code> per content type processed. New agent file: <code>.claude/agents/canvas-content-template-agent.md</code>. New Drupal-side configuration created during Phase 4.5: <code>node.&lt;type&gt;.full</code> display modes and Canvas template registrations for each flagged content type.</p> <h3 id="summary-internal-references">Internal references</h3> <ul> <li>Source markdown: <code>RESEARCH-2026-04-28/99-final/ISSUES/Sprint-6-Skill-Architecture/03-P2-6-canvas-content-templates-not-used.md</code> (id: P2-6)</li> <li>Consolidated issue: <code>RESEARCH-2026-04-28/99-final/consolidated-issues.md</code> &sect; P2-6</li> <li>Primary source &mdash; discovery and post-mortem: <code>RESEARCH-2026-04-28/03-efi-ed-source/Q4-records-8651-to-11536/post-mortem-learnings.md</code></li> <li>Architecture gap evidence: <code>RESEARCH-2026-04-28/03-efi-ed-source/Q4-records-8651-to-11536/issues-found.md</code> ("Architecture Gap: No Per-Node Canvas Display Modes")</li> <li>Recommended agent description: <code>RESEARCH-2026-04-28/99-final/migrate-site-skill-recommendations.md</code> &sect; New Skills/Agents / canvas-content-template-agent</li> <li>Related gotcha (delete vs archive): <code>RESEARCH-2026-04-28/07-cross-cutting/acquia-cms-gotchas.md</code> &sect; G6</li> <li>Scope reference: <code>RESEARCH-2026-04-28/99-final/SCOPE-REFERENCE-2026-05-01.md</code></li> <li>Empirical scope probe: <code>RESEARCH-2026-04-28/99-final/SCOPE-PROBE-FINDINGS-2026-05-01.md</code> &sect; "Affected issues &mdash; REWORK NEEDED" (P2-6 row)</li> <li>Skill evolution timeline: <code>RESEARCH-2026-04-28/07-cross-cutting/migrate-site-skill-evolution.md</code></li> <li>Bug-fix counterpart: <code>RESEARCH-2026-04-28/99-final/ISSUES/Sprint-8-Patterns-To-Encode/02-NEW-2-canvas-content-templates-phase.md</code></li> </ul> <h3 id="summary-open-questions">Open questions</h3> <ul> <li>What is the actual Acquia Source API endpoint for checking existing Canvas content templates? <code>node.&lt;type&gt;.full</code> is the display-mode pattern but the GET endpoint for checking existence has not been confirmed. Probe before writing the agent's "check for existing template" step.</li> <li>Does pathauto need to be configured for the content type to get clean URLs, or does Acquia Source handle this automatically for Canvas content templates?</li> <li>Confirm "delete (not archive)" cleanup of old per-item Canvas pages &mdash; the rationale is that path-alias-based archiving creates stale <code>path_alias</code> entries (gotcha G6).</li> <li>Is there a distinction between "Canvas page template" (display mode config, the scope name <code>page_template:administer</code>) and "Canvas content template" (what this issue describes &mdash; <code>node.&lt;type&gt;.full</code>)? The scope name may refer to a different entity. Verify when the OAuth path becomes available.</li> <li>Once Sprint 1 1-08 (<code>scripts/verify-scopes.mjs</code>) reports that <code>page_template:administer</code> endpoints have landed, switch the agent's transport from browser-session to OAuth API.</li> </ul>