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

cognito and permit shared prod environment support

* code complete

* user creattion tool

test harness

docs/ai.generated/08-operations-guide.md

@@ -163,6 +163,18 @@ curl http://localhost:8082/health  # docInitRunner
 # ... etc
 ```
 
+The queryAPI health response includes `version`, `buildTime`, and `commit` fields. When `COGNITO_ENVIRONMENT_ID` is configured, an additional `cognitoEnvironmentId` field is included in the response, allowing operators to verify which environment the server instance is scoped to:
+
+```json
+{
+  "status": "healthy",
+  "version": "1.0.0",
+  "buildTime": "2025-01-15T10:00:00Z",
+  "commit": "abc1234",
+  "cognitoEnvironmentId": "acmehealth"
+}
+```
+
 #### Health Check Implementation
 ```go
 func (h *HealthHandler) IsHealthy(ctx echo.Context) error {
@@ -563,6 +575,31 @@ Queue consumer services require SQS permissions:
 }
 ```
 
+### Cognito Permissions (Environment Isolation)
+
+When `COGNITO_ENVIRONMENT_ID` is configured, the queryAPI service automatically registers the `custom:environment_id` attribute on the Cognito user pool at startup. This requires additional IAM permissions:
+
+```json
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Sid": "CognitoEnvironmentAttributeRegistration",
+      "Effect": "Allow",
+      "Action": [
+        "cognito-idp:DescribeUserPool",
+        "cognito-idp:AddCustomAttributes"
+      ],
+      "Resource": [
+        "arn:aws:cognito-idp:${REGION}:${ACCOUNT_ID}:userpool/${USER_POOL_ID}"
+      ]
+    }
+  ]
+}
+```
+
+The `DescribeUserPool` permission is used to check if the attribute already exists. The `AddCustomAttributes` permission is only used when the attribute needs to be registered for the first time. Once registered, the attribute persists permanently on the pool (Cognito custom attributes cannot be removed).
+
 ### Legacy Textract Permissions
 
 The prior text extraction/query pipeline is deprecated. Keep Textract IAM permissions only if you still run legacy compatibility services in your deployment.