From 4d6b6abb5b582cb3724da4a1d8f0b798146f5b02 Mon Sep 17 00:00:00 2001 From: forkadarshp Date: Fri, 29 May 2026 06:01:40 +0530 Subject: [PATCH 1/2] docs: frame ModelPort as behavioral migration, not just ID swaps Add a "More than a model-ID swap" section: ModelPort updates prompts, tool descriptions, and guardrails to match the target model's actual behavior, including unadvertised quirks (e.g. GPT-4o's chess jump from training-data shifts that never hit the changelog), sourced from observed runs, prior migrations, web research, and provider changelogs. Update the related FAQ answer to say the same. --- README.md | 21 +++++++++++++++++++-- 1 file changed, 19 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index e164cdf..c83717c 100644 --- a/README.md +++ b/README.md @@ -69,6 +69,20 @@ tuning, and refuses to claim "done" without proof. ╰──────────────────────────────────────────────────────────────────────╯ ``` +## More than a model-ID swap + +ModelPort doesn't just rewrite `model="..."`. It updates prompts, tool +descriptions, and guardrails to match how the **target model actually behaves** — +including the undocumented quirks that never make the changelog. + +Take chess: GPT-3.5 played badly, GPT-4o was a leap ahead — not from a rules +change, but because 4o's training data held far more chess games. That kind of +capability shift never appears in the release notes. ModelPort's research +surfaces these advertised *and* unadvertised behaviors — from observed runs, +prior migrations, web research, and provider changelogs — and folds the matching +prompt and tooling changes into the migration, so the new model is actually used +to its strengths instead of just dropped in. + ## Outcomes: with vs. without ModelPort Skipping the discipline is exactly where migrations look fine in review and @@ -331,8 +345,11 @@ adaptive thinking, tokenizer, removed prefills). Often, yes — and that's the problem ModelPort exists to solve. Newer models follow instructions more literally and re-tokenize differently, so a raw -find/replace can silently break tool calls and parsers. ModelPort treats the -swap as behavior preservation and validates the contract before finishing. +find/replace can silently break tool calls and parsers. ModelPort goes beyond +the model ID: it updates prompts, tool descriptions, and guardrails to match the +target model's actual behavior — researched from observed runs, web research, +and provider changelogs, including unadvertised quirks — then validates the +contract before finishing. ### How do I benchmark Opus 4.8 against my current model? From 26a3887196582fa80fb7987ebe1e5274bafe8590 Mon Sep 17 00:00:00 2001 From: forkadarshp Date: Fri, 29 May 2026 06:05:55 +0530 Subject: [PATCH 2/2] docs: tighten README copy for community appeal (terminal-pure) Punchier, GitHub-friendly wording without emoji, keeping the terminal brand: - Hook: "Ship model upgrades without breaking prod." + agent-native / drop-in framing - Add a star CTA after the hero block - Rename headers to convention: How it works, Why ModelPort, Quickstart, What it migrates (anchors updated) --- README.md | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index c83717c..817acc2 100644 --- a/README.md +++ b/README.md @@ -8,11 +8,11 @@ ![ModelPort social preview](assets/social-preview.svg) -**Production-grade LLM migrations: Swap models safely across agents, prompts, and code.** +**Ship model upgrades without breaking prod.** -An AI agent skill for safe, production-grade LLM model migrations. Automate behavior-preserving upgrades across prompts, agents, API callers, and tests. Universal and plug-and-play across Codex, Claude Code, Cursor, and more. +Agent-native, drop-in, behavior-preserving LLM migrations — across prompts, agents, tools, API callers, and tests. One skill, works in Claude Code, Codex, and Cursor. -> **Install in one line:** `npx skills add forkadarshp/MPort` — then tell your agent to migrate. See [Quick start](#quick-start). +> **Install in one line:** `npx skills add forkadarshp/MPort` — then tell your agent to migrate. See [Quickstart](#quickstart). **The model ID is one line. The behavior around it is everything else.** Most migrations break because search-and-replace silently shatters tool calling, @@ -28,6 +28,8 @@ parsers, and orchestration. ModelPort treats a swap as behavior preservation: ✓ callers mapped ✓ contract held ✓ tests + rollback evidence ``` +> **Star it** if it's saved you a migration headache — it helps other teams find it. + ## Now shipping: Claude Opus 4.8 (released 2026-05-28) Opus 4.8 is live, and ModelPort already ships a dedicated migration guide for it: @@ -43,7 +45,7 @@ Apply required compatibility fixes first, keep tool + output behavior stable, and return validation evidence plus rollback notes. ``` -## Our approach to migration +## How it works ModelPort treats a model swap as a **behavior-preservation problem**, not a search-and-replace. The model ID is one line; the behavior around it — tool @@ -141,7 +143,7 @@ particular move with the target model and are always reported as measured, never assumed. Methodology, metric definitions, and composite scoring live in [references/benchmarking.md](references/benchmarking.md). -## Why teams use it +## Why ModelPort - Replace deprecated model IDs without breaking runtime calls. - Preserve output contracts, parser behavior, and tool calling. @@ -150,9 +152,9 @@ assumed. Methodology, metric definitions, and composite scoring live in - Produce validation evidence and rollback notes. - Benchmark pre vs. post (and raw-swap control) to quantify the upgrade. -## Quick start +## Quickstart -Install ModelPort globally for all compatible AI agents (Codex, Claude Code, Cursor, etc.) using the universal skills CLI: +Install once, use everywhere — the universal skills CLI wires ModelPort into Codex, Claude Code, Cursor, and more: ```bash npx skills add forkadarshp/MPort @@ -201,7 +203,7 @@ rollback notes. For detailed migration requests, start from [templates/migration-starter-prompt.md](templates/migration-starter-prompt.md). -## What it helps migrate +## What it migrates | Area | Migration support | | --- | --- |