"""documents.image_context: markdown anchor context for image docs
(phase 125, task 01)

Revision ID: 0023
Revises: 0022
Create Date: 2026-09-26

Phase 125 (image-anchor context — task 01, storage only):

* ``documents.image_context`` — TEXT NULLABLE: the surrounding text
  extracted from the markdown file that references the image
  (LOCKED A1) — the ``![alt text](image.png)`` alt text plus N
  paragraphs before and after the reference. This is what makes the
  image retrievable not just by what it shows but by WHY it exists in
  the documentation (the phase-125 objective).

The column is additive and NULL for every pre-phase row: standalone
images (no markdown reference), images referenced only from
non-markdown formats, and all pre-phase-125 rows simply read NULL —
no backfill (A4 keeps their behaviour byte-identical). One fully
reversible migration (A13): ``downgrade`` drops the column and leaves
0022's schema byte-identical.
"""
from __future__ import annotations

import sqlalchemy as sa

from alembic import op

revision = "0023"
down_revision = "0022"
branch_labels = None
depends_on = None


def upgrade() -> None:
    op.add_column("documents", sa.Column("image_context", sa.Text(), nullable=True))


def downgrade() -> None:
    # The column is the only 0023 artefact — dropping it leaves 0022's
    # schema byte-identical (A13, fully reversible).
    op.drop_column("documents", "image_context")