Merged in feature/cognito-shared-environments (pull request #211)

cognito and permit shared prod environment support

* code complete

* user creattion tool

test harness

deployment_env_variables.md

@@ -65,6 +65,7 @@ These should be **IDENTICAL** for all services:
 | `COGNITO_CLIENT_ID` | `client_id_here` | AWS Cognito Client ID                              |
 | `COGNITO_CLIENT_SECRET` | `client_secret_here` | AWS Cognito Client Secret                          |
 | `COGNITO_DOMAIN` | `your-domain.auth.us-east-2.amazoncognito.com` | AWS Cognito Domain                                 |
+| `COGNITO_ENVIRONMENT_ID` | `acmehealth` | Optional. Scopes server to a specific environment within a shared Cognito user pool. Lowercase alphanumeric + underscores, max 50 chars. Leave empty/unset for unscoped mode. |
 
 ### 6. Application Configuration (SHARED across all services)
 
@@ -152,6 +153,7 @@ These should be **IDENTICAL** for all services:
 - `CLIENT_SYNC_URL`
 - `BUCKET` (S3 bucket name)
 - `DEBUG` (optional, set to `true` for development)
+- `COGNITO_ENVIRONMENT_ID` (optional, scopes user operations to a specific environment)
 - AWS config (shared)
 - Database config (shared)
 - Auth config (shared)
@@ -200,6 +202,7 @@ When deploying to a new environment (e.g., moving from dev to stage):
 - [ ] Set LOG_LEVEL appropriately (DEBUG for dev, INFO for prod)
 - [ ] Set DISABLE_AUTH appropriately (true for dev, false for prod)
 - [ ] Ensure `QUEUE_URL` is unique for each runner service
+- [ ] Set `COGNITO_ENVIRONMENT_ID` for queryAPI if using shared Cognito user pool (e.g., `acmehealth`)
 - [ ] Remove `AWS_ENDPOINT_URL` and `AWS_S3_USE_PATH_STYLE` (LocalStack only)
 
 ## Common Mistakes to Avoid