netconverter-cli 0.4.0__py3-none-any.whl

netconverter_cli/update.py

@@ -0,0 +1,344 @@
+"""`netconverter update` and the once-a-day "new version available" notice.
+
+Only the public GitHub Releases API of this repository is contacted, without
+credentials: no NetConverter key or sign-in is ever sent there. A copy that uv
+installed from PyPI is upgraded with ``uv tool upgrade``; any other copy gets the
+release wheel, installed only after its SHA-256 matches ``SHA256SUMS``. The
+passive check runs in a background thread with a short timeout, writes a small
+cache file, swallows every error and never prints to stdout.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import re
+import shutil
+import subprocess
+import sys
+import tempfile
+import threading
+import time
+import tomllib
+from importlib import metadata
+from pathlib import Path
+from urllib.parse import urlsplit
+
+import httpx
+
+from . import __version__
+
+REPO = "valeronlabs/netconverter_terminals"
+DIST = "netconverter-cli"
+LATEST_URL = f"https://api.github.com/repos/{REPO}/releases/latest"
+DOWNLOAD_PREFIX = f"https://github.com/{REPO}/releases/download/"
+# GitHub answers an asset download with a redirect to its object storage.
+DOWNLOAD_HOSTS = frozenset({"github.com", "objects.githubusercontent.com",
+                            "release-assets.githubusercontent.com"})
+CHECK_INTERVAL_S = 24 * 3600
+NOTICE_TIMEOUT_S = 3.0
+MAX_WHEEL_BYTES = 50 * 1024 * 1024
+MAX_SUMS_BYTES = 64 * 1024
+MAX_API_BYTES = 1024 * 1024
+_VERSION = re.compile(r"v?(\d{1,4})\.(\d{1,4})\.(\d{1,4})\Z")
+_WHEEL = re.compile(r"netconverter_cli-(\d{1,4}\.\d{1,4}\.\d{1,4})-py3-none-any\.whl\Z")
+_HEX = re.compile(r"[0-9a-f]{64}\Z")
+
+
+class UpdateError(RuntimeError):
+    pass
+
+
+def disabled() -> bool:
+    return os.getenv("NETCONVERTER_NO_UPDATE_CHECK") == "1"
+
+
+def parse_version(text) -> tuple | None:
+    """(major, minor, patch) for a plain release version; None for anything else (pre-releases)."""
+    match = _VERSION.fullmatch(str(text or "").strip())
+    return tuple(int(part) for part in match.groups()) if match else None
+
+
+def newer(latest, installed=__version__) -> bool:
+    a, b = parse_version(latest), parse_version(installed)
+    return bool(a and b and a > b)
+
+
+def cache_dir() -> Path:
+    """The per-user cache folder (never the workspace)."""
+    if sys.platform == "darwin":
+        return Path.home() / "Library" / "Caches" / "netconverter"
+    if os.name == "nt":
+        base = os.getenv("LOCALAPPDATA")
+        return (Path(base) if base else Path.home() / "AppData" / "Local") / "netconverter" / "Cache"
+    base = os.getenv("XDG_CACHE_HOME")
+    return (Path(base) if base else Path.home() / ".cache") / "netconverter"
+
+
+def _cache_file() -> Path:
+    return cache_dir() / "update-check.json"
+
+
+def read_cache() -> dict:
+    try:
+        data = json.loads(_cache_file().read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def write_cache(**fields) -> None:
+    path = _cache_file()
+    data = {**read_cache(), **fields}
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd, name = tempfile.mkstemp(prefix=".update-", dir=path.parent)
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as stream:
+            json.dump(data, stream)
+        os.replace(name, path)
+    finally:
+        Path(name).unlink(missing_ok=True)
+
+
+# -- GitHub ---------------------------------------------------------------
+
+
+def _http(transport=None, timeout=10.0) -> httpx.Client:
+    return httpx.Client(timeout=timeout, transport=transport, follow_redirects=False, trust_env=False,
+                        headers={"Accept": "application/vnd.github+json",
+                                 "User-Agent": f"netconverter-cli/{__version__}"})
+
+
+def latest_release(*, transport=None, timeout=10.0) -> dict:
+    """{version, tag, wheel_name, wheel_url, sums_url}; sums_url/wheel_* may be None."""
+    with _http(transport, timeout) as http:
+        try:
+            response = http.get(LATEST_URL)
+        except httpx.HTTPError:
+            raise UpdateError("Could not reach GitHub to check for a new release") from None
+    if response.status_code == 404:
+        raise UpdateError("No published release was found")
+    if response.is_error or len(response.content) > MAX_API_BYTES:
+        raise UpdateError(f"GitHub answered HTTP {response.status_code}")
+    try:
+        body = response.json()
+    except ValueError:
+        raise UpdateError("GitHub returned an invalid response") from None
+    tag = body.get("tag_name") if isinstance(body, dict) else None
+    version = parse_version(tag)
+    if version is None:
+        raise UpdateError("The latest release has no plain version tag")
+    out = {"version": ".".join(map(str, version)), "tag": str(tag), "wheel_name": None,
+           "wheel_url": None, "sums_url": None}
+    for asset in body.get("assets") or []:
+        if not isinstance(asset, dict):
+            continue
+        name, url = asset.get("name"), asset.get("browser_download_url")
+        if not isinstance(name, str) or not isinstance(url, str) or url != f"{DOWNLOAD_PREFIX}{tag}/{name}":
+            continue
+        wheel = _WHEEL.fullmatch(name)
+        if wheel and wheel.group(1) == out["version"]:
+            out["wheel_name"], out["wheel_url"] = name, url
+        elif name == "SHA256SUMS":
+            out["sums_url"] = url
+    return out
+
+
+def _download(http: httpx.Client, url: str, limit: int) -> bytes:
+    for _ in range(5):  # bounded redirects, each to an allowlisted HTTPS host
+        parts = urlsplit(url)
+        if parts.scheme != "https" or (parts.hostname or "") not in DOWNLOAD_HOSTS:
+            raise UpdateError("Release download redirected to an unexpected host")
+        try:
+            with http.stream("GET", url, headers={"Accept": "application/octet-stream"}) as response:
+                if response.is_redirect:
+                    url = str(response.url.join(response.headers.get("location", "")))
+                    continue
+                if response.is_error:
+                    raise UpdateError(f"Release download failed (HTTP {response.status_code})")
+                chunks, size = [], 0
+                for chunk in response.iter_bytes():
+                    size += len(chunk)
+                    if size > limit:
+                        raise UpdateError("Release asset is larger than expected")
+                    chunks.append(chunk)
+                return b"".join(chunks)
+        except httpx.HTTPError:
+            raise UpdateError("Release download failed") from None
+    raise UpdateError("Too many redirects downloading the release")
+
+
+def expected_hash(sums: bytes, filename: str) -> str:
+    for line in sums.decode("utf-8", "replace").splitlines():
+        parts = line.strip().split()
+        if len(parts) == 2 and parts[1].lstrip("*") == filename and _HEX.fullmatch(parts[0].lower()):
+            return parts[0].lower()
+    raise UpdateError(f"SHA256SUMS has no entry for {filename}")
+
+
+def fetch_verified_wheel(release: dict, dest: Path, *, transport=None) -> Path:
+    if not release.get("wheel_url") or not release.get("sums_url"):
+        raise UpdateError("The latest release has no wheel and SHA256SUMS to verify")
+    with _http(transport, 60.0) as http:
+        sums = _download(http, release["sums_url"], MAX_SUMS_BYTES)
+        wheel = _download(http, release["wheel_url"], MAX_WHEEL_BYTES)
+    want = expected_hash(sums, release["wheel_name"])
+    got = hashlib.sha256(wheel).hexdigest()
+    if got != want:
+        raise UpdateError(f"Checksum mismatch for {release['wheel_name']}; nothing was installed")
+    path = Path(dest) / release["wheel_name"]
+    path.write_bytes(wheel)
+    return path
+
+
+# -- how this copy was installed ------------------------------------------
+
+# Receipt keys that mean uv installed from a file, URL or checkout, not the index.
+_DIRECT_KEYS = ("path", "url", "git", "directory", "editable")
+
+
+def _has_direct_url() -> bool:
+    """PEP 610: a wheel, URL or checkout install records direct_url.json; an index install does not."""
+    try:
+        return metadata.distribution(DIST).read_text("direct_url.json") is not None
+    except metadata.PackageNotFoundError:
+        return True
+
+
+def from_pypi(prefix=None, direct_url=_has_direct_url) -> bool:
+    """True when this copy is a `uv tool install netconverter-cli` from the package index."""
+    try:
+        receipt = tomllib.loads((Path(prefix or sys.prefix) / "uv-receipt.toml").read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return False
+    for req in (receipt.get("tool") or {}).get("requirements") or []:
+        if isinstance(req, dict) and req.get("name") == DIST:
+            return not any(key in req for key in _DIRECT_KEYS) and not direct_url()
+    return False
+
+
+# -- `netconverter update` ------------------------------------------------
+
+
+def run(args, *, transport=None, runner=subprocess.run, which=shutil.which, ask=input,
+        pypi=from_pypi) -> int:
+    try:
+        release = latest_release(transport=transport)
+    except UpdateError as exc:
+        print(f"netconverter update: {exc}", file=sys.stderr)
+        return 1
+    available = newer(release["version"])
+    try:
+        write_cache(checked_at=time.time(), latest=release["version"])
+    except OSError:
+        pass
+    if args.check:
+        print(json.dumps({"installed": __version__, "latest": release["version"],
+                          "update_available": available}))
+        return 0
+    if not available:
+        print(f"NetConverter CLI {__version__} is up to date (latest release {release['version']}).")
+        return 0
+    uv = which("uv")
+    if uv and pypi():
+        return _upgrade_from_pypi(args, release, uv, runner, ask)
+    if not uv:
+        print(f"NetConverter CLI {release['version']} is available (installed {__version__}), "
+              "but uv is not on PATH. Download the wheel and SHA256SUMS from\n"
+              f"  https://github.com/{REPO}/releases/tag/{release['tag']}\n"
+              "verify it with `shasum -a 256 -c SHA256SUMS`, then run:\n"
+              f"  uv tool install --force ./{release['wheel_name'] or 'netconverter_cli-<version>-py3-none-any.whl'}")
+        return 1
+    print(f"Update NetConverter CLI {__version__} → {release['version']} "
+          f"(verified wheel from github.com/{REPO}).")
+    if not args.yes and ask("Install it now? [y/N] ").strip().lower() not in {"y", "yes"}:
+        print("Nothing was changed.")
+        return 0
+    with tempfile.TemporaryDirectory(prefix="netconverter-update-") as tmp:
+        try:
+            wheel = fetch_verified_wheel(release, Path(tmp), transport=transport)
+        except UpdateError as exc:
+            print(f"netconverter update: {exc}", file=sys.stderr)
+            return 1
+        print(f"SHA-256 verified: {wheel.name}")
+        done = runner([uv, "tool", "install", "--force", str(wheel)])
+    if done.returncode != 0:
+        print("uv tool install failed; your current version is unchanged.", file=sys.stderr)
+        return 1
+    print(f"Installed NetConverter CLI {release['version']}.")
+    return 0
+
+
+def _upgrade_from_pypi(args, release, uv, runner, ask) -> int:
+    print(f"Update NetConverter CLI {__version__} → {release['version']} (PyPI, `uv tool upgrade {DIST}`).")
+    if not args.yes and ask("Upgrade it now? [y/N] ").strip().lower() not in {"y", "yes"}:
+        print("Nothing was changed.")
+        return 0
+    if runner([uv, "tool", "upgrade", DIST]).returncode != 0:
+        print("uv tool upgrade failed; your current version is unchanged.", file=sys.stderr)
+        return 1
+    print("Upgraded NetConverter CLI from PyPI. Run `netconverter --version` to confirm.")
+    return 0
+
+
+# -- passive check --------------------------------------------------------
+
+
+def cached_status() -> dict:
+    """{latest, update_available} from the cache only; never touches the network."""
+    latest = read_cache().get("latest")
+    return {"latest": latest if parse_version(latest) else None,
+            "update_available": newer(latest) if parse_version(latest) else None}
+
+
+def refresh(*, transport=None, timeout=NOTICE_TIMEOUT_S) -> None:
+    """One bounded check that updates the cache. Errors are swallowed."""
+    try:
+        release = latest_release(transport=transport, timeout=timeout)
+        write_cache(checked_at=time.time(), latest=release["version"])
+    except Exception:
+        try:
+            write_cache(checked_at=time.time())  # do not retry on every command while offline
+        except Exception:
+            pass
+
+
+def _stale(now=None) -> bool:
+    checked = read_cache().get("checked_at")
+    return not isinstance(checked, (int, float)) or (now or time.time()) - checked >= CHECK_INTERVAL_S
+
+
+def status(*, transport=None, timeout=NOTICE_TIMEOUT_S) -> dict:
+    """For the MCP `account` tool: the cache, refreshed (bounded) when older than a day."""
+    if disabled():
+        return {"latest": None, "update_available": None}
+    try:
+        if _stale():
+            refresh(transport=transport, timeout=timeout)
+        return cached_status()
+    except Exception:
+        return {"latest": None, "update_available": None}
+
+
+def notify(stream=None, *, transport=None, background=True) -> None:
+    """At most once a day, a one-line notice on stderr. Never blocks or raises."""
+    try:
+        stream = stream or sys.stderr
+        if disabled() or not stream.isatty():
+            return
+        now = time.time()
+        state = cached_status()
+        notified = read_cache().get("notified_at")
+        recently = isinstance(notified, (int, float)) and now - notified < CHECK_INTERVAL_S
+        if state["update_available"] and not recently:
+            stream.write(f"NetConverter CLI {state['latest']} is available (installed {__version__}). "
+                         "Run `netconverter update`. Set NETCONVERTER_NO_UPDATE_CHECK=1 to hide this.\n")
+            write_cache(notified_at=now)
+        if _stale(now):
+            if background:
+                threading.Thread(target=refresh, kwargs={"transport": transport}, daemon=True).start()
+            else:
+                refresh(transport=transport)
+    except Exception:
+        pass

netconverter_cli/workspace.py

@@ -0,0 +1,148 @@
+"""Bounded local IO. This module is never exposed as a model tool."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import re
+import tempfile
+from pathlib import Path
+
+MAX_CONFIG_BYTES = 50_000
+_IDENTIFIER = re.compile(r"[A-Za-z0-9_-]{1,80}\Z")
+
+
+class WorkspaceError(ValueError):
+    pass
+
+
+class Workspace:
+    def __init__(self, root: Path | str):
+        self.root = Path(root).resolve(strict=True)
+        self.state_dir = self.root / ".netconverter"
+
+    def _inside(self, path: Path) -> Path:
+        resolved = path.resolve()
+        if not resolved.is_relative_to(self.root):
+            raise WorkspaceError("Path is outside the workspace")
+        return resolved
+
+    def locate(self, filename: str | os.PathLike) -> Path:
+        """Resolve a user/model-supplied path, confined to the workspace.
+
+        Relative paths are taken from the workspace root; absolute paths must
+        already point inside it. The named file itself may not be a symlink,
+        and any symlinked directory on the way must still resolve inside the
+        root. The client's own ``.netconverter`` state folder is never offered.
+        """
+        raw = Path(filename)
+        if "\x00" in str(filename):
+            raise WorkspaceError("Invalid path")
+        candidate = raw if raw.is_absolute() else self.root / raw
+        if candidate.is_symlink():
+            raise WorkspaceError("Symbolic links are not accepted; pass the real file")
+        resolved = self._inside(candidate)
+        if resolved == self.state_dir or resolved.is_relative_to(self.state_dir):
+            raise WorkspaceError("The client state folder is not a configuration source")
+        return resolved
+
+    def snapshot(
+        self, filename: str, max_bytes: int = MAX_CONFIG_BYTES
+    ) -> tuple[Path, bytes, str]:
+        path = self.locate(filename)
+        if not path.is_file():
+            raise WorkspaceError("Select a regular configuration file")
+        # Bound the read, including when the source changes during the read.
+        with path.open("rb") as stream:
+            content = stream.read(max_bytes + 1)
+        if not content or len(content) > max_bytes:
+            raise WorkspaceError(
+                "Free pilot inputs must be 1–50,000 bytes; contact NetConverter for larger files"
+                if max_bytes == MAX_CONFIG_BYTES
+                else f"Configuration must be 1–{max_bytes:,} bytes"
+            )
+        try:
+            content.decode("utf-8")
+        except UnicodeDecodeError:
+            raise WorkspaceError(
+                "Select a UTF-8 text, SET, or XML configuration"
+            ) from None
+        if b"\x00" in content:
+            raise WorkspaceError("Binary configurations are not supported")
+        return path, content, hashlib.sha256(content).hexdigest()
+
+    def load(self) -> dict:
+        path = self._inside(self.state_dir / "session.json")
+        if not path.exists():
+            return {"version": 1, "configurations": {}, "jobs": {}}
+        if path.stat().st_size > 1_000_000:
+            raise WorkspaceError("Session metadata exceeds its limit")
+        try:
+            state = json.loads(path.read_text())
+            if state.get("version") != 1 or not isinstance(state.get("jobs"), dict):
+                raise ValueError()
+            return state
+        except (ValueError, TypeError):
+            raise WorkspaceError(
+                "Invalid session metadata; originals have not been changed"
+            ) from None
+
+    def store(self, state: dict) -> None:
+        self._inside(self.state_dir).mkdir(mode=0o700, exist_ok=True)
+        self._atomic_replace(
+            self.state_dir / "session.json", json.dumps(state, indent=2).encode()
+        )
+
+    @staticmethod
+    def _atomic_replace(path: Path, content: bytes) -> None:
+        fd, name = tempfile.mkstemp(prefix=".nc-", dir=path.parent)
+        try:
+            with os.fdopen(fd, "wb") as stream:
+                stream.write(content)
+                stream.flush()
+                os.fsync(stream.fileno())
+            os.replace(name, path)
+        finally:
+            Path(name).unlink(missing_ok=True)
+
+    def save_artifact(
+        self, job_id: str, filename: str, content: bytes, sha256: str
+    ) -> Path:
+        if not _IDENTIFIER.fullmatch(job_id):
+            raise WorkspaceError("Invalid server job ID")
+        if (
+            not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9._-]{0,120}", filename)
+            or ".." in filename
+        ):
+            raise WorkspaceError("Invalid artifact filename")
+        if (
+            not re.fullmatch(r"[a-f0-9]{64}", sha256)
+            or hashlib.sha256(content).hexdigest() != sha256
+        ):
+            raise WorkspaceError("Artifact checksum failed; no file was written")
+        path = self.root / f"{job_id}.{filename}"
+        if path.is_symlink():
+            raise WorkspaceError("Artifact destination is a symlink")
+        if path.exists():
+            if path.read_bytes() == content:
+                return path
+            raise WorkspaceError(
+                "Artifact destination already exists with different contents"
+            )
+        fd, temporary = tempfile.mkstemp(prefix=".nc-download-", dir=self.root)
+        try:
+            with os.fdopen(fd, "wb") as stream:
+                stream.write(content)
+                stream.flush()
+                os.fsync(stream.fileno())
+            # Atomic no-clobber publication, including a concurrent user write.
+            try:
+                os.link(temporary, path)
+            except FileExistsError:
+                raise WorkspaceError(
+                    "Artifact destination was created during download"
+                ) from None
+        finally:
+            Path(temporary).unlink(missing_ok=True)
+        return path

netconverter_cli-0.4.0.dist-info/METADATA

@@ -0,0 +1,167 @@
+Metadata-Version: 2.5
+Name: netconverter-cli
+Version: 0.4.0
+Summary: NetConverter CLI — any-vendor network configuration migration, validation and optimization, and a local MCP bridge for your AI assistant
+Project-URL: Homepage, https://netconverter.ai
+Project-URL: Repository, https://github.com/valeronlabs/netconverter_terminals
+Project-URL: Documentation, https://github.com/valeronlabs/netconverter_terminals/blob/main/QUICK_START.md
+Project-URL: Issues, https://github.com/valeronlabs/netconverter_terminals/issues
+Project-URL: Changelog, https://github.com/valeronlabs/netconverter_terminals/blob/main/CHANGELOG.md
+Author-email: ValeronLabs LLC <contact@netconverter.ai>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: check-point,cisco,firewall,fortinet,mcp,migration,model-context-protocol,netconverter,network-automation,palo-alto
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: System Administrators
+Classifier: Intended Audience :: Telecommunications Industry
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Networking
+Classifier: Topic :: System :: Networking :: Firewalls
+Classifier: Topic :: Utilities
+Requires-Python: >=3.12
+Requires-Dist: httpx==0.28.1
+Requires-Dist: keyring==25.7.0
+Requires-Dist: pydantic==2.13.5
+Requires-Dist: textual==8.2.8
+Description-Content-Type: text/markdown
+
+# NetConverter CLI
+
+<!-- mcp-name: ai.netconverter/netconverter -->
+
+**Migrate, validate and optimize network configurations from the folder that holds them — and let your own AI assistant do it too, without the configuration ever passing through the model.**
+
+NetConverter — by ValeronLabs LLC.
+
+```text
+◆ NetConverter  v0.3.0                      ● Server   ◆ Bridge claude-code · 2m ago
+▍ Start
+▍ /convert    Migrate a configuration to another vendor
+▍ /validate   Check a configuration before migrating
+▍ /optimize   Cleanup and optimization findings
+▍ /activity   What your AI assistant did here
+╭ What does edge-fw.conf contain? ───────────────────────────────╮
+│ ▸  1  Fortinet FortiGate  · detected                            │
+│    2  Cisco ASA                                                 │
+╰──────────────────────────────── ↑↓ choose · 1–9 jump · Enter ───╯
+```
+
+One small client, three ways in:
+
+| | What it is |
+| --- | --- |
+| `netconverter` | A keyboard-first full-screen app: pick a file, answer a few inline questions, follow the job, get verified outputs beside your source. |
+| `netconverter mcp` | A local MCP bridge for Claude Code, Claude Desktop, Cursor, VS Code and Codex. Your AI passes a **file path**; the bridge reads the file and uploads it straight to NetConverter. The AI sees paths, job IDs and summaries — never the configuration. |
+| `netconverter validate edge.cfg --vendor fortinet` | Plain one-shot commands that print JSON, for scripts and CI. |
+
+## What it supports
+
+Whatever the NetConverter server you sign in to supports — the client reads
+`GET /capabilities` and builds every menu from it, so new vendors appear
+without a client update. Today that is:
+
+- **Firewalls:** Palo Alto (SET, XML, Panorama), Fortinet FortiGate, Cisco FMC (JSON);
+  Cisco ASA as a source. Check Point is a source through a handoff bundle in the portal.
+- **Routers and switches:** Cisco IOS-XE, Juniper JunOS (braces and set), Aruba CX;
+  ArubaOS as a source.
+- **Jobs:** convert, validate, optimize; follow-up questions on NAT, policy, routes,
+  interfaces, unused objects, object dependencies and traffic flows.
+
+Run `netconverter capabilities` to see exactly what your credential can do.
+A 0.1.x **Terminal Quick pilot key** still works and keeps its ASA → Palo Alto
+scope; the app labels it as such.
+
+## Start here
+
+One line installs everything (uv, the CLI from PyPI), signs you in and connects
+your AI assistants to `~/migrations`:
+
+```sh
+curl -LsSf https://netconverter.ai/install.sh | sh              # macOS / Linux
+```
+
+```powershell
+irm https://netconverter.ai/install.ps1 | iex                    # Windows PowerShell
+```
+
+Options: `--yes` (no prompts, for IT/MDM), `--no-connect`, `--workspace PATH`
+(`curl … | sh -s -- --yes`; PowerShell: `-Yes -NoConnect -Workspace PATH`, see
+[scripts/install.ps1](scripts/install.ps1)). Running it again only does what is missing.
+
+Or by hand:
+
+```sh
+# 1. Install (Python 3.12+ via uv: https://docs.astral.sh/uv)
+uv tool install --python 3.12 netconverter-cli
+
+# 2. Sign in once
+netconverter login --clerk          # your NetConverter account, in the browser
+#    or: netconverter login          # paste an API key at a hidden prompt
+
+# 3. Work in the folder that holds your configs
+cd ~/migrations && netconverter
+```
+
+Upgrading from `netconverter-terminal` 0.1.x: `uv tool uninstall netconverter-terminal`
+first. Saved keys and sign-ins carry over (Keychain service **NetConverter Terminal**).
+
+Full walkthrough: [Quick start](QUICK_START.md).
+
+## Use it from your AI
+
+Step-by-step guides for every assistant (Claude, ChatGPT, Cursor, Gemini CLI, Codex …):
+[docs/connect](docs/connect/README.md).
+
+```sh
+netconverter connect claude-code    # or claude-desktop, cursor, vscode, codex, gemini, windsurf, lmstudio
+netconverter connect --all          # every assistant found on this computer
+netconverter connect chatgpt        # ChatGPT / claude.ai: remote-connector setup steps
+```
+
+`connect` shows the exact change it will make and asks before applying it
+(Claude Code through its own `claude mcp add`; JSON files keep a `.bak`). For
+Claude Code it then offers a `Read` deny rule for the folder, so the assistant
+works on your configurations only through the bridge.
+Then ask your assistant, for example: *"Validate edge-fw.conf and tell me what it finds,"*
+*"Convert it to Palo Alto XML,"* *"Can WEB reach DB on tcp/1433?"*
+
+Bridge tools: `submit_file`, `job_status`, `wait_for_job`, `account`, `download`,
+plus an allowlist of NetConverter's read-only tools (reports, evidence, NAT, flows,
+knowledge base). `netconverter mcp --strict` narrows those to the strict-view set.
+
+Inside the app, `/activity` and the header's **Bridge** pill show what your AI did
+through the bridge — paths, sizes, SHA-256 and job IDs only.
+
+## Stay current
+
+`netconverter update` upgrades a PyPI install with `uv tool upgrade netconverter-cli`;
+a copy installed from a release wheel gets the latest wheel after its SHA-256 is
+checked (`--check` only reports). Interactive commands mention a new release at most once
+a day; set `NETCONVERTER_NO_UPDATE_CHECK=1` to turn that off.
+
+## Boundaries
+
+- Configurations travel only from your workspace to NetConverter, over HTTPS.
+  The bridge never returns configuration text to the AI; the server tokenizes
+  addresses and removes credentials from every summary.
+- The client never pushes to a device. Outputs are files you review and load.
+- Downloads are hash-verified and never overwrite a file you changed.
+- An optional in-app model (`/model`: Anthropic, OpenAI, Gemini or local Ollama)
+  only chooses among fixed operations; it never receives configurations or results.
+
+## Documentation
+
+- [Quick start](QUICK_START.md) · [Commands and troubleshooting](docs/COMMANDS.md)
+- [Privacy and data flow](docs/PRIVACY.md) · [Verification status](docs/VERIFICATION.md)
+- [Changelog](CHANGELOG.md) · [Contributing](CONTRIBUTING.md) · [Security](SECURITY.md)
+
+The client is [MIT licensed](LICENSE). The license does not grant access to the
+hosted service or license the server code. macOS is the exercised platform;
+Windows acceptance remains pending.