refactor: align Makefile target names with a documented grammar

.buildkite/pipeline.yml

@@ -13,10 +13,10 @@ steps:
       key: build-react
       command: |
           # Fail fast if any step (including the backgrounded
-          # `prep-translations`, surfaced via `wait`) returns non-zero,
+          # `fetch-translations`, surfaced via `wait`) returns non-zero,
           # rather than continuing into `make build` with partial inputs.
           set -euo pipefail
-          # `prep-translations` is pure network I/O and no longer depends
+          # `fetch-translations` is pure network I/O and no longer depends
           # on `node_modules` (uses Node's built-in `fetch`), so it can run
           # in parallel with `npm ci`. Vite reads `src/translations/` when
           # it emits locale bundles, so we wait for the fetch to complete
@@ -27,16 +27,16 @@ steps:
           # interleave with `npm ci`'s and confuse Buildkite log folding.
           # The replay happens unconditionally so a failed fetch surfaces
           # its log before `set -e` aborts the script.
-          make prep-translations STRICT_L10N=1 > prep-translations.log 2>&1 &
-          PREP_PID=$$!
-          make npm-dependencies
-          PREP_STATUS=0
-          wait $$PREP_PID || PREP_STATUS=$$?
-          echo "--- :earth_americas: prep-translations (ran in parallel with npm ci)"
-          cat prep-translations.log
-          rm -f prep-translations.log
-          if [ "$$PREP_STATUS" -ne 0 ]; then
-              exit "$$PREP_STATUS"
+          make fetch-translations STRICT_L10N=1 > fetch-translations.log 2>&1 &
+          FETCH_PID=$$!
+          make install-web-deps
+          FETCH_STATUS=0
+          wait $$FETCH_PID || FETCH_STATUS=$$?
+          echo "--- :earth_americas: fetch-translations (ran in parallel with npm ci)"
+          cat fetch-translations.log
+          rm -f fetch-translations.log
+          if [ "$$FETCH_STATUS" -ne 0 ]; then
+              exit "$$FETCH_STATUS"
           fi
           make build REFRESH_JS_BUILD=1
           tar -czf dist.tar.gz dist/
@@ -55,7 +55,7 @@ steps:
 
     - label: ':eslint: Lint React App'
       key: lint-js
-      command: make lint-js
+      command: make lint-web
       plugins: *plugins
 
     - label: ':npm: Check @wordpress package versions'
@@ -65,7 +65,7 @@ steps:
 
     - label: ':javascript: Test JavaScript'
       key: test-js
-      command: make test-js
+      command: make test-web-unit
       plugins: *plugins
 
     - label: ':performing_arts: Test Web E2E'
@@ -77,7 +77,7 @@ steps:
           echo "--- :wordpress: Starting wp-env"
           make wp-env-start
           echo "--- :performing_arts: Running E2E tests"
-          make test-e2e
+          make test-web-e2e
       plugins: *plugins
 
     - label: ':android: Publish Android Library'
@@ -110,7 +110,7 @@ steps:
       command: |
           buildkite-agent artifact download dist.tar.gz .
           tar -xzf dist.tar.gz
-          make test-android
+          make test-android-library-unit
       agents:
           queue: android
       plugins: *plugins
@@ -121,7 +121,7 @@ steps:
       command: |
           buildkite-agent artifact download dist.tar.gz .
           tar -xzf dist.tar.gz
-          make test-swift-package
+          make test-ios-library-simulator
       plugins: *plugins
 
     - label: ':swift: Library Tests'
@@ -130,7 +130,7 @@ steps:
       command: |
           buildkite-agent artifact download dist.tar.gz .
           tar -xzf dist.tar.gz
-          make test-swift-library
+          make test-ios-library-host
       plugins: *plugins
 
     - label: ':xcode: Build XCFramework'
@@ -143,7 +143,7 @@ steps:
           tar -xzf dist.tar.gz
           install_gems
           bundle exec fastlane set_up_signing_release
-          make build-resources-xcframework
+          make build-ios-resources-xcframework
           bundle exec fastlane xcframework_sign
           ./package_xcframework.sh
       artifact_paths:
@@ -199,7 +199,7 @@ steps:
       command: |
           buildkite-agent artifact download dist.tar.gz .
           tar -xzf dist.tar.gz
-          make test-ios-e2e
+          make test-ios-app-e2e
       plugins: *plugins
 
     - label: ':android: Test Android E2E'
@@ -212,7 +212,7 @@ steps:
               --system-image "system-images;android-34;google_apis;arm64-v8a" \
               --device "pixel_5"
           echo "--- :android: Running Android instrumented tests"
-          make test-android-e2e
+          make test-android-app-e2e
       agents:
           queue: mac-metal
       plugins: *plugins

AGENTS.md

@@ -23,6 +23,8 @@ To see all available make commands with descriptions, run:
 make help
 ```
 
+New targets follow the naming grammar documented in the header comment at the top of the `Makefile`.
+
 By default, dependencies, translations, and JS build are skipped if output directories already exist. Environment variables be used to force refresh of these steps when needed.
 
 -   `REFRESH_DEPS=1` - Force refresh of dependencies (e.g. re-install npm packages)
@@ -71,10 +73,10 @@ Note: Console logs should be used sparingly. For verbose or development-specific
 
 ```bash
 # Auto-fix linting errors & verify linting passes
-make lint-js-fix
+make lint-web-fix
 
 # When Swift files changed
-make lint-swift-fix
+make lint-ios-fix
 ```
 
 These commands ensure code quality and prevent lint errors from blocking commits.
@@ -85,8 +87,8 @@ Swift code is linted with SwiftLint, run via the SwiftPM plugin in the `BuildToo
 package so the linter stays out of the dependency graph of anyone consuming
 GutenbergKit via SwiftPM.
 
--   `make lint-swift` — report violations
--   `make lint-swift-fix` — auto-correct the violations SwiftLint can fix
+-   `make lint-ios` — report violations
+-   `make lint-ios-fix` — auto-correct the violations SwiftLint can fix
 
 The SwiftLint version is pinned in a single place: the `swiftlint_version` key in
 `.swiftlint.yml`. `BuildTools/Package.swift` parses that key at manifest-evaluation
@@ -102,14 +104,14 @@ stay consistent for the shared team.
 To lint specific files rather than the whole project, set `SWIFT_LINT_PATHS`:
 
 ```bash
-make lint-swift SWIFT_LINT_PATHS=ios/Sources/GutenbergKit/Sources/EditorService.swift
+make lint-ios SWIFT_LINT_PATHS=ios/Sources/GutenbergKit/Sources/EditorService.swift
 ```
 
 Separate multiple files with **newlines**, not spaces, so that paths containing
 spaces stay intact. This makes it easy to lint just the changed files:
 
 ```bash
-make lint-swift SWIFT_LINT_PATHS="$(git diff --name-only -- '*.swift')"
+make lint-ios SWIFT_LINT_PATHS="$(git diff --name-only -- '*.swift')"
 ```
 
 Each value must be a path to an existing **file**. Passing a directory (or a

CONTRIBUTING.md

@@ -19,8 +19,8 @@ Whether you're looking to write code, improve documentation, or help triage issu
 
 ## Guidelines
 
--   Run `make format` and `make lint-js` before submitting changes
--   Ensure tests pass with `make test-js`, `make test-swift-package`, and `make test-android`
+-   Run `make format` and `make lint-web` before submitting changes
+-   Ensure tests pass with `make test-web-unit`, `make test-ios-library-simulator`, and `make test-android-library-unit`
 -   Follow the existing code style and patterns
 
 ## Releases