anymorph 0.2.5 → 0.4.0

package/dist/skillpacks/geo/skills/geo-pages-diagnosis/references/diagnosis-contract.md

@@ -19,18 +19,35 @@ Do not choose final production routes. The page generation executor owns route c
 - brand is mentioned but not recommended
 - low visibility and no page exists
 
+## Freshness And Indexing Guard
+
+Do not treat a newly generated page as weak just because it has no traffic,
+GSC impressions, or AI citations yet. If a generated page was published less
+than 7 days ago, return `no_action` / monitor unless there is a concrete
+non-performance defect such as wrong intent, crawl/indexation blocker,
+duplicate/cannibalization, missing brand/entity clarity, or factual/product
+claim error.
+
+If a generated page is not indexed after 7 days, flag this in the diagnosis.
+Use `technical_issue` when indexation, crawlability, canonical, sitemap,
+robots, noindex, render, or status-code evidence identifies a blocker. Use
+`insufficient_evidence` when indexation state is unknown but the page still has
+no measurable crawl, GSC, or visibility signal. Do not turn this into a content
+update by default.
+
 ## Evidence Order
 
 Use the cheapest sufficient evidence.
 
 1. Common run context and routed candidates.
-2. `list_geo_strategy_candidates` for the first generated-page or no-page candidate slice.
+2. `list_geo_page_candidates` for the first generated-page or no-page candidate slice.
 3. `get_geo_intent_diagnostic` for one intent before deeper checks.
-4. For commerce workspaces and create_geo_page candidates, `get_intent_products` to verify catalog fit and product ids.
-5. `get_page_insights`, `get_page_visibility`, or `list_ai_responses` for prompt/answer evidence.
-6. `get_page_content` or `get_page_source_code` for generated page body or technical diagnosis.
-7. `web_scrape` only for a specific cited/recommended competitor URL.
-8. `serp_snapshot` or `dataforseo_research` only when the evidence depends on external search demand or SERP shape.
+4. For commerce workspaces and hub/spoke create candidates, `get_intent_products` to verify catalog fit and product ids.
+5. `get_page_insights` default compact mode for page decision evidence; use `mode: "full"`, `get_page_visibility`, or `list_ai_responses` only when raw prompt/answer evidence changes the recommendation.
+6. Page age and indexation evidence before diagnosing low performance on existing generated pages.
+7. `get_page_content` for generated page body or technical diagnosis.
+8. `web_scrape` only for a specific cited/recommended competitor URL.
+9. `serp_snapshot` or `dataforseo_research` only when the evidence depends on external search demand or SERP shape.
 
 ## Root Cause Buckets
 
@@ -56,13 +73,11 @@ Use `authority_gap` only when external citation evidence or recommendation reaso
 
 Allowed families:
 
-- `create_geo_page`
-- `iterate_geo_page`
-- `re_research_geo_page`
-- `regenerate_geo_page`
-- `retire_geo_page`
-- `expand_adjacent_intent`
-- `fix_technical_issue`
+- `create_hub_page`
+- `create_spoke_page`
+- `update_existing_page`
+- `replace_existing_page`
+- `remove_or_merge_page`
 - `no_action`
 
 ## Output
@@ -73,7 +88,9 @@ Do not write intermediate diagnosis JSON files directly.
 
 Do not include `workspaceId`, `runId`, `channel`, final action id, final URL, or final `assetType`; the orchestrator and executor derive them.
 
-For commerce workspaces, create_geo_page proposals must include product evidence from `get_intent_products` when catalog fit is fit or weak-fit. Put the selected product ids in `target.targetProductIds`. If catalog fit is no-fit, reject the create action or propose a non-product informational direction.
+For commerce workspaces, `create_hub_page` and `create_spoke_page` proposals must include product evidence from `get_intent_products` when catalog fit is fit or weak-fit. Put the selected product ids in `target.targetProductIds`. If catalog fit is no-fit, reject the create action or propose a non-product informational direction.
+
+For create proposals, put `target.pageRole: "HUB"` on `create_hub_page` and `target.pageRole: "SPOKE"` on `create_spoke_page`.
 
 Use this shape:
 
@@ -84,11 +101,11 @@ Use this shape:
     {
       "intentId": "intent_123",
       "candidateType": "low_visibility_no_page",
-      "target": { "suggestedSlug": "optional-non-binding-hint", "targetProductIds": ["optional-commerce-product-id"] },
+      "target": { "suggestedSlug": "optional-non-binding-hint", "pageRole": "HUB", "targetProductIds": ["optional-commerce-product-id"] },
       "rootCauses": [
         { "bucket": "intent_coverage_gap", "confidence": 0.81, "evidence": ["No page covers the weak intent."] }
       ],
-      "actionFamily": "create_geo_page",
+      "actionFamily": "create_hub_page",
       "operations": ["Generate a CMS-backed GEO page for the intent"],
       "priority": "high",
       "confidence": "high",
@@ -100,7 +117,9 @@ Use this shape:
     }
   ],
   "rejected": [
-    { "ref": "page_456", "reason": "Existing page is healthy." }
+    { "ref": "page_456", "reason": "Existing page is healthy." },
+    { "ref": "page_789", "reason": "Generated page was published less than 7 days ago; monitor until the minimum observation window has passed." },
+    { "ref": "page_999", "reason": "Generated page is not indexed after 7 days; flag indexation analysis before recommending content changes." }
   ]
 }
 ```

package/dist/skillpacks/geo/skills/geo-pages-diagnosis/references/workflow.md

@@ -30,6 +30,9 @@ It works on pages where:
   - `geo_page_intent_visibility_gaps`
   - `geo_page_performance`
   - `geo_strategy_actions_recent`
+- page age and indexation signals when present:
+  - `createdAt`, `generatedAt`, `deployedAt`, `publishedAt`, or equivalent page timestamp
+  - indexation state, indexed URL inspection state, GSC impressions/clicks, crawler logs, or sitemap/canonical errors
 - generated page scrape when needed
 - representative prompts
 - AI answer samples
@@ -50,11 +53,32 @@ Drop candidates when:
 - recent action mask suppresses the same action
 - tenant strategy forbids generated pages for that intent class
 - evidence is too thin
+- the only negative evidence is missing performance data for a fresh generated page still inside the minimum observation window
 
 ### 2. Classify Candidate Case
 
 Assign one primary case.
 
+### Freshness and Indexing Guard
+
+Before using Case A for an existing generated page, check page age and indexation state.
+
+Use a minimum observation window of 7 days after the page was first generated, deployed, or published. If the generated page was published less than 7 days ago, default to `no_action` / monitor unless there is a concrete non-performance defect:
+
+- wrong intent or prompt mismatch
+- broken route, bad canonical, blocked crawl, noindex, sitemap omission, or render failure
+- duplicate/cannibalizing page
+- missing brand/entity clarity visible in the page content
+- factual, compliance, or product-claim defect
+
+For fresh pages, do not use low visibility, zero traffic, zero GSC impressions, or zero AI citations alone as evidence for `update_existing_page`, `replace_existing_page`, or `remove_or_merge_page`. Record the page in `rejected` or `noActionRationale` with a monitor note and the next evaluation date when possible.
+
+If a generated page is not indexed after 7 days, flag this in the analysis. Treat it as a possible `technical_issue` or `insufficient_evidence` finding depending on the evidence:
+
+- Use `technical_issue` when there is an indexation, crawlability, canonical, sitemap, robots, noindex, render, or status-code signal.
+- Use `insufficient_evidence` when indexation status is unknown but there are still no GSC impressions, crawler hits, or external visibility signals after the 7-day window.
+- Prefer a diagnostic note or SEO technical follow-up over a content update unless the page content itself is also defective.
+
 #### A. Generated Page Exists But Visibility Is Low
 
 Use when:
@@ -62,6 +86,7 @@ Use when:
 - `geo_page_count > 0`
 - `current_visibility` is low
 - quadrant is mostly `absent`, `cited_unnamed`, or `mentioned_not_recommended`
+- the page is outside the freshness guard, or there is a concrete non-performance defect
 
 Diagnosis questions:
 
@@ -120,6 +145,7 @@ Default evidence:
 - representative prompts
 - quadrant rates
 - page performance summary
+- page age and indexation status
 - AI answer excerpts
 
 Fetch generated page scrape when:
@@ -157,22 +183,23 @@ Use `authority_gap` only when external citation evidence or recommendation reaso
 
 Allowed action families:
 
-- `create_geo_page`
-- `iterate_geo_page`
-- `re_research_geo_page`
-- `regenerate_geo_page`
-- `retire_geo_page`
-- `expand_adjacent_intent`
-- `fix_technical_issue`
+- `create_hub_page`
+- `create_spoke_page`
+- `update_existing_page`
+- `replace_existing_page`
+- `remove_or_merge_page`
 - `no_action`
 
 Routing defaults:
 
-- No page + low visibility + absent -> `create_geo_page`
-- Existing page + intent mismatch -> `regenerate_geo_page` or `retire_geo_page`
-- Existing page + weak content -> `iterate_geo_page`
-- Existing page + missing evidence -> `re_research_geo_page`
-- Healthy page -> `expand_adjacent_intent` or `no_action`
+- Broad uncovered intent that should anchor related questions -> `create_hub_page`
+- Narrow uncovered or non-overlapping long-tail intent under an existing hub -> `create_spoke_page`
+- Existing page has the right role and intent but needs content, proof, comparison, research, or technical improvement -> `update_existing_page`
+- Existing page slot should remain but the angle/brief is fundamentally wrong -> `replace_existing_page`
+- Existing page should not remain independent because it is duplicate, overlapping, or should consolidate into a stronger page -> `remove_or_merge_page`
+- Healthy page or weak evidence -> `no_action`
+- Fresh generated page with no concrete defect -> `no_action` until the minimum observation window has passed
+- Page not indexed after 7 days -> flag the indexation issue in analysis; route to `no_action` or a technical follow-up unless there is enough evidence for a concrete fix
 
 ### 6. Output
 
@@ -186,11 +213,13 @@ Return a compact diagnosis for each accepted action:
 - concrete operations
 - evidence references
 - why other actions were rejected
+- freshness/indexation rationale for monitored fresh pages or pages not indexed after 7 days
 
 For create actions:
 
 - do not invent final URL
 - optional `target.suggestedSlug` is non-binding only
+- include `target.pageRole` as `HUB` for `create_hub_page` and `SPOKE` for `create_spoke_page`
 
 ## Examples
 
@@ -199,15 +228,32 @@ For create actions:
 If a generated page exists but competitors win because their cited pages contain stronger comparison criteria:
 
 - root cause: `comparison_gap`
-- action family: `iterate_geo_page`
+- action family: `update_existing_page`
 - operation: add comparison criteria, direct recommendation framing, and proof points
 
+### Existing Generated Page Is Fresh
+
+If a generated page was published less than 7 days ago and the only weak signals are zero traffic, zero GSC impressions, or zero AI citations:
+
+- root cause: `insufficient_evidence`
+- action family: `no_action`
+- operation: monitor until the minimum observation window has passed
+
+### Existing Generated Page Is Not Indexed After 7 Days
+
+If a generated page is not indexed after 7 days:
+
+- root cause: `technical_issue` when crawl/indexation evidence identifies a blocker
+- root cause: `insufficient_evidence` when indexation status is unknown
+- action family: `no_action` or technical follow-up, not a content update by default
+- operation: flag the indexation issue in the analysis and recommend checking sitemap, canonical, robots, noindex, status code, and rendered HTML
+
 ### No Page Exists
 
 If no discovered or generated page covers a weak intent:
 
 - root cause: `intent_coverage_gap`
-- action family: `create_geo_page`
+- action family: `create_hub_page`
 - operation: generate a CMS-backed GEO page for the intent
 
 ## Guardrails
@@ -215,5 +261,9 @@ If no discovered or generated page covers a weak intent:
 - Use CMS-backed generation only.
 - Do not use legacy Astro paths.
 - Do not duplicate a discovered page that clearly owns the intent.
-- Do not regenerate when a targeted iteration is sufficient.
+- Do not replace a page when a targeted update is sufficient.
+- Do not create a spoke page unless the differentiation from the hub or existing page is explicit.
 - Do not diagnose authority from low visibility alone.
+- Do not diagnose a fresh generated page as underperforming from missing performance data alone.
+- Do not recommend generated-page content updates for pages published less than 7 days ago unless a concrete non-performance defect is present.
+- Do flag pages that are not indexed after 7 days, but separate indexation analysis from content-quality analysis.

package/dist/skillpacks/geo/skills/seo-ecommerce-opportunity/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: seo-ecommerce-opportunity
+description: Use when diagnosing ecommerce SEO opportunities for product, category, collection, shopping-intent SERPs, Product schema, offers, reviews, availability, shipping, return policy, or merchant page actions.
+---
+
+# SEO Ecommerce Opportunity
+
+Use this skill only when ecommerce signals exist. It adapts `claude-seo`
+ecommerce, schema, product, and competitor-page patterns to Anymorph action
+generation.
+
+## Activation
+
+Activate when any of these are true:
+
+- product catalog exists.
+- URLs contain product, collection, category, cart, checkout, shop, or pricing
+  product patterns.
+- Product or Offer schema exists or should exist.
+- DFS SERP shows shopping/product/category/listicle intent.
+- workspace business type is ecommerce or commerce-enabled.
+
+## Artifact
+
+Write outputs under:
+
+```text
+agent/seo/seo-ecommerce-opportunity/{runId}/
+```
+
+## References
+
+- `references/ecommerce-rules.md` for product/category/schema rules.
+- `../seo-opportunity-audit/references/action-contract.md` for output shape.
+- `../../shared/evidence-principles.md` for claim strength, source hierarchy,
+  freshness, structured-data, and GEO/AEO framing rules.
+- `../../shared/vertical-playbooks/commerce.md` for general commerce patterns.
+- `../../shared/vertical-playbooks/beauty.md` instead of, or in addition to,
+  `commerce.md` when the catalog is beauty, skincare, makeup, haircare, or
+  personal care. Beauty rules take precedence for cosmetic, ingredient,
+  review/UGC, and regulated-claim safety.
+
+Read only the matching vertical playbook(s). Treat vertical playbooks as
+heuristics for diagnosis and action selection, not as evidence for claims.
+
+## Workflow
+
+1. Read product catalog, intent-product mappings, CMS/GEO pages, and product URLs.
+2. Load `../../shared/evidence-principles.md` and the matching commerce/beauty
+   playbook when product, category, review, schema, or shopping-surface findings
+   are in scope.
+3. Inspect product and category pages for title/meta, product description,
+   schema, offers, price, availability, reviews, shipping, return policy, images,
+   and FAQ-like buyer objections.
+4. Use DFS through the toolkit for shopping/product/listicle SERP evidence.
+5. Detect opportunities:
+   - product schema gap.
+   - offer/availability gap.
+   - review or aggregate rating evidence gap.
+   - merchant policy gap.
+   - category page gap.
+   - product comparison/buying guide gap.
+   - image/product rich result gap.
+6. Map actions to product-linked GEO page creation, CMS updates, schema fixes,
+   or third-party/manual tasks.
+
+## Output Files
+
+- `products.json`
+- `findings.json`
+- `opportunities.json`
+- `actions.json`
+- `rationale.md`
+
+## Guardrails
+
+- Do not invent prices, availability, reviews, ratings, shipping, or return
+  policy details.
+- Do not recommend review markup unless review evidence is first-party and
+  policy-safe.
+- Product-linked page actions must include product ids when available.
+- Comparison pages need factual, source-backed claims and a last-updated date.

package/dist/skillpacks/geo/skills/seo-ecommerce-opportunity/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "SEO Ecommerce Opportunity"
+  short_description: "Find ecommerce SEO, product schema, and shopping-intent opportunities."
+  default_prompt: "Use $seo-ecommerce-opportunity to diagnose product, category, schema, offer, review, and shopping SERP opportunities."
+

package/dist/skillpacks/geo/skills/seo-ecommerce-opportunity/references/ecommerce-rules.md

@@ -0,0 +1,31 @@
+# Ecommerce Rules
+
+## Product Pages
+
+- Product title and description should be specific and useful.
+- Product schema should include verifiable Product identity.
+- Offer data must match visible page data.
+- Price, availability, currency, shipping, and return policy must not be invented.
+- Product images should have descriptive alt text and stable dimensions.
+
+## Category and Collection Pages
+
+- category title and intro explain who the collection is for.
+- include comparison criteria, buying guidance, and links to key products.
+- avoid thin grids with no explanatory content.
+- add internal links from relevant guide/comparison pages.
+
+## Reviews and Ratings
+
+- only use review/aggregateRating when evidence exists.
+- do not generate fake or extrapolated ratings.
+- flag missing review collection motion as third-party/manual when appropriate.
+
+## Shopping SERP Opportunities
+
+- `best_of`, `comparison`, `alternatives`, and buying guide SERPs can justify new
+  GEO/CMS pages when product fit is clear.
+- product/category SERPs can justify category improvement rather than blog posts.
+- marketplace-dominated SERPs may require third-party execution, not owned-page
+  creation.
+

package/dist/skillpacks/geo/skills/seo-internal-link-opportunity/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: seo-internal-link-opportunity
+description: Use when finding internal link opportunities, orphan pages, hub-and-spoke gaps, anchor text improvements, CMS/GEO page graph issues, or auto-applicable internal link actions.
+---
+
+# SEO Internal Link Opportunity
+
+Use this skill for CMS, owned-page, and generated-page internal link analysis.
+It follows the `claude-seo` cluster link-matrix pattern and adapts it to
+Anymorph-managed actions.
+
+## Artifact
+
+Write outputs under:
+
+```text
+agent/seo/seo-internal-link-opportunity/{runId}/
+```
+
+## References
+
+- `references/link-rules.md` for matrix and anchor guidance.
+- `../seo-opportunity-audit/references/action-contract.md` for output shape.
+
+## Workflow
+
+1. Read CMS inventory, generated GEO pages, owned URLs, existing internal links,
+   intents, products, and SERP clusters.
+2. Build a page graph: source, target, anchor, page type, intent, product, status.
+3. Detect:
+   - orphan pages.
+   - weak hub pages.
+   - missing spoke-to-pillar links.
+   - missing pillar-to-spoke links.
+   - missing comparison/category/product support links.
+   - poor or generic anchors.
+4. Create action candidates only where source and target are controlled or
+   editable through Anymorph/CMS.
+5. Emit link action candidates with exact source page, target page, suggested
+   anchor, placement rationale, and verification method.
+
+## Output Files
+
+- `graph.json`
+- `opportunities.json`
+- `actions.json`
+- `rationale.md`
+
+## Auto-Apply Rule
+
+Set `canAutoApply=true` only when:
+
+- the source page is managed by Anymorph or known CMS tooling.
+- the target URL is stable.
+- the suggested anchor is natural and context-compatible.
+- the change can be represented as a deterministic edit or generation action.
+

package/dist/skillpacks/geo/skills/seo-internal-link-opportunity/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "SEO Internal Link Opportunity"
+  short_description: "Find internal link, hub-spoke, and anchor opportunities."
+  default_prompt: "Use $seo-internal-link-opportunity to find orphan pages, hub-spoke gaps, anchor improvements, and internal link actions."
+

package/dist/skillpacks/geo/skills/seo-internal-link-opportunity/references/link-rules.md

@@ -0,0 +1,28 @@
+# Internal Link Rules
+
+## Matrix
+
+- pillar to spoke: required for every planned spoke.
+- spoke to pillar: required for every spoke.
+- same-cluster spoke to spoke: 2-3 links when context supports it.
+- cross-cluster links: use sparingly for adjacent intent paths.
+- money/product/category pages should receive links from relevant informational
+  pages, not unrelated pages.
+
+## Anchors
+
+- descriptive, natural, and context-specific.
+- avoid repeated exact-match anchors across many pages.
+- avoid generic anchors such as "click here" or "read more" unless surrounding
+  context makes target clear.
+- use product/category/comparison terminology only when the source paragraph
+  supports it.
+
+## Scorecard
+
+- orphan pages: target has zero controlled inbound links.
+- weak pages: target has fewer than two relevant controlled inbound links.
+- hub weakness: pillar does not link to all active spokes.
+- cannibalization risk: two pages target the same primary query without clear
+  differentiation.
+

package/dist/skillpacks/geo/skills/seo-opportunity-audit/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: seo-opportunity-audit
+description: Use when running a complete SEO opportunity pass across technical diagnosis, page diagnosis, DFS-backed SERP research, internal linking, and ecommerce-specific opportunity discovery.
+---
+
+# SEO Opportunity Audit
+
+Use this as the integrated SEO workflow. It coordinates the five focused SEO
+skills and writes one consolidated artifact set under `agent/seo/`.
+
+This skill is diagnosis-to-action oriented. Every finding must become either an
+action candidate, a blocked/no-action record, or a verification task.
+
+## Source Pattern
+
+Follow the structure and judgment style of `AgriciDaniel/claude-seo` where it
+fits Anymorph:
+
+- orchestrate first, then delegate to narrow skills.
+- use technical, page, SERP/SXO, cluster, ecommerce, and DFS evidence separately.
+- keep static rules in references.
+- prefer evidence-backed, falsifiable recommendations over generic SEO advice.
+
+Do not copy marketing footers, community CTAs, broad PDF/report workflow, or
+unbounded 500-page crawling defaults.
+
+## Shared References
+
+Read shared references selectively:
+
+- `../../shared/evidence-principles.md` before writing or accepting claim,
+  freshness, schema, feed, review, comparison, or compliance findings.
+- `../../shared/vertical-playbooks/{vertical}.md` when the tenant vertical is
+  known. Use only the matching playbook(s). These files provide vertical
+  heuristics for entity patterns, asset plays, measurement signals, and risk
+  categories; they are not tenant evidence and do not override
+  `agent/BRAND.md`, `agent/STRATEGY.md`, or source data.
+
+Vertical selection defaults:
+
+- beauty/skincare/makeup/haircare/personal care -> `beauty.md`
+- SaaS/software/subscription/developer tool -> `saas.md`
+- OTA/travel/hospitality/lodging/tours/things-to-do -> `ota.md`
+- ecommerce/consumer goods/retail outside beauty -> `commerce.md`
+
+## Focused Skills
+
+Invoke or apply these in order:
+
+1. `$seo-technical-diagnosis`
+2. `$seo-page-diagnosis`
+3. `$seo-serp-opportunity-research`
+4. `$seo-internal-link-opportunity`
+5. `$seo-ecommerce-opportunity` only when ecommerce signals exist.
+
+## Artifact Setup
+
+All outputs go under:
+
+```text
+agent/seo/seo-opportunity-audit/{runId}/
+agent/seo/seo-technical-diagnosis/{runId}/
+agent/seo/seo-page-diagnosis/{runId}/
+agent/seo/seo-serp-opportunity-research/{runId}/
+agent/seo/seo-internal-link-opportunity/{runId}/
+agent/seo/seo-ecommerce-opportunity/{runId}/
+```
+
+Use the bundled script to create paths and validate JSON:
+
+```bash
+SEO_TOOLKIT=.agents/skills/seo-opportunity-audit/scripts/seo-toolkit.mjs
+test -f "$SEO_TOOLKIT" || SEO_TOOLKIT=.claude/skills/seo-opportunity-audit/scripts/seo-toolkit.mjs
+node "$SEO_TOOLKIT" init-artifact --skill seo-opportunity-audit --run-id "$RUN_ID"
+```
+
+If there is no host-provided `RUN_ID`, derive one from the current GEO run id.
+Only use a timestamp fallback for local exploratory work.
+
+## Workflow
+
+1. Read the GEO run context, tenant memory, product catalog, intents, and known
+   page inventory before using external data.
+2. Create the integrated audit artifact directory.
+3. Run technical and page diagnosis first to establish crawl/index/page evidence.
+4. Run DFS-backed SERP opportunity research. Use Firecrawl only to inspect
+   concrete competitor pages or public pages after DFS identifies candidates.
+5. Run internal link opportunity analysis against the CMS/GEO page inventory.
+6. Run ecommerce opportunity only when ecommerce signals exist.
+7. Merge outputs into `summary.json`, `actions.json`, and `rationale.md`.
+8. Reject duplicate or weak findings. Prefer no action over speculative action.
+
+## DFS Rule
+
+DFS API usage must be wrapped by the bundled script:
+
+```bash
+node "$SEO_TOOLKIT" dfs-request --endpoint serp_organic_live_advanced --params '{"keyword":"example","location_name":"United States","language_code":"en"}'
+```
+
+Then call the matching DataForSEO MCP/API tool. If direct DataForSEO credentials
+are available in the environment, use the same script for REST calls:
+
+```bash
+node "$SEO_TOOLKIT" dfs-call --path /v3/dataforseo_labs/google/related_keywords/live --payload '[{"keyword":"example","location_name":"United States","language_code":"en","limit":10}]' > dfs-response.json
+```
+
+In hosted GEO strategy runs,
+prefer the Anymorph MCP wrappers such as `mcp__anymorph__dataforseo_research`,
+`mcp__anymorph__search_keywords`, `mcp__anymorph__serp_snapshot`, and
+`mcp__anymorph__list_seo_opportunities` when direct DataForSEO tools are not
+available. Normalize the response:
+
+```bash
+node "$SEO_TOOLKIT" dfs-normalize --endpoint serp_organic_live_advanced < dfs-response.json
+```
+
+Do not call DFS broadly without a request artifact, estimated cost tier, and
+normalization output saved in the skill artifact directory.
+
+## Consolidated Output
+
+Write:
+
+- `summary.json`: compact rollup and scorecard.
+- `actions.json`: action candidates with fingerprints.
+- `blocked.json`: rejected or blocked opportunities.
+- `rationale.md`: short human-readable decision record.
+
+Each final action must include:
+
+- `sourceSkill`
+- `opportunityType`
+- `target`
+- `evidence`
+- `confidence`: `confirmed`, `likely`, or `hypothesis`
+- `impact`, `effort`, and `priority`
+- `canAutoApply`
+- `requiresThirdPartyExecution`
+- `verificationMethod`
+- `actionFingerprint`

package/dist/skillpacks/geo/skills/seo-opportunity-audit/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "SEO Opportunity Audit"
+  short_description: "Run a complete SEO opportunity audit across focused SEO skills."
+  default_prompt: "Use $seo-opportunity-audit to run technical, page, SERP, internal link, and ecommerce SEO opportunity analysis."
+