feat(notion): migrate 31+32 to API 2025-09-03 + add property writes, upsert, anchor-link fix

Phase 1 — docs alignment:
- Fix path drift in 32 CLAUDE.md (02-notion-writer → 32-notion-writer)
- Align env var to NOTION_API_KEY in 31 docs (NOTION_TOKEN still accepted)
- Document Phase 3 roadmap in 31 (metadata-aware migration, Notion-as-RAG)

Phase 2 — multi-source database support:
- New 32/scripts/_notion_compat.py: client factory, data_source resolution
  with cache, property coercion, find_existing_page (for upsert),
  explain_api_error for friendlier failure messages
- 32 notion_writer.py: drop the 2022-06-28 pin, route schema introspection
  through data_sources.retrieve, build data_source_id parent shape, accept
  arbitrary properties via --properties JSON-or-file flag, add --upsert-by
  for idempotent re-runs
- 32 markdown parser: anchor-link fix — Notion's URL validator rejects
  fragment URLs and relative paths; fragments now render as bold to preserve
  TOC nav intent, relatives drop the link, absolute URLs preserved
- 31 async_organizer.py + schema_migrator.py: same data_sources migration
  with cached resolution; pages.create now uses data_source_id parent
- 16/16 parser tests pass (was 13; +3 link-handling regression guards)

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

custom-skills/31-notion-organizer/code/CLAUDE.md

@@ -79,11 +79,40 @@ python scripts/async_organizer.py --database [ID] --action restructure
 
 Environment variables:
 ```bash
-NOTION_TOKEN=secret_xxx
+# Preferred (matches 32-notion-writer)
+NOTION_API_KEY=secret_xxx
+
+# Legacy fallback also accepted
+# NOTION_TOKEN=secret_xxx
 ```
 
+The scripts read `NOTION_TOKEN` first, then fall back to `NOTION_API_KEY`. Use `NOTION_API_KEY` for new setups so the same `.env` works across all Notion skills.
+
 ## Notes
 
 - Always use `--dry-run` first for destructive operations
 - Large operations (1000+ pages) use async with progress reporting
 - Scripts implement automatic rate limiting
+
+## Roadmap (Phase 3)
+
+The current scripts cover schema migration and async bulk ops. Two larger goals are parked for a future iteration:
+
+### Goal 1 — Metadata-aware page move/integration
+
+Search source pages, compare their property metadata against a target database schema, and move/migrate while transforming property values to fit. Beyond the existing `schema_migrator.py` (which expects a hand-written mapping file), this would:
+
+- Auto-suggest property mappings using name + type similarity
+- Surface unmappable properties before the move (no silent data loss)
+- Support cross-database moves (not just same-schema migrations)
+
+### Goal 2 — Notion as personal RAG source
+
+Treat Notion as a small, personal knowledge base for AI agents:
+
+- Search pages by query across databases, filter by property
+- Merge results into a single context (with source citations back to page URLs)
+- Summarize / distill via LLM into agent-ready snippets
+- Export as JSONL or markdown for fine-tuning or RAG indexing
+
+This dovetails with `90-reference-curator` (which does the same for web sources) — Phase 3 would make Notion a first-class source type for that pipeline.