revamps docs complete

master-docs/90-misc/MIGRATION-NOTES.md

@@ -0,0 +1,55 @@
+ # Migration Notes
+ 
+ ## Purpose
+ Track significant schema or data migrations, with references to the scripts present in the repo that have been used to adjust data or structure.
+ 
+ ## Code Locations (exact paths)
+ - Migration/utility scripts (repo root `backend/`):
+   - `verify_migrations.py`, `verify_status_fixes.py`, `verify_taxonomy.py`
+   - `fix_*` scripts (e.g., `fix_cluster_status.py`, `fix_content_types.py`, `fix_integration_site_url.py`, `fix_sync.py`, `fix_taxonomy_relationships.py`)
+   - `rename_fields_migration.sql`
+   - `inject_test_data.py`, `sync_idea_status.py`, `check_recent_keywords.py`, `check_api_response.py`, `diagnose_generate_content.py`
+ - Django migrations: `backend/igny8_core/**/migrations/` (per app)
+ 
+ ## High-Level Responsibilities
+ - Capture when ad-hoc fixes or manual SQL were required so future migrations can account for existing state.
+ - Provide guidance on verifying migrations after code changes.
+ 
+ ## Detailed Behavior
+ - Python fix/verify scripts operate against live DBs to patch or validate data (names indicate target domain: clusters/content/integration/taxonomy).
+ - `rename_fields_migration.sql` suggests a manual SQL rename was performed; ensure corresponding Django migration exists or is applied.
+ - `verify_*` scripts check consistency after migrations or data changes.
+ - These scripts are not automatically executed; they are run manually as needed.
+ 
+ ## Execution Flow (Recommended)
+ - Prefer standard Django migrations first: `python manage.py makemigrations && python manage.py migrate`.
+ - For data issues covered by fix scripts:
+   - Review script purpose and run in controlled environment (staging) before production.
+   - Take DB backup before executing manual SQL or fix scripts.
+ - After applying migrations/fixes, run verify scripts to confirm expected state.
+ 
+ ## Cross-Module Interactions
+ - Scripts touch planner/writer/integration data; impacts automation and billing indirectly if content/status changes alter usage.
+ 
+ ## State Transitions (if applicable)
+ - DB schema changes via migrations; data patches via scripts.
+ 
+ ## Error Handling
+ - Scripts log/print outputs; failures will surface during execution; no centralized handler.
+ 
+ ## Tenancy Rules
+ - All scripts should respect account/site scoping; review code before running to ensure filters exist or add them.
+ 
+ ## Billing Rules (if applicable)
+ - None directly; data corrections may affect content/automation counts but not credit logs.
+ 
+ ## Background Tasks / Schedulers (if applicable)
+ - None; scripts are on-demand.
+ 
+ ## Key Design Considerations
+ - Keep fix/verify scripts version-controlled but treat them as one-off tools; remove or archive obsolete scripts.
+ - Ensure Django migrations are the source of truth for schema; manual SQL should be mirrored in migrations.
+ 
+ ## How Developers Should Work With This Module
+ - Before running any fix/verify script, read it and constrain to target account/site if possible.
+ - Add notes here when new manual interventions occur, including date/purpose and scripts used.

master-docs/90-misc/TEMPORARY-NOTES.md

@@ -0,0 +1,11 @@
+ # Temporary Notes
+ 
+ ## Purpose
+ Provide a space for short-lived operational notes or in-progress decisions; should be cleared or moved to canonical docs once finalized.
+ 
+ ## Current Guidance
+ - No active temporary notes documented. Use this file to capture time-bound decisions, experiments, or rollout instructions, then archive or delete after completion.
+ 
+ ## How Developers Should Work With This Module
+ - Add date-stamped bullet points for any temporary guidance.
+ - When resolved, move durable learnings into the relevant module docs and prune from here.