@stacksjs/defaults 0.75.109 → 0.75.111

package/ai/skills/stacks-marketing-ads/references/platform-setup-checklists.md

@@ -0,0 +1,277 @@
+# Platform Setup Checklists
+
+Complete setup checklists for major ad platforms.
+
+## Contents
+- Google Ads Setup (Account Foundation, Conversion Tracking, Analytics Integration, Audience Setup, Campaign Readiness, Ad Extensions, Brand Protection)
+- Meta Ads Setup (Business Manager Foundation, Pixel & Tracking, Domain & Aggregated Events, Audience Setup, Catalog, Creative Assets, Compliance)
+- LinkedIn Ads Setup (Campaign Manager Foundation, Insight Tag & Tracking, Audience Setup, Lead Gen Forms, Document Ads, Creative Assets, Budget Considerations)
+- Twitter/X Ads Setup (Account Foundation, Tracking, Audience Setup, Creative)
+- TikTok Ads Setup (Account Foundation, Pixel & Tracking, Audience Setup, Creative)
+- Universal Pre-Launch Checklist
+
+## Google Ads Setup
+
+### Account Foundation
+
+- [ ] Google Ads account created and verified
+- [ ] Billing information added
+- [ ] Time zone and currency set correctly
+- [ ] Account access granted to team members
+
+### Conversion Tracking
+
+- [ ] Google tag installed on all pages
+- [ ] Conversion actions created (purchase, lead, signup)
+- [ ] Conversion values assigned (if applicable)
+- [ ] Enhanced conversions enabled
+- [ ] Test conversions firing correctly
+- [ ] Import conversions from GA4 (optional)
+
+### Analytics Integration
+
+- [ ] Google Analytics 4 linked
+- [ ] Auto-tagging enabled
+- [ ] GA4 audiences available in Google Ads
+- [ ] Cross-domain tracking set up (if multiple domains)
+
+### Audience Setup
+
+- [ ] Remarketing tag verified
+- [ ] Website visitor audiences created:
+  - All visitors (180 days)
+  - Key page visitors (pricing, demo, features)
+  - Converters (for exclusion)
+- [ ] Customer match lists uploaded
+- [ ] Similar audiences enabled
+
+### Campaign Readiness
+
+- [ ] Negative keyword lists created:
+  - Universal negatives (free, jobs, careers, reviews, complaints)
+  - Competitor negatives (if needed)
+  - Irrelevant industry terms
+- [ ] Location targeting set (include/exclude)
+- [ ] Language targeting set
+- [ ] Ad schedule configured (if B2B, business hours)
+- [ ] Device bid adjustments considered
+
+### Ad Extensions
+
+- [ ] Sitelinks (4-6 relevant pages)
+- [ ] Callouts (key benefits, offers)
+- [ ] Structured snippets (features, types, services)
+- [ ] Call extension (if phone leads valuable)
+- [ ] Lead form extension (if using)
+- [ ] Price extensions (if applicable)
+- [ ] Image extensions (where available)
+
+### Brand Protection
+
+- [ ] Brand campaign running (protect branded terms)
+- [ ] Competitor campaigns considered
+- [ ] Brand terms in negative lists for non-brand campaigns
+
+---
+
+## Meta Ads Setup
+
+### Business Manager Foundation
+
+- [ ] Business Manager created
+- [ ] Business verified (if running certain ad types)
+- [ ] Ad account created within Business Manager
+- [ ] Payment method added
+- [ ] Team access configured with proper roles
+
+### Pixel & Tracking
+
+- [ ] Meta Pixel installed on all pages
+- [ ] Standard events configured:
+  - PageView (automatic)
+  - ViewContent (product/feature pages)
+  - Lead (form submissions)
+  - Purchase (conversions)
+  - AddToCart (if e-commerce)
+  - InitiateCheckout (if e-commerce)
+- [ ] Conversions API (CAPI) set up for server-side tracking
+- [ ] Event Match Quality score > 6
+- [ ] Test events in Events Manager
+
+### Domain & Aggregated Events
+
+- [ ] Domain verified in Business Manager
+- [ ] Aggregated Event Measurement configured
+- [ ] Top 8 events prioritized in order of importance
+- [ ] Web events prioritized for iOS 14+ tracking
+
+### Audience Setup
+
+- [ ] Custom audiences created:
+  - Website visitors (all, 30/60/90/180 days)
+  - Key page visitors
+  - Video viewers (25%, 50%, 75%, 95%)
+  - Page/Instagram engagers
+  - Customer list uploaded
+- [ ] Lookalike audiences created (1%, 1-3%)
+- [ ] Saved audiences for common targeting
+
+### Catalog (E-commerce)
+
+- [ ] Product catalog connected
+- [ ] Product feed updating correctly
+- [ ] Catalog sales campaigns enabled
+- [ ] Dynamic product ads configured
+
+### Creative Assets
+
+- [ ] Images in correct sizes:
+  - Feed: 1080x1080 (1:1)
+  - Stories/Reels: 1080x1920 (9:16)
+  - Landscape: 1200x628 (1.91:1)
+- [ ] Videos in correct formats
+- [ ] Ad copy variations ready
+- [ ] UTM parameters in all destination URLs
+
+### Compliance
+
+- [ ] Special Ad Categories declared (if housing, credit, employment, politics)
+- [ ] Landing page complies with Meta policies
+- [ ] No prohibited content in ads
+
+---
+
+## LinkedIn Ads Setup
+
+### Campaign Manager Foundation
+
+- [ ] Campaign Manager account created
+- [ ] Company Page connected
+- [ ] Billing information added
+- [ ] Team access configured
+
+### Insight Tag & Tracking
+
+- [ ] LinkedIn Insight Tag installed on all pages
+- [ ] Tag verified and firing
+- [ ] Conversion tracking configured:
+  - URL-based conversions
+  - Event-specific conversions
+- [ ] Conversion values set (if applicable)
+
+### Audience Setup
+
+- [ ] Matched Audiences created:
+  - Website retargeting audiences
+  - Company list uploaded (for ABM)
+  - Contact list uploaded
+- [ ] Lookalike audiences created
+- [ ] Saved audiences for common targeting
+
+### Lead Gen Forms (if using)
+
+- [ ] Lead gen form templates created
+- [ ] Form fields selected (minimize for conversion)
+- [ ] Privacy policy URL added
+- [ ] Thank you message configured
+- [ ] CRM integration set up (or CSV export process)
+
+### Document Ads (if using)
+
+- [ ] Documents uploaded (PDF, PowerPoint)
+- [ ] Gating configured (full gate or preview)
+- [ ] Lead gen form connected
+
+### Creative Assets
+
+- [ ] Single image ads: 1200x627 (1.91:1) or 1080x1080 (1:1)
+- [ ] Carousel images ready
+- [ ] Video specs met (if using)
+- [ ] Ad copy within character limits:
+  - Intro text: 600 max, 150 recommended
+  - Headline: 200 max, 70 recommended
+
+### Budget Considerations
+
+- [ ] Budget realistic for LinkedIn CPCs ($8-15+ typical)
+- [ ] Audience size validated (50K+ recommended)
+- [ ] Daily vs. lifetime budget decided
+- [ ] Bid strategy selected
+
+---
+
+## Twitter/X Ads Setup
+
+### Account Foundation
+
+- [ ] Ads account created
+- [ ] Payment method added
+- [ ] Account verified (if required)
+
+### Tracking
+
+- [ ] Twitter Pixel installed
+- [ ] Conversion events created
+- [ ] Website tag verified
+
+### Audience Setup
+
+- [ ] Tailored audiences created:
+  - Website visitors
+  - Customer lists
+- [ ] Follower lookalikes identified
+- [ ] Interest and keyword targets researched
+
+### Creative
+
+- [ ] Tweet copy within 280 characters
+- [ ] Images: 1200x675 (1.91:1) or 1200x1200 (1:1)
+- [ ] Video specs met (if using)
+- [ ] Cards configured (website, app, etc.)
+
+---
+
+## TikTok Ads Setup
+
+### Account Foundation
+
+- [ ] TikTok Ads Manager account created
+- [ ] Business verification completed
+- [ ] Payment method added
+
+### Pixel & Tracking
+
+- [ ] TikTok Pixel installed
+- [ ] Events configured (ViewContent, Purchase, etc.)
+- [ ] Events API set up (recommended)
+
+### Audience Setup
+
+- [ ] Custom audiences created
+- [ ] Lookalike audiences created
+- [ ] Interest categories identified
+
+### Creative
+
+- [ ] Vertical video (9:16) ready
+- [ ] Native-feeling content (not too polished)
+- [ ] First 3 seconds are compelling hooks
+- [ ] Captions added (most watch without sound)
+- [ ] Music/sounds selected (licensed if needed)
+
+---
+
+## Universal Pre-Launch Checklist
+
+Before launching any campaign:
+
+- [ ] Conversion tracking tested with real conversion
+- [ ] Landing page loads fast (<3 sec)
+- [ ] Landing page mobile-friendly
+- [ ] UTM parameters working
+- [ ] Budget set correctly (daily vs. lifetime)
+- [ ] Start/end dates correct
+- [ ] Targeting matches intended audience
+- [ ] Ad creative approved
+- [ ] Team notified of launch
+- [ ] Reporting dashboard ready

package/ai/skills/stacks-marketing-ads/references/reading-google-ads-data.md

@@ -0,0 +1,121 @@
+# Reading Google Ads Data Without False Conclusions
+
+Load this before analyzing, auditing, or reporting on a Google Ads account, or before deciding whether to pause, keep, or scale anything in one. [audit-guardrails.md](audit-guardrails.md) covers how to *grade* what you find. This file covers how the data *misleads* you before you get that far.
+
+Google Ads reports are partial by design and plausible by accident. Default views omit data without saying so, resource names suggest contents they don't have, and small accounts produce numbers that look like findings. Most wrong conclusions come from not knowing that, not from bad reasoning.
+
+Query patterns and API gotchas live in [google-ads.md](https://github.com/coreyhaines31/marketingskills/blob/1efedbc5148b54b2f0f6c6c9fe0be62e151c7fff/tools/integrations/google-ads.md).
+
+## What the data hides
+
+### Search terms are a sample, not the total
+
+Google withholds any query searched by too few people. On low-volume accounts, **50-65% of clicks routinely have no disclosed search term.** The visible terms are a non-random sample skewed toward common searches.
+
+- Any claim about "what this campaign is buying" carries the ratio: *of the 13 clicks Google discloses, out of 33 total.*
+- Pull the report **unfiltered first**. Filtering by `clicks > 0` also drops every impression-only term, and combined with a low `LIMIT` it hides most of the picture.
+- **Nothing recovers the withheld queries.** The query is never passed to the site, so GA4, PostHog, or a CRM can show what every session *did* (joined on gclid), never what was *typed*.
+
+```
+disclosed clicks = SUM(clicks in the search terms report)
+total clicks     = campaign clicks for the same window
+withheld         = total - disclosed
+```
+
+### Names describe intentions, not contents
+
+An ad group called "Competitor - Commercial" can hold entirely informational keywords. A campaign named for one theme can target another. Read the keyword list and the search terms; treat every name as a label someone typed once.
+
+### "Conversions" is several things in one column
+
+`metrics.conversions` counts actions marked primary, plus any secondary action a campaign's custom goal pulls in. `metrics.all_conversions` adds the rest. Check campaign goals as well as action settings. One campaign's conversions might mix a page-view proxy, a trial signup, and a booked demo.
+
+- Segment by conversion action before calling anything a lead or a demo.
+- Check each action's attribution model and click window while you're there.
+- Data-driven attribution runs on low volume too, but with few conversions its individual credit assignments are soft. Don't read much into one campaign's share.
+
+### One ad group can send traffic to several pages
+
+Ads carry their own final URLs, and stale pages linger in rotation long after a new landing page ships. Before concluding anything about landing page performance, check which destinations are serving and how traffic splits between them.
+
+### Dates are click dates
+
+Conversions are attributed back to the originating click. A conversion recorded today can appear dated a week earlier. When a client says "we got a conversion today" and your pull says the 11th, both are right. Say "clicked on the 11th."
+
+### Identical campaign names are usually experiment arms
+
+Expired experiment arms inherit the base campaign's name and can keep an ENABLED status while serving nothing. Check `campaign.experiment_type` and `campaign.serving_status` before believing a duplicate exists.
+
+### Change history is short: 30 days with detail, 90 without
+
+`change_event` (field-level before and after) covers 30 days. `change_status` covers 90 days but only says which resource changed, not what. Past that, the API has nothing. A performance shift four months ago may have no recoverable explanation, so say that instead of guessing one.
+
+### Other people are changing the account
+
+Client staff, automated rules, scripts, and agents all leave changes. In `change_event`, `client_type` says which client made the change: `GOOGLE_ADS_WEB_CLIENT` (the UI), `GOOGLE_ADS_API`, `GOOGLE_ADS_SCRIPTS`, `GOOGLE_ADS_AUTOMATED_RULE`, `GOOGLE_ADS_BULK_UPLOAD`, `GOOGLE_ADS_RECOMMENDATIONS`, `INTERNAL_TOOL` (Google-side tooling), and others in the enum. Report the client, not a guess at who or why: an API change could be an agency tool or a script. Google Ads Editor changes aren't returned at all, so a missing edit doesn't mean nobody made one. A repeating weekday-and-time pattern under one user is a scheduled job, not a person.
+
+## The window is not the picture
+
+A 30-day pull on a campaign that has run since spring is a slice of a longer series. Recent CPA can differ sharply from lifetime CPA.
+
+- **Establish how long something has run** before quoting any efficiency number. Quote both recent and lifetime when they diverge.
+- **Don't pool across configuration changes.** If bids, keywords, budget, ads, or targeting changed mid-window, the period is several experiments averaged together.
+- **Bid-only changes are a special case.** They invalidate cost and volume comparisons but leave intent and audience questions readable.
+- **Bid strategies in learning are unreadable.** `primary_status = LEARNING` means don't judge performance or optimize on it. Fixing a verified break (tracking down, wrong URL) still comes first; see [audit-guardrails.md](audit-guardrails.md).
+
+## Small numbers
+
+Most false findings in small accounts are sample-size errors that look like insight. Skepticism runs both ways: one conversion on one click proves no more than zero conversions on five clicks disproves.
+
+Zero conversions in N clicks only rules out conversion rates at or above (95% confidence):
+
+| Clicks | Rules out CVR ≥ | What you can say |
+|---|---|---|
+| 5 | 45% | Nothing. Zero is the expected outcome |
+| 10 | 26% | Still nothing useful |
+| 30 | 10% | Can begin doubting a strong CVR |
+| 50 | 6% | Meaningful for high-intent search |
+| 100 | 3% | Underperforming if break-even CVR is above 3% |
+
+Before calling spend wasted, work out what it would have to convert at to be worth keeping:
+
+```
+break-even CVR = CPC ÷ target CPA
+```
+
+If break-even CVR is below the plausible range for that traffic, the term isn't failing, it's unmeasured. Then estimate how long a readable sample takes at current click volume. "Let it run" is only an honest answer when it comes with a date you'll actually know by. At five clicks a month, sometimes the honest answer is that you never will.
+
+## Documents describe a day; accounts move
+
+Audits, status docs, and proposals were true when written. Every performance number in them is stale until re-pulled. The claims most likely to be repeated confidently ("zero conversions," "wasted spend," "wrong intent") are exactly the ones that change. Carry the date with the claim: *as of the audit on the 2nd*.
+
+## Stating findings
+
+Know which of these each claim is:
+
+- **Verified**: pulled live this session, unfiltered, and reconciled against a total
+- **Inferred**: reasoned from verified data, could be wrong
+- **Stale**: from a document, an earlier session, or the client, with its date attached
+
+Keep stale claims out of client-facing sentences unless they're labeled as such.
+
+**The test before anything reaches a client: can they disprove this in a minute with their own account access?** They have the same reports. Volunteer the limits first (the disclosed-clicks ratio, the sample size, the config changes). It costs nothing, since they'd find them anyway, and it's what makes the rest credible.
+
+If a claim touches a landing page, open it. Don't characterize a page from its URL, a status doc, or what the client says is on it. Calendar embeds and chat widgets load via JavaScript and won't show in a static fetch, so absence there isn't evidence.
+
+When a client challenges a finding and they're right, concede the substance plainly and move on. Stacked retractions cost more credibility than the original error.
+
+## Conclusions that sound right
+
+| Sounds like | Usually |
+|---|---|
+| "This campaign has zero conversions" | True on the day the doc was written |
+| "The search terms are junk" | You're seeing ~40% of the clicks |
+| "That ad group is wrong-intent" | It's *named* that; the keywords say otherwise |
+| "$X wasted on those terms" | Below any readable sample size |
+| "It converted, so the term works" | One conversion on one click is noise |
+| "Performance declined in August" | Bids changed three times that month |
+| "Traffic lands on the new page" | Two ads serve; one points at the old page |
+| "It got a demo" | It got a conversion; check which action |
+| "There are duplicate campaigns" | Expired experiment arms with the base name |
+| "Nobody touched it last quarter" | Change history only covers 30 days |

package/ai/skills/stacks-marketing-ads/references/rsa-output-spec.md

@@ -0,0 +1,88 @@
+# Google RSA Output Spec
+
+When the user requests Google Ads RSAs (Responsive Search Ads), output MUST comply with these platform limits and structural requirements. Do not output any RSA that violates them.
+
+## Hard limits per RSA (enforce before responding)
+
+- **Headlines:** exactly **15** per RSA, each **≤ 30 characters** (count characters, including spaces). Render as `1. ... (NN chars)` so the reader can verify.
+- **Descriptions:** exactly **4** per RSA, each **≤ 90 characters**.
+- **Paths:**up to 2 path fields, each**≤ 15 characters**.
+- **Final URL:** present, https.
+- **Pinning:** state any pinned positions explicitly. Default = unpinned unless user asks.
+- **Per-account guardrail:** Google enforces **3 RSAs max per ad group**. When the user asks for >3, group them by ad group.
+
+## Required sidecar artifacts (always include with RSA request)
+
+1. **Ad group structure**, labeled `Ad group structure:` - list each ad group with its theme, target keywords (match types), and which RSAs map to it.
+2. **Negative keyword list**, labeled `Negative keywords:` - minimum **8** entries, group-level vs campaign-level called out.
+3. **Sitelinks** (≥ 4), **Callouts** (≥ 4 ≤25 chars), **Structured snippets** if relevant.
+
+## Medical / CFM compliance (when product context indicates pt-BR medical practice)
+
+If `.agents/product-marketing.md` indicates a Brazilian medical practice (CFM-regulated), the following terms are **forbidden** in headlines, descriptions, sitelinks, and callouts:
+
+- Superlatives: `#1`, `melhor`, `o melhor`, `melhor do brasil`, `top`, `referência`
+- Outcome promises: `garantido`, `garantia`, `cura`, `cura definitiva`, `100%`, `resultado garantido`, `livre da dor`
+- Comparative claims vs other doctors/clinics
+
+Use neutral framing: `atendimento`, `consulta`, `avaliação`, `segunda opinião`, `agende sua consulta`, `tire suas dúvidas`. Geo modifier (`Porto Alegre`, `POA`, `Zona Sul POA`) required where the prompt specifies a region.
+
+## Output ORDER (mandatory - emit in this order to avoid truncation)
+
+1. **Ad group structure** (short)
+2. **Negative keywords** (≥8, MANDATORY - emit BEFORE RSAs so it isn't dropped if output runs long)
+3. **Sitelinks** (≥4)
+4. **Callouts** (≥4)
+5. **RSA1, RSA2, RSA3** (largest section, last - safe to truncate gracefully)
+
+## Output template (mandatory shape)
+
+```
+Ad group structure:
+- AG1 [theme]: keywords (match types) → RSA1, RSA2
+- AG2 [theme]: ...
+
+Negative keywords:
+  Campaign-level:
+    - <kw>
+    - <kw>
+    (≥4 here)
+  Ad-group level:
+    - AG1: <kw>, <kw>
+    - AG2: <kw>, <kw>
+    (≥4 more here - TOTAL ≥8 entries)
+
+Sitelinks (≥4):
+  - <title (≤25)> | <desc1 (≤35)> | <desc2 (≤35)> | URL
+
+Callouts (≥4, each ≤25 chars):
+  - <callout>
+
+RSA1 - [ad group name]
+  Final URL: https://...
+  Path1: ...   Path2: ...
+  Headlines (15, each ≤30 chars):
+    1. <headline> (NN chars)
+    ...
+    15. <headline> (NN chars)
+  Descriptions (4, each ≤90 chars):
+    1. <description> (NN chars)
+    ...
+    4. <description> (NN chars)
+  Pinning: H1=none; H2=none; ...   (or explicit pins)
+
+RSA2 - ...
+RSA3 - ...
+```
+
+## Self-check before responding
+
+Before sending the output, run this checklist mentally:
+
+- [ ] Each RSA has exactly 15 headlines, exactly 4 descriptions.
+- [ ] Every headline is ≤30 chars; every description is ≤90 chars. Character counts printed.
+- [ ] Negative keyword list labeled and ≥8 entries.
+- [ ] Ad group structure labeled.
+- [ ] If medical (CFM): no forbidden superlative/outcome words; geo modifier present where required; language is pt-BR.
+
+If any check fails, rewrite before responding. Do not ship partial RSAs.

package/ai/skills/stacks-marketing-ai-seo/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Corey Haines
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/ai/skills/stacks-marketing-ai-seo/NOTICE.md

@@ -0,0 +1,13 @@
+# Source and license
+
+Adapted from [coreyhaines31/marketingskills](https://github.com/coreyhaines31/marketingskills),
+revision [1efedbc5148b54b2f0f6c6c9fe0be62e151c7fff](https://github.com/coreyhaines31/marketingskills/tree/1efedbc5148b54b2f0f6c6c9fe0be62e151c7fff),
+upstream skill `ai-seo`, version 2.7.6.
+The original MIT copyright and permission notice is in [LICENSE](LICENSE).
+
+Stacks supplies a namespaced entrypoint, shared implementation guidance, mapped
+related-skill links, and regular-hyphen copy. The playbook and its supporting
+references/templates are retained. Tool integrations remain optional linked
+references; upstream CLI programs, servers, and packaging scripts are not
+bundled or installed. Source examples are illustrative and changing platform
+facts require verification.