substrate-setup 0.2.2__tar.gz → 0.3.1__tar.gz

{substrate_setup-0.2.2 → substrate_setup-0.3.1}/.gitignore

@@ -1,77 +1,77 @@
-# Secrets
-.env
-.env.local
-.env.*.local
-*.secret
-secrets/
-credentials.txt
-credentials.*.txt
-
-# Python
-__pycache__/
-*.py[cod]
-*$py.class
-*.so
-.Python
-.venv/
-venv/
-env/
-.pytest_cache/
-.mypy_cache/
-.ruff_cache/
-*.egg-info/
-dist/
-build/
-
-# Node / Next.js
-node_modules/
-.next/
-.vercel/
-.turbo/
-
-# CodeGraph (local-only code knowledge graph index)
-.codegraph/
-out/
-*.tsbuildinfo
-.npm/
-.yarn/
-
-# IDE
-.vscode/
-.idea/
-*.swp
-*.swo
-
-# OS
-.DS_Store
-Thumbs.db
-desktop.ini
-
-# Logs
-*.log
-logs/
-
-# Local databases
-*.db
-*.sqlite
-*.sqlite3
-
-# Editors
-*~
-.#*
-
-# Coverage
-.coverage
-htmlcov/
-coverage.xml
-*.cover
-
-# Claude Code project state (if any project-local)
-.claude/
-
-# Misc
-*.bak
-*.tmp
-
-# brainstorming companion working dir
-.superpowers/
+# Secrets
+.env
+.env.local
+.env.*.local
+*.secret
+secrets/
+credentials.txt
+credentials.*.txt
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+.venv/
+venv/
+env/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+*.egg-info/
+dist/
+build/
+
+# Node / Next.js
+node_modules/
+.next/
+.vercel/
+.turbo/
+
+# CodeGraph (local-only code knowledge graph index)
+.codegraph/
+out/
+*.tsbuildinfo
+.npm/
+.yarn/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+desktop.ini
+
+# Logs
+*.log
+logs/
+
+# Local databases
+*.db
+*.sqlite
+*.sqlite3
+
+# Editors
+*~
+.#*
+
+# Coverage
+.coverage
+htmlcov/
+coverage.xml
+*.cover
+
+# Claude Code project state (if any project-local)
+.claude/
+
+# Misc
+*.bak
+*.tmp
+
+# brainstorming companion working dir
+.superpowers/

substrate_setup-0.3.1/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+## 0.3.1 — 2026-05-24
+
+- Persist `SUBSTRATE_API_KEY` automatically during `configure`:
+  on Windows, writes `HKCU\Environment\SUBSTRATE_API_KEY` via `winreg`
+  + `WM_SETTINGCHANGE` broadcast — visible to GUI agents (Codex Desktop)
+  on next launch without the user editing rc files or restarting their
+  session. On macOS / Linux, appends a marker-fenced `export` block (or
+  fish-syntax `set -gx` for fish users) to the user's shell rc. Re-runs
+  collapse stale blocks idempotently — the rc never grows on repeated
+  configures.
+- Codex adapter now prints a one-line Windows Defender exclusion command
+  to eliminate SmartScreen prompts on per-action helper binary spawns.
+  Informational only — substrate-setup never elevates itself.
+- Adapters surface env-persistence failures with a clear `WARNING:`
+  prefix + manual fallback hint so users notice when the convenience
+  step fails but the config file itself was written successfully.
+- Codex adapter drops the stale "/v1/responses NOT YET STARTED" warning
+  — Phase 2 shipped on 2026-05-24.
+- No config schema changes from 0.3.0. Upgrade cleanly via
+  `uv tool install --force substrate-setup` (or pipx).

substrate_setup-0.3.1/PKG-INFO

@@ -0,0 +1,116 @@
+Metadata-Version: 2.4
+Name: substrate-setup
+Version: 0.3.1
+Summary: One-shot local configurator for coding agents against a Substrate gateway
+Project-URL: Homepage, https://github.com/FrankXiaA/substrate-solutions
+Project-URL: Source, https://github.com/FrankXiaA/substrate-solutions/tree/main/substrate-api/substrate_setup
+Project-URL: Issues, https://github.com/FrankXiaA/substrate-solutions/issues
+Author: Substrate Solutions
+License: MIT
+Keywords: aider,continue,gateway,hermes,llm,openai-compatible,substrate
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Code Generators
+Classifier: Topic :: Utilities
+Requires-Python: >=3.12
+Requires-Dist: httpx>=0.27
+Requires-Dist: ruamel-yaml>=0.18
+Requires-Dist: tomli-w>=1.2
+Provides-Extra: dev
+Requires-Dist: mypy<2,>=1.13; extra == 'dev'
+Requires-Dist: pytest-httpx>=0.30; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff<1,>=0.7; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# substrate-setup
+
+One-shot configurator that points local coding agents at a Substrate gateway.
+
+## Install
+
+`substrate-setup` requires Python 3.12+. The installers below pick the right interpreter automatically — you don't need a Python 3.12 already on your machine:
+
+```bash
+# Option A — uv (recommended; downloads Python 3.12 on demand if missing)
+uv tool install substrate-setup
+
+# Option B — pipx
+pipx install substrate-setup
+```
+
+Don't have `uv`? Install it once with:
+
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh   # macOS / Linux
+# or on Windows:
+powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
+```
+
+> **Why not `pip install substrate-setup`?** It works only if the `pip` on your PATH is bound to a Python 3.12+ interpreter. Anaconda's default `pip` (Python 3.9) is the common pitfall — PyPI hides every release from it with `Requires-Python >=3.12` and the error message is unhelpful. `uv` and `pipx` both create an isolated 3.12 venv for the tool, so they sidestep the issue entirely.
+
+## Use
+
+```bash
+substrate-setup configure          # detect installed agents and wire them up
+substrate-setup verify             # read-only: confirm everything points at the gateway
+substrate-setup remove             # strip the substrate-managed entries
+substrate-setup --help
+```
+
+### After running configure
+
+`substrate-setup configure` writes the API key for you automatically. On Windows it lands in `HKCU\Environment\SUBSTRATE_API_KEY` (visible to Codex Desktop and other GUI agents on next launch). On macOS / Linux it lands in your shell rc (`~/.zshrc`, `~/.bashrc`, or `~/.config/fish/config.fish` depending on `$SHELL`) inside a marker-fenced block — re-running configure replaces the block in place, no duplicates.
+
+You should not need to set `SUBSTRATE_API_KEY` by hand. If auto-persistence fails (the printed message will say `API key WARNING: …`), you can set it manually:
+
+- **Windows:** `[Environment]::SetEnvironmentVariable("SUBSTRATE_API_KEY", "<your-key>", "User")` then re-launch the agent.
+- **macOS / Linux:** add `export SUBSTRATE_API_KEY=<your-key>` to your shell rc and `source` it.
+
+Supported agents: `hermes`, `cursor`, `aider`, `continue`, `claude-code`, `codex`.
+
+Subset with `--agents-only hermes,aider`. Preview without writing: `--dry-run`. Override the gateway base URL: `--base-url https://your-gateway.example.com`.
+
+### Per-agent catalog UX (0.3.0+)
+
+| Agent | How it learns about Substrate's models |
+|---|---|
+| `hermes` | Live URL fetch via `model_catalog.providers.substrate.url`. Picker shows all chat-capable Substrate models, refreshed on Hermes' 24h TTL. |
+| `cursor` | Walkthrough printed after configure — copy the base URL, key, and model ids into Cursor's Settings → Models. |
+| `aider` | `~/.aider.model.metadata.json` written with one entry per chat-capable Substrate model. Use `--model openai/<id>` to switch. |
+| `continue` | All chat-capable Substrate models written as separate `models:` entries in `~/.continue/config.yaml`. |
+| `claude-code` | `~/.claude/settings.json` env block (`ANTHROPIC_BASE_URL`, `ANTHROPIC_AUTH_TOKEN`, `ANTHROPIC_MODEL`). The `/model` picker stays opus/sonnet/haiku — use `claude --model openai/<id>` for any other Substrate model. Requires Substrate's `/v1/messages` endpoint — shipped in gateway Phase 1. |
+| `codex` | `~/.codex/config.toml` `[model_providers.substrate]` block with `wire_api = "responses"`. API key is auto-persisted (see above). Requires Substrate's `/v1/responses` endpoint — shipped in gateway Phase 2. |
+
+### Heads-up: tool calling on Gemini 3.1 Pro Preview
+
+If your CLI agent (Hermes, Aider, etc.) uses tool calling against
+`google/gemini-3.1-pro-preview`, expect occasional misses (~20-30% of
+attempts). All other Substrate models hit ≥95% reliability for tool calls.
+
+## Troubleshooting
+
+### Windows: Defender SmartScreen prompts on every Codex click
+
+Codex Desktop spawns helper binaries (`codex-command-runner.exe`,
+`node_repl.exe`) per UI action. With `sandbox = "elevated"` in
+`~/.codex/config.toml`, each spawn triggers Windows Defender
+SmartScreen, prompting you on every click until the Codex install
+directory is whitelisted.
+
+One-time fix — open an **Administrator** PowerShell window and run:
+
+```powershell
+Add-MpPreference -ExclusionPath "$env:LOCALAPPDATA\OpenAI\Codex"
+```
+
+This excludes Codex's binaries from real-time scanning. Reverse with
+`Remove-MpPreference -ExclusionPath "$env:LOCALAPPDATA\OpenAI\Codex"`.
+
+`substrate-setup configure --agents-only codex` also prints this
+command at the end of its walkthrough on Windows.

substrate_setup-0.3.1/README.md

@@ -0,0 +1,86 @@
+# substrate-setup
+
+One-shot configurator that points local coding agents at a Substrate gateway.
+
+## Install
+
+`substrate-setup` requires Python 3.12+. The installers below pick the right interpreter automatically — you don't need a Python 3.12 already on your machine:
+
+```bash
+# Option A — uv (recommended; downloads Python 3.12 on demand if missing)
+uv tool install substrate-setup
+
+# Option B — pipx
+pipx install substrate-setup
+```
+
+Don't have `uv`? Install it once with:
+
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh   # macOS / Linux
+# or on Windows:
+powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
+```
+
+> **Why not `pip install substrate-setup`?** It works only if the `pip` on your PATH is bound to a Python 3.12+ interpreter. Anaconda's default `pip` (Python 3.9) is the common pitfall — PyPI hides every release from it with `Requires-Python >=3.12` and the error message is unhelpful. `uv` and `pipx` both create an isolated 3.12 venv for the tool, so they sidestep the issue entirely.
+
+## Use
+
+```bash
+substrate-setup configure          # detect installed agents and wire them up
+substrate-setup verify             # read-only: confirm everything points at the gateway
+substrate-setup remove             # strip the substrate-managed entries
+substrate-setup --help
+```
+
+### After running configure
+
+`substrate-setup configure` writes the API key for you automatically. On Windows it lands in `HKCU\Environment\SUBSTRATE_API_KEY` (visible to Codex Desktop and other GUI agents on next launch). On macOS / Linux it lands in your shell rc (`~/.zshrc`, `~/.bashrc`, or `~/.config/fish/config.fish` depending on `$SHELL`) inside a marker-fenced block — re-running configure replaces the block in place, no duplicates.
+
+You should not need to set `SUBSTRATE_API_KEY` by hand. If auto-persistence fails (the printed message will say `API key WARNING: …`), you can set it manually:
+
+- **Windows:** `[Environment]::SetEnvironmentVariable("SUBSTRATE_API_KEY", "<your-key>", "User")` then re-launch the agent.
+- **macOS / Linux:** add `export SUBSTRATE_API_KEY=<your-key>` to your shell rc and `source` it.
+
+Supported agents: `hermes`, `cursor`, `aider`, `continue`, `claude-code`, `codex`.
+
+Subset with `--agents-only hermes,aider`. Preview without writing: `--dry-run`. Override the gateway base URL: `--base-url https://your-gateway.example.com`.
+
+### Per-agent catalog UX (0.3.0+)
+
+| Agent | How it learns about Substrate's models |
+|---|---|
+| `hermes` | Live URL fetch via `model_catalog.providers.substrate.url`. Picker shows all chat-capable Substrate models, refreshed on Hermes' 24h TTL. |
+| `cursor` | Walkthrough printed after configure — copy the base URL, key, and model ids into Cursor's Settings → Models. |
+| `aider` | `~/.aider.model.metadata.json` written with one entry per chat-capable Substrate model. Use `--model openai/<id>` to switch. |
+| `continue` | All chat-capable Substrate models written as separate `models:` entries in `~/.continue/config.yaml`. |
+| `claude-code` | `~/.claude/settings.json` env block (`ANTHROPIC_BASE_URL`, `ANTHROPIC_AUTH_TOKEN`, `ANTHROPIC_MODEL`). The `/model` picker stays opus/sonnet/haiku — use `claude --model openai/<id>` for any other Substrate model. Requires Substrate's `/v1/messages` endpoint — shipped in gateway Phase 1. |
+| `codex` | `~/.codex/config.toml` `[model_providers.substrate]` block with `wire_api = "responses"`. API key is auto-persisted (see above). Requires Substrate's `/v1/responses` endpoint — shipped in gateway Phase 2. |
+
+### Heads-up: tool calling on Gemini 3.1 Pro Preview
+
+If your CLI agent (Hermes, Aider, etc.) uses tool calling against
+`google/gemini-3.1-pro-preview`, expect occasional misses (~20-30% of
+attempts). All other Substrate models hit ≥95% reliability for tool calls.
+
+## Troubleshooting
+
+### Windows: Defender SmartScreen prompts on every Codex click
+
+Codex Desktop spawns helper binaries (`codex-command-runner.exe`,
+`node_repl.exe`) per UI action. With `sandbox = "elevated"` in
+`~/.codex/config.toml`, each spawn triggers Windows Defender
+SmartScreen, prompting you on every click until the Codex install
+directory is whitelisted.
+
+One-time fix — open an **Administrator** PowerShell window and run:
+
+```powershell
+Add-MpPreference -ExclusionPath "$env:LOCALAPPDATA\OpenAI\Codex"
+```
+
+This excludes Codex's binaries from real-time scanning. Reverse with
+`Remove-MpPreference -ExclusionPath "$env:LOCALAPPDATA\OpenAI\Codex"`.
+
+`substrate-setup configure --agents-only codex` also prints this
+command at the end of its walkthrough on Windows.

{substrate_setup-0.2.2 → substrate_setup-0.3.1}/pyproject.toml

@@ -1,62 +1,63 @@
-[build-system]
-requires = ["hatchling"]
-build-backend = "hatchling.build"
-
-[project]
-name = "substrate-setup"
-version = "0.2.2"
-description = "One-shot local configurator for coding agents against a Substrate gateway"
-readme = "README.md"
-requires-python = ">=3.12"
-authors = [{ name = "Substrate Solutions" }]
-license = { text = "MIT" }
-keywords = ["substrate", "llm", "gateway", "aider", "continue", "hermes", "openai-compatible"]
-classifiers = [
-  "Development Status :: 4 - Beta",
-  "Environment :: Console",
-  "Intended Audience :: Developers",
-  "License :: OSI Approved :: MIT License",
-  "Operating System :: OS Independent",
-  "Programming Language :: Python :: 3 :: Only",
-  "Programming Language :: Python :: 3.12",
-  "Topic :: Software Development :: Code Generators",
-  "Topic :: Utilities",
-]
-dependencies = [
-  "httpx>=0.27",
-  "ruamel.yaml>=0.18",
-]
-
-[project.urls]
-Homepage = "https://github.com/FrankXiaA/substrate-solutions"
-Source = "https://github.com/FrankXiaA/substrate-solutions/tree/main/substrate-api/substrate_setup"
-Issues = "https://github.com/FrankXiaA/substrate-solutions/issues"
-
-[project.optional-dependencies]
-dev = [
-  "pytest>=8.0",
-  "pytest-httpx>=0.30",
-  "ruff>=0.7,<1",
-  "mypy>=1.13,<2",
-]
-
-[project.scripts]
-substrate-setup = "substrate_setup.cli:main"
-
-[tool.hatch.build.targets.wheel]
-packages = ["substrate_setup"]
-
-[tool.pytest.ini_options]
-testpaths = ["tests"]
-
-[tool.mypy]
-python_version = "3.12"
-strict = true
-ignore_missing_imports = true
-packages = ["substrate_setup"]
-
-[[tool.mypy.overrides]]
-module = "tests.*"
-disallow_untyped_defs = false
-disallow_incomplete_defs = false
-check_untyped_defs = false
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "substrate-setup"
+version = "0.3.1"
+description = "One-shot local configurator for coding agents against a Substrate gateway"
+readme = "README.md"
+requires-python = ">=3.12"
+authors = [{ name = "Substrate Solutions" }]
+license = { text = "MIT" }
+keywords = ["substrate", "llm", "gateway", "aider", "continue", "hermes", "openai-compatible"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Software Development :: Code Generators",
+  "Topic :: Utilities",
+]
+dependencies = [
+  "httpx>=0.27",
+  "ruamel.yaml>=0.18",
+  "tomli-w>=1.2",
+]
+
+[project.urls]
+Homepage = "https://github.com/FrankXiaA/substrate-solutions"
+Source = "https://github.com/FrankXiaA/substrate-solutions/tree/main/substrate-api/substrate_setup"
+Issues = "https://github.com/FrankXiaA/substrate-solutions/issues"
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.0",
+  "pytest-httpx>=0.30",
+  "ruff>=0.7,<1",
+  "mypy>=1.13,<2",
+]
+
+[project.scripts]
+substrate-setup = "substrate_setup.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["substrate_setup"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.mypy]
+python_version = "3.12"
+strict = true
+ignore_missing_imports = true
+packages = ["substrate_setup"]
+
+[[tool.mypy.overrides]]
+module = "tests.*"
+disallow_untyped_defs = false
+disallow_incomplete_defs = false
+check_untyped_defs = false

{substrate_setup-0.2.2 → substrate_setup-0.3.1}/scripts/lint_no_app_import.sh

@@ -1,10 +1,10 @@
-#!/usr/bin/env bash
-# CI lint: substrate_setup/ MUST NOT import anything from app/.
-# The two packages share a source tree, not a dependency graph.
-set -euo pipefail
-PKG_DIR="$(cd "$(dirname "$0")/.." && pwd)"
-if grep -RIn --include='*.py' '^from app\b\|^import app\b' "$PKG_DIR/substrate_setup"; then
-    echo "ERROR: substrate_setup/ must not import from app/. See package boundary rule in spec."
-    exit 1
-fi
-echo "OK: no app/ imports in substrate_setup/"
+#!/usr/bin/env bash
+# CI lint: substrate_setup/ MUST NOT import anything from app/.
+# The two packages share a source tree, not a dependency graph.
+set -euo pipefail
+PKG_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+if grep -RIn --include='*.py' '^from app\b\|^import app\b' "$PKG_DIR/substrate_setup"; then
+    echo "ERROR: substrate_setup/ must not import from app/. See package boundary rule in spec."
+    exit 1
+fi
+echo "OK: no app/ imports in substrate_setup/"

{substrate_setup-0.2.2 → substrate_setup-0.3.1}/scripts/regenerate_fallback_catalog.py

@@ -1,68 +1,68 @@
-"""Regenerate the bundled fallback catalog snapshot.
-
-Run manually before each PyPI release of substrate-setup. NOT run by CI cron —
-a transient production glitch should NEVER be baked into the next release.
-
-Usage:
-    SUBSTRATE_API_KEY=sk-substrate-... \
-        python scripts/regenerate_fallback_catalog.py [--base-url https://...]
-
-Writes substrate_setup/data/fallback_catalog.json. Applies a sanity check
-(>= 5 models, all five expected providers present) before writing.
-"""
-from __future__ import annotations
-
-import argparse
-import json
-import os
-import sys
-from pathlib import Path
-
-import httpx
-
-EXPECTED_PROVIDERS = {"anthropic", "openai", "google", "deepseek", "moonshot"}
-DEFAULT_BASE_URL = "https://substrate-solutions-api.fly.dev/v1"
-TARGET = Path(__file__).resolve().parents[1] / "substrate_setup" / "data" / "fallback_catalog.json"
-
-
-def main(argv: list[str] | None = None) -> int:
-    parser = argparse.ArgumentParser()
-    parser.add_argument("--base-url", default=DEFAULT_BASE_URL)
-    args = parser.parse_args(argv)
-
-    api_key = os.environ.get("SUBSTRATE_API_KEY")
-    if not api_key:
-        print("ERROR: SUBSTRATE_API_KEY env var required.", file=sys.stderr)
-        return 1
-
-    # Tolerate --base-url with or without a trailing /v1 (same convention as
-    # substrate_setup.catalog.fetch_catalog).
-    normalized = args.base_url.rstrip("/")
-    if normalized.endswith("/v1"):
-        normalized = normalized[:-3]
-
-    resp = httpx.get(
-        f"{normalized}/v1/models",
-        headers={"Authorization": f"Bearer {api_key}"},
-        timeout=15.0,
-    )
-    resp.raise_for_status()
-    payload = resp.json()
-
-    data = payload.get("data") or []
-    providers = {item.get("owned_by") for item in data}
-    if len(data) < 5:
-        print(f"REFUSED: only {len(data)} models in catalog (expected >= 5).", file=sys.stderr)
-        return 2
-    if not EXPECTED_PROVIDERS.issubset(providers):
-        missing = EXPECTED_PROVIDERS - providers
-        print(f"REFUSED: missing providers {missing}.", file=sys.stderr)
-        return 2
-
-    TARGET.write_text(json.dumps(payload, indent=2) + "\n", encoding="utf-8")
-    print(f"Wrote {len(data)} models to {TARGET}")
-    return 0
-
-
-if __name__ == "__main__":
-    raise SystemExit(main())
+"""Regenerate the bundled fallback catalog snapshot.
+
+Run manually before each PyPI release of substrate-setup. NOT run by CI cron —
+a transient production glitch should NEVER be baked into the next release.
+
+Usage:
+    SUBSTRATE_API_KEY=sk-substrate-... \
+        python scripts/regenerate_fallback_catalog.py [--base-url https://...]
+
+Writes substrate_setup/data/fallback_catalog.json. Applies a sanity check
+(>= 5 models, all five expected providers present) before writing.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+
+import httpx
+
+EXPECTED_PROVIDERS = {"anthropic", "openai", "google", "deepseek", "moonshot"}
+DEFAULT_BASE_URL = "https://substrate-solutions-api.fly.dev/v1"
+TARGET = Path(__file__).resolve().parents[1] / "substrate_setup" / "data" / "fallback_catalog.json"
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--base-url", default=DEFAULT_BASE_URL)
+    args = parser.parse_args(argv)
+
+    api_key = os.environ.get("SUBSTRATE_API_KEY")
+    if not api_key:
+        print("ERROR: SUBSTRATE_API_KEY env var required.", file=sys.stderr)
+        return 1
+
+    # Tolerate --base-url with or without a trailing /v1 (same convention as
+    # substrate_setup.catalog.fetch_catalog).
+    normalized = args.base_url.rstrip("/")
+    if normalized.endswith("/v1"):
+        normalized = normalized[:-3]
+
+    resp = httpx.get(
+        f"{normalized}/v1/models",
+        headers={"Authorization": f"Bearer {api_key}"},
+        timeout=15.0,
+    )
+    resp.raise_for_status()
+    payload = resp.json()
+
+    data = payload.get("data") or []
+    providers = {item.get("owned_by") for item in data}
+    if len(data) < 5:
+        print(f"REFUSED: only {len(data)} models in catalog (expected >= 5).", file=sys.stderr)
+        return 2
+    if not EXPECTED_PROVIDERS.issubset(providers):
+        missing = EXPECTED_PROVIDERS - providers
+        print(f"REFUSED: missing providers {missing}.", file=sys.stderr)
+        return 2
+
+    TARGET.write_text(json.dumps(payload, indent=2) + "\n", encoding="utf-8")
+    print(f"Wrote {len(data)} models to {TARGET}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())