skilldrop-cli 0.16.3__py3-none-any.whl

skilldrop_cli/data/packs/design/skills/deck-builder/templates/deck-spec.json

@@ -0,0 +1,168 @@
+{
+  "_comment": "Full deck-spec schema. The build_deck.py script consumes this. Top-level fields: title, audience, aspect, template, layout_map, palette, brand, slide_numbers, slides[].",
+
+  "title": "ProjectX Migration — Board Update",
+  "audience": "board",
+
+  "_aspect_comment": "16:9 (default), 4:3, or 16:10. Ignored when `template` is set — the template's own slide size wins.",
+  "aspect": "16:9",
+
+  "_template_comment": "Set `template` to a brand .pptx/.potx and the deck inherits its masters, theme fonts, colors and slide size. Relative paths resolve against this spec file. Discover the layout names with: python3 scripts/build_deck.py --list-layouts brand.potx — then map each logical layout to one. Any logical layout left out of the map falls back to the deck's own built-in design.",
+  "_template": "./brand/acme-master.potx",
+  "_layout_map": {
+    "title": "Title Slide",
+    "section": "Section Header",
+    "content": "Title and Content",
+    "two_column": "Two Content",
+    "big_number": "Title Only",
+    "quote": "Title Only",
+    "image": "Picture with Caption",
+    "table": "Title Only",
+    "chart": "Title Only",
+    "closing": "Closing"
+  },
+
+  "_brand_comment": "Path to a brand.json from the brand-kit skill, or the same object inline. It fills anything this spec leaves out: palette colours, template, logo files (logo.primary, logo.on_dark — PNG or JPG) and fonts (fonts.heading.family, fonts.body.family). --brand on the command line overrides it.",
+  "brand": "./brand/brand.json",
+
+  "palette": {
+    "primary": "#1A2A6C",
+    "secondary": "#4A5A8C",
+    "accent": "#FDBB2D",
+    "background": "#FFFFFF",
+    "text": "#222222"
+  },
+
+  "slide_numbers": true,
+
+  "slides": [
+    {
+      "layout": "title",
+      "title": "ProjectX Migration",
+      "subtitle": "Board update — Q3 FY26",
+      "presenter": "John Doe",
+      "date": "2026-09-15",
+      "notes": "Set the scene in one sentence — we're 60% through, ask is to approve overrun budget."
+    },
+
+    {
+      "layout": "section",
+      "title": "Where we are",
+      "notes": "Quick orientation before diving into the numbers."
+    },
+
+    {
+      "layout": "content",
+      "title": "Migration is 60% complete and on track for Q1 close",
+      "bullets": [
+        "8 of 14 services cut over with zero customer-visible incidents",
+        "Performance up 22% on migrated services (p99 latency)",
+        "Two services pushed to phase 3 — schema rewrite needed first"
+      ],
+      "notes": "Lead with the positive — zero incidents matters. Note the slipped services so it isn't a surprise later."
+    },
+
+    {
+      "layout": "big_number",
+      "title": "Cost savings already realised",
+      "number": "$2.4M",
+      "caption": "Annualised infra savings from the 8 migrated services",
+      "notes": "Pause here. Let the number land. Then say: we expect $5.8M annualised at full completion."
+    },
+
+    {
+      "layout": "chart",
+      "title": "Savings accrue as services cut over",
+      "takeaway": "Every phase has beaten its savings forecast — phase 3 is the same shape of work.",
+      "chart": {
+        "type": "column",
+        "categories": ["Phase 1", "Phase 2", "Phase 3 (fcst)"],
+        "series": [
+          { "name": "Forecast ($M)", "values": [0.6, 1.4, 2.0] },
+          { "name": "Actual ($M)", "values": [0.8, 1.6, null] }
+        ],
+        "legend": true,
+        "number_format": "0.0"
+      },
+      "source": "FinOps monthly report, Aug FY26",
+      "notes": "Only chart numbers that exist in the source. If a forecast is a forecast, label it one."
+    },
+
+    {
+      "layout": "table",
+      "title": "Service cut-over status",
+      "columns": ["Service", "Phase", "Status", "p99 delta"],
+      "rows": [
+        ["checkout-api", "1", "Live", "-31%"],
+        ["billing-core", "1", "Live", "-18%"],
+        ["catalogue", "2", "Live", "-22%"],
+        ["identity", "2", "Live", "-9%"],
+        ["ledger", "3", "Schema rewrite", "—"],
+        ["reporting", "3", "Schema rewrite", "—"]
+      ],
+      "caption": "Full 14-service table in the appendix pack.",
+      "notes": "Don't read the table. Point at the two rows in the last column and move on."
+    },
+
+    {
+      "layout": "image",
+      "title": "Target architecture after phase 3",
+      "image": "./assets/target-architecture.png",
+      "position": "right",
+      "bullets": [
+        "Single control plane per region",
+        "Legacy DB decommissioned at phase 3 close",
+        "Active-active across two regions"
+      ],
+      "caption": "Generated from the C4 model — see the architecture repo for the source.",
+      "notes": "Raster only (PNG/JPG). Export SVG or EMF diagrams to PNG first — python-pptx cannot read them."
+    },
+
+    {
+      "layout": "two_column",
+      "title": "What's left vs. what's added",
+      "left": {
+        "title": "Original scope",
+        "bullets": [
+          "14 services migrated",
+          "Legacy DB decommissioned",
+          "Single-region active"
+        ]
+      },
+      "right": {
+        "title": "Discovered in flight",
+        "bullets": [
+          "2 services need schema rewrite",
+          "Multi-region requirement (regulatory)",
+          "Auth refactor coupled with cut-over"
+        ]
+      },
+      "notes": "Frame the scope additions honestly. Multi-region was a regulator change, not a planning miss."
+    },
+
+    {
+      "layout": "quote",
+      "quote": "The migration went smoother than any I've seen in 20 years — and our team learned more in 6 months than the prior 2.",
+      "attribution": "VP Engineering, after phase 2 cut-over",
+      "notes": "Optional, but lands well with a board that's worried about morale."
+    },
+
+    {
+      "layout": "content",
+      "title": "Top risks for the remaining 40%",
+      "bullets": [
+        "Schema rewrite — 6 weeks, narrowly de-risked by dry runs",
+        "Auth refactor coupling — increases coordination overhead",
+        "Holiday-period freeze cuts available calendar by 4 weeks"
+      ],
+      "notes": "Don't soften the risks. Boards trust presenters who name them."
+    },
+
+    {
+      "layout": "closing",
+      "title": "Asking for $620k FY26 budget overrun",
+      "subtitle": "Covers schema rewrite + multi-region; payback < 8 months",
+      "notes": "Land on the Ask. Take questions here, not after a thank-you slide."
+    }
+  ]
+}

skilldrop_cli/data/packs/design/skills/deck-builder/templates/palettes.json

@@ -0,0 +1,59 @@
+{
+  "_comment": "Pre-built palettes. Reference by name in a deck spec via `palette: \"corporate-blue\"` (the script resolves the name to these values), or copy/paste the block into the spec's `palette` field.",
+
+  "corporate-blue": {
+    "primary": "#1A2A6C",
+    "secondary": "#4A5A8C",
+    "accent": "#FDBB2D",
+    "background": "#FFFFFF",
+    "text": "#222222"
+  },
+
+  "monochrome": {
+    "primary": "#212121",
+    "secondary": "#555555",
+    "accent": "#888888",
+    "background": "#FFFFFF",
+    "text": "#1A1A1A"
+  },
+
+  "vibrant": {
+    "primary": "#FF3366",
+    "secondary": "#FF9933",
+    "accent": "#33CCFF",
+    "background": "#FFFFFF",
+    "text": "#1F1F1F"
+  },
+
+  "dark-mode": {
+    "primary": "#4FC3F7",
+    "secondary": "#7E57C2",
+    "accent": "#FFD54F",
+    "background": "#121212",
+    "text": "#EAEAEA"
+  },
+
+  "editorial": {
+    "primary": "#2C3E50",
+    "secondary": "#7F8C8D",
+    "accent": "#E67E22",
+    "background": "#FDFBF7",
+    "text": "#2C3E50"
+  },
+
+  "forest": {
+    "primary": "#1B5E20",
+    "secondary": "#558B2F",
+    "accent": "#FBC02D",
+    "background": "#FFFFFF",
+    "text": "#1B1B1B"
+  },
+
+  "sunset": {
+    "primary": "#C2185B",
+    "secondary": "#F57C00",
+    "accent": "#FFEB3B",
+    "background": "#FFF8F0",
+    "text": "#2A1A1A"
+  }
+}

skilldrop_cli/data/packs/design/skills/marketing-flyer/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: marketing-flyer
+description: Generate a print-ready, on-brand marketing flyer — event, launch, open day, offer, hiring — as one self-contained HTML file (Letter, A4, A5, or square and story sizes for social) that saves to PDF, built from the user's own logo, colours, fonts and content, with one call to action, a short headline, contrast checked, and no invented dates, prices or contact details. Use when the user wants a flyer, poster, one-pager, handout, leaflet or event announcement "in our branding", or says "make a flyer for…".
+---
+
+# marketing-flyer
+
+You make a flyer that looks like it came from the user's own team, because it's built from
+their brand: their logo, their colours, their fonts, their words. The output is one HTML file
+with the images embedded, sized for print, that saves to PDF from any browser. When a
+`brand.json` from [`brand-kit`](../brand-kit/SKILL.md) exists, use it, and the flyer will match
+the user's decks from [`deck-builder`](../deck-builder/SKILL.md).
+
+## How to respond
+
+1. **Ask for everything in one message.** Take what's already been given, and suggest
+   defaults so the user can reply "go".
+
+   > Before I build the flyer, send these. Anything you skip, I'll use the default shown:
+   > 1. **Brand:** a `brand.json` from brand-kit, *or* your logo file (and a white version for
+   >    dark backgrounds), brand colours as hex codes, and heading and body fonts.
+   >    *Default: no brand, which looks generic, so please send at least a logo and one colour.*
+   > 2. **What it's for, and who reads it:** an event, a launch, an offer, hiring, a service
+   > 3. **The words:** a headline (ten words or fewer), a one-line subhead, up to four key
+   >    points, and details such as date, time, place and price
+   > 4. **One call to action:** what the reader should do, and the web address, phone or email for it.
+   >    A QR code image too, if you have one.
+   > 5. **Images:** a photo for the top of the flyer, if any, with a line describing it
+   > 6. **Size:** `letter` · `a4` · `a5` · `square` (Instagram/LinkedIn) · `story` · and
+   >    portrait or landscape. *Default: letter, portrait.*
+   > 7. **Layout:** `hero` (photo across the top) · `split` (photo down one side) ·
+   >    `event` (a big date block) · `minimal`. *Default: event when there's a date, otherwise hero.*
+
+   **Content is the hard input.** Never invent a date, time, price, address, phone number,
+   web address or statistic. If the user gave only a topic, ask for the details. A flyer with
+   a wrong date is worse than no flyer.
+
+2. **Write the copy to fit a flyer.** Rewrite long text into the flyer's shape and show the
+   user what you changed:
+   - A headline of ten words or fewer that names the thing, such as "Free community health
+     fair", not "You're invited!".
+   - A subhead that says who it's for, or why it's worth coming.
+   - At most four points, each one line, so they can be read in passing.
+   - Exactly **one** call to action, worded as a verb ("Save your spot", "Call to book"). Two
+     calls to action means the reader does neither.
+
+   Use the brand's voice from `brand.json` when it has one: words to use, words to avoid.
+
+3. **Write the spec** in the shape of [`templates/flyer-spec.json`](templates/flyer-spec.json),
+   with paths relative to the spec file.
+
+4. **Build it.**
+
+   ```bash
+   # Claude Code
+   python3 "${CLAUDE_SKILL_DIR}/scripts/build_flyer.py" flyer-spec.json -o flyer.html --brand ./brand/brand.json --pdf flyer.pdf
+   # Other IDEs (from the skill folder)
+   python3 scripts/build_flyer.py flyer-spec.json -o flyer.html --brand ./brand/brand.json --pdf flyer.pdf
+   ```
+
+   `--pdf` and `--png` use a local Chrome or Chromium when one is installed. Without one, the
+   user opens `flyer.html` and prints it to PDF at 100% scale with margins set to none.
+   Use `--png` for the `square` and `story` sizes, which are posted as images.
+
+5. **Read the output and every warning.** The script prints three contrast figures: text,
+   the header band, and the call to action. It picks white or the brand's text colour on each
+   filled band, whichever reads better. It warns about a long headline, more than four
+   points, more than one call to action, a missing logo or image, and no brand. Fix what you
+   can, and report the rest to the user with what it means.
+
+6. **Tell the user how to check it before printing:** read every date, time and address
+   aloud against the source, check the web address works, and print one test copy.
+
+**Non-interactive runs** (subagent, CI, headless): missing *content* does not get a default.
+Emit `BLOCKED: need the flyer's details: <what is missing>` and build nothing. Missing brand
+falls back to defaults with an `[assumption]` line at the top; never make up a logo.
+
+## Useful references in this skill
+
+- [`reference.md`](reference.md) — sizes and print rules, layouts and when to use each, copy budgets, contrast
+- [`templates/flyer-spec.json`](templates/flyer-spec.json) — the spec, every field shown
+- [`scripts/build_flyer.py`](scripts/build_flyer.py) — the builder (stdlib only): HTML, plus PDF and PNG through headless Chrome
+- [`examples/community-health-fair.md`](examples/community-health-fair.md) — worked example: an email from the user becomes a flyer spec and a branded flyer
+
+## Quality bar
+
+- **It is in the user's brand:** their logo, their colours as hex codes, their fonts. Default colours only when the user has no brand material, and then said out loud.
+- **Every fact comes from the user.** Dates, times, places, prices and contact details are copied, not composed.
+- **One call to action,** worded as a verb, with the address or number that makes it actionable.
+- **A headline of ten words or fewer, at most four points.** Anything longer belongs on the linked page.
+- **Text is readable everywhere:** body text at least 4.5:1 against the background, and the script's band and call-to-action figures reported.
+- **The file is the whole flyer.** Images are embedded, with no links to local files that break when it's emailed.
+
+## When to use this skill
+
+- ✅ An event, a launch, an open day, an offer, a hiring drive, a service announcement
+- ✅ A one-page handout or leaflet in the company's branding
+- ✅ A square or story-sized image for social posts that matches the printed flyer
+
+## When NOT to use this skill
+
+- ❌ A slide deck; use `deck-builder`
+- ❌ A multi-page brochure or a report, which this doesn't lay out
+- ❌ Designing a brand from scratch; capture an existing one with `brand-kit`
+
+## Anti-patterns to avoid
+
+- ❌ **"You're invited!" as the headline.** Name the event, the offer or the product.
+- ❌ **Three buttons** ("Register", "Learn more", "Follow us"). Pick the one action that matters.
+- ❌ **Filling a missing date with "TBC"** or a plausible guess. Ask, or build nothing.
+- ❌ **White text on a pale accent** because the brand's buttons are white. The script flips it; don't override it.
+- ❌ **A paragraph of body copy.** No one reads a paragraph on a noticeboard.
+- ❌ **Sending the HTML with images linked from the user's disk.** Always build with the script, which embeds them.

skilldrop_cli/data/packs/design/skills/marketing-flyer/evals/eval_queries.json

@@ -0,0 +1,30 @@
+[
+  {
+    "query": "Make a flyer for our open day in our brand colours",
+    "should_trigger": true
+  },
+  {
+    "query": "Design a one-page handout announcing the new clinic",
+    "should_trigger": true
+  },
+  {
+    "query": "I need a poster for the charity run, with our logo",
+    "should_trigger": true
+  },
+  {
+    "query": "Create an Instagram-sized announcement image that matches our flyer",
+    "should_trigger": true
+  },
+  {
+    "query": "Build the board deck as a pptx",
+    "should_trigger": false
+  },
+  {
+    "query": "Write the press release for the launch",
+    "should_trigger": false
+  },
+  {
+    "query": "Set up our brand colours and fonts so we can reuse them",
+    "should_trigger": false
+  }
+]

skilldrop_cli/data/packs/design/skills/marketing-flyer/evals/evals.json

@@ -0,0 +1,18 @@
+{
+  "skill_name": "marketing-flyer",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Make a flyer for our community health fair using ./brand/brand.json. It's Saturday 14 November, 10am to 2pm, at the Riverside Park pavilion, free. There'll be blood pressure and glucose checks, flu shots with no appointment, a kids' corner and cooking demos. People should register at northwindhealth.example/fair. Letter size.",
+      "assertions": [
+        "Uses the supplied brand.json, so the flyer carries the brand logo and colours",
+        "The headline is ten words or fewer and names the event",
+        "There is exactly one call to action, worded as a verb, with northwindhealth.example/fair",
+        "The date, time, place and price match the prompt exactly; nothing is invented (no phone number, no extra dates)",
+        "No more than four points",
+        "Runs build_flyer.py and reports the contrast figures and any warnings",
+        "Picks the event layout, or explains choosing another, because the date is the key fact"
+      ]
+    }
+  ]
+}

skilldrop_cli/data/packs/design/skills/marketing-flyer/evals/files/1/brand/brand.json

@@ -0,0 +1,80 @@
+{
+  "$comment": "brand-kit output. deck-builder and marketing-flyer read this file; any field left out is asked for or defaulted by them. Paths are relative to this file. Every value carries where it came from in `sources`.",
+  "name": "Northwind Health",
+  "tagline": "Care that comes to you",
+  "logo": {
+    "primary": "logo.png",
+    "on_dark": "logo-white.png",
+    "mark": "mark.png",
+    "notes": "Keep clear space equal to the height of the N on every side. Never place the full-colour logo on the green."
+  },
+  "colors": {
+    "primary": "#0E5A46",
+    "secondary": "#3D7F6B",
+    "accent": "#F2A541",
+    "background": "#FFFFFF",
+    "text": "#1F2A28",
+    "extra": [
+      {
+        "name": "Mist",
+        "hex": "#E8F1EE",
+        "use": "panel backgrounds"
+      }
+    ]
+  },
+  "fonts": {
+    "heading": {
+      "family": "Georgia",
+      "fallback": "serif",
+      "weight": 700
+    },
+    "body": {
+      "family": "Arial",
+      "fallback": "sans-serif",
+      "weight": 400
+    }
+  },
+  "voice": {
+    "tone": "Warm, plain, confident. Short sentences.",
+    "use": [
+      "members",
+      "care team",
+      "near you"
+    ],
+    "avoid": [
+      "patients",
+      "cutting-edge",
+      "solutions"
+    ]
+  },
+  "imagery": {
+    "style": "Real people in daylight, community settings, no stock handshakes.",
+    "do": [
+      "natural light",
+      "diverse ages"
+    ],
+    "dont": [
+      "clinical close-ups",
+      "illustrated icons as hero images"
+    ]
+  },
+  "templates": {
+    "pptx": "northwind-master.potx"
+  },
+  "contact": {
+    "website": "northwindhealth.example",
+    "email": "hello@northwindhealth.example",
+    "phone": "",
+    "address": ""
+  },
+  "legal": {
+    "footer": "\u00a9 2026 Northwind Health",
+    "disclaimer": ""
+  },
+  "sources": {
+    "colors": "brand guidelines PDF, page 4 [explicit]",
+    "fonts": "brand guidelines PDF, page 6 [explicit]",
+    "voice": "website About page [inferred]",
+    "logo": "files supplied by the user [explicit]"
+  }
+}

skilldrop_cli/data/packs/design/skills/marketing-flyer/examples/community-health-fair.md

@@ -0,0 +1,68 @@
+# Worked example — an email about a health fair becomes a branded flyer
+
+## Input given to the skill
+
+> Can you make a flyer for our community health fair? Use our brand kit in ./brand/. It's
+> Saturday 14 November, 10am to 2pm, at the Riverside Park pavilion, and it's free. We'll have
+> free blood pressure and glucose checks, flu shots (no appointment), a kids' corner and some
+> healthy cooking demos. Oh and a raffle. People should register at
+> northwindhealth.example/fair so we know numbers. Letter size please, we'll print it at the office.
+
+---
+
+**Copy, fitted to a flyer.** Here is what I changed from your email:
+
+- **Headline:** "Free community health fair" (5 words)
+- **Subhead:** "Checkups, flu shots and healthy cooking — for the whole family"
+- **Points (3):** free blood pressure and glucose checks · flu shots, no appointment needed ·
+  kids' corner and healthy cooking demos. *The raffle is left off: four points is the most a
+  flyer carries, and the other three bring people in. Say if you want it instead of the
+  cooking demos.*
+- **Call to action:** "Save your spot" → northwindhealth.example/fair
+- **Layout:** `event`, because the date is the fact people need first
+
+**Spec** (`flyer-spec.json`):
+
+```json
+{
+  "brand": "./brand/brand.json",
+  "size": "letter",
+  "layout": "event",
+  "headline": "Free community health fair",
+  "subhead": "Checkups, flu shots and healthy cooking — for the whole family",
+  "points": ["Free blood pressure and glucose checks", "Flu shots, no appointment needed", "Kids' corner and healthy cooking demos"],
+  "details": [
+    { "label": "When", "value": "Sat 14 Nov, 10am–2pm" },
+    { "label": "Where", "value": "Riverside Park pavilion" },
+    { "label": "Cost", "value": "Free" }
+  ],
+  "cta": { "text": "Save your spot", "url": "northwindhealth.example/fair" },
+  "image": { "path": "./riverside-park.png", "alt": "Families at Riverside Park" },
+  "footer": "© 2026 Northwind Health"
+}
+```
+
+**Build:**
+
+```
+$ python3 scripts/build_flyer.py flyer-spec.json -o community-health-fair.html --brand ./brand/brand.json --pdf community-health-fair.pdf
+wrote ./community-health-fair.html (event, letter; brand: yes; logo: yes)
+  contrast: text 14.8:1 · band 8.2:1 · call to action 7.2:1
+wrote ./community-health-fair.pdf
+```
+
+**The flyer:** Northwind's green band across the top with the white logo. A large amber date
+block reading *Sat 14 Nov, 10am–2pm* sits beside the Georgia headline. Below are the park
+photo, the three points with amber markers, Where and Cost, and an amber "Save your spot" panel
+with the web address in dark text, because white on that amber would be hard to read. The
+footer carries the website and the copyright line.
+
+**Before you print:** read the date, time and place aloud against your email, open
+northwindhealth.example/fair to check it works, and print one test copy.
+
+---
+
+**Why this is a good output:** every fact is copied from the email, and the one cut (the raffle)
+is named and offered back instead of silently dropped. There's one call to action. The layout
+puts the date first because that's what a passer-by needs. The contrast figures are reported,
+and the panel text uses the colour that reads.

skilldrop_cli/data/packs/design/skills/marketing-flyer/manifest.json

@@ -0,0 +1,40 @@
+{
+  "name": "marketing-flyer",
+  "version": "0.1.0",
+  "description": "Generate a print-ready, on-brand marketing flyer — event, launch, open day, offer, hiring — as one self-contained HTML file (Letter, A4, A5, or square and story sizes for social) that saves to PDF, built from the user's own logo, colours, fonts and content, with one call to action, a short headline, contrast checked, and no invented dates, prices or contact details. Use when the user wants a flyer, poster, one-pager, handout, leaflet or event announcement \"in our branding\", or says \"make a flyer for…\".",
+  "entrypoint": "SKILL.md",
+  "deps": {
+    "npm": [],
+    "pip": []
+  },
+  "env": {
+    "required": [],
+    "optional": []
+  },
+  "related": [
+    "brand-kit",
+    "deck-builder"
+  ],
+  "handoff": [
+    {
+      "to": "brand-kit",
+      "when": "the user has brand material but no brand.json",
+      "purpose": "Capture the logo, colours and fonts once, so the flyer and later decks match.",
+      "fallback": "If brand-kit is absent, ask for the logo path and brand hex codes in the setup block and put them in the spec's brand object inline."
+    }
+  ],
+  "tags": [
+    "flyer",
+    "poster",
+    "marketing",
+    "print",
+    "pdf",
+    "brand",
+    "design"
+  ],
+  "permissions": {"network": [], "commands": ["google-chrome", "chromium", "chrome"], "files": "named-paths", "notes": "A local Chrome or Chromium is run headless only for --pdf and --png; the HTML needs nothing."},
+  "model": {
+    "tier": "standard",
+    "rationale": "Writes short copy to fit and fills a spec for a deterministic builder. Bounded generation."
+  }
+}

skilldrop_cli/data/packs/design/skills/marketing-flyer/reference.md

@@ -0,0 +1,54 @@
+# marketing-flyer reference
+
+## Sizes
+
+| `size` | Dimensions | Use |
+|---|---|---|
+| `letter` | 8.5 × 11 in | US noticeboards and handouts (default) |
+| `a4` | 210 × 297 mm | Everywhere outside the US |
+| `a5` | 148 × 210 mm | Leaflets, counter cards, two to a sheet |
+| `square` | 1080 × 1080 px | Instagram and LinkedIn posts; export with `--png` |
+| `story` | 1080 × 1920 px | Stories and phone screens; export with `--png` |
+
+`"orientation": "landscape"` swaps width and height. The HTML sets `@page` to the exact size
+with no margins and turns on exact colour printing, so a browser's *Print → Save as PDF* at
+100% scale reproduces it. Home and office printers can't print to the edge. For a flyer
+printed on a desk printer, keep important content at least 0.25 in (6 mm) from the edge,
+which every layout already does except for the full-width image and band. For professional
+printing with bleed, export the PDF and ask the printer for their bleed requirements.
+
+## Layouts
+
+| `layout` | Looks like | Use when |
+|---|---|---|
+| `hero` | Logo band, a full-width photo, then the copy | There's a strong photo, and the thing itself is the draw |
+| `split` | A photo (or brand-colour block) down the left, copy on the right | The photo is portrait, or the copy is a list of points |
+| `event` | Logo band, a large date block beside the headline, then photo and details | The date is the most important fact |
+| `minimal` | Logo, headline, a rounded photo, copy on white | Offers and announcements where restraint reads as quality |
+
+The first `details` entry is the date block in `event`; put the date there.
+
+## Copy budgets
+
+| Element | Budget | Why |
+|---|---|---|
+| Headline | ≤ 10 words | Read from across a room in two seconds |
+| Subhead | One line | Who it's for, or why it's worth it |
+| Points | ≤ 4, one line each | A flyer is scanned, not read |
+| Body | ≤ 60 words, usually none | A paragraph is skipped on a noticeboard |
+| Call to action | Exactly one, a verb | Two choices means neither gets made |
+
+## Colour and contrast
+
+- **Body text** must reach 4.5:1 against the background. The script refuses to build below that.
+- **Header band and call to action:** the script prints white or the brand's text colour,
+  whichever contrasts more with the fill. A pale accent therefore gets dark text. Don't
+  override this.
+- **Points' markers use the accent.** Keep the accent for shapes and highlights, not long text.
+
+## Fonts
+
+The HTML names the brand's fonts with a fallback, such as `'Georgia', serif`. A font the
+viewer doesn't have installed falls back to the generic family, so the PDF uses whatever is
+installed on the machine that printed it. For an exact match, export the PDF on a machine
+that has the brand fonts installed.