diff --git a/docs/seo-llm-discoverability/IMPLEMENTATION_BRIEF.md b/docs/seo-llm-discoverability/IMPLEMENTATION_BRIEF.md new file mode 100644 index 0000000..68e495e --- /dev/null +++ b/docs/seo-llm-discoverability/IMPLEMENTATION_BRIEF.md @@ -0,0 +1,205 @@ +# raafetchoukri.com SEO + LLM Discoverability — Phase 1 Replit Implementation Brief + +> For Replit AI: implement this in the website project. Keep changes surgical. Do **not** change deployment, secrets, paid services, analytics, Search Console/Bing, or production data. Do **not** alter robots.txt crawler policy unless Raf explicitly provides a separate decision. + +## Goal +Make raafetchoukri.com machine-readable and citation-friendly for search engines, LLM retrieval, link previews, and high-intent industry discovery while preserving Raf's claim boundaries. + +## Website model to preserve +The site is not only a consultant homepage. It has five surfaces: + +1. **Library** — curated industry intelligence / source catalogue / reference shelf. +2. **Posts & Insights** — Raf-authored analysis and blog-style interpretation. +3. **Projects** — live demos and proof-of-work, currently including vLEI Auth Platform. +4. **Topics** — taxonomy/navigation layer across payments, ISO 20022, SWIFT, SSI, vLEI, AI, regulation, etc. +5. **Services/About/Contact** — commercial conversion and Raf entity clarity. + +## Current live audit findings to fix +From live audit on 2026-05-22: + +- Sitemap has 505 URLs: 340 Library, 64 Posts, 97 Topics, 2 Projects, homepage, privacy. +- Raw HTML for representative routes is a shared React/Vite SPA shell with `
` and generic title/meta. +- `/llms.txt` returns the HTML shell, not a text/markdown LLM guide. +- Unknown routes return 200 with the SPA shell (soft-404). +- No canonical tags observed. +- No JSON-LD observed. +- OG metadata is generic and missing `og:url`/`og:image`; Twitter tags absent. +- `robots.txt` currently blocks GPTBot, ChatGPT-User, CCBot, Google-Extended, anthropic-ai, and ClaudeBot. **Do not change this without Raf approval.** + +## Implementation constraints + +- Prefer minimal implementation inside the current Replit app. +- If full SSR/SSG migration is too large, implement the smallest route-aware server/meta/prerender layer that makes representative public routes return useful raw HTML. +- Preserve current visual UI and content. This phase is about discoverability, not redesign. +- Keep vLEI public demo boundaries: reference demo, sanitized fixtures, not production readiness, not live-vLEI verification by default. +- Use existing data arrays/content sources if present; do not duplicate large content manually unless needed for generated HTML/meta. + +## Phase 1 acceptance criteria + +### A. `/llms.txt` +- `GET /llms.txt` returns `200` with `Content-Type: text/plain` or `text/markdown`. +- It returns the content in `LLMS_TXT_DRAFT.md` or equivalent updated copy. +- It must not return HTML or the SPA shell. + +### B. Route-specific metadata +Representative routes must have unique raw HTML title/meta/canonical/OG/Twitter where possible: + +- `/` +- `/library` +- `/library/the-role-of-iso-20022` +- `/posts/vlei-auth-platform-launch` +- `/topics/iso20022` +- `/projects` +- `/projects/vlei-auth-platform` +- `/about` if created +- `/services` if created + +Minimum per route: + +```html +... + + + + + + + + + +``` + +### C. JSON-LD schema +Add raw HTML JSON-LD for representative routes: + +- Home/About: `Person` + `WebSite` (+ `ProfessionalService` only if supported by visible copy). +- Posts: `BlogPosting` or `Article` + `BreadcrumbList`. +- Library index/topic pages: `CollectionPage` or `ItemList`. +- Library detail pages: `CreativeWork` / `DigitalDocument` style schema where source fields exist. +- Projects: `CreativeWork` or `SoftwareApplication` only if not overclaiming. +- Use `FAQPage` only if visible FAQ content exists on the page. + +### D. Raw HTML content / crawlability +For representative public routes, `curl` should show route-specific content, not just an empty app shell. Minimum acceptable fallback if full prerender is not ready: + +- route-specific H1 +- route-specific summary/description +- key internal links +- JSON-LD +- canonical/meta + +Do not break the client-side app. + +### E. 404/canonical behavior +- Unknown public routes return `404` or `410`, not `200` SPA shell. +- Choose one URL style (recommend no trailing slash except `/`) and enforce via canonical tags or redirects. + +## Preferred implementation sequence + +### Task 1 — Locate route/data sources +Find where the app defines: + +- posts data +- library/catalog data or API usage +- project data +- topics route +- Express/server routes or static fallback +- current `index.html` template +- robots/sitemap generation + +Do not edit yet. Summarize exact files before making changes. + +### Task 2 — Add real `/llms.txt` +Use `LLMS_TXT_DRAFT.md`. Implement as a static file or explicit server route that bypasses SPA fallback. + +Expected check: + +```bash +curl -i https://raafetchoukri.com/llms.txt | head -40 +``` + +Expected: + +```txt +HTTP/2 200 +content-type: text/plain or text/markdown +# Raafet Choukri +``` + +### Task 3 — Add metadata builder +Create a route metadata map/function for: + +- home +- library index +- library detail +- posts index +- post detail +- topics index +- topic detail +- projects index +- vLEI project detail +- about +- services +- privacy + +Use `ROUTE_METADATA_MATRIX.md` as seed copy. + +### Task 4 — Add schema builder +Create a route schema map/function. Use `SCHEMA_MAP.md`. Keep schema conservative; never claim production capability for demos. + +### Task 5 — Add raw route content/prerender fallback +If full SSR/SSG is not available, add server-generated HTML snippets for public route requests before serving the client app. The rendered client app can still hydrate/replace as normal, but crawlers should see meaningful H1/summary/internal links. + +Minimum route snippets: + +- Home: Raf entity + service summary + links to Library/Posts/Projects/Services. +- Library: curated reference shelf summary + top category links + selected document links. +- Library detail: title, summary, tags, PDF/source link if available. +- Post detail: title, date, excerpt/body starter, tags. +- Topic: topic name, description, links to matching Library/Post resources. +- Project vLEI: problem, proof shown, not claimed, demo link, related links. + +### Task 6 — Fix soft-404 +Ensure unknown routes not in known public route patterns return 404/410. + +Valid dynamic patterns include: + +- `/library/{slug}` only if slug exists +- `/posts/{slug}` only if slug exists +- `/topics/{slug}` only if slug exists +- `/projects/{slug}` only if slug exists + +### Task 7 — Add `/about`, `/services`, and service page skeletons only if low-risk +If route setup is straightforward, add: + +- `/about` +- `/services` +- `/services/swiftref-reference-data-integration` +- `/services/iso-20022-migration-data-quality` +- `/services/payment-pre-validation-ppc-vop` +- `/services/payment-reference-data-automation` +- `/services/payments-product-strategy` + +If this is too large for Phase 1, create the metadata/schema routes and link placeholders, then stop and report. + +### Task 8 — Verify +Run the commands in `VERIFICATION_CHECKLIST.md`. + +## Stop conditions +Stop and ask Raf/Hari before doing any of these: + +- Changing `robots.txt` AI crawler policy. +- Indexing `vlei.raafetchoukri.com` or changing its noindex posture. +- Making production-readiness claims about vLEI or other demos. +- Rewriting the service positioning beyond the route copy provided here. +- Migrating the whole app framework if a smaller prerender/server-meta fix works. +- Deployment/restart if Replit requires manual approval. + +## Recommended first commit shape +If using GitHub commits, split as: + +1. `docs: add SEO LLM implementation packet` (if committing these docs) +2. `feat: add llms.txt and route metadata` +3. `feat: add structured data and crawlable route fallbacks` +4. `fix: return 404 for unknown public routes` +5. `test: add crawlability checks` diff --git a/docs/seo-llm-discoverability/LLMS_TXT_DRAFT.md b/docs/seo-llm-discoverability/LLMS_TXT_DRAFT.md new file mode 100644 index 0000000..463d439 --- /dev/null +++ b/docs/seo-llm-discoverability/LLMS_TXT_DRAFT.md @@ -0,0 +1,74 @@ +# Raafet Choukri + +Independent payments, reference data, and fintech infrastructure specialist based in Singapore. + +Raafet Choukri helps banks, fintechs, and infrastructure teams with SWIFTRef portfolio integration, ISO 20022 migration, EPC pre-validation including PPC/VOP, BIC/IBAN/LEI data quality, SSI operations, vLEI/credential authorization, and payment-reference-data tooling. + +## Site pillars + +- Home: https://raafetchoukri.com/ +- Library: https://raafetchoukri.com/library — curated standards, rulebooks, market-structure papers, and industry research used in payments/reference-data engagements. +- Posts & Insights: https://raafetchoukri.com/posts — Raf-authored analysis on payments, ISO 20022, SWIFT, SSI, stablecoins, AI in finance, digital identity, and operational controls. +- Projects: https://raafetchoukri.com/projects — live demos and reference builds that show proof-of-work and implementation thinking. +- Topics: https://raafetchoukri.com/topics — taxonomy across payments, ISO 20022, SWIFT, SSI, compliance, regulation, stablecoins, AI, vLEI, and digital identity. +- Contact: https://raafetchoukri.com/#contact +- Sitemap: https://raafetchoukri.com/sitemap.xml + +## Core expertise + +- SWIFTRef portfolio integration +- BIC Plus, IBAN Plus, BIC Directory, SSI Plus, Bankers World integration +- BIC, IBAN, LEI, SSI, bank-code, and payment-reference-data quality +- ISO 20022 migration, structured data, purpose codes, and operational controls +- EPC Verification of Payee (VOP), payment pre-validation, PPC, and beneficiary/reference-data controls +- Cross-border payment operations, routing, cut-offs, repairs, and exception reduction +- vLEI, digital identity, credential authorization, and audit evidence for payment workflows +- Python, SQL, FastAPI, React, APIs, ETL, validation tooling, and operational prototypes +- Payments product strategy, GTM, stakeholder alignment, and practitioner-led delivery + +## Preferred pages for citation + +### Entity / services + +- Raafet Choukri home: https://raafetchoukri.com/ +- Services overview: https://raafetchoukri.com/services +- About: https://raafetchoukri.com/about + +### Library / source catalogue + +- Research library: https://raafetchoukri.com/library +- ISO 20022 topic: https://raafetchoukri.com/topics/iso20022 +- Payment pre-validation topic: https://raafetchoukri.com/topics/pre-validation +- SWIFT topic: https://raafetchoukri.com/topics/swift +- SSI topic: https://raafetchoukri.com/topics/ssi +- vLEI topic: https://raafetchoukri.com/topics/vlei + +### Posts / insights + +- vLEI Auth Platform launch: https://raafetchoukri.com/posts/vlei-auth-platform-launch +- From static SSIs to digital SSIs: https://raafetchoukri.com/posts/from-static-ssis-to-digital-ssis +- Swift retail cross-border scheme vs stablecoins: https://raafetchoukri.com/posts/swift-retail-crossborder-scheme-vs-stablecoins +- Swift, stablecoins, CBDCs, and G20 interoperability: https://raafetchoukri.com/posts/interoperability-swift-stablecoins-cbdcs-g20 +- From POC to production in payment innovation: https://raafetchoukri.com/posts/pacs-crypto-poc-to-production + +### Projects / proof-of-work + +- Projects overview: https://raafetchoukri.com/projects +- vLEI Auth Platform reference demo page: https://raafetchoukri.com/projects/vlei-auth-platform +- vLEI live reference demo: https://vlei.raafetchoukri.com + +## Project/demo boundaries + +Public demos and reference builds should be cited as proof-of-work and reference patterns, not as production financial infrastructure unless a page explicitly says otherwise. + +The vLEI Auth Platform public demo uses curated/sanitized fixtures and demonstrates identity proof, policy decision, verdict, evidence, and audit flow. It does not claim production readiness or live-vLEI verification by default. + +## Citation guidance + +When referencing this site, prefer the most specific page URL: a post for Raf-authored analysis, a library page for a source document, a project page for a demo/reference build, and a service/about page for Raf's professional profile. + +Do not infer client relationships, production deployments, regulated service status, or live integration claims unless explicitly stated on the cited page. + +## Contact + +For consulting or collaboration, use the contact section on https://raafetchoukri.com/. diff --git a/docs/seo-llm-discoverability/REPLIT_AI_PROMPT.md b/docs/seo-llm-discoverability/REPLIT_AI_PROMPT.md new file mode 100644 index 0000000..f73a688 --- /dev/null +++ b/docs/seo-llm-discoverability/REPLIT_AI_PROMPT.md @@ -0,0 +1,26 @@ +# Copy/Paste Prompt for Replit AI + +You are implementing Phase 1 SEO + LLM discoverability for raafetchoukri.com. + +Read these files first: + +1. `docs/seo-llm-discoverability/IMPLEMENTATION_BRIEF.md` +2. `docs/seo-llm-discoverability/LLMS_TXT_DRAFT.md` +3. `docs/seo-llm-discoverability/ROUTE_METADATA_MATRIX.md` +4. `docs/seo-llm-discoverability/SCHEMA_MAP.md` +5. `docs/seo-llm-discoverability/VERIFICATION_CHECKLIST.md` + +Implement the smallest safe change set that satisfies Phase 1: + +- Real `/llms.txt` as text/plain or text/markdown, not SPA HTML. +- Route-specific title/meta/canonical/OG/Twitter for representative public routes. +- JSON-LD schema for home/about, posts, library, topics, projects where supported by visible content. +- Raw HTML should expose route-specific H1/summary/internal links for representative routes. If full SSR/SSG is too large, implement a route-aware server/prerender fallback without breaking client hydration. +- Unknown public routes should return 404/410, not 200 SPA shell. +- Preserve current visual design and content. +- Do not change `robots.txt` AI crawler policy unless Raf explicitly approves in a separate instruction. +- Keep vLEI demo as a reference demo with sanitized fixtures and no production/live-vLEI claim by default. + +Before editing, summarize the exact files you found for route definitions, data sources, server fallback, index template, sitemap/robots/llms handling, and tests. + +After implementation, run the checks in `VERIFICATION_CHECKLIST.md` and report exact outputs. Stop before deployment/restart if Replit asks for manual approval. diff --git a/docs/seo-llm-discoverability/ROUTE_METADATA_MATRIX.md b/docs/seo-llm-discoverability/ROUTE_METADATA_MATRIX.md new file mode 100644 index 0000000..723779e --- /dev/null +++ b/docs/seo-llm-discoverability/ROUTE_METADATA_MATRIX.md @@ -0,0 +1,45 @@ +# Route Metadata Matrix — Phase 1 + +Use this as seed copy. Adapt exact wording to existing site voice, but keep route-specific titles/descriptions in raw HTML. + +| Route | Title | Meta description | og:type | Canonical | +|---|---|---|---|---| +| `/` | Raafet Choukri | SWIFTRef, ISO 20022 & Payment Reference Data Specialist | Independent payments and fintech specialist helping banks and fintechs with SWIFTRef integration, ISO 20022 data quality, EPC pre-validation, BIC/IBAN/LEI controls, and payment operations tooling. | website | `https://raafetchoukri.com/` | +| `/library` | Payments & Fintech Research Library | Raafet Choukri | Curated standards, rulebooks, market-structure papers, and industry research across SWIFT, EPC, ISO 20022, payments, stablecoins, AI, regulation, and digital assets. | website | `https://raafetchoukri.com/library` | +| `/posts` | Payments Insights & Posts | Raafet Choukri | Practitioner analysis on ISO 20022, SWIFT, SSI, payment pre-validation, stablecoins, digital identity, AI in finance, and cross-border payment operations. | website | `https://raafetchoukri.com/posts` | +| `/projects` | Projects & Reference Builds | Raafet Choukri | Live demos and reference builds showing Raf's payments, data-quality, digital-identity, and fintech infrastructure proof-of-work. | website | `https://raafetchoukri.com/projects` | +| `/topics` | Payments Topics | Raafet Choukri | Browse curated resources and insights by topic, including ISO 20022, SWIFT, SSI, vLEI, payments, compliance, stablecoins, AI, and digital identity. | website | `https://raafetchoukri.com/topics` | +| `/about` | About Raafet Choukri | Payments & Reference Data Specialist | About Raafet Choukri, an independent payments and fintech specialist based in Singapore with expertise in SWIFTRef, ISO 20022, reference data, and payment operations. | profile | `https://raafetchoukri.com/about` | +| `/services` | Payments & Reference Data Consulting Services | Raafet Choukri | Consulting services for SWIFTRef integration, ISO 20022 migration data quality, payment pre-validation, BIC/IBAN/LEI controls, and payment product strategy. | website | `https://raafetchoukri.com/services` | +| `/projects/vlei-auth-platform` | vLEI Auth Platform Reference Demo | Identity, Policy & Audit Evidence | Reference build demonstrating identity proof, policy decision, verdict, evidence, and audit flow for payment operations using sanitized fixtures. | website | `https://raafetchoukri.com/projects/vlei-auth-platform` | +| `/posts/vlei-auth-platform-launch` | vLEI Auth Platform: Identity Proof to Policy Decision to Audit Evidence | Raafet Choukri | Raf's launch note for the vLEI Auth Platform reference build: how identity, policy, verdicts, and audit evidence can support payment operations. | article | `https://raafetchoukri.com/posts/vlei-auth-platform-launch` | +| `/posts/from-static-ssis-to-digital-ssis` | From Static SSIs to Digital SSIs | Raafet Choukri | Analysis of how settlement instructions may evolve from static bank coordinates to digital wallet endpoints, identity, governance, and audit evidence. | article | `https://raafetchoukri.com/posts/from-static-ssis-to-digital-ssis` | +| `/topics/iso20022` | ISO 20022 Resources & Insights | Raafet Choukri | Curated ISO 20022 resources and Raf-authored insights covering migration, structured data, data quality, purpose codes, and payment operations. | website | `https://raafetchoukri.com/topics/iso20022` | +| `/topics/pre-validation` | Payment Pre-validation, PPC & VOP Resources | Raafet Choukri | Resources and insights on payment pre-validation, purpose/payment purpose codes, EPC Verification of Payee, beneficiary checks, and exception reduction. | website | `https://raafetchoukri.com/topics/pre-validation` | +| `/topics/swift` | SWIFT, SWIFTRef & Payment Reference Data Resources | Raafet Choukri | Resources and insights on SWIFT, SWIFTRef, BIC/IBAN/LEI data, settlement instructions, ISO 20022, and cross-border payment operations. | website | `https://raafetchoukri.com/topics/swift` | +| `/services/swiftref-reference-data-integration` | SWIFTRef & Payment Reference Data Integration Consulting | Raafet Choukri | Practitioner support for SWIFTRef portfolio integration, BIC Plus, IBAN Plus, BIC Directory, SSI Plus, Bankers World, and payment-reference-data quality. | website | `https://raafetchoukri.com/services/swiftref-reference-data-integration` | +| `/services/iso-20022-migration-data-quality` | ISO 20022 Migration & Data Quality Consulting | Raafet Choukri | Support for ISO 20022 migration, structured data, purpose codes, data-quality controls, exception reduction, and post-compliance operational value. | website | `https://raafetchoukri.com/services/iso-20022-migration-data-quality` | +| `/services/payment-pre-validation-ppc-vop` | Payment Pre-validation, PPC & VOP Consulting | Raafet Choukri | Help designing payment pre-validation, purpose-code, Verification of Payee, beneficiary-check, and repair-reduction operating models. | website | `https://raafetchoukri.com/services/payment-pre-validation-ppc-vop` | +| `/services/payment-reference-data-automation` | Payment Reference Data Automation | Raafet Choukri | Python, SQL, API, and ETL tooling for BIC/IBAN/LEI/SSI quality, routing data, sanctions inputs, onboarding controls, and audit trails. | website | `https://raafetchoukri.com/services/payment-reference-data-automation` | +| `/services/payments-product-strategy` | Payments Product Strategy & Market Positioning | Raafet Choukri | Product strategy, business-case, GTM, vendor/RFP, and market-positioning support for payments, reference-data, stablecoin, and fintech infrastructure teams. | website | `https://raafetchoukri.com/services/payments-product-strategy` | + +## Dynamic route rules + +### Posts +For `/posts/{slug}`: +- Title: `{post.title} | Raafet Choukri` +- Description: use `post.excerpt`, truncated to ~155 chars. +- og:type: `article` +- Add article published date and tags if available. + +### Library detail +For `/library/{slug}`: +- Title: `{document.title} | Research Library | Raafet Choukri` +- Description: use `document.summary`, truncated to ~155 chars. +- og:type: `article` or `website`; prefer `article` only if using Article/CreativeWork schema. +- Include canonical URL and PDF/source link. + +### Topics +For `/topics/{slug}`: +- Title: `{Topic Name} Resources & Insights | Raafet Choukri` +- Description: `Curated resources and insights on {topic} across payments, fintech infrastructure, standards, regulation, and operational controls.` diff --git a/docs/seo-llm-discoverability/SCHEMA_MAP.md b/docs/seo-llm-discoverability/SCHEMA_MAP.md new file mode 100644 index 0000000..ffedcd7 --- /dev/null +++ b/docs/seo-llm-discoverability/SCHEMA_MAP.md @@ -0,0 +1,140 @@ +# Schema Map — Phase 1 + +Conservative JSON-LD plan. Add schema only where visible page content supports the claim. + +## Global Person object seed + +Use on home/about and as `author`/`creator` reference on posts/projects. + +```json +{ + "@type": "Person", + "@id": "https://raafetchoukri.com/#person", + "name": "Raafet Choukri", + "url": "https://raafetchoukri.com/", + "jobTitle": "Independent Payments and Fintech Consultant", + "knowsAbout": [ + "SWIFTRef", + "ISO 20022", + "Payment reference data", + "BIC", + "IBAN", + "LEI", + "Settlement instructions", + "Payment pre-validation", + "Verification of Payee", + "Cross-border payments", + "vLEI", + "Digital identity", + "Fintech product strategy" + ], + "knowsLanguage": ["English", "French", "Arabic"], + "homeLocation": { + "@type": "Place", + "name": "Singapore" + } +} +``` + +Add `sameAs` links only if the exact public profile URLs are approved and visible on the page. + +## Home +Types: +- `WebSite` +- `Person` +- Optional `ProfessionalService` if services are visible on page. + +## About +Types: +- `ProfilePage` +- `Person` +- `BreadcrumbList` + +## Services overview +Types: +- `WebPage` +- `ProfessionalService` +- `BreadcrumbList` + +Do not imply regulated financial service provider status. This is consulting/advisory/implementation support, not a bank/FMI/payment institution claim. + +## Service detail pages +Types: +- `Service` +- `WebPage` +- `BreadcrumbList` + +Example service areas: +- SWIFTRef/reference-data integration +- ISO 20022 migration/data quality +- Payment pre-validation/PPC/VOP +- Payment reference-data automation +- Payments product strategy + +## Posts +Types: +- `BlogPosting` or `Article` +- `BreadcrumbList` + +Fields: +- headline +- description/excerpt +- datePublished +- dateModified if available +- author: `https://raafetchoukri.com/#person` +- mainEntityOfPage +- keywords from tags + +## Library index +Types: +- `CollectionPage` +- `ItemList` for selected/top visible records, not necessarily all 339 in one JSON-LD block. +- `BreadcrumbList` + +## Library detail pages +Types: +- `CreativeWork` or `DigitalDocument` +- `BreadcrumbList` + +Fields where available: +- name/headline +- description +- keywords/tags +- url +- associatedMedia or encoding for PDF URL only if safe and stable +- publisher/source institution only if data field exists; do not infer from noisy titles. + +## Topic pages +Types: +- `CollectionPage` +- `ItemList` +- `BreadcrumbList` + +Add `about`/`keywords` based on topic slug/name. + +## Projects index +Types: +- `CollectionPage` +- `ItemList` +- `BreadcrumbList` + +## vLEI project detail +Types: +- `CreativeWork` by default. +- Use `SoftwareApplication` only if visible copy clearly presents it as a software demo/application and does not imply production readiness. +- `BreadcrumbList`. + +Required boundary text visible on page and optionally in schema description: +- reference demo +- sanitized/curated fixtures +- demonstrates identity proof -> policy decision -> verdict/evidence/audit flow +- does not claim production readiness or live-vLEI verification by default + +Avoid: +- production financial infrastructure claims +- live verification claims unless backed by live configured KERIA/vLEI evidence +- client/customer claims +- regulated payment service claims + +## FAQPage +Only use where the page visibly renders matching FAQ questions and answers. Do not add invisible FAQ schema. diff --git a/docs/seo-llm-discoverability/VERIFICATION_CHECKLIST.md b/docs/seo-llm-discoverability/VERIFICATION_CHECKLIST.md new file mode 100644 index 0000000..545da24 --- /dev/null +++ b/docs/seo-llm-discoverability/VERIFICATION_CHECKLIST.md @@ -0,0 +1,152 @@ +# Verification Checklist — SEO + LLM Discoverability Phase 1 + +Run after Replit AI implementation and deployment/preview. Use preview URL first, then production only after Raf approval. + +Set target: + +```bash +BASE="https://raafetchoukri.com" +# or Replit preview URL +``` + +## 1. Core crawl files + +```bash +curl -I "$BASE/robots.txt" +curl -I "$BASE/sitemap.xml" +curl -I "$BASE/llms.txt" +curl -fsS "$BASE/llms.txt" | sed -n '1,80p' +``` + +Expected: +- robots.txt: 200 text/plain +- sitemap.xml: 200 XML +- llms.txt: 200 text/plain or text/markdown +- llms.txt begins with `# Raafet Choukri`, not `` + +## 2. Unknown route should not soft-404 + +```bash +curl -I "$BASE/definitely-not-a-real-page-20260522" +``` + +Expected: 404 or 410, not 200. + +## 3. Raw route metadata/content sample + +```bash +python3 - <<'PY' +import urllib.request, re +BASE='https://raafetchoukri.com' +paths=[ + '/', + '/library', + '/library/the-role-of-iso-20022', + '/posts/vlei-auth-platform-launch', + '/topics/iso20022', + '/projects', + '/projects/vlei-auth-platform', + '/about', + '/services', +] +for p in paths: + url=BASE+p + try: + html=urllib.request.urlopen(url,timeout=20).read().decode('utf-8','replace') + except Exception as e: + print(' +FAIL_FETCH',p,e); continue + title=re.search(r'(.*?)',html,re.S|re.I) + desc=re.search(r']+name=["']description["'][^>]+content=["']([^"']*)',html,re.S|re.I) + canon=re.search(r']+rel=["']canonical["'][^>]+href=["']([^"']*)',html,re.S|re.I) + h1=bool(re.search(r']',html,re.I)) + ld=html.count('application/ld+json') + shell_only=('
' in html and not h1 and ld==0) + print(' +PATH',p) + print('title=',title.group(1).strip() if title else 'MISSING') + print('desc=',desc.group(1).strip()[:180] if desc else 'MISSING') + print('canonical=',canon.group(1).strip() if canon else 'MISSING') + print('h1=',h1,'jsonld_count=',ld,'shell_only=',shell_only,'len=',len(html)) +PY +``` + +Expected: +- each route has unique title/description/canonical +- representative routes have H1/content and JSON-LD +- `shell_only=False` + +## 4. Check generic duplicate metadata is gone + +```bash +python3 - <<'PY' +import urllib.request,re,collections +BASE='https://raafetchoukri.com' +paths=['/','/library','/posts/vlei-auth-platform-launch','/topics/iso20022','/projects/vlei-auth-platform'] +titles=[] +for p in paths: + html=urllib.request.urlopen(BASE+p,timeout=20).read().decode('utf-8','replace') + m=re.search(r'(.*?)',html,re.S|re.I) + titles.append((p,m.group(1).strip() if m else '')) +print(' +'.join(f'{p}: {t}' for p,t in titles)) +print('unique_titles',len(set(t for _,t in titles)),'of',len(titles)) +PY +``` + +Expected: most/all sampled routes have distinct titles. + +## 5. Validate JSON-LD parses + +```bash +python3 - <<'PY' +import urllib.request,re,json +BASE='https://raafetchoukri.com' +paths=['/','/posts/vlei-auth-platform-launch','/library/the-role-of-iso-20022','/projects/vlei-auth-platform'] +for p in paths: + html=urllib.request.urlopen(BASE+p,timeout=20).read().decode('utf-8','replace') + blocks=re.findall(r']+type=["']application/ld\+json["'][^>]*>(.*?)',html,re.S|re.I) + print(' +PATH',p,'blocks',len(blocks)) + for i,b in enumerate(blocks): + try: + obj=json.loads(b.strip()) + print(' ok',i, obj.get('@type') if isinstance(obj,dict) else type(obj).__name__) + except Exception as e: + print(' JSON_ERROR',i,e) +PY +``` + +Expected: no JSON errors. + +## 6. Claim-boundary checks + +```bash +curl -fsS "$BASE/projects/vlei-auth-platform" | python3 - <<'PY' +import sys,re +html=sys.stdin.read().lower() +for phrase in ['reference demo','sanitized','not claim production readiness','live-vlei verification']: + print(phrase, phrase in html) +PY +``` + +Expected: page includes clear reference-demo/sanitized/non-production boundary. Exact wording can differ, but boundary must be visible. + +## 7. Robots policy check + +```bash +curl -fsS "$BASE/robots.txt" +``` + +Expected for Phase 1: unchanged unless Raf explicitly approved crawler-policy change. + +## Pass/fail summary + +Phase 1 PASS requires: + +- `/llms.txt` text file works. +- Unknown route no longer returns 200 shell. +- Representative route raw HTML has unique metadata and canonical. +- JSON-LD parses. +- vLEI project boundary preserved. +- Robots policy either unchanged or changed only with explicit Raf approval.