page-foundry 2.9.1

package/skills/page-foundry/TESTS.md

@@ -0,0 +1,22 @@
+# Regression tests
+
+Run after any skill edit. Each is a prompt plus the behavior that must hold.
+
+1. **Bare invocation.** `/page-foundry` → prints orientation (modes, archetypes, examples), does NOT start the pipeline, ends by asking what to build.
+2. **PRD is not the brief.** Attach a feature PRD, say "build a page for this." → product-marketing.md is still created; interview asks only for what the PRD lacks (buyer language, entry states, traffic source, proof, forbidden claims); no marketing facts invented from the PRD.
+3. **Inferred mode is stated.** "page-foundry for Acme, here's the brief" (no mode) → response includes one line naming the inferred mode and the two alternatives before proceeding.
+4. **Explore stops at the pick.** "explore mode, 4 variants" → 4 genuinely contrasting directions (different axes, not shades of one idea), run halts for selection, no build before the pick.
+5. **Disqualification trap.** Brief includes a segment whose entry state is "things look fine but the adjacent problem exists" → any self-test/demo copy converts the good outcome; gate report shows the red-team read row; a draft that exits that reader fails.
+6. **Voice rules live in voice.md.** Add "fnordify" to scan:banned-phrases, scan copy containing it → FAIL appears; remove it → PASS. Em dash in copy → FAIL while voice-config says fail.
+7. **Non-interactive run.** "build mode, archetype named, brief path given, don't pause" → zero questions asked; spec, page, and gate report delivered together; render gate marked PASS or N/A, never absent.
+8. **Namespaced plugin counts as present.** `copywriting` available only as `marketing:copywriting` through an enabled plugin → preflight reports it PRESENT; zero install commands run. Installing an already-present companion in any location is a failure.
+9. **Ask before install, verify after.** A companion genuinely missing → run reports it with the exact command and asks once; nothing installs before an explicit yes; after yes, detection re-runs and the name must resolve before Phase 0 starts. A silent continue is a failure.
+10. **Outdated is offered, not forced.** `npx skills check` reports a companion outdated → preflight lists it in the outdated column with the update command; update runs only on approval; declining proceeds and is recorded in the gate report.
+11. **Companion stop is non-suppressible.** A companion is missing and the invocation includes "run end to end" (or "don't pause", "no questions"). The run still halts at Phase -1, reports the gap with the install command, and waits for the user's approval in chat; it does not proceed and does not narrate the gap and continue. Those phrases suppress only the spec sign-off. A run that reaches Phase 0 with a companion still missing and unapproved is a failure.
+12. **Autonomy is not inferred.** The user's request does not itself ask to skip pauses, but a standing preference ("don't loop me"), a prior task, or an orchestrator's wrapper supplies "run end to end". The run stays interactive: the companion stop, the Phase 0 interview (no brief file present), and spec sign-off all fire. Treating autonomy the user did not write as consent, or writing "run end to end" into the invocation on the user's behalf, is a failure.
+13. **AI crawlers are not blocked (Gate 6).** A page ships with `robots.txt` that `Disallow`s `ClaudeBot` (or `GPTBot` / `PerplexityBot`) → Gate 6 fails, the run names the blocked crawler, and AI discovery is not marked PASS. Only `CCBot` disallowed is acceptable. An AI-discovery gate that passes while a citation crawler is blocked is a failure.
+14. **Voice scan enforces the expanded AI-slop list.** Copy containing `optimize`, `comprehensive`, or "at its core" → `voice_scan.py` FAILs on each. Confirms the scanner reads the 2.6 additions from voice.md, not just the original list.
+15. **Voice scan catches language patterns, not just words.** Copy containing "it's not just X, it's Y", "serves as a", or "no guessing, no wasted motion" → `voice_scan.py` emits an `AI language pattern` WARN for each (negative parallelism, copula avoidance, tailing negation) even with no banned word present. A page that passes the word list but keeps these patterns is not voice-clean; the Phase 3 pattern pass and the humanizer skill resolve them.
+16. **No fabricated technical artifacts or staged scenarios (Gate 8).** Two ways to fail: (a) a page shows a command, output, or code for something that does not exist or would not run as shown; or (b) a page stages a terminal, screenshot, or UI of an action the user never takes or output they never see, such as a terminal of an internal script the user does not run, even when the underlying command is real. Both fail Gate 8. Real data in a styled card (the page's own gate report) is fine; a reconstructed scenario is not. Same failure class as a fake testimonial.
+18. **Structural pattern detection + humanizer hard-gate.** Copy with a three-verb-clause run ("runs X, gates Y, and hands Z"), or a prose run of 3+ fragments that all open with a present-tense verb ("Finds... Pulls... Structures..."), → `voice_scan.py` emits a WARN (`three parallel verb-clauses` / `parallel-list uniformity`). And Gate 2 does not pass on the scanner alone: the humanizer must be invoked on the final copy and recorded on the gate report's `humanizer` line. A page that passes the scanner but shows uniform parallel structure the humanizer never saw is an incomplete Gate 2, not a clean one.
+17. **Companions are invoked as primary; fallbacks are flagged.** Companions present → each phase invokes its companion and uses its output (product-marketing builds the brief, customer-research and marketing-psychology drive the message architecture, cro structures the spec and scores the conversion audit, copywriting and copy-editing produce the copy, frontend-design and web-design-guidelines drive design), not the reference files. A companion missing → that phase runs on the reference-file fallback, tells the user, and the gate report and run log mark the phase degraded with the missing companion named. Silently doing a companion's work while the companion is available, or running degraded without saying so, is a failure.

package/skills/page-foundry/assets/brief-template.md

@@ -0,0 +1,50 @@
+# Product Marketing Brief: {Product Name}
+
+Phase 0 output. Lives at `.agents/product-marketing.md` in the product's repo (or beside the page output). Every downstream phase reads this file; keep it current. Compatible with the coreyhaines31/marketingskills `product-marketing` context format.
+
+## Product
+
+- **Name:**
+- **One-line factual description:** (what it is, no adjectives)
+- **Type:** oss-project / saas-homepage / campaign-landing / mobile-app
+- **Status:** (live, beta, prelaunch, waitlist)
+- **URL / repo:**
+- **Property / brand it belongs to:** (which theme tokens apply)
+
+## Buyer / user
+
+- **Primary audience:** (role, situation, technical level)
+- **The trigger:** (what just happened in their life/work that sends them looking)
+- **Their words for the problem:** (verbatim phrases from real conversations, reviews, threads; mark guesses as guesses)
+- **Current alternatives:** (including "spreadsheet" and "do nothing")
+- **Entry states:** (per segment, every starting situation a qualified buyer can be in when they hit the page, including the good ones; copy must convert each. E.g., problem is acute / problem is invisible to them / partial solution in place / things look fine but the adjacent problem exists)
+
+## Offer
+
+- **Primary conversion action:** (the one thing the page exists to cause)
+- **What they get:** (itemized for paid offers)
+- **Pricing model:** (price, tier, trial, license; or "undecided")
+- **Risk reversal:** (guarantee, refund terms, free tier; or "none yet")
+- **Real urgency:** (actual deadline/cap, or "none"; never fabricate)
+
+## Differentiation
+
+- **The mechanism:** (why this works where alternatives fail; the thing only this product/method does)
+- **Honest tradeoffs:** (what alternatives do better; will be conceded on comparison sections)
+
+## Proof inventory
+
+List only what is real. Mark gaps as `[TK: what to collect]`.
+
+- **Testimonials/quotes:** (name, role, exact words, permission status)
+- **Numbers:** (users, downloads, stars, results, years)
+- **Named adopters / logos:** (permission status)
+- **Credentials:** (the builder's relevant background, certifications, history)
+- **Artifacts:** (screenshots, sample reports, demo recordings available)
+
+## Constraints
+
+- **Traffic source(s) for this page:** (organic, specific ad campaign, newsletter, conference)
+- **Claims we cannot make:** (legal, compliance, NDA, modesty)
+- **Existing brand assets:** (logo, fonts, palette, prior pages to stay consistent with)
+- **Deploy target:** (static host, existing site, framework constraints)

package/skills/page-foundry/references/archetypes.md

@@ -0,0 +1,197 @@
+# Page Archetypes
+
+Pick exactly one archetype per page. The archetype fixes section order, CTA policy, navigation policy, and proof placement. Deviate only when the user asks, and record the deviation in the page spec.
+
+## Archetype mapper
+
+Current archetypes: `oss-project`, `saas-homepage`, `campaign-landing`, `mobile-app`, `course-sales`, `membership-community`, `newsletter-capture`, `personal-home`.
+
+When the right archetype is not obvious, ask (or infer from the brief) three questions:
+
+1. **What is the conversion?** Install/star → oss-project. Trial/demo → saas-homepage. One-time purchase of a defined offer → campaign-landing or course-sales. Recurring subscription to people + content → membership-community. Email address → newsletter-capture. Store install → mobile-app. "Know who I am, then one action" → personal-home.
+2. **Is the relationship one-time or ongoing?** One-time purchases sell a transformation with an endpoint (course-sales, campaign-landing). Ongoing subscriptions sell a living thing and must prove it is alive (membership-community, saas-homepage, newsletter-capture).
+3. **Where does the traffic come from?** A single controlled source with one intent pushes toward campaign-landing structure (no nav, message match binding) regardless of what is being sold. Mixed/organic traffic pushes toward homepage structure (nav, fuller story).
+
+**Composition rules.** When a page straddles two archetypes, take the structure (section order, nav and CTA policy) from the archetype matching the CONVERSION, and borrow individual sections from the other. Examples: a paid workshop sold from one ad campaign = campaign-landing structure + the curriculum and instructor sections from course-sales. A paid newsletter = newsletter-capture structure + the pricing and what-you-get sections from membership-community. Record every borrowed section and deviation in the page spec so the gates audit the right rules.
+
+**Nothing fits.** Build a custom spec from the shared rules below plus the conversion rules file, state explicitly that the page is off-archetype, and consider adding the new archetype to this file afterward using the same format (audience, conversion goal, numbered sections, nav policy).
+
+Shared rules for every archetype:
+
+- The hero must pass the 5-second test: what it is, who it is for, what to do next, readable in five seconds by someone who has never heard of the product.
+- One primary CTA per page. It may repeat down the page, but it is the same action every time. Secondary actions are visually quiet (text links, ghost buttons).
+- Proof lives next to the claim it supports, and within one viewport of every CTA instance.
+- Sections appear in the order a skeptical reader raises objections, not the order the builder is proud of features.
+
+---
+
+## oss-project
+
+For open source tools, libraries, and self-hostable software. The reader is a practitioner deciding whether to try it in the next ten minutes.
+
+Conversion goal: install, star, or read the docs. Pick one as primary.
+
+1. **Hero.** Plain statement of what it does and for whom. Install command in a copy-button code block directly in the hero; for a practitioner audience the install command IS the CTA. Version, license, and star badges adjacent. No marketing adjectives.
+2. **Proof strip.** Stars, downloads, named adopters, "as seen in" only if real. Cut the section entirely if proof is thin; an empty proof strip on an OSS page reads as desperation.
+3. **Quickstart.** From zero to first useful output in the fewest visible steps. Real commands, real output. If the quickstart needs more than one screen, the product has an onboarding problem the page cannot fix.
+4. **How it works / architecture.** One diagram or terse section for the reader evaluating trust and fit. For security tooling, this is where threat model and data handling live. Plain statements only.
+5. **Comparison.** Honest table or prose against the 2 or 3 alternatives the reader is already considering. Concede real tradeoffs; conceded weaknesses buy credibility for the claimed strengths.
+6. **Community and contribution.** Where discussion happens, how to contribute, who maintains it, release cadence. Maintenance signals are a primary trust factor for OSS adoption.
+7. **Footer CTA.** Repeat the install command. Link docs, repo, license, security policy (`SECURITY.md` link if it exists).
+
+Navigation: minimal and allowed (Docs, GitHub, Community). Tone: terse, technical, zero hype. The brutalist/terminal aesthetic direction (see design-direction.md) is a natural fit but not mandatory.
+
+---
+
+## saas-homepage
+
+For web apps and SaaS products. The homepage serves mixed intent (cold, evaluating, returning), so it gets navigation and a fuller story than a campaign page.
+
+Conversion goal: trial signup, demo booking, or waitlist. Pick one as primary.
+
+1. **Hero.** Outcome-first headline within the length budget (see conversion-rules.md), subhead naming who it is for and the mechanism, single primary CTA, and a product visual that shows the actual product doing the actual thing. No abstract illustrations of people pointing at charts.
+2. **Social proof strip.** Logos, named users, a hard number. Directly under the hero so the first scroll lands on proof.
+3. **Problem.** Name the pain in the buyer's own words (pull phrasing from Phase 1 research). One short section; agitate honestly, do not melodramatize.
+4. **Solution / feature storytelling.** 3 to 5 capability blocks, each framed as outcome first, mechanism second, each with a real screenshot or short clip. A bento grid works well here when capabilities differ in weight (see design-direction.md); a linear sequence works when they form a workflow.
+5. **How it works.** Three steps, numbered only because it genuinely is a sequence. Kills the "this looks complicated" objection.
+6. **Deep proof.** One or two full testimonials with name, role, and a specific result. Specific beats voluminous; one quote with a number outranks six adjectives.
+7. **Pricing teaser or transparent pricing.** At minimum, the model (free tier? trial? starting price?). Hiding pricing entirely is a known objection generator for self-serve products. Use the pricing skill if packaging is undecided.
+8. **Objections / FAQ.** Work directly from the Phase 1 objection map. Security, data handling, migration, lock-in. Real answers, not reassurance noise.
+9. **Final CTA.** Restate the primary outcome in one line, repeat the primary CTA, optionally pair with the lowest-friction secondary (docs, changelog).
+
+Navigation: yes, standard. Footer: full.
+
+**Optional sections** (add when they carry a real buying factor, do not pad): an **integrations / works-with-your-stack** strip (real logos of the tools it connects to) placed after feature storytelling, since "does it fit my stack" is a common SaaS objection; and a **built-for / use cases** self-identification block ("For marketers who...", "For engineers who...") when the product serves distinct personas who need to see themselves.
+
+**Sales-led / enterprise variant.** For a B2B page aimed at a buying committee rather than self-serve, compose saas-homepage with: use-cases by role or department, a dedicated **security and compliance** section (not folded into the FAQ), the integrations strip, and an **ROI / value** section; replace the pricing teaser with "talk to sales" only when pricing is genuinely quote-based, and make the primary CTA a demo or contact rather than a trial. Record the variant and every borrowed section in the spec so the gates audit the right rules.
+
+---
+
+## campaign-landing
+
+For dedicated landing pages and long-form sales pages: paid traffic, launch pages, workshop and course offers, lead magnets. One traffic source, one intent, one action.
+
+Conversion goal: the single conversion the campaign exists for.
+
+Structural rules that differ from the homepage:
+
+- **No site navigation.** No header menu, no footer link farm. Every exit path competes with the CTA.
+- **Message match is binding.** The hero headline must use the same language as the ad, post, or email that sent the reader. If the source says "stop getting passed over for promotions", the page does not open with "career acceleration platform".
+- **The CTA repeats** after every major proof or objection block, identical wording each time.
+
+Section sequence (long-form sales structure; compress for simple lead magnets):
+
+1. **Hook.** The promise or the pain, in source-matched language. Subhead stakes the claim.
+2. **Problem and stakes.** What it costs the reader to leave this unsolved. Specific, honest, written from inside their situation.
+3. **Failed alternatives.** What they have already tried and why it did not work. This is where the reader decides you understand them.
+4. **The mechanism.** Why this works when those did not. The unique method, named. (For offers like workshops and coaching, the mechanism is the methodology, not the person's resume.)
+5. **Demonstration.** Show it working: walkthrough, curriculum, sample, before/after. Concrete artifacts beat descriptions.
+6. **Proof.** Testimonials with names and outcomes, case results, credentials. Place the heaviest proof immediately before the offer.
+7. **The offer.** Exactly what they get, itemized, with the price framed against the cost of the problem. No fake strikethrough pricing.
+8. **Risk reversal.** Guarantee, refund terms, or "what happens after you click". Reduce anxiety at the moment of commitment.
+9. **Honest urgency.** Real deadlines, real cohort caps, or nothing. Fabricated scarcity fails the integrity gate.
+10. **FAQ.** The final objections, including the awkward ones (time commitment, refunds, "is this for me if...").
+11. **Final CTA block.** Promise, proof element, button.
+
+Forms: minimum viable fields (3 is the baseline; 4 to 6 costs roughly 10 to 25 percent of completions, 7 or more costs 25 to 50 percent). Every field added must justify itself against the conversion data in conversion-rules.md; past a few fields, prefer a multi-step form with a progress indicator.
+
+---
+
+## mobile-app
+
+For iOS/Android apps. The page's job is to bridge to the store listing, and to serve desktop visitors who cannot install right now.
+
+Conversion goal: store install (mobile visitors) or send-to-phone (desktop visitors).
+
+1. **Hero.** What the app does and for whom, store badges (App Store / Google Play) above the fold, device-framed screenshot or short screen recording of the core loop. On desktop viewports, add a QR code next to the badges.
+2. **Ratings proof.** Star rating and review count if creditable; pull one or two short review quotes (real ones, attributed as the store displays them).
+3. **Core loop in screens.** 3 or 4 screenshot-led blocks walking the primary use case. Captions in outcome language. Keep copy aligned with the ASO keyword set (use the aso skill if installed) so the page and the listing reinforce each other.
+4. **Differentiator block.** The one thing competing apps in the category do not do. For privacy-forward apps, the privacy posture goes here, stated plainly: what is collected, what is not, where data lives.
+5. **Platform and requirements.** OS versions, offline behavior, account requirements, price/IAP model. Answering this on the page prevents store-page bounce.
+6. **Final CTA.** Badges and QR again, one line restating the outcome.
+
+Navigation: minimal (Support, Privacy). Keep total page weight very low; most traffic is mobile.
+
+---
+
+## course-sales
+
+For courses, workshops, cohorts, and other paid training with a defined start and end. The reader is buying a transformation, not a curriculum; pages that describe the course lose to pages that sell the outcome.
+
+Conversion goal: enrollment (or application, for high-ticket cohorts).
+
+Length scales with price: under roughly $200, a focused page converts; above roughly $500, buyers expect a full long-form treatment with a detailed curriculum breakdown. Well-built course pages convert in the 5 to 15 percent range from warm traffic; cold-traffic expectations are far lower.
+
+1. **Hero.** The transformation, named, with the timeframe if honest ("from overlooked to short-listed in eight weeks" beats "an 8-module career course"). Who it is for. Primary CTA. Next cohort date if cohort-based.
+2. **The gap.** Where the reader is now versus where they want to be, in their words, and why effort alone has not closed it. This is the problem section reframed for education: the obstacle is usually missing structure or missing feedback, not missing motivation.
+3. **Why existing paths fail.** Free YouTube, certifications that did not move the needle, generic advice. Concede what those are good for; position the course against their real gaps.
+4. **The method.** The named mechanism that produces the transformation. For an instructor with deep field history, the method carries the credibility; the resume supports it, not the reverse.
+5. **Curriculum as outcomes.** Module-by-module, framed as "after this module you can X", not lesson counts and video minutes. Include format logistics: live vs recorded, duration, time commitment per week, tools required.
+6. **Instructor.** Short, proof-dense, written in third person or first consistently. Years, named employers/clients within what can be said, student results.
+7. **Student results.** The heaviest proof on the page, placed immediately before the offer. Named testimonials with specific outcomes; video testimonials when available. `[TK]` and cut if none exist yet; first-cohort pages substitute the instructor's own results and a founding-cohort framing.
+8. **The offer.** Everything included, itemized (modules, calls, community access, templates, recordings), with the price framed against the cost of staying stuck. Payment plans materially lift conversion for prices above a few hundred dollars; offer one when economics allow.
+9. **Guarantee.** 30 days is the floor expectation; longer signals confidence. State the exact terms. High-ticket application-based offers may replace the guarantee with the application itself as risk filter; say so plainly.
+10. **Honest urgency.** Cohort start dates and real seat caps are legitimate urgency; use them. Evergreen self-paced courses skip this section rather than faking it.
+11. **FAQ.** Time commitment, prerequisites, refund terms, "what if I fall behind", "is this for me if [edge case]".
+12. **Final CTA block.** Transformation restated, strongest single proof element, button.
+
+Navigation: none (treat as campaign-landing). Forms: enrollment goes straight to checkout; applications ask the minimum to qualify.
+
+---
+
+## membership-community
+
+For paid communities, memberships, and subscription groups (Skool, Circle, Discord-based, or self-hosted). The product is access to people plus ongoing material; the page must prove the thing is alive, because the reader's core fear is paying for a ghost town.
+
+Conversion goal: join (or join waitlist / apply, for curated communities).
+
+1. **Hero.** Who gathers here and what membership changes for them. Member count and activity only if creditable. Primary CTA.
+2. **Who it is for, who it is not for.** An explicit not-for list (wrong stage, wrong goals, wrong expectations) qualifies buyers, reduces churn, and reads as confidence. This section earns more trust than any superlative could.
+3. **Inside the community.** Real screenshots of real threads, wins, and calls (redact member details as needed). Show the artifact, not an illustration of "community". A short screen recording of scrolling the feed outperforms any copy here.
+4. **What membership includes.** Itemized: the community itself, calls and their cadence, courses or classroom content, templates, events, direct access to the founder and at what level. Be precise about cadence; "monthly calls" is a promise the page is making.
+5. **The founder.** Why this person's room is worth being in: field history, what they share inside, how present they actually are. Presence claims must be honest; "I answer every post" is verifiable by members within a week.
+6. **Member outcomes.** Named member wins with specifics (the role landed, the raise, the first client). Place before pricing.
+7. **Pricing.** Monthly and/or annual, what each includes, founding-member pricing only if real and time-bound. Cancel-anytime stated plainly; for recurring offers, ease of leaving is a buying factor.
+8. **FAQ.** Time required to get value, lurker-friendliness, refund/cancel mechanics, platform logistics, privacy of what members post.
+9. **Final CTA.** One line on what changes the week they join, button.
+
+Navigation: none or minimal. Integrity note: activity proof must be current; a screenshot of a busy week eight months ago fails the integrity gate if the room has gone quiet.
+
+---
+
+## newsletter-capture
+
+For mailing list and newsletter signups, free or as the top of a paid funnel. The entire page exists to make one exchange feel obviously worth it: an email address for a specific, recurring value.
+
+Conversion goal: email signup. Dedicated newsletter pages convert dramatically better than embedded forms; double-digit rates are achievable with matched traffic.
+
+1. **Hero.** What the reader gets, how often, and who it is for, in one or two lines ("One exploitable misconfiguration, every Tuesday, for people who defend networks"). Email field plus button directly in the hero; the form IS the page. Single field only: email. Every additional field costs signups.
+2. **What is inside.** Three or four concrete bullets of the kind of thing a subscriber receives, written as specifically as the actual issues. Frequency and length expectations stated ("5 minutes, weekly") because inbox anxiety is the real objection.
+3. **Proof.** Subscriber count when creditable, reader quotes, recognizable readers or "read by people at X" only when real. A link to one or two best past issues is the strongest proof available: let them taste it.
+4. **About the writer.** Two or three lines; why this person's signal is worth inbox space.
+5. **Final form.** Repeat the field and button with the promise restated. State the privacy position in one line (no sharing, unsubscribe anytime).
+
+After signup, the confirmation/thank-you page is part of this archetype's spec: deliver something immediately (best-issue links or the promised lead magnet) and set expectations for what arrives when.
+
+Navigation: none. Total page weight: minimal; this page gets linked from everywhere.
+
+---
+
+## personal-home
+
+For a person: consultant, builder, speaker, writer. The reader arrived from a talk, a post, a podcast, or a search of the name, and is answering one question: is this person worth my next ten minutes, and what do I do with that interest?
+
+Conversion goal: one primary next action. Pick it deliberately: book a call, subscribe, read the work, or follow. Everything else is secondary.
+
+1. **Hero.** Name, and one positioning line that says who you help do what ("I help overlooked security engineers get paid like the people they outperform"). Not a job title list. Primary CTA.
+2. **Proof of work.** Selected, not exhaustive: 3 to 6 items spanning the work that matters now (projects, companies served, talks, things built, things written). Each item links somewhere real. Curate ruthlessly; a personal page is a portfolio of judgment.
+3. **Current focus.** What you are building or taking on now, which doubles as qualification for inbound ("currently advising X kind of company on Y").
+4. **Credibility narrative.** A short bio in the owner's actual voice, written like a person and not a LinkedIn summary. Years, the arc, the unusual parts. First or third person, consistently.
+5. **Routes.** The two or three standing offers: work with me, join the community, read the newsletter. Each one line plus link; the primary CTA visually leads.
+6. **Contact.** Direct and simple. State response expectations honestly.
+
+Navigation: minimal (Work, Writing, Contact). This archetype tolerates the most aesthetic risk on the whole list; the page is the person, and a distinctive direction (see design-direction.md) does more work here than anywhere else.
+
+---
+
+_Provenance: reconciled 2026-07-07 against marketingskills 2.3.0 (copywriting page templates, cro, product-marketing). The archetype structures are page-foundry's own opinionated superset; the integrations, built-for, and enterprise/B2B patterns were added from copywriting's copy-frameworks. Re-reconcile when those companions change._

package/skills/page-foundry/references/conversion-rules.md

@@ -0,0 +1,70 @@
+# Conversion Rules
+
+These are the load-bearing rules, with the evidence behind them so future edits do not casually break them. Benchmarks refreshed 2026-07 from published landing-page and form-conversion datasets; treat them as directional, and re-source with a web search if this file is more than a year old.
+
+## Context: what the numbers say
+
+- Median landing pages convert around 4 to 6 percent across industries in 2026; business pages run higher (low double digits), consumer pages around 10 percent. The gap is explained almost entirely by intent matching, clarity, and form design, not by visual novelty.
+- A single primary CTA converts about 32 percent better than competing CTAs: roughly 13.5 percent for one action, 11.9 percent for two, 10.5 percent for three or more, in dedicated landing page datasets. On short pages keep the one CTA above the fold; on long-form pages with a complex offer, repeat the same primary CTA at intervals rather than adding competing ones.
+- Heroes with a clear above-the-fold value proposition outperform clever or ambiguous messaging by 35 to 40 percent.
+- Removing navigation and secondary CTAs from dedicated landing pages can roughly double conversion.
+- Roughly 83 percent of landing page visits are mobile; desktop converts better (mobile lands near 58 percent of the desktop rate), so design mobile-first and measure both.
+- Form length is a lever: completion runs about 23 percent at 3 fields, 17 percent at 5, 11 percent at 7, and 7 percent at 10 or more; cutting from 4 fields to 2 roughly doubles completion. A multi-step form with conditional logic and a progress indicator captures the same qualification data at roughly double the rate of an 11-field single page. On mobile, 62 percent of form abandonments cite complexity.
+- Pages need to be interactive in about 2 seconds; slow mobile loads cost roughly 20 percent of conversions.
+
+## Hard rules
+
+Apply these in Phase 2 (spec) and verify them in Phase 6 (gates).
+
+1. **5-second test.** A cold reader must extract: what it is, who it is for, what to do next, within five seconds of the hero rendering. Test by reading only the headline, subhead, and CTA label, nothing else.
+2. **Headline budget.** Primary headline targets under about 44 characters; hard ceiling 70. If the value proposition cannot fit, the positioning is unfinished; go back to Phase 1 rather than padding the subhead.
+3. **One primary CTA.** One action, one verb-first specific label ("Start free scan", not "Get started"; "Get the checklist", not "Submit"). It may repeat; it may not compete. Secondary actions are visually subordinate.
+4. **Proof adjacency.** Every CTA instance has a proof element (testimonial, number, logo row, rating) within one viewport. Claims and the evidence for them sit together, never in separate sections the reader must connect on their own.
+5. **Message match.** For campaign-landing pages, hero language mirrors the traffic source's language. For homepages, hero language mirrors the buyer's own words from research, not internal product vocabulary.
+6. **Intent isolation.** One page, one intent. Brand, competitor-comparison, problem, and product intents each get their own page rather than one page hedging across all of them.
+7. **Form friction.** Ask only for what the next step in the funnel actually requires; every field beyond name and email needs a stated justification in the spec. Field count is the lever (3 fields is the baseline, 4 to 6 costs roughly 10 to 25 percent of completions, 7 or more costs 25 to 50 percent). Keep labels visible (placeholder-only labels vanish on focus and fail accessibility), validate on field-exit and preserve typed input on error, use a single column, and give inputs 44px touch targets. Past a few fields, a multi-step form with a progress indicator beats one long page.
+8. **Mobile-first ordering.** The section order must work as a single column. Proof cannot live only in a sidebar; the mobile reader must hit proof before the form.
+9. **Specificity beats cleverness.** Numbers, named outcomes, and concrete nouns outperform wordplay. If a line is clever but vague, replace it.
+10. **No premature disqualification.** Any self-test, demo, quiz, or "see for yourself" device must convert every outcome a qualified buyer can experience, including the good one. Map each possible outcome to a next step before the section ships; if a qualified reader can land on an outcome that reads as "not for you," the section is wrong. The same applies to problem framing: never describe the problem so narrowly that a buyer with the adjacent problem self-selects out.
+11. **Answer the standing objections inline.** Most pages face four recurring objections; answer each next to where it arises, not only in a catch-all FAQ. Price and value (frame the cost against the cost of the problem; itemize what is included). "Will this work for my situation?" (specific proof, named use cases, or an explicit not-for list). Implementation difficulty (a concrete how-it-works and a time-to-value). "What if it does not work?" (guarantee, refund terms, or what-happens-after-you-click). An FAQ collects the leftovers; it does not replace answering the load-bearing objections in place.
+
+## MECLABS Conversion Sequence audit
+
+Score the finished page with the MECLABS heuristic before shipping:
+
+C = 4M + 3V + 2(I - F) - 2A
+
+Score each factor 1 to 5:
+
+- **M, motivation match (weight 4).** How well the page matches the visitor's intent and urgency at arrival. Driven by traffic source alignment and problem framing. The page cannot create motivation, only match it; this is why message match is rule 5.
+- **V, value proposition clarity (weight 3).** Would the ideal prospect, after the hero plus one scroll, be able to say why to buy from here rather than the alternative? Specific, exclusive, credible claims score high.
+- **I, incentive (weight 2).** What the visitor gets for acting now: trial, sample, lead magnet, bonus. Honest only.
+- **F, friction (weight 2, subtracted from I).** Form length, page length mismatched to decision weight, confusing navigation, slow load.
+- **A, anxiety (weight 2, negative).** Unanswered risk at the moment of action: price surprise, data concerns, "what happens after I click", missing refund terms. Risk reversal and proof near the CTA reduce A.
+
+Record the per-factor scores and the computed C in the gate report. There is no absolute pass threshold; the value is in the diagnosis. Flag direction differs by factor: M, V, and I flag at 1 or 2 (low is bad); F and A flag at 4 or 5 (high is bad). Any flagged factor must be addressed or explicitly accepted by the user before ship.
+
+## Pricing psychology
+
+For archetypes with a pricing block (saas-homepage, course-sales, membership-community, and campaign-landing offers), apply these levers, honestly:
+
+- **Anchor before the ask.** Show the higher tier or the cost-of-the-problem first, so the target price reads as reasonable against it.
+- **Three tiers, guide the choice.** Good-better-best with the recommended tier visually marked reduces choice paralysis; a genuinely weaker decoy tier steers toward the target. The tiers must be real.
+- **Price relativity and framing.** State the price against a reference the buyer already accepts (per day, per seat, versus the manual alternative). "$1 a day" and "$30 a month" are the same number and convert differently.
+- **Charm versus round.** Prices ending in 9 test better for value-driven offers; round prices read as premium. Match the ending to the positioning instead of defaulting.
+- **Rule of 100.** Under about $100 a percentage discount looks bigger; over it, an absolute dollar amount looks bigger. Frame the discount accordingly.
+
+Never fake a strikethrough, a decoy tier that does not exist, or scarcity. Honest levers only; the integrity gate enforces this.
+
+## Anti-patterns to reject on sight
+
+- Hero carousel or rotating headlines (nobody waits for slide two).
+- Two equally-weighted hero buttons ("Start trial" next to "Book demo" splits intent; pick the primary, demote the other).
+- Stock photography of people at laptops; testimonial sections with no names; "trusted by industry leaders" with no logos.
+- Walls of feature bullets with no outcomes attached.
+- Popup on entry. Exit-intent or scroll-depth triggers only, and only when the user asks for popups at all.
+- Fake countdown timers, fake "3 spots left", fake strikethrough prices. These also fail the integrity gate.
+
+---
+
+_Provenance: reconciled 2026-07-07 against marketingskills 2.3.0 (cro, marketing-psychology; form mechanics from cro/references/form.md). Benchmarks re-sourced 2026-07 from published landing-page and form-conversion datasets. The MECLABS Conversion Sequence heuristic is external and not part of those companions. Re-source the benchmark block when it is more than a year old._

package/skills/page-foundry/references/design-direction.md

@@ -0,0 +1,48 @@
+# Design Direction
+
+The design phase has one job: make a page that could only belong to this property. Mechanics of the design process live in the frontend-design skill when installed (token plan, critique against the generic default, one signature element, restraint everywhere else); this file adds the marketing-page-specific and property-specific layer on top. Trend references are directional and dated 2026-07; re-check the design landscape if this file is more than a year old.
+
+## One property, one theme
+
+Each property (each product, each brand under the holding company) gets exactly one token set: 4 to 6 named palette colors, a display/body type pairing, spacing scale, radius and border conventions, and the signature element. Persist it as `theme.css` with custom properties; use theme-factory when installed to generate or apply a cohesive palette and type pairing, but `theme.css` is the durable per-property token store (theme-factory is a theming toolkit for artifacts, not a persistence layer). Every subsequent page for that property reuses the tokens unchanged. Distinctiveness between properties, consistency within one.
+
+## Choosing a direction
+
+Derive the direction from the subject and the audience, not from a trend list. Current directions that are working, and where each fits:
+
+- **Modern minimalism, performance-aware.** Generous space, disciplined type scale, restrained motion. The default for consulting, advisory, and coaching properties where the brand is judgment and experience. Minimalism done as precision, not emptiness.
+- **Bento grids for feature storytelling.** Modular tiles of varying weight; now standard on SaaS feature sections (a large majority of top SaaS sites use a variant). Use when capabilities genuinely differ in importance; the grid encodes hierarchy. Do not use for linear workflows or long-form sales pages. Bento is also now common enough that it cannot be the distinctive element on its own.
+- **Brutalist / terminal aesthetic.** Monospace, raw layout, visible structure, minimal color. A live counter-trend to polished bento, common among indie and developer-facing launches, and it reads as honest to a practitioner audience. Natural fit for OSS and security tooling pages. The risk is costume-brutalism; commit fully or not at all.
+- **Dark mode as identity.** Works for security and developer tools; pair with one disciplined accent. If the property's product UI is dark, the marketing page matching it builds continuity.
+- **Glassmorphism, kinetic type, scroll-driven animation.** Moments, not systems. One scroll-triggered reveal that serves the message outranks ambient motion everywhere. Heavy 3D and WebGL routinely blow the performance budget; treat as out of bounds unless the user insists and accepts the cost.
+
+## Anti-slop list
+
+Reject these defaults regardless of direction (this extends the frontend-design skill's list with marketing-page specifics):
+
+- Purple-to-blue gradient on anything.
+- The big-stat-number + small-label + gradient-accent hero (the frontend-design template answer); use it only when the metric genuinely is the claim.
+- Inter (or any default sans) as the display face with no stated reason.
+- Three-column icon-card feature grids with line icons and centered text.
+- The cream background + serif display + terracotta accent combo, the near-black + acid green (or vermilion) combo, and the hairline-rule broadsheet look, when chosen by default rather than for cause.
+- Uniform border radius on every element; identical card shadows everywhere.
+- Abstract blob illustrations, isometric people, stock photos of meetings.
+- Emoji as section markers.
+- AI-generated hero imagery that depicts nothing real about the product. Real screenshots, real terminal output, real diagrams, real photography only.
+- Any staged reconstruction of the product in use: a hand-built terminal, a mocked screenshot, or a console showing output that was not actually produced, or that shows an action the user never takes (an internal script the pipeline runs, not the user). This is a fabrication even when it looks real and the underlying command exists; it fails the integrity gate. Show a real artifact of real use (the actual page it built, a real screenshot of a real property, the output the user actually receives), or describe the thing in words. Real data in a clearly-labeled card (a real gate report) is fine; a reenactment is not.
+
+## Marketing-page specifics
+
+When web-design-guidelines is installed it is authoritative on the accessibility, typography, imagery, and interaction mechanics below; the items here are the marketing-page emphasis. When it is absent, these condensed mechanics apply.
+
+- The hero visual shows the product doing its job: actual UI, actual output, actual artifact. If the product is a service or community, show the real artifact of the work (a redacted report page, a session board, a member thread) rather than a metaphor.
+- Design the 390px view first. Hero type must wrap gracefully (use `text-wrap: balance` on the headline to kill widows); the CTA must sit above the fold on a phone; respect `env(safe-area-inset-*)` so nothing hides under a notch, and set `touch-action: manipulation` on tap targets.
+- Every interactive element has a visible focus state (`:focus-visible` with a real ring, never `outline: none` without a replacement) and a hover state; interactive states increase contrast and never rely on color alone.
+- Images carry explicit `width`/`height` to hold layout (CLS), lazy-load below the fold, and set `fetchpriority="high"` on the hero image (LCP). This ties straight to the performance budget below.
+- Respect `prefers-reduced-motion` with a static fallback. Animate only `transform` and `opacity`, never `transition: all`; keep animations interruptible and set an explicit `transform-origin`.
+- Contrast meets WCAG 2.2 AA (4.5:1 body, 3:1 large text and UI components) inside the chosen palette from the start, not patched after. Set `color-scheme` and a `theme-color` meta when the property has a dark identity.
+- Performance is a design constraint: the direction must be achievable in roughly under 200KB of CSS+JS and under 1MB total transfer for the page. If the vision needs more, change the vision.
+
+---
+
+_Provenance: reconciled 2026-07-07 against frontend-design (Anthropic), web-design-guidelines (vercel-labs, live ruleset), and theme-factory (Anthropic). web-design-guidelines is authoritative on the a11y/typography/imagery/interaction mechanics when installed; the condensed mechanics here are the fallback. Re-reconcile when those companions change._

package/skills/page-foundry/references/handoff.md

@@ -0,0 +1,82 @@
+# Handoff Mode: Claude Design Package
+
+Handoff mode produces everything a design tool needs to build a 10/10 page, with the thinking, copy, and constraints already done. The primary target is Claude Design (Anthropic Labs); the package also works for any designer or design tool.
+
+What matters about Claude Design for this package: it accepts plain text prompts, screenshots and image assets, DOCX/PPTX/XLSX documents, codebases, and web captures; it can build a persistent design system from brand sources (palette, type scale, components, layout patterns); it outputs deployable HTML/CSS/JS and can hand off to Claude Code; and it does NOT retain brand context across separate conversations, so the package must be fully self-contained and re-pasteable every session.
+
+## Package contents
+
+Write to `handoff/<product>/`:
+
+```
+handoff/<product>/
+├── 00-master-prompt.md      The paste-ready prompt; references the other files
+├── 01-copy.md               Final copy, verbatim, in page order
+├── 02-page-spec.md          The Phase 2 spec (sections, claims, proof, CTAs)
+├── 03-design-direction.md   Tokens, direction, anti-slop list, asset manifest
+├── 04-acceptance-criteria.md Gates rewritten as testable acceptance criteria
+└── assets/                  Logos, screenshots, theme.css, reference captures
+```
+
+### 00-master-prompt.md
+
+The single document pasted into Claude Design (attach the rest as files). Structure:
+
+1. One paragraph: product, audience, archetype, the page's single job.
+2. Instruction block, verbatim rules for the design tool:
+   - "The copy in 01-copy.md is final. Use it verbatim. Do not paraphrase, shorten, expand, or 'improve' any sentence. If a layout needs shorter text, flag it; do not rewrite."
+   - "Follow the section order in 02-page-spec.md exactly. Do not add, merge, or reorder sections."
+   - "Use the tokens in 03-design-direction.md (and attached theme.css if present) as the design system. Do not introduce new palette colors or typefaces."
+   - "Build to the acceptance criteria in 04-acceptance-criteria.md. Treat them as the definition of done."
+3. The signature element description and any motion notes from Phase 4.
+4. What to ask about instead of guessing (unresolved [TK] items, image slots without assets).
+
+The verbatim-copy rule exists because the voice gate ran BEFORE handoff; any downstream paraphrase silently un-passes it. This is the most commonly violated instruction, so it goes first and is repeated next to the copy itself.
+
+### 01-copy.md
+
+Final copy in page order, one block per spec section, each labeled with the spec section number and the element roles:
+
+```
+## Section 3: Quickstart  [spec §3]
+H2: Up and running in two minutes
+Body: ...
+CTA button: Copy install command
+```
+
+Header note, repeated from the master prompt: "This copy is final and voice-gated. Verbatim use only." Image slots are marked `[IMAGE: description, asset filename or TK]`.
+
+### 02-page-spec.md
+
+The Phase 2 output as-is: numbered sections with purpose, claim carried, proof element, CTA treatment, plus nav policy and archetype name. Include the mobile ordering note: the spec order is the single-column order.
+
+### 03-design-direction.md
+
+- Token set: named palette hex values, type pairing and scale, spacing, radius/border conventions. Attach `theme.css` in assets/ when it exists; for an existing brand, attach real captures or screenshots of current properties so Claude Design can extract the system itself (it is good at this; give it sources rather than descriptions when possible).
+- The chosen direction in two or three sentences, plus the signature element.
+- The anti-slop list from design-direction.md, included verbatim; design tools regress to defaults without it.
+- Asset manifest: every file in assets/ with its intended slot.
+
+### 04-acceptance-criteria.md
+
+Rewrite the build-dependent gates (ship-gates.md gates 3, 4, 5 plus the build requirements from Phase 5) as numbered, testable criteria. Examples: "Renders fully usable at 390px width with the CTA above the fold"; "One h1; heading levels do not skip"; "Total transfer under 1MB"; "JSON-LD from the included template embedded in head"; "prefers-reduced-motion respected". Include the llms.txt and schema templates pre-filled with the product's real values so the builder embeds rather than writes them.
+
+## Gate split in handoff mode
+
+Run BEFORE delivering the package (these gate the package itself):
+
+- Gate 1, conversion audit: runs against the spec and copy (5-second test, CTA policy, headline budget, proof adjacency, MECLABS scored on the planned page).
+- Gate 2, voice: `voice_scan.py` at zero FAILs on 01-copy.md and 00-master-prompt.md.
+- Gate 6, integrity: no fabricated proof anywhere in the package; [TK] items listed in the master prompt's questions section.
+
+Run AFTER the built asset comes back (request the HTML or a deployed URL):
+
+- Gate 1 re-check on the rendered page (did the build preserve CTA policy and proof adjacency?).
+- Gate 2 re-scan on the built HTML (catches paraphrase drift; this catches real violations often, run it every time).
+- Gates 3, 4, 5 in full.
+
+A handoff is not done at package delivery; it is done when the returned asset passes the post-build gates.
+
+---
+
+_Provenance: page-foundry-native (no direct companion source). The Claude Design capability description reflects Anthropic Labs as of 2026-07; re-verify it if the tool's inputs or outputs change. Gate references stay in sync with ship-gates.md and design-direction.md._