# SEO Readiness Portal MVP — Status and Evidence

# SEO Readiness Portal MVP — status and evidence

## Scope

SEO Readiness Portal is the productized continuation of SEO Automation v1. The MVP converts intake, readiness audit structure, backlog, and reporting workflow into a local-first SaaS scaffold.

## Current implementation status

- Phase 1: scaffold, app shell, RBAC types, audit domain types, initial schema, spec validation.
- Phase 2: partner/client workspace, client detail page, structured intake UI, sample demo data, intake field definitions and guardrails.
- Phase 3: local/dev persistence for intake save/submit flow.
- Phase 4: local readiness audit runner with persisted audit results and audit detail page.
- Phase 5: local draft report and backlog generator from persisted audit findings.
- Phase 6: local Markdown report review/export workflow with persisted export metadata and checksum.
- Phase 7: local export review notes and internal approval status.
- Phase 8: local client handoff checklist for internally approved exports.
- Phase 9: local client handoff summary draft for approved checklist exports.
- Phase 10: local partner follow-up package draft from approved handoff summary drafts.
- Phase 11: internal SnowIT deploy readiness with Docker packaging, persistent volume, health endpoint, and Cloudflare Access trusted-header gate.
- Phase 12: live protected Cloudflare Access route completed and strictly authenticated on `seo-tools.alai.no`; exact `seo-tools.snowit.ba` route remains blocked pending `snowit.ba` nameserver/Cloudflare zone activation.
- Post-UAT UX fix: explicit **Add new client** flow added from `/partners` to `/clients/new`, creating a lead client, active site, and draft intake before redirecting into intake.

## Add client UX delivered behavior

- `/partners` now has a primary **Add new client** call-to-action and a simple 3-step workflow explanation.
- `/clients/new` provides a dedicated form for partner/owner, company, contact, website/domain, target markets, languages, priority services, competitors, CMS/hosting notes, access-status fields, and internal notes.
- Creating a client persists a `lead` client, active site, and draft intake, then redirects to the intake page with a success notice.
- Validation rejects missing required fields, invalid email, duplicate active domains, secret-like wording, and ranking/traffic/guarantee claims.
- Evidence: `UX-ADD-CLIENT-EVIDENCE.md`, `/tmp/evidence-102370/add-client-ux-validation.log`, `/tmp/evidence-102370/browser-add-client-flow.json`, `/tmp/evidence-102370/add-client-live-deploy-and-smoke.log`, `/tmp/evidence-102370-live-auth/verification.json`, and screenshots under `/tmp/evidence-102370/screenshots/` plus `/tmp/evidence-102370-live-auth/screenshots/`.

## Phase 3 delivered behavior

- File-backed local/dev workspace repository.
- Default app data path: `.data/workspace.json` and gitignored.
- Partner/client pages read through the persistence repository.
- Intake page server actions: 
    - save draft
    - submit intake
- Repository updates client, site, and intake records.
- Submitted intake rejects missing required fields.
- Submitted intake rejects secret-like content such as password, API key, token, secret, or bearer wording.

## Phase 4 delivered behavior

- Basic local readiness audit runner, not a live crawler.
- Client workspace action to run a local audit.
- Persisted audit records in local/dev file-backed workspace data.
- Audit detail page with readiness score, findings, and guardrails.
- Guardrail checks prevent ranking/traffic/guarantee wording in generated findings.

## Phase 5 delivered behavior

- Generates a local draft readiness report from a persisted local audit.
- Generates client-safe backlog items from audit findings.
- Persists `reports` and `backlogItems` in local/dev workspace data.
- Adds audit detail action to generate a draft report.
- Adds report detail page with executive summary, guardrails, and backlog draft.
- Guardrail checks prevent ranking/traffic/guarantee wording in generated report/backlog text.

## Phase 6 delivered behavior

- Generates a local Markdown export from a persisted draft readiness report.
- Persists `reportExports` metadata in local/dev workspace data, including filename, byte length, and SHA-256 checksum.
- Stores the Markdown artifact under local `.data/exports/` storage.
- Adds report action to generate the Markdown export.
- Adds export detail route `/clients/[clientId]/reports/[reportId]/exports/[exportId]` with metadata, guardrails, and Markdown preview.
- Guardrail checks prevent positive ranking/traffic/guarantee wording in generated export text.

## Phase 7 delivered behavior

- Persists `exportReviewNotes` in local/dev workspace data.
- Adds export detail action to save a local internal review note.
- Adds export detail UI for current local review status, reviewer, note, and review history count.
- Supports internal statuses: draft review, changes requested, approved internal.
- Guardrail checks reject secret-like wording and positive ranking/traffic/guarantee wording in review notes.
- Approval status is internal/local only and does not imply public deploy or client delivery.

## Phase 8 delivered behavior

- Persists `handoffChecklists` in local/dev workspace data.
- Adds export detail action to generate a local handoff checklist.
- Requires an `approved_internal` local export review note before checklist generation.
- Adds export detail UI for latest local handoff checklist, linked review note, and pending checklist items.
- Checklist references local evidence such as export checksum and approved review note id.
- Guardrail checks reject secret-like wording and positive ranking/traffic/guarantee wording in checklist content.
- Checklist is internal/local only and does not imply deploy, publication, or client delivery.

## Phase 9 delivered behavior

- Persists `handoffSummaries` in local/dev workspace data.
- Adds export detail action to generate a local handoff summary draft.
- Requires a local handoff checklist linked to an `approved_internal` local export review note before summary generation.
- Adds export detail UI for latest local summary draft, recommended next steps, evidence references, and limitations.
- Summary references local evidence such as export filename/checksum, approved review note id, and checklist id.
- Guardrail checks reject secret-like wording and positive ranking/traffic/guarantee wording in summary content.
- Summary is local draft copy only and does not imply email sending, deploy, publication, or client delivery.

## Phase 10 delivered behavior

- Persists `partnerFollowupPackages` in local/dev workspace data.
- Adds export detail action to generate a local partner follow-up package draft.
- Requires a local handoff summary draft linked to a checklist and `approved_internal` local review note before package generation.
- Adds export detail UI for latest local partner follow-up package draft, suggested message draft, client questions, internal preparation steps, evidence references, limitations, and guardrails.
- Package references local evidence such as export filename/checksum, approved review note id, checklist id, and handoff summary id.
- Guardrail checks reject secret-like wording and positive ranking/traffic/guarantee wording in package content.
- Package is local draft copy only and does not imply automated email sending, public deploy, publication, or client delivery.

## Phase 11 delivered behavior

- Adds standalone Next.js production packaging for container runtime.
- Adds Dockerfile and internal Docker Compose profile.
- Binds the app origin to `127.0.0.1:3100` only in the internal compose profile.
- Uses file-backed Docker volume persistence at `/data/workspace.json` for internal v1.
- Adds `SEO_PORTAL_ACCESS_MODE=cf-access` mode.
- Adds app-level trusted-header access gate using `CF-Access-Authenticated-User-Email` after Cloudflare Access authenticates upstream.
- Adds `/api/health` endpoint for container/reverse-proxy checks.
- Adds internal runbook for proposed `seo-tools.snowit.ba` deployment.
- Local container verification confirms unauthenticated page access returns 401 and authenticated-header page access returns 200.
- Live DNS/Cloudflare Access for `seo-tools.snowit.ba` is not yet configured in this session.

## Phase 12 live-route status

Completed live protected route:

- `https://seo-tools.alai.no`

Observed behavior:

- unauthenticated `/partners` request returns HTTP `302` to Cloudflare Access login;
- spoofed `CF-Access-Authenticated-User-Email` request without Access session still returns HTTP `302` to Cloudflare Access login;
- local origin remains bound to `127.0.0.1:3100` and blocks unauthenticated page access with HTTP `401`;
- browser verification confirms the live unauthenticated page lands on `Sign in ・ Cloudflare Access`, not the origin app;
- strict authenticated UAT for `info@snowit.ba` passed: OTP was received/submitted and the browser loaded `https://seo-tools.alai.no` with title `SEO Readiness Portal`.

Exact SnowIT URL status:

- `https://seo-tools.snowit.ba` is confirmed as the desired SnowIT-branded URL, but is not live yet.
- `snowit.ba` is currently hosted in AWS Route53 and is not an active Cloudflare zone in the available Cloudflare account.
- Cloudflare Access rejected `seo-tools.snowit.ba` with `domain does not belong to zone`.
- A pending Cloudflare zone for `snowit.ba` exists with nameservers `aspen.ns.cloudflare.com` and `wells.ns.cloudflare.com`.
- Existing Route53 records have been mirrored into the pending Cloudflare zone as DNS-only records, and `seo-tools.snowit.ba` has been prepared there as a proxied CNAME to the Cloudflare Tunnel target.
- Nameserver migration/delegation was approved as the correct direction, but is blocked by missing registrar/NIC access path. AWS Route53Domains reports `.ba` as unsupported, and no Bitwarden item for NIC.ba/UTIC/SnowIT domain registrar credentials was found.

## Evidence

Product worktree:

`/Users/makinja/business/ALAI-Holding-AS/products/SEO-Readiness-Portal`

Evidence files:

- `PHASE-1-EVIDENCE.md`
- `PHASE-2-EVIDENCE.md`
- `PHASE-3-EVIDENCE.md`
- `PHASE-4-EVIDENCE.md`
- `PHASE-5-EVIDENCE.md`
- `PHASE-6-EVIDENCE.md`
- `PHASE-7-EVIDENCE.md`
- `PHASE-8-EVIDENCE.md`
- `PHASE-9-EVIDENCE.md`
- `PHASE-10-EVIDENCE.md`
- `PHASE-11-EVIDENCE.md`
- `PHASE-12-EVIDENCE.md`
- `UX-ADD-CLIENT-EVIDENCE.md`
- `/tmp/evidence-102370/add-client-ux-validation.log`
- `/tmp/evidence-102370/browser-add-client-flow.json`
- `/tmp/evidence-102370/browser-add-client-flow-summary.txt`
- `/tmp/evidence-102370/add-client-live-deploy-and-smoke.log`
- `/tmp/evidence-102370-live-auth/verification.json`
- `/tmp/evidence-102370-live-auth/SUMMARY.md`
- `/tmp/evidence-102370/screenshots/01-partners-add-client-cta.png`
- `/tmp/evidence-102370/screenshots/02-new-client-form.png`
- `/tmp/evidence-102370/screenshots/03-created-client-intake.png`
- `/tmp/alai/seo-readiness-phase3-http-smoke.txt`
- `/tmp/alai/redzo-102064-review.md`
- `/tmp/alai/company-mesh-responder/2026-05-26T11-20-45-604Z-mesh-msg-1c229051-b7e6-4bdc-af43-c442d3dd8fe2.json`
- `/tmp/alai/seo-readiness-phase4-http-smoke.txt`
- `/tmp/alai/redzo-102070-review.md`
- `/tmp/alai/seo-readiness-phase5-http-smoke.txt`
- `/tmp/alai/seo-readiness-phase6-hard-evidence-102091/command-log.txt`
- `/tmp/alai/seo-readiness-phase6-http-smoke.txt`
- `/tmp/alai/seo-readiness-phase7-hard-evidence-102112/command-log.txt`
- `/tmp/alai/seo-readiness-phase7-http-smoke.txt`
- `/tmp/alai/seo-readiness-phase8-hard-evidence-102220/command-log.txt`
- `/tmp/alai/seo-readiness-phase8-http-smoke.txt`
- `/tmp/alai/seo-readiness-phase9-hard-evidence-102231/command-log.txt`
- `/tmp/alai/seo-readiness-phase9-http-smoke.txt`
- `/tmp/alai/seo-readiness-phase10-hard-evidence-102323/command-log.txt`
- `/tmp/alai/seo-readiness-phase10-http-smoke.txt`
- `/tmp/alai/seo-readiness-phase11-evidence-102338/command-log.txt`
- `/tmp/alai/seo-readiness-phase11-evidence-102338/docker-build.txt`
- `/tmp/alai/seo-readiness-phase11-evidence-102338/docker-compose-ps.txt`
- `/tmp/alai/seo-readiness-phase11-evidence-102338/container-health.json`
- `/tmp/alai/seo-readiness-phase11-evidence-102338/container-unauth-partners.txt`
- `/tmp/alai/seo-readiness-phase11-evidence-102338/container-auth-partners.txt`
- `/tmp/alai/seo-readiness-phase11-evidence-102338/browser/phase11-browser-verify.json`
- `/tmp/alai/gemini-102338-phase11-review-v2.md`
- `/tmp/alai/seo-readiness-phase12-evidence-102350/seo-tools-alai-unauth-curl.txt`
- `/tmp/alai/seo-readiness-phase12-evidence-102350/seo-tools-alai-spoof-and-local.txt`
- `/tmp/alai/seo-readiness-phase12-evidence-102350/browser/live-unauth-browser-verify.json`
- `/tmp/alai/seo-readiness-phase12-evidence-102350/browser/seo-tools-alai-access-redirect.png`
- `/tmp/evidence-102350/cloudflare-tunnel-remote-config-add-seo-tools.txt`
- `/tmp/evidence-102350/cloudflare-tunnel-remote-config-seo-tools-127001.txt`
- `/tmp/evidence-102350-info-snowit-strict/verification.json`
- `/tmp/evidence-102350-info-snowit-strict/SUMMARY.md`
- `/tmp/evidence-102350-info-snowit-strict/screenshots/S04-after-login.png`
- `/tmp/evidence-102350/live-edge-and-origin-check-after-auth-uat.txt`
- `/tmp/alai/seo-readiness-phase12-evidence-102350/cloudflare-access-seo-tools-alai.txt`
- `/tmp/alai/seo-readiness-phase12-evidence-102350/cloudflare-access-seo-tools-snowit.txt`
- `/tmp/alai/seo-readiness-phase12-evidence-102350/route53-snowit-ba-records-summary.txt`
- `/tmp/alai/seo-readiness-phase12-evidence-102350/cloudflare-snowit-pending-zone-record-sync.txt`
- `/tmp/alai/seo-readiness-phase12-evidence-102350/cloudflare-access-seo-tools-snowit-retry-after-zone-sync.txt`
- `/tmp/alai/seo-readiness-phase12-evidence-102350/snowit-ba-nameserver-change-request-bs.md`
- `/tmp/alai/seo-readiness-phase12-evidence-102350/aws-registrar-snowit.txt`
- Company Mesh/P2P PASS: `mesh-thr-ede2b968-6abc-4354-a24b-be13f4f0262d` / `mesh-msg-1827f723-6ae5-4f22-b868-afd2da5d1dc2`
- `/tmp/alai/redzo-102231-review-v2-with-evidence.md`
- Company Mesh/P2P PASS: `mesh-thr-83994892-4a0c-4dc7-96c3-c553511f9a8f` / `mesh-msg-32536a8d-8826-4a74-a665-a52c07805f33`

Validation commands observed through Phase 11:

```bash
npm run type-check
npm run validate:spec
npm run validate:phase2
npm run validate:phase3
npm run validate:phase4
npm run validate:phase5
npm run validate:phase6
npm run validate:phase7
npm run validate:phase8
npm run validate:phase9
npm run validate:phase10
npm run validate:phase11
npm run build
npm audit --audit-level=high
python3 /tmp/alai/seo-readiness-phase3-smoke.py
python3 /tmp/alai/seo-readiness-phase4-smoke.py
python3 /tmp/alai/seo-readiness-phase5-smoke.py
python3 /tmp/alai/seo-readiness-phase6-smoke.py
python3 /tmp/alai/seo-readiness-phase7-smoke.py
python3 /tmp/alai/seo-readiness-phase8-smoke.py
# Phase 9 smoke was curl-based; see /tmp/alai/seo-readiness-phase9-http-smoke.txt

```

Observed results:

- type-check: PASS
- validate:spec: PASS
- validate:phase2: PASS
- validate:phase3: PASS
- validate:phase4: PASS
- validate:phase5: PASS
- validate:phase6: PASS
- validate:phase7: PASS
- validate:phase8: PASS
- validate:phase9: PASS
- build: PASS
- npm audit high threshold: PASS; moderate postcss/next advisory remains and was not force-fixed
- local HTTP smoke: PASS for `/`, `/partners`, `/clients/client-demo-nordic-clinic`, `/clients/client-demo-nordic-clinic/intake`
- Phase 4 local HTTP smoke: PASS for audit detail route `/clients/client-demo-nordic-clinic/audits/<auditId>`
- Phase 5 local HTTP smoke: PASS for report detail route `/clients/client-demo-nordic-clinic/reports/<reportId>`
- Phase 6 local HTTP smoke: PASS for export detail route `/clients/client-demo-nordic-clinic/reports/<reportId>/exports/<exportId>`
- Phase 7 local HTTP smoke: PASS for export review status markers on `/clients/client-demo-nordic-clinic/reports/<reportId>/exports/<exportId>`
- Phase 8 local HTTP smoke: PASS for local handoff checklist markers on `/clients/client-demo-nordic-clinic/reports/<reportId>/exports/<exportId>`
- Phase 9 local HTTP smoke: PASS for local handoff summary draft markers on `/clients/client-demo-nordic-clinic/reports/<reportId>/exports/<exportId>`
- Phase 9 independent review: Redzo APPROVE and Company Mesh/P2P PASS
- Phase 10 local HTTP smoke: PASS for local partner follow-up package markers on `/clients/client-demo-nordic-clinic/reports/<reportId>/exports/<exportId>`
- Phase 11 packaging validation: PASS for standalone config, Docker packaging, localhost-only origin, `/data` volume, access mode, allowlist configuration, and runbook checks
- Phase 11 Docker build: PASS for `alai/seo-readiness-portal:internal`
- Phase 11 container health: PASS for `http://127.0.0.1:3100/api/health`
- Phase 11 unauthenticated page access: PASS/blocked with HTTP 401 and `x-seo-portal-access: blocked`
- Phase 11 authenticated-header page access: PASS/allowed with HTTP 200 and `x-seo-portal-access: cf-access`
- Phase 11 browser verification: PASS for blocked unauthenticated `/partners` and allowed authenticated-header `/partners`
- Phase 11 independent read-only Gemini CLI review: PASS for deploy-readiness packaging and access-gate behavior, with live DNS/Cloudflare hookup explicitly not claimed
- Phase 11 Company Mesh/P2P pre-verifier: PASS for ready\_for\_review scope on deploy-readiness packaging and access-gate behavior
- Phase 12 `seo-tools.alai.no` live protected route: PASS for unauthenticated Cloudflare Access redirect and spoofed trusted-header redirect
- Phase 12 `seo-tools.snowit.ba`: BLOCKED by Cloudflare Access zone ownership requirement until `snowit.ba` is active/delegated to Cloudflare or the internal URL decision changes

## Non-goals preserved

- No public unauthenticated deploy.
- No live DNS/Cloudflare Access configuration completed for `seo-tools.snowit.ba` in this session.
- No nameserver migration for `snowit.ba` was executed automatically.
- No production database connection or secrets.
- No Google Search Console or Analytics integration.
- No paid keyword/SERP API integration.
- No ranking or traffic claims.

## Suggested next phase

Phase 13 candidate: obtain registrar/NIC access path for `snowit.ba`, execute the approved nameserver migration to Cloudflare, then create the exact `seo-tools.snowit.ba` Access application and run authenticated browser verification through the SnowIT URL. Pending Cloudflare zone is already pre-populated.

## 2026-06-22 — LIVE self-serve autonomous loop verified (MC #102915)

- **Status:** LIVE in production, autonomous self-serve loop confirmed end-to-end WITHOUT human involvement.
- **Azure:** app `seo-readiness-alai` (`rg-seo-readiness-prod`), state Running, image `20260618-ga4-selfheal` (real audit engine).
- **Public self-serve path:** `https://seo-tools.snowit.ba/intake/<token>` (CF Access bypass for `/intake/*`; `/partners` stays gated).
- **Independent Proveo live E2E (real browser/Playwright) — PASS:**
    - Magic-link intake form renders (HTTP 200, screenshot).
    - AI chatbot live (`/api/intake-chat`) returns real Bosnian response — tier: Groq.
    - Form submit → IntakeSubmission v1 persisted (screenshot).
    - Auto-audit pipeline fired post-submit: `live_crawl` OK + `report_draft` OK, audit (3 findings), report with 9-step Bosnian action plan — all in ~10s.
- **Evidence:** `/tmp/alai/seo-portal-e2e-104192/` (screenshots step3/step5, step4-uat-chat.json, workspace-live-after-submit.json); til-done receipt `/tmp/til-done/102915-20260622T133626Z.json`; verdict `/tmp/evidence-102915/verdict.json`.
- **Open follow-ups (non-blocking):**
    1. Production chatbot single-tier Groq only — no Anthropic fallback key on live app → 503 risk if Groq down.
    2. Minor: `pipeline_record`/`notify` stages not persisted to workspace snapshot (`intake-pipeline.ts` ~L208).
    3. Google GSC/GA restricted-scope still pending Google OAuth verification (#103428) — affects live ranking/traffic data only, NOT the crawl-based audit which works now.

**Conclusion:** ALAI/SnowIT has a working autonomous SEO tool that serves clients (audit + Bosnian action plan) without Asmir or CEO at every step except the designed partner-mediated magic-link entry.

---

## See Also — Agent Runbook

The canonical end-to-end workflow runbook (intake to John deep-report, anti-pitfalls, trigger checklist) lives here:

- [SEO Pipeline — Portal Intake to John Deep-Report (agent runbook)](https://docs.alai.no/books/seo-readiness-portal/page/seo-pipeline-portal-intake-john-deep-report-agent-runbook)