Skip to main content

SEO Pipeline — Portal Intake → John Deep-Report (agent runbook)

Purpose

The SnowIT SEO offering uses the portal for intake and crawl at scale (zero partner effort). John (agents) produces the quality deep report. The portal’s own auto-report is a shallow teaser; the real deliverable is John’s deep-report play. This runbook is the canonical reference for any agent session picking up SEO work.

Architecture / Flow

Asmir (partner) adds client via /partners in portal
  OR John mints magic-link directly
        |
        v
System emails HMAC-bound magic-link to end client
        |
        v
Client opens https://seo-tools.snowit.ba/intake/<token>
  fills smart form + AI chatbot
        |
        v
Portal auto-crawls site
  stores intakeSubmission + crawl summary in workspace.json
  fires notify_audit_ready webhook/email
        |
        v
seo-intake-watcher (LaunchAgent) polls workspace every 10 min
  detects NEW submission
  emails [email protected]
        |
        v
John agent session runs ~/system/prompts/seo-deep-report-play.md
        |
        v
Quality deep report delivered to Asmir / client

Key Live Facts (verified 2026-06-22)

ItemValue
Portal appAzure App Service seo-readiness-alai, RG rg-seo-readiness-prod
Current known-good image20260622-audit-depth (v1.1.0 crawl audit engine)
Public URLsseo-tools.snowit.ba / seo-tools.alai.no
Deploy methodaz acr build + az webapp config container set (DEPLOY-MAP.md in repo root; ZAKON PI2)
Workspace read (read-only)Kudu VFS + AAD token: az account get-access-token --resource https://management.azure.com then GET https://seo-readiness-alai.scm.azurewebsites.net/api/vfs/data/workspace.json
Handoff watcher script~/system/tools/seo-intake-watcher.js
LaunchAgentcom.john.seo-intake-watcher (10-min poll; emails [email protected] on NEW intake only)
Watcher state~/system/state/seo-intake-watcher-seen.json
Deep-report play~/system/prompts/seo-deep-report-play.md
GSC/GA layerOPTIONAL / separate — pending OAuth verification (MC #103428). Crawl-based audit needs NO Google credentials.

Trigger Checklist — Receiving a New Intake

  1. Email arrives at [email protected] with subject containing "SEO intake" or "audit_ready".
  2. Open workspace.json via Kudu VFS (read-only; see table above) and confirm intakeSubmission is present for the client domain.
  3. Read ~/system/prompts/seo-deep-report-play.md — follow it exactly. Do not improvise the report structure.
  4. Deliver completed report to Asmir (partner) and optionally to client email on record.
  5. Mark intake as processed in seen-state: add domain + timestamp to ~/system/state/seo-intake-watcher-seen.json.

When to Use the Portal vs Do It Directly

For a small number of one-off clients, John running the audit directly (without the portal intake flow) is faster and produces a deeper initial result. The portal earns its keep at intake volume — when Asmir is referring multiple clients per week and cannot afford to coordinate each one manually. (CEO note 2026-06-22.)

Anti-Pitfalls for Agents

  • Portal auto-report can produce false positives. Example verified 2026-06-22: bilko.cloud robots.txt and sitemap.xml were reported as 200 OK by the shallow auto-report when both URLs actually returned homepage HTML. Always verify by live outcome (curl -sI <url>), not the portal’s own summary.
  • One deploy per task. Build agents must perform exactly one deploy cycle. Do not iterate deploys within a single MC task unless explicitly unblocked.
  • No new endpoints/scope without a new MC. If the task is a runbook write, do not add API routes or portal features as a side-effect.
  • Never hand-write expected results into workspace.json to fake verification. Evidence must be machine-generated from actual portal behaviour.
  • Deploy path is ZAKON PI2. Always check DEPLOY-MAP.md in repo root before any az acr build or az webapp command.

Evidence & Memory Links

No comments to display

Back to top