Close gap in botocore model registration onboarding

[HellcatOvO]

Summary

Tightens the AWS Transform Agent Toolkit power's onboarding so users can't silently end up without registered botocore service models — the symptom that surfaces much later as Unknown service: 'transformagenticservice'.

What the user reported

The models aren't registered anywhere on this machine. The MCP server (running via uvx) has its own isolated environment but also lacks the models. This is a known gap — the botocore models need to be registered before the registry API can be called.

WARNING: Package(s) not found: agent-builder-mcp-aws-transform

The Kiro Power keeps flagging the SDK version: "Full SDK Waiting on agent-builder-sdk-aws-transform to ship (currently placeholder v0.0.1)"

Root cause

Two compounding issues, both fixable in docs and mcp.json:

1. No version floor on installs. The original pip install line and mcp.json had no version constraint. Users who installed before May 13 (when only the v0.0.1 name-reservation placeholder existed on PyPI) ended up with a package that imports but ships no botocore model JSONs, so aws configure add-model had nothing to point at. Today both packages are GA on PyPI (agent-builder-sdk-aws-transform==1.0.2, agent-builder-mcp-aws-transform==1.0.1).
2. No verification step. aws configure add-model exits 0 even when the source path is empty, so users only discovered the failure at deploy time as Unknown service. There was no immediate signal in onboarding.

A third symptom in the report — "uvx env is isolated, so it lacks the models" — is a misconception. aws configure add-model writes to ~/.aws/models/, which boto3 reads regardless of which virtualenv (or uvx environment) the client runs in. Host registration is sufficient for the MCP server too.

Changes

• POWER.md Step 2: install line now uses pip install --upgrade '...>=1.0.0' so users on placeholder v0.0.1 are pulled forward and new users skip it entirely. Adds an importlib.metadata.version print to make the resolved version visible. Adds a boto3 sanity check (Models OK) immediately after aws configure add-model that fails fast with UnknownServiceError if registration didn't take. Adds a one-line clarification that host registration is sufficient for uvx.
• POWER.md Step 5 + mcp.json: pins agent-builder-mcp-aws-transform>=1.0.0 on the uvx args so Kiro re-resolves to a real release on next launch. Adds guidance on uv cache clean --force agent-builder-mcp-aws-transform for the rare case where a previous resolution is still cached.
• troubleshooting.md entry 30: fallback recovery recipe covering the three symptoms in the report, with explicit cross-reference back to the Step 2 commands and a note correcting the uvx-isolation misconception.

No changes to Dockerfile templates or deployment-pipeline-guide.md — container builds always pull fresh from PyPI with no cache, so they already resolve to the latest stable.

Verification

All changed and added commands were run on macOS to confirm behavior:

Command	Result
pip install --upgrade '...>=1.0.0'	Resolved to agent-builder-sdk-aws-transform==1.0.2. Placeholder skipped.
python3 -c "from importlib.metadata import version; ..."	SDK version: 1.0.2
aws configure add-model (both services)	Both succeeded; SDK-bundled JSONs match what's already on disk.
python3 -c "import boto3; ...; print('Models OK')"	Models OK happy-path. Confirmed it raises UnknownServiceError when models are absent.
mcp.json args with >=1.0.0 floor	uv pip install --dry-run confirms resolution to the latest stable release.
uv cache clean --force agent-builder-mcp-aws-transform	Returned in <1s, removed 154 cached files.

Impact

• New users: guided through install + register + verify with a fail-fast signal. Can't silently land on the placeholder.
• Legacy users on placeholder v0.0.1: MCP server auto-upgrades on next Kiro launch (different mcp.json cache key). SDK side still requires re-running Step 2, but the Models OK failure and troubleshooting entry 30 surface a clear recovery path.

Related

Companion PR for fork-internal review: lzongren#4