anymorph 0.2.2 → 0.2.4

package/dist/skillpacks/geo/skills/geo-generating-actions/references/orchestrator.workflow.md

@@ -0,0 +1,274 @@
+# Orchestrator Workflow
+
+## Role
+
+The orchestrator owns the weekly GEO strategy run.
+
+It does four things:
+
+1. Analyze last week's performance.
+2. Combine performance with tenant strategy into one common run context.
+3. Run all three channel diagnoses with that common context.
+4. Judge the returned proposals and write the final action list.
+
+The orchestrator is not just a router.
+
+It is the final decision-maker for the run.
+
+## Inputs
+
+- `agent/runs/{runId}/context.json`
+- `agent/runs/{runId}/manifest.json`
+- `agent/runs/{runId}/intents.json`
+- `agent/BRAND.md`
+- `agent/STRATEGY.md`
+- `agent/LEARNINGS.md`
+- prior `agent/runs/*` summaries when useful
+- `schemaCatalog`
+- `signals`
+- `geo_*` query surface
+
+## Required Views
+
+Use these views when available:
+
+- `geo_intent_coverage`
+- `geo_recommendation_quadrants`
+- `geo_page_intent_visibility_gaps`
+- `geo_page_performance`
+- `geo_strategy_actions_recent`
+- `geo_pages`
+- `geo_intents`
+
+Use these when third-party analysis is enabled:
+
+- `geo_intent_citations`
+- `geo_third_party_domains`
+- `geo_competitor_citations`
+- `geo_third_party_sentiment`
+
+If a view is unavailable, continue with lower confidence and record the missing view in `rationale.md`.
+
+## Workflow
+
+### 1. Load Stable Tenant Context
+
+Read:
+
+- `agent/BRAND.md`
+- `agent/STRATEGY.md`
+- `agent/LEARNINGS.md`
+- recent prior run artifacts
+
+Extract:
+
+- current tenant priorities
+- explicit channel preferences
+- forbidden actions
+- recent bets
+- repeated learnings
+- open questions
+
+Do not rewrite tenant memory in this phase.
+
+### 2. Analyze Last Week's Performance
+
+Build a concise performance summary for the run.
+
+Use:
+
+- visibility changes
+- weak intents
+- covered-but-weak intents
+- recommendation quadrant changes
+- page performance changes
+- citation/domain changes
+- prior action outcomes when available
+
+The summary should answer:
+
+- What improved?
+- What regressed?
+- Which intents remain weak?
+- Which existing pages are underperforming?
+- Which pages or intents look healthy enough to avoid touching?
+- Which prior actions should suppress repeats?
+
+### 3. Build Common Run Context
+
+Create one shared context object for all channel diagnoses.
+
+It should include:
+
+- tenant objective for this run
+- relevant brand constraints
+- strategy priorities from `STRATEGY.md`
+- last-week performance summary
+- recent action exclusion mask
+- candidate intent/page/domain slices
+- evidence budget
+- output schema
+
+This context is shared by all three channel diagnoses.
+
+Channel diagnoses may receive channel-specific candidate slices, but they should share the same strategic baseline.
+
+### 4. Run Three Channel Diagnoses
+
+Apply these channel skills directly:
+
+- `brand-owned-diagnosis`
+- `geo-pages-diagnosis`
+- `third-party-diagnosis`
+
+Each channel diagnosis returns one compact proposal set to the lead agent.
+
+Expected channel diagnosis output:
+
+```json
+{
+  "summary": "Short channel-level diagnosis.",
+  "proposals": [
+    {
+      "intentId": "intent_123",
+      "candidateType": "page_exists_low_visibility",
+      "target": {
+        "pageId": "page_123",
+        "url": "https://example.com/page"
+      },
+      "rootCauses": [
+        {
+          "bucket": "proof_gap",
+          "confidence": 0.72,
+          "evidence": ["Evidence summary"]
+        }
+      ],
+      "actionFamily": "refresh_existing_page",
+      "operations": ["Add proof section"],
+      "priority": "high",
+      "confidence": "medium",
+      "evidence": [
+        {
+          "type": "signal",
+          "ref": "geo_recommendation_quadrants:intent_123",
+          "summary": "mentioned_not_recommended_rate is high"
+        }
+      ],
+      "whyNow": "Why this should be considered this week.",
+      "risks": ["Possible risk or uncertainty"]
+    }
+  ],
+  "rejected": [
+    {
+      "ref": "intent_456",
+      "reason": "Suppressed by recent action mask"
+    }
+  ],
+  "noActionRationale": "Optional. Use when proposals is empty."
+}
+```
+
+Channel diagnoses must not include `workspaceId`, `runId`, `channel`, final action id, final `assetType`, or final URL.
+The orchestrator derives final action ids, channel-to-asset mapping, and executable action shape.
+
+### 5. Judge Channel Outputs
+
+The orchestrator reviews all proposals.
+
+It should ask:
+
+- Does this proposal match tenant strategy?
+- Is the evidence strong enough?
+- Is it redundant with another channel's proposal?
+- Is it suppressed by recent actions?
+- Is the action executable by the current product surface?
+- Is it more important than competing proposals this week?
+
+The orchestrator may:
+
+- accept
+- merge
+- downgrade
+- reject
+- move to `rationale.md` only
+
+### 6. Resolve Cross-Channel Conflicts
+
+Common conflicts:
+
+- `brand_owned` proposes refreshing a page while `geo_pages` proposes creating a new page for the same intent.
+- `geo_pages` proposes iteration while `third_party` argues authority is the bottleneck.
+- `third_party` proposes outreach but owned page coverage is clearly weak.
+
+Default resolution:
+
+1. If an existing page clearly owns the intent and content gaps are fixable, prefer updating it.
+2. If no page exists, prefer GEO page generation unless tenant strategy says customer-site page first.
+3. If page content is strong but external validation is the bottleneck, keep third-party as a candidate.
+4. If evidence is weak, do not emit an action; record the uncertainty.
+
+### 7. Build Final Action List
+
+Select at most 20 final actions.
+
+Prefer:
+
+1. high-confidence fixes for existing important pages
+2. high-confidence generated GEO page iteration
+3. high-confidence net-new page generation
+4. third-party actions only when actionability is clear
+
+Low-confidence findings go to `rationale.md`.
+
+Guardrail:
+
+- `brand_owned` is only for customer-owned discovered pages.
+- Do not send Anymorph-generated, recommended, preview-only, or unpublished GEO pages to Fix.
+- Existing generated page work must stay `assetType: "geo_page"` even when the proposed operation is a technical fix or content iteration.
+
+### 8. Write Artifacts
+
+Write:
+
+- `agent/runs/{runId}/actions.json`
+- `agent/runs/{runId}/rationale.md`
+- `agent/runs/{runId}/status.json`
+
+Optionally archive compact observations in:
+
+- `agent/archive/{time5}-{slug}.json`
+
+Update stable memory only when the run changes durable tenant strategy.
+On bootstrap runs, also update stable memory when `agent/STRATEGY.md` or
+`agent/LEARNINGS.md` is missing, blank, or still scaffold-only.
+
+`agent/BRAND.md` is backend-managed. It is regenerated from the workspace
+brand record whenever the `brandHash` frontmatter drifts, and the agent
+must not edit it. If a brand fact looks wrong, raise it in
+`rationale.md` rather than editing the file.
+
+## Final Action Contract
+
+Each final action must include:
+
+- `operation`
+- `surface`
+- `assetType`
+- `intentId`
+- `target`
+- `objective`
+- `changeBrief`
+- `reason`
+- `expectedOutcome`
+- `evidence`
+- `priority`
+- `confidence`
+
+## Guardrails
+
+- Do not let a channel diagnosis proposal pass through automatically.
+- Do not choose duplicate actions for the same intent unless they are clearly complementary.
+- Do not invent final routes for create actions.
+- Do not treat missing data as proof.
+- Do not diagnose authority from low visibility alone.
+- Do not update tenant memory with generic SEO/GEO advice.

package/dist/skillpacks/geo/skills/geo-initializing-strategy/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: geo-initializing-strategy
+description: Use when creating or repairing the initial Strategy Map baseline for an Anymorph workspace before recurring GEO action generation begins.
+---
+
+# GEO Initializing Strategy
+
+Use this skill to create the first durable Strategy Map for a tenant.
+
+This is a baseline skill, not an action-generation skill. It diagnoses the workspace's owned-site foundation, visibility state, semantic clusters, and external authority so later GEO loops have a stable operating plan.
+
+## Required Inputs
+
+- Tenant repository path.
+- `workspaceId` for internal MCP calls.
+- Host-created Strategy Map context and manifest files.
+- Existing tenant memory files when present:
+  - `agent/BRAND.md`
+  - `agent/STRATEGY.md`
+  - `agent/LEARNINGS.md`
+
+## Workflow
+
+1. Read the host context and manifest first.
+2. Read existing tenant memory before using external evidence.
+3. Use Strategy Map diagnoses for foundation, visibility, semantic clusters, and external authority.
+4. Treat diagnosis section JSON files as the source of truth after they are submitted.
+5. Synthesize a long-term strategy with investment mix, active bets, guardrails, and open strategic questions.
+6. Rewrite `agent/STRATEGY.md` as the canonical human-readable Strategy Map.
+7. Submit structured Strategy Map artifacts through the runtime artifact tools; do not write structured JSON artifacts directly.
+
+## Contracts
+
+Read these references only when needed:
+
+- `references/memory-contract.md` for tenant memory file requirements.
+- `references/strategy-map-contract.md` for output boundaries and quality bar.
+- `references/foundation-diagnosis.md` for owned-site foundation diagnosis.
+- `references/visibility-diagnosis.md` for AI visibility baseline diagnosis.
+- `references/semantic-clusters-diagnosis.md` for semantic cluster diagnosis.
+- `references/external-authority-diagnosis.md` for external authority diagnosis.
+
+## Guardrails
+
+- Preserve YAML frontmatter on existing tenant memory files.
+- Never write empty frontmatter.
+- Do not generate weekly actions, page briefs, outreach tasks, or execution steps.
+- Prefer `unknown` or omitted optional fields over invented certainty.
+- Exclude Anymorph-generated GEO pages from owned-site foundation evidence.
+- Do not edit `agent/BRAND.md`; raise brand drift in rationale instead.

package/dist/skillpacks/geo/skills/geo-initializing-strategy/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "GEO Initializing Strategy"
+  short_description: "Create the initial Strategy Map baseline for a workspace."
+  default_prompt: "Use $geo-initializing-strategy to create the initial Strategy Map baseline for this workspace."

package/dist/skillpacks/geo/skills/geo-initializing-strategy/references/external-authority-diagnosis.md

@@ -0,0 +1,66 @@
+# Strategy Map: External Authority Diagnosis
+
+Summarize external authority by surface class:
+
+- Reddit
+- YouTube
+- Wikipedia/Wikidata
+- review platforms
+- directories
+- publications
+- forums
+- podcasts
+- newsletters
+- social
+- other
+
+Capture tenant presence, competitor presence, relevance, actionability, and strategic implication.
+
+Do not include outreach copy, posts, scripts, or tactical execution steps.
+
+Use DataForSEO as the primary paid source for backlink and referring-domain evidence. Prefer `mcp__anymorph__dataforseo_research` for:
+
+- `/v3/backlinks/summary/live`
+- `/v3/backlinks/referring_domains/live`
+- `/v3/backlinks/backlinks/live`
+- `/v3/dataforseo_labs/google/domain_rank_overview/live`
+
+Ahrefs is not required for this section.
+
+Keep web research bounded:
+
+- Use at most 6 `mcp__anymorph__web_search` calls.
+- Use `mcp__anymorph__summarized_web_scrape` only for the highest-signal pages that change the diagnosis.
+- Prefer citation tools before broad web search.
+
+Never emit `null`. Omit optional fields when unknown. Required unknown enum fields must use `unknown`.
+
+Submit exactly one section artifact with `mcp__strategy_map_artifacts__submit_strategy_map_section`.
+
+```json
+{
+  "section": "externalAuthority",
+  "artifact": [
+    {
+      "id": "auth-short-stable-id",
+      "surfaceClass": "reddit | youtube | wikipedia_wikidata | review_platform | directory | publication | forum | podcast | newsletter | social | other",
+      "relevance": "high | medium | low | unknown",
+      "tenantPresence": "strong | medium | weak | absent | unknown",
+      "competitorPresence": "strong | medium | weak | absent | unknown",
+      "actionability": "high | medium | low | none | unknown",
+      "strategicImplication": "What this authority state means for the roadmap.",
+      "evidenceRefs": ["ev-authority-1"]
+    }
+  ],
+  "evidence": [
+    {
+      "id": "ev-authority-1",
+      "type": "signal | workspace | source | research",
+      "ref": "tool or source reference",
+      "summary": "Specific evidence summary."
+    }
+  ]
+}
+```
+
+Final response: one short sentence naming the saved section.

package/dist/skillpacks/geo/skills/geo-initializing-strategy/references/foundation-diagnosis.md

@@ -0,0 +1,86 @@
+# Strategy Map: Foundation Diagnosis
+
+Diagnose the technical SEO/GEO foundation.
+
+Focus only on durable strategic signals:
+
+- indexability
+- crawlability
+- schema/content parity
+- AI crawler access
+- internal linking
+- page experience
+
+Do not emit page-level fixes, implementation briefs, or action lists.
+
+Use `mcp__anymorph__dataforseo_onpage` as the primary owned-site crawl and internal-link evidence source.
+
+Baseline rule:
+
+- Foundation is the existing brand-owned site baseline.
+- Exclude Anymorph-generated GEO pages from owned-page, internal-link hub, inbound-link, orphan-page, and crawl-state judgments.
+- Pass `workspaceId` to `dataforseo_onpage`; backend will remove generated GEO pages from DFS pages/links results.
+- Generated GEO pages may be mentioned only as strategy execution surfaces in semantic/visibility synthesis, not as Foundation evidence.
+
+Expected DataForSEO On-Page flow:
+
+1. `action=start_crawl`, `target=<workspace domain>`, `workspaceId=<workspace id>`, `maxCrawlPages` around 100.
+2. `action=summary` with the returned `taskId`, `workspaceId=<workspace id>`.
+3. If the crawl is finished, call `action=pages` ordered by `meta.inbound_links_count,desc`, with `workspaceId=<workspace id>`.
+4. Call `action=links` with `direction=internal`, `dofollowOnly=true`, `workspaceId=<workspace id>`.
+
+Use these DFS fields:
+
+- `status_code` and `page_to_status_code` for crawl/indexability evidence.
+- `meta.internal_links_count`, `meta.inbound_links_count`, and `checks.is_orphan_page` for internal-link topology.
+- `page_from`, `page_to`, `link_from`, `link_to`, and `dofollow` for edge evidence.
+
+Do not use DataForSEO Backlinks API as a substitute for owned-site internal-link evidence. Use DataForSEO On-Page only.
+
+Do not claim a page is an in-content hub from DFS alone. DFS On-Page can show internal edges and target status, but not guaranteed nav/footer/content placement. For true in-content hub claims, corroborate with CMS source or page HTML via `get_page_source_code`, `get_page_content`, or summarized scrape.
+
+Use Ahrefs only as optional enrichment for crawl and in-content internal-link evidence. For internal-link hubs, filter to in-content, dofollow links when the endpoint supports it. If Ahrefs returns "API units limit reached", times out, fails auth, or is unavailable, stop calling Ahrefs and continue with DataForSEO On-Page + owned-source evidence.
+
+Use `mcp__anymorph__summarized_web_scrape` by its full tool name. Do not call a bare `mcp__summarized_web_scrape`.
+
+Never emit `null`. Omit optional fields when unknown. Required unknown enum fields must use `unknown`.
+
+Submit exactly one section artifact with `mcp__strategy_map_artifacts__submit_strategy_map_section`.
+
+```json
+{
+  "section": "foundation",
+  "artifact": {
+    "status": "strong | medium | weak | unknown",
+    "signals": {
+      "indexability": "strong | medium | weak | unknown",
+      "crawlability": "strong | medium | weak | unknown",
+      "schemaParity": "strong | medium | weak | unknown",
+      "aiCrawlerAccess": "strong | medium | weak | unknown",
+      "internalLinking": "strong | medium | weak | unknown",
+      "pageExperience": "strong | medium | weak | unknown"
+    },
+    "blockers": [
+      {
+        "id": "blk-short-stable-id",
+        "type": "indexability | crawlability | schema_parity | ai_crawler_access | internal_linking | page_experience | faceted_navigation | duplicate_content | rendering | other",
+        "severity": "high | medium | low",
+        "summary": "Strategic blocker, not a page-level fix brief.",
+        "evidenceRefs": ["ev-foundation-1"]
+      }
+    ],
+    "strategicImplication": "What this foundation state means for long-term investment mix.",
+    "evidenceRefs": ["ev-foundation-1"]
+  },
+  "evidence": [
+    {
+      "id": "ev-foundation-1",
+      "type": "signal | workspace | source | research",
+      "ref": "tool or source reference",
+      "summary": "Specific evidence summary."
+    }
+  ]
+}
+```
+
+Final response: one short sentence naming the saved section.

package/dist/skillpacks/geo/skills/geo-initializing-strategy/references/memory-contract.md

@@ -0,0 +1,15 @@
+# Tenant Memory Contract
+
+Durable tenant memory lives in the tenant repository.
+
+- `agent/BRAND.md`: brand facts regenerated by backend; read-only during Strategy Map runs.
+- `agent/STRATEGY.md`: canonical human-readable Strategy Map.
+- `agent/LEARNINGS.md`: stable repeated observations only.
+
+Rules:
+
+- Keep frontmatter present and non-empty.
+- Preserve existing frontmatter keys unless the run has explicit reason to update them.
+- Keep memory concise.
+- Do not paste raw evidence, generic SEO advice, or long research transcripts.
+- Put run-specific details under `agent/strategy-map/runs/{runId}/`.

package/dist/skillpacks/geo/skills/geo-initializing-strategy/references/semantic-clusters-diagnosis.md

@@ -0,0 +1,58 @@
+# Strategy Map: Semantic Clusters Diagnosis
+
+Map the brand's long-term opportunity space into semantic clusters.
+
+Each cluster should describe:
+
+- intent
+- AI decision criteria
+- current coverage state
+- missing surface types
+- known overlap or cannibalization risk
+- confidence
+
+Do not include recommended actions, briefs, or page creation instructions. The orchestrator will turn cluster diagnosis into long-term strategy.
+
+Use DataForSEO-backed tools first for keyword demand, SERP shape, ranked-keyword gaps, and competitor content gaps:
+
+- `mcp__anymorph__search_keywords`
+- `mcp__anymorph__serp_snapshot`
+- `mcp__anymorph__dataforseo_research`
+- `mcp__anymorph__get_competitor_gap`
+
+Use Ahrefs only when available for in-content internal-link hub evidence. If Ahrefs returns "API units limit reached", times out, fails auth, or is unavailable, stop calling Ahrefs and omit `hubSurfaceId` unless a real non-Ahrefs surface id is known.
+
+Never emit `null`. Omit optional fields like `hubSurfaceId` and `overlaps` when unknown. Required unknown enum fields must use `unknown`.
+
+Submit exactly one section artifact with `mcp__strategy_map_artifacts__submit_strategy_map_section`.
+
+```json
+{
+  "section": "semanticClusters",
+  "artifact": [
+    {
+      "id": "cl-short-stable-id",
+      "name": "Cluster name",
+      "intent": "User intent this cluster captures",
+      "aiDecisionCriteria": ["Criteria AI answers compare"],
+      "priority": "high | medium | low",
+      "coverageState": "covered | gap | weak | overlap | monitor | unknown",
+      "hubSurfaceId": "optional existing hub surface id",
+      "missingSurfaceTypes": ["proof_surface", "comparison_page"],
+      "overlaps": ["optional overlapping cluster ids"],
+      "confidence": "high | medium | low",
+      "evidenceRefs": ["ev-semantic-1"]
+    }
+  ],
+  "evidence": [
+    {
+      "id": "ev-semantic-1",
+      "type": "signal | workspace | source | research",
+      "ref": "tool or source reference",
+      "summary": "Specific evidence summary."
+    }
+  ]
+}
+```
+
+Final response: one short sentence naming the saved section.

package/dist/skillpacks/geo/skills/geo-initializing-strategy/references/strategy-map-contract.md

@@ -0,0 +1,26 @@
+# Strategy Map Contract
+
+The Strategy Map is a diagnosis artifact, not an execution plan.
+
+Include:
+
+- Owned-site foundation status and blockers.
+- Current AI visibility posture.
+- Semantic clusters with priority and coverage state.
+- External authority gaps.
+- Long-term investment mix and guardrails.
+
+Do not include:
+
+- Recommended page actions.
+- Outreach copy.
+- Concrete prompt panels.
+- Measurement targets.
+- Weekly success criteria.
+
+Evidence rules:
+
+- Use DataForSEO On-Page as the primary owned-site crawl and internal-link source.
+- Use Ahrefs only as optional enrichment for in-content internal-link and crawl evidence.
+- Use workspace MCP tools before freeform research.
+- Mark missing evidence as `unknown`; do not infer certainty from absence.

package/dist/skillpacks/geo/skills/geo-initializing-strategy/references/visibility-diagnosis.md

@@ -0,0 +1,50 @@
+# Strategy Map: Visibility Diagnosis
+
+Summarize current AI visibility.
+
+Classify durable patterns by cluster or engine:
+
+- `absent`
+- `cited_not_mentioned`
+- `mentioned_not_recommended`
+- `cited_not_recommended`
+- `recommended`
+- `declining`
+- `unknown`
+
+Do not paste raw AI answers. Do not propose weekly actions.
+
+Never emit `null`. Omit optional fields like `clusterId` and `engine` when unknown. Required unknown enum fields must use `unknown`.
+
+Submit exactly one section artifact with `mcp__strategy_map_artifacts__submit_strategy_map_section`.
+
+```json
+{
+  "section": "visibility",
+  "artifact": {
+    "overall": "strong | medium | weak | unknown",
+    "patterns": [
+      {
+        "id": "vis-short-stable-id",
+        "clusterId": "optional-cluster-id",
+        "engine": "optional engine name",
+        "state": "absent | cited_not_mentioned | mentioned_not_recommended | cited_not_recommended | recommended | declining | unknown",
+        "summary": "Cluster- or engine-level visibility pattern.",
+        "competitors": ["Competitor names"],
+        "evidenceRefs": ["ev-visibility-1"]
+      }
+    ],
+    "evidenceRefs": ["ev-visibility-1"]
+  },
+  "evidence": [
+    {
+      "id": "ev-visibility-1",
+      "type": "signal | workspace | source | research",
+      "ref": "tool or source reference",
+      "summary": "Specific evidence summary."
+    }
+  ]
+}
+```
+
+Final response: one short sentence naming the saved section.

package/dist/skillpacks/geo/skills/geo-pages-diagnosis/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: geo-pages-diagnosis
+description: Use when diagnosing Anymorph-generated GEO pages, generated-page iteration opportunities, regeneration candidates, or GEO page creation gaps.
+---
+
+# GEO Pages Diagnosis
+
+Use this skill for Anymorph-generated or Anymorph-managed GEO page surfaces.
+
+The output is a compact diagnosis plus action candidates for `assetType="geo_page"`.
+
+## Scope
+
+Diagnose:
+
+- Existing generated page performance.
+- Missing generated pages for weak or uncovered intents.
+- GEO page refresh, regeneration, and technical fix candidates.
+- Commerce product fit for product-linked page creation.
+
+Do not propose:
+
+- Customer-owned page fixes as `geo_page`.
+- Third-party outreach or external profile work.
+- Product-linked create actions without product evidence.
+
+## Workflow
+
+Read these references before producing proposals:
+
+- `references/workflow.md` for the full generated-page product workflow, candidate rules, commerce product-fit rules, root causes, action families, and no-action cases.
+- `references/diagnosis-contract.md` for the exact runtime diagnosis contract and artifact submission shape.
+
+1. Read shared run context and the GEO page candidate slice.
+2. Use `list_geo_strategy_candidates` before broad SQL.
+3. Use `get_geo_intent_diagnostic` for weak intents and generated-page gaps.
+4. Use page visibility, page insights, content, source, and products only when needed.
+5. For commerce create actions, use product evidence before proposing product-linked pages.
+6. Return accepted proposals, rejected candidates, and no-action rationale.
+
+## Output Contract
+
+Each proposal should include:
+
+- intent id or proposed intent.
+- existing page id or URL for update actions.
+- suggested slug only as a non-binding hint for create actions.
+- target product ids when product-linked evidence is present.
+- root cause, action family, priority, confidence, and evidence.
+
+Never invent a final route or URL for create actions.