Document secure workstation setup and slow terminal scroll

.agents/skills/migrate-agent-configs/SKILL.md

@@ -122,6 +122,12 @@ in a local OS keychain and are intentionally not portable. On AgentFormation,
 use the page's **OAuth** helper when a remote MCP login redirects the browser to
 `127.0.0.1` or `localhost`.
 
+Never migrate `~/.aws/credentials`, `~/.aws/sso/cache`, or `~/.aws/cli/cache`.
+The AgentFormation runtime uses its attached instance role for its normal AWS
+access. If the user also needs a personal operator profile on the remote host,
+invoke `$setup-agentformation` there and complete a fresh IAM Identity Center
+device-code login instead of copying credentials or cached tokens.
+
 ## Transfer through SSM
 
 1. Generate a one-time asymmetric key pair inside the remote scratch directory

.agents/skills/setup-agentformation/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: setup-agentformation
+description: Prepare a macOS or Linux computer to check, deploy, or contribute to AgentFormation, including secure AWS CLI Identity Center sign-in and correct amd64 versus arm64 tool selection. Use for first-time setup or platform and AWS-profile troubleshooting; do not use it to deploy or delete AWS resources without a separate request.
+---
+
+# Set up AgentFormation
+
+Prepare the current computer without changing AWS resources. Before acting, read
+[the workstation setup guide](../../../docs/workstation-setup.md) completely and
+follow its security and platform rules.
+
+## Start with a read-only inventory
+
+Identify these facts before recommending an installer or AWS change:
+
+- operating system from `uname -s`;
+- CPU architecture from `uname -m`;
+- Docker server operating system and architecture;
+- whether Docker Buildx, AWS CLI version 2, Git, and `jq` are available;
+- whether contributor-only tools are needed; and
+- existing AWS profile names and the intended deployment Region.
+
+Do not read credential files or cached SSO tokens. It is appropriate to show the
+current caller identity in the user's own terminal for verification, but do not
+copy account IDs, role ARNs, or organization-specific Identity Center addresses
+into reports, commits, issues, or logs.
+
+## Keep platform names straight
+
+Treat the operator OS, operator CPU, employee runtime architecture, and web-image
+target as separate choices. `amd64` and `x86_64` are two names for one CPU
+architecture; `arm64` and `aarch64` are two names for another. Linux is an
+operating system and can run on either CPU.
+
+Choose downloaded binaries from the detected CPU architecture. Do not copy
+binaries, package caches, or agent plugins from a different OS or architecture.
+Do not change `runtime.architecture` to match the operator computer; match it to
+the selected EC2 instance family. AgentFormation's current web-image target is
+`linux/amd64`, and Docker Buildx handles an ARM build host.
+
+## Configure AWS safely
+
+Prefer a named IAM Identity Center profile that returns temporary credentials:
+
+```bash
+aws configure sso --profile agentformation-operator
+aws sso login --profile agentformation-operator
+aws sts get-caller-identity --profile agentformation-operator
+```
+
+Use `--use-device-code` for both configure and login on a remote or headless
+host. Never use the AWS root user, create or copy static access keys, copy an SSO
+cache between computers, or commit anything under `~/.aws/`.
+
+Distinguish the two Identity Center assignments when diagnosing access:
+
+- an AWS account permission set controls the operator's console and CLI access;
+- the AgentFormation application group controls employee web-app access only.
+
+Recommend least privilege. If the deployment creates IAM resources and the
+organization does not provide a CloudFormation execution role, explain that a
+generic PowerUser permission set may be insufficient; do not silently broaden
+the operator's access.
+
+## Verify before any deployment
+
+Use the selected profile explicitly and run `./agentformation doctor`. For source
+work, also run `./scripts/check.sh`. Explain failures using the workstation guide
+and fix only the local setup the user authorized.
+
+`doctor` is the stopping point for setup. Treat `deploy`, `destroy`, user
+disable/enable/purge commands, permission-set changes, and application-group
+changes as separate AWS mutations that require the user's explicit request.
+
+At handoff, report the detected platform, installed tool status, selected profile
+name, `doctor` result, contributor-check result when applicable, and anything the
+organization administrator must assign. Keep private AWS identifiers out of the
+report.

.agents/skills/setup-agentformation/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Set Up AgentFormation"
+  short_description: "Prepare AWS access and local tools safely"
+  default_prompt: "Use $setup-agentformation to prepare this computer for AgentFormation without deploying anything yet."
+
+policy:
+  allow_implicit_invocation: true

CONTRIBUTING.md

@@ -23,6 +23,11 @@ Thanks for helping improve AgentFormation.
 
 ## Checks
 
+If the AWS CLI, Docker, or CPU platform names are unfamiliar, first follow the
+[workstation setup guide](docs/workstation-setup.md). In particular, Linux is an
+operating system while `amd64`/`x86_64` and `arm64`/`aarch64` are CPU
+architectures.
+
 Use the Node.js and Bun versions pinned in `agentformation.example.json` for the
 web app. New AgentFormation runtime images include those versions, so a checkout
 under `/workspace` can run the same checks. From the repository root, the

README.md

@@ -58,6 +58,14 @@ deploy the resources, Docker with `buildx`, `jq`, and access to the selected
 Bedrock models. The AWS root user is deliberately not an app login. Root is a
 separate emergency identity and should not be used for daily work.
 
+Before deploying, follow the
+[workstation setup guide](docs/workstation-setup.md) to install the correct AWS
+CLI and Docker tools for macOS or Linux on `amd64`/`x86_64` or
+`arm64`/`aarch64`. It also explains why the AWS account permission set used by
+the CLI is separate from the Identity Center group assigned to the
+AgentFormation application. For a guided, read-only setup, start Codex from this
+repository and invoke `$setup-agentformation`.
+
 AWS does not expose customer-managed SAML application creation or attribute
 mapping through its public CLI, API, or CloudFormation resource. Creating the
 Identity Center application and entering its two attribute mappings is therefore
@@ -215,6 +223,9 @@ Disabling a user stops EC2 compute but preserves EBS storage. Use `purge` or
 
 ## Development
 
+Prepare the pinned tools and understand the host-versus-container architecture
+using the [workstation setup guide](docs/workstation-setup.md), then run:
+
 ```bash
 ./scripts/check.sh
 ```

docs/configuration.md

@@ -11,21 +11,21 @@ cp agentformation.example.json agentformation.local.json
 
 ## Configuration fields
 
-| Field | What to enter | When to change it |
-| --- | --- | --- |
-| `deploymentName` | A lowercase name using letters, numbers, and hyphens | Keep it stable for the life of one deployment. Changing it creates a separate set of AWS resources. |
-| `region` | The AWS Region for the deployment | Choose a Region supported by the required AWS services and configured Bedrock models. |
-| `publicUrl` | Empty, or the exact `https://` origin of an active App Runner custom domain | Leave empty for the generated App Runner address. Do not add a path or trailing slash. |
-| `networkMode` | `private-nat` or `private-endpoints` | `private-nat` is the normal starting point. The endpoint mode adds AWS service endpoints but still keeps internet access for developer tools. |
-| `identityCenter.metadataUrl` | The private HTTPS metadata address from the customer-managed SAML application | Preferred after the first identity bootstrap. Set only this field or `metadataFile`. |
-| `identityCenter.metadataFile` | A local path to downloaded SAML metadata XML | Use only when IAM Identity Center does not provide a metadata address. A path under `.agentformation/` stays out of Git. |
-| `cloudFormationRoleArn` | An optional, existing CloudFormation service role ARN | Add it only when the AWS account requires CloudFormation to use that role. |
-| `runtime.architecture` | `arm64` or `x86_64` | It must match the selected instance family. ARM is the example default. |
-| `runtime.instanceType` | The EC2 type for each employee environment | Review cost and memory before inviting a group. |
-| `runtime.volumeSizeGiB` | Persistent disk size, from 20 through 1024 GiB | Increasing the default affects newly created environments. |
-| `models.claude` | An active Bedrock inference-profile ID | The deploy check resolves the profile and limits the runtime role to that profile and its current destination models. |
-| `models.codex` | The Bedrock model ID used by Codex | Confirm access, provider terms, and quotas in the deployment Region. |
-| `versions.*` | Exact AWS CLI, Node.js, Bun, Claude Code, and Codex versions | Keep exact versions. A maintainer should update and test them deliberately. |
+| Field                         | What to enter                                                                 | When to change it                                                                                                                             |
+| ----------------------------- | ----------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| `deploymentName`              | A lowercase name using letters, numbers, and hyphens                          | Keep it stable for the life of one deployment. Changing it creates a separate set of AWS resources.                                           |
+| `region`                      | The AWS Region for the deployment                                             | Choose a Region supported by the required AWS services and configured Bedrock models.                                                         |
+| `publicUrl`                   | Empty, or the exact `https://` origin of an active App Runner custom domain   | Leave empty for the generated App Runner address. Do not add a path or trailing slash.                                                        |
+| `networkMode`                 | `private-nat` or `private-endpoints`                                          | `private-nat` is the normal starting point. The endpoint mode adds AWS service endpoints but still keeps internet access for developer tools. |
+| `identityCenter.metadataUrl`  | The private HTTPS metadata address from the customer-managed SAML application | Preferred after the first identity bootstrap. Set only this field or `metadataFile`.                                                          |
+| `identityCenter.metadataFile` | A local path to downloaded SAML metadata XML                                  | Use only when IAM Identity Center does not provide a metadata address. A path under `.agentformation/` stays out of Git.                      |
+| `cloudFormationRoleArn`       | An optional, existing CloudFormation service role ARN                         | Add it only when the AWS account requires CloudFormation to use that role.                                                                    |
+| `runtime.architecture`        | `arm64` (`aarch64`) or `x86_64` (`amd64`)                                     | It must match the selected instance family, not the operator computer. ARM is the example default.                                            |
+| `runtime.instanceType`        | The EC2 type for each employee environment                                    | Review cost and memory before inviting a group.                                                                                               |
+| `runtime.volumeSizeGiB`       | Persistent disk size, from 20 through 1024 GiB                                | Increasing the default affects newly created environments.                                                                                    |
+| `models.claude`               | An active Bedrock inference-profile ID                                        | The deploy check resolves the profile and limits the runtime role to that profile and its current destination models.                         |
+| `models.codex`                | The Bedrock model ID used by Codex                                            | Confirm access, provider terms, and quotas in the deployment Region.                                                                          |
+| `versions.*`                  | Exact AWS CLI, Node.js, Bun, Claude Code, and Codex versions                  | Keep exact versions. A maintainer should update and test them deliberately.                                                                   |
 
 Run this after every config edit:
 
@@ -36,6 +36,22 @@ AWS_PROFILE=your-profile ./agentformation doctor
 The command checks the file shape, local tools, AWS identity, templates, and
 model availability without printing private metadata or credentials.
 
+## Architecture names and build targets
+
+`runtime.architecture` controls the employee EC2 runtime only. It is independent
+of the computer running `./agentformation deploy`:
+
+- `arm64` is also called `aarch64` and matches AWS Graviton instance families
+  such as `m7g`;
+- `x86_64` is also called `amd64` and matches 64-bit Intel/AMD instance
+  families; and
+- Linux and macOS are operating systems, not CPU architectures.
+
+The current App Runner web image target is `linux/amd64`. Docker Buildx lets a
+macOS or Linux ARM host build that target without changing the employee runtime
+architecture. See the [workstation setup guide](workstation-setup.md) for
+detection commands, installer selection, and architecture-error troubleshooting.
+
 ## Move an existing deployment config to another computer
 
 Build a new file from `agentformation.example.json` and copy approved values
@@ -128,6 +144,7 @@ separately so workspace data and personal settings are backed up and verified.
 - A custom `publicUrl` must already be active in App Runner and must contain only
   the HTTPS origin.
 - The Claude value must be an inference-profile ID, not an arbitrary model name.
-- The instance family must match `runtime.architecture`.
+- The instance family must match `runtime.architecture`; do not copy the
+  operator computer's architecture into this field by habit.
 - Never commit the local config, metadata XML, `.env` files, or
   `.agentformation/` state.

docs/identity-center-setup.md

@@ -9,6 +9,11 @@ This setup requires an **organization instance** of IAM Identity Center and an
 administrator who can add customer-managed applications and assign groups. An AWS
 account instance of Identity Center is not enough for customer-managed SAML apps.
 
+The application assignment described here controls who can open AgentFormation.
+It is separate from the AWS account and permission-set assignment an operator
+uses with the AWS CLI. Prepare that temporary CLI access first with the
+[workstation setup guide](workstation-setup.md).
+
 AWS currently allows customer-managed SAML application creation and SAML
 attribute mapping only in the IAM Identity Center console. Its
 [public application API](https://docs.aws.amazon.com/singlesignon/latest/APIReference/API_CreateApplication.html)

docs/migrating-local-agent-configs.md

@@ -85,6 +85,11 @@ repository.
 
 ## Portability checks
 
+- Compare `uname -s` and `uname -m` on both computers before moving tool state.
+  `amd64`/`x86_64` and `arm64`/`aarch64` name CPU architectures; Linux and
+  macOS name operating systems. Follow the
+  [workstation setup guide](workstation-setup.md) instead of copying executables
+  or installer caches between platforms.
 - Rewrite paths such as `/Users/name/...` to Linux paths under
   `/home/agentformation` or `/workspace`.
 - Disable local-only MCP servers and tools instead of marking them required and
@@ -96,6 +101,10 @@ repository.
   chats. Do not replace the remote history database with an older local copy.
 - Do not copy macOS Keychain data, sockets, process state, caches, logs,
   `node_modules`, virtual environments, or machine-specific binaries.
+- Do not migrate `~/.aws/credentials`, `~/.aws/sso/cache`, or
+  `~/.aws/cli/cache`. Use the runtime's instance role for normal access and
+  complete a fresh IAM Identity Center device-code login when a personal
+  operator profile is actually needed there.
 - Back up live SQLite databases with SQLite's backup operation before archiving
   them.
 - On macOS, create the archive with Apple metadata disabled. Reject AppleDouble