ima-claude 2.16.0 → 2.20.0

package/plugins/ima-claude/skills/agentic-workflows/references/standards/outline-format.md

@@ -0,0 +1,110 @@
+# Outline Format
+
+Structural rules for outlines produced by the outline phase. Injected by the consumer when the recipe declares this file.
+
+---
+
+## What an Outline Is
+
+An outline is a structural proposal in bullet points. It is not a draft. It contains no prose paragraphs. It communicates architecture — what sections exist, in what order, what each section argues, and where visual elements land.
+
+The outline is the contract between the outline phase and the draft phase. The draft phase follows the outline unless a deviation is explicitly documented.
+
+---
+
+## Governing Principle
+
+Structure around reader needs, not source material architecture.
+
+The source material (transcript, study, press release) has its own sequence driven by how it was produced. That sequence is rarely the best sequence for a reader encountering the material for the first time. The outline phase's job is to find the reader's sequence.
+
+Ask: what does the reader need to know first to understand what comes next? Start there.
+
+---
+
+## Required Elements
+
+Every outline must contain these elements in this order:
+
+### Title
+A proposed headline. Clear, specific, benefit-oriented. Not a topic label — a claim or a promise. The draft phase may refine it, but the outline provides a working title.
+
+### Intro
+Three components:
+- **Hook** — the entry point that earns the reader's attention. One sentence. Can be a bold claim, a striking finding, a tension, or a question the reader is already asking.
+- **Frame** — what this piece is about and why it matters now. One to two sentences.
+- **Setup** — what the reader will get from reading. One sentence.
+
+### Body Sections (3–5)
+For each section:
+- **Section title** — communicates the core argument, not just the topic
+- **Core argument** — one sentence stating what this section claims
+- **Key points** — bullet list of the specific evidence, data, or ideas that support the core argument
+- **Asset placements** — where images, video embeds, or CTAs land within this section (if applicable)
+- **Quote placements** — where blockquotes land inline, with the speaker and a fragment of the quote
+
+Sections must not overlap in argument. If two sections are making the same point, merge them.
+
+### Related Reading
+Three to five links or resource types. Can be TBD if assets are not yet confirmed. Include a brief description of each.
+
+### Editorial Watch Items
+Things the draft phase should pay special attention to:
+- Naming sensitivities (speakers, institutions, studies)
+- Attribution requirements (quotes that must be near-verbatim)
+- Gaps that need `[bracket]` treatment
+- Recipe-specific requirements the draft phase must apply
+- Anything from the gather phase gaps section that was not resolved
+
+### Word Target
+Carry forward from the gather phase. If the outline reveals the scope is larger or smaller than estimated, adjust and explain the change in one sentence.
+
+---
+
+## Section Scope
+
+Each body section argues exactly one thing. The section title states that argument. Every key point in the section supports that argument. If a section has key points that pull in two directions, split it into two sections.
+
+Aim for 3–5 sections. Fewer than 3 means the content lacks depth. More than 5 means the scope is too broad or the arguments are not being consolidated.
+
+---
+
+## Visual Element Placement
+
+Apply these rules for every asset:
+
+- **No adjacent visual elements** — never place two images, embeds, or CTAs in sequence without prose between them
+- **Images break up content within sections** — place images mid-section when a section runs long, not at the top as a header image (unless the recipe specifies a hero)
+- **CTAs go between sections** — interstitial CTAs belong in the transition between sections, not embedded within a section's prose
+- **Video embeds** — typically at the top of the piece as the hero element; note this in the intro element, not a body section
+
+---
+
+## Quote Placement
+
+Quotes belong inline where they would naturally land if the reader encountered them in prose — not in a separate "Quotes" section.
+
+For each quote, mark its placement in the relevant section's key points:
+
+```
+- Quote: [Speaker last name]: "[fragment of quote]" — after point about [topic]
+```
+
+Blockquote format in the draft:
+```
+> [Speaker Name]: "exact or near-verbatim quote"
+```
+
+Select quotes that advance the section's core argument. Do not include quotes for variety or because they seem interesting. Every quote should be the best available evidence for the point it follows.
+
+---
+
+## What Does NOT Belong in an Outline
+
+- Prose paragraphs — outlines use bullets, not paragraphs
+- Every detail from the source material — only what advances the reader's understanding
+- Meta descriptions — these belong in the draft
+- A separate "Quotes" section — quotes go inline
+- The source material's own section structure — unless it happens to be the best reader sequence
+- Stacked visual elements — no two adjacent assets
+- Speculative sections — if you are not confident a section belongs, it does not belong

package/plugins/ima-claude/skills/agentic-workflows/references/templates/avada-construction-guide.md

@@ -0,0 +1,263 @@
+# Avada/Fusion Builder Construction Guide
+
+General reference for building IMA blog posts and editorial pages in the WordPress backend using Fusion Builder shortcode markup. This document covers building blocks, syntax patterns, and placement principles. It is content-type agnostic. Content-type-specific templates (webinar summaries, research posts, etc.) live in their respective project instruction files and reference this guide for construction mechanics.
+
+---
+
+## Core Container Structure
+
+Every post is wrapped in a single container → row → column stack:
+
+```
+[fusion_builder_container]
+  [fusion_builder_row]
+    [fusion_builder_column type="1_1"]
+      <!-- all content blocks go here -->
+    [/fusion_builder_column]
+  [/fusion_builder_row]
+[/fusion_builder_container]
+```
+
+This outer wrapper never changes. Copy verbatim from any existing post.
+
+---
+
+## Content Block Types
+
+### Text Block
+The workhorse. Used for body paragraphs, bullet lists, blockquotes, and inline links.
+
+```
+[fusion_text]
+<p>Paragraph content here with <strong>strategic bold</strong> for emphasis.</p>
+
+<blockquote>"Speaker quote here." — <strong>Name</strong></blockquote>
+
+<ul>
+  <li><strong>Label:</strong> Description text</li>
+  <li><strong>Label:</strong> Description text</li>
+</ul>
+[/fusion_text]
+```
+
+**Usage notes:**
+- One `fusion_text` block per logical content section. Don't cram an entire post into one block.
+- Break into new blocks at natural visual anchor points: before/after images, at section transitions.
+- `<strong>` for emphasis within paragraphs. Don't bold entire sentences.
+- `<blockquote>` for speaker/researcher quotes with em-dash attribution.
+
+### Title Block
+Used for section headers and styled intro text.
+
+```
+[fusion_title title_type="text" style_type="none" title_tag="h2"]
+<strong>N.</strong> Section Title
+[/fusion_title]
+```
+
+For styled intro blocks (non-heading text that needs title-level formatting):
+
+```
+[fusion_title title_type="text" style_type="none" size="div"]
+Intro text styled as a title block
+[/fusion_title]
+```
+
+**Usage notes:**
+- Numbered sections use `<h2><strong>N.</strong> Section Title</h2>` inside a `fusion_text` block (not `fusion_title`) for consistency with existing posts.
+- `fusion_title` is primarily for standalone headers and styled intro text.
+
+### Image Block
+Used for slide images, diagrams, headshots, promo graphics, and resource covers.
+
+```
+[fusion_imageframe
+  image_id="ATTACHMENT_ID|full"
+  style_type="none"
+  alt="Descriptive alt text"
+  align="center"
+  lightbox="yes"
+  margin_top="20px"
+  margin_bottom="20px"]
+  https://imahealth.org/wp-content/uploads/path/to/image.jpg
+[/fusion_imageframe]
+```
+
+**Lightbox rules:**
+- `lightbox="yes"` for diagrams, charts, slides, data tables — anything the reader might want to zoom into
+- `lightbox="no"` for promo images and linked graphics. Add `link` attribute when the image should click through to a page.
+
+**Sizing:**
+- Headshots: `max_width="200"` in a `1_4` column
+- Slide images: full-width within the content column
+- Promo images: full-width, linked, no lightbox
+
+**Border treatment for covers, figures, and charts:**
+- Study covers, guide covers, book covers, figures, charts, and graphs: `bordersize="3" bordercolor="#00066f" borderradius="10"`
+- This applies to any image that represents a document or data visualization. It does not apply to promo images, headshots, or hero images.
+
+**External links:**
+- All links to external sites (anything outside imahealth.org) must include `linktarget="_blank"` on imageframes and `target="_blank"` on `<a>` tags within fusion_text blocks.
+
+**Video embed spacing:**
+- The first `fusion_text` block after a video embed should include `margin_top="30px"` for breathing room between the video player and the body text.
+
+### Button Block
+Used for CTAs (forums, donation, external links).
+
+```
+[fusion_button
+  link="https://imahealth.org/forums/"
+  icon="fa-comments fas"
+  alignment="center"]
+  Continue the conversation at the Forums
+[/fusion_button]
+```
+
+### Separator Block
+Used for visual breaks between major sections.
+
+```
+[fusion_separator style_type="single solid" sep_color="#e0e0e0" border_size="2"][/fusion_separator]
+```
+
+### Code Block (for embeds)
+Used for video embeds and any content requiring base64-encoded shortcodes.
+
+```
+[fusion_code]BASE64_ENCODED_SHORTCODE_HERE[/fusion_code]
+```
+
+**Common use:** Cloudflare stream video embeds. Encode the stream shortcode as base64 and place inside `fusion_code`.
+
+---
+
+## Layout Patterns
+
+### Single Column (default)
+Most content uses the outer 1_1 column. No inner rows needed.
+
+### Two-Column Split (e.g., resource covers, side-by-side elements)
+Nested inner row with two half-width columns:
+
+```
+[fusion_builder_row_inner]
+  [fusion_builder_column_inner type="1_2"]
+    [fusion_imageframe ...]image_url[/fusion_imageframe]
+    [fusion_text]<p style="text-align: center;"><strong>Title</strong><br>One-line description</p>[/fusion_text]
+  [/fusion_builder_column_inner]
+  [fusion_builder_column_inner type="1_2"]
+    [fusion_imageframe ...]image_url[/fusion_imageframe]
+    [fusion_text]<p style="text-align: center;"><strong>Title</strong><br>One-line description</p>[/fusion_text]
+  [/fusion_builder_column_inner]
+[/fusion_builder_row_inner]
+```
+
+**Use when:** Featuring two related resources side by side (PDF covers, guide pairs, before/after comparisons).
+
+### Headshot + Bio (e.g., expert profiles, author intros)
+Quarter-width image column + three-quarter text column:
+
+```
+[fusion_builder_row_inner]
+  [fusion_builder_column_inner type="1_4"]
+    [fusion_imageframe image_id="ID|full" max_width="200" style_type="none" align="center"]
+      headshot_url
+    [/fusion_imageframe]
+  [/fusion_builder_column_inner]
+  [fusion_builder_column_inner type="3_4"]
+    [fusion_text]
+    <p><strong>Name</strong><br><em>Title, Credentials</em></p>
+    <p>Bio paragraph.</p>
+    [/fusion_text]
+  [/fusion_builder_column_inner]
+[/fusion_builder_row_inner]
+```
+
+**Credential structure:** Keep parallel across multiple experts. If some lack titles/achievements, simplify everyone to the same level of detail (e.g., institution affiliation only).
+
+---
+
+## Interstitials (Global Blocks)
+
+Reusable CTA blocks stored as Fusion Builder globals. Each global block requires the full `row_inner` → `column_inner` → content structure inline. The `fusion_global` attribute syncs with WordPress, but **the inline content is what renders**. Never swap a global ID without swapping the full content block.
+
+**Available blocks and their full markup live in the CTA Block Catalog** (`cta-block-catalog.md`). That file is the single source of truth for all globals. Copy the markup verbatim from the catalog when placing CTAs in post markup.
+
+### Placement Principles
+
+- One interstitial every 1–2 sections
+- Never back to back
+- Place at natural pause points, not mid-argument
+- Engagement CTAs (Journal, Research Hub, Substack, Conference) go earlier in the post as informational breaks
+- Donation CTAs are the ask: they go late, typically before the emotional close or final section
+- Match the donation CTA to the content topic (webinar → Webinar Donation, cancer → Cancer Research Donation, research study → Research Donation, journal → Journal Donation). The CTA catalog has usage notes for each block.
+
+---
+
+## Image Placement Decision Framework
+
+1. **Does the section introduce a visual concept (framework, diagram, cycle)?** → Place the corresponding image immediately after the text introduces it, before the next paragraph continues.
+
+2. **Are new resources being released?** → Use the two-column PDF cover split in the section that introduces them.
+
+3. **Is there a contextually relevant promo?** → Place after the final body section. Must be earned by the content (e.g., speakers mentioned in the post are at the conference).
+
+4. **Are there 2+ sections in a row without a visual break?** → Insert an interstitial between them.
+
+5. **Does the post feel visually dense in the middle?** → Rearrange interstitials to create breathing room.
+
+---
+
+## TODO Placeholders
+
+Use these standardized placeholders in templates. Replace before publishing.
+
+| Placeholder Pattern | What to Replace With |
+|---------------------|---------------------|
+| `VIDEO_EMBED_BASE64_HERE` | Base64-encoded fusion_code shortcode |
+| `*_HEADSHOT_ID` | WordPress media library attachment ID |
+| `PATH_TO_*.jpg` | Full URL path to image in media library |
+| `*_COVER_ID` | Media library ID for guide/resource cover images |
+| Any `image_id="*_ID\|full"` | Actual WordPress attachment ID |
+
+---
+
+## Related Reading Block
+
+Standard footer block before the forums button. Curated links relevant to the post content.
+
+```
+[fusion_text]
+<h2>Related Reading</h2>
+<ul>
+  <li><strong>Label:</strong> <a href="URL">Title</a></li>
+  <li><strong>Label:</strong> <a href="URL">Title</a></li>
+</ul>
+[/fusion_text]
+```
+
+**Format:** Bold type label + linked title. No descriptions. Labels indicate content type (Guide, Monograph, Webinar, Hub, etc.).
+
+---
+
+## Forums Button (standard footer)
+
+Appears at the bottom of every post. Copy verbatim.
+
+```
+[fusion_button link="/forums/" icon="fa-comments fas" alignment="center"]
+  Continue the conversation at the Forums
+[/fusion_button]
+```
+
+---
+
+## Transition to LiveCanvas / Bootstrap
+
+When the environment changes, the principles carry over:
+
+- **Content structure** (intro → experts → body sections → related reading) doesn't change
+- **Image placement logic** doesn't change
+- **Interstitial placement logic** doesn't change
+- **What changes:** The markup language. Fusion Builder shortcodes become Bootstrap utility classes and HTML. This document will be updated with new markup patterns, but the structural logic transfers directly.