Secrets usage is not documented properly and incredibly confusing

### Before opening, please confirm:

- [X] I have checked to see if my question is addressed in the [FAQ](https://github.com/aws-amplify/amplify-hosting/blob/master/FAQ.md).
- [X] I have [searched for duplicate or closed issues](https://github.com/aws-amplify/amplify-hosting/issues?q=is%3Aissue+).
- [X] I have removed any sensitive information from my code snippets and submission.

### Amplify Hosting feature

Build settings, Deployments, Environment variables, SSR

### Is your feature request related to a problem? Please describe:

AWS Amplify Gen2 console has secrets section and following documentation page about how to use them:
- https://docs.amplify.aws/react/deploy-and-host/fullstack-branching/secrets-and-vars/

However, it's way more confusing that it might look from the first glance.

#### Frontend build time secrets

1. Documentation says that secrets created through AWS Amplify Gen2 console are stored under the `/amplify///`:

- But in reality they are stored under the under the path like `/amplify//-branch-/`, so amplify is failing to load them in Build Time::

```
2024-11-08T18:50:07.430Z [INFO]: ---- Setting Up SSM Secrets ----
2024-11-08T18:50:07.430Z [INFO]: SSM params {"Path":"/amplify//main/","WithDecryption":true}
```

- Secrets configured as "for all branches" are created under the documented location `/amplify/shared//`, but they are not being picked up during the build.

2. Amplify Application needs IAM service role assigned permissions to do `ssm: GetParametersByPath` for the `arn::ssm:::parameter/amplify//`. Otherwise you will also see warning like `[WARNING]: !Failed to set up process.env.secrets` [^0]

[^0]: https://github.com/aws-amplify/amplify-hosting/issues/3348

4. None of this is explained in the documentation:
- https://docs.amplify.aws/react/deploy-and-host/fullstack-branching/secrets-and-vars/ - this documentation page says that it should be accessed via `import { defineAuth, secret } from '@aws-amplify/backend';` but it doesn't explain that this works only for backend applications[^1]
[^1]: https://github.com/aws-amplify/amplify-backend/issues/1052#issuecomment-1957733738
- Instead you need to follow [Gen1 documentation](https://docs.aws.amazon.com/amplify/latest/userguide/environment-secrets.html#set-environment-secrets), which is counter-intuitive, because we're using Gen2 app, right?

See this comment for additional details:
- https://github.com/aws-amplify/amplify-hosting/issues/3348#issuecomment-1476044689

#### Fronted run time secrets

All above also applies to the Frontend runtime secrets, but frontend runtime doesn't support env variables and seems you need to write them to the .env file instead[^2], however that would expose plaintext secret values in downloaded build artifact. And seems there are no other workarounds as of yet:
[^2]: https://docs.aws.amazon.com/amplify/latest/userguide/ssr-environment-variables.html

- ~~There is no way to pass IAM role to server side~~:
- https://github.com/aws-amplify/amplify-hosting/issues/3205
- `import { defineAuth, secret } from '@aws-amplify/backend';` can't be used from Server Side code[^1]

### Describe how you'd like this feature to work

1. Secrets created through AWS Amplify Gen2 console should be possible to use in build time
2. Create proper documentation page explaining how to:
- Access secrets in build time
- Access secrets in SSR Runtime
- Access secrets for backend

Start with the linked AWS Amplify Gen2 secrets-and-vars page, then compare the Gen1 environment-secrets and SSR references cited in the issue. Document how to access secrets at build time, in SSR runtime, and in the backend, including the SSM paths and IAM requirements described here; done means each requested usage has an accurate, separate explanation.

Written by the indexing model from the issue text.