doc update

STAGE_3_PLAN.md

@@ -0,0 +1,375 @@
+expects the agent to read:
+
+STAGE_1_COMPLETE.md
+
+STAGE_2_REFACTOR_COMPLETE.md
+
+✅ STAGE 3 — FINAL PIPELINE COMPLETION PROMPT
+IGNY8 Unified Workflow, WordPress Sync, Publishing, and Final System Stabilization
+MANDATORY HEADER — DO NOT SKIP
+
+The backend is fully finalized per STAGE_1_COMPLETE.md.
+The frontend architecture and UI structure are defined in STAGE_2_EXECUTION_PLAN.md.
+
+You MUST NOT:
+
+modify backend models
+
+modify backend serializers
+
+modify backend fields
+
+change content_type or content_structure choices
+
+modify WordPress plugin structure
+
+create new database fields
+
+change Stage 1 or 2 logic
+
+Stage 3 is pipeline-level integration, end-to-end fixing, and system stabilization, NOT architecture change.
+
+🎯 STAGE 3 GOAL
+
+Make IGNY8 fully functional, with a working, reliable end-to-end pipeline:
+
+Planner → Writer → Content Manager → Publish → WordPress → Sync → Cluster & Taxonomy Updates → Final Status
+
+This stage ensures:
+
+everything connects
+
+everything updates correctly
+
+statuses reflect reality
+
+cluster mapping works
+
+taxonomy assignments work
+
+WordPress sync is stable
+
+publish flow is consistent
+
+Writer → Content → WP loop is clean
+
+system supports full-scale SEO workflows
+
+🔷 PART A — END-TO-END PIPELINE FLOW FIXES
+A.1 Planner → Task Flow Verification
+
+Ensure:
+
+Keywords → Clusters mapping correct
+
+Ideas → Tasks creation uses final fields
+
+Clusters created appear correctly in Writer & Content Manager
+
+No legacy fields flow into tasks
+
+Task statuses correctly set to queued → completed
+
+Fix any broken points.
+
+A.2 Writer → Content Flow
+
+Ensure:
+
+Writer generates correct content_html
+
+Writer stores data using final fields from Stage 1
+
+Writer tasks insert content into Content table
+
+Correct mapping:
+
+cluster
+
+content_type
+
+content_structure
+
+taxonomy_term (optional)
+
+Content created through Writer must appear immediately in Content Manager
+
+Task status must update to “completed” after generation
+
+Fix any inconsistencies.
+
+🔷 PART B — CONTENT MANAGER FINALIZATION
+
+The Content Manager becomes the “📌 Single Source of Truth” in IGNY8.
+
+You must ensure:
+B.1 Content Manager loads all content types
+
+From both:
+
+IGNY8 generated content
+
+WordPress-synced content
+
+B.2 Editing is stable
+
+Editor page must:
+
+load existing content correctly
+
+allow editing title and content_html
+
+allow cluster assignment
+
+allow taxonomy assignment
+
+save updates reliably
+
+show backend validation errors clearly
+
+B.3 Taxonomy assignment works
+
+Assigning categories/tags/attributes must update ContentTaxonomy M2M
+
+No old taxonomy structures referenced
+
+B.4 Cluster assignment works
+
+Content cluster updated reliably
+
+Appears correctly in Cluster Detail page
+
+B.5 Filters fully functional
+
+Remove dead filters.
+Ensure all filters are aligned with backend schema.
+
+🔷 PART C — WORDPRESS INTEGRATION (IMPORT + PUBLISH)
+
+This part ensures the SEO cycle is complete.
+
+C.1 WordPress Sync (WP → IGNY8)
+
+Verify and fix:
+
+Import posts/pages/products → Creates Content rows
+
+Import categories/tags/product_attrs → Creates ContentTaxonomy rows
+
+Imported content:
+
+source = wordpress
+
+status = draft
+
+correct mapping of external_id & external_url
+
+Verify:
+
+site connections
+
+WP credentials
+
+CORS rules
+
+error handling
+
+Fix anything missing.
+
+C.2 WordPress Publish (IGNY8 → WP)
+When user clicks “Publish” in Content Manager:
+
+Pipeline MUST:
+
+Build WP payload
+
+Include:
+
+title (post_title)
+
+content_html (post_content)
+
+taxonomy mappings via external_id
+
+content_type → correct WP post_type
+
+Send POST request to WP REST API
+
+On success:
+
+Update external_id
+
+Update external_url
+
+status → published
+
+source → igny8
+
+Fix all missing or unstable behavior.
+
+C.3 Prevent Duplicate Publishing
+
+Ensure:
+
+Content with external_id cannot publish again
+
+Instead, show “View on WordPress” action
+
+Add frontend guard to disable publish
+
+Add backend guard to return 400 “Already published”
+
+🔷 PART D — CLUSTER DETAIL PAGE INTEGRATION
+
+Ensure cluster detail page:
+
+fetches content by cluster
+
+supports:
+
+articles
+
+pages
+
+products
+
+taxonomy archive items
+
+uses final backend fields
+
+links items to Content Manager
+
+supports filters
+
+Fix any broken integration.
+
+🔷 PART E — SITES MODULE PIPELINE
+
+Stage 3 ensures the Sites module is fully integrated:
+
+E.1 Site → Planner Link
+
+Clusters display only for selected site.
+Ideas feed into tasks for the active site.
+
+E.2 Site → Writer Link
+
+Writer tasks must be per-site
+(Different sites should not mix content.)
+
+E.3 Site → Content Manager Link
+
+Content Manager must only load content for selected site.
+
+E.4 Site → WordPress Credentials
+
+Ensure publish + sync functions use the active site’s credentials.
+
+🔷 PART F — STATUS SYSTEM (FINAL CLEANUP)
+
+The final statuses MUST be:
+
+F.1 Content Status
+
+draft
+
+published
+
+F.2 Task Status
+
+queued
+
+completed
+
+F.3 Source
+
+igny8
+
+wordpress
+
+Ensure:
+
+No legacy statuses appear anywhere in the frontend or backend.
+
+🔷 PART G — PERFORMANCE & RELIABILITY CHECKS
+
+Implement:
+
+Pagination improvements
+
+Loading states
+
+Error messages
+
+Retry messages
+
+Graceful handling of WP network issues
+
+Handling slow Writer/AI operations
+
+Prevent double actions (double publish, double sync)
+
+Full test run across pipeline
+
+🔷 PART H — STAGE 3 DOCUMENTATION UPDATE
+
+Update main docs:
+
+Full pipeline workflow
+
+Sequence diagrams
+
+Final UI screenshots
+
+API interaction diagrams
+
+All user flows (Planner → Writer → Content → Publish)
+
+🔷 PART I — CHANGELOG UPDATE
+
+Append:
+
+[2025-11-XX] IGNY8 Stage 3 — Full System Pipeline Complete
+- Completed end-to-end workflow integration
+- Fully functional Content Manager with editing, cluster/taxonomy assignment, publishing
+- Verified WordPress import + publish flows
+- Added frontend guards against double publish
+- Unified content source + status logic
+- Cleaned all final inconsistencies across Planner → Writer → Content Manager
+- IGNY8 is production-ready with complete pipeline
+
+🔥 FINAL EXECUTION INSTRUCTIONS (AGENT)
+
+You MUST:
+
+Fix all pipeline gaps
+
+Update all frontend integration points
+
+Refine all WordPress flows
+
+Verify all status transitions
+
+Confirm API compatibility with Stage 1 backend
+
+Produce all updated code files
+
+Update documentation
+
+Update changelog
+
+Provide a final summary of:
+
+All updated pages
+
+All updated components
+
+All updated stores
+
+All updated hooks
+
+Pipeline fixes
+
+WordPress integration fixes
+
+Begin Stage 3 execution now.