## AI Blog Writer — Implementation Specification (Copilot-first, Research-led)

### Overview
- **Goal**: Build a SOTA AI blog writer that guides non-technical users end-to-end: research → outline → section generation → quality/SEO → publishing.
- **Approach**: Copilot-first UX using CopilotKit. Reuse LinkedIn assistive writing patterns: Google Search grounding, Exa research, hallucination detector, quality analysis, citations.
- **User Interaction Model**: The user only talks to the Copilot; the editor reflects all state and changes via generative UI and HITL confirmations.

### Key Principles
- **AI-first, HITL**: The assistant leads with intelligent suggestions; the user approves via render-and-wait HITL components where appropriate.
- **Research fidelity**: Google grounding + Exa researcher; hallucination detection with claim verification; pervasive citations.
- **Persona-aware**: Import blog writing persona from DB and apply it across planning/generation/optimizations.
- **SEO-excellent**: Real-time SEO analysis, metadata generation, schema, and image alt handling.
- **Publish-ready**: Smooth handoff to Wix/WordPress; preview and scheduling.

---

## 1) Workflow (4 Stages)

### Stage 1: Research & Strategy (AI Orchestration)
Inputs
- `keywords: string[]`, `industry: string`, `targetAudience: string`, `tone: string`, `wordCountTarget: number`, `userId`
- Persona is fetched from DB and persisted in session

Backend/Services
- Reuse LinkedIn research handler patterns: Google native grounding (Gemini provider), optional Exa research.
- Reuse hallucination detector service and models: `/api/hallucination-detector/*` for claim extraction and verification.

CopilotKit Actions
- `getPersonaFromDB(userId)` → persona constraints and style.
- `analyzeKeywords(keywords, industry, audience)` → search intent, primary/secondary/long-tail, difficulty, volume.
- `researchTopic(topic, depth, sources=['google','exa'])` → aggregated research sources (with credibility + timestamps).
- `analyzeCompetitors(keywords, industry)` → top pages, headings used, gaps/opportunities.

Generative UI (render-only)
- Research Summary card: sources, credibility score, proposed angles.
- Suggested Keywords: chip list; add/remove HITL.

Suggestions (programmatic)
- “Confirm research”, “Refine keywords”, “Add competitor”, “Proceed to outline”.

---

### Stage 2: Content Planning (AI + Human)
Deliverables
- Structured outline (H1/H2/H3), per-section key points, citations to use, target word counts.

CopilotKit Actions
- `generateOutline(research, persona, wordCount)` → full outline with per-section targets and suggested refs.
- `refineOutline(operation, sectionId, payload?)` → add/remove/move/merge sections (HITL diff in UI).
- `attachReferences(sectionId, sourceIds[])` → associate sources to sections.

Generative UI (HITL)
- Outline Editor: draggable sections/subsections, per-section references and target words, persona style hints.

Suggestions
- “Generate [Section 1]”, “Regenerate [Section 2]”, “Attach sources to [Section]”, “Generate All Sections”.

---

### Stage 3: Content Generation (CopilotKit-only, no multi-agent)
Deliverables
- Long-form markdown content with inline citations, persona-aligned tone, and sectioned structure.

CopilotKit Actions
- `generateSection(sectionPlan, keywords, tone, persona, refs[])` → returns markdown + inline cites.
- `generateAllSections(outline)` → sequential section generation with progress render.
- `optimizeSection(content, goals[])` → readability/EEAT/examples/data improvements; UI shows diff preview (HITL confirm).
- `runHallucinationCheck(content)` → uses `/api/hallucination-detector/detect` to flag claims + propose fixes.

Editor/UI Updates
- Per-section markdown tabs; word count; inline citation chips; section mini-SEO score.
- DiffPreview component for any AI edit prior to apply.

Suggestions
- “Add table/figure”, “Insert case study with source”, “Strengthen introduction”, “Tighten conclusion CTA”.

---

### Stage 4: Optimization & Publishing (AI + Human)
SEO Optimization
- `analyzeSEO(content, keywords)` → density, heading structure, links, readability, image alt coverage, overall SEO score.
- `generateSEOMetadata(content, title, keywords)` → title options, meta description, OG/Twitter cards, schema Article/FAQ.
- `applySEOFixes(suggestions[])` → diff preview + HITL apply.

Publishing
- `prepareForPublish(platform: 'wix' | 'wordpress')` → HTML + images + metadata packaging.
- `publishToPlatform(platform, schedule?)` → uses Wix/WordPress clients (ToBeMigrated integrations). Shows URL/status.

Suggestions
- “Run SEO analysis”, “Apply recommended fixes”, “Generate metadata”, “Publish to WordPress”, “Schedule on Wix”.

---

## 2) SEO Tools Integration & Metadata

Existing Services to Wrap
- Meta Description, OpenGraph, Image Alt, On-Page SEO, Technical SEO, Content Strategy (see `backend/services/seo_tools/*` and docs).

Unified Endpoints
- `POST /api/blog/seo/analyze` → { seoScore, density, structure, readability, link suggestions, image alt status, recs }
- `POST /api/blog/seo/metadata` → { titleOptions, metaDescriptionOptions, openGraph, twitterCard, schema: { Article, FAQ?, Breadcrumb, Org/Person } }

Editor SEO Panel
- Live density and distribution, readability (Flesch-Kincaid), heading hierarchy, internal/external link suggestions.
- One-click “Apply Fix” with diff preview.

Schema
- Default Article schema; optional FAQ when Q&A snippets exist; Breadcrumb, Organization/Person as applicable.

---

## 3) Dedicated Blog Editor Design (Copilot-first)

Layout
- Left: Markdown Editor (per-section tabs), word count, persona cues, inline citation chips.
- Right: Live Preview (desktop/mobile), SEO SERP snippet preview, social preview (OG/Twitter).
- Sidebar Panels: Research (sources, claims), SEO (scores/fixes), Media (AI images + alt text), History (versions).

Core Components
- `BlogResearchCard` (render-only): sources, credibility scores, add-to-outline.
- `OutlineEditor` (HITL): drag-drop H2/H3, per-section refs and target words.
- `SectionEditor`: markdown area with persona/tone badges; per-section SEO mini-score.
- `DiffPreview` (HITL): apply/reject AI edits.
- `SEOPanel`: density/structure/readability + apply fix.
- `MediaPanel`: AI images, compression, automatic alt-text.

CopilotKit Integrations
- Suggestions: set programmatically (`useCopilotChatHeadless_c`) or via `CopilotSidebar` props.
- Generative UI: `useCopilotAction({ render })` for research cards, outline editor, diff preview, publish dialog.
- HITL: `renderAndWaitForResponse` for approvals at outline, diff apply, and publish steps.
- References: CopilotKit docs — Frontend Actions, Generative UI, Suggestions, HITL.

Persistence
- Persist outline, per-section content, references, persona snapshot, SEO state, metadata drafts.
- Auto-save every 30s; version history for undo.

---

## 4) Backend APIs

New Blog Endpoints
- `POST /api/blog/research` → inputs: keywords/industry/audience/tone/wordCount, personaId?; returns research bundle.
- `POST /api/blog/outline/generate` → returns structured outline with targets and ref suggestions.
- `POST /api/blog/outline/refine` → returns updated outline (operation-based).
- `POST /api/blog/section/generate` → returns markdown + inline citations.
- `POST /api/blog/section/optimize` → returns optimized content + rationale.
- `POST /api/blog/quality/hallucination-check` → proxies hallucination detector results for blog.
- `POST /api/blog/seo/analyze` → wraps SEO analyzers; returns scores/suggestions.
- `POST /api/blog/seo/metadata` → returns title/meta/OG/Twitter/schema.
- `POST /api/blog/publish` → platform: wix|wordpress, schedule?; returns URL/status.

Reuse
- `/api/hallucination-detector/detect|extract-claims|verify-claim|health` (already implemented).

Models (indicative)
- `BlogResearchRequest`, `BlogResearchResponse`
- `BlogOutline`, `BlogOutlineRefinement`
- `BlogSectionRequest`, `BlogSectionResponse`
- `BlogSEOAnalysisRequest`, `BlogSEOMetadataResponse`

---

## 5) CopilotKit Action Inventory

Research
- `getPersonaFromDB`, `analyzeKeywords`, `researchTopic`, `analyzeCompetitors`

Planning
- `generateOutline`, `refineOutline`, `attachReferences`

Generation
- `generateSection`, `generateAllSections`, `optimizeSection`, `runHallucinationCheck`

SEO
- `analyzeSEO`, `generateSEOMetadata`, `applySEOFixes`

Publishing
- `prepareForPublish`, `publishToPlatform`

UX/Render-only/HITL
- `showResearchCard`, `showOutlineEditor`, `showDiffPreview`, `showSEOPanel`, `showPublishDialog`

---

## 6) Intelligent Suggestions (states)

Before research
- “Load persona”, “Analyze keywords”, “Research topic”

After research
- “Generate outline”, “Add competitor H2s”, “Attach sources”

Outline ready
- “Generate [Section 1]”, “…”, “Generate all sections”

Draft ready
- “Run fact-check”, “Run SEO analysis”, “Generate metadata”

Final
- “Publish to WordPress”, “Schedule on Wix”

---

## 7) Delivery Plan / Milestones

Milestone 1: Research + Outline
- Actions: persona load, analyze keywords, research topic, generate outline, outline editor (HITL)

Milestone 2: Section Generation + Quality
- generateSection/generateAllSections, optimizeSection with diff preview, hallucination check + fixes

Milestone 3: SEO & Metadata
- analyzeSEO panel, generateSEOMetadata (title/meta/OG/Twitter/schema), apply fixes

Milestone 4: Publishing
- prepareForPublish, publishToPlatform (Wix/WordPress), schedule, success URL

Milestone 5: Polish
- Readability aids, version history, performance, accessibility

---

## 8) References
- CopilotKit Quickstart, Frontend Actions, Generative UI, HITL, Suggestions
  - Quickstart: https://docs.copilotkit.ai/direct-to-llm/guides/quickstart
  - Frontend Actions: https://docs.copilotkit.ai/frontend-actions
  - Generative UI: https://docs.copilotkit.ai/direct-to-llm/guides/generative-ui
  - Headless + Suggestions + HITL: https://docs.copilotkit.ai/premium/headless-ui

---

## 9) Notes on Reuse from LinkedIn Writer
- Research handler; Gemini grounded provider; citation manager; quality analyzer.
- Hallucination detector + Exa verification endpoints.
- CopilotKit integration patterns: actions, suggestions, render/HITL, state persistence.