chore: additional buildout of KB for agentic coding (#3440)

Started to expand buildout of docs for agentic coding tools contributing
to the repo, including known gaps, workarounds, and statuses thereof.

No code changes. Feel free to skip checks and merge if it looks OK.

Author: svidgen

.agent-docs/CODE_NAVIGATION.md

@@ -0,0 +1,41 @@
+# Development Commands
+
+Common commands for building, testing, and working with this repository.
+
+## Build & Test
+
+```sh
+yarn build              # Build all packages
+yarn test               # Run all tests
+yarn test-ci            # Run all tests in CI mode (with coverage)
+yarn lint               # Check linting (see note below)
+yarn setup-dev          # Setup local CLI (amplify-dev)
+yarn production-build   # Production build
+yarn build-tests        # Build test packages
+```
+
+## Linting
+
+`yarn lint` does NOT pass on the full repo (OOM + thousands of existing errors). CI only lints PR-changed files and treats eslint failures as non-blocking (`|| true`). `prettier-check` and `depcheck` DO block in CI.
+
+## License Verification
+
+```sh
+yarn verify-dependency-licenses-extract
+# Equivalent to: yarn extract-dependency-licenses && ./scripts/verify-dependency-licenses.sh
+```
+
+- License changes after dependency updates are expected — always commit `dependency_licenses.txt` changes
+- The pre-commit hook runs this automatically
+
+## Local Registry (Verdaccio)
+
+Used for e2e testing. Publishes packages to a local registry.
+
+```sh
+# Start Verdaccio (in separate terminal)
+npx verdaccio
+
+# Publish packages
+yarn publish-to-verdaccio
+```

.agent-docs/CUSTOMER_EXPERIENCE.md

@@ -0,0 +1,133 @@
+# E2E Testing
+
+Complete guide for running, monitoring, and debugging e2e tests.
+
+## Key Concept
+
+E2E tests run against pushed code in AWS CodeBuild, not local changes. Always commit and push before triggering.
+
+## When to Run E2E Tests
+
+- User explicitly requests e2e tests
+- User approves e2e testing as part of a task
+- Implied when user says "fix and test ..." or "add feature ... and test"
+
+## Cloud E2E Workflow
+
+```sh
+# 1. Commit and push all changes first
+git push
+
+# 2. Trigger e2e suite
+yarn cloud-e2e
+
+# 3. Monitor (auto-retries failed builds, polls every 5 min)
+yarn e2e-monitor {batchId}
+```
+
+Batch ID format: `amplify-category-api-e2e-workflow:{UUID}` — always use the full ID.
+
+### Other Commands
+
+```sh
+yarn e2e-status {batchId}    # Check status once
+yarn e2e-retry {batchId}     # Retry failed builds
+yarn e2e-list [limit]        # List recent batches
+yarn e2e-failed {batchId}    # Show failed builds
+yarn e2e-logs {buildId}      # View build logs
+```
+
+### Monitor Behavior
+
+The monitor auto-retries failed builds up to 10 times by default. It skips retrying `build_linux`, `build_windows`, `test`, and `lint` because failures in those are typically code-related and require fixes, not retries.
+
+If errors persist after multiple retries or multiply as fixes are applied, ask the user for guidance.
+
+## Running Individual E2E Tests Locally
+
+```sh
+cd packages/amplify-e2e-tests
+yarn e2e src/__tests__/api_1.test.ts
+```
+
+Local e2e tests create real AWS resources. You need valid credentials.
+
+### Authentication
+
+The repo scripts use `ada` (Amazon's credential management tool), called automatically. Setup:
+
+1. Ensure `ada` and `mwinit` are installed
+2. Create `scripts/.env`:
+   ```bash
+   E2E_ACCOUNT_PROD=<account-id>
+   E2E_ACCOUNT_BETA=<account-id>
+   ```
+3. If you see auth errors, run `mwinit`
+
+For personal AWS profiles, export credentials before running:
+
+```sh
+export AWS_PROFILE=your-profile-name
+```
+
+## Debugging E2E Failures
+
+### 1. Identify the Failing Build
+
+```sh
+yarn e2e-failed <batch-id>
+```
+
+### 2. Get Build Logs
+
+```sh
+yarn e2e-logs <build-id>
+```
+
+### 3. Simulate Locally
+
+Run the equivalent local command to reproduce. See [Development Commands](./DEVELOPMENT.md) for build step equivalents.
+
+### 4. Check for Pre-existing Issues
+
+```sh
+git stash
+git checkout main
+yarn <failing-command>
+git checkout <your-branch>
+git stash pop
+```
+
+## Common Failure Patterns
+
+| Pattern                  | Symptoms                                           | Action                                            |
+| ------------------------ | -------------------------------------------------- | ------------------------------------------------- |
+| Transient infrastructure | Timeouts, credential expiration, quota errors      | Retry the build                                   |
+| Code-related             | Test failures, build errors, coverage threshold    | Fix the code, don't retry                         |
+| Dependency-related       | Module not found, version conflicts, breaking APIs | Check for major version changes, consider pinning |
+
+## Build Job Types
+
+- `build_linux` / `build_windows` — Platform builds (not auto-retried)
+- `test` — Unit tests (not auto-retried)
+- `lint` — Linting (not auto-retried)
+- `verify_dependency_licenses_extract` — License verification
+- `verify_api_extract` — API surface verification
+- `verify_yarn_lock` — yarn.lock consistency
+- `publish_to_local_registry` — Verdaccio publish
+- `graphql_e2e_tests_*` — GraphQL e2e test suites (171 jobs)
+
+## Resource Cleanup
+
+E2e tests create real AWS resources. Run periodically:
+
+```sh
+yarn cleanup-stale-resources
+```
+
+## Troubleshooting
+
+- **"Command failed with exit code 1"** — Generic error. Read the full output for the actual message.
+- **"Cannot read properties of undefined"** — Usually a dependency version mismatch or breaking API change.
+- **"Coverage threshold not met"** — Check if pre-existing by testing on the base branch.
+- **"License change detected"** — Expected after dependency updates. Run `yarn extract-dependency-licenses` and commit.