chore: remove orphaned directories and correct stale documentation (#4267)

* chore: remove orphaned test app, tools, and dead CI scripts

These directories were orphaned when the root Amplify.xcodeproj was deleted
in 937c47e (Feb 2022) and have had no live references since. Every commit
touching them afterwards was a release bump or a repo-wide formatting sweep,
so they were costing maintenance without being built or run.

- AmplifyTestApp/: an iOS app bundle with no .xcodeproj to build it. Its only
  mention anywhere was the .swiftlint.yml exclusion list. Its
  awsconfiguration.json is not even valid JSON (unterminated string on the
  PoolId line), confirming nothing has parsed it in years.
- AmplifyFunctionalTests/: not a target in Package.swift and not run by any
  workflow; uncompiled, unrunnable test code.
- AmplifyTools/: 48 files including a nested SPM package and its own
  .xcodeproj, never built by CI. Self-declared deprecated in its own README
  ("will be completely removed in a future release").

Also cleans up the CircleCI leftovers. There has been no .circleci/ config
since 2022, but the directory name survived:

- Deleted pre_start_simulator.sh (untouched since 2019; depends on
  CircleCI-only $BASH_ENV and circleci-test-device, so it cannot work on
  GitHub Actions).
- Deleted check_api_breakage.sh, superseded by
  api-breaking-changes-detection.yml. It had already drifted stale: it
  checked 2 modules while api-dump/ tracks 4, so a local run gave a false
  pass.
- Renamed CircleciScripts/ to scripts/, keeping the one live script
  (jazzy_doc_gen.sh), and updated its three workflow references.

Finally, drops two unreferenced readme-images assets and the now-dangling
.swiftlint.yml exclusions.

Verified: `swift package dump-package` succeeds, `swiftlint` reports zero
errors, and no references to the removed paths remain outside CHANGELOG.md.

* docs: correct stale versions, paths, links, and API signatures

Audited the markdown against the actual repo contents and fixed the claims
that contradict it. Each item below was verified against Package.swift, the
source, or by resolving the URL.

Version and tooling facts:
- CONTRIBUTING.md said Xcode 13.4 minimum; README.md and AGENTS.md say 16.0,
  and 13.4 cannot even parse `swift-tools-version:5.9`.
- CONTRIBUTING.md specified a 100-character line limit; SwiftLint enforces 160.
- CONTRIBUTING.md's Tools section listed only Xcode, omitting the SwiftFormat
  0.60.1 / SwiftLint 0.54.0 pins and Fastlane that CI actually requires.
- AGENTS.md said 19 test targets (there are 23) and "60+" workflows (70).

Wrong or dead references:
- AWS SDK for Swift linked to github.com/aws-amplify/aws-sdk-swift; the
  correct org is awslabs, per Package.swift.
- Six dead CONTRIBUTING.md TOC anchors (off-by-one step links, a
  "Running Cocoapods Locally" entry with no target section).
- Four legacy docs.amplify.aws /lib/...q/platform/ios URLs updated to the
  paths they now redirect to.
- bug_report.yaml pointed at the old amplify-ios repo and asked Swift users
  for an Amplify CLI log; LogsGuidance.md is about Xcode console output.
- ETHOS.md named a nonexistent AWSStoragePlugin (it is AWSS3StoragePlugin).
- AmplifyTests/CoreTests/README.md described an amplifyconfiguration.json
  sample that is not in that directory, and predated amplify_outputs.json.

Corrected code and structure claims:
- AmplifyClients/AGENTS.md: KinesisError.unknown has three associated values,
  not two; the initializer is `throws`; `record` is `@discardableResult`; the
  User-Agent example double-stamped the version, which UserAgentClientEngine
  already injects as lib/amplify-swift#<version>.
- AmplifyClients/AGENTS.md: added the missing AmplifyRecordCache layer (used
  by Kinesis and Firehose) and corrected the integration-test layout, which
  is not co-located per client.
- AmplifyPlugins/AGENTS.md: unit-test directory names vary by plugin, so the
  single stated pattern was wrong for most of them. Also removed
  `@visibleForTesting`, which is not a Swift attribute and has zero
  occurrences in this codebase.
- Amplify/AGENTS.md: named the two actual DefaultPlugins and resolved the
  contradiction about Hub needing no plugin.
- Documented that api-dump/ covers only four modules, and distinguished
  api-breaking-changes-detection.yml from api_digester_check.yml.
- Documented that SwiftLint's `included:` scope excludes AmplifyClients/,
  AmplifyFoundation/, and AmplifyFoundationBridge/, and that the lint
  workflows do not run on pull_request.
- Added the footnote the README's visionOS "Preview*" marker was missing, and
  noted visionOS is not declared in Package.swift but inherited from iOS.
- Surfaced the Amazon Pinpoint retirement notice (Oct 30, 2026) in README.md
  and AmplifyPlugins/AGENTS.md; previously only the migration guide carried
  it while the README still listed Analytics as GA with no caveat.
- Fixed a syntax error in both README-combine-support.md samples
  (`search(for "coffee")` was missing its colon) and two LogsGuidance.md typos.

* ci: bump checkout pin on lint workflows and drop stale scheme testable

The SwiftLint and SwiftFormat workflows were the only two of 26 still pinned
to actions/checkout v3.5.3, which runs on the deprecated Node 16 runtime.
Bumped both to the v4.1.1 pin the other 24 workflows already use.

Also removed the AmplifyConnectClientIntegrationTests testable from
Amplify-Package.xcscheme. That target does not exist in Package.swift — the
integration tests live in a separate host-app project
(AmplifyClients/AmplifyConnectClient/Tests/ConnectClientHostApp) where the
scheme is named ConnectClientIntegrationTests. This was harmless only because
Amplify-Package is used for `xcodebuild build` and never `test`; it would fail
for anyone invoking the scheme's test action. Verified the scheme is still
valid XML.

Author: harsh62

.github/ISSUE_TEMPLATE/bug_report.yaml

@@ -87,8 +87,8 @@ body:
     attributes:
       label: Relevant log output
       description: >-
-        Include any relevant log output under
-        `~/.amplify/logs/amplify-cli-<issue-date>.log` (See: [Logs Guidance](https://github.com/aws-amplify/amplify-ios/blob/main/LogsGuidance.md))
+        Include any relevant log output from the Xcode console
+        (See: [Logs Guidance](https://github.com/aws-amplify/amplify-swift/blob/main/LogsGuidance.md))
       value: |
         <details>
         <summary>Log Messages</summary>

.github/workflows/deploy_package.yml

@@ -80,4 +80,4 @@ jobs:
         working-directory: ${{ github.workspace }}
         run: |
           git checkout -B gh-pages
-          bash ./CircleciScripts/jazzy_doc_gen.sh
+          bash ./scripts/jazzy_doc_gen.sh

.github/workflows/deploy_release.yml

@@ -75,4 +75,4 @@ jobs:
         working-directory: ${{ github.workspace }}
         run: |
           git checkout -B gh-pages
-          bash ./CircleciScripts/jazzy_doc_gen.sh
+          bash ./scripts/jazzy_doc_gen.sh

.github/workflows/release_doc.yml

@@ -45,4 +45,4 @@ jobs:
         env:
           GITHUB_EMAIL: aws-amplify-ops@amazon.com
           GITHUB_USER: aws-amplify-ops
-        run: bash ./CircleciScripts/jazzy_doc_gen.sh
+        run: bash ./scripts/jazzy_doc_gen.sh

.github/workflows/swiftformat.yml

@@ -28,7 +28,7 @@ jobs:
       SWIFTFORMAT_VERSION: '0.60.1'
       SWIFTFORMAT_SHA256: 'cb4738085cf39c08da00b79b4a3683e77458ca12909934d04e5087d8e73f5e43'
     steps:
-      - uses: actions/checkout@c85c95e3d7251135ab7dc9ce3241c5835cc595a9 #v3.5.3
+      - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 #v4.1.1
         with:
           persist-credentials: false
 

.github/workflows/swiftlint.yml

@@ -27,7 +27,7 @@ jobs:
     container:
       image: ghcr.io/realm/swiftlint:0.54.0
     steps:
-      - uses: actions/checkout@c85c95e3d7251135ab7dc9ce3241c5835cc595a9 #v3.5.3
+      - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 #v4.1.1
         with:
           persist-credentials: false
 

.swiftlint.yml

@@ -9,8 +9,6 @@ excluded:
   - Pods
   - .build
   - AmplifyAsyncTesting
-  - AmplifyFunctionalTests
-  - AmplifyTestApp
   - AmplifyTestCommon
   - AmplifyTests
   - AmplifyPlugins/Core/AWSPluginsCoreTests

.swiftpm/xcode/xcshareddata/xcschemes/Amplify-Package.xcscheme

@@ -895,16 +895,6 @@
                ReferencedContainer = "container:">
             </BuildableReference>
          </TestableReference>
-         <TestableReference
-            skipped = "NO">
-            <BuildableReference
-               BuildableIdentifier = "primary"
-               BlueprintIdentifier = "AmplifyConnectClientIntegrationTests"
-               BuildableName = "AmplifyConnectClientIntegrationTests"
-               BlueprintName = "AmplifyConnectClientIntegrationTests"
-               ReferencedContainer = "container:">
-            </BuildableReference>
-         </TestableReference>
       </Testables>
    </TestAction>
    <LaunchAction

AGENTS.md

@@ -13,11 +13,13 @@ Detailed conventions and patterns live closer to the code. Read the relevant gui
 
 - [`Amplify/AGENTS.md`](Amplify/AGENTS.md) — Core framework: categories, plugin protocols, error handling, configuration, Hub
 - [`AmplifyPlugins/AGENTS.md`](AmplifyPlugins/AGENTS.md) — Plugin implementations: Auth, API, Storage, DataStore, etc.
-- [`AmplifyClients/AGENTS.md`](AmplifyClients/AGENTS.md) — Standalone clients: Foundation, Bridge, Kinesis (new pattern)
+- [`AmplifyClients/AGENTS.md`](AmplifyClients/AGENTS.md) — Standalone clients: Kinesis, Firehose, Connect, EventEnrichment, plus shared RecordCache (new pattern)
 
 ## Linting & Formatting (MUST pass)
 
-**Always run `swiftformat` on changed files before every commit.** CI enforces both formatting and linting — PRs will fail if files are not formatted. See `.swiftlint.yml` and `.swiftformat` for full rules.
+**Always run `swiftformat` on changed files before every commit.** The SwiftFormat and SwiftLint workflows run on pushes to non-default branches (not on `pull_request`), so format locally rather than relying on a PR check to catch it. See `.swiftlint.yml` and `.swiftformat` for full rules.
+
+Note that `.swiftlint.yml` only lints `Amplify/` and `AmplifyPlugins/` — `AmplifyClients/`, `AmplifyFoundation/`, and `AmplifyFoundationBridge/` are outside SwiftLint's `included:` scope, though SwiftFormat covers the whole repo.
 
 ```bash
 swiftformat <changed-files>   # Format changed files before committing
@@ -42,7 +44,7 @@ swiftlint --fix               # Then lint
 amplify-swift/
 ├── Amplify/                    # Core framework (categories, protocols, errors, config)
 ├── AmplifyPlugins/             # AWS service plugins (Auth, API, Storage, DataStore, etc.)
-├── AmplifyClients/             # Standalone AWS clients (Kinesis) — new pattern
+├── AmplifyClients/             # Standalone AWS clients (Kinesis, Firehose, Connect, EventEnrichment) — new pattern
 ├── AmplifyFoundation/          # Shared protocols (credentials, logging, errors) — no deps
 ├── AmplifyFoundationBridge/    # Foundation ↔ AWS SDK adapters
 ├── AmplifyTests/               # Core unit tests
@@ -84,7 +86,7 @@ chore: update aws-swift-sdk dependency
 ```
 
 **Types**: `feat`, `fix`, `chore`, `refactor`, `test`, `docs`, `perf`, `ci`
-**Scopes**: `auth`, `api`, `storage`, `datastore`, `geo`, `analytics`, `logging`, `predictions`, `push`, `kinesis`, `core`, `foundation`
+**Scopes**: `auth`, `api`, `storage`, `datastore`, `geo`, `analytics`, `logging`, `predictions`, `push`, `kinesis`, `firehose`, `connect`, `core`, `foundation`
 
 No period at end. One feature/bugfix per PR. Reference issues: `fixes #<issue>`.
 
@@ -95,7 +97,7 @@ swift test                                          # All unit tests
 swift test --filter AWSCognitoAuthPluginUnitTests    # Specific target
 ```
 
-- **Unit tests**: XCTest, defined in Package.swift (19 test targets)
+- **Unit tests**: XCTest, defined in Package.swift (23 test targets)
 - **Integration tests**: Xcode host app projects under `AmplifyPlugins/<Category>/Tests/<Category>HostApp/`
 - **Conventions**: Mock via behavior protocols, use `AmplifyTestCommon` for shared utilities, `AmplifyAsyncTesting` for async helpers
 - **Test documentation**: Use Given/When/Then doc comments on all test methods:
@@ -114,11 +116,11 @@ swift test --filter AWSCognitoAuthPluginUnitTests    # Specific target
 
 ## Semver
 
-New enum cases = **minor** bump. Breaking API changes = **major** (rare, needs approval). API surface tracked via `api-dump/` JSON snapshots and CI checks.
+New enum cases = **minor** bump. Breaking API changes = **major** (rare, needs approval). API surface tracked via `api-dump/` JSON snapshots and CI checks, currently covering four modules only: `Amplify`, `AWSPluginsCore`, `AWSDataStorePlugin`, and `CoreMLPredictionsPlugin`.
 
 ## CI/CD
 
-60+ GitHub Actions workflows in `.github/workflows/`: per-category unit tests (`unit_test_*.yml`), integration tests (`integ_test_*.yml`), platform builds, SwiftLint/SwiftFormat checks, API digester, CodeQL, Fortify. Releases via Fastlane.
+70 GitHub Actions workflows in `.github/workflows/`: per-category unit tests (`unit_test_*.yml`), integration tests (`integ_test_*.yml`), platform builds, SwiftLint/SwiftFormat checks, API digester, CodeQL, Fortify. Releases via Fastlane.
 
 ## Common Agent Tasks
 

Amplify/AGENTS.md

@@ -34,7 +34,7 @@ Amplify/
 │   ├── Auth/            # AuthCategoryBehavior (sign-in, sign-up, session, MFA)
 │   ├── DataStore/       # DataStoreCategoryBehavior (sync, query, observe)
 │   ├── Geo/             # GeoCategoryBehavior (search, maps)
-│   ├── Hub/             # Built-in pub/sub event system (no plugin needed)
+│   ├── Hub/             # Pub/sub event system (no user setup needed — backed by the built-in AWSHubPlugin)
 │   ├── Logging/         # LoggingCategoryBehavior
 │   ├── Notifications/   # Push notification behavior
 │   ├── Predictions/     # ML prediction behavior (text, vision, speech)
@@ -47,7 +47,7 @@ Amplify/
 │   ├── Model/           # Model, Schema, Field definitions (DataStore)
 │   ├── Plugin/          # Plugin protocol, PluginKey, Resettable
 │   └── Support/         # AmplifyError protocol, utilities
-├── DefaultPlugins/      # Built-in default plugin implementations
+├── DefaultPlugins/      # AWSHubPlugin and AWSUnifiedLoggingPlugin (registered automatically)
 └── DevMenu/             # Developer debug menu
 ```
 
@@ -107,7 +107,7 @@ let token = Amplify.Hub.listen(to: .auth) { payload in ... }
 
 ## API Surface Stability
 
-API dumps in `api-dump/*.json` track the public surface. Breaking changes detected by CI (`api_digester_check.yml`). New enum cases = minor bump; removing/renaming public APIs = major bump (needs approval).
+API dumps in `api-dump/*.json` track the public surface of four modules (`Amplify`, `AWSPluginsCore`, `AWSDataStorePlugin`, `CoreMLPredictionsPlugin`). Breaking changes detected by CI (`api-breaking-changes-detection.yml`; `api_digester_check.yml` separately verifies the digester tool itself against the `api-dump-test/` fixtures). New enum cases = minor bump; removing/renaming public APIs = major bump (needs approval).
 
 ## Adding a New API to a Category