orkas-ai/orkas/seo-report

seo-report

Render an audit into the deliverable: a dashboard spec the chat can show inline, and a written action plan. Pure formatting — no network, no scoring (it trusts the audit, opportunity and probe inputs).

When to use

• The diagnose flow has a seo-tech-audit result and needs the user-facing report + dashboard.
• The diagnose flow has seo-opportunity and/or geo-probe --op score output to include in the same one-run report.
• Producing a monitoring snapshot's dashboard from a fresh audit.

When NOT to use

• Scoring or generating findings — that is seo-tech-audit.
• Acquiring page data — that is seo-crawl.

Preconditions

On a continuation, supplied current-run evidence remains usable context. Finish the pending artifact from it, keeping unsupported findings Estimated, instead of restarting collection merely because the work spans turns.

• A seo-tech-audit JSON object. Optionally the originating seo-crawl JSON, seo-opportunity JSON, and geo-probe --op score JSON for extra context.
• Python 3.9+ (stdlib only).

How to call

For a bounded end-to-end diagnosis, first run seo-crawl --out so its compact summary supplies representative links, then call this orchestrator once:

"$ORKAS_NODE" "$ORKAS_PC_DIR/bin/run-skill.cjs" seo-report diagnose -- --crawl .orkas-seo-audit/crawl.json --out-dir .orkas-seo-audit [--sample-url <url> ...] [--include-cwv]

It runs root tech/content/schema/GEO/opportunity analysis, audits at most five explicit sample URLs once each, writes multi-summary.json and report.json, and returns the dashboard, action_plan_md, page matrix, and optional CWV failure in one envelope. A failed sample is recorded and not retried. The workspace-relative output directory rejects absolute and parent-traversal paths. Use write_file for the returned action_plan_md.

For report-only assembly from existing inputs:

"$ORKAS_NODE" "$ORKAS_PC_DIR/bin/run-skill.cjs" seo-report report -- --audit <audit.json> [--crawl <crawl.json>] [--opportunities <opportunities.json>] [--geo-probe <geo-probe.json>] [--plan <ACTION-PLAN.md>] [--out <dashboard.json>]

• --audit path to the seo-tech-audit JSON (omit or - to read stdin).
• --crawl optional seo-crawl JSON for context.
• --opportunities optional seo-opportunity JSON. Rendered as a one-run Keyword Opportunities section; no trend claims.
• --geo-probe optional geo-probe --op score JSON. Rendered as a one-run GEO Share-of-Voice Snapshot.
• --plan write the ACTION-PLAN.md markdown here.
• --out also write the dashboard JSON here.

Expected output

stdout is an envelope:

{ "ok": true,
  "dashboard": { "schema_version": 1, "root": { ... } },
  "action_plan_md": "# SEO/GEO Action Plan\n...",
  "health_score": 96, "summary": { "critical": 0, "high": 0, "medium": 0, "low": 2, "total": 2 } }

The dashboard object is validated against the directive schema before printing (schema_version 1; Stack/Grid/Metric/Chart/Table/Alert/Markdown), so it always renders. On failure: {"ok": false, "error": "..."} on stderr with a non-zero exit. --plan / --out additionally write the plan / dashboard to files.

Rendering note for the agent

1. Emit the dashboard object once, inside a fenced block:

:::dashboard
<the dashboard object here>
:::

1. Write action_plan_md to ACTION-PLAN.md (use write_file). Preserve every P0/P1 item's Evidence, concrete action, Leading indicator, and Failure criterion exactly enough to remain testable; do not replace the generated plan with a generic checklist. If tools are unavailable, present these four fields as the required executor contract instead of inventing findings.

1. Make a strategy answer usable without opening the artifact. After the

dashboard, inline:

• a compact intent-to-page table for the sampled core pages, with owner URL,

primary question, answer-ready passage/block, evidence or trust block, and recommended matching schema;

• entity-clarity, authoritative-citation, author/reviewer, and visible

updated-date requirements; and

• every P0/P1 item's Evidence, action, Leading indicator, and Failure

criterion. Do not replace these details with only an ACTION-PLAN.md link.

Before strategy cards, print ### Execution sequence with steps numbered 1..N; each step names its owner role, effort band, and validation window. P0 means dependency order, not technical severity. When no Critical/High technical finding exists, lead with intent ownership and first-party proof, and keep polish in P2 and last.

Do not hand-edit the JSON — regenerate via this skill if the audit changes.

For a strategy request, a safety-blocked crawl is an evidence limitation rather than a reason to stop. Do not retry, search, or open an execution plan. Write the evidence-honest Estimated plan to ACTION-PLAN.md, persist the bounded strategy-baseline.json, and deliver the provisional strategy with the missing verification named.