@zaip-ai/cli 6.3.0 → 7.5.0

package/templates/.agents/skills/zaip-skill-website-readiness/SKILL.md

@@ -1,13 +1,54 @@
 ---
 name: zaip-skill-website-readiness
-description: Build capability-aware websites with discoverable agent-readable metadata.
+description: Create or optimize any site or landing page with automatic SEO, GEO, performance and image care, preserving design; audit existing sites proportionately.
 ---
 
 # Website and Agent Readiness
 
+Apply [visual preservation](references/visual-preservation.md) before SEO/GEO edits:
+technical optimization never authorizes new visible sections, FAQs, CTAs or links.
+Agent Markdown stays at separate public URLs, never mounted or hidden in page DOM.
+Compare the approved baseline through build/hydration and inspect the page end.
+
+Every new site or LP automatically applies SEO, GEO, site performance and image
+optimization from the first implementation, even when the user only says “crie uma
+LP”. Preserve the supplied design, brand, accessibility and conversion contract;
+do not wait for separate optimization requests or a first deployment.
+
+Select `create`, `audit` (read-only), `fix` (baseline before changes), or
+`publication-check` (read-only after separately authorized deploy). For deterministic
+scope selection run `node .agents/skills/zaip-skill-website-readiness/scripts/quality-plan.mjs "crie uma LP"`.
+This helper complements native skill discovery; it does not dispatch agents or grant
+publication. Small edits verify affected scope without an automatic heavy audit.
+Select the [frontend impact contract](../zaip-skill-testing-strategy/references/frontend-impact.md)
+before testing an existing site. Presentation-only changes use diff, affected render
+and an inspected screenshot; existing forms/backend and deploy do not require
+unchanged conversion or integration tests.
+
+Compose with [image optimization](../zaip-skill-image-optimization/SKILL.md) and
+[performance engineering](../zaip-skill-performance-engineering/SKILL.md).
+New sites use the configured Astro + TypeScript + React Islands stack through
+[the creation contract](../zaip-skill-performance-engineering/references/astro-islands.md):
+static HTML for content and minimal hydration for interaction. Preserve existing
+consumer stacks unless migration is authorized. Performance minimum is 91 on mobile
+and desktop separately, aiming at 95 for margin; measurements must prove the result.
+Defina budgets antes de criar e use gates lab/public/field por cenário e device;
+um score ou captura isolada não comprova a prontidão inteira do site.
+For LP form creation or behavioral changes, compose
+[landing-page forms](../zaip-skill-landing-page-forms/SKILL.md) for format, recovery,
+accessible submission and confirmation semantics; a visual-only edit stays proportional.
+Use [site quality](references/site-quality.md) for SEO/GEO/social implementation and
+commands; [validation](references/site-validation.md) for visual/conversion evidence.
+
 Para componentes de UI novos ou alterados, carregue também
 `$zaip-skill-frontend-componentization`.
 
+Para referência Figma, screenshots ou URL em `apps/site/**`, escolha
+[`faithful`](../zaip-skill-design-reproduction/SKILL.md) para reprodução ou
+[`standardized`](../zaip-skill-design-redesign/SKILL.md) para adaptação ao contrato real.
+[`report-only`](../zaip-skill-visual-report/SKILL.md) não edita produto. Source não
+concede escrita externa nem escolhe Manu; central-promotion é output separado do designer.
+
 Use this skill for `apps/site/**`, landing pages, institutional websites, SEO, GEO,
 Markdown for Agents, or an Agent Readiness audit. Jonny owns implementation inside the
 site scope; Manu remains the owner of central design rules and must be called first when
@@ -22,26 +63,34 @@ the work changes `DESIGN.md`, design tokens, or canonical components.
 4. Implement responsive, semantic, accessible pages with deterministic metadata.
 5. Apply the capability-aware checklist in
    [references/capability-checklist.md](references/capability-checklist.md).
-6. Verify the rendered HTML, structured data, crawler files, Markdown representation,
-   links, and response headers. Record unsupported capabilities explicitly.
-7. Publish only to the configured validation branch and the site's own validation
-   environment. Production promotion follows the [deployment and access
-   contract](../zaip-skill-backend/references/deployment-environments.md); a
-   Supabase query, when relevant, uses only a configured READ-ONLY-BETA or
-   READ-ONLY-PROD context.
+6. For creation/readiness, verify rendered HTML, structured data, crawler files,
+   implemented Markdown, links and headers. For edits, verify only affected
+   capabilities; record unsupported capabilities explicitly.
+7. Publication requires a separate authorized deploy through the existing deploy
+   skill and configured hosting/branch. Verify the actual published SHA, official
+   domain and affected surface/contracts afterwards. Push, CI and
+   served application are separate observations; preserve rollback.
+
+## Outcomes by declared applicability
 
-## Required outcomes
+Classify each item using [the evidence contract](references/search-evidence.md):
+provider requirement, recommendation, ZAIP convention, or experimental capability.
+Record source, review date, applicability and observed proof; do not invent SEO scores.
 
 - Landing pages and institutional pages use the configured site stack and design system.
 - Every indexable page has a canonical URL, useful title and description, semantic
   headings, accessible navigation, and appropriate Open Graph metadata.
 - Structured data uses only facts present in the product or organization content.
-- `/robots.txt` contains valid `User-agent` groups and references the canonical sitemap.
-- `/sitemap.xml` contains only canonical, indexable URLs and is updated by the build.
-- Agent-readable Markdown is available through `Accept: text/markdown` when the hosting
-  stack supports content negotiation; otherwise publish an explicit Markdown endpoint
-  and advertise it without claiming negotiation support.
-- Link headers or HTML links advertise only resources that actually exist.
+- When robots policy exists, verify the most specific group and the complete path/query
+  for the selected agent. Preserve the owner's search/training/user-fetch choices.
+- A sitemap is recommended when useful, not required for every site. Declare its real
+  paths; an index may reference bounded same-origin children. Include canonical indexable
+  URLs only. Missing or partial observation is never full approval.
+- Where useful and supported, offer agent-readable Markdown through real content
+  negotiation or an explicit endpoint. Optional discovery resources are not universal
+  SEO/GEO requirements; advertise only implemented capabilities.
+- Link headers or head alternate links advertise only resources that exist; visible
+  links require specific authorization and the agreed placement.
 - AI crawler rules and Content Signals reflect the product owner's policy; never infer
   permission to train from a generic allow rule.
 
@@ -55,7 +104,14 @@ absent. Report each check as implemented, applicable but missing, or not applica
 
 ## Verification
 
-Run the site's own lint, typecheck, unit, accessibility, build, and preview checks. For
-readiness, verify status code and content type for `/`, `/robots.txt`, `/sitemap.xml`,
+Read [crawler purposes](references/crawler-policy.md), [schema applicability](references/schema-matrix.md),
+[content and agent representation](references/content-and-agents.md) and
+[change discovery](references/change-discovery.md) only for the affected capability.
+For account-aware measurement use [search observability](../zaip-skill-search-observability/SKILL.md).
+No universal H1 count, word count, JSON-LD type, Markdown endpoint or llms.txt requirement.
+
+Select the site's lint, typecheck, unit, accessibility, build and preview checks
+only when the changed impact or serving needs them. Presentation-only edits follow
+the visual quick path above. For initial readiness, verify status/content type for `/`, `/robots.txt`, `/sitemap.xml`,
 the Markdown request/endpoint, and each published well-known resource. Validate JSON-LD
 as JSON and inspect the rendered browser experience before declaring completion.

package/templates/.agents/skills/zaip-skill-website-readiness/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: Website Readiness
-  short_description: Build agent-ready sites with truthful discovery.
-  default_prompt: Use $zaip-skill-website-readiness to implement or audit an apps/site change without inventing unavailable integrations.
+  short_description: "Apply SEO, GEO, performance and images to every site."
+  default_prompt: "Use $zaip-skill-website-readiness to create a landing page with automatic SEO, GEO, performance and image care while preserving design."

package/templates/.agents/skills/zaip-skill-website-readiness/references/capability-checklist.md

@@ -12,10 +12,14 @@ Use three states for every item: `implemented`, `applicable-missing`, or
 - Valid `/robots.txt` with at least one `User-agent` directive, explicit policy, and a
   canonical `Sitemap:` directive.
 - Valid `/sitemap.xml` with canonical, indexable URLs.
-- AI-specific crawler groups and `Content-Signal` directives matching the owner's
-  documented policy.
-- Agent-readable Markdown through content negotiation or a truthful advertised
-  fallback endpoint.
+- Preserve the owner's documented crawler/training policy. Add bot-specific groups
+  or experimental directives only after checking their current official support;
+  their absence is not a universal defect.
+- Optional agent-readable Markdown through real content negotiation or a truthful
+  advertised endpoint where useful; absence is not a universal SEO/GEO defect.
+  Advertise through technical head/HTTP discovery where appropriate, without
+  adding visual links or mounting Markdown in the page. Follow
+  [visual preservation](visual-preservation.md).
 - GEO content that answers user questions directly, identifies entities consistently,
   cites first-party facts, and does not hide critical content behind client-only UI.
 

package/templates/.agents/skills/zaip-skill-website-readiness/references/change-discovery.md

@@ -0,0 +1,22 @@
+# Discover changed public URLs
+
+Reviewed 2026-10-29. Inventory actual changed canonical URLs, removals/redirects and their
+HTTP evidence, public status, owner and candidate. Sitemap paths are project-specific;
+an index and children must be coherent and bounded. Use accurate lastmod from real changes,
+not the audit clock. Never submit private, test, query-secret or unapproved external URLs.
+
+Default workflow is local preview: compare old/new URL inventory, inspect canonical,
+hreflang and redirect chains, detect cycles and retain rollback. IndexNow is optional
+for supported engines; it is not a Google submission API or an indexing/ranking promise.
+Its verification key is public ownership evidence, not a credential to hide in a secret
+store. Ownership verification still must succeed for the exact host/key location.
+
+Real submission requires explicit authorization for the actual changed public URLs and
+provider. Use the provider's supported tool only after validating host, payload, limits and
+response; do not retry unchanged inventories or treat HTTP acceptance as indexing. Save
+the submitted inventory/hash and observed result; do not submit to diagnose a local draft.
+
+Sources:
+- https://developers.google.com/search/docs/crawling-indexing/sitemaps/overview
+- https://www.indexnow.org/documentation
+- https://www.indexnow.org/faq

package/templates/.agents/skills/zaip-skill-website-readiness/references/content-and-agents.md

@@ -0,0 +1,25 @@
+# Content, rendering and agent representations
+
+Reviewed 2026-10-29. Start with user intent and existing approved journeys. Record source,
+author/reviewer, actual expertise, claim evidence and revision trigger. Propose internal
+links where useful; adding visible links, sections, answers or copy requires approval.
+No doorway city substitutions, mass thin pages, fabricated authors or citations.
+
+Inspect initial HTML and browser-rendered DOM separately, including hydration, mobile,
+navigation/focus/semantics, image selection and third-party effects. Reuse the current
+stack and performance workflow. Lab measurements and field CWV answer different questions;
+do not force SSR, a framework migration or a new dependency just for an audit score.
+
+Optional Markdown is a second representation of the same public source and facts. Exclude
+private metadata, draft claims and internal instructions. Serve correct MIME; advertise only
+an implemented endpoint/alternate. Content negotiation must honor Accept, correct Vary and
+cache keys; verify HTML and Markdown both. It is not a different marketing story for bots.
+Keep it outside page DOM, never as hidden text or another footer. No prompt manipulation,
+cloaking or access-control bypass. llms.txt remains an optional experiment, not a Google
+eligibility requirement. A missing experimental endpoint is not a universal SEO defect.
+
+Sources:
+- https://developers.google.com/search/docs/fundamentals/creating-helpful-content
+- https://developers.google.com/search/docs/crawling-indexing/javascript/javascript-seo-basics
+- https://developers.google.com/search/docs/fundamentals/ai-optimization-guide
+- https://web.dev/articles/ai-agent-site-ux

package/templates/.agents/skills/zaip-skill-website-readiness/references/crawler-policy.md

@@ -0,0 +1,35 @@
+# Crawler purpose and access matrix
+
+Official sources reviewed by host 2026-10-29. Confirm current names and any published
+verification endpoints before changing rules. A claimed User-Agent is not authentication.
+
+| Provider | Search/discovery | Training/control | User-requested fetch | Verification limit |
+| --- | --- | --- | --- | --- |
+| Google | Googlebot, eligible ordinary search + Search Console AI Include/Exclude/Inherit | Google-Extended is a separate documented product control | User-triggered tools are not equivalent to Googlebot | Use Google's current verification guidance; do not infer all agents share IPs |
+| Bing | bingbot; Bing Webmaster AI visibility where available | Product-specific controls require current documentation | Distinguish interactive retrieval from indexing | Official verification only, never a copied stale IP list |
+| OpenAI | OAI-SearchBot | GPTBot | ChatGPT-User | Independent controls; use published IP resources for the specific agent where available |
+| Anthropic | Claude-SearchBot | ClaudeBot | Claude-User | robots and documented Crawl-delay; no public fixed IP ranges established by cited source |
+| Perplexity | PerplexityBot | Do not infer training permission from a search allow | Perplexity-User | Use published verification only where the current provider source supplies it |
+
+1. Inventory existing robots, CDN/WAF and owner's search/training policy before proposing
+   a diff. Generic Allow never grants training consent or rewrites a specific bot choice.
+2. Match the most specific product token; combine only equally specific groups. Evaluate
+   path plus query, longest matching rule, Allow on equal specificity. Empty Disallow
+   imposes no restriction but still separates groups. Test wildcard/end anchors/encoding.
+3. `noindex` requires the applicable crawler to fetch the page. robots is a request policy,
+   not access control, deindexing proof or a privacy barrier. Meta and HTTP directives are
+   agent scoped; generic directives still apply. A block may prevent reading noindex.
+4. Diagnose HTTP/WAF challenge, robots, rendering and engine state separately. Never
+   disable a WAF, trust a UA string, grant blanket traffic or fetch external targets to
+   make a check green. Use the provider's documented verification procedure when authorized.
+5. Search Console AI inclusion changes require explicit owner authorization for the exact
+   property. Record inherited versus explicit settings and keep training policy separate.
+
+Sources:
+- https://developers.google.com/crawling/docs/robots-txt/robots-txt-spec
+- https://developers.google.com/search/docs/crawling-indexing/verifying-googlebot
+- https://support.google.com/webmasters/answer/16908024
+- https://developers.openai.com/api/docs/bots
+- https://privacy.anthropic.com/en/articles/8896518-does-anthropic-crawl-data-from-the-web-and-how-can-site-owners-block-the-crawler
+- https://docs.perplexity.ai/docs/resources/perplexity-crawlers
+- https://www.bing.com/webmasters/help/webmaster-guidelines-30fba23a?region=france

package/templates/.agents/skills/zaip-skill-website-readiness/references/schema-matrix.md

@@ -0,0 +1,23 @@
+# Structured-data applicability
+
+Reviewed 2026-10-29. Confirm current provider support before selecting a type.
+
+| Business/content | Candidate vocabulary | Eligibility/proof boundary |
+| --- | --- | --- |
+| Confirmed organization or local establishment | Organization or actual LocalBusiness subtype | Real identity/location/service area; not invented regional presence |
+| Actual product/offer | Product/Offer | Actual visible product, price/currency/availability; provider restrictions checked |
+| Authored article | Article subtype, real author and dates | Authorship/review sources, visible content and current provider policy |
+| Navigable hierarchy | BreadcrumbList | Matches actual navigation; no invented hierarchy |
+| Event or job posting | Applicable Event/JobPosting | Actual dates, terms, availability and provider-specific requirements |
+| Visible service/page/site | Service, WebPage, WebSite where semantically useful | Schema.org syntax is not a promise of a Google rich-result feature |
+| FAQ | FAQ vocabulary only if truthful/useful | Google FAQ rich results retired 2026-05-07; documentation update 2026-06-15. Do not sell FAQ markup as current eligibility |
+
+Validate four independent levels: JSON syntax → truthful visible facts → current feature
+eligibility → observed search appearance. None implies the next. Do not add reviews,
+ratings, authors, addresses, awards, FAQ sections or prices to satisfy a schema checker.
+An applicable schema is conditional, not a universal checklist item for every LP.
+
+Sources:
+- https://developers.google.com/search/docs/appearance/structured-data/sd-policies
+- https://developers.google.com/search/updates
+- https://schema.org/docs/schemas.html

package/templates/.agents/skills/zaip-skill-website-readiness/references/search-evidence.md

@@ -0,0 +1,36 @@
+# Search evidence contract
+
+Reviewed 2026-10-29 against official sources listed below; revalidate changed provider
+features before adoption. This is framework guidance, not proof of account availability.
+
+| Class | Applicability | Sufficient observation | Stop/limit |
+| --- | --- | --- | --- |
+| Provider requirement | Named engine, feature and public URL | HTTP + applicable directive/configuration; engine account evidence separately | Unknown policy or unobserved layer remains unknown |
+| Recommendation | Documented usefulness for the actual site | Explain benefit and verify implementation | Not a ranking guarantee or universal failure |
+| ZAIP convention | Explicit project contract, such as metadata/social baseline | Candidate/render/HTTP compared with that contract | Convention is not a search-engine eligibility rule |
+| Experimental | Named consumer and current support evidence | Controlled opt-in with fallback | Absence alone is not a defect |
+
+For each finding record URL, selected crawler, initial/rendered layer, request/response,
+candidate/version, source URL, checked_at, applicability, expected, observed and limitation.
+`passed_scoped` covers the declared snapshot only. `partial`, unavailable account access,
+unverified external targets or missing observations never become a whole-site pass.
+Do not infer indexing from crawl permission, visibility from indexing, clicks from citations,
+sessions from clicks, conversions from sessions or attribution from any of these.
+
+Google AI search: ordinary indexed/snippet-eligible content and the applicable Search
+Console generative-AI setting matter; there is no mandatory special AI schema, llms.txt
+or Markdown format. Include is the default at root; child properties default to Inherit;
+Exclude/Include/Inherit require the correct domain/subdomain/URL-prefix context. This
+control is distinct from model training and traditional search ranking. Read the actual
+property configuration; never change it merely to improve an audit.
+
+Sources (official, verified by the host 2026-10-29):
+- https://developers.google.com/search/docs/fundamentals/ai-optimization-guide
+- https://support.google.com/webmasters/answer/16908024
+- https://developers.google.com/search/docs/fundamentals/creating-helpful-content
+- https://developers.google.com/search/docs/appearance/core-web-vitals
+
+Useful titles and clear semantic structure support people and discovery. Neither a fixed
+word count nor exactly one H1 determines eligibility. JSON-LD is conditional; descriptions,
+canonical and social checks in the supplied config are declared project conventions.
+Skip inapplicable checks with a reason, never by deleting a failed observation.

package/templates/.agents/skills/zaip-skill-website-readiness/references/site-quality.example.json

@@ -0,0 +1,14 @@
+{
+  "origin": "https://example.com",
+  "baseUrl": "http://127.0.0.1:4173",
+  "agent": "Googlebot",
+  "sitemapPaths": ["/sitemap.xml"],
+  "sitemapCoverage": "sampled",
+  "routes": [
+    { "path": "/", "indexable": true },
+    { "path": "/obrigado/", "indexable": false, "social": false }
+  ],
+  "missingPaths": ["/zaip-missing-route", "/zaip-missing-asset.png", "/ai-catalog.json"],
+  "immutableAssets": [],
+  "maxResponseBytes": 8000000
+}

package/templates/.agents/skills/zaip-skill-website-readiness/references/site-quality.md

@@ -0,0 +1,109 @@
+# Site quality workflow
+
+For every site/LP creation, apply this baseline during implementation without waiting
+for separate SEO, GEO, performance or image requests. Retain design geometry, crop,
+typography, brand and conversion behavior. Existing-site fixes first capture a baseline;
+audit and publication-check modes never mutate the site. Changes to one button do not
+justify a full performance audit. Do not migrate stacks merely to satisfy an audit tool.
+
+## Technical SEO and content
+
+Apply the [evidence classification](search-evidence.md), [crawler matrix](crawler-policy.md)
+and [schema matrix](schema-matrix.md). Sitemap and JSON-LD are conditional; no fixed
+word count or H1 quota is a universal engine requirement. Preserve owner's AI/search
+settings. Use [content/agent representations](content-and-agents.md) for approved copy
+and optional Markdown; [change discovery](change-discovery.md) never auto-submits URLs.
+
+Map public indexable, private, test and conversion routes. Use distinct useful titles and
+descriptions matching intent; editorial character ranges are guidance, not ranking laws.
+Set UTF-8, lang, viewport, semantic headings and real crawlable links. Essential content,
+metadata and social tags belong in initial HTML where the stack allows. Prefer static
+HTML/SSG for stable public content, SSR for request-bound content, or targeted prerender
+for an existing SPA. Verify direct access and reload, including success routes.
+
+Use absolute canonical URLs consistent with official HTTPS, www/apex and trailing slash
+policy. Internal links, redirects and sitemap must agree. Sitemap contains only public
+canonical indexable URLs; exclude thank-you, internal and test pages as appropriate.
+Use lastmod only from actual content changes. Review robots groups against the existing
+policy; do not block crawling of a page whose removal relies on reading noindex.
+Test real HTTP 200/redirect/404 responses, soft 404s and SPA fallback for missing assets.
+Our bounded verifier detects wrong statuses; assess content-based soft 404s manually.
+
+Use applicable Organization, LocalBusiness subtype, Service, WebSite, WebPage and
+BreadcrumbList JSON-LD only from visible, confirmed facts. Syntax validation is not
+schema eligibility or a rich-result guarantee. Never invent ratings, addresses, service
+coverage, awards, prices, authors or credentials. hreflang requires real translated or
+regional pages. Do not add meta keywords as a Google ranking improvement.
+
+For local SEO, distinguish desired expansion from confirmed service area. Verify contact,
+location and service details with project sources. Regional pages need distinct useful
+content, not city-name substitutions. Identify Search Console, Bing Webmaster Tools and
+business-profile opportunities without assuming access or taking external action.
+
+## GEO and crawler policy
+
+Follow [visual preservation](visual-preservation.md): technical SEO/GEO does not
+authorize visible additions, duplication, layout changes or a second footer section.
+New editorial content needs specific approval; preserve existing approved FAQs.
+
+State brand, service, audience, region, evidenced differentiators, process and conditions
+clearly. Use direct answers and genuine FAQs only when useful to people. Align visible
+text, metadata and structured data. Cite claims and preserve uncertainty. No cloaking,
+hidden keyword text, stuffing or instructions manipulating AI answers.
+
+Consult [official sources](sources.md) again when changing crawler recommendations and
+record source/date. Search crawling, model training and user-requested navigation are
+different purposes. Preserve existing access and training policy; never silently allow
+all bots. llms.txt is optional/experimental, not a universal requirement or ranking
+promise. Investigate an actual specification and consumer support before adding
+ai-catalog.json or another discovery document; absence should return 404/410, not SPA
+HTML 200. No universal GEO score, guaranteed ChatGPT presence or first-place claim.
+
+## Sharing, including WhatsApp
+
+Where pertinent, put Open Graph and Twitter Card title, description, URL, locale, type
+and image tags in the initial head. Use absolute public asset URLs, correct MIME and
+decoded dimensions. Never invent twitter:site/creator identities. Favicon, application
+icon and social image are different derivatives; preserve the provided identity without
+stretching. Review platform format support before choosing a social-image encoding.
+HTTP tag checks are not proof of WhatsApp rendering. Previews are cached: after a real
+content change use a versioned image URL and the platform's supported refresh/debugger;
+report actual in-app preview tests separately, without sending real messages merely to test.
+
+## Executable checks
+
+Copy [site-quality.example.json](site-quality.example.json) to project-owned configuration,
+set official origin, preview base URL and the complete bounded route inventory. Preview
+fetches use baseUrl while canonical comparisons use origin. Run against an already built
+and served preview (GET only, at most 100 declared routes; no form submission):
+
+```text
+node .agents/skills/zaip-skill-website-readiness/scripts/audit-site.mjs site-quality.json
+```
+
+Persist stdout as raw JSON evidence using the host's UTF-8 file tooling. Nonzero means a
+measured error. Warnings and limitations remain review obligations, not full approval.
+External social-image hosts are not fetched automatically: inspect them through an
+authorized tool and supply evidence to `auditSite` or report unverified. The parser is a
+bounded initial-head inspector, not a full HTML, XML, robots or schema validator. Decode
+social dimensions with the image workflow. Verify CSS/background images, art direction,
+preload selection and actual network requests in a browser. `immutableAssets` must come
+only from hash-verified generated derivatives; never whitelist HTML/mutable files.
+
+Auditor config: `agent` selects robots and indexing directives (default Googlebot).
+`sitemapPaths: []` disables sitemap checks explicitly; otherwise declare actual paths
+or use the legacy /sitemap.xml default. Indices traverse at most20documents/depth3,
+same-origin only. `sitemapCoverage: "complete"` makes missing declared routes an error;
+sampled/unknown coverage and unobserved sitemap URLs remain partial, not nonindexable.
+External canonical targets require exact `externalCanonicals` declarations. External
+hreflang evidence uses `{url,hreflang,reciprocal}` in `externalAlternates`; those are
+supplied observations, never an automatic external fetch or proof of live availability.
+`requireH1` and `minContentCharacters` apply only when set on a route by the project.
+`passed_scoped` is neither whole-site approval nor XML/DOM/browser conformance.
+
+Static HTML: write metadata directly in head and responsive markup at build time.
+React/Vite: use the existing framework or build/prerender pipeline for route metadata;
+do not rely on Helmet/client injection for social crawlers. Import only used image
+records, not an entire asset inventory. Ensure image generation runs in the clean build.
+Native optimization (Astro/Next or another framework): reuse its image component and
+loader, inspect emitted HTML and requests, avoid running a second conversion pipeline.

package/templates/.agents/skills/zaip-skill-website-readiness/references/site-validation.md

@@ -0,0 +1,60 @@
+# Evidence and acceptance
+
+Classify each check with [search-evidence](search-evidence.md). Sitemap, H1 quotas,
+word counts, JSON-LD types and Markdown/llms.txt are conditional, not universal pass
+criteria. Initial-HTML/HTTP `passed_scoped` is not rendered DOM, WAF, engine indexing or
+account proof; unobserved/sample-limited URLs remain partial. Scope an absent capability
+before calling it a defect. The source-only skill installer proof is separate from full
+runtime/dashboard/exact-package qualification and leaves global gates intact.
+
+Select scope first through the
+[frontend impact contract](../../zaip-skill-testing-strategy/references/frontend-impact.md).
+Creation/readiness and changed conversion contracts differ from a presentation-only edit.
+Do not infer impact from the presence of a form, Supabase or a deployment request.
+
+For a reviewed visual-only diff: inspect the diff, render the affected UI and examine
+a real screenshot. Check only the relevant route/state and viewports. Do not fill or
+submit the form, query the database or retest unchanged backend/integrations. A build
+is needed only to serve/publish the current change; lint/typecheck/tests require
+changed impact or an observed failure. A broader visual footprint may need more
+screenshots, not unrelated flow testing.
+
+For creation or changes to build/assets, a clean build must generate assets/manifests
+from committed inputs without a developer-local manifest. Direct routes/reload and
+missing URLs are required for initial readiness or changes to navigation/hosting.
+
+Capture before/after with equal viewport, DPR, fonts, data, crop, motion settings and
+cache when a before/after comparison is needed. Inspect the changed region; first fold,
+main sections, gallery and form coverage applies to creation or changes reaching them. Generated
+files alone do not pass visual acceptance. Distinguish compression artifacts from crop,
+layout, color/alpha and typography regressions. Check affected keyboard/motion behavior
+when the diff reaches those contracts. Do not repeat unchanged checks by ceremony.
+
+For a new conversion contract, changed submission/payload/flow, or explicit full-flow
+request, exercise the affected conversion contract with local mocks/sandbox: required and optional
+steps, invalid fields, sending, failure, retry and success page. If resuming a registration
+exists, use synthetic owned data and validate authorization. Do not create real leads,
+messages or automations for evidence, and do not make a client-specific modal behavior a
+global rule. A field-validation change needs that field's affected behavior, not an
+automatic end-to-end retest of all integrations. State what was mocked/observed and
+mark unrelated modalities not applicable because their contracts did not change.
+
+Use the [performance workflow](../../zaip-skill-performance-engineering/references/site-performance.md)
+for raw network evidence, budgets and benchmark conditions. A network capture cannot
+prove Lighthouse/PageSpeed/GTmetrix scores; unavailable tools stay unavailable. Lack of
+field data neither approves nor fails CWV. Never lower budgets silently to produce PASS.
+
+After separately authorized deployment, retain the same impact scope in the GitHub/provider workflow:
+authorized identity/SSH/hosting, secrets in the approved mechanism, tested candidate SHA,
+published SHA and rollback. Distinguish push, CI status and served application. Check
+the published affected surface. Asset MIME/cache, canonical, redirects, direct/reload
+conversion routes and missing resources apply to initial readiness or changes to those
+contracts. A visual-only deploy does not add a form submission or backend check.
+Unknown CI state remains unknown. This workflow grants no deploy
+authority and does not require infrastructure changes to satisfy an audit.
+
+For creation, full audit or changes reaching the corresponding contract, select probes for missing/duplicate metadata, wrong canonical, sitemap
+noindex, invalid JSON-LD, social 404, SPA HTML 200, lazy hero, mismatched preload, heavy
+original PNG requests, opposite-viewport images, incorrect dimensions, missing assets,
+budget excess and mutable/HTML immutable caching. Inspect browser waterfall to distinguish
+preload warnings from actual duplicate downloads.

package/templates/.agents/skills/zaip-skill-website-readiness/references/sources.md

@@ -0,0 +1,37 @@
+# Official sources — updated 2026-10-29
+
+Recheck these official pages before changing a project's crawler or platform policy.
+Dates describe this inspection, not a guarantee that documentation remains unchanged.
+
+- [Google AI optimization](https://developers.google.com/search/docs/fundamentals/ai-optimization-guide):
+  replaces the older AI-features URL; ordinary indexing/snippet eligibility and the applicable
+  Search Console AI setting matter, with no special Markdown, schema or llms.txt requirement.
+- [Search Console AI controls](https://support.google.com/webmasters/answer/16908024):
+  Include/Exclude/Inherit at the exact property, independent from training/traditional rank.
+- [Generative AI report](https://support.google.com/webmasters/answer/16984139):
+  impressions/report aggregation and export-zero ambiguity; not extra Web Performance traffic.
+- [Structured-data updates](https://developers.google.com/search/updates):
+  Google FAQ rich results retired May2026; vocabulary is not feature eligibility.
+- [OpenAI crawler documentation](https://developers.openai.com/api/docs/bots):
+  OAI-SearchBot supports search, GPTBot concerns possible training, ChatGPT-User supports
+  user-initiated access. Policy and robots behavior differ; verify current bot details.
+- [Google robots](https://developers.google.com/search/docs/crawling-indexing/robots/intro):
+  robots limits crawling, not a reliable removal mechanism; noindex needs crawler access.
+- [Google HTTP errors](https://developers.google.com/search/docs/crawling-indexing/http-network-errors):
+  status and content both matter; successful HTML responses can still be soft 404s.
+- [Web Vitals](https://web.dev/articles/vitals): field p75 targets LCP 2.5 s, INP 200 ms,
+  CLS 0.1, segmented by device. Lab data is a different evidence population.
+- [Open Graph protocol](https://ogp.me/): shared-object properties and structured image
+  metadata; protocol compliance alone does not prove a particular messaging app preview.
+- [llms.txt proposal](https://llmstxt.org/): publisher proposal, optional; inspect current
+  support rather than declaring it a universal search requirement.
+
+ai-catalog.json is not required by the cited Google/OpenAI search guidance. This does
+not prove no specification exists elsewhere: investigate the requested feature's real
+specification/support first. Never generate a placeholder and claim universal support.
+
+The host verified the updated Google/crawler sources on 2026-10-29. Earlier CWV/OGP/
+proposal references remain background and should be checked again before adoption.
+Use [search-evidence](search-evidence.md), [crawler policy](crawler-policy.md) and
+[schema matrix](schema-matrix.md) for class, applicability and proof limits. This source
+list does not turn H1, word count, sitemap, JSON-LD or Markdown into universal requirements.

package/templates/.agents/skills/zaip-skill-website-readiness/references/visual-preservation.md

@@ -0,0 +1,84 @@
+# SEO/GEO sem alteração visual não solicitada
+
+Este é o contrato canônico. Otimização técnica não autoriza novas seções, FAQs,
+CTAs, resumos, banners, links, conteúdo duplicado ou alterações de espaço/altura/
+hierarquia. Nunca adicionar editorial depois do rodapé para satisfazer um checker.
+Preserve FAQs e conteúdo previamente aprovados. Se a melhoria depender de novo
+conteúdo visível, apresente a proposta e obtenha autorização antes de implementar.
+Criar um site novo já autoriza desenvolver o conteúdo humano dentro do briefing;
+isso não autoriza acrescentar um segundo layout para robôs.
+
+## Três camadas
+
+1. Interface humana: somente conteúdo aprovado, sem duplicação para pontuação.
+2. Head técnico: title, description, canonical, OG/Twitter e JSON-LD pertinente,
+   sem montar componentes visuais. Schema representa fatos e conteúdo da página;
+   não receber conteúdo removido da interface para contornar requisitos do tipo.
+3. Representação pública para agentes: Markdown e llms.txt opcional em arquivos/
+   endpoints separados. Humanos também podem abrir as URLs. Ausente do layout não
+   significa secreto. Não substitui conteúdo útil/indexável destinado ao visitante.
+
+Não guardar texto SEO em display:none, opacity:0, offscreen, fonte minúscula,
+aria-hidden ou classes sr-only. Não variar editorial por User-Agent. Isso não
+proíbe acessibilidade legítima, accordion/FAQ aprovado, live regions ou modais;
+avalie finalidade e compare com a interface aprovada, sem blacklist de classes.
+
+## Geração e descoberta
+
+Use fatos verificados e preferencialmente uma fonte compartilhada com o conteúdo
+aprovado. O helper de build
+[agent-content.mjs](../scripts/agent-content.mjs) gera somente arquivos .md/.txt e
+um link rel=alternate type=text/markdown para o head. Ele nunca gera HTML visível.
+Sua validação de URLs não comprova a veracidade dos fatos; revisar fontes é obrigatório.
+Execute com JSON revisado e diretório de saída existente, separadamente do DOM:
+
+    node .agents/skills/zaip-skill-website-readiness/scripts/agent-content.mjs approved-content.json dist
+
+O JSON contém canonical, title, facts:[{text,source}], markdownPath opcional e llms
+booleano opcional. Defaults não geram llms.txt nem link visual. Arquivo diferente
+existente exige revisão, não sobrescrita silenciosa. Builds limpos geram os arquivos
+da fonte versionada, sem depender de manifesto particular do desenvolvedor.
+
+HTML estático/SSG: exporte arquivos públicos e somente headAlternate no head.
+React/Vite: não importe Markdown como componente nem renderize seu conteúdo no JSX;
+exporte no build/public e mantenha metadados iniciais pelo recurso da stack.
+SSR/framework nativo: endpoint público com MIME correto, independente de User-Agent.
+Hidratação, plugins, templates e fallback sem JS obedecem ao mesmo contrato.
+
+Por padrão não há link visual. Se autorizado, inserir apenas o link acordado dentro
+do rodapé existente, com foco/contraste/teclado acessíveis e espaço preservado. Uma
+autorização específica de outra posição ou alteração de layout prevalece e deve ser
+registrada no baseline. Texto/posição do exemplo Moradigna não são defaults globais.
+
+## Prova proporcional
+
+Capture baseline e candidato em condições equivalentes mobile/desktop, inclusive
+fim da página, com JS e sem JS quando aplicável. Use visualSnapshot e
+compareVisualSnapshots de [visual-preservation.mjs](../scripts/visual-preservation.mjs).
+Para um runner pronto, use Playwright já instalado no projeto, sem instalar browser
+automaticamente: `node .agents/skills/zaip-skill-website-readiness/scripts/verify-site-design.mjs design-check.json`.
+O config declara baselineUrl/candidateUrl locais, outputDir, projectRoot opcional e
+readySelector opcional para aguardar hidratação. source registra a identidade do
+candidato; snapshots, condições e screenshots ficam no outputDir. Requisições
+externas e métodos de escrita são bloqueados; registre diferenças de produção.
+O comparador verifica conteúdo/geometria reais, sem depender de nomes de componentes.
+Scripts, metadados e portais vazios não são editorial. Mudança legítima em conteúdo
+interativo/acessível exige revisão específica; não é rotulada automaticamente abuso.
+O link autorizado pode ser excluído da comparação textual mediante referência da
+autorização e href/texto exatos; mudanças de geometria continuam exigindo aceite visual.
+Tire e examine screenshots, não aceite apenas a existência de PNGs.
+
+Declare agentResources no config de audit-site para conferir status, MIME, conteúdo
+e fallback SPA dos arquivos adotados; recurso opcional ausente não é erro universal.
+Metadados/JSON-LD precisam permanecer no HTML inicial. Não executar formulário,
+enviar leads nem chamar API de escrita para validar SEO/estilo sem impacto funcional.
+
+Positivo: head atualizado + /site.md separado + rodapé idêntico.
+Negativo: componente com qualquer nome acrescenta apresentação/FAQ após footer.
+Negativo: Markdown montado no DOM, mesmo escondido ou injetado depois da hidratação.
+Positivo: FAQ já aprovado, modal existente e texto acessível legítimo preservados.
+
+Fontes verificadas em 22/10/2026: [Google AI features](https://developers.google.com/search/docs/appearance/ai-features),
+[spam policies](https://developers.google.com/search/docs/essentials/spam-policies),
+[structured data policies](https://developers.google.com/search/docs/appearance/structured-data/sd-policies).
+Não há garantia de ranking/rich result/presença em IA ou exigência universal de llms.txt.