pyarchinit-mini 2.1.68__tar.gz → 2.4.1__tar.gz

{pyarchinit_mini-2.1.68 → pyarchinit_mini-2.4.1}/CHANGELOG.md

@@ -1,3 +1,200 @@
+## [2.4.1] - 2026-05-18
+
+### Fixed (IT)
+- Editor Harris Matrix: `window._currentSite` ora inizializzato server-side
+  dall'hidden input `#site-name`, quindi i pulsanti Save / + New Row /
+  Export yEd GraphML funzionano anche se `/api/load/<site>` fallisce (caso
+  tipico: migration `node_uuid` non ancora applicata sul DB di produzione).
+- Editor Harris Matrix: se `/api/load/<site>` ritorna errore, il corpo
+  della risposta viene mostrato in un alert con suggerimento di lanciare
+  `pyarchinit-mini-migrate-vocab --apply` (prima era silenzioso).
+- Editor Harris Matrix: messaggio "No site loaded" sostituito con
+  istruzione esplicita di tornare all'indice del Creator.
+
+### Added (IT)
+- Nuova pagina `/paradata/` (sezione Tools): picker sito + bottoni rapidi
+  ai 5 tipi di paradata (authors, licenses, embargoes, documents, epochs).
+  Link aggiunto sia al dropdown navbar che alla sidebar laterale.
+- Modal di aiuto nell'editor Harris (icona "?") che spiega la differenza
+  tra GraphML (s3dgraphy clean, auto-regen, per Datacenter/3D), Export
+  yEd GraphML (TableNode swimlane, on-demand, per yEd Desktop), DOT
+  (Graphviz), PNG (snapshot raster).
+- Tooltip migliorati su tutti i pulsanti di export.
+
+### Fixed (EN)
+- Harris Matrix Editor: `window._currentSite` is now initialised server-side
+  from hidden input `#site-name`, so Save / + New Row / Export buttons work
+  even when `/api/load/<site>` fails (typical when the `node_uuid` migration
+  is still pending on production).
+- Harris Matrix Editor: failed swimlane loads now surface the backend error
+  body in an alert with a hint to run `pyarchinit-mini-migrate-vocab`.
+
+### Added (EN)
+- New `/paradata/` landing page (Tools section): site picker + quick links
+  to the 5 paradata kinds. Sidebar entries added.
+- Help modal explaining the four export formats (GraphML, yEd GraphML,
+  DOT, PNG) accessible via a question-mark icon on the editor toolbar.
+
+## [2.4.0] - 2026-05-18
+
+### Added (IT)
+- Modulo `pyarchinit_mini/harris_swimlane/` (5 moduli: row_provider,
+  swimlane_state, period_sync_service, compound_layout, exceptions) per
+  l'editor swimlane di Harris Matrix.
+- `pyarchinit_mini/graphml_io/yed_writer.py` — nuovo emitter
+  yEd-flavored con `y:TableNode + y:Rows + y:ShapeNode`, separato
+  dall'export s3dgraphy clean di Spec 2.
+- 5 nuove route REST per il Harris Creator:
+  `GET/POST /api/swimlanes/<site>`, `GET /api/load/<site>`,
+  `POST /api/save/<site>`, `GET /api/export/<site>/yed-graphml`.
+- Editor `/harris-creator/editor` ora carica swimlane automaticamente
+  (row da `period_table` priorità → fallback distinct values), supporta
+  drag-drop tra row, creazione interattiva di nuove row, save esplicito
+  con auto-regen (Spec 2) post-commit.
+- Export yEd GraphML on-demand → `data/exports/harris_yed/<slug>-harris-yed.graphml`.
+
+### Added (EN)
+- New `pyarchinit_mini/harris_swimlane/` package — backend for Harris
+  Matrix swimlane editing.
+- New `pyarchinit_mini/graphml_io/yed_writer.py` — yEd-flavored GraphML
+  emitter (TableNode + Rows + ShapeNode), separate from Spec 2's
+  s3dgraphy delegate.
+- 5 new REST endpoints under `/harris-creator/api/`.
+- Editor loads swimlanes auto from `period_table` (fallback distinct);
+  drag-drop between rows; interactive row creation; explicit Save with
+  Spec 2 auto-regen. On-demand yEd export.
+
+### Changed
+- `harris_creator_routes.py` extended additively — existing routes
+  unchanged.
+- `editor.html` extended additively — Cytoscape compound nodes,
+  swimlane parents, new toolbar buttons.
+
+### Architecture note
+Two GraphML outputs now coexist:
+- `data/paradata/<slug>/stratigraphy.graphml` (Spec 2 auto-regen,
+  s3dgraphy clean, EM-canonical)
+- `data/exports/harris_yed/<slug>-harris-yed.graphml` (Spec 3-bis,
+  on-demand, yEd-flavored with TableNode)
+
+Legacy `pure_networkx_exporter` stays deprecated (was deprecated in
+Spec 2 PR8). NOT resurrected.
+
+### Dependencies
+- No new dependencies.
+
+### Spec / Plan
+- Spec: `docs/superpowers/specs/2026-05-18-harris-swimlane-template-design.md`
+- Plan: `docs/superpowers/plans/2026-05-18-harris-swimlane-template.md`
+- Spec 3-bis (auxiliary): independent of Spec 3 (SyncEngine + EM
+  Datacenter, on hold pending Datacenter readiness).
+
+## [2.3.0-alpha] - 2026-05-18
+
+### Added (IT)
+- Modulo `pyarchinit_mini/graphproj/` con `GraphProjector` (DB → s3dgraphy.Graph),
+  `ParadataStore` (storage per-sito su filesystem), `GraphIngestor` (preview/apply
+  bidirezionale con staleness check), `auto_regen` (hook post-commit), edge_registry,
+  filesystem helpers.
+- Modulo `pyarchinit_mini/graphml_io/` con writer/reader delegati a
+  `s3dgraphy.exporter.graphml.GraphMLExporter` / `s3dgraphy.importer.import_graphml.GraphMLImporter`.
+- Auto-regen di `data/paradata/<site_slug>/stratigraphy.graphml` su ogni save US/USM
+  (best-effort, errori isolati). Disabilitabile con `PYARCHINIT_DISABLE_AUTO_REGEN=1`
+  o col context manager `auto_regen.disable_regen()`.
+- 5 pagine HTML CRUD per paradata (authors, licenses, embargoes, documents, epochs)
+  con form Bootstrap.
+- REST API completa `/api/v1/paradata/<site>/{authors,licenses,embargoes,documents,epochs}`.
+- Route web `/sites/<site>/graph/{view,download,import-preview,import-apply}` con
+  preview 2-fasi obbligatorio per l'import GraphML + snapshot staleness check.
+
+### Changed
+- `pyarchinit_mini/graphml_converter/{graphml_builder, graphml_exporter,
+  pure_networkx_exporter, converter}.py` marcati deprecati (emettono
+  `DeprecationWarning` all'import). Verranno rimossi in Spec 3.
+- `harris_creator_routes.py` refactored: il branch `graphml` ora usa
+  `GraphProjector.populate_graph()` + `graphml_io.writer.write_graphml()`
+  invece di passare attraverso `HarrisMatrixGenerator.export_to_graphml()` /
+  `GraphMLBuilder`.
+- Edge canonical names allineati a s3dgraphy 0.1.42: `covers` → `overlies`,
+  `leans_against` → `abuts`. Fix del bug latente Spec 1 in
+  `vocab_{en,it}.json` e `s3d_converter._LEGACY_CODE_MAP`.
+
+### Architecture note (paradata storage)
+s3dgraphy 0.1.42's GraphML exporter does not round-trip standalone paradata
+nodes (AuthorNode, etc.) — they're only serialised when wrapped in
+ParadataNodeGroup. Spec 2 therefore adopted a **JSON sidecar pattern**:
+paradata entities live in `data/paradata/<site_slug>/paradata.json`
+(committed to git), while the auto-regenerated `stratigraphy.graphml` is
+purely the stratigraphic projection. Paradata are exposed via REST/UI but
+not embedded in the GraphML output.
+
+### Added (EN)
+- New `pyarchinit_mini/graphproj/` package: GraphProjector, ParadataStore,
+  GraphIngestor (2-phase preview/apply), auto_regen post-commit hook,
+  edge_registry, filesystem helpers.
+- New `pyarchinit_mini/graphml_io/` package delegating to s3dgraphy.
+- Auto-regen of stratigraphy.graphml on US/USM save, error-isolated.
+- 5 paradata CRUD HTML pages + REST API.
+- Graph routes: view, download, import-preview, import-apply with snapshot
+  staleness check (409 on stale).
+- Deprecation warnings on 4 legacy writers.
+
+### Dependencies
+- No new dependencies. Uses s3dgraphy 0.1.42 (bumped in 2.2.0-alpha).
+
+### Spec / Plan
+- Spec: `docs/superpowers/specs/2026-05-17-spec-2-local-graph-paradata-design.md`
+- Plan: `docs/superpowers/plans/2026-05-17-spec-2-local-graph-paradata.md`
+- Spec 2 of 4 for the s3dgraphy bidirectional bridge work.
+
+## [2.2.0-alpha] - 2026-05-17
+
+### Added (IT)
+- Modulo `pyarchinit_mini/vocab/` con `VocabProvider` singleton: legge i tre pillar JSON di s3dgraphy
+  (`s3Dgraphy_node_datamodel.json`, `s3Dgraphy_connections_datamodel.json`, `em_visual_rules.json`)
+  come fonte canonica per tipi di unità, tipi di relazione, e stili visivi.
+- Endpoint REST `/api/v1/vocab/{unit-types, edge-types, visual-style, diagnostics}` per popolare
+  select e form lato web.
+- CLI `pyarchinit-mini-migrate-vocab` per allineare il vocabolario legacy
+  (`USVA`/`USVB` → `USVs`, `USVC` → `USVn`) e fare il backfill della colonna `node_uuid` (UUID v7)
+  su `us_table`, `inventario_materiali_table`, `periodizzazione_table`.
+- Colonna `node_uuid` (prerequisito per il sync futuro col Datacenter EM).
+- Catalogo i18n custom (`pyarchinit_mini/vocab/translations/vocab_{en,it}.json`) con
+  `edge_type_aliases` per il parsing dei `rapporti` italiani.
+
+### Added (EN)
+- New `pyarchinit_mini/vocab/` package with `VocabProvider` singleton reading three s3dgraphy
+  JSON pillars as canonical source of unit types, edge types, and visual styles.
+- REST endpoints `/api/v1/vocab/{unit-types, edge-types, visual-style, diagnostics}` to populate
+  forms in the web UI.
+- CLI `pyarchinit-mini-migrate-vocab` to align legacy vocabulary (`USVA`/`USVB` → `USVs`,
+  `USVC` → `USVn`) and backfill `node_uuid` (UUID v7) across `us_table`,
+  `inventario_materiali_table`, `periodizzazione_table`.
+- `node_uuid` column (prerequisite for future EM Datacenter sync).
+- Custom i18n catalogue with `edge_type_aliases` for parsing Italian `rapporti` strings.
+
+### Changed
+- `graphml_converter/em_palette.py` reads visual styles from `VocabProvider` instead of the
+  hardcoded `PALETTE` dict (kept as deprecated shim emitting `DeprecationWarning` on access).
+- `s3d_integration/s3d_converter.py` parses `rapporti` text and categorizes node families via
+  `VocabProvider` (`italian_aliases`, `family`, `class_name`) instead of hardcoded if/elif chains.
+- Harris Matrix Creator now consumes `VocabProvider` visual styles end-to-end.
+
+### Migration required
+- After upgrading, run `pyarchinit-mini-migrate-vocab --dry-run` to preview, then
+  `--apply` to migrate (auto-backup under `data/backups/`).
+- See `docs/CLI_MIGRATE_VOCAB.md` for full reference.
+
+### Dependencies
+- `s3dgraphy>=0.1.42` (was 0.1.15).
+- New: `uuid7>=0.1.0` (importable as `uuid_extensions`).
+- Dev: `freezegun>=1.5.0`.
+
+### Spec / Plan
+- Spec: `docs/superpowers/specs/2026-05-16-s3dgraphy-web-foundation-design.md`
+- Plan: `docs/superpowers/plans/2026-05-16-s3dgraphy-web-foundation.md`
+- This is Spec 1 of 4 for porting the s3dgraphy bidirectional bridge from the QGIS plugin.
+
 ## [2.1.6] - 2026-02-25
 
 ### Fixed

{pyarchinit_mini-2.1.68/pyarchinit_mini.egg-info → pyarchinit_mini-2.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyarchinit-mini
-Version: 2.1.68
+Version: 2.4.1
 Summary: Lightweight archaeological data management system with REST API, Web UI, Desktop GUI, CLI, multi-user authentication, real-time collaboration, analytics dashboard, PyArchInit import/export, Heriverse/ATON export integration, and 3D CRUD viewer
 Home-page: https://github.com/enzococca/pyarchinit-mini
 Author: PyArchInit Team
@@ -42,7 +42,8 @@ Requires-Dist: networkx>=3.0.0
 Requires-Dist: reportlab>=4.0.0
 Requires-Dist: pillow>=10.0.0
 Requires-Dist: qrcode[pil]>=7.4.0
-Requires-Dist: s3dgraphy>=0.1.13
+Requires-Dist: s3dgraphy>=0.1.42
+Requires-Dist: uuid7>=0.1.0
 Requires-Dist: click>=8.1.0
 Requires-Dist: rich>=13.0.0
 Requires-Dist: inquirer>=3.0.0
@@ -91,6 +92,7 @@ Requires-Dist: black>=23.0.0; extra == "dev"
 Requires-Dist: flake8>=6.0.0; extra == "dev"
 Requires-Dist: isort>=5.12.0; extra == "dev"
 Requires-Dist: mypy>=1.0.0; extra == "dev"
+Requires-Dist: freezegun>=1.5.0; extra == "dev"
 Provides-Extra: docs
 Requires-Dist: sphinx>=6.0.0; extra == "docs"
 Requires-Dist: sphinx-rtd-theme>=1.2.0; extra == "docs"
@@ -2366,3 +2368,94 @@ This project is licensed under the GNU General Public License v2.0 - see the [LI
 
 
 **Made with ❤️ for the Archaeological Community**
+
+## s3dgraphy integration
+
+Since 2.2.0-alpha, pyarchinit-mini-web reads the canonical Extended Matrix
+vocabulary (unit types, edge types, visual styles) from the
+[s3dgraphy](https://github.com/zalmoxes-laran/s3dgraphy) package's JSON
+catalogues. Unit types like `US`, `USVs`, `USVn`, `RSF`, `USM` come from
+`s3Dgraphy_node_datamodel.json` (v1.5.4 at time of writing).
+
+Bumping s3dgraphy (`pip install --upgrade s3dgraphy`) makes new EM types
+immediately available in form selects without any pyarchinit-mini code change.
+
+After upgrading, run the data alignment to update legacy records:
+
+```bash
+pyarchinit-mini-migrate-vocab --dry-run    # preview changes
+pyarchinit-mini-migrate-vocab --apply      # backup + migrate
+```
+
+See `docs/CLI_MIGRATE_VOCAB.md` for the full CLI reference.
+
+The vocab is exposed to the browser via:
+
+- `GET /api/v1/vocab/unit-types?lang=it`
+- `GET /api/v1/vocab/unit-types/<abbr>`
+- `GET /api/v1/vocab/edge-types?lang=it`
+- `GET /api/v1/vocab/visual-style/<unit_type>`
+- `GET /api/v1/vocab/diagnostics` (admin-only)
+
+## Graph projection & paradata
+
+Since 2.3.0-alpha, pyarchinit-mini-web auto-generates the stratigraphic graph
+as a GraphML file every time you save a US/USM record. Output lives at
+`data/paradata/<site_slug>/stratigraphy.graphml`.
+
+Paradata (authors, licenses, embargoes, documents, epochs) are stored in a
+JSON sidecar:
+```
+data/paradata/<site_slug>/paradata.json
+```
+because s3dgraphy 0.1.42's GraphML exporter does not round-trip standalone
+paradata nodes. The JSON sidecar IS committed to git.
+
+### Paradata editing
+
+Visit `/paradata/<site>/{authors,licenses,embargoes,documents,epochs}` to
+manage paradata. REST endpoints under `/api/v1/paradata/<site>/...` mirror
+the UI. See `docs/PARADATA_GUIDE.md`.
+
+### Graph import
+
+`/sites/<site>/graph/import-preview` accepts a GraphML upload; you see a
+preview of planned INSERT/UPDATE/SKIP and must confirm via
+`/sites/<site>/graph/import-apply` before any DB write.
+
+### Auto-regen control
+
+- Disable globally: `export PYARCHINIT_DISABLE_AUTO_REGEN=1`
+- Disable during bulk ops: `with graphproj.auto_regen.disable_regen():`
+
+See `docs/GRAPH_AUTO_REGEN.md`.
+
+## Harris Swimlane Editor
+
+Since 2.4.0, the Harris Matrix Creator at `/harris-creator/editor`
+displays stratigraphic graphs with **yEd-like swimlanes** — horizontal
+rows representing periods+phases. Existing US records are auto-placed
+in their row based on `periodo_iniziale + fase_iniziale`. Users can
+drag US records between rows, create new rows interactively, and save
+back to the DB.
+
+Row source priority:
+1. `period_table` (formal definitions)
+2. Fallback: distinct `(periodo_iniziale, fase_iniziale)` from
+   `periodizzazione_table` + `us_table`
+
+### Two GraphML outputs
+
+- `data/paradata/<site>/stratigraphy.graphml` (Spec 2, auto-regen):
+  s3dgraphy clean, EM-canonical, for the EM Datacenter
+- `data/exports/harris_yed/<site>-harris-yed.graphml` (Spec 3-bis,
+  on-demand): yEd-flavored with `y:TableNode`, for users editing in
+  yEd Desktop
+
+### Auto-regen integration
+
+Save endpoint also triggers Spec 2's auto_regen for
+`stratigraphy.graphml`, keeping the canonical output consistent with
+DB state.
+
+See `docs/HARRIS_SWIMLANE.md` and `docs/YED_INTEGRATION.md`.

{pyarchinit_mini-2.1.68 → pyarchinit_mini-2.4.1}/README.md

@@ -2264,4 +2264,95 @@ This project is licensed under the GNU General Public License v2.0 - see the [LI
 ---
 
 
-**Made with ❤️ for the Archaeological Community**
+**Made with ❤️ for the Archaeological Community**
+
+## s3dgraphy integration
+
+Since 2.2.0-alpha, pyarchinit-mini-web reads the canonical Extended Matrix
+vocabulary (unit types, edge types, visual styles) from the
+[s3dgraphy](https://github.com/zalmoxes-laran/s3dgraphy) package's JSON
+catalogues. Unit types like `US`, `USVs`, `USVn`, `RSF`, `USM` come from
+`s3Dgraphy_node_datamodel.json` (v1.5.4 at time of writing).
+
+Bumping s3dgraphy (`pip install --upgrade s3dgraphy`) makes new EM types
+immediately available in form selects without any pyarchinit-mini code change.
+
+After upgrading, run the data alignment to update legacy records:
+
+```bash
+pyarchinit-mini-migrate-vocab --dry-run    # preview changes
+pyarchinit-mini-migrate-vocab --apply      # backup + migrate
+```
+
+See `docs/CLI_MIGRATE_VOCAB.md` for the full CLI reference.
+
+The vocab is exposed to the browser via:
+
+- `GET /api/v1/vocab/unit-types?lang=it`
+- `GET /api/v1/vocab/unit-types/<abbr>`
+- `GET /api/v1/vocab/edge-types?lang=it`
+- `GET /api/v1/vocab/visual-style/<unit_type>`
+- `GET /api/v1/vocab/diagnostics` (admin-only)
+
+## Graph projection & paradata
+
+Since 2.3.0-alpha, pyarchinit-mini-web auto-generates the stratigraphic graph
+as a GraphML file every time you save a US/USM record. Output lives at
+`data/paradata/<site_slug>/stratigraphy.graphml`.
+
+Paradata (authors, licenses, embargoes, documents, epochs) are stored in a
+JSON sidecar:
+```
+data/paradata/<site_slug>/paradata.json
+```
+because s3dgraphy 0.1.42's GraphML exporter does not round-trip standalone
+paradata nodes. The JSON sidecar IS committed to git.
+
+### Paradata editing
+
+Visit `/paradata/<site>/{authors,licenses,embargoes,documents,epochs}` to
+manage paradata. REST endpoints under `/api/v1/paradata/<site>/...` mirror
+the UI. See `docs/PARADATA_GUIDE.md`.
+
+### Graph import
+
+`/sites/<site>/graph/import-preview` accepts a GraphML upload; you see a
+preview of planned INSERT/UPDATE/SKIP and must confirm via
+`/sites/<site>/graph/import-apply` before any DB write.
+
+### Auto-regen control
+
+- Disable globally: `export PYARCHINIT_DISABLE_AUTO_REGEN=1`
+- Disable during bulk ops: `with graphproj.auto_regen.disable_regen():`
+
+See `docs/GRAPH_AUTO_REGEN.md`.
+
+## Harris Swimlane Editor
+
+Since 2.4.0, the Harris Matrix Creator at `/harris-creator/editor`
+displays stratigraphic graphs with **yEd-like swimlanes** — horizontal
+rows representing periods+phases. Existing US records are auto-placed
+in their row based on `periodo_iniziale + fase_iniziale`. Users can
+drag US records between rows, create new rows interactively, and save
+back to the DB.
+
+Row source priority:
+1. `period_table` (formal definitions)
+2. Fallback: distinct `(periodo_iniziale, fase_iniziale)` from
+   `periodizzazione_table` + `us_table`
+
+### Two GraphML outputs
+
+- `data/paradata/<site>/stratigraphy.graphml` (Spec 2, auto-regen):
+  s3dgraphy clean, EM-canonical, for the EM Datacenter
+- `data/exports/harris_yed/<site>-harris-yed.graphml` (Spec 3-bis,
+  on-demand): yEd-flavored with `y:TableNode`, for users editing in
+  yEd Desktop
+
+### Auto-regen integration
+
+Save endpoint also triggers Spec 2's auto_regen for
+`stratigraphy.graphml`, keeping the canonical output consistent with
+DB state.
+
+See `docs/HARRIS_SWIMLANE.md` and `docs/YED_INTEGRATION.md`.

{pyarchinit_mini-2.1.68 → pyarchinit_mini-2.4.1}/pyarchinit_mini/__init__.py

@@ -23,7 +23,7 @@ Features:
 - Scalable and modular architecture
 """
 
-__version__ = "2.1.68"
+__version__ = "2.4.1"
 __author__ = "PyArchInit Team"
 __email__ = "enzo.ccc@gmail.com"
 

pyarchinit_mini-2.4.1/pyarchinit_mini/cli/migrate_vocab.py

@@ -0,0 +1,164 @@
+"""CLI: pyarchinit-mini-migrate-vocab
+
+Wraps the 3 Spec 1 Foundation migrations (node_uuid schema → backfill →
+vocab alignment USVA/USVB→USVs USVC→USVn) and the backup module.
+
+Discovery order for target DBs:
+  1. --database <url>  (CLI flag, wins outright)
+  2. $DATABASE_URL     (default app DB)
+  3. data/connections.json  (saved web connections; skip with --only-default)
+
+Usage examples:
+  pyarchinit-mini-migrate-vocab --dry-run
+  pyarchinit-mini-migrate-vocab --apply --yes
+  pyarchinit-mini-migrate-vocab --rollback --yes
+  pyarchinit-mini-migrate-vocab --list-backups
+  pyarchinit-mini-migrate-vocab --apply --script vocab_alignment --database sqlite:///x.db --yes
+"""
+from __future__ import annotations
+
+import argparse
+import importlib
+import json
+import os
+import sys
+from pathlib import Path
+
+# Use importlib to avoid name collisions with the legacy DatabaseMigrations
+# class exported from pyarchinit_mini.database.migrations.__init__.
+_pkg = "pyarchinit_mini.database.migrations"
+schema_m = importlib.import_module(f"{_pkg}._2026_05_node_uuid_schema")
+backfill_m = importlib.import_module(f"{_pkg}._2026_05_node_uuid_backfill")
+align_m = importlib.import_module(f"{_pkg}._2026_05_vocab_alignment")
+
+from pyarchinit_mini.database.migrations.backup import backup_database  # noqa: E402
+
+
+SCRIPTS = {
+    "node_uuid_schema": schema_m,
+    "node_uuid_backfill": backfill_m,
+    "vocab_alignment": align_m,
+}
+ORDER = ["node_uuid_schema", "node_uuid_backfill", "vocab_alignment"]
+
+
+def _discover_dbs(args) -> list[str]:
+    if args.database:
+        return [args.database]
+    dbs: list[str] = []
+    env = os.environ.get("DATABASE_URL")
+    if env:
+        dbs.append(env)
+    if not args.only_default:
+        conns = Path("data/connections.json")
+        if conns.exists():
+            try:
+                data = json.loads(conns.read_text(encoding="utf-8"))
+                for entry in data.get("connections", []):
+                    url = entry.get("url")
+                    if url and url not in dbs:
+                        dbs.append(url)
+            except json.JSONDecodeError:
+                print(f"warning: could not parse {conns}", file=sys.stderr)
+    return dbs
+
+
+def _confirm(prompt: str, yes: bool) -> bool:
+    if yes:
+        return True
+    try:
+        ans = input(f"{prompt} [y/N] ").strip().lower()
+    except EOFError:
+        return False
+    return ans == "y"
+
+
+def _list_backups(backups_dir: Path) -> int:
+    idx = backups_dir / "_index.json"
+    if not idx.exists():
+        print("No backups found.")
+        return 0
+    for r in json.loads(idx.read_text(encoding="utf-8")):
+        print(f"{r['timestamp']}  {r['backup_path']}  ({r['size_bytes']} bytes)")
+    return 0
+
+
+def main(argv=None) -> int:
+    p = argparse.ArgumentParser(
+        prog="pyarchinit-mini-migrate-vocab",
+        description="Foundation migrations: node_uuid schema + backfill + vocab alignment.",
+    )
+    mode = p.add_mutually_exclusive_group(required=True)
+    mode.add_argument("--dry-run", action="store_true", help="Report changes without mutating")
+    mode.add_argument("--apply", action="store_true", help="Backup then apply migrations")
+    mode.add_argument("--rollback", action="store_true", help="(Manual) restore from backup")
+    mode.add_argument("--list-backups", action="store_true", help="List recorded backups")
+    p.add_argument("--database", type=str, help="Target a specific DB URL")
+    p.add_argument("--script", type=str, choices=list(SCRIPTS.keys()),
+                   help="Run a single script (advanced)")
+    p.add_argument("--only-default", action="store_true",
+                   help="Skip data/connections.json discovery")
+    p.add_argument("--backups-dir", type=Path, default=Path("data/backups"))
+    p.add_argument("--yes", action="store_true", help="Skip confirmation prompts")
+    args = p.parse_args(argv)
+
+    if args.list_backups:
+        return _list_backups(args.backups_dir)
+
+    if args.rollback:
+        # TODO(Spec-2): implement actual rollback (read _index.json → restore latest backup
+        # SQLite via cp / PG via pg_restore). Currently prints manual instructions only.
+        print("Rollback requires manual restore. Use --list-backups to see what's available,")
+        print("then copy/restore the backup file manually (SQLite) or pg_restore (PostgreSQL).")
+        return 0
+
+    dbs = _discover_dbs(args)
+    if not dbs:
+        print("No databases discovered. Use --database <url> or set DATABASE_URL.",
+              file=sys.stderr)
+        return 2
+
+    scripts_to_run = (
+        [SCRIPTS[args.script]] if args.script
+        else [SCRIPTS[k] for k in ORDER]
+    )
+
+    # TODO(Spec-2): acquire data/.migration_lock (PID + timestamp) to reject concurrent
+    # --apply invocations per Spec §6.3
+    overall_status = 0
+    for db in dbs:
+        print(f"== DB: {db} ==")
+        if args.apply:
+            if not _confirm(f"Backup and migrate {db}?", args.yes):
+                print("  skipped (no confirmation)")
+                continue
+            try:
+                rec = backup_database(db, backups_dir=args.backups_dir)
+                print(f"  backup: {rec.backup_path}")
+            except Exception as e:
+                print(f"  backup failed: {e}", file=sys.stderr)
+                overall_status = 1
+                continue
+        for script in scripts_to_run:
+            try:
+                report = script.run(db, dry_run=args.dry_run)
+                print(f"  {report.script}: status={report.status}")
+                if hasattr(report, "tables_changed") and report.tables_changed:
+                    print(f"    tables_changed: {report.tables_changed}")
+                if hasattr(report, "tables_skipped") and report.tables_skipped:
+                    print(f"    tables_skipped: {report.tables_skipped}")
+                if hasattr(report, "rows_updated"):
+                    print(f"    rows_updated: {report.rows_updated}")
+                if hasattr(report, "mappings"):
+                    print(f"    mappings: {report.mappings}")
+            except Exception as e:
+                print(f"  {script.__name__} FAILED: {e}", file=sys.stderr)
+                overall_status = 1
+
+    # TODO(Spec-2): append per-script JSON-line entry to data/migration.log per Spec §6.4
+    # (ts, script, db, rows_updated/mappings/tables_*, duration_ms, status)
+    return overall_status
+
+
+if __name__ == "__main__":
+    sys.exit(main())