# 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 john@alai.no
        |
        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)

<table id="bkmrk-itemvalue-portal-app"><thead><tr><th>Item</th><th>Value</th></tr></thead><tbody><tr><td>Portal app</td><td>Azure App Service `seo-readiness-alai`, RG `rg-seo-readiness-prod`</td></tr><tr><td>Current known-good image</td><td>`20260622-audit-depth` (v1.1.0 crawl audit engine)</td></tr><tr><td>Public URLs</td><td>[seo-tools.snowit.ba](https://seo-tools.snowit.ba) / [seo-tools.alai.no](https://seo-tools.alai.no)</td></tr><tr><td>Deploy method</td><td>`az acr build` + `az webapp config container set` (DEPLOY-MAP.md in repo root; ZAKON PI2)</td></tr><tr><td>Workspace read (read-only)</td><td>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`</td></tr><tr><td>Handoff watcher script</td><td>`~/system/tools/seo-intake-watcher.js`</td></tr><tr><td>LaunchAgent</td><td>`com.john.seo-intake-watcher` (10-min poll; emails john@alai.no on NEW intake only)</td></tr><tr><td>Watcher state</td><td>`~/system/state/seo-intake-watcher-seen.json`</td></tr><tr><td>Deep-report play</td><td>`~/system/prompts/seo-deep-report-play.md`</td></tr><tr><td>GSC/GA layer</td><td>OPTIONAL / separate — pending OAuth verification (MC #103428). Crawl-based audit needs NO Google credentials.</td></tr></tbody></table>

---

## Trigger Checklist — Receiving a New Intake

1. Email arrives at john@alai.no 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 &amp; Memory Links

- Memory project: `project_seo_pipeline_portal_plus_john_2026-06-22`
- Memory project: `project_seo_portal_live_autonomous_2026-06-22`
- Related pages: 
    - [SEO Readiness Portal MVP — Status and Evidence](https://docs.alai.no/books/new-client-template/page/seo-readiness-portal-mvp-status-and-evidence) (new-client-template book)
    - [SEO Readiness Portal Cloud Migration — 2026-06-01](https://docs.alai.no/books/snowit/page/seo-readiness-portal-cloud-migration-2026-06-01) (SnowIT book)
    - [SEO Client Workflow — Skill + Intake Auto-Ingest](https://docs.alai.no/books/seo-readiness-portal/page/seo-client-workflow-skill-seo-client-intake-auto-ingest)
    - [SEO Portal intake-audit loop + chatbot P0 security (2026-06-07)](https://docs.alai.no/books/seo-readiness-portal/page/seo-portal-intake-audit-loop-chatbot-p0-security-mc-103100103105103101-2026-06-07)