docs(scripts): clarify prompt size limits

docs/scripts.md

@@ -21,7 +21,7 @@ Run scripts from the repository root. PowerShell and Bash commands have equivale
 | `commands/update.ps1`, `commands/update.sh` | Update an existing installation; Quick reuses saved choices. |
 | `commands/uninstall.ps1`, `commands/uninstall.sh` | Remove setup-owned configuration and extensions. |
 | `commands/doctor.ps1`, `commands/doctor.sh` | Check generated output and installed configuration. |
-| `commands/prompt-budget.ps1`, `commands/prompt-budget.sh` | Check generated instruction sizes against their budget. |
+| `commands/prompt-budget.ps1`, `commands/prompt-budget.sh` | Warn above 115% of the 4,000-byte soft target; fail above the 6,000-byte hard limit for generated permanent instructions. |
 | `commands/repository-context.ps1`, `commands/repository-context.sh` | Refresh the local repository-context cache. |
 | `commands/session-state.ps1`, `commands/session-state.sh` | Read or update the local agent session state. |
 | `commands/telemetry.ps1`, `commands/telemetry.sh` | Append a local telemetry event. |

scripts/tests/test-shell-packages.ps1

@@ -72,8 +72,9 @@ foreach ($shell in @('powershell','bash')) {
                 if (-not (Test-Path -LiteralPath $skillPath)) { throw "$package is missing generated skill $($ruleSource.Skill)." }
             }
         }
-        if ($docContent -notmatch [regex]::Escape('Use the `mcporter` CLI for MCP services by default.')) { throw "$package must set the MCPorter default" }
-        if ($docContent -notmatch [regex]::Escape('Use a native MCP connection when MCPorter is not active, or when the user explicitly requests it or selects a native MCP plugin in this configuration.')) { throw "$package must allow the selected native MCP route" }
+        if ($docContent -notmatch [regex]::Escape('Use the `mcporter` CLI for MCP servers this configuration registers there')) { throw "$package must route managed MCP servers through MCPorter" }
+        if ($docContent -notmatch [regex]::Escape("Use a selected native plugin's MCP tools directly even when MCPorter is active")) { throw "$package must allow the selected native MCP route" }
+        if ($docContent -notmatch [regex]::Escape('Keep MCPorter where it provides a concrete shared benefit')) { throw "$package must scope MCPorter to concrete shared benefits" }
         if (([regex]::Matches($docContent, [regex]::Escape('Apply instructions in this order'))).Count -ne 1) { throw "$client-$shell must embed the priority rule exactly once" }
         if ($client -eq 'codex' -and $docContent -match 'Always load and apply `rules/general\.md`') { throw "$package must not still instruct loading general.md by path" }
         if ($client -eq 'claude' -and (Test-Path (Join-Path $package 'rules/general.md'))) { throw 'Claude must not automatically load a second copy of general rules.' }

scripts/tests/test-shell-packages.sh

@@ -79,8 +79,9 @@ for shell in powershell bash; do
         test -f "$package/skills/rules/$skill_name/SKILL.md"
       done
     fi
-    printf '%s' "$doc_content" | grep -Fq 'Use the `mcporter` CLI for MCP services by default.'
-    printf '%s' "$doc_content" | grep -Fq 'Use a native MCP connection when MCPorter is not active, or when the user explicitly requests it or selects a native MCP plugin in this configuration.'
+    printf '%s' "$doc_content" | grep -Fq 'Use the `mcporter` CLI for MCP servers this configuration registers there'
+    printf '%s' "$doc_content" | grep -Fq "Use a selected native plugin's MCP tools directly even when MCPorter is active"
+    printf '%s' "$doc_content" | grep -Fq 'Keep MCPorter where it provides a concrete shared benefit'
     occurrences=$(printf '%s' "$doc_content" | grep -o 'Apply instructions in this order' | wc -l)
     [ "$occurrences" -eq 1 ] || { printf '%s-%s must embed the priority rule exactly once\n' "$client" "$shell" >&2; exit 1; }
     if [ "$client" = codex ] && printf '%s' "$doc_content" | grep -q 'Always load and apply `rules/general\.md`'; then