# SEO Client Workflow — Skill (/seo-client) + Intake Auto-Ingest

# SEO Client Workflow — Layers 2+3 Architecture

**Status:** Active (2026-06-03)  
**Driver:** Asmir SEO partner clients (first = Smoke House Hadžići)  
**MCs:** #102865 (skill), #102866 (intake ingest)  
**Owner:** Skillforge (docs), CodeCraft (ingest), FlowForge (launchd)

## Architecture Overview

The SEO client workflow is structured in 3 layers:

- **Layer 1:** SEO Readiness Portal tool — local/cloud dual-mode audit, GBP/local-first for no-website clients (MC #102861, see [GBP/Local-First Audit Mode](https://docs.alai.no/books/seo-readiness-portal/page/gbplocal-first-audit-mode-no-website-clients))
- **Layer 2:** `/seo-client` skill — generates 5 Bosnian DRAFT deliverables from intake
- **Layer 3:** Intake auto-ingest — parses inbound email into portal workspace

## Layer 2: /seo-client Skill

### Location

`~/.claude/skills/seo-client/SKILL.md`

### Purpose

Given a client SEO intake (from SEO Readiness Portal workspace data **OR** pasted partner email), produce 5 review-ready **DRAFT** deliverables in Bosnian. Never auto-send. All outputs are local drafts under `/tmp/alai/seo-client/<client-slug>/` for human review before delivery.

### Inputs

- **Portal workspace:** `/path/to/portal/.data/workspace.json` (client, site, intake objects)
- **Pasted intake email:** numbered questionnaire text (like Asmir partner emails)
- **Email ID:** `--email-id <id>` (fetches via `email-inbox.js`, read-only)

### Deliverables (5 Bosnian DRAFTS)

1. **gbp-content.md** — GBP optimization content:
    - Business description (max 750 chars, keyword-rich, natural BS)
    - Primary + 2-3 secondary categories (from GBP taxonomy)
    - Suggested attributes (wheelchair accessible, parking, etc.)
    - 3-5 sample GBP posts (seasonal offers, service updates, local events)
    - Review-ask template (polite, brief, BS)
2. **competitor-benchmark.md** — Competitor analysis:
    - For each competitor (up to 3): GBP completeness, review count/rating, categories, notable strengths
    - Client gap analysis + quick wins
    - Actionable recommendations
    - *Note:* No live GBP API scraping (Phase 10+); manual research or intake-provided competitor URLs
3. **client-report.md** — Client-facing SEO readiness report (BS):
    - Executive summary (current status + top opportunity)
    - Goals (from intake: target location, priority services, conversion action)
    - Current status table (Technical SEO, On-page, Content, Local SEO, Conversion — RAG status)
    - Top findings (P0/P1/P2 prioritized)
    - Recommended action plan (Week 1-2, Month 1, Month 2-3)
    - What we need from client (access, approvals, content)
    - Measurement (KPIs: organic traffic, GBP interactions, contact forms)
    - **Disclaimer:** SEO does NOT guarantee ranking/traffic
    - *Evidence grounding:* portal audit findings (if website exists) or GBP checklist (if GBP-first mode)
4. **client-email-draft.md** — Draft client email (BS):
    - Subject line suggestion
    - Summary: what was reviewed, top findings
    - Immediate asks: missing access, info gaps, priorities
    - Next steps: what ALAI/partner will do after client responds
    - Disclaimer: readiness review only, no ranking/traffic guarantee
    - **Mark as DRAFT** — never auto-send
5. **owner-gbp-claim-guide.md** — Step-by-step GBP claim + add-ALAI-as-Manager guide (BS):
    - Go to business.google.com
    - Search for business name + location
    - Claim existing listing (if unclaimed)
    - Verify ownership (postcard/phone/email)
    - Complete profile: hours, photos, services, description
    - Add ALAI/partner as Manager (Settings → Users → Add user, role: Manager)
    - Notify ALAI/partner when access granted
    - *Screenshot placeholders:* `[Screenshot: GBP claim button]`

### Guardrails

- **No ranking/traffic guarantees:** forbidden words enforced (`ranking|traffic|guarantee|guaranteed|first page|top results`)
- **Drafts only:** all outputs are local files; NO auto-send, NO email trigger
- **Optional Lexicon BS check:** route to Lexicon (Dževad Jahić) for linguistic QA if requested
- **MAX TURNS:** 30 (skill execution timeout)
- **No fabricated metrics:** no Search Console/Analytics data without verified access
- **No hardcoded competitor data:** always from intake or prompt user

### Workflow Modes

- **GBP\_FIRST mode:** no website detected (`intake.hasWebsite === false` OR `site.canonicalUrl` empty)
    - Focus: `owner-gbp-claim-guide.md` as P0 deliverable
    - Skip website-specific audit findings
    - All deliverables optimized for GBP
- **WEBSITE\_AND\_GBP mode:** website exists
    - Run portal audit: `npm run audit -- --client <slug>`
    - Parse audit findings for client report evidence
    - Include both website + GBP recommendations

### Evidence Bundle

On completion, creates `/tmp/alai/seo-client/<client-slug>/DELIVERABLES-MANIFEST.md` with:

- File checklist (all 5 deliverables)
- Validation: PASS (no forbidden words)
- Linguistic QA: PENDING | REVIEWED\_BY\_LEXICON
- Approval: PENDING\_HUMAN\_REVIEW
- Next steps: human review required before client delivery

### Registration

Registered in `~/.claude/skill-registry.db`:  
\- **Name:** seo-client  
\- **Triggers:** /seo-client, "seo client workflow", "process seo intake", "generate seo deliverables", "asmir seo tip"  
\- **Domain:** seo-operations  
\- **Level:** 3  
\- **Max Turns:** 30  
\- **Status:** active

## Layer 3: Intake Auto-Ingest

### Location

`~/business/ALAI-Holding-AS/products/SEO-Readiness-Portal/scripts/ingest-intake-email.ts`

### Purpose

Parse inbound client SEO intake email (numbered questionnaire format) and append a DRAFT Client+Site+Intake record to the portal workspace. Idempotent via ingest ledger. Read-only email access; no email send.

### Usage

```
# Ingest specific email by ID
npm run ingest:intake -- --email-id <id>

# Scan pending ACTION emails (list only)
npm run ingest:intake -- --scan

# Dry-run mode (no writes)
npm run ingest:intake -- --email-id <id> --dry-run

# Auto-run audit after ingest (deferred; not implemented in current draft)
npm run ingest:intake -- --email-id <id> --run-audit

```

### Workflow

1. **Email fetch:** Shell-out to `node ~/system/tools/email-inbox.js show <id>` (read-only, no network calls)
2. **Parse:** Extract numbered intake fields:
    - Business name, location, services, languages
    - Target markets (local/regional/national)
    - Competitors (names or URLs)
    - GBP status (claimed/unclaimed, manager access yes/no)
    - Website status (has website yes/no, URL if yes)
    - Analytics/Search Console status
    - Priority services, conversion goals
3. **Workspace append:** Create draft Client, Site, Intake objects:
    - `client.status = "lead"`
    - `intake.status = "submitted"`
    - `intake.hasWebsite = inferred from question "Do you have a website?"`
    - `site.canonicalUrl = empty if no website (triggers GBP-first mode in skill)`
4. **Idempotency:** Dedup by source email ID via `.data/ingest-ledger.json`:
    - Schema: `{ schemaVersion: 1, updatedAtUtc, ingestedEmailIds: { [emailId]: { emailId, clientId, siteId, intakeId, ingestedAtUtc } } }`
    - If email ID already in ledger → skip (NOOP)
5. **Output:** JSON summary to stdout:
    - Email ID, client ID, site ID, intake ID
    - Client name, status, target markets
    - Site domain (or "no website — GBP/local mode")
    - Intake status, hasWebsite, gbpClaimed, gbpManagerAccess, priorityServicesCount, competitorsCount

### Guardrails

- **DRAFT only:** status = "lead"/"submitted" — no active/onboarded promotion
- **No audit auto-run:** unless `--run-audit` flag (not implemented; manual run via portal)
- **No email send:** read-only email access, no outbound mail
- **No production mutation:** writes only to local workspace file (`.data/workspace.json`) + ledger

### Launchd Wrapper (Deferred)

Template at `scripts/launchd/com.alai.seo-intake-ingest.plist`:  
\- NOT installed (manual trigger for now)  
\- When enabled: periodic scan for ACTION emails, auto-ingest eligible intake questionnaires  
\- Safe + logged (writes to `~/logs/seo-intake-ingest.log`)

## End-to-End Flow

1. **Intake email arrives** (from Asmir or direct client) → tagged ACTION by email-inbox.js rules
2. **Layer 3 ingest:** `npm run ingest:intake -- --email-id <id>` → creates draft client in portal workspace
3. **Portal GBP audit:** CEO or automated task runs audit (Layer 1) → evidence collected
4. **Layer 2 skill:** `/seo-client` generates 5 Bosnian DRAFT deliverables
5. **CEO review:** human reviews drafts at `/tmp/alai/seo-client/<client-slug>/`
6. **Send:** CEO or agent manually copies content to client email / BookStack client page

## Limitations / Deferred

- **Live GBP API:** Google OAuth + Places API deferred pending CEO approval (Phase 10+)
- **Launchd not installed:** manual trigger for intake ingest (no auto-scan yet)
- **No auto-send:** all deliverables require human review gate
- **No Search Console/Analytics API:** access verification deferred
- **Single language:** Bosnian (BS) only; EN/DE deferred
- **No BookStack page auto-creation:** manual copy-paste for client-facing docs

## Related Documentation

- [Layer 1: GBP/Local-First Audit Mode](https://docs.alai.no/books/seo-readiness-portal/page/gbplocal-first-audit-mode-no-website-clients)
- SEO Operations Playbook: `~/business/ALAI-Holding-AS/sales/seo-automation/SEO-OPERATIONS-PLAYBOOK.md`
- Client Report Template: `~/business/ALAI-Holding-AS/sales/seo-automation/seo-client-report-template.md`
- Bosnian Linguistic QA: `~/system/rules/bosnian-linguistic-validation.md`

## Evidence

- **MC #102865:** /seo-client skill authored at `~/.claude/skills/seo-client/SKILL.md`
- **MC #102866:** Intake ingest script at `scripts/ingest-intake-email.ts`
- **Test fixture:** Asmir email #8792 (Smoke House Hadžići)
- **Skill registration:** `~/.claude/skill-registry.db`
- **Status:** DRAFT (no deploy, no auto-send, no production data mutation)