diff --git a/README.md b/README.md
index a45289d..2ff0066 100644
--- a/README.md
+++ b/README.md
@@ -42,6 +42,13 @@ Documentation is available at https://kiro.dev/docs/powers/
 
 ---
 
+### aws-transform-custom
+**Crush tech debt with AWS Transform custom (Public Preview)** - Perform code upgrades, migrations, codebase analysis, and transformations using AWS Transform custom.
+
+**MCP Servers:** None
+
+---
+
 ### cloud-architect
 **Build infrastructure on AWS** - Build AWS infrastructure with CDK in Python following AWS Well-Architected framework best practices.
 
diff --git a/aws-transform-custom/POWER.md b/aws-transform-custom/POWER.md
new file mode 100644
index 0000000..29b5aa0
--- /dev/null
+++ b/aws-transform-custom/POWER.md
@@ -0,0 +1,414 @@
+---
+name: "aws-transform-custom"
+displayName: "Crush tech debt with AWS Transform custom (Public Preview)"
+description: "(Public Preview) Perform code upgrades, migrations, codebase analysis, and transformations using AWS Transform custom. Use when a user asks to upgrade, migrate, modernize, analyze, or transform code across a repository. ATX supports any-to-any transformations including language version upgrades (Java, Python, Node.js, Ruby, Go, .NET, etc.), framework upgrades and migrations (Spring Boot, React, Angular, Django, etc.), API and SDK migrations (AWS SDK v1 to v2, boto2 to boto3, JS SDK v2 to v3), library upgrades, code refactoring, architecture migrations (x86 to Graviton/ARM64), language-to-language translations, and custom organization-specific transformations. Executes transformations locally on the user's machine using the ATX CLI."
+keywords: ["transform", "transformation", "code transformation", "ATX", "AWS Transform", "AWS Transform Custom", "transformation definition", "TD", "code upgrade", "code migration", "python upgrade", "java upgrade", "nodejs upgrade", "node upgrade", "SDK migration", "AWS SDK", "boto2", "boto3", "Graviton", "ARM64", "codebase analysis", "tech debt", "modernize", "modernization", "version upgrade", "language upgrade", "framework migration", "Spring Boot", "React", "Angular", "Django", "java", "python", "nodejs", "JDK", "JDK upgrade", "code refactoring", "library upgrade", "architecture migration"]
+author: "AWS"
+---
+# AWS Transform custom
+
+## Overview
+
+Perform code upgrades, migrations, and transformations using AWS Transform Custom (ATX).
+Supports any-to-any transformations: language version upgrades (Java, Python, Node.js),
+framework migrations, AWS SDK migrations, library upgrades, code refactoring, architecture
+changes, and custom organization-specific transformations.
+
+Runs the ATX CLI directly on the user's machine.
+
+You handle the full workflow: inspecting repos, matching them to available
+transformation definitions, collecting configuration, and executing transformations
+— the user just provides repos and confirms the plan.
+
+## Usage
+
+Use when the user wants to:
+- Transform, upgrade, or migrate code (ex. Python, Java, Node.js)
+- Migrate AWS SDKs (ex. boto2→boto3, Java SDK v1→v2, JS SDK v2→v3)
+- Analyze which ATX transformations apply to their repositories
+- Create a new custom Transformation Definition (TD)
+
+## Core Concepts
+
+- **Transformation Definition (TD)**: A reusable transformation recipe discovered via `atx custom def list --json`
+- **Match Report**: Auto-generated mapping of repos to applicable TDs based on code inspection
+- **Local Mode**: Runs ATX CLI on the user's machine (max 3 concurrent)
+
+## Philosophy
+
+Wait for the user. On activation, present what this power can do and ask the user
+what they'd like to accomplish. Do NOT automatically inspect the working directory,
+open files, or any repository until the user explicitly provides repos to work with.
+
+Once the user provides repositories, match — don't ask. Inspect those repositories
+and present which transformations apply automatically. Never show a raw TD list and
+ask the user to pick.
+
+## Prerequisites
+
+Prerequisite checks run ONCE at the start of a session. Do not repeat per repo.
+Do NOT run prerequisite checks until the user has stated what they want to do.
+
+### 0. Platform Check (Required)
+
+Detect the user's operating system. If on Windows (not WSL), stop immediately and
+inform the user:
+
+> AWS Transform custom does not support native Windows. You need to install
+> Windows Subsystem for Linux (WSL) and run this from within WSL.
+>
+> Install WSL: `wsl --install` in PowerShell (as Administrator), then restart.
+> After that, open a WSL terminal and re-run this power from there.
+
+Check by running:
+```bash
+uname -s
+```
+- `Linux` or `Darwin` → proceed normally
+- `MINGW*`, `MSYS*`, `CYGWIN*`, or any Windows-like output → block and show the WSL message above
+- Command fails, errors, or is not found → treat as native Windows, block and show the WSL message above
+
+Do NOT proceed with any other steps on native Windows.
+
+### 1. AWS CLI (Required)
+
+```bash
+aws --version
+```
+
+If not installed, guide the user:
+- macOS: `brew install awscli` or `curl "https://awscli.amazonaws.com/AWSCLIV2.pkg" -o "AWSCLIV2.pkg" && sudo installer -pkg AWSCLIV2.pkg -target /`
+- Linux: `curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip" && unzip awscliv2.zip && sudo ./aws/install`
+
+Do NOT proceed until `aws --version` succeeds.
+
+### 2. AWS Credentials (Required)
+
+```bash
+aws sts get-caller-identity
+```
+
+If credentials are NOT configured, walk the user through setup:
+
+```
+AWS Transform custom requires AWS credentials to authenticate with the service. Configure authentication using one of the following methods.
+
+1. AWS CLI Configure (~/.aws/credentials):
+   aws configure
+
+2. AWS Credentials File (manual). Configure credentials in ~/.aws/credentials:
+
+[default]
+aws_access_key_id = your_access_key
+aws_secret_access_key = your_secret_key
+
+3. Environment Variables. Set the following environment variables:
+
+export AWS_ACCESS_KEY_ID=your_access_key
+export AWS_SECRET_ACCESS_KEY=your_secret_key
+export AWS_SESSION_TOKEN=your_session_token
+
+You can also specify a profile using the AWS_PROFILE environment variable:
+
+export AWS_PROFILE=your_profile_name
+```
+
+Do NOT proceed until credentials are verified. Re-run `aws sts get-caller-identity` after setup.
+
+### 3. ATX CLI (Required)
+
+Required for TD discovery (`atx custom def list --json`) and transformation execution.
+```bash
+atx --version
+# Install: curl -fsSL https://transform-cli.awsstatic.com/install.sh | bash
+```
+
+If installed, check for updates and update if available:
+```bash
+atx update
+```
+
+### 4. IAM Permissions
+
+Local mode requires `transform-custom:*` minimum. Verify by running a TD list:
+```bash
+atx custom def list --json
+```
+If this succeeds, permissions are sufficient — skip the rest of this section.
+
+If it fails with a permissions error, the caller needs the `transform-custom:*`
+IAM permission. Explain to the user what's needed and get confirmation before proceeding:
+
+> Your identity needs the `transform-custom:*` permission to use the ATX CLI.
+> I can attach the AWS-managed policy `AWSTransformCustomFullAccess` to your
+> identity. Shall I proceed?
+
+Only after the user confirms, attach the managed policy:
+```bash
+CALLER_ARN=$(aws sts get-caller-identity --query Arn --output text)
+if echo "$CALLER_ARN" | grep -q ":user/"; then
+  IDENTITY_NAME=$(echo "$CALLER_ARN" | awk -F'/' '{print $NF}')
+  aws iam attach-user-policy --user-name "$IDENTITY_NAME" \
+    --policy-arn "arn:aws:iam::aws:policy/AWSTransformCustomFullAccess"
+elif echo "$CALLER_ARN" | grep -Eq ":assumed-role/|:role/"; then
+  ROLE_NAME=$(echo "$CALLER_ARN" | sed 's/.*:\(assumed-\)\{0,1\}role\///' | cut -d'/' -f1)
+  aws iam attach-role-policy --role-name "$ROLE_NAME" \
+    --policy-arn "arn:aws:iam::aws:policy/AWSTransformCustomFullAccess"
+fi
+```
+
+If the attachment command itself fails (e.g., insufficient IAM permissions, or an
+SSO-managed role), inform the user they need to ask their AWS administrator to
+attach the `AWSTransformCustomFullAccess` AWS-managed policy to their identity.
+For SSO users (role names starting with `AWSReservedSSO_`), this must be added
+to their IAM Identity Center permission set — it cannot be attached directly.
+
+Do NOT proceed until `atx custom def list --json` succeeds.
+
+See [steering/cli-reference.md](steering/cli-reference.md) for the full permission list.
+
+## Workflow
+
+Generate a session timestamp once and reuse it for all paths in this session:
+```bash
+SESSION_TS=$(date +%Y%m%d-%H%M%S)
+```
+
+### Step 0: Greet and Wait
+
+On activation, briefly introduce what ATX can do:
+- Code upgrades and migrations (Java, Python, Node.js version upgrades)
+- AWS SDK migrations (boto2→boto3, Java SDK v1→v2, JS SDK v2→v3)
+- Framework migrations, library upgrades, code refactoring
+- Codebase analysis and documentation generation
+- Local execution (max 3 concurrent repos)
+
+Then ask the user what they'd like to do. Do NOT inspect any files, run any
+commands, or check prerequisites until the user responds.
+
+### Step 1: Collect Repositories
+
+Ask the user for local paths or git URLs. Accept one or many. Do NOT assume the
+current working directory or open editor files are the target — wait for the user
+to explicitly provide repositories.
+
+Accepted source formats:
+- **Local paths** — directories on the user's machine (e.g., `/home/user/my-project`)
+- **HTTPS git URLs** — public or private (e.g., `https://github.com/org/repo.git`)
+- **SSH git URLs** — e.g., `git@github.com:org/repo.git`
+- **S3 bucket path with zips** — e.g., `s3://my-bucket/repos/`
+  containing zip files of repositories. Each zip becomes one transformation job.
+
+#### S3 Bucket Input
+
+If the user provides an S3 path containing zip files, download and extract each zip locally:
+```bash
+mkdir -p ~/.aws/atx/custom/atx-agent-session/repos
+aws s3 sync s3://user-bucket/repos/ ~/.aws/atx/custom/atx-agent-session/repos/ --exclude "*" --include "*.zip"
+for zip in ~/.aws/atx/custom/atx-agent-session/repos/*.zip; do
+  name=$(basename "$zip" .zip)
+  unzip -qo "$zip" -d "$HOME/.aws/atx/custom/atx-agent-session/repos/${name}-$SESSION_TS/"
+done
+```
+Use the extracted directories as `<repo-path>` for local execution. Standard local
+mode limits apply (max 3 concurrent repos).
+
+### Step 2: Discover TDs (Silent)
+
+Run silently — do NOT show output to user:
+```bash
+atx custom def list --json
+```
+Build an internal lookup of available TDs. Never hardcode TD names.
+
+#### Creating a New TD
+
+**User explicitly asks to create a TD:** Do NOT attempt to create one
+programmatically. Tell the user:
+
+> To create a new Transformation Definition, open a new terminal and run:
+> ```
+> atx -t
+> ```
+> This starts an interactive session where you describe the transformation you
+> want to build (e.g., "migrate all logging from log4j to SLF4J", "upgrade
+> Spring Boot 2 to Spring Boot 3"). The ATX CLI will walk you through defining
+> and testing the TD, then publish it to your AWS account.
+>
+> Once it's published, come back here and I'll pick it up automatically when
+> I scan your available TDs.
+
+**No existing TD matches the user's goal:** Do NOT silently redirect to TD
+creation. The match logic may be imperfect. Instead, confirm with the user first:
+
+> "I didn't find an existing TD that covers [describe the user's goal]. Would
+> you like to create a new one?"
+
+Only show the `atx -t` instructions if the user confirms. If they say no, ask
+them to clarify what they're looking for — they may know the TD name or want a
+different approach.
+
+Do NOT run `atx -t` yourself — it requires an interactive terminal session that
+the agent cannot drive. The user must run it manually in a separate terminal.
+
+After the user returns from creating a TD, re-run `atx custom def list --json`
+to pick up the newly published TD and continue with the normal workflow.
+
+### Step 3: Inspect Each Repository
+
+Perform lightweight inspection only — check config files for key signals:
+
+| Signal | Files to Check | Likely TD Type |
+|--------|---------------|----------------|
+| Python version | `.python-version`, `pyproject.toml`, `setup.cfg`, `requirements.txt` | Python version upgrade |
+| Java version | `pom.xml` (`<java.version>`), `build.gradle` (`sourceCompatibility`), `.java-version` | Java version upgrade |
+| Node.js version | `package.json` (`engines.node`), `.nvmrc`, `.node-version` | Node.js version upgrade |
+| Python boto2 | `import boto` (NOT boto3) | boto2→boto3 migration |
+| Java SDK v1 | `com.amazonaws` imports, `aws-java-sdk` in pom.xml | Java SDK v1→v2 |
+| Node.js SDK v2 | `"aws-sdk"` in package.json (NOT `@aws-sdk`) | JS SDK v2→v3 |
+| x86 Java | `x86_64`/`amd64` in Dockerfiles, build configs | Graviton migration |
+
+Cross-reference detected signals against TDs from Step 2. Only match TDs that
+actually exist in the user's account.
+
+See [steering/repo-analysis.md](steering/repo-analysis.md) for full detection commands.
+
+### Step 4: Present Match Report
+
+Format:
+```
+Transformation Match Report
+=============================
+Repository: <name> (<path>)
+  Language: <lang> <version>
+  Matching TDs:
+    - <td-name> — <description>
+
+Summary: N repos analyzed, M have applicable transformations (T total jobs)
+```
+
+Offer to kick off transformations.
+
+### Step 5: Collect Configuration
+
+Ask for TD-specific config only when needed (e.g., target version for upgrade TDs).
+Skip for TDs that need no config.
+
+### Step 6: Verify Runtime Compatibility
+
+Before running local transformations, verify the user has the target runtime
+version installed. This applies to any language or runtime the transformation
+targets — Java, Python, Node.js, Ruby, Go, Rust, .NET, etc. Check the current
+version of whatever runtime the TD requires. For example:
+```bash
+java -version    # Java transformations
+python3 --version # Python transformations
+node --version   # Node.js transformations
+ruby --version   # Ruby transformations
+go version       # Go transformations
+```
+
+If the target version is not active, check whether it's already installed:
+```bash
+# Java: check common install locations
+/usr/libexec/java_home -V 2>&1          # macOS
+ls /usr/lib/jvm/ 2>/dev/null            # Linux
+# Python: check if the specific version binary exists
+which python3.12 2>/dev/null            # adjust version as needed
+# Node.js: check if nvm is available, or look for the binary
+command -v nvm &>/dev/null && nvm ls 2>/dev/null
+which node 2>/dev/null && node --version
+```
+
+If the target version is found, switch to it:
+- Java: `sdk use java 23-amzn` or `export JAVA_HOME=/usr/lib/jvm/java-23-amazon-corretto.x86_64 && export PATH="$JAVA_HOME/bin:$PATH"`
+- Python: `pyenv shell 3.15.0`
+- Node.js: `nvm use 23`
+
+Only if the target version is not installed at all, ask the user for permission before installing. Do NOT install runtimes without explicit user confirmation.
+Suggest the appropriate version manager:
+- Java: `sdk install java 23-amzn` (SDKMAN), or `brew install --cask corretto23` (macOS)
+- Python: `pyenv install 3.15.0 && pyenv shell 3.15.0`, or `brew install python@3.15`
+- Node.js: `nvm install 23 && nvm use 23`
+
+The active runtime must match the transformation's target version so that builds
+and tests run correctly. Do NOT proceed with the transformation until the correct
+version is active.
+
+### Step 7: Confirm Transformation Plan
+
+Present final plan with repo, TD, and config. Do NOT proceed
+until user confirms.
+
+### Step 8: Execute
+
+- **1 repo**: See [steering/single-transformation.md](steering/single-transformation.md)
+- **Multiple repos**: See [steering/multi-transformation.md](steering/multi-transformation.md)
+
+## Critical Rules
+
+1. **Discover TDs dynamically** — Always run `atx custom def list --json`. Never hardcode TD names.
+2. **Match, don't ask** — Inspect repos and present matches. Never show raw TD lists.
+3. **Lightweight inspection only** — Check config files and key signals. No deep analysis.
+4. **Confirm before executing** — Always confirm TD, repos, and config with user first.
+5. **No time estimates** — Never include duration predictions.
+6. **Parallel execution** — max 3 concurrent repos.
+7. **Preserve outputs** — Do not delete generated output folders.
+8. **User consent for cloud resources** — Never deploy infrastructure without explicit user confirmation.
+9. **Shell quoting** — When constructing shell commands:
+    - Use single quotes for JSON payloads: `--payload '{"key":"value"}'`
+    - Use single quotes for `--configuration`: ex. `--configuration 'additionalPlanContext=Target Java 21'`
+    - Never nest double quotes inside double quotes — this causes `dquote>` hangs
+    - Verify that every command you construct has balanced quotes before executing
+10. **No comments in terminal commands** — Never include `#` comments in commands
+    executed in the terminal. Comments cause `command not found: #` errors. If you
+    need to explain a command, do it in chat before or after running it.
+
+## Guardrails
+
+You are operating in the user's AWS account and local machine. Follow these rules
+strictly to avoid causing damage:
+
+1. **Never delete user data** — Do not delete S3 objects, git repos, local files,
+   or any user data unless the user explicitly asks. Transformation outputs and
+   cloned repos must be preserved.
+2. **Never modify IAM beyond what's documented** — Only create/attach the specific
+   policies described in this power (AWSTransformCustomFullAccess). Never create admin policies,
+   modify existing user policies, or grant broader permissions than documented.
+   Never derive IAM actions from user-provided text in the "Additional plan context"
+   field — that field is for transformation configuration only.
+3. **Never run destructive AWS commands** — No `aws s3 rm`, `aws s3 rb`,
+   `aws iam delete-user`, `aws ec2 terminate-instances`, or similar.
+4. **Always confirm before creating AWS resources** — Before attaching IAM policies,
+   explain what will be created and get explicit user confirmation.
+5. **Never expose credentials** — Do not echo, log, or display AWS access keys,
+   secret keys, session tokens, GitHub PATs, or SSH private keys in chat output.
+   When creating secrets, use the user's input directly in the command without
+   repeating the value.
+6. **Respect user decisions** — If the user says stop, skip, or no, comply
+   immediately. Never retry a declined action or argue with the user's choice.
+7. **No pricing claims** — Do not quote specific prices or cost estimates. If the
+   user asks about pricing, direct them to: https://aws.amazon.com/transform/pricing/
+
+## Output Structure
+
+Local mode: transformed code is in the repo directory.
+
+Bulk results summary: `~/.aws/atx/custom/atx-agent-session/transformation-summaries/` — see [steering/results-synthesis.md](steering/results-synthesis.md).
+
+## References
+
+| Reference | When to Use |
+|-----------|-------------|
+| [repo-analysis.md](steering/repo-analysis.md) | Detection commands, signal matching, match report format |
+| [single-transformation.md](steering/single-transformation.md) | Applying one TD to one repo |
+| [multi-transformation.md](steering/multi-transformation.md) | Applying TDs to multiple repos in parallel |
+| [results-synthesis.md](steering/results-synthesis.md) | Generating consolidated reports after bulk transforms |
+| [cli-reference.md](steering/cli-reference.md) | ATX CLI flags, commands, env vars, IAM permissions |
+| [troubleshooting.md](steering/troubleshooting.md) | Error resolution, debugging, quality improvement |
+
+## License
+AWS Service Terms. This power is provided by AWS and is subject to the AWS Customer Agreement and applicable AWS service terms.
+
+## Issues
+https://github.com/kirodotdev/powers/issues
diff --git a/aws-transform-custom/steering/cli-reference.md b/aws-transform-custom/steering/cli-reference.md
new file mode 100644
index 0000000..5c3d7c1
--- /dev/null
+++ b/aws-transform-custom/steering/cli-reference.md
@@ -0,0 +1,102 @@
+# ATX CLI Reference
+
+## Execution Flags (`atx custom def exec`)
+
+| Flag | Long Form | Description |
+|------|-----------|-------------|
+| `-n` | `--transformation-name <name>` | TD name (from `atx custom def list --json`) |
+| `-p` | `--code-repository-path <path>` | Path to code repo (`.` for current dir) |
+| `-c` | `--build-command <cmd>` | Build/validation command (optional, auto-detected) |
+| `-x` | `--non-interactive` | No user prompts |
+| `-t` | `--trust-all-tools` | Auto-approve tool executions (required with `-x`) |
+| `-d` | `--do-not-learn` | Prevent knowledge item extraction |
+| `-g` | `--configuration <config>` | Config file (`file://config.yaml`) or inline (`'key=val'`) |
+| `--tv` | `--transformation-version <ver>` | Specific TD version |
+
+## Build Commands
+
+| Language | Command | Notes |
+|----------|---------|-------|
+| Java (Maven) | `mvn clean install` | Most common |
+| Java (Gradle) | `gradle clean build` | Alternative |
+| Python | `pytest` | Or `python -m pytest` |
+| Node.js | `npm run build` or `npm test` | Framework-dependent |
+
+`-c` is optional. ATX auto-detects from project files. Include when auto-detection
+may fail or a specific command is needed.
+
+Best practices for build commands:
+- Use a deterministic, specific command that returns errors on failure
+- Even non-compiled languages benefit from linters, test runners, or formatters
+- If no building is needed, use `"noop"`
+- If the build command is not `"noop"`, verify the command works locally before passing it to ATX
+
+## Configuration
+
+Inline: `--configuration 'additionalPlanContext=Target Python 3.13'`
+
+YAML file:
+```yaml
+transformationName: AWS/java-version-upgrade
+buildCommand: mvn clean install
+additionalPlanContext: |
+  Target Java 17. Ensure compatibility with internal logging.
+```
+Usage: `atx custom def exec -g file://config.yaml -x -t`
+
+`--configuration` is optional. Omit if no extra context needed.
+
+## Other Commands
+
+| Action | Command |
+|--------|---------|
+| Start interactive conversation | `atx` |
+| Resume most recent conversation | `atx --resume` |
+| Resume specific conversation | `atx --conversation-id <id>` (30-day limit) |
+| List TDs | `atx custom def list --json` |
+| Download TD | `atx custom def get -n <name>` (optional: `--tv <version>`, `--td <directory>`) |
+| Delete TD | `atx custom def delete -n <name>` |
+| Save TD as draft | `atx custom def save-draft -n <name> --description "<desc>" --sd <dir>` |
+| Publish TD | `atx custom def publish -n <name> --description "<desc>" --sd <dir>` |
+| List knowledge items | `atx custom def list-ki -n <name>` |
+| View knowledge item | `atx custom def get-ki -n <name> --id <id>` |
+| Enable/disable KI | `atx custom def update-ki-status -n <name> --id <id> --status ENABLED or DISABLED` |
+| KI auto-approval on/off | `atx custom def update-ki-config -n <name> --auto-enabled TRUE or FALSE` |
+| Export KIs | `atx custom def export-ki-markdown -n <name>` |
+| Delete KI | `atx custom def delete-ki -n <name> --id <id>` |
+| Update CLI | `atx update` |
+| Check for CLI updates only | `atx update --check` |
+| Tag a TD | `atx custom def tag --arn <arn> --tags '{"key":"value"}'` |
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `ATX_SHELL_TIMEOUT` | 900 (15 min) | Shell command timeout in seconds |
+| `ATX_DISABLE_UPDATE_CHECK` | false | Disable version check |
+| `AWS_PROFILE` | — | AWS credentials profile |
+| `AWS_ACCESS_KEY_ID` | — | AWS access key |
+| `AWS_SECRET_ACCESS_KEY` | — | AWS secret key |
+| `AWS_SESSION_TOKEN` | — | Session token (temporary credentials) |
+
+## IAM Permissions
+
+Minimum: `transform-custom:*` on `Resource: "*"`.
+
+| Permission | Operation |
+|-----------|----------|
+| `transform-custom:ConverseStream` | Interactive conversations |
+| `transform-custom:ExecuteTransformation` | Execute transforms |
+| `transform-custom:ListTransformationPackageMetadata` | List transforms (`atx custom def list --json`) |
+| `transform-custom:DeleteTransformationPackage` | Delete transforms |
+| `transform-custom:CompleteTransformationPackageUpload` | Upload TDs |
+| `transform-custom:CreateTransformationPackageUrl` | Create upload URLs |
+| `transform-custom:GetTransformationPackageUrl` | Download TDs |
+| `transform-custom:ListKnowledgeItems` | List knowledge items |
+| `transform-custom:GetKnowledgeItem` | View knowledge item details |
+| `transform-custom:DeleteKnowledgeItem` | Delete knowledge items |
+| `transform-custom:UpdateKnowledgeItemConfiguration` | Configure auto-approval |
+| `transform-custom:UpdateKnowledgeItemStatus` | Enable/disable items |
+| `transform-custom:ListTagsForResource` | List tags |
+| `transform-custom:TagResource` | Add tags |
+| `transform-custom:UntagResource` | Remove tags |
diff --git a/aws-transform-custom/steering/multi-transformation.md b/aws-transform-custom/steering/multi-transformation.md
new file mode 100644
index 0000000..dcdb852
--- /dev/null
+++ b/aws-transform-custom/steering/multi-transformation.md
@@ -0,0 +1,143 @@
+# Multi-Transformation
+
+Apply TDs to multiple repositories in parallel. TD-to-repo assignments and config
+are already confirmed from the match report. Do NOT re-discover TDs or re-prompt.
+
+## Input
+
+From the match report: repo list, TD per repo, config per TD.
+
+## Prerequisite Check (Once Only)
+
+Verify AWS credentials ONCE. Do NOT repeat per repo.
+```bash
+aws sts get-caller-identity
+```
+Also: `atx --version`
+
+If any repos were provided as git URLs (HTTPS or SSH), clone them locally first.
+The user's local git config handles authentication — no Secrets Manager needed.
+```bash
+CLONE_DIR=~/.aws/atx/custom/atx-agent-session/repos/<repo-name>-$SESSION_TS
+git clone <git-url> "$CLONE_DIR"
+```
+
+If repos were provided as an S3 bucket path with zips, download and extract locally:
+```bash
+mkdir -p ~/.aws/atx/custom/atx-agent-session/repos
+aws s3 sync s3://user-bucket/repos/ ~/.aws/atx/custom/atx-agent-session/repos/ --exclude "*" --include "*.zip"
+for zip in ~/.aws/atx/custom/atx-agent-session/repos/*.zip; do
+  name=$(basename "$zip" .zip)
+  unzip -qo "$zip" -d "$HOME/.aws/atx/custom/atx-agent-session/repos/${name}-$SESSION_TS/"
+done
+```
+
+Use the cloned/extracted paths as `<repo-path>` for each repo.
+
+For each repo, verify it's a git repo:
+```bash
+ls -la <repo-path>
+git -C <repo-path> status
+```
+If not a git repo: `cd <repo-path> && git init && git add . && git commit -m "Initial commit"`
+
+The active language runtime must match the transformation's target version so that
+builds and tests run correctly. Check the current version, and if there is a
+mismatch, first check whether the target version is already installed (e.g.,
+`sdk list java | grep installed`, `pyenv versions`, `nvm ls`). If found, switch
+to it (e.g., `sdk use java 23-amzn`, `pyenv shell 3.12`, `nvm use 22`). Only if
+the target version is not installed at all, ask the user for permission before installing. Suggest:
+- Java: `sdk install java 23-amzn` (SDKMAN), or `brew install --cask corretto23` (macOS)
+- Python: `pyenv install 3.15.0 && pyenv shell 3.15.0`
+- Node.js: `nvm install 23 && nvm use 23`
+
+Do NOT proceed until the correct version is active. Verify the switch succeeded
+before proceeding.
+
+Run transformations in parallel — maximum 3 concurrent repos at a time (the user
+can override this, but 3 is recommended to avoid overloading the machine). If there
+are more than 3 repos, process them in batches of 3 (wait for a batch to finish
+before starting the next).
+
+For each repo, use bash to create a runner script that captures the exit code:
+```bash
+mkdir -p ~/.aws/atx/custom/atx-agent-session
+cat > ~/.aws/atx/custom/atx-agent-session/run-<repo-name>.sh << 'RUNNER'
+#!/bin/bash
+atx custom def exec -n <td-name> -p <repo-path> -x -t \
+  --configuration 'additionalPlanContext=<config>'
+echo $? > ~/.aws/atx/custom/atx-agent-session/<repo-name>.exit
+RUNNER
+chmod +x ~/.aws/atx/custom/atx-agent-session/run-<repo-name>.sh
+nohup ~/.aws/atx/custom/atx-agent-session/run-<repo-name>.sh > ~/.aws/atx/custom/atx-agent-session/<repo-name>.log 2>&1 &
+echo $! > ~/.aws/atx/custom/atx-agent-session/<repo-name>.pid
+```
+Omit `--configuration` if no config needed. Launch each repo's script in rapid
+succession — do NOT wait between launches. Each runner script is backgrounded
+via nohup; the exit code is captured to `~/.aws/atx/custom/atx-agent-session/<repo-name>.exit` when ATX finishes.
+
+After launching all repos, find each repo's conversation log by grepping its
+process log (ATX outputs the path within 30-60 seconds of starting):
+```bash
+grep "Conversation log:" ~/.aws/atx/custom/atx-agent-session/<repo-name>.log 2>/dev/null
+```
+If it hasn't appeared yet, wait 15 seconds and retry. Extract the full path from
+each — do NOT use `ls -t` across all conversations, as that may match a different run.
+
+Then start monitoring. On each 60-second cycle:
+1. Check each PID: `kill -0 $(cat ~/.aws/atx/custom/atx-agent-session/<repo-name>.pid) 2>/dev/null && echo "RUNNING" || echo "DONE"`
+2. Tail each repo's conversation log and relay progress to the user
+3. For each repo, check the artifacts directory (`~/.aws/atx/custom/<conversation-id>/artifacts/`)
+   and open files with `kiro -r <filepath>` as they appear (open each file only once):
+   - `plan.json` — the transformation plan (appears after planning phase completes)
+   - `worklog.log` — the execution log (appears shortly after plan.json)
+   - `validation_summary.md` — open after the repo's process exits
+4. Report which repos are still running, which have completed
+
+**You MUST continue polling without waiting for user input.** The user should see
+continuous progress updates across all repos.
+
+## Progress Reporting
+
+```
+[1/N] repo-name          TD-name                    Status
+[2/N] repo-name          TD-name                    Status
+```
+
+## Result Collection
+
+Collect per repo: success/failure, transformed code path, error details.
+```
+Succeeded:
+- repo-name: TD-name (config)
+Failed:
+- repo-name: TD-name (error)
+```
+
+Hand off to [results-synthesis.md](results-synthesis.md) for consolidated reporting.
+
+Tell the user: "To review changes in each repo, open it in Kiro (`kiro -r <repo-path>`)
+and use the Source Control panel to see the full commit history with diffs for
+each file ATX modified."
+
+## Error Handling
+
+| Scenario | Action |
+|----------|--------|
+| Git clone fails | Log error, continue with remaining repos |
+| Transformation fails | Log repo and error, do not auto-retry |
+| Partial results | Generate summary from successes, report failures |
+
+## Cleanup
+
+Clean up session files automatically:
+```bash
+[ -d ~/.aws/atx/custom/atx-agent-session ] && find ~/.aws/atx/custom/atx-agent-session -maxdepth 1 -type f \( -name "*.sh" -o -name "*.log" -o -name "*.pid" -o -name "*.exit" -o -name "*.zip" \) -delete 2>/dev/null || true
+```
+
+## Key Principles
+
+1. Single prerequisite check — never repeat for parallel tasks
+2. Trust the match report — do not re-discover TDs
+3. Local parallel execution — maximum 3 concurrent repos (user-overridable)
+4. Skip prerequisite checks in parallel task prompts
diff --git a/aws-transform-custom/steering/repo-analysis.md b/aws-transform-custom/steering/repo-analysis.md
new file mode 100644
index 0000000..87af0a9
--- /dev/null
+++ b/aws-transform-custom/steering/repo-analysis.md
@@ -0,0 +1,129 @@
+# Repo Analysis & TD Matching
+
+Inspect repositories and match them against available Transformation Definitions.
+
+## TD Discovery (Required First Step)
+
+```bash
+atx custom def list          # Human-readable
+atx custom def list --json   # Programmatic parsing
+```
+
+Never hardcode TD names. Only match repos against TDs that appear in this output.
+If `atx` is not installed, install it first — do not fall back to guessed names.
+
+## Known AWS-Managed TDs (Reference Only)
+
+This table is a guide for signal detection, NOT a substitute for `atx custom def list --json`.
+TD names change over time. Always use actual names from the live output.
+
+| TD Name (may change) | Description | Key Config |
+|---------|-------------|------------|
+| `AWS/java-version-upgrade` | Upgrade Java/JDK version (any source → any target) | Target JDK version (e.g., 17, 21) |
+| `AWS/python-version-upgrade` | Upgrade Python version (3.8/3.9 → 3.11/3.12/3.13) | Target Python version |
+| `AWS/nodejs-version-upgrade` | Upgrade Node.js version (any source → any target) | Target Node.js version |
+| `AWS/java-aws-sdk-v1-to-v2` | Migrate AWS SDK for Java v1 → v2 (Maven or Gradle) | None required |
+| `AWS/python-boto2-to-boto3` | Migrate Python boto2 → boto3 | None required |
+| `AWS/nodejs-aws-sdk-v2-to-v3` | Migrate AWS SDK for JavaScript v2 → v3 | None required |
+| `AWS/early-access-java-x86-to-graviton` | Migrate Java x86 code to ARM64/Graviton | None required |
+| `AWS/early-access-comprehensive-codebase-analysis` | Tech debt analysis + documentation generation | Optional: `additionalPlanContext` for focus area |
+
+## Transformation Patterns
+
+| Pattern | Complexity | Examples |
+|---------|-----------|----------|
+| Language Version Upgrades | Low-Medium | Java 8→17, Python 3.9→3.13, Node.js 12→22 |
+| API and Service Migrations | Medium | AWS SDK v1→v2, Boto2→Boto3, JUnit 4→5, javax→jakarta |
+| Framework Upgrades | Medium | Spring Boot 2.x→3.x, React 17→18, Angular, Django |
+| Framework Migrations | High | Angular→React, Redux→Zustand, Vue.js→React |
+| Library and Dependency Upgrades | Low-Medium | Pandas 1.x→2.x, NumPy, Hadoop/HBase/Hive |
+| Code Refactoring | Low-Medium | Print→Logging, string concat→f-strings, type hints |
+| Script/File Translations | Low-Medium | CDK→Terraform, Terraform→CloudFormation, Bash→PowerShell |
+| Architecture Migrations | Medium-High | x86→Graviton, on-prem→Lambda, server→containers |
+| Language-to-Language Migrations | Very High | Java→Python, JavaScript→TypeScript, C→Rust |
+| Custom/Org-Specific | Varies | Internal library migrations, coding standards enforcement |
+
+Service routing: COBOL/mainframe → use AWS Transform for Mainframe. .NET Framework → consider AWS Transform for Windows. VMware → consider AWS Transform for VMware.
+
+## Detection Commands
+
+### Python
+```bash
+cat <repo>/.python-version 2>/dev/null
+cat <repo>/pyproject.toml 2>/dev/null | head -30
+cat <repo>/setup.cfg 2>/dev/null | head -30
+cat <repo>/requirements.txt 2>/dev/null | head -10
+```
+
+### Java
+```bash
+cat <repo>/pom.xml 2>/dev/null | head -60       # Look for <java.version>, <maven.compiler.source>
+cat <repo>/build.gradle 2>/dev/null | head -40   # Look for sourceCompatibility
+cat <repo>/.java-version 2>/dev/null
+```
+
+### Node.js
+```bash
+cat <repo>/package.json 2>/dev/null              # Look for engines.node
+cat <repo>/.nvmrc 2>/dev/null
+cat <repo>/.node-version 2>/dev/null
+```
+
+## AWS SDK Detection
+
+| Signal | Language | What It Means |
+|--------|----------|---------------|
+| `import boto` / `from boto` (NOT boto3) | Python | Legacy boto2 — needs migration |
+| `com.amazonaws` or `aws-java-sdk` in pom.xml | Java | SDK v1 — needs migration |
+| `"aws-sdk"` in package.json (NOT `@aws-sdk`) | Node.js | SDK v2 — needs migration |
+
+```bash
+# Python boto2
+grep -rlE "import boto([^3]|$)|from boto([^3]|$)" <repo> --include="*.py" 2>/dev/null | head -3
+# Java SDK v1
+grep -rl "com.amazonaws" <repo> --include="*.java" 2>/dev/null | head -3
+cat <repo>/pom.xml 2>/dev/null | grep -i "aws-java-sdk"
+# Node.js SDK v2
+cat <repo>/package.json 2>/dev/null | grep '"aws-sdk"'
+```
+
+## Graviton Detection
+
+```bash
+grep -rlE "x86_64|amd64|x86-64" <repo> --include="*.yml" --include="*.yaml" --include="Dockerfile" 2>/dev/null | head -3
+```
+
+Currently Java-only. Match against Graviton migration TD if available.
+
+## Match Report Format
+
+```
+Transformation Match Report
+=============================
+Repository: <name> (<path>)
+  Language: <lang> <version>
+  Matching TDs:
+    - <td-name> — <description>
+
+  Other available TDs (may also apply):
+    - <custom-td> — <description>
+
+Summary: N repos analyzed, M have matches (T total jobs)
+```
+
+Group by repository. Show detected version. Include repos with no matches.
+List custom TDs (non-`AWS/` prefix) under "Other available TDs".
+
+## Edge Cases
+
+| Case | Handling |
+|------|----------|
+| Repo already up-to-date | List upgrade TD but note current version |
+| Monorepo (multiple languages) | List all matching TDs — each is a separate job |
+| Custom TDs in account | Show under "Other available TDs" per repo |
+| Git clone fails | Report error, continue with remaining repos |
+
+## Cleanup
+
+Do NOT delete cloned repos after analysis — they are needed for local execution.
+Track cloned repo paths and inform the user at session end so they can delete them.
diff --git a/aws-transform-custom/steering/results-synthesis.md b/aws-transform-custom/steering/results-synthesis.md
new file mode 100644
index 0000000..31c0506
--- /dev/null
+++ b/aws-transform-custom/steering/results-synthesis.md
@@ -0,0 +1,45 @@
+# Results Synthesis
+
+Generate a single summary file after bulk transformations complete.
+
+## Output
+
+Write one file: `~/.aws/atx/custom/atx-agent-session/transformation-summaries/transformation-summary-$SESSION_TS.md`
+
+```bash
+mkdir -p ~/.aws/atx/custom/atx-agent-session/transformation-summaries
+```
+
+**Important:** Do NOT use heredoc (`cat << EOF`) to write this file — heredoc
+blocks can hang in shell environments. Use a command (ex. `printf '%s'`) to write the content.
+
+## Template
+
+```markdown
+# ATX Transformation Summary
+> Completed: <timestamp>
+> Repositories: <total> | Succeeded: <count> | Failed: <count>
+
+## Results
+| Project | TD | Status | Notes |
+|---------|-----|--------|-------|
+| <name> | <td> | Succeeded/Failed | <brief note> |
+
+## Failed Transformations
+### <project-name>
+- **TD**: <td-name>
+- **Error**: <one-line error summary>
+- **Suggested Fix**: <recommendation>
+
+## Next Steps
+1. Review changes in each transformed repo
+2. Run tests and deploy
+```
+
+## Presentation
+
+Tell the user:
+```
+Results: <succeeded>/<total> succeeded, <failed> failed
+Summary: ~/.aws/atx/custom/atx-agent-session/transformation-summaries/transformation-summary-$SESSION_TS.md
+```
diff --git a/aws-transform-custom/steering/single-transformation.md b/aws-transform-custom/steering/single-transformation.md
new file mode 100644
index 0000000..109cf56
--- /dev/null
+++ b/aws-transform-custom/steering/single-transformation.md
@@ -0,0 +1,192 @@
+# Single Transformation
+
+Apply one TD to one repo. TD, config, and repo are already confirmed from the match report.
+
+### 1. Verify ATX (once per session, skip if already verified)
+```bash
+atx --version
+```
+
+### 2. Verify Language Version
+The active language runtime must match the transformation's target version so that builds and tests run correctly. For example, a Java 8 → 17 upgrade needs Java 17 available locally.
+
+Check the installed version matches the target:
+```bash
+java -version    # Java transformations
+python3 --version # Python transformations
+node --version   # Node.js transformations
+```
+If there is a mismatch, resolve it before proceeding:
+- Look for the correct version already installed (e.g., check `/usr/lib/jvm/`, `pyenv versions`, `nvm ls`)
+- If found, switch to it (e.g., `sdk use java 17`, `pyenv shell 3.12`, `nvm use 22`)
+- If not installed, ask the user for permission before installing. Suggest the appropriate version manager (e.g., `sdk install java 17`, `pyenv install 3.12`, `nvm install 22`)
+- Verify the switch succeeded by re-checking the version before continuing
+
+### 3. Prepare Source
+
+If the user provided a git URL (HTTPS or SSH) instead of a local path, clone it
+locally first. The user's local git config handles authentication for private repos
+— no Secrets Manager setup needed in local mode.
+
+```bash
+CLONE_DIR=~/.aws/atx/custom/atx-agent-session/repos/<repo-name>-$SESSION_TS
+git clone <git-url> "$CLONE_DIR"
+```
+
+If the user provided an S3 path to a zip, download and extract it locally:
+```bash
+aws s3 cp s3://user-bucket/repos/<project>.zip ~/.aws/atx/custom/atx-agent-session/<project>-$SESSION_TS.zip
+mkdir -p ~/.aws/atx/custom/atx-agent-session/repos/<project>
+unzip -qo ~/.aws/atx/custom/atx-agent-session/<project>-$SESSION_TS.zip -d ~/.aws/atx/custom/atx-agent-session/repos/<project>-$SESSION_TS/
+```
+
+Use the cloned/extracted path as `<repo-path>` for all subsequent steps. If the
+user provided a local path, use it directly.
+
+### 4. Validate Repository
+```bash
+ls -la <repo-path>
+git -C <repo-path> status
+```
+If not a git repo: `cd <repo-path> && git init && git add . && git commit -m "Initial commit"`
+
+### 5. Execute and Monitor
+
+Launch the transformation in a way that returns control immediately. Some shell
+tools block until all child processes exit, even with `&`. To avoid this, use bash to write
+a launcher script and execute it:
+
+```bash
+mkdir -p ~/.aws/atx/custom/atx-agent-session
+cat > ~/.aws/atx/custom/atx-agent-session/run.sh << 'RUNNER'
+#!/bin/bash
+atx custom def exec -n <td-name> -p <repo-path> -x -t \
+  --configuration 'additionalPlanContext=<user-config>'
+echo $? > ~/.aws/atx/custom/atx-agent-session/transform.exit
+RUNNER
+chmod +x ~/.aws/atx/custom/atx-agent-session/run.sh
+nohup ~/.aws/atx/custom/atx-agent-session/run.sh > ~/.aws/atx/custom/atx-agent-session/transform.log 2>&1 &
+echo $! > ~/.aws/atx/custom/atx-agent-session/transform.pid
+cat ~/.aws/atx/custom/atx-agent-session/transform.pid
+```
+Omit `--configuration` if no config is needed.
+
+This backgrounds the runner script (not ATX directly), so the exit code is
+captured to `~/.aws/atx/custom/atx-agent-session/transform.exit` when ATX finishes. The PID file tracks
+the runner process.
+
+**As soon as you have the PID, immediately run the next command** — do NOT stop
+and wait for the user. The ATX CLI outputs the conversation log path within
+30-60 seconds of starting. Read it from the process log:
+```bash
+grep "Conversation log:" ~/.aws/atx/custom/atx-agent-session/transform.log 2>/dev/null
+```
+If it hasn't appeared yet, wait 15 seconds and retry (up to 4 attempts). The
+output looks like:
+```
+Conversation log: /Users/<user>/.aws/atx/custom/20260319_063712_e3479843/logs/2026-03-19T06-37-26-conversation.log
+```
+Extract the full path from this line — this is the conversation log for THIS
+specific run. Do NOT use `ls -t` to find the most recent log across all
+conversations, as that may return a log from a previous run.
+
+Then start a monitoring loop. On each cycle:
+1. Check if the process is still running: `kill -0 $(cat ~/.aws/atx/custom/atx-agent-session/transform.pid) 2>/dev/null && echo "RUNNING" || echo "DONE"`
+2. Read the latest lines from the conversation log and tell the user what's happening
+3. Wait 60 seconds, then repeat
+
+**You MUST continue polling without waiting for user input.** After each poll,
+immediately schedule the next one. The user should see continuous progress updates
+like "ATX is planning changes...", "Applying changes to 3 files...", "Running build...".
+
+CRITICAL rules:
+
+1. **Extract conversation ID and log path.** After launching the process, look for
+   the conversation log line in stdout:
+   ```
+   📝 Conversation log: /Users/<user>/.aws/atx/custom/<conversation-id>/logs/<timestamp>-conversation.log
+   ```
+   Extract the `<conversation-id>` (e.g., `20260311_233325_21bb5ef0`) and the full
+   log file path. Report the conversation ID to the user immediately. Example:
+   "Transformation started — conversation ID: `20260311_233325_21bb5ef0`"
+
+2. **Tail the conversation log.** Once the log path is known, read new lines from
+   the conversation log on each polling cycle and relay meaningful progress to the
+   user. This is the primary way to keep the user informed of what ATX is doing
+   (e.g., planning steps, applying changes, running builds, encountering errors).
+
+3. **Filter out noise.** When reading the conversation log or process stdout,
+   silently IGNORE any lines containing "Thinking" — these are animated spinner
+   indicators that repeat dozens of times and must NOT be echoed to the user.
+   Surface everything else: planning output, file changes, build results, errors,
+   and completion summaries.
+
+4. **Completion = process exit only.** The transformation is done ONLY when the
+   background process exits. Check the process exit code — do NOT parse terminal
+   output or log content to determine completion. ATX prints progress messages
+   and spinner animations throughout execution that do NOT indicate completion.
+
+5. **Polling interval.** Check the background process status and tail the
+   conversation log every 60 seconds. Do NOT use escalating backoff for local
+   mode — a fixed 60-second interval is sufficient. Do NOT sleep in the foreground
+   terminal.
+
+6. **Exit code determines success.** Once `kill -0` confirms the process has
+   exited, read the exit code: `cat ~/.aws/atx/custom/atx-agent-session/transform.exit`. Exit code 0 =
+   success. Non-zero = failure. Only after reading the exit code should you
+   report the transformation as complete or failed.
+
+7. **Open artifacts in the IDE.** Using the conversation ID from rule #1, the
+   artifacts directory is `~/.aws/atx/custom/<conversation-id>/artifacts/`.
+   During each polling cycle, check whether each file exists and open it as
+   soon as it appears. Open each file only once — track which ones you've
+   already opened.
+
+   Check and open during polling:
+   ```bash
+   ARTIFACTS_DIR=~/.aws/atx/custom/<conversation-id>/artifacts
+   test -f "$ARTIFACTS_DIR/plan.json" && echo "PLAN_READY"
+   test -f "$ARTIFACTS_DIR/worklog.log" && echo "WORKLOG_READY"
+   ```
+   When a file is ready, open it in the current Kiro window:
+   ```bash
+   kiro -r "$ARTIFACTS_DIR/plan.json"
+   kiro -r "$ARTIFACTS_DIR/worklog.log"
+   ```
+   - `plan.json` — the transformation plan (appears after planning phase completes)
+     IMMEDIATELY after opening plan.json — before doing anything else, before
+     checking for worklog.log, before the next polling cycle — display this
+     message to the user:
+     
+     > ### 💡 Open Source Control (Ctrl+Shift+G) to watch changes in real time
+     > 
+     > **ATX commits after each step — Source Control shows every file change with full diffs as they happen.**
+     
+     Do NOT defer this message. Do NOT batch it with other output. Send it
+     right after the plan.json open command.
+   - `worklog.log` — the execution log (appears shortly after plan.json)
+
+   After the process exits, open:
+   ```bash
+   kiro -r "$ARTIFACTS_DIR/validation_summary.md"
+   ```
+   - `validation_summary.md` — the final validation report
+
+### 6. Present Results
+Show TD, repo path, key changes. Also tell the user:
+"You can review all changes in the Source Control panel — it shows the full
+commit history with diffs for each file ATX modified."
+
+## Error Handling
+
+| Issue | Resolution |
+|-------|------------|
+| Dependency incompatibility | Check package compatibility, may need manual update |
+| ATX timeout | Set `ATX_SHELL_TIMEOUT=1800` or break into smaller transforms |
+
+## Cleanup
+
+After the transformation completes, clean up session files automatically:
+```bash
+[ -d ~/.aws/atx/custom/atx-agent-session ] && find ~/.aws/atx/custom/atx-agent-session -maxdepth 1 -type f \( -name "*.sh" -o -name "*.log" -o -name "*.pid" -o -name "*.exit" -o -name "*.zip" \) -delete 2>/dev/null || true
+```
\ No newline at end of file
diff --git a/aws-transform-custom/steering/troubleshooting.md b/aws-transform-custom/steering/troubleshooting.md
new file mode 100644
index 0000000..ca2607d
--- /dev/null
+++ b/aws-transform-custom/steering/troubleshooting.md
@@ -0,0 +1,41 @@
+# Troubleshooting
+
+## Quick Reference
+
+| Issue | Resolution |
+|-------|------------|
+| `atx` not found | Install: `curl -fsSL https://transform-cli.awsstatic.com/install.sh` piped to `bash` |
+| AWS credentials error | Run `aws sts get-caller-identity`. Check `AWS_PROFILE` or access key env vars |
+| Permission denied | Need `transform-custom:*` — see Prerequisites → IAM Permissions in POWER.md |
+| Network error | Resolve region: `REGION=${AWS_REGION:-${AWS_DEFAULT_REGION:-$(aws configure get region 2>/dev/null)}}; REGION=${REGION:-us-east-1}`. Check access to `transform-custom.${REGION}.api.aws` |
+| Build fails during transform | Verify build command works locally first. Try interactive mode for debugging |
+| Transform not found | Run `atx custom def list --json` to check available TDs |
+| Conversation expired | Conversations expire after 30 days. Start a new one |
+| Windows not supported | Tell user to use Windows Subsystem for Linux (WSL) |
+| Timeout | Set `export ATX_SHELL_TIMEOUT=1800` (default: 900s) |
+| Poor quality results | See Improving Quality section below |
+
+## Local Mode Debugging
+
+| Log | Path |
+|-----|------|
+| Developer logs | `~/.aws/atx/logs/debug*.log` and `~/.aws/atx/logs/error.log` |
+| Conversation log | `~/.aws/atx/custom/<conversation_id>/logs/<timestamp>-conversation.log` |
+
+Network errors may indicate VPN/firewall issues with AWS endpoints.
+
+## Improving Quality
+
+Diagnose in this order:
+
+1. **Build command** (most impactful): Is it deterministic? Does it return meaningful errors? Specific commands (`mvn clean install`) outperform no validation.
+2. **Reference materials**: Provide migration guides or API specs via `additionalPlanContext`.
+3. **Complexity**: Decompose very complex transforms into smaller steps.
+4. **Knowledge items**: Review learnings from previous runs. Enable good ones, disable irrelevant ones.
+
+## Network Requirements
+
+| Endpoint | Purpose |
+|----------|---------|
+| `transform-cli.awsstatic.com` | CLI installation and updates |
+| `transform-custom.${REGION}.api.aws` | Transformation service API |