#!/usr/bin/env bash
#
# archive_superseded.sh
# Relocate documentation superseded by GEOMETRIC_SUBSTANCE_CANONICAL.md into a
# read-only archive directory, prepending a banner to each file.
#
# Non-destructive: uses `git mv` (history preserved) and only prepends text.
# Nothing is deleted. Reversible with `git mv` back or by stripping the banner.
#
# Run from the research-stack repository root.

set -euo pipefail

DEST="6-Documentation/docs/_superseded/2026-06"   # NOT 'archive/': repo gitignores **/archive/
CANON="GEOMETRIC_SUBSTANCE_CANONICAL.md"

BANNER="> **ARCHIVED — READ ONLY.** Superseded by \`${CANON}\` (2026-06).
> Retained for historical traceability. Do **not** use for current work — the
> vocabulary and conceptual frame in this file have been reconciled and replaced.

---
"

if [ ! -d .git ]; then
  echo "error: run this from the git repository root (no .git/ found here)." >&2
  exit 1
fi

mkdir -p "$DEST"

if git check-ignore -q "$DEST" 2>/dev/null; then
  echo "WARNING: '$DEST' is gitignored — archived files will NOT be tracked or committed." >&2
  echo "         Repo ignores **/archive/. Use a non-'archive' path to keep the archive in git." >&2
fi

archive() {
  local f="$1"
  if [ ! -f "$f" ]; then
    echo "skip (missing): $f"
    return 0
  fi
  local base dest tmp
  base="$(basename "$f")"
  dest="$DEST/$base"
  if [ -e "$dest" ]; then
    echo "skip (already archived): $dest"
    return 0
  fi
  git mv "$f" "$dest"
  tmp="$(mktemp)"
  { printf '%s\n' "$BANNER"; cat "$dest"; } > "$tmp"
  mv "$tmp" "$dest"
  git add "$dest"
  echo "archived: $f  ->  $dest"
}

# ─── CONFIRMED superseded (canonical owns their entire purpose) ───────────────
archive "6-Documentation/docs/VOCABULARY_LOCK.md"
archive "0-Core-Formalism/otom/docs/nuvmap/NUVMAP_NAMING_AND_DEFINITION.md"

# ─── REVIEW CANDIDATES — uncomment a line only after confirming it is superseded
# archive "0-Core-Formalism/otom/docs/wiki/NotationNomenclatureRegistry.md"
# archive "6-Documentation/docs/WEIRD_CONCEPTS_GLOSSARY.md"
# archive "6-Documentation/docs/GLOSSARY.md"
# archive "6-Documentation/wiki/Glossary.md"
# archive "obsidian-vault/00-MAP/Glossary.md"
# archive "0-Core-Formalism/otom/docs/nuvmap/NUVMAP_DESIGN_REFLECTIONS.md"
# archive "0-Core-Formalism/otom/docs/nuvmap/NUVMAP_ENCODING_DOS_AND_DONTS.md"

echo
echo "Done. Review with: git status"
echo "Then commit:       git commit -m 'Archive docs superseded by ${CANON}'"