anymorph 0.2.6 → 0.4.0

package/dist/skillpacks/geo/scaffold/AGENTS.md

@@ -0,0 +1,38 @@
+# Anymorph GEO Tenant Repo
+
+This tenant repo uses Anymorph's local GEO workflow.
+
+Codex reads this file. Claude reads `CLAUDE.md`. Both runtimes use the same
+managed skillpack installed under `.agents/skills` and `.claude/skills`, plus
+shared references under `.agents/shared` and `.claude/shared`.
+
+Run Anymorph CLI commands from the repository root.
+
+At the first user request in a new agent session, check whether the installed
+`anymorph` CLI can be updated before running GEO workflow commands. Update it
+when npm has a newer published version, then run `anymorph doctor` to confirm
+the managed skillpack is fresh.
+
+```bash
+CURRENT=$(anymorph --version 2>/dev/null || true)
+LATEST=$(npm view anymorph version 2>/dev/null || true)
+if [ -n "$LATEST" ] && [ "$CURRENT" != "$LATEST" ]; then
+  npm install -g anymorph@latest
+fi
+anymorph doctor
+```
+
+```bash
+anymorph init
+anymorph doctor
+anymorph prepare <workspaceId>
+anymorph validate <runId>
+anymorph submit <runId>
+```
+
+## Rules
+
+- Do not edit managed files under `.agents/skills`, `.agents/shared`, `.claude/skills`, `.claude/shared`, or `agent/contracts` by hand.
+- Keep stable brand and strategy context in `agent/BRAND.md`, `agent/STRATEGY.md`, and `agent/LEARNINGS.md`.
+- Write run artifacts only under `agent/runs/{runId}` unless a skill explicitly says otherwise.
+- Run `anymorph doctor` when managed skill behavior looks stale.

package/dist/skillpacks/geo/scaffold/CLAUDE.md

@@ -0,0 +1,33 @@
+# Anymorph GEO Tenant Repo
+
+This repository is a tenant workspace for Anymorph GEO work.
+
+Claude reads this file. Codex reads `AGENTS.md`. Both runtimes use the same
+managed skillpack installed under `.claude/skills` and `.agents/skills`, plus
+shared references under `.claude/shared` and `.agents/shared`.
+
+At the first user request in a new Claude Code session, check whether the
+installed `anymorph` CLI can be updated before running GEO workflow commands.
+Update it when npm has a newer published version, then run `anymorph doctor` to
+confirm the managed skillpack is fresh.
+
+```bash
+CURRENT=$(anymorph --version 2>/dev/null || true)
+LATEST=$(npm view anymorph version 2>/dev/null || true)
+if [ -n "$LATEST" ] && [ "$CURRENT" != "$LATEST" ]; then
+  npm install -g anymorph@latest
+fi
+anymorph doctor
+```
+
+Use the root `AGENTS.md` for shared agent rules. Claude-specific local behavior should still follow the Anymorph CLI workflow:
+
+```bash
+anymorph init
+anymorph doctor
+anymorph prepare <workspaceId>
+anymorph validate <runId>
+anymorph submit <runId>
+```
+
+Do not manually patch managed skill copies or shared references under `.claude/` or `.agents/`; repair them with `anymorph doctor --fix`.

package/dist/skillpacks/geo/shared/evidence-principles.md

@@ -0,0 +1,35 @@
+# Evidence Principles
+
+Use this shared reference for claim, evidence, freshness, and structured-data judgment across GEO skills.
+
+## Claim Strength
+
+- Do not create claims stronger than the approved evidence source.
+- Distinguish product facts, positioning, customer evidence, third-party evidence, and agent inference.
+- If evidence is absent, stale, ambiguous, jurisdiction-specific, or compliance-sensitive, flag for review instead of publishing or recommending the claim.
+- Do not summarize reviews, UGC, case studies, or external commentary into a stronger claim than the source supports.
+
+## Source Hierarchy
+
+- Prefer first-party approved records for brand, product, price, availability, policy, certification, and compliance facts.
+- Use product catalog, approved documentation, trust centers, policy pages, feeds, and brand-managed KB before external research.
+- Use external research to understand market context, comparison criteria, definitions, and third-party authority. Do not use it to invent brand-specific facts.
+- For comparison claims, record the criteria, date, source, and scope.
+
+## Freshness
+
+- Facts involving price, availability, policy, certification, integration support, hours, inventory, fees, shipping, returns, regulatory status, or live booking state need source, date, and refresh cadence.
+- Label live, feed-supplied, estimated, seasonal, and stale facts clearly.
+- Prefer no claim over a stale or unsupported claim.
+
+## Structured Data
+
+- Structured data must match visible page content.
+- Valid structured data can improve eligibility for supported search experiences, but does not guarantee display, ranking, or AI citation.
+- Do not add schema for hidden, misleading, fake, outdated, or unsupported content.
+
+## GEO/AEO Framing
+
+- Do not treat GEO/AEO as separate from technical SEO, content quality, entity clarity, structured data accuracy, and evidence governance.
+- Pages should be useful, crawlable, self-contained, source-aware, and explicit about assumptions.
+- AI search inclusion, citation, and recommendation are not guaranteed outcomes.

package/dist/skillpacks/geo/shared/geo-principles.md

@@ -0,0 +1,281 @@
+# GEO Principles — Anymorph MCP
+
+이 문서는 Anymorph GEO Skills의 모든 sub-Skill이 공유하는 원칙이다.
+sub-Skill 본문에 인라인으로 복붙하지 말고, 필요한 항목만 한 줄 링크로 참조할 것.
+
+---
+
+## 1. Generative Engine Optimization(GEO) 정의
+
+### GEO vs 전통 SEO
+
+전통 SEO는 Google 검색 결과 페이지(SERP)의 순위를 올리는 작업이다.
+KPI는 "클릭률(CTR)", "페이지 1 진입", "organic traffic" 등 SERP 기반 지표다.
+
+GEO는 다르다. 목표는 **AI 엔진(ChatGPT, Gemini, Perplexity, Claude 등)이 사용자 질문에
+답변할 때 우리 브랜드 페이지를 인용 소스로 채택하게 만드는 것**이다.
+KPI는 "AI 응답 내 인용 빈도(citation rate)", "intent 커버리지", "AI 가시성 점수"다.
+
+### 왜 다른가
+
+- LLM은 SERP 순위를 보지 않는다. 크롤된 콘텐츠를 학습 or RAG로 직접 참조한다.
+- AI가 인용하는 조건: 사실 밀도, 구조 명확성, 신뢰 신호, 도메인 권위.
+- 트래픽 경로가 바뀐다: "검색 → 클릭 → 사이트" 대신 "AI 답변 → 브랜드 노출 → 직접 유입".
+- GEO 최적화 페이지는 SEO에도 도움이 되지만, 역은 성립하지 않는다.
+
+### Anymorph MCP의 역할
+
+Anymorph MCP는 26개 도구로 GEO Visibility Loop를 자동화한다:
+- 현재 AI 가시성 측정 → 약한 intent 탐지 → 경쟁사 gap 분석 → 키워드 리서치
+- brand voice kit 추출 → managed remote 생성/수정 또는 tenant repo 직접 수정 → 발행 후 재검증
+
+MCP 도구 하나하나를 수동으로 호출하는 대신, sub-Skill이 올바른 순서와 인자로 도구를 자동 조합한다.
+페이지 생성·수정은 작업 목적에 따라 실행 경로를 고른다. Dashboard 상태, DB, preview/build, version 관리와 일치해야 하면 Anymorph MCP managed workflow를 사용한다. 사용자가 로컬 tenant repo 경로를 제공했거나 코드/컴포넌트/레이아웃을 직접 고쳐야 하면 Claude Code가 tenant repo를 직접 수정할 수 있다. 이 둘은 대체 관계가 아니라 서로 다른 실행 경로다.
+
+---
+
+## 2. AI 인용 패턴 (Citation Patterns)
+
+AI 엔진이 어떤 페이지를 인용 소스로 선택하는지는 공개된 연구와 역분석으로 파악된다.
+아래는 Anymorph가 확인한 핵심 패턴이다.
+
+### 2-1. 명확한 사실 진술
+
+- 검증 가능한 수치/날짜/이름이 있는 문장이 우선 인용된다.
+  - 좋음: "2024년 기준 국내 전기차 판매량은 17만 2천 대(한국자동차산업협회)."
+  - 나쁨: "최근 전기차 시장이 크게 성장했습니다."
+- 수치는 출처 명시와 함께 써야 인용 신뢰도가 올라간다.
+
+### 2-2. 구조화된 헤딩
+
+- H1 한 개 (페이지 intent를 한 문장으로 요약).
+- H2/H3 계층이 명확해야 LLM이 섹션 단위로 chunking한다.
+- 헤딩만 읽어도 페이지 전체 흐름이 파악되어야 한다.
+
+### 2-3. 자기완결적 단락
+
+- 한 단락 = 한 아이디어. LLM은 토큰 단위로 단락을 추출한다.
+- 전 단락을 읽지 않아도 이해되는 단락이 인용되기 쉽다.
+- 단락 길이는 3-6 문장 권장. 너무 길면 chunking 경계에서 의미가 잘린다.
+
+### 2-4. 출처 명시
+
+- 인용·통계·연구에 링크 또는 "(출처: …)" 표기.
+- 외부 권위 있는 출처(학술지, 정부 기관, 업계 표준 기관)를 인용하면
+  AI 엔진이 페이지를 신뢰 노드로 분류할 가능성이 높아진다.
+
+### 2-5. schema.org 구조화 데이터
+
+- FAQ → `FAQPage` schema: AI가 Q&A를 직접 추출해 답변에 포함.
+- HowTo → `HowToStep` schema: 단계별 가이드 인용 최적화.
+- Article → `datePublished`, `dateModified`, `author` 필드 필수.
+- 구조화 데이터는 Anymorph 페이지 생성 시 자동 삽입되지만,
+  `get_page` 도구로 확인 후 누락된 필드가 있으면 명시적으로 요청할 것.
+
+---
+
+## 3. 신뢰 신호 (Trust Signals)
+
+AI 인용 후보가 되려면 단순히 정보가 많은 것만으로는 부족하다.
+신뢰 신호가 쌓여야 한다.
+
+### 3-1. 브랜드 voice/tone 일관성
+
+- `get_brand_voice_kit` 도구로 추출한 tone(formal/conversational 등),
+  vocabulary, 금지 표현을 페이지 전체에 일관 적용.
+- AI는 일관성 없는 tone을 "복수 저자 or 저품질 콘텐츠"로 분류한다.
+
+### 3-2. Brand-curated 사실 우선
+
+- `search_living_document` 도구로 workspace의 brand-curated 사실 베이스를 조회.
+- 외부 출처를 쓰기 전에 living document에 동일 사실이 있는지 먼저 확인.
+- living document에 없는 사실을 추가하려면 사용자(브랜드 담당자)에게 확인 요청.
+
+### 3-3. 편향 없는 인용
+
+- 경쟁사·외부 출처도 팩트 근거로 인용하면 AI 엔진이 더 신뢰한다.
+- "우리 브랜드만 좋다"는 편향된 서술은 AI가 광고성 콘텐츠로 분류해 인용을 기피.
+- 균형 잡힌 비교 섹션(장단점, 시장 전반 현황)을 포함할 것.
+
+### 3-4. 발행 후 갱신 이력
+
+- `dateModified` 필드와 "마지막 업데이트: YYYY-MM-DD" 가시적 표기 필수.
+- AI는 갱신된 콘텐츠를 stale 콘텐츠보다 우선 인용한다.
+- `refreshing-existing-pages` Skill은 이 갱신 이력을 자동 관리한다.
+
+### 3-5. 도메인 depth
+
+- 같은 브랜드 도메인 내에 관련 페이지가 많을수록 도메인 권위가 높아진다.
+- 단발성 랜딩 페이지 하나보다 "keyword cluster" 전략(관련 키워드 10-20페이지 군집)이 효과적.
+- `creating-keyword-landing-pages` Skill은 cluster 단위 생성을 지원한다.
+
+---
+
+## 4. Authoring Execution Model
+
+Anymorph GEO Skill은 인증 모델을 사용자에게 설명하는 문서가 아니다. 핵심은 어떤 실행 경로를 선택할지다.
+
+| 경로 | 사용 시점 | 대표 도구/동작 |
+|------|-----------|----------------|
+| Managed remote generation | 새 페이지를 Dashboard/backend 상태와 맞춰 생성해야 할 때 | `generate_managed_pages` → `get_managed_operation` |
+| Managed remote edit | 기존 페이지를 원격 sandbox에서 수정하고 version/build handoff까지 남겨야 할 때 | `edit_managed_page` → 사용자 확인 → `confirm_managed_page_edit` |
+| Tenant repo direct edit | 사용자가 tenant repo 경로를 제공했거나 코드/레이아웃 직접 수정이 목적일 때 | 로컬 파일 수정 → repo build/test/review |
+| Research-only draft | 사용자가 먼저 방향, brief, 초안을 검토하려 할 때 | 리서치 요약과 authoring brief 출력 |
+
+도구 호출이 인증 문제로 실패하면 내부 인증 항목을 나열하지 말고, 실패한 단계와 다음 선택지만 짧게 말한다: 재인증 후 같은 경로 재시도, 가능한 다른 경로로 전환, 또는 research-only draft로 마무리.
+
+---
+
+## 5. Visibility Loop 5단계
+
+GEO 작업은 항상 이 루프를 따른다. 각 단계의 산출물이 다음 단계의 입력이다.
+
+```
+Audit → Diagnose → Research → Author → Verify
+```
+
+### 5-1. Audit (현재 가시성 측정)
+
+**도구**: `get_page_visibility`, `list_weak_intents`
+
+- `list_weak_intents(workspaceId)` → intent score가 임계값 미만인 페이지 목록.
+- `get_page_visibility(pageId)` → 특정 페이지의 intent별 visibility score.
+- **산출물**: 보강이 필요한 intent 목록 + 현재 점수 분포.
+
+**트리거 Skill**: `recovering-weak-intents`, `verifying-published-pages`
+
+### 5-2. Diagnose (약한 지점 진단)
+
+**도구**: `get_competitor_gap`, `get_page_insights`
+
+- `get_competitor_gap(pageId)` → 경쟁사 대비 우리 페이지가 다루지 못한 주제.
+- `get_page_insights(pageId)` → 페이지 구조·사실 밀도·신뢰 신호 점수.
+- **산출물**: 보강 대상 섹션 목록, 경쟁사가 커버하는 키워드 gap.
+
+### 5-3. Research (보강 자료 수집)
+
+**도구**: `search_keywords`, `serp_snapshot`, `search_living_document`
+
+- `search_keywords(query, locationCode, languageCode)` → 관련 키워드 + 검색량/난이도.
+- `serp_snapshot(keyword)` → 현재 SERP 상위 결과 구조 파악.
+- `search_living_document(workspaceId, query)` → brand-curated 사실 베이스 조회.
+- **산출물**: 사용할 키워드 목록, 인용할 사실 목록, 경쟁 페이지 구조 패턴.
+
+**주의**: `search_keywords`가 인증/사용량 문제로 실패하면 키워드 리서치를 건너뛰고 사용자 제공 키워드로 진행한다.
+
+### 5-4. Author (페이지 생성/갱신)
+
+**도구**: `get_brand_voice_kit`, `get_workspace_instructions`, `generate_managed_pages`, `edit_managed_page`, `confirm_managed_page_edit`, `get_managed_operation`
+
+- `get_brand_voice_kit(workspaceId)` → tone, vocabulary, 금지 표현.
+- `get_workspace_instructions(workspaceId)` → 페이지 생성 시 추가 지침.
+- 새 페이지는 Research 단계 산출물을 `title`, `description`, `context`로 합성해 `generate_managed_pages`를 호출한다.
+- JSON-LD는 raw tool input으로 전달하지 않는다. `context`에 structured data intent만 적고, 실제 schema.org 출력은 생성 파이프라인이 페이지 타입/상품/FAQ 데이터로 만들게 둔다.
+- 기존 페이지는 진단 결과를 edit prompt로 합성해 `edit_managed_page`를 호출하고, 사용자 승인 후 `confirm_managed_page_edit`를 호출한다.
+- tenant repo 직접 수정 경로에서는 MCP write tool 대신 로컬 파일을 수정하고 repo의 build/test/review 절차를 따른다.
+- 상태는 별도 MCP-only operation record가 아니라 `get_managed_operation`으로 기존 batch/session/page 상태를 읽는다.
+- **산출물**: 선택한 경로에 따라 Dashboard와 같은 DB 상태/preview/version이 남는 managed operation, 또는 tenant repo의 코드 변경.
+
+**트리거 Skill**: `creating-keyword-landing-pages`, `refreshing-existing-pages`
+
+### 5-5. Verify (발행 후 검증)
+
+**도구**: `get_page_visibility`, `get_page_insights`
+
+- 발행 후 24-72시간 대기 (AI 엔진 크롤 주기).
+- `get_page_visibility(pageId)` 재호출 → 점수 변화 확인.
+- 점수가 개선되지 않으면 Diagnose 단계로 되돌아가 원인 분석.
+- **산출물**: Before/After 가시성 점수 비교 리포트.
+
+**트리거 Skill**: `verifying-published-pages`
+
+---
+
+## 6. 공통 실패 모드 (Common Failure Modes)
+
+sub-Skill 작성 시 반드시 처리해야 하는 에러 케이스 목록.
+
+### 6-1. workspaceId 미일치
+
+**에러**: `WorkspaceClaimMismatchError`
+
+- JWT의 `workspaceIds` 배열에 포함된 ID만 사용 가능.
+- `list_workspaces()` 도구로 접근 가능한 workspace 목록을 먼저 조회.
+- 사용자가 다른 workspace ID를 요청하면 목록을 보여주고 재선택 유도.
+
+```
+❌ WorkspaceClaimMismatchError: workspace 'ws_xxxx' is not in your token.
+→ 접근 가능한 workspace: list_workspaces() 결과를 보여줄게요.
+```
+
+### 6-2. 도구 인증 또는 접근 실패
+
+- 실패한 도구와 영향받는 workflow 단계만 짧게 설명한다.
+- 가능한 우회 경로가 있으면 바로 제안한다.
+- 재인증이 필요한 경우에도 내부 인증 항목을 길게 나열하지 않는다.
+
+```
+search_keywords 호출이 인증 문제로 실패했습니다.
+→ 키워드 리서치를 건너뛰고 사용자 제공 키워드로 계속 진행할 수 있습니다.
+```
+
+### 6-3. DataForSEO 결과 0건 (비영어 시장)
+
+**증상**: `search_keywords` 결과가 빈 배열.
+
+- `(locationCode, languageCode)` pair가 맞지 않으면 결과 0건.
+- 기본값: Brand의 `primaryLocationCode` + `primaryLang` 자동 사용.
+- 비기본 시장(예: ko-KR이 아닌 en-US로 한국 쿼리) → `targetOverride` 인자 명시.
+- `get_brand_profile(workspaceId)` 로 `primaryLocationCode`, `primaryLang` 확인 후 정렬.
+
+```python
+# 예시: ko-KR 명시
+search_keywords(query="비건 화장품 추천", locationCode=2410, languageCode="ko")
+```
+
+### 6-4. Brand voice kit이 null
+
+**증상**: `get_brand_voice_kit` 반환값이 `null` or 빈 객체.
+
+- workspace에 Brand row가 없거나 voice kit이 미설정됨.
+- Fallback: `get_brand_profile(workspaceId)`로 브랜드 기본 정보(이름, 업종) 추출.
+- 사용자에게 Anymorph Dashboard에서 Brand 설정을 완료해 달라고 안내.
+- voice kit 없이 작성할 경우 "중립적 professional tone"으로 폴백하고 명시.
+
+```
+⚠️ brand voice kit을 찾을 수 없습니다.
+→ Anymorph Dashboard > Brand 설정에서 voice kit을 등록해주세요.
+→ 지금은 중립적 professional tone으로 초안을 작성합니다.
+```
+
+### 6-5. 키워드 언어와 brand primaryLang 불일치
+
+**증상**: 키워드는 영어인데 brand primaryLang은 ko-KR.
+
+- `get_brand_voice_kit(workspaceId)`에서 `primaryLang`, `supportedLangs` 먼저 확인.
+- 사용자가 영어 키워드를 요청했는데 brand가 한국어 전용이면:
+  1. `supportedLangs`에 en-US가 포함되어 있는지 확인.
+  2. 포함: 해당 language로 page 생성 진행.
+  3. 미포함: 사용자에게 언어 범위 확인 요청.
+- 페이지 언어와 SERP 타겟 언어가 다르면 AI 인용 신뢰도 하락.
+
+```
+⚠️ 요청 키워드 언어(en)가 brand primaryLang(ko)과 다릅니다.
+→ supportedLangs: [ko, en] — en-US 타겟으로 진행하겠습니다.
+```
+
+### 6-6. 페이지 미존재 (refreshing 시나리오)
+
+**증상**: `get_page(pageId)` → 404 or `PageNotFoundError`.
+
+- pageId 오타 or 삭제된 페이지.
+- `list_managed_pages(workspaceId, query/path/status)` 로 유사 경로와 같은 `clusterKey` 후보 제안.
+- 없으면 `creating-keyword-landing-pages` Skill로 신규 생성 전환 안내.
+
+---
+
+## Author Note
+
+> **Author note**: 이 원칙은 sub-Skill에서 본문에 인라인으로 인용하지 마세요.
+> 필요한 항목만 한 줄 링크로 참조하세요.
+> 예: `자세한 인용 패턴은 [shared/geo-principles.md §2](../shared/geo-principles.md#2-ai-인용-패턴-citation-patterns) 참조`

package/dist/skillpacks/geo/shared/vertical-playbooks/beauty.md

@@ -0,0 +1,65 @@
+# Beauty SEO/GEO/AEO Playbook
+
+## Scope
+
+Reusable guidance for beauty, skincare, makeup, haircare, and personal care. Use this for vertical strategy, diagnosis, and page planning. Keep tenant-specific bets in `agent/STRATEGY.md`.
+
+## Entity And Demand Patterns
+
+- Beauty demand is combinatorial: `ingredient x concern`, `product type x skin type`, `routine step x concern`, `finish/effect x use case`, and `authenticity/where-to-buy x product`.
+- Core entities: product type, ingredient, skin or hair concern, skin or hair type, routine step, finish, retailer, claim, evidence, review.
+- Common modifiers include oily, dry, sensitive-feeling, acne-prone, mature, darker skin tones, fragrance-free, travel-size, and refillable. Pregnancy/lactation and disease-adjacent modifiers require review before use.
+- Users need discovery and reassurance: fit, safety, authenticity, real-user experience, expected results, and where to buy.
+- Cluster by reusable intent, not exact keyword wording. One strong canonical asset should cover related phrasings when the user need is the same.
+
+## Search And AI Surfaces
+
+- Standard organic results for education and shopping research.
+- Concern-led pages may appear in AI search experiences only when they are crawlable, indexed, snippet-eligible, helpful, and policy-compliant. Inclusion is not guaranteed.
+- Product snippets and merchant listings for buyable PDPs.
+- Google Images, Lens, shopping modules, retailer PDPs, and marketplace search.
+- Review, editorial, and comparison surfaces for `best for`, concern, and product-alternative intent.
+- Brand-owned pages should be the official source for education, product facts, authenticity, and usage guidance.
+- Retailer surfaces often win on availability, shipping, returns, and review volume. Treat them as part of the journey.
+
+## Asset Plays
+
+- Concern hubs: explain the concern, safe language boundaries, ingredient/product fit, routine options, and when to seek professional advice.
+- Ingredient hubs: define the ingredient, common pairings, limits, product matches, formulation nuance, and evidence level.
+- Product type x skin type pages: help users narrow choices with texture, finish, compatibility, and routine role.
+- Routine guides: morning/night order, what to combine, what to avoid, product bundles, and user context.
+- PDP upgrades: complete product identity, ingredients, usage, texture, imagery, reviews, price, availability, and structured data.
+- Authenticity / where-to-buy pages: official retailer list, counterfeit avoidance, seller trust, shipping, returns, and FAQ.
+- Comparison pages: compare ingredients, products, or routines with explicit criteria, pros/cons, and user-fit guidance.
+- Review and UGC summaries: summarize representative themes without amplifying unsubstantiated therapeutic, safety, or atypical-result claims.
+
+## Evidence And Claim Safety
+
+- Cosmetic claims must be truthful, not misleading, and supported by visible evidence.
+- Disease treatment, prevention, structure/function, SPF, hair-loss, acne, eczema, rosacea, psoriasis, melasma, and wrinkle claims need extra review.
+- Pregnancy, lactation, children-related, SPF, acne, dandruff, hair growth/loss, eczema, rosacea, psoriasis, and melasma claims require explicit brand-approved evidence and regulatory review.
+- Agents must not infer pregnancy safety, disease suitability, or therapeutic effect from ingredient lists.
+- Ingredient guidance should distinguish ingredient presence from concentration, formulation, pH, delivery system, contact time, and product-level testing.
+- Do not let visible copy, FAQ, UGC quotes, structured data, influencer scripts, and merchant data drift apart.
+- Do not imply atypical before/after outcomes are normal unless the evidence supports that framing.
+- Avoid fake reviews, review gating, undisclosed incentives, and pay-to-play comparison placements.
+- Prefer suitability, routine role, texture, finish, ingredient role, and user context over therapeutic promises.
+- Price, availability, shipping, returns, and authorized retailer facts are freshness-sensitive.
+
+## Measurement Signals
+
+- Non-brand ingredient, concern, product type, and routine impressions.
+- PDP conversion, retailer outbound CTR, add-to-cart, checkout starts, and where-to-buy interactions.
+- Product snippet and merchant listing eligibility, errors, and warnings.
+- Review coverage, review freshness, UGC disclosure coverage, and claim QA pass rate.
+- AI mention share, owned citation share, answer accuracy, and surfaced competitor/reviewer sources.
+- Availability accuracy and consistency across brand site, schema, merchant data, and retailers.
+
+## Anti-Patterns
+
+- Thin programmatic pages for every ingredient/concern pair without distinct evidence.
+- Unsupported cosmetic-to-drug claims in headings, FAQs, UGC pull-quotes, or schema.
+- Product pages that hide price, availability, shipping, returns, or seller trust.
+- Text-light pages where key facts only exist in images or video.
+- `best for` pages without comparison logic, user context, pros/cons, or proof.
+- Inconsistent product facts across owned site, merchant data, and retailer listings.

package/dist/skillpacks/geo/shared/vertical-playbooks/commerce.md

@@ -0,0 +1,65 @@
+# Commerce SEO/GEO/AEO Playbook
+
+## Scope
+
+Reusable guidance for ecommerce and consumer goods outside beauty-specific use cases. Use this for vertical strategy, diagnosis, and page planning.
+
+## Entity And Demand Patterns
+
+- Map demand across category, subcategory, product type, product family, SKU, and variant.
+- Common patterns: `category x use case`, `product type x audience`, `product x comparison`, `product x review`, `product x problem/compatibility`, and `SKU/model x spec/fit/size/material`.
+- Category pages are broad-intent assets. PDPs are exact product entity assets. Buying guides, comparisons, and reviews are decision-stage assets.
+- Variant pages and feeds are evidence layers for size, color, material, bundle, price, availability, and compatibility.
+- Prefer stable identifiers: brand, MPN, GTIN/EAN/UPC, SKU, model, and variant group.
+
+## Search And AI Surfaces
+
+- Web results, product rich results, merchant listings, shopping tabs, image/visual search, local inventory, retailer search, marketplace search, and AI answers that synthesize product and review content.
+- The same product should be understandable from page HTML, structured data, and feed data.
+- AI visibility is indirect and not guaranteed. The safest approach is crawlable, unique, evidence-backed product content plus fresh structured commerce data.
+- Owned pages, feeds, and marketplace/retailer listings should reinforce the same product entity facts.
+
+## Asset Plays
+
+- Category x use-case pages: pair category terms with real jobs-to-be-done, occasions, constraints, and product routing.
+- PDP upgrades: exact title, core attributes, specs, compatibility, materials, dimensions, images, shipping, returns, price, stock, reviews, and schema.
+- SKU-level evidence: publish model/SKU/GTIN/MPN where available and keep identifiers consistent across owned and syndicated surfaces.
+- Product schema and merchant listings: use Product/Offer data that matches visible content. Use variant grouping for product families.
+- Faceted navigation: control filters, sorts, and parameter URLs. Index only useful, distinct, demand-backed pages.
+- Variant strategy: define single PDP vs variant URL handling, canonicalization, inventory state, and ProductGroup data where appropriate.
+- Product feeds: maintain feed hygiene for large, fast-changing, or high-variant catalogs.
+- Reviews: support customer, expert, and editorial reviews with firsthand evidence, measurements, pros/cons, and best-fit context.
+- Comparison and buying guides: `best for X`, `A vs B`, `best under Y`, and `what to choose if Z`, with clear links to PDPs and category hubs.
+- Images/video: show the actual product, scale, setup, fit, usage, and variant differences.
+
+## Evidence And Claim Safety
+
+- Prefer verifiable attributes over persuasion copy.
+- Separate fact from marketing language.
+- Only claim specs, compatibility, performance, material, certifications, warranty, or `best for` statements when evidence exists.
+- Regulated or high-risk goods need separate review: supplements, OTC drugs, alcohol, nicotine, medical devices, children’s products, electronics safety, automotive parts, and sustainability claims.
+- Comparisons and guides need measurements, criteria, firsthand observations, and explicit tradeoffs.
+- Keep page, schema, feed, and retailer facts synchronized.
+- Freshness-sensitive facts include price, availability, shipping, returns, sale windows, inventory, policy details, out-of-stock, discontinued, backorder, and promo states.
+- If reviews or comparisons monetize outbound links, keep disclosures and link handling compliant.
+
+## Measurement Signals
+
+- Indexation and crawl coverage for categories, PDPs, and variant pages.
+- Product rich result and merchant listing eligibility, errors, and warnings.
+- Feed disapprovals, mismatch rates, attribute completeness, and freshness latency.
+- Impressions/clicks by category, use-case, comparison, PDP, and SKU query classes.
+- PDP conversion, add-to-cart, category-to-PDP CTR, and marketplace/retailer share.
+- Review coverage, rating volume, product identifier coverage, and valid schema coverage.
+- AI mention, owned citation, cited source mix, and branded query lift after guide/review publication.
+
+## Anti-Patterns
+
+- One thin PDP template repeated across many SKUs.
+- Category pages that are only product grids.
+- Query-fanout pages for every wording variation.
+- `Best` or review pages with no firsthand evidence, measurements, or tradeoffs.
+- Variant facts hidden behind JS selectors or collapsed product families.
+- Price, stock, shipping, or return mismatches between page, schema, feed, and retailer.
+- Missing or unstable product identifiers across syndication channels.
+- Treating GEO/AEO as separate from product data quality, crawlability, and evidence.

package/dist/skillpacks/geo/shared/vertical-playbooks/ota.md

@@ -0,0 +1,62 @@
+# OTA / Travel SEO/GEO/AEO Playbook
+
+## Scope
+
+Reusable guidance for OTA, travel marketplace, destination, lodging, tour, and things-to-do businesses. Use this for vertical strategy, diagnosis, and page planning.
+
+## Entity And Demand Patterns
+
+- Travel demand mixes entity-led planning with date, price, availability, route, and booking-led transactions.
+- Core entities: destination, neighborhood, property, operator, attraction, route, itinerary, traveler type, season, event, availability, price, review, and policy.
+- Durable patterns include `destination x traveler type`, `destination x use case`, `destination x season`, `destination x trip length`, `destination x things-to-do`, `destination x where-to-stay`, and `property/tour x availability + price + review`.
+- Best travel pages connect entities across trip planning, local context, inventory, and booking instead of treating keywords as isolated posts.
+
+## Search And AI Surfaces
+
+- Web results, maps/local packs, rich results, review surfaces, partner/affiliate listings, tourism boards, and AI travel-planning answers.
+- Travel planning pages should answer: who it is for, when to go, how long to spend, what to do in order, where to stay, cost assumptions, what is included, and what may be unavailable or seasonal.
+- Strong travel content is specific, itinerary-shaped, comparison-friendly, source-aware, and explicit about freshness and uncertainty.
+- Maps/local visibility is part of SEO for physical travel entities, not a separate concern.
+
+## Asset Plays
+
+- Destination hubs: neighborhoods, attractions, maps, audience fit, seasonality, and links to stays/tours/itineraries.
+- Itinerary pages: common durations, ordered plans, timing, transport, tradeoffs, alternatives, and booking modules.
+- Things-to-do pages: attraction entities with hours, access, cost/free status, location, seasonality, and best-fit traveler types.
+- Where-to-stay pages: neighborhood fit, accommodation types, budget bands, transit access, practical considerations, and inventory links.
+- Property/tour pages: price, availability, amenities, images, geo, cancellation, inclusions, exclusions, and review evidence.
+- Local readiness: name, address, geo, hours, category, business details, review signals, and profile consistency.
+- Partner/affiliate surfaces: keep names, location data, inventory facts, ratings, images, and policies consistent across syndicated listings.
+
+## Evidence And Claim Safety
+
+- Never publish stale availability or stale prices as if live.
+- Label prices, taxes, mandatory fees, `from` pricing, seasonal ranges, currency, cancellation terms, and uncertain timing clearly.
+- Distinguish live, feed-supplied, estimated, seasonal, and stale facts.
+- Separate evergreen editorial guidance from volatile booking facts.
+- Structured data must match visible page content and page purpose.
+- Do not mark up hidden, fake, misleading, or irrelevant review content.
+- Distinguish editorial recommendation, user review, partner-supplied fact, live feed fact, and estimated itinerary timing.
+- Safety content should use sourced, dated practical considerations. Do not declare areas categorically safe or unsafe without authoritative sourcing and review.
+- Use Google Business Profile, VacationRental, and things-to-do markup/feed concepts only when the tenant is eligible and the data matches visible content.
+- Freshness-sensitive facts include availability, hours, closures, seasonal access, review dates, policy changes, taxes, fees, inclusions, and cancellation terms.
+
+## Measurement Signals
+
+- Destination, itinerary, things-to-do, and where-to-stay impressions.
+- Indexation and rich-result coverage for key entity pages.
+- Booking conversion, inventory clickthrough, partner outbound CTR, and assisted conversions.
+- Map/profile visibility, direction/call/website actions, review volume, rating, and reply rate.
+- Freshness coverage for price, availability, hours, and policy fields.
+- AI mention, owned citation, itinerary answer inclusion, and cited source mix.
+
+## Anti-Patterns
+
+- Thin `best things to do` pages with no entity depth.
+- Destination pages with no traveler, season, or use-case segmentation.
+- Generic itinerary copy reused across destinations.
+- Mixing evergreen advice with stale booking facts.
+- Schema that does not match visible content.
+- Review markup without trustworthy visible reviews.
+- Hiding fees, blackout periods, closures, or booking constraints.
+- Contradictory partner and first-party listings.

package/dist/skillpacks/geo/shared/vertical-playbooks/saas.md

@@ -0,0 +1,64 @@
+# SaaS SEO/GEO/AEO Playbook
+
+## Scope
+
+Reusable guidance for B2B SaaS and software-led subscription businesses. Use this for vertical strategy, diagnosis, and page planning. Keep tenant-specific positioning and bets in `agent/STRATEGY.md`.
+
+## Entity And Demand Patterns
+
+- SaaS demand is entity-led: category, problem, role, workflow, use case, feature, integration, competitor, pricing model, security standard, and deployment model.
+- Map demand by buying stage: problem, use case, workflow, integration, evaluation, validation, implementation, and support.
+- Common patterns: `role x problem`, `workflow x tool`, `integration x integration`, `feature x use case`, `competitor x alternative`, `category x industry`.
+- Treat docs, integrations, trust pages, and comparisons as demand capture assets, not only support material.
+- Build pages that stand alone for users and search systems: clear scope, crawlable text, explicit product facts, stable terminology, self-contained answers, and proof near claims.
+
+## Search And AI Surfaces
+
+- Web search, AI answer surfaces, Bing/Copilot-style citation layers, review platforms, docs, help centers, changelogs, trust centers, and status/security pages.
+- Review platforms such as G2, Capterra, TrustRadius, and analyst-style marketplaces influence validation and external authority.
+- Documentation can capture high-intent implementation queries and assist activation when it links to product value and next steps.
+- AI search experiences may synthesize information from multiple indexed sources. Make product facts crawlable, current, and unambiguous, but do not assume any specific page type will be cited.
+
+## Asset Plays
+
+- Category pages: define the category, who it is for, differentiation, proof, pricing path, and links to deeper assets.
+- Problem pages: explain pain, root causes, measurable outcomes, and product fit. Avoid generic thought leadership.
+- Use-case pages: role, industry, scenario, inputs, outputs, success metrics, and examples.
+- Workflow pages: before/after process, systems touched, time/risk savings, and fit constraints.
+- Integration pages: what connects, triggers/actions, setup path, limitations, related docs, and adjacent integrations.
+- Alternative/comparison pages: objective criteria, current facts, tradeoffs, methodology, and buyer-help framing.
+- Docs-assisted activation: prerequisites, architecture notes, examples, demos, templates, and product pathways.
+- Trust pages: verified security, privacy, compliance, and admin-control facts with artifact paths. Do not list controls or certifications unless currently supported.
+- Proof assets: case studies, testimonials, review profiles, benchmarks, analyst mentions, and compliant review coverage/recency.
+
+## Evidence And Claim Safety
+
+- Attribute substantive claims to first-party product facts, public docs, customer evidence, third-party reviews, benchmarks, or trust artifacts.
+- Separate product facts from positioning. `Supports SAML SSO` is not the same as `best enterprise security`.
+- Comparison claims must be truthful, current, non-deceptive, and clear about methodology.
+- Do not imply certifications, integrations, customer logos, uptime, ROI, feature parity, or compliance posture without proof.
+- Security, compliance, privacy, and regulated-industry claims need an artifact path: trust center, policy page, release note, support doc, or certification.
+- Do not claim AI capability, autonomy, accuracy, compliance suitability, legal/medical/security adequacy, or productivity gains without product evidence and disclaimers.
+- Pricing, plan limits, edition availability, API limits, add-ons, and enterprise-only capabilities must match product docs and pricing pages.
+- Use careful ROI language. Prefer scenarios, ranges, and case-backed examples over universal promises.
+- AI-assisted content needs human editorial control; scaled low-value SaaS pages are a quality risk.
+
+## Measurement Signals
+
+- Indexation and crawl health by page type.
+- Non-brand impressions and rankings for category, problem, integration, workflow, and comparison intents.
+- AI citation, supporting-link appearance, and answer inclusion for tracked prompts.
+- Demo/trial starts, product-qualified signups, qualified pipeline, and win-rate influence.
+- Docs-to-signup assists, docs-to-demo assists, docs CTA CTR, and activation by doc cluster.
+- Review-platform completeness, rating, review coverage, recency, representativeness, and compliant solicitation.
+- Trust-page engagement and enterprise conversion assists.
+
+## Anti-Patterns
+
+- Thin `best X`, industry, or city pages with no real differentiation.
+- Treating GEO as separate from crawlability, canonical hygiene, and helpful content.
+- Hiding product facts behind JS, login walls, PDFs, or vague marketing copy.
+- Attack-style comparison pages.
+- Docs that rank but never route users to activation.
+- Security or compliance claims without proof paths.
+- Schema, AI text generation, or review widgets used as shortcuts to trust.