Enhancement: Opt-in orphan pruning for pages removed from nav

[virtualguard101]

Summary

When notes are removed from nav or deleted locally, Notion pages are left intact. Over time this causes orphan pages and stale section nodes in the wiki database.

Today the sync only logs:

deleted locally (Notion page left intact): <path>

Motivation

Structure reconciliation (reparent / ensure sections) fixes wrong parent but not pages that should no longer exist in the mirrored tree. Users need an explicit, safe way to clean up Notion without accidental mass deletion.

Proposed solution

Add opt-in pruning — never enabled by default.

mkdocs-note ns --prune=archive    # archive in Notion + drop from local state
mkdocs-note ns --prune=delete     # hard delete (dangerous)
mkdocs-note ns --dry-run --prune=archive

Optional flags:

• --prune-sections — remove empty stale section pages after content orphans are handled.
• mkdocs.yml: notion_sync.prune: off | archive | delete

Behavior

1. After building nav tree + loading state, compute pages in state that are no longer nav-listed (scoped by --section when set).
2. --prune=archive: Notion archive API + remove key from .notion_sync_state.json.
3. --prune=delete: delete page + remove from state.
4. Dry-run: list every page that would be archived/deleted with title and URL.

Safety requirements

• Prune never runs without an explicit flag.
• Dry-run must list all prune targets before execution.
• Summary: archived, deleted, orphans_skipped.
• Document risk: manual Notion-only pages under the same database may be pruned if not in nav (consider allowlist / not_in_nav escape hatch).

Acceptance criteria

• Default sync does not archive or delete anything.
• --prune=archive archives a page removed from nav.
• --dry-run --prune=archive shows targets without API writes.

Related

• Structure reconciliation (reparent / ensure sections) — separate issue