ltcai 4.3.1 → 4.4.0

package/latticeai/services/kg_portability.py

@@ -1,431 +1,11 @@
-"""Knowledge Graph portability — local export / import / backup / restore.
+"""Compatibility shim: physically moved to ``lattice_brain.portability``.
 
-The Knowledge Graph is the user's durable asset, so it must be portable without
-any cloud service. Two complementary mechanisms, both fully local:
-
-* **Logical export/import** (JSON): nodes/edges/chunks/sources/provenance with a
-  versioned header (schema + projection + embed-dim). Re-embeds on import, so it
-  is portable across machines.
-* **Binary backup/restore** (ZIP): a faithful snapshot of the SQLite DB (incl.
-  vector embeddings) plus the blob directory, integrity-checked, for
-  same-machine recovery.
+Aliases itself to the physical module so identity, module-level state, and
+monkeypatching keep working through the old import path.
 """
 
-from __future__ import annotations
-
-import hashlib
-import json
-import shutil
-import tempfile
-import zipfile
-from datetime import datetime, timezone
-from pathlib import Path, PurePosixPath
-from typing import Any, Dict, Optional
-
-from lattice_brain.archive import BrainArchivePaths, EncryptedBrainArchive
-from lattice_brain.storage import (
-    DockerPostgresWizard,
-    PostgresEngine,
-    SQLiteToPostgresMigrator,
-)
-
-FORMAT = "latticeai.kg.export"
-FORMAT_VERSION = 1
-BACKUP_FORMAT = "latticeai.kg.backup"
-
-
-def _now_iso() -> str:
-    return datetime.now(timezone.utc).isoformat()
-
-
-def _stamp() -> str:
-    return _now_iso().replace(":", "").replace("-", "").replace(".", "")[:15]
-
-
-def _sha256_file(path: Path) -> str:
-    h = hashlib.sha256()
-    with open(path, "rb") as fh:
-        for block in iter(lambda: fh.read(65536), b""):
-            h.update(block)
-    return h.hexdigest()
-
-
-def _safe_zip_names(names) -> None:
-    for name in names:
-        path = PurePosixPath(name)
-        if path.is_absolute() or ".." in path.parts:
-            raise ValueError(f"Backup archive contains unsafe path: {name}")
-
-
-class KGPortabilityService:
-    def __init__(self, *, knowledge_graph: Any, data_dir, enable_graph: bool = True, device_identity: Any = None) -> None:
-        self._kg = knowledge_graph
-        self._data_dir = Path(data_dir)
-        self._enable = bool(enable_graph)
-        self._exports_dir = self._data_dir / "workspace_exports"
-        # v4 sovereignty: when a DeviceIdentity is wired, exports are signed
-        # and imports record origin provenance. Pre-v4 unsigned bundles stay
-        # importable locally (origin='unsigned-legacy') — signatures are
-        # mandatory only on the Brain Network peer path.
-        self._identity = device_identity
-
-    def available(self) -> bool:
-        return self._enable and self._kg is not None
-
-    def _require(self) -> None:
-        if not self.available():
-            raise RuntimeError("Knowledge Graph is disabled (LATTICEAI_ENABLE_GRAPH).")
-
-    # ── logical export / import ──────────────────────────────────────────────
-    def export(self, *, workspace_id: Optional[str] = None) -> Dict[str, Any]:
-        self._require()
-        data = self._kg.export_graph_data(workspace_id=workspace_id)
-        header = {
-            "format": FORMAT,
-            "format_version": FORMAT_VERSION,
-            **self._kg.schema_versions(),
-            "exported_at": _now_iso(),
-            "workspace_id": workspace_id,
-            "counts": data.get("counts"),
-        }
-        artifact = {"header": header, **data}
-        if self._identity is not None:
-            artifact["signature"] = self._identity.sign_manifest(header)
-        return artifact
-
-    def export_to_file(self, path=None, *, workspace_id: Optional[str] = None) -> Dict[str, Any]:
-        artifact = self.export(workspace_id=workspace_id)
-        self._exports_dir.mkdir(parents=True, exist_ok=True)
-        path = Path(path) if path else self._exports_dir / f"kg-export-{_stamp()}.json"
-        path.write_text(json.dumps(artifact, ensure_ascii=False, indent=2), encoding="utf-8")
-        return {"path": str(path), "header": artifact["header"], "bytes": path.stat().st_size}
-
-    def import_data(self, artifact: Dict[str, Any], *, mode: str = "merge", dry_run: bool = False) -> Dict[str, Any]:
-        self._require()
-        if not isinstance(artifact, dict) or "nodes" not in artifact:
-            raise ValueError("Invalid Knowledge Graph export artifact.")
-        if mode not in ("merge", "replace"):
-            raise ValueError("mode must be 'merge' or 'replace'.")
-        origin = "unsigned-legacy"
-        signature = artifact.get("signature")
-        if signature:
-            from lattice_brain.identity import verify_manifest
-
-            if not verify_manifest(artifact.get("header") or {}, signature):
-                raise ValueError("Bundle signature verification failed — refusing to import.")
-            origin = f"device:{signature.get('fingerprint') or 'unknown'}"
-        result = self._kg.import_graph_data(artifact, mode=mode, dry_run=dry_run)
-        result["header"] = artifact.get("header")
-        result["origin"] = origin
-        result["signed"] = bool(signature)
-        if not dry_run:
-            try:
-                self._kg.record_provenance(
-                    node_id="import:" + str((artifact.get("header") or {}).get("exported_at") or _now_iso()),
-                    source_type="bundle_import",
-                    pipeline="kg-portability",
-                    owner=None,
-                    metadata={"origin": origin, "mode": mode,
-                              "counts": (artifact.get("header") or {}).get("counts")},
-                )
-            except Exception:
-                pass
-        return result
-
-    def import_from_file(self, path, *, mode: str = "merge", dry_run: bool = False) -> Dict[str, Any]:
-        artifact = json.loads(Path(path).read_text(encoding="utf-8"))
-        return self.import_data(artifact, mode=mode, dry_run=dry_run)
-
-    # ── binary backup / restore ──────────────────────────────────────────────
-    def backup(self, dest_path=None) -> Dict[str, Any]:
-        self._require()
-        self._exports_dir.mkdir(parents=True, exist_ok=True)
-        dest = Path(dest_path) if dest_path else self._exports_dir / f"kg-backup-{_stamp()}.zip"
-        with tempfile.TemporaryDirectory() as tmp_s:
-            tmp = Path(tmp_s)
-            db_copy = tmp / "knowledge_graph.sqlite"
-            self._kg.backup_database(db_copy)
-            manifest = {
-                "format": BACKUP_FORMAT,
-                "format_version": FORMAT_VERSION,
-                **self._kg.schema_versions(),
-                "created_at": _now_iso(),
-                "db_sha256": _sha256_file(db_copy),
-                "has_blobs": Path(self._kg.blob_dir).exists(),
-            }
-            with zipfile.ZipFile(dest, "w", zipfile.ZIP_DEFLATED) as zf:
-                zf.write(db_copy, "knowledge_graph.sqlite")
-                zf.writestr("manifest.json", json.dumps(manifest, ensure_ascii=False, indent=2))
-                blob_dir = Path(self._kg.blob_dir)
-                if blob_dir.exists():
-                    for f in blob_dir.rglob("*"):
-                        if f.is_file():
-                            zf.write(f, f"blobs/{f.relative_to(blob_dir)}")
-        return {"path": str(dest), "bytes": dest.stat().st_size, "manifest": manifest}
-
-    def restore(
-        self,
-        archive_path,
-        *,
-        verify: bool = True,
-        dry_run: bool = False,
-        confirm: bool = False,
-    ) -> Dict[str, Any]:
-        self._require()
-        archive = Path(archive_path)
-        if not archive.exists():
-            raise FileNotFoundError(f"Backup archive not found: {archive}")
-        if not dry_run and not confirm:
-            raise ValueError("Explicit confirmation is required before restoring a Knowledge Graph backup.")
-        with zipfile.ZipFile(archive) as zf:
-            names = zf.namelist()
-            _safe_zip_names(names)
-            if "knowledge_graph.sqlite" not in names:
-                raise ValueError("Archive is missing knowledge_graph.sqlite.")
-            manifest = json.loads(zf.read("manifest.json")) if "manifest.json" in names else {}
-            with tempfile.TemporaryDirectory() as tmp_s:
-                tmp = Path(tmp_s)
-                zf.extractall(tmp)
-                db_src = tmp / "knowledge_graph.sqlite"
-                if verify and manifest.get("db_sha256"):
-                    if _sha256_file(db_src) != manifest["db_sha256"]:
-                        raise ValueError("Backup integrity check failed (db sha256 mismatch).")
-                if dry_run:
-                    return {
-                        "restored": False,
-                        "dry_run": True,
-                        "verified": True,
-                        "manifest": manifest,
-                        "planned": {
-                            "database": str(self._kg.db_path),
-                            "blobs": str(self._kg.blob_dir),
-                            "archive": str(archive),
-                        },
-                    }
-                db_dest = Path(self._kg.db_path)
-                blob_dest = Path(self._kg.blob_dir)
-                db_dest.parent.mkdir(parents=True, exist_ok=True)
-                # Drop the live DB + stale WAL/SHM siblings so the restored copy
-                # is authoritative (no stale journal overlaying old pages).
-                for sib in (db_dest, Path(str(db_dest) + "-wal"), Path(str(db_dest) + "-shm")):
-                    if sib.exists():
-                        sib.unlink()
-                shutil.copyfile(db_src, db_dest)
-                blob_src = tmp / "blobs"
-                if blob_src.exists():
-                    if blob_dest.exists():
-                        shutil.rmtree(blob_dest)
-                    shutil.copytree(blob_src, blob_dest)
-                else:
-                    blob_dest.mkdir(parents=True, exist_ok=True)
-        stats = self._kg.stats()
-        return {
-            "restored": True,
-            "manifest": manifest,
-            "nodes": sum(stats.get("nodes", {}).values()),
-        }
-
-    def verify_backup(self, archive_path) -> Dict[str, Any]:
-        archive = Path(archive_path)
-        if not archive.exists():
-            return {"ok": False, "path": str(archive), "errors": [f"Backup archive not found: {archive}"]}
-        try:
-            with zipfile.ZipFile(archive) as zf:
-                names = zf.namelist()
-                _safe_zip_names(names)
-                if "knowledge_graph.sqlite" not in names:
-                    raise ValueError("Archive is missing knowledge_graph.sqlite.")
-                manifest = json.loads(zf.read("manifest.json")) if "manifest.json" in names else {}
-                with tempfile.TemporaryDirectory() as tmp_s:
-                    tmp = Path(tmp_s)
-                    zf.extract("knowledge_graph.sqlite", tmp)
-                    db_src = tmp / "knowledge_graph.sqlite"
-                    if manifest.get("db_sha256") and _sha256_file(db_src) != manifest["db_sha256"]:
-                        raise ValueError("Backup integrity check failed (db sha256 mismatch).")
-            return {"ok": True, "path": str(archive), "manifest": manifest, "errors": []}
-        except (ValueError, zipfile.BadZipFile, OSError, json.JSONDecodeError) as exc:
-            return {"ok": False, "path": str(archive), "errors": [str(exc)]}
-
-    # ── encrypted .latticebrain archive ───────────────────────────────────
-    def encrypted_archive(self, dest_path=None, *, passphrase: str) -> Dict[str, Any]:
-        self._require()
-        self._exports_dir.mkdir(parents=True, exist_ok=True)
-        dest = Path(dest_path) if dest_path else self._exports_dir / f"brain-{_stamp()}.latticebrain"
-        metadata = {
-            "storage": self.storage_status().get("active", {}),
-            "snapshot": self.snapshot_metadata(),
-            "device_identity": self._identity.describe() if self._identity is not None else {},
-            "provenance": {"exported_at": _now_iso(), "source": "kg-portability"},
-        }
-        archive = EncryptedBrainArchive(
-            BrainArchivePaths(
-                db_path=Path(self._kg.db_path),
-                blob_dir=Path(self._kg.blob_dir),
-                data_dir=self._data_dir,
-                metadata=metadata,
-            )
-        )
-        return archive.create(dest, passphrase=passphrase)
-
-    def inspect_encrypted_archive(self, archive_path, *, passphrase: Optional[str] = None) -> Dict[str, Any]:
-        archive = EncryptedBrainArchive(
-            BrainArchivePaths(
-                db_path=Path(self._kg.db_path),
-                blob_dir=Path(self._kg.blob_dir),
-                data_dir=self._data_dir,
-            )
-        )
-        return archive.inspect(Path(archive_path), passphrase=passphrase)
-
-    def verify_encrypted_archive(self, archive_path, *, passphrase: str) -> Dict[str, Any]:
-        archive = EncryptedBrainArchive(
-            BrainArchivePaths(
-                db_path=Path(self._kg.db_path),
-                blob_dir=Path(self._kg.blob_dir),
-                data_dir=self._data_dir,
-            )
-        )
-        return archive.verify(Path(archive_path), passphrase=passphrase)
-
-    def restore_encrypted_archive(
-        self,
-        archive_path,
-        *,
-        passphrase: str,
-        dry_run: bool = False,
-        confirm: bool = False,
-    ) -> Dict[str, Any]:
-        self._require()
-        archive = EncryptedBrainArchive(
-            BrainArchivePaths(
-                db_path=Path(self._kg.db_path),
-                blob_dir=Path(self._kg.blob_dir),
-                data_dir=self._data_dir,
-            )
-        )
-        return archive.restore(
-            Path(archive_path),
-            passphrase=passphrase,
-            target=BrainArchivePaths(
-                db_path=Path(self._kg.db_path),
-                blob_dir=Path(self._kg.blob_dir),
-                data_dir=self._data_dir,
-            ),
-            dry_run=dry_run,
-            confirm=confirm,
-        )
-
-    def import_encrypted_archive(
-        self,
-        archive_path,
-        *,
-        passphrase: str,
-        dry_run: bool = False,
-        confirm: bool = False,
-    ) -> Dict[str, Any]:
-        result = self.restore_encrypted_archive(
-            archive_path,
-            passphrase=passphrase,
-            dry_run=dry_run,
-            confirm=confirm,
-        )
-        result["operation"] = "import"
-        return result
-
-    # ── status surface ───────────────────────────────────────────────────────
-    def snapshot_metadata(self) -> Dict[str, Any]:
-        if not self.available():
-            return {"available": False}
-        return {
-            "available": True,
-            **self._kg.schema_versions(),
-            "stats": self._kg.stats(),
-            "provenance": self._kg.provenance_stats(),
-            "storage": (
-                self._kg.storage_engine.capabilities().as_dict()
-                if getattr(self._kg, "storage_engine", None) is not None
-                else {"engine": "sqlite", "available": True}
-            ),
-        }
-
-    def storage_status(self) -> Dict[str, Any]:
-        if not self.available():
-            return {"available": False}
-        return {
-            "available": True,
-            "active": (
-                self._kg.storage_engine.capabilities().as_dict()
-                if getattr(self._kg, "storage_engine", None) is not None
-                else {"engine": "sqlite", "available": True}
-            ),
-            "postgres": PostgresEngine("", schema="lattice_brain").capabilities().as_dict(),
-            "backup_health": self.backup_health(),
-        }
-
-    def backup_health(self) -> Dict[str, Any]:
-        self._exports_dir.mkdir(parents=True, exist_ok=True)
-        backups = sorted(
-            [
-                p for p in self._exports_dir.glob("*")
-                if p.is_file() and (p.suffix == ".zip" or p.suffix == ".latticebrain")
-            ],
-            key=lambda p: p.stat().st_mtime,
-            reverse=True,
-        )
-        latest = backups[0] if backups else None
-        return {
-            "available": True,
-            "directory": str(self._exports_dir),
-            "count": len(backups),
-            "latest": str(latest) if latest else None,
-            "latest_bytes": latest.stat().st_size if latest else 0,
-            "encrypted_archives": sum(1 for p in backups if p.suffix == ".latticebrain"),
-            "zip_backups": sum(1 for p in backups if p.suffix == ".zip"),
-        }
-
-    def postgres_docker_setup(
-        self,
-        *,
-        consent: bool,
-        dry_run: bool = False,
-        port: int = 5432,
-    ) -> Dict[str, Any]:
-        wizard = DockerPostgresWizard(self._data_dir / "postgres", port=port)
-        return wizard.start(consent=consent, dry_run=dry_run)
+import sys
 
-    def migrate_sqlite_to_postgres(
-        self,
-        *,
-        dsn: str,
-        schema: str = "lattice_brain",
-        dry_run: bool = True,
-    ) -> Dict[str, Any]:
-        self._require()
-        if not dsn:
-            raise ValueError("Postgres DSN is required for SQLite to Postgres migration.")
-        migrator = SQLiteToPostgresMigrator(
-            Path(self._kg.db_path),
-            PostgresEngine(dsn, schema=schema),
-        )
-        if dry_run:
-            return migrator.migrate(dry_run=True)
-        backup = self.backup()
-        verification = self.verify_backup(backup["path"])
-        if not verification.get("ok"):
-            raise RuntimeError(
-                "Pre-migration backup verification failed; Postgres migration was not started: "
-                + "; ".join(verification.get("errors") or [])
-            )
-        result = migrator.migrate(dry_run=False)
-        result["pre_migration_backup"] = {
-            "path": backup["path"],
-            "verified": True,
-            "manifest": backup.get("manifest"),
-        }
-        return result
+import lattice_brain.portability as _impl
 
-    def recent_ingestions(self, *, limit: int = 50, source_type: Optional[str] = None) -> Dict[str, Any]:
-        """Recent provenance records (newest first) for the ingestion-sources UI."""
-        if not self.available():
-            return {"items": [], "count": 0}
-        return self._kg.list_provenance(limit=limit, source_type=source_type)
+sys.modules[__name__] = _impl

package/latticeai/services/platform_runtime.py

@@ -17,9 +17,9 @@ from typing import Any, Callable, Dict, Optional, Set
 
 from fastapi import HTTPException, Request
 
-from latticeai.core.hooks import dispatch_tool
-from latticeai.core.multi_agent import MultiAgentOrchestrator, default_role_runner, llm_role_runner
-from latticeai.core.workflow_engine import ApprovalRequired, WorkflowEngine
+from lattice_brain.runtime.hooks import dispatch_tool
+from lattice_brain.runtime.multi_agent import MultiAgentOrchestrator, default_role_runner, llm_role_runner
+from lattice_brain.workflow import ApprovalRequired, WorkflowEngine
 from tools import execute_tool
 
 

package/latticeai/services/run_executor.py

@@ -13,7 +13,7 @@ from dataclasses import dataclass
 from datetime import datetime
 from typing import Any, Callable, Dict, Optional
 
-from latticeai.core.workflow_engine import WorkflowEngine
+from lattice_brain.workflow import WorkflowEngine
 
 
 ACTIVE_STATUSES = {"queued", "running", "in_progress", "retrying", "cancelling"}

package/latticeai/services/upload_service.py

@@ -9,7 +9,7 @@ from pathlib import Path
 
 from fastapi import HTTPException, Request, UploadFile
 
-from latticeai.services.ingestion import IngestionItem
+from lattice_brain.ingestion import IngestionItem
 from tools import ToolError, read_document
 
 

package/p_reinforce.py

@@ -118,7 +118,7 @@ class PReinforceGardener:
         if self._pipeline is None:
             return {"graph": "unavailable", "graph_detail": "ingestion pipeline not wired"}
         try:
-            from latticeai.services.ingestion import IngestionItem
+            from lattice_brain.ingestion import IngestionItem
 
             ingest = self._pipeline.ingest(
                 IngestionItem(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ltcai",
-  "version": "4.3.1",
+  "version": "4.4.0",
   "description": "Lattice AI — local-first Digital Brain Platform (knowledge graph, durable memory, hybrid search, agents, portable encrypted brain archives)",
   "homepage": "https://github.com/TaeSooPark-PTS/LatticeAI#readme",
   "repository": {
@@ -25,17 +25,14 @@
     "check:python": "node scripts/run_python.mjs scripts/check_python.py",
     "lint": "node --check tests/visual/mock_server.cjs && node --check tests/visual/v3.spec.js && npm run lint:frontend",
     "lint:frontend": "node scripts/lint_frontend.mjs",
+    "docs:check-links": "node scripts/check_markdown_links.mjs",
     "typecheck": "npm run typecheck:frontend && cd vscode-extension && npm run build",
     "typecheck:frontend": "npx tsc -p tsconfig.json --noEmit",
     "test": "node scripts/run_python.mjs -m pytest tests/ -v",
     "test:unit": "node scripts/run_python.mjs -m pytest tests/unit/ -v",
     "test:integration": "node scripts/run_python.mjs -m pytest tests/integration/ -v",
     "test:visual": "playwright test",
-    "capture:workspace": "node scripts/capture/capture_workspace.js",
-    "capture:graph": "node scripts/capture/capture_graph.js",
-    "capture:skills": "node scripts/capture/capture_skills.js",
-    "capture:enterprise": "node scripts/capture/capture_enterprise.js",
-    "capture:onboarding": "node scripts/capture/capture_onboarding.js",
+    "vercel:build": "node scripts/build_vercel_static.mjs",
     "desktop:tauri": "tauri dev",
     "desktop:tauri:build": "tauri build",
     "desktop:tauri:check": "cd src-tauri && cargo check",

package/scripts/build_vercel_static.mjs

@@ -0,0 +1,77 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { readFileSync } from "node:fs";
+
+const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+const outDir = new URL("../vercel-static/", import.meta.url);
+
+await mkdir(outDir, { recursive: true });
+
+const html = `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Lattice AI ${pkg.version}</title>
+    <style>
+      :root {
+        color-scheme: dark;
+        font-family: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+        background: #0f141b;
+        color: #e5edf4;
+      }
+      body {
+        margin: 0;
+        min-height: 100vh;
+        display: grid;
+        place-items: center;
+        padding: 32px;
+      }
+      main {
+        max-width: 760px;
+        border: 1px solid #2d3745;
+        border-radius: 8px;
+        padding: 32px;
+        background: #151b24;
+      }
+      h1 {
+        margin: 0 0 12px;
+        font-size: 32px;
+      }
+      p {
+        line-height: 1.6;
+        color: #b8c4d2;
+      }
+      a {
+        color: #41ddd2;
+      }
+      code {
+        background: #0f141b;
+        border: 1px solid #2d3745;
+        border-radius: 4px;
+        padding: 2px 6px;
+      }
+    </style>
+  </head>
+  <body>
+    <main>
+      <h1>Lattice AI ${pkg.version}</h1>
+      <p>
+        Lattice AI is a local-first desktop Digital Brain. The product runtime is the
+        Tauri desktop app plus a localhost FastAPI sidecar; it is not hosted on Vercel.
+      </p>
+      <p>
+        This Vercel build is intentionally documentation-only so Git integration checks
+        do not try to deploy the desktop runtime or a fake cloud app.
+      </p>
+      <p>
+        Use the validated desktop/package artifacts from the GitHub release process.
+        Repository: <a href="${pkg.homepage}">${pkg.homepage}</a>
+      </p>
+      <p>Runtime route when installed locally: <code>http://127.0.0.1:4825/app</code></p>
+    </main>
+  </body>
+</html>
+`;
+
+await writeFile(new URL("index.html", outDir), html, "utf8");
+console.log(`Vercel static placeholder generated for Lattice AI ${pkg.version}`);

package/scripts/bump_version.py

@@ -26,7 +26,7 @@ TARGETS = [
     ("lattice_brain/__init__.py", "regex", r'(__version__ = ")([^"]+)(")'),
     ("latticeai/core/workspace_os.py", "regex", r'(WORKSPACE_OS_VERSION = ")([^"]+)(")'),
     ("latticeai/core/marketplace.py", "regex", r'(MARKETPLACE_VERSION = ")([^"]+)(")'),
-    ("latticeai/core/multi_agent.py", "regex", r'(MULTI_AGENT_VERSION = ")([^"]+)(")'),
+    ("lattice_brain/runtime/multi_agent.py", "regex", r'(MULTI_AGENT_VERSION = ")([^"]+)(")'),
     ("pyproject.toml", "regex", r'(^version = ")([^"]+)(")'),
     ("package.json", "json", "version"),
     ("package-lock.json", "package-lock", None),

package/scripts/check_markdown_links.mjs

@@ -0,0 +1,75 @@
+import { existsSync, readFileSync, statSync } from "node:fs";
+import path from "node:path";
+
+const root = process.cwd();
+const readme = path.join(root, "README.md");
+const checkedMarkdown = new Set();
+const failures = [];
+
+function stripAnchor(target) {
+  const hash = target.indexOf("#");
+  return hash >= 0 ? target.slice(0, hash) : target;
+}
+
+function isExternal(target) {
+  return /^(https?:|mailto:|tel:)/i.test(target);
+}
+
+function decodeTarget(target) {
+  return decodeURIComponent(target.replace(/^<|>$/g, ""));
+}
+
+function localPath(fromFile, target) {
+  const cleaned = stripAnchor(target).trim();
+  if (!cleaned || isExternal(cleaned)) return null;
+  return path.resolve(path.dirname(fromFile), decodeTarget(cleaned));
+}
+
+function links(markdown) {
+  const out = [];
+  const linkPattern = /!?\[[^\]]*\]\(([^)]+)\)/g;
+  let match;
+  while ((match = linkPattern.exec(markdown))) {
+    out.push(match[1].trim());
+  }
+  return out;
+}
+
+function checkFileLink(fromFile, target) {
+  const resolved = localPath(fromFile, target);
+  if (!resolved) return;
+  if (!resolved.startsWith(root)) {
+    failures.push(`${path.relative(root, fromFile)} links outside repo: ${target}`);
+    return;
+  }
+  if (!existsSync(resolved)) {
+    failures.push(`${path.relative(root, fromFile)} has missing link: ${target}`);
+  }
+}
+
+function checkMarkdownFile(file) {
+  if (checkedMarkdown.has(file)) return;
+  checkedMarkdown.add(file);
+  const markdown = readFileSync(file, "utf8");
+  for (const target of links(markdown)) {
+    checkFileLink(file, target);
+  }
+}
+
+checkMarkdownFile(readme);
+
+for (const target of links(readFileSync(readme, "utf8"))) {
+  const resolved = localPath(readme, target);
+  if (!resolved || !existsSync(resolved)) continue;
+  if (statSync(resolved).isFile() && resolved.endsWith(".md")) {
+    checkMarkdownFile(resolved);
+  }
+}
+
+if (failures.length) {
+  console.error("Markdown link check failed:");
+  for (const failure of failures) console.error(`- ${failure}`);
+  process.exit(1);
+}
+
+console.log(`Markdown link check passed for README and ${checkedMarkdown.size - 1} README-linked Markdown files.`);