@stacksjs/defaults 0.75.109 → 0.75.110

package/ai/skills/stacks-marketing-seo-audit/references/local-seo-pages-and-measurement.md

@@ -0,0 +1,39 @@
+# Location Pages and Measurement
+
+Use this when the request includes local pages, schema, or performance reporting.
+
+## Page Content That Helps a Local Customer
+
+For a real customer-facing location, include accurate location/contact details, hours, services available there, booking/call links, access/parking directions where known, staff or location evidence, and useful nearby/service information. Link it from a location index and relevant service pages.
+
+For service coverage without an office, explain actual availability, constraints, travel or call-out policies, relevant local work examples when available, and a clear enquiry path. Say that it is a service area. Do not show a fake street address or imply a staffed branch.
+
+Example decision: a plumber has one operating base and serves two nearby towns. One honest coverage page may suffice. Separate town pages are justified only by additional useful information or evidence; neither town automatically merits another Business Profile.
+
+Before scaling, confirm a stable data source and meaningful differences across pages. Check the current [doorway-abuse policy](https://developers.google.com/search/docs/essentials/spam-policies#doorway-abuse). Route justified templates to programmatic-seo and hierarchy to site-architecture; consolidate pages when the proposed variants add no value.
+
+## Local Structured Data
+
+Use the most specific accurate LocalBusiness subtype and a stable identifier for each real location. Match the visible page facts; connect the location URL, public phone, hours, and physical coordinates where applicable. Do not mark service cities as invented branches or publish a hidden residential address through JSON-LD.
+
+Important distinction: Schema.org can describe a business without satisfying Google's rich-result requirements. Google's [LocalBusiness documentation](https://developers.google.com/search/docs/appearance/structured-data/local-business) requires an address for that search feature. For a business that cannot publish one, preserve privacy and explain that the rich-result requirement is unmet; do not fabricate an address or promise eligibility from `areaServed` alone.
+
+Self-serving LocalBusiness review markup does not earn review stars merely because the business displays testimonials. Do not import a profile rating into markup as a shortcut to stars.
+
+Use schema for implementation. Validate the rendered page and relevant test tools, then verify deployed markup matches the public content. A stripped text fetch is insufficient proof that JavaScript-injected JSON-LD is absent. Validation does not guarantee display or a local-pack ranking change.
+
+## Measure Customer Outcomes
+
+Keep a baseline by location and period:
+
+| Metric | Evidence | Interpretation limits |
+|---|---|---|
+| Qualified calls/bookings/leads | CRM or owner-confirmed outcomes | Deduplicate; attribution may be incomplete |
+| Profile interactions | Available Business Profile performance export | Interaction is not a completed sale |
+| Organic local queries/pages | Search Console query/page reports | Privacy thresholds and aggregation limit detail |
+| Website actions from profile links | Analytics with consistent campaign tags | Consent, blockers, and tagging can affect counts |
+| Local visibility | Comparable query/location observations | Distance, personalization, and volatility matter |
+
+Use a consistent tagging convention for profile website links while keeping the canonical location URL stable. Test that redirects and booking flows preserve the attribution needed. For call tracking, retain a genuine reachable business contact and verify the platform's current phone rules; do not blindly replace canonical citation numbers.
+
+Review changes against a comparable period, seasonality, opening-hours changes, and service capacity. Record what changed and when. Treat a visibility increase as an observation, not proof of causation or additional revenue. Set follow-up timing with the user rather than promising a universal recovery deadline.

package/ai/skills/stacks-marketing-seo-audit/references/local-seo-profile-and-citations.md

@@ -0,0 +1,41 @@
+# Profiles and Citations
+
+Use this for profile eligibility, field changes, and name/address/phone cleanup. Verify facts with the owner and the current [business representation guidelines](https://support.google.com/business/answer/3038177).
+
+## Model the Real Business
+
+| Business | Profile approach | Common mistake |
+|---|---|---|
+| Staffed storefront receiving customers | Actual location, public address and customer-facing hours | Keyword-stuffed name or wrong entrance |
+| Service-area business visiting customers | Actual base with address hidden when customers are not served there | Profiles for every city or exposing a home address |
+| Hybrid | Real customer-facing location plus actual coverage | Claiming unstaffed locations |
+| Multiple locations | Verify each location and its staffing/eligibility separately | Assuming a location page or rented mailbox establishes eligibility |
+| Online only | Use organic/AI search strategy appropriate to the business | Creating a fictitious local presence |
+
+Exceptions for practitioners, departments, co-located businesses, and special business types require their specific rules. Do not merge two legitimately distinct entities just because they share an address. An actual relocation needs an update to the existing business identity rather than an unexplained new duplicate.
+
+## Field-Level Review
+
+- **Name:** match real-world branding. Put services and coverage in their proper fields rather than adding search keywords to the name.
+- **Categories:** use the most specific accurate primary category and only justified additional categories. Check the current category options for that market.
+- **Services:** describe services actually offered; distinguish availability, territory, and appointment requirements.
+- **Description:** write factual business/service information. Keep promotions and links out of this field.
+- **Hours and contact:** confirm regular/special hours, correct phone routing, and a location-specific working website/booking link.
+- **Photos:** propose real exterior/entrance, interior, team, or service imagery appropriate to the business. Confirm permission before publishing identifiable customers.
+- **Posts:** use them for relevant current updates, offers, or events where available; do not invent a posting-frequency ranking benefit.
+- **Q&A:** Google [discontinued its Q&A API on November 3, 2025](https://developers.google.com/my-business/content/qanda/change-log). Do not prescribe API seeding or a universal editable Q&A section. Verify current interface availability; answer common customer questions in website content and accurate profile fields when a profile feature is unavailable.
+
+For service areas, confirm actual coverage using [Google's service-area guidance](https://support.google.com/business/answer/9157481). Listing another town does not create a new location or remove searcher distance as a ranking factor.
+
+## Citation Cleanup Table
+
+Use one row per observed listing:
+
+| Location/entity | Listing URL | Observed public facts | Verified source of truth | Correction / duplicate action | Access/status | Verification date |
+|---|---|---|---|---|---|---|
+
+Compare meaning, not merely punctuation: an abbreviation need not be an identity conflict. A wrong phone, old address, mismatched business, or duplicate that diverts customers deserves priority. Preserve location distinctions and legitimate branch phone numbers.
+
+For a home-based service business, use supported hidden-address listings or skip platforms that require publishing private information. Maintain the private operating address separately from public citation data.
+
+Select listings for customer relevance and accurate discovery. Bulk low-quality links, lifetime domain metrics, or a directory count alone do not demonstrate improved local outcomes. DIY corrections are a valid path; paid listing management is optional when its coverage, control, cost, and verification process fit the business.

package/ai/skills/stacks-marketing-seo-audit/references/local-seo.md

@@ -0,0 +1,86 @@
+# Local SEO
+
+Use this reference when the audit or request is about a local business: Google Business Profile, the map pack, citations, reviews, or location pages.
+
+Help local customers find the right business and turn searches into qualified calls, bookings, and visits. Diagnose the specific location and search context before prescribing changes.
+
+## Start With the Business Model
+
+Read existing product context at `.agents/product-marketing.md` (or `.claude/product-marketing.md`, including older `product-marketing-context.md` setups). Ask only for missing facts relevant to the request:
+
+- Business type: customers visit a storefront, staff travel to customers, both, or online only.
+- Actual operating locations, staffed hours, service coverage, services, and capacity.
+- Website and profile URLs; ownership, verification, duplicates, suspensions, or recent moves.
+- Desired outcome and available evidence: qualified calls, bookings, visits, profile performance, Search Console, and location-level conversion data.
+
+Use the requested scope. A profile description request needs a description, not a compulsory full audit. Without access, provide a provisional plan and identify the evidence needed; never report invented profile findings.
+
+For profile eligibility, address visibility, duplicates, categories, and current feature availability, read [profile-and-citations.md](local-seo-profile-and-citations.md). An online-only business needs a different SEO plan. A service area is not a collection of extra storefronts.
+
+## Diagnose the Local Search Problem
+
+Keep the two surfaces separate:
+
+| Surface | Inspect | Evidence to retain |
+|---|---|---|
+| Maps / local pack | Correct profile, query relevance, searcher distance, reputation | Query, observation date, search location, device/context, profile URL |
+| Organic website results | Indexation, relevant location/service page, content, internal links | Query, page URL, Search Console data where available |
+
+Google describes local ranking through relevance, distance, and prominence. Distance varies with the searcher's location; a larger declared service area does not establish a nearer physical location. Do not promise a top-three placement or a fixed ranking uplift.
+
+Compare like with like: the same queries, locations, observation method, and time window. A single search from the owner's office is not evidence of visibility throughout a city. Separate branded from non-branded demand and label estimates, observed facts, and hypotheses.
+
+Prioritize the constraint supported by evidence:
+
+1. Wrong, ineligible, duplicate, unverified, or suspended profile: resolve the actual issue before adding promotional content.
+2. Customers cannot contact or visit correctly: repair location facts, hours, destination links, and conversion paths.
+3. Relevant demand is not represented: improve accurate categories, service information, and useful location pages.
+4. Weak trust or discovery: address genuine customer feedback, relevant citations, and earned local mentions.
+
+## Improve the Profile and Citation Record
+
+Use [profile-and-citations.md](local-seo-profile-and-citations.md) for the requested profile or listing work. Produce field-level edits grounded in real business facts, with the existing value, proposed value, reason, and missing verification.
+
+Build a canonical location record for the real-world name, public contact details, customer-facing hours, profile ID, and matching location URL. Keep a private operating address separate when customers do not visit it. Never publish a hidden home address merely to satisfy a citation checklist.
+
+Citation cleanup should resolve conflicting identities and customer-facing information. Prioritize relevant maps, local/chamber, and industry listings customers actually use. Correct existing records and merge true duplicates through supported processes before creating more listings. For a software product directory campaign, use directory-submissions; its launch prerequisites and incentive rules are not a local Google review policy.
+
+## Earn and Respond to Reviews
+
+Ask customers with genuine experiences for honest feedback through a neutral request and the correct location's review link. Do not select only happy customers, buy reviews, offer incentives, require particular wording, or promise removal of criticism. Google's rules differ from other review platforms (see the stacks-marketing-referrals skill's review programs reference); read the current [Maps review policy](https://support.google.com/contributionpolicy/answer/7400114?hl=en-GB).
+
+Example request: "Thanks for choosing [business]. If you'd like to share your experience, you can leave a review here: [location review link]. We welcome your honest feedback."
+
+Reply specifically and courteously. For a complaint, acknowledge the concern and offer an appropriate private contact path without exposing customer, medical, financial, or job details. Report a policy violation through the platform's process; an unfavorable genuine opinion is not automatically removable.
+
+Track recurring feedback and service improvements alongside review volume and recency. A rating target must not become a staff quota for soliciting specified review content.
+
+## Build Useful Location and Service Pages
+
+Read [location-pages-and-measurement.md](local-seo-pages-and-measurement.md) when building pages, preparing local schema, or measuring results.
+
+Give each real location a useful destination. A service-area page describes verified service coverage; it must not imply an office that does not exist. Publish a city page only when it adds meaningful local information, evidence, or customer utility. Swapping city names in duplicated text does not create that value.
+
+Route implementation details to the relevant existing skill:
+
+- **The rest of this skill (seo-audit):** crawling, indexing, redirects, speed, and technical diagnosis.
+- **site-architecture:** location hierarchy, navigation, and internal links.
+- **programmatic-seo:** scaling a justified page pattern backed by real data.
+- **schema:** markup implementation after choosing accurate, public business facts.
+- **ai-seo:** visibility in AI answers when that is part of the request.
+
+## Return a Decision and an Actionable Artifact
+
+For an audit or plan, return:
+
+1. Business model and the specific location/search surface assessed.
+2. Findings with source, date, customer impact, confidence, and missing evidence.
+3. Prioritized changes with a responsible owner and a way to verify completion.
+4. The requested artifact: field edits, citation cleanup table, review drafts, location-page outline, or measurement plan.
+5. Follow-up measures tied to qualified customer actions rather than rankings alone.
+
+For narrow requests, deliver the artifact directly and state only the relevant assumptions. Drafting a plan does not itself authorize profile changes, messages to customers, or directory submissions; follow the user's existing authorization for execution.
+
+## Sources
+
+Check current platform rules when a recommendation depends on them. The references link directly to the relevant Google documentation, including retired Q&A functionality and the distinction between Schema.org validity and Google rich-result eligibility.

package/ai/skills/stacks-marketing-seo-audit/references/rankings-push.md

@@ -0,0 +1,62 @@
+# Rankings Push
+
+Audits find what's broken. This reference covers the next step: moving pages that already rank onto page one, and shipping new pages so they start strong. Both are cheaper than winning a query from nothing, because Google has already decided the site is relevant.
+
+## Find the candidates
+
+From Search Console, pull query + page pairs for the trailing 28 days (compare with the previous period to filter out spikes):
+
+| Bucket | Filter | Fix type |
+|--------|--------|----------|
+| **Striking distance** | Average position 8-20, impressions above a floor that fits the site (often 100+/month) | Content and links |
+| **Weak click-through** | Position 1-5, CTR well below other pages at similar positions | Title and meta description |
+| **Near the top** | Position 4-7 on a revenue query | Content, links, and featured-snippet format |
+
+Prioritize by business value: a position-11 query that drives demos beats a position-9 glossary term with three times the impressions.
+
+Before touching a page, check for **cannibalization**: if two of your pages rank for the same query, positions often bounce between them and neither climbs. Pick one owner, merge the useful parts of the other into it, and redirect.
+
+## Diagnose against the top three
+
+Open the three results above you and write down, for each one, the concrete reason it wins. Usually one of these:
+
+- **Intent match.** They answer the question the searcher is asking; your page answers a neighboring one. A pricing query answered with a features page loses.
+- **A missing section.** They cover a sub-question you skip. The People Also Ask box and the subheadings across the top results show what searchers expect.
+- **Freshness.** Their facts, screenshots, or year are current and yours aren't.
+- **Format.** They have the table, steps, or tool the query calls for.
+- **Links.** They're linked from more, and stronger, pages, inside their site and out.
+
+If you can't name a reason, don't guess with a rewrite. The gap is more likely authority than on-page, and the fix is links (the `backlink-prospecting` loop in `stacks-marketing-loops`) rather than content.
+
+## Make the smallest change that closes the gap
+
+- **Answer the query in the first two sentences**, then expand. This is also the passage AI Overviews and assistants tend to quote.
+- **Add the missing section**, not a rewrite of the whole page. Pages that already rank have signals worth keeping.
+- **Put the query in the title and H1** if it reads naturally. If the title is already aligned, leave it.
+- **Add internal links to the page** from your strongest related pages, with anchor text that describes the target. This is often the biggest single lever and the most neglected.
+- **Refresh what's stale**: facts, screenshots, the year, broken links.
+- **For weak click-through only**, change the title and meta description and nothing else, so the result is attributable. Patterns in [title-tags.md](title-tags.md).
+
+Record the starting position, impressions, and CTR, then wait 3-4 weeks before judging or changing the page again. Rankings take time to settle after an edit, and stacked changes make it impossible to know what worked.
+
+If two rounds move nothing, stop editing. The page is probably limited by intent mismatch (Google wants a different kind of page) or authority, and more on-page work won't fix either.
+
+## Shipping a new page
+
+A new page should launch with everything it needs to be found, so it doesn't spend months as an orphan:
+
+- [ ] Internal links from at least three relevant existing pages, with descriptive anchors
+- [ ] Unique title and meta description matching the target query
+- [ ] One H1, aligned with the title
+- [ ] Self-referencing canonical
+- [ ] Added to the XML sitemap
+- [ ] Structured data where the page type supports it (see `stacks-marketing-schema`)
+- [ ] Main content present in the server-rendered HTML, not only after JavaScript runs
+- [ ] Indexable: no stray `noindex`, not blocked in robots.txt
+- [ ] Linked to the right conversion path (see `stacks-marketing-cro`)
+
+After it ships, request indexing once in Search Console. Requesting again doesn't speed anything up. If the page isn't indexed after a few weeks, check the causes in the Indexation section of the audit instead of resubmitting.
+
+## Run it on a schedule
+
+The striking-distance push loop in `stacks-marketing-loops` runs this weekly with state, cooldowns, and a stop rule. The SEO operator recipe in the same skill combines it with the other SEO loops.

package/ai/skills/stacks-marketing-seo-audit/references/title-tags.md

@@ -0,0 +1,89 @@
+# Title Tags
+
+How to write and audit titles for both rankings and clicks. The title is the strongest on-page relevance signal you control and the first thing a searcher reads, so it has two jobs. It has to match the query, and it has to win the click against nine other results.
+
+## Start from the results page
+
+Search the page's target query before writing. The titles already ranking tell you three things:
+- **The format Google rewards** for this query: lists, guides, tools, product pages, comparisons.
+- **The words searchers expect to see**: modifiers like "best," "free," "template," "vs," a year, a number.
+- **The gap**: what every title promises, and what none of them do.
+
+Match the format, use the expected words, and differentiate on the gap. A how-to title on a query where every result is a tool page loses no matter how well it's written.
+
+## Default structure
+
+```text
+[Primary query] + [what makes this result worth clicking] + [brand, if it helps]
+```
+
+- **Query first.** Put it in the first few words, where both the ranking and the reader's scan start.
+- **Then the reason to click**: a number, a specific outcome, a scope ("for Shopify stores"), freshness, or a format ("free template").
+- **Brand last**, and only where it earns the space. A well-known brand adds clicks; an unknown one mostly adds truncation risk.
+- **About 50-60 characters.** Google truncates by pixel width, not characters, so keep the important words in the first 50.
+
+## Pattern by page type
+
+Pick the page type first, then the pattern. Don't blend two patterns in one title unless the results page does.
+
+| Page type | When | Pattern |
+|-----------|------|---------|
+| Product / feature | Commercial query for what you sell | `[Category] for [Audience] \| [Brand]` |
+| Pricing | "[brand] pricing," "[category] cost" | `[Brand] Pricing: Plans and Costs` |
+| Comparison | "X vs Y" | `[A] vs [B]: [the deciding difference]` |
+| Alternatives | "[competitor] alternatives" | `[N] Best [Competitor] Alternatives ([Year])` |
+| Listicle | "best [things]" | `[N] Best [Things] for [Audience] in [Year]` |
+| How-to | Task query | `How to [Task]` or `How to [Task] Without [Obstacle]` |
+| Definition | "what is [term]" | `What Is [Term]? [Short payoff]` |
+| Guide / pillar | Broad topic | `[Topic]: A Complete Guide for [Audience]` |
+| Template / tool | "[thing] template," "[thing] calculator" | `Free [Thing] [Template/Calculator] ([Format])` |
+| Troubleshooting | Error or problem query | `How to Fix [Problem]` or `[Error]: What It Means and How to Fix It` |
+
+Only use "free," a year, or a number when the page delivers on it. A "2026" title on a page last updated in 2024 is a promise the content breaks.
+
+## Keep the set consistent
+
+- **Title, H1, URL slug, and meta description** should all describe the same topic. They don't need identical wording, but a reader moving from the title to the page should never wonder whether they landed in the right place.
+- **Every title is unique.** Duplicates split relevance and usually mean a template is filling in the same string everywhere.
+- **Don't change slugs** to chase a year or a number. Change the title; leave the URL and its links alone.
+
+## Google rewrites titles
+
+Google replaces the title tag with its own text in a meaningful share of results, usually taking it from the H1 or anchor text. It does this most often when a title is:
+- Much longer than the display width
+- Stuffed with keywords or repeated boilerplate ("| Brand | Brand Blog | Home")
+- Out of line with the page's H1 or content
+- Generic ("Home," "Products," "Untitled")
+
+If Search Console or a live search shows a different title than the one you wrote, treat it as a signal: tighten the title and align it with the H1.
+
+## Fixing low click-through
+
+A page in the top five with a click-through rate well below other pages at the same position has a title or description problem, not a content problem. Compare it to the results around it and rewrite to:
+- State the specific outcome or answer, not the topic
+- Add the qualifier the searcher is filtering for (audience, platform, price, format)
+- Remove words that add length without meaning ("Ultimate," "Complete Guide to the Many...")
+
+Change one page at a time and record the baseline CTR, so a gain is attributable. Allow 3-4 weeks before judging.
+
+## Common fixes
+
+| Problem | Before | After |
+|---------|--------|-------|
+| Says nothing | `Home` | `Invoicing Software for Freelancers \| Acme` |
+| Bloated | `The Ultimate Complete Guide to Everything About Email Deliverability` | `Email Deliverability: 12 Fixes for Inbox Placement` |
+| Wrong page type | `Plans That Grow With You` | `Acme Pricing: Plans and Costs` |
+| Brand first on an unknown brand | `Acme \| Project Management for Agencies` | `Project Management for Agencies \| Acme` |
+| Promise the page breaks | `Free CRM Templates` (one paid template) | `CRM Template for Small Teams (Google Sheets)` |
+
+## Bulk audits
+
+Work from a crawl export (URL, title, H1, length, indexable status) and, if available, Search Console queries per page. Return changes as a table the owner can approve line by line:
+
+```markdown
+| Page | Current title | Proposed title | Reason |
+|------|---------------|----------------|--------|
+| /stacks-marketing-pricing | Plans That Grow With You | Acme Pricing: Plans and Costs | Matches the "acme pricing" query |
+```
+
+Give 2-3 options only for the pages that matter most (top revenue pages, top-5 rankings with weak CTR). For the long tail, one proposal per page keeps the review fast.

package/ai/skills/stacks-marketing-signup/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-signup/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 `signup`, version 2.0.1.
+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.