miclaw-app 0.1.0

package/.next/standalone/.next/server/app/commands.segments/commands/__PAGE__.segment.rsc

@@ -0,0 +1,1658 @@
+1:"$Sreact.fragment"
+2:I[22450,["/_next/static/chunks/0mmpyn9fv2fjf.js","/_next/static/chunks/0d3shmwh5_nmn.js","/_next/static/chunks/12p3iqtw2ohfq.js"],"ExpandableBody"]
+13:I[97367,["/_next/static/chunks/0mmpyn9fv2fjf.js","/_next/static/chunks/0d3shmwh5_nmn.js"],"OutletBoundary"]
+14:"$Sreact.suspense"
+3:T1810,# Infrastructure Security Audit
+
+Scan all AWS infrastructure modules for security issues across four categories: IAM least-privilege, unprotected API routes, encryption, and factory module bypass.
+
+## How This Codebase Works
+
+This is an OpenTofu infrastructure codebase. Key facts:
+
+- AWS modules live in `modules/aws/`
+- Reusable factory modules enforce security defaults:
+  - `private_s3_bucket` — S3 with public access blocked + AES256 encryption
+  - `sqs_queue_with_dlq` — SQS with managed SSE + DLQ + CloudWatch alarms
+  - `lambda_zip_function` — Lambda with scoped IAM base policy + CloudWatch logs + error/throttle alarms
+  - `http_lambda_integration` — API Gateway routes with authorizer wiring
+- IAM policies use `aws_iam_policy_document` data sources with managed policies (not inline)
+- API Gateway routes are defined per-service via `http_lambda_integration`, NOT centralized. Each service module specifies its routes using one of three variables:
+  - `api_base_paths` — uses the account authorizer (validates JWT + account membership)
+  - `jwt_authorizer_endpoints` — uses JWT-only authorizer (validates JWT, strips account headers)
+  - `public_endpoints` — no auth (strips all Bioscope headers)
+
+## Your Task
+
+### Step 1: Audit factory modules
+
+Use the Task tool (subagent_type: "general-purpose") to spin up ONE sub-agent that reads and audits all four factory modules:
+
+- `modules/aws/private_s3_bucket/`
+- `modules/aws/sqs_queue_with_dlq/`
+- `modules/aws/lambda_zip_function/`
+- `modules/aws/http_lambda_integration/`
+
+This agent should verify the security defaults are sound, write its report to `/tmp/infra-security-audit/factory-modules.md`, and return ONLY a one-line confirmation (e.g., "Wrote report to /tmp/infra-security-audit/factory-modules.md. N findings."). Do NOT return the full report — it's in the file.
+
+### Step 2: Audit platform_vpc
+
+Spin up ONE sub-agent for `modules/aws/platform_vpc/`. Check:
+
+- Security groups: any rules with `0.0.0.0/0` or `::/0` ingress
+- Any public subnets or internet gateways
+- VPC endpoint configuration
+
+Write report to `/tmp/infra-security-audit/platform-vpc.md` and return ONLY a one-line confirmation.
+
+### Step 3: Audit service modules
+
+First, create the output directory: `mkdir -p /tmp/infra-security-audit`
+
+Then spin up sub-agents in parallel to scan service modules in batches (~5 modules per agent). Skip the factory modules and `platform_vpc` (already audited). For each module, check:
+
+#### IAM Least-Privilege
+
+- `resources = ["*"]` on any action EXCEPT where AWS requires it (e.g., Textract, EC2 network interfaces for VPC config). Flag wildcards that could be scoped to specific ARNs.
+- Overly broad actions (e.g., `dynamodb:*` instead of specific operations, `s3:*` instead of specific operations)
+- `Action = "*"` (full admin access) — this would be critical
+
+#### Unprotected API Routes
+
+- Look for usage of `http_lambda_integration` module. Check which variables are set:
+  - `api_base_paths` — good, uses account authorizer
+  - `jwt_authorizer_endpoints` — fine for user-centric routes, but flag if the endpoint path suggests it needs account context (e.g., contains `/patients/`, `/accounts/` but not `/me`)
+  - `public_endpoints` — flag for review, note what the endpoint does
+- If a service has an API Gateway integration but doesn't use `http_lambda_integration`, flag it
+
+#### Encryption & Security Defaults
+
+- Any `aws_s3_bucket` created directly (NOT using `private_s3_bucket` module) — check it has public access block and encryption
+- Any `aws_sqs_queue` created directly (NOT using `sqs_queue_with_dlq` module) — check it has `sqs_managed_sse_enabled = true`
+- Any `aws_dynamodb_table` — check if it has `deletion_protection_enabled` on tables that look like they store important data
+- Any SNS topics without encryption
+
+#### Factory Module Bypass
+
+- Flag any raw `aws_s3_bucket`, `aws_sqs_queue`, or `aws_lambda_function` resources that aren't using the factory modules. These may be intentional (note the context) but should be reviewed.
+
+Each sub-agent should write its report to `/tmp/infra-security-audit/batch-<N>.md` and return ONLY a one-line confirmation (e.g., "Wrote report to /tmp/infra-security-audit/batch-1.md. N findings across M modules."). Do NOT return the full report — it's in the file.
+
+**IMPORTANT:** When calling the Task tool for each sub-agent, explicitly instruct it to write findings to the file and return only a brief one-line confirmation. The full report must go in the file, NOT in the return message. This prevents the main agent's context from overflowing.
+
+### Step 4: Report format
+
+Each sub-agent should write its report in this format:
+
+```text
+## <module-name>
+
+### Findings
+
+#### <Issue title>
+- **File**: path/to/file.tf:line
+- **Resource**: resource type and name
+- **Issue**: description
+- **Severity**: Critical / High / Medium / Low
+- **Notes**: context (e.g., "wildcard may be required by AWS for this service")
+
+### No Issues Found
+```
+
+### Step 5: Aggregate
+
+**Important:** Do NOT read the report files yourself — this will overflow your context. Instead, spin up one final sub-agent (subagent_type: "general-purpose") to handle aggregation. This agent should:
+
+1. List all files in `/tmp/infra-security-audit/`
+2. Read each file one at a time, extracting only findings (skip "No Issues Found" sections and clean modules)
+3. Write a final summary to `/tmp/infra-security-audit/SUMMARY.md` with:
+   - **Executive Summary**: Total modules scanned, total findings by severity
+   - **Factory Module Health**: Summary of factory module audit
+   - **Findings by Category**: IAM, Routes, Encryption, Factory Bypass
+   - **Clean Modules**: List of modules with no findings (names only)
+4. Return a brief summary of the findings to you (just counts and critical items, not the full report)
+
+After the aggregation agent completes, tell the user the full report is at `/tmp/infra-security-audit/SUMMARY.md` and output the brief summary.
+
+Read the actual .tf files — don't guess based on module names. When a wildcard resource is found, check if it's a known AWS requirement before flagging.0:{"rsc":["$","$1","c",{"children":[["$","div",null,{"className":"mx-auto max-w-5xl px-8 py-10","children":[["$","div",null,{"className":"mb-8","children":[["$","div",null,{"className":"flex items-baseline gap-3","children":[["$","h1",null,{"className":"text-2xl font-medium tracking-tight","children":"Commands"}],["$","span",null,{"className":"text-sm text-text-muted","children":12}]]}],["$","p",null,{"className":"mt-1 text-sm text-text-muted","children":"Procedural commands across projects"}]]}],[["$","div","infrastructure",{"className":"mb-8","children":[["$","h2",null,{"className":"text-xs font-medium text-text-dim uppercase tracking-wide mb-3","children":"infrastructure"}],["$","div",null,{"className":"space-y-3","children":[["$","div","/Users/gabry/Desktop/infrastructure/.claude/commands/security-audit.md",{"className":"border border-border rounded-sm p-5 ","children":[["$","div",null,{"className":"flex items-center gap-2","children":[["$","h3",null,{"className":"text-sm font-medium","children":"security-audit"}],["$","span",null,{"className":"inline-flex items-center px-2 py-0.5 text-xs font-medium rounded-sm bg-surface-raised text-text-muted","children":"infrastructure"}]]}],["$","$L2",null,{"content":"$3","previewLines":3}]]}]]}]]}],"$L4","$L5"],false]}],["$L6"],"$L7"]}],"isPartial":false,"staleTime":300,"varyParams":null,"buildId":"BgLP6ChyOyE0k8Ahr8F2H"}
+8:T368e,# Broken Access Control Scan
+
+Scan ALL route handlers and Lambda handlers in platform-services for broken access control vulnerabilities beyond IDOR (which is covered by the separate `idor-scan` command).
+
+## How This Codebase Works
+
+This is a FastAPI-based backend. Key facts:
+
+- Routes live in `packages/*/src/*/routes/*.py`
+- App setup files are at `packages/*/src/*/app.py`
+- Lambda handlers are at `packages/*/src/*/handler.py`
+- Service-specific middleware may be at `packages/*/src/*/middleware.py`
+- Shared middleware is in `packages/shared_middleware/src/shared_middleware/`
+- Most routes are behind an API Gateway account authorizer that validates the JWT and sets trusted headers: `Bioscope-Account-Id`, `Bioscope-User-Id`, `Bioscope-User-Role`, `Bioscope-Is-Demo-User`
+- Some routes use a simpler JWT-only authorizer or no authorizer at all (public endpoints). The authorizer config lives in infrastructure and is not visible from this repo.
+
+### Standard Middleware Stack
+
+Every FastAPI service should mount these middlewares in this order in `app.py`:
+
+```python
+app = FastAPI(title="service-name", dependencies=[Depends(enforce_demo_read_only)])
+app.add_middleware(WithExceptionLoggingMiddleware)
+app.add_middleware(WithMetadataLoggingMiddleware)
+app.add_middleware(WithLoggerMiddleware)
+```
+
+And include routers via `app.include_router(...)`.
+
+### Role-Based Access Control
+
+The codebase has a single role validation dependency:
+
+- `require_owner_role` in `shared_middleware/role_validation.py` — checks `Bioscope-User-Role` header equals `"owner"`, raises 403 otherwise
+- Used as `RequireOwnerRoleDeps = Annotated[None, Depends(require_owner_role)]`
+
+Role is set by the API Gateway authorizer from the user's account membership record in DynamoDB.
+
+### Demo Mode
+
+- `enforce_demo_read_only` is applied as a global FastAPI dependency — blocks all non-GET/HEAD/OPTIONS requests for demo users
+- Routes can opt in to allow demo writes with the `@allow_demo_writes` decorator
+
+### Header Dependencies
+
+Trusted headers are injected via these typed dependencies (from `shared_middleware/headers.py`):
+
+- `BioscopeAccountIdHeaderDeps` — `Bioscope-Account-Id`
+- `BioscopeUserIdHeaderDeps` — `Bioscope-User-Id`
+- `BioscopeUserRoleHeaderDeps` — `Bioscope-User-Role`
+- `BioscopeCorrelationIdHeaderDeps` — `Bioscope-Correlation-Id`
+- `BioscopeInternalApiKeyHeaderDeps` — `Bioscope-Internal-Api-Key`
+- `BioscopeIsDemoUserHeaderDeps` — `Bioscope-Is-Demo-User`
+
+## Your Task
+
+### Step 1: Discover all services
+
+Use glob to find:
+1. All route files: `packages/*/src/*/routes/*.py`
+2. All app files: `packages/*/src/*/app.py`
+3. All handler files: `packages/*/src/*/handler.py`
+4. All handler directories: `packages/*/src/*/handlers/*.py`
+
+Group them by service. A service may have routes (FastAPI), handlers (Lambda), or both.
+
+### Step 2: Create an output directory and spin up sub-agents
+
+First, create an output directory using Bash: `mkdir -p access-control-scan-results` (in the repo root directory).
+
+Then, for **every service** (both route-based and handler-only), use the Task tool (subagent_type: "general-purpose") to scan that service.
+
+#### Parallelism guidelines
+
+**CRITICAL: Do NOT launch all agents at once.** This codebase has many services (typically 50+). Launching too many parallel agents causes resource contention, slow completions, and permission prompt overload.
+
+Instead, process services in **batches of 5 agents at a time**:
+
+1. **Batch 1**: Launch 5 route-based service agents in parallel (in a single message with 5 Task tool calls). Run them in background (`run_in_background: true`).
+2. **Wait**: After launching a batch, wait for all agents in the batch to complete before launching the next batch. Check completion by reading the output files or using TaskOutput.
+3. **Batch 2**: Launch the next 5 route-based services.
+4. **Continue**: Repeat until all route-based services are scanned, then do the same for handler-only services.
+
+For **handler-only services**, you may group 3-5 related services into a single agent (e.g., all `*_event_consumer` services in one agent) since they are simpler to scan. This reduces the total number of agents needed. Each grouped agent should write **separate report files** for each service it scans.
+
+#### What each sub-agent should do
+
+**For services with route files**, each sub-agent should:
+1. Read ALL route files for that service
+2. Read the service's `app.py` to check middleware mounting and global dependencies
+3. Read any service-specific `middleware.py` if it exists
+4. For each route handler, check for the vulnerabilities listed in Step 3
+5. **Write the report to a file** at `access-control-scan-results/<service-name>.md` (relative to the repo root) using the format in Step 4
+6. **Return ONLY a one-line confirmation** (e.g., "Wrote report to access-control-scan-results/chat_service.md. 2 findings."). Do NOT return the full report — it's in the file.
+
+**For handler-only services** (no route files, only `handler.py` and optionally `handlers/*.py`), each sub-agent should:
+1. Read the service's `handler.py` and all files in `handlers/` if present
+2. For each Lambda handler (decorated with `@handler.sqs`, `@handler.sns`, `@handler.direct_invocation`, `@handler.event_bridge`, `@handler.authorizer`), check for the vulnerabilities listed in Step 3 section E
+3. **Write the report to a file** at `access-control-scan-results/<service-name>.md` (relative to the repo root) using the format in Step 4
+4. **Return ONLY a one-line confirmation**
+
+**IMPORTANT:** When calling the Task tool for each sub-agent, explicitly instruct it to write findings to the file and return only a brief one-line confirmation. The full report must go in the file, NOT in the return message. This prevents the main agent's context from overflowing.
+
+### Step 3: What to check per service and route
+
+#### A. Middleware and App-Level Checks
+
+For each service's `app.py`, verify:
+
+- **Missing standard middleware**: The app MUST mount all three middlewares (`WithExceptionLoggingMiddleware`, `WithMetadataLoggingMiddleware`, `WithLoggerMiddleware`). Flag any that are missing.
+- **Missing demo mode enforcement**: The app MUST have `dependencies=[Depends(enforce_demo_read_only)]` on the `FastAPI()` constructor. Flag if missing.
+- **Non-standard middleware ordering**: Middlewares execute in reverse order of addition (LIFO). `WithLoggerMiddleware` must be added last so it executes first. Flag incorrect ordering.
+- **Routes mounted outside the app**: Check if any route files exist that are NOT included via `app.include_router(...)`. These routes would bypass all app-level middleware and dependencies.
+
+#### B. Role-Based Access Control Checks
+
+For each route handler, check:
+
+- **Sensitive mutations without role checks**: Routes that perform destructive or admin-level operations (DELETE endpoints, account settings changes, user management, billing operations) should use `RequireOwnerRoleDeps` or `Depends(require_owner_role)`. Flag mutation endpoints that handle sensitive operations without any role check. Use your judgment — not every POST/PATCH/DELETE needs a role check, but operations like deleting accounts, managing users, or changing account settings do.
+- **Role from untrusted source**: Any route that reads a role from path params, query params, or request body instead of the `Bioscope-User-Role` header. The role MUST come from the trusted header dependency.
+
+#### C. Authentication/Authorization Gaps
+
+For each route handler, check:
+
+- **Missing identity headers**: Routes that perform any data access or mutation but do NOT inject `BioscopeAccountIdHeaderDeps` or `BioscopeUserIdHeaderDeps`. Every non-public route should use at least the account ID header to scope its operations.
+- **Hardcoded or default account/user IDs**: Any route that uses a hardcoded UUID or default value for account_id or user_id instead of extracting from headers.
+- **Internal API key routes without validation**: Routes that accept `BioscopeInternalApiKeyHeaderDeps` should validate the key value against an expected secret, not just check that the header is present.
+
+#### D. Demo Mode Bypass
+
+- **Mutation routes with @allow_demo_writes that shouldn't have it**: The `@allow_demo_writes` decorator should only be on routes where demo users legitimately need write access (e.g., creating a chat for a demo walkthrough). Flag any destructive operations (DELETE, account mutations) that have this decorator.
+
+#### E. Lambda Handler Checks (for handler-only and hybrid services)
+
+Lambda handlers (`@handler.sqs`, `@handler.sns`, `@handler.direct_invocation`, `@handler.event_bridge`) are internal-facing and trust their event sources by design (IAM policies and queue/topic access policies control who can invoke them). The checks below focus on risks that remain even within that trust model.
+
+For each Lambda handler, check:
+
+- **Unscoped destructive operations**: Direct invocation or event-driven handlers that perform bulk deletes, account mutations, or data purges without scoping to a specific `account_id` or `patient_id` from the event payload. A handler that deletes "all matching records" rather than scoping by the account/patient in the event is dangerous if it ever receives malformed input.
+- **Missing account/patient scoping on queries**: Handlers that query DynamoDB or other data stores without filtering by `account_id` or `patient_id` when the event payload contains those identifiers. The handler should use the event's IDs to scope its operations, not fetch all records globally.
+- **Sensitive operations in direct invocation handlers without caller context**: Direct invocation handlers that perform admin-level operations (creating users, modifying account settings, issuing credentials) should accept and log a `correlation_id` or caller identifier for audit trail. Flag handlers that perform sensitive mutations with no traceability to the original caller.
+- **Event payload used to construct external requests without validation**: Handlers that take URLs, email addresses, or external identifiers from event payloads and pass them directly to external services (HTTP calls, email sends, S3 operations). Validate that the handler sanitizes or validates these inputs rather than blindly trusting them.
+- **Internal API key routes without key validation**: Any HTTP route (in hybrid services that have both routes and handlers) that accepts `BioscopeInternalApiKeyHeaderDeps` should validate the key value against an expected secret, not just check that the header is present.
+
+**Important context for sub-agents**: Do NOT flag handler-level findings for the following, as these are expected patterns:
+- Direct invocation handlers that don't have API Gateway-style JWT authorization — they're internal Lambda-to-Lambda calls secured by IAM
+- SQS/SNS handlers that trust `account_id` or `patient_id` from the event body — the event source is trusted
+- Handlers that don't inject `BioscopeAccountIdHeaderDeps` — header dependencies are for HTTP routes only, not Lambda handlers
+
+### Step 4: Report format
+
+Each sub-agent should write findings in this format:
+
+**For services with routes (FastAPI):**
+
+```text
+## <service-name>
+
+### App-Level Configuration
+- **Middleware**: [All present / Missing: <list>]
+- **Demo mode**: [Enforced / MISSING]
+- **Middleware order**: [Correct / INCORRECT: <details>]
+- **Unmounted routes**: [None / <list>]
+
+### Routes Scanned
+- `GET /path` — handler_name (file:line)
+- `POST /path` — handler_name (file:line)
+...
+
+### Findings
+
+#### Missing role check on sensitive mutation — `DELETE /resource/{id}`
+- **File**: path/to/file.py:123
+- **Handler**: `delete_resource`
+- **Issue**: Destructive operation with no role validation
+- **Confidence**: High / Medium / Low
+- **Notes**: <any relevant context>
+
+#### Missing identity headers — `GET /resource`
+...
+
+### No Issues Found
+(list routes that were scanned and passed all checks)
+```
+
+**For handler-only services (Lambda):**
+
+```text
+## <service-name>
+
+### Handlers Scanned
+- `@handler.sqs(queue_name="queue-name")` — handler_function (file:line)
+- `@handler.direct_invocation()` — handler_function (file:line)
+- `@handler.event_bridge()` — handler_function (file:line)
+...
+
+### Findings
+
+#### Unscoped destructive operation — handle_delete_event
+- **File**: path/to/handler.py:45
+- **Handler**: `handle_delete_event`
+- **Decorator**: `@handler.sqs(queue_name="...")`
+- **Issue**: Deletes records without scoping to account_id from event payload
+- **Confidence**: High / Medium / Low
+- **Notes**: <any relevant context>
+
+### No Issues Found
+(list handlers that were scanned and passed all checks)
+```
+
+### Step 5: Aggregate
+
+After all sub-agents complete, read each file from `access-control-scan-results/` and compile a final summary. To avoid context limits, read one file at a time and extract only the findings (skip the "No Issues Found" and "Routes Scanned" sections for clean services).
+
+Write the final report to `access-control-scan-results/SUMMARY.md` with:
+
+1. **Executive Summary**: Total services scanned (route-based + handler-only), total routes/handlers scanned, total findings by category
+2. **App-Level Issues**: Any services with middleware or configuration problems
+3. **Route-Level Findings**: All access control vulnerabilities in FastAPI routes, grouped by type
+4. **Handler-Level Findings**: All access control vulnerabilities in Lambda handlers, grouped by type
+5. **Clean Services**: List of services with no findings (names only)
+6. **Per-Service Details**: Full findings for services that had issues
+
+Then output the summary to the user.
+
+Be thorough. Read the actual code — don't guess based on function names alone. When checking for role validation, trace the full dependency chain. If a role check happens in a called function or middleware rather than at the route level, note it but don't flag it as a vulnerability.4:["$","div","platform-services",{"className":"mb-8","children":[["$","h2",null,{"className":"text-xs font-medium text-text-dim uppercase tracking-wide mb-3","children":"platform-services"}],["$","div",null,{"className":"space-y-3","children":[["$","div","/Users/gabry/Desktop/platform-services/.claude/commands/access-control-scan.md",{"className":"border border-border rounded-sm p-5 ","children":[["$","div",null,{"className":"flex items-center gap-2","children":[["$","h3",null,{"className":"text-sm font-medium","children":"access-control-scan"}],["$","span",null,{"className":"inline-flex items-center px-2 py-0.5 text-xs font-medium rounded-sm bg-surface-raised text-text-muted","children":"platform-services"}]]}],["$","$L2",null,{"content":"$8","previewLines":3}]]}],"$L9","$La","$Lb","$Lc","$Ld","$Le","$Lf","$L10","$L11"]}]]}]
+12:T1605,# Investigate WGS Ingestion Failure
+
+You are investigating a WGS ingestion Step Function failure in production. Follow each step. Do NOT ask for user input -- work autonomously.
+
+## Input
+
+$ARGUMENTS
+
+## Step 1: Parse the Alert
+
+Extract from the input text: `correlationId`, `wgsIngestionId`, `sfnError`, `sfnStatus`.
+
+If the input is missing required fields, write a report noting the parse failure and stop.
+
+## Step 2: Query Axiom
+
+Use `mcp__axiom__queryDataset` with `startTime` = `now-24h` and `endTime` = `now`.
+
+Trace the correlationId:
+
+```apl
+['bioscope-prod']
+| where correlationId == "<correlationId>"
+| order by _time asc
+```
+
+Search by wgsIngestionId:
+
+```apl
+['bioscope-prod']
+| where data.wgsIngestionId == "<wgsIngestionId>" or message contains "<wgsIngestionId>"
+| order by _time asc
+```
+
+Focus on ERROR-level entries. Record only the key log lines needed to explain the failure -- not the full trace.
+
+## Step 3: Cross-Reference Code
+
+Read the `PLATFORM_SERVICES_PATH` and `INFRASTRUCTURE_PATH` environment variables to locate the repos.
+
+### Application code (platform-services)
+
+1. `$PLATFORM_SERVICES_PATH/packages/wgs_ingestion_service/src/wgs_ingestion_service/handlers/handle_sfn_failure.py`
+2. `$PLATFORM_SERVICES_PATH/packages/wgs_ingestion_service/src/wgs_ingestion_service/handlers/handle_initiate_ingestion.py`
+3. `$PLATFORM_SERVICES_PATH/packages/bioscope_types/src/bioscope_types/dynamodb/wgs_ingestions.py`
+
+### Infrastructure (Terraform)
+
+If the error points to a Step Function state, Lambda config, IAM permissions, or resource limits, cross-reference these files:
+
+1. `$INFRASTRUCTURE_PATH/modules/aws/wgs_ingestion/sfn.tf` -- Step Function state machine definition and pipeline flow
+2. `$INFRASTRUCTURE_PATH/modules/aws/wgs_ingestion/lambda.tf` -- Lambda function configuration (memory, timeout, layers)
+3. `$INFRASTRUCTURE_PATH/modules/aws/wgs_ingestion/iam.tf` -- IAM roles and policies for the pipeline
+4. `$INFRASTRUCTURE_PATH/modules/aws/wgs_ingestion/eventbridge.tf` -- EventBridge rule that triggers on SFN failures
+5. `$INFRASTRUCTURE_PATH/modules/aws/wgs_ingestion/dynamodb.tf` -- DynamoDB table and index definitions
+
+The execution name format is `{wgs_ingestion_id}_{kit_id}_{timestamp}`.
+
+## Step 4: Classify the Failure
+
+**Default to Bug.** Only classify as Transient if you can point to specific evidence (see criteria below).
+
+- **Bug**: Code error, unhandled exception, missing IAM permissions, missing config, infrastructure misconfiguration. Requires a code or infra fix. **This is the default classification when the root cause is unclear.**
+- **Transient**: A failure that meets ALL of these criteria:
+  1. The error is a network timeout, AWS throttling, or a known transient pattern (see below)
+  2. There is no underlying code/config/IAM issue that caused it
+  3. A redrive would be expected to succeed WITHOUT any code or infrastructure changes
+- **Data issue**: Bad input, missing files, malformed data. Requires manual intervention.
+
+You MUST justify your classification in the Root Cause section. If classifying as Transient, explicitly state why a redrive would fix it without code changes.
+
+### Example Transient Errors
+
+These LOOK like data issues but are known transient -- classify as **Transient**:
+
+- **`INTERSECT_VARIANTS` / `KeyError: 'CHR:POS:A0:A1'` / "No variants in intersection"**: Intermittent failure in `pgsc_calc` during PRS generation. Resolves on redrive.
+
+### Example Bug Patterns
+
+These may LOOK transient but are bugs -- classify as **Bug**:
+
+- **S3 403 Forbidden on HeadObject/GetObject/PutObject**: Usually a missing IAM permission on the task role, not a temporary auth issue. Check the relevant IAM policy in infrastructure. Example: BIOENG-535 where `genomics-bam-subset-processor` was missing `s3:GetObject` on its output bucket.
+- **S3 404 Not Found on expected files**: Could indicate a missing deployment artifact, misconfigured path, or a race condition in the pipeline -- not transient.
+- **Persistent STS/credential errors on FARGATE_SPOT**: If the same error recurs on redrive or appears on non-spot tasks, it is an IAM issue, not credential expiration.
+
+## Step 5: Write the Report
+
+Write the report file as: `reports/YYYY-MM-DD_<first-8-chars-of-wgsIngestionId>.md`
+
+The `reports/` directory is in the current working directory. Verify with `Glob` that the directory exists before writing. If it does not exist, create it.
+
+Keep the report concise. Only include log lines that are directly relevant to explaining the failure cause.
+
+```
+# WGS Ingestion Failure Report
+
+## Summary
+
+| Field | Value |
+|-------|-------|
+| Date | YYYY-MM-DD HH:MM UTC |
+| Correlation ID | ... |
+| WGS Ingestion ID | ... |
+| Execution Name | ... |
+| SFN Error | ... |
+| SFN Status | ... |
+
+## Key Logs
+
+Only the log lines that explain the failure (oldest first):
+
+- `TIMESTAMP` [LEVEL] message (logGroup: ...)
+
+## Root Cause
+
+<1-3 sentences. What failed and why.>
+
+## Classification
+
+**<Transient | Bug | Data issue>**
+
+## Recommended Action
+
+<1-2 sentences.>
+
+### Redrive JSON
+
+If transient, include:
+
+{
+  "executionIds": ["<execution-name>"]
+}
+
+Env-task name: `redrive-wgs-ingestion-execution`
+```
+
+## Rules
+
+- Do NOT ask for user input. Work fully autonomously.
+- Do NOT include PII/PHI. Only UUIDs, error codes, timestamps, status values.
+- Do NOT use Bash commands. Use only Read, Glob, Grep, Write, and mcp__axiom__queryDataset.
+- If Axiom queries fail, proceed with code analysis and note the gap in the report.5:["$","div","wgs-ingestion-bot",{"className":"mb-8","children":[["$","h2",null,{"className":"text-xs font-medium text-text-dim uppercase tracking-wide mb-3","children":"wgs-ingestion-bot"}],["$","div",null,{"className":"space-y-3","children":[["$","div","/Users/gabry/Desktop/wgs-ingestion-bot/.claude/commands/investigate-wgs-ingestion.md",{"className":"border border-border rounded-sm p-5 ","children":[["$","div",null,{"className":"flex items-center gap-2","children":[["$","h3",null,{"className":"text-sm font-medium","children":"investigate-wgs-ingestion"}],["$","span",null,{"className":"inline-flex items-center px-2 py-0.5 text-xs font-medium rounded-sm bg-surface-raised text-text-muted","children":"wgs-ingestion-bot"}]]}],["$","$L2",null,{"content":"$12","previewLines":3}]]}]]}]]}]
+6:["$","script","script-0",{"src":"/_next/static/chunks/12p3iqtw2ohfq.js","async":true}]
+7:["$","$L13",null,{"children":["$","$14",null,{"name":"Next.MetadataOutlet","children":"$@15"}]}]
+16:Tf1d,# Add a New Model to llm-proxy-service
+
+Add a new LLM model to `llm-proxy-service`, ensuring accurate cost reporting.
+
+## Background
+
+- `litellm` contains bundled pricing data in `model_prices_and_context_window.json`
+- We disable litellm's automatic pricing fetch; we ONLY use the bundled pricing
+- If the bundled pricing is wrong or missing for a model, litellm reports $0 cost, which breaks our cost reporting
+- Overrides for incorrect pricing go in `platform-services/packages/llm_proxy_service/src/llm_proxy_service/service.py` via `litellm.register_model()`
+- **IMPORTANT**: Both `llm-proxy-service` and `embedding-service` depend on `litellm`. Their versions must always match. If this skill requires upgrading litellm, update BOTH packages.
+
+## Step 1: Gather information
+
+Ask the user:
+
+1. What model do they want to add? (e.g., `anthropic/claude-opus-4-5-20251101`)
+2. What is the provider's pricing page URL for this model?
+
+## Step 2: Determine the current litellm version
+
+Read `platform-services/packages/llm_proxy_service/pyproject.toml` to find the currently-used litellm version.
+
+## Step 3: Validate pricing in the current litellm version
+
+Use `uv run` to check if the model has correct pricing in the bundled litellm data:
+
+```bash
+uv run --with litellm==<CURRENT_VERSION> python -c "import litellm, json; print(json.dumps(litellm.model_cost.get('<model_key>', {}), indent=2))"
+```
+
+Note: The key in `litellm.model_cost` may not exactly match the model string. If an exact match isn't found, search for partial matches:
+
+```bash
+uv run --with litellm==<CURRENT_VERSION> python -c "import litellm; keys = [k for k in litellm.model_cost if '<partial_model_name>' in k]; print('\n'.join(sorted(keys)))"
+```
+
+Fetch the provider's pricing page and compare against the litellm pricing. Validate ALL of these fields:
+
+- `input_cost_per_token`
+- `output_cost_per_token`
+- `cache_read_input_token_cost` (if applicable)
+- `cache_creation_input_token_cost` (if applicable)
+
+Present the comparison to the user.
+
+## Step 4: Add the model
+
+### 4a. Add to LLMModel type
+
+Add the model string to the `LLMModel` Literal type in `platform-services/packages/bioscope_types/src/bioscope_types/services/llm_proxy_service.py`.
+
+- Place it in the correct provider group (bedrock, anthropic, vertex_ai, azure, groq)
+- Ensure the provider group has a comment linking to the pricing page (add one if it's a new provider)
+
+### 4b. Add pricing override (if needed)
+
+If the pricing is incorrect or missing in litellm, add an override in `platform-services/packages/llm_proxy_service/src/llm_proxy_service/service.py`:
+
+```python
+litellm.register_model(
+    {
+        "<model_key>": {
+            "input_cost_per_token": <value>,  # $X per 1M tokens
+            "output_cost_per_token": <value>,  # $X per 1M tokens
+            "cache_read_input_token_cost": <value>,  # $X per 1M tokens (if applicable)
+            "cache_creation_input_token_cost": <value>,  # $X per 1M tokens (if applicable)
+            "litellm_provider": "<provider>",
+            "max_input_tokens": <value>,
+            "max_output_tokens": <value>,
+            "mode": "chat",
+        }
+    }
+)
+```
+
+Include inline comments showing the human-readable cost (e.g., `# $3.00 per 1M tokens`).
+
+### 4c. Add to health check warmup (if needed)
+
+If the model requires additional env vars (vertex_ai, groq, or anthropic models), consider adding a `set_additional_env_vars()` call in the health check in `platform-services/packages/llm_proxy_service/src/llm_proxy_service/handler.py`. Only one model per provider prefix is needed for warmup.
+
+## Step 5: Validate
+
+1. Run `pnpm exec nx run bioscope-types:type-check` to verify the type is valid
+2. Run `pnpm exec nx run llm-proxy-service:test` to verify tests pass
+3. Run `pnpm exec nx run llm-proxy-service:lint` and `pnpm exec nx run llm-proxy-service:type-check`9:["$","div","/Users/gabry/Desktop/platform-services/.claude/commands/add-llm-proxy-service-model.md",{"className":"border border-border rounded-sm p-5 ","children":[["$","div",null,{"className":"flex items-center gap-2","children":[["$","h3",null,{"className":"text-sm font-medium","children":"add-llm-proxy-service-model"}],["$","span",null,{"className":"inline-flex items-center px-2 py-0.5 text-xs font-medium rounded-sm bg-surface-raised text-text-muted","children":"platform-services"}]]}],["$","$L2",null,{"content":"$16","previewLines":3}]]}]
+17:T1c43,# IDOR & Authorization Vulnerability Scan
+
+Scan ALL route handlers in platform-services for IDOR (Insecure Direct Object Reference) and authorization vulnerabilities.
+
+## How This Codebase Works
+
+This is a FastAPI-based backend. Key facts:
+
+- Routes *should* live in `packages/*/src/*/routes/*.py` (flag any routes that do not)
+- App setup files are at `packages/*/src/*/app.py`
+- Service-specific middleware may be at `packages/*/src/*/middleware.py`
+- Shared middleware is in `packages/shared_middleware/src/shared_middleware/`
+- Most routes are behind an API Gateway account authorizer that validates the JWT and verifies the user is a member of the account in the `Bioscope-Account-Id` header. For these routes, `account_id`, `user_id`, and `user_role` from headers can be trusted.
+- Some routes use a simpler JWT-only authorizer (e.g. `/accounts/me`, `/users/me`) or no authorizer at all (public endpoints). The authorizer config lives in infrastructure and is not visible from this repo, so don't make assumptions about which authorizer a given route uses — just focus on whether the route handler code itself properly validates ownership.
+- With the above two bullets in mind, `account_id`, `user_id`, and `user_role` can ONLY come from these headers and can NEVER come from path params, query params, request body, etc.
+
+### Auth/Authorization Patterns in Route Handlers
+
+**Patient validation (cross-service ownership check):**
+Routes with `{patient_id}` in the path MUST use `Depends(validate_patient_account_from_path_as_patient)` (or the factory `get_validate_patient_account`). This calls account-service to verify the patient belongs to the requesting account. A route that takes a patient_id without this dependency is an IDOR unless the route is checking the patient belongs to the account in its internal implementation.
+
+**Inline account ownership checks:**
+For non-patient resources (orders, EHR connections, etc.), routes typically fetch the resource and then check `if resource.account_id != account_id`. Missing this check on a resource lookup by ID is a potential IDOR.
+
+## Your Task
+
+### Step 1: Discover all services with routes
+
+Use glob to find all route files matching `packages/*/src/*/routes/*.py`. Group them by service. Also check for any routes that aren't under a `routes` directory and flag them.
+
+### Step 2: Create an output directory and spin up sub-agents
+
+First, create an output directory using Bash: `mkdir -p /tmp/idor-scan-results`
+
+Then, for each service, use the Task tool (subagent_type: "general-purpose") to scan that service's routes. Run these in parallel (include all Task tool calls in a single message). Each sub-agent should:
+
+1. Read ALL route files for that service
+2. Read the service's `app.py` to check what global dependencies/middleware are applied
+3. Read any service-specific `middleware.py` if it exists
+4. For each route handler, check for the vulnerabilities listed in Step 3
+5. **Write the report to a file** at `/tmp/idor-scan-results/<service-name>.md` using the format in Step 4
+6. **Return ONLY a one-line confirmation** (e.g., "Wrote report to /tmp/idor-scan-results/chat_service.md. 2 findings."). Do NOT return the full report — it's in the file.
+
+**IMPORTANT:** When calling the Task tool for each sub-agent, explicitly instruct it to write findings to the file and return only a brief one-line confirmation. The full report must go in the file, NOT in the return message. This prevents the main agent's context from overflowing.
+
+### Step 3: What to check per route
+
+For every route handler function, check for these IDOR vulnerabilities:
+
+- **Missing patient validation**: Route path contains `{patient_id}` but handler does NOT use `Depends(validate_patient_account_from_path_as_patient)` or equivalent
+- **Patient dependency result discarded**: Route uses `validate_patient_account_from_path_as_patient` but assigns the result to `_` instead of `patient`. The presence of the dependency alone is NOT sufficient — if the route also takes a sub-resource ID (e.g., `{chat_id}`, `{file_id}`, `{order_id}`), the validated `patient.patient_id` MUST be passed to the service layer and checked against the fetched resource's `patient_id`. A discarded `_` is a strong signal that this check is missing. Trace the full call chain to verify.
+- **Missing resource-to-account ownership**: Route takes a resource ID as a path/query/body param, fetches the resource, but does NOT verify `resource.account_id == account_id` before returning or mutating it
+- **Missing resource-to-patient ownership**: Route takes both a `{patient_id}` and another resource ID, fetches the resource, but does NOT verify `resource.patient_id == patient_id`. This applies even if the patient validation dependency is present — the dependency only confirms the patient belongs to the account, NOT that the sub-resource belongs to the patient. You must trace into the service layer to verify this check exists.
+- **Unscoped list/query endpoints**: Route returns a collection of resources (list/search/query) but the underlying query does NOT filter by `account_id` (or `patient_id` where applicable). Follow the call chain into the repository/data access layer to verify the query includes the appropriate scope filter.
+- **Using account, user, or user role not from header**: Route uses account id, user id, or user role from query param, path param, or request body and not from the trusted `Bioscope-Account-Id`, `Bioscope-User-Id`, and `Bioscope-User-Role` headers.
+
+### Step 4: Compile the report
+
+Each sub-agent should return its findings in this format:
+
+```text
+## <service-name>
+
+### Routes Scanned
+- `GET /path` — handler_name (file:line)
+- `POST /path` — handler_name (file:line)
+...
+
+### Findings
+
+#### Missing patient validation — `POST /patients/{patient_id}/resource`
+- **File**: path/to/file.py:123
+- **Handler**: `create_resource`
+- **Issue**: Route includes `{patient_id}` in path but does not use `validate_patient_account_from_path_as_patient`
+- **Confidence**: High / Medium / Low
+- **Notes**: <any relevant context>
+
+#### Missing ownership check — `GET /resource/{resource_id}`
+...
+
+### No Issues Found
+(list routes that were scanned and passed all checks)
+```
+
+### Step 5: Aggregate
+
+After all sub-agents complete, read each file from `/tmp/idor-scan-results/` and compile a final summary. To avoid context limits, read one file at a time and extract only the findings (skip the "No Issues Found" and "Routes Scanned" sections for clean services).
+
+Write the final report to `/tmp/idor-scan-results/SUMMARY.md` with:
+
+1. **Executive Summary**: Total routes scanned, total findings
+2. **Findings**: All IDOR vulnerabilities grouped by type
+3. **Clean Services**: List of services with no findings (names only)
+4. **Per-Service Details**: Full findings for services that had issues
+
+Then output the summary to the user.
+
+Be thorough. Read the actual code — don't guess based on function names alone. When in doubt about whether a check exists, read the called functions to see if ownership validation happens deeper in the call chain. If validation happens in a called function rather than at the route level, note it but don't flag it as a vulnerability.a:["$","div","/Users/gabry/Desktop/platform-services/.claude/commands/idor-scan.md",{"className":"border border-border rounded-sm p-5 ","children":[["$","div",null,{"className":"flex items-center gap-2","children":[["$","h3",null,{"className":"text-sm font-medium","children":"idor-scan"}],["$","span",null,{"className":"inline-flex items-center px-2 py-0.5 text-xs font-medium rounded-sm bg-surface-raised text-text-muted","children":"platform-services"}]]}],["$","$L2",null,{"content":"$17","previewLines":3}]]}]
+18:T2543,# PHI/PII Data Exposure Scan
+
+Scan ALL application code in platform-services for Protected Health Information (PHI) and Personally Identifiable Information (PII) exposure vulnerabilities. This covers logging, error responses, API over-fetching, and any other channel where sensitive data could leak.
+
+## What Constitutes PHI/PII in This Codebase
+
+### Patient PHI Fields (from `bioscope_types/dynamodb/patients.py`)
+- `first_name`, `last_name` (names)
+- `date_of_birth` (DOB)
+- `sex`
+- `mrn` (medical record number)
+- `address_line_1`, `address_line_2`, `city`, `state`, `zip_code`, `country` (address)
+- `phone_number`
+- `email`
+
+### User PII Fields (from `bioscope_types/dynamodb/users.py`)
+- `first_name`, `last_name`
+- `email`
+- `npi_number` (healthcare provider identifier)
+
+### Account PII Fields (from `bioscope_types/dynamodb/accounts.py`)
+- Address fields: `address_line_1`, `address_line_2`, `city`, `state`, `zip_code`, `country`
+
+### Other PHI Sources
+- FHIR resources (contain full patient demographics, diagnoses, medical history)
+- EHR data (clinical records, lab results, immunizations)
+- Genomic/WGS data and results
+- Chat messages about patients (may contain clinical discussions)
+- File contents (uploaded documents, lab reports)
+
+### Safe to Log
+- UUIDs (patient_id, account_id, user_id, order_id, etc.)
+- Timestamps
+- Status values and enums
+- Counts and metrics
+- Operation names and types
+- File IDs (not file contents or names that might contain patient info)
+
+## How Logging Works
+
+- `BioscopeLogger` (from `bioscope_logger` package) is the standard logger
+- Uses Python's `logging.LoggerAdapter` with JSON formatting
+- Supports `.child()` for adding context fields
+- Extra fields passed via `extra={}` parameter are serialized into the JSON log output
+- Logs go to stdout and optionally CloudWatch — all log output is persisted
+- `BioscopeLoggerDeps` injects the logger into FastAPI routes
+- Lambda handlers receive `logger: BioscopeLogger` via dependency injection
+
+## Your Task
+
+### Step 1: Discover all scannable code
+
+Use glob to find:
+1. All route files: `packages/*/src/*/routes/*.py`
+2. All handler files: `packages/*/src/*/handler.py`
+3. All handlers directories: `packages/*/src/*/handlers/*.py`
+4. All service/business logic files: `packages/*/src/*/*.py` (excluding `__init__.py`, `aws.py`, `app.py`)
+5. Any standalone scripts or local dev files: `packages/*/src/*/local.py`
+
+Group them by service/package.
+
+### Step 2: Create an output directory and spin up sub-agents
+
+First, create an output directory using Bash: `mkdir -p /tmp/phi-exposure-scan-results`
+
+Then, for each service/package, use the Task tool (subagent_type: "general-purpose") to scan that package's code. Run these in parallel (include all Task tool calls in a single message). Each sub-agent should:
+
+1. Read ALL Python source files for that package (routes, handlers, service modules, utilities)
+2. Check for every vulnerability type listed in Step 3
+3. **Write the report to a file** at `/tmp/phi-exposure-scan-results/<package-name>.md` using the format in Step 4
+4. **Return ONLY a one-line confirmation** (e.g., "Wrote report to /tmp/phi-exposure-scan-results/chat_service.md. 3 findings."). Do NOT return the full report — it's in the file.
+
+**IMPORTANT:** When calling the Task tool for each sub-agent, include the full list of PHI/PII fields from the "What Constitutes PHI/PII" section above so the sub-agent knows exactly what to look for. Instruct it to write findings to the file and return only a brief one-line confirmation. The full report must go in the file, NOT in the return message.
+
+### Step 3: What to check
+
+#### A. PHI/PII in Log Statements (CRITICAL)
+
+Search for all `logger.info`, `logger.warning`, `logger.error`, `logger.debug`, `logger.exception`, and `logger.critical` calls. For each, check:
+
+- **Full model dumps in logs**: Calls like `logger.info("...", extra={"patient": patient.model_dump()})` or `model_dump_json()` that serialize an entire Pydantic model containing PHI fields. This includes Patient, User, Account, or any FHIR resource model.
+- **PHI field values in log messages**: Direct references to PHI fields in log strings or extra dicts, e.g., `extra={"name": patient.first_name}`, `extra={"email": user.email}`, `extra={"dob": patient.date_of_birth}`.
+- **F-string or format-string PHI**: Log messages that interpolate PHI values, e.g., `logger.info(f"Created patient {patient.first_name} {patient.last_name}")`.
+- **Logging raw request/response bodies**: Logging full HTTP request bodies or response payloads that may contain PHI, e.g., `logger.info("Request", extra={"body": request.body()})`.
+- **Logging full event payloads**: SQS/SNS/EventBridge event payloads logged in full when they may contain PHI fields.
+- **Logging FHIR resources**: Any FHIR Bundle, Patient, Observation, Immunization, or other clinical resource logged in full.
+
+#### B. PHI/PII in Error Responses (HIGH)
+
+Check all `HTTPException` raises and error response construction:
+
+- **PHI in HTTPException detail**: `raise HTTPException(status_code=..., detail=f"Patient {patient.first_name} not found")` — the detail message should never contain PHI, only IDs or generic messages.
+- **PHI in custom error response models**: Any error response class that includes PHI fields.
+- **Full exception messages with PHI**: Exception handlers that return `str(e)` where the exception message might contain PHI from a database query or validation error.
+
+#### C. PHI/PII in API Response Over-Fetching (MEDIUM)
+
+Check route return values and response models:
+
+- **Returning full patient/user records when not needed**: A route that returns a complete Patient object with all fields when the consumer only needs a subset (e.g., patient_id and status).
+
+#### D. PHI/PII in URLs and Query Parameters (HIGH)
+
+- **Patient data in query strings**: Routes that accept PHI as query parameters (e.g., `?name=John&dob=1990-01-01`). Query strings end up in access logs, browser history, and CDN logs. Only IDs should be in URLs.
+- **PHI in path parameters**: Path params should only contain UUIDs or opaque identifiers, never names, emails, or other PHI.
+
+#### E. PHI/PII in Development/Debug Code (MEDIUM)
+
+- **Local development files**: Files like `local.py` or scripts that log full records for debugging but exist in the production codebase.
+- **Commented-out debug logging**: Commented code that logs PHI — a developer might uncomment it and forget to remove it.
+- **Print statements with PHI**: Any `print()` calls that output PHI (should use logger instead, but print output also goes to CloudWatch).
+
+#### F. Missing Data Sanitization (LOW)
+
+- **No redaction utilities**: Note if the codebase lacks any sanitization/redaction utilities for PHI fields. This is an architectural observation, not a per-route vulnerability.
+- **PHI passed through multiple layers without scrubbing**: Trace data flow where PHI enters the system (e.g., from account-service or EHR) and check if it's ever inadvertently logged along the way.
+
+### Step 4: Report format
+
+Each sub-agent should write findings in this format:
+
+```text
+## <package-name>
+
+### Files Scanned
+- path/to/file.py
+- path/to/other_file.py
+...
+
+### Findings
+
+#### [CRITICAL] Full patient model logged — service.py:45
+- **File**: path/to/file.py:45
+- **Code**: `logger.info("Patient: ", extra={"patient": patient.model_dump_json()})`
+- **Category**: PHI in log statements
+- **PHI Fields Exposed**: first_name, last_name, date_of_birth, email, phone_number, address, mrn
+- **Notes**: Logs the entire Patient FHIR resource including all demographics
+
+#### [HIGH] PHI in error response — routes/patients.py:78
+- **File**: path/to/file.py:78
+- **Code**: `raise HTTPException(detail=f"Patient {patient.first_name} not found")`
+- **Category**: PHI in error responses
+- **PHI Fields Exposed**: first_name
+- **Notes**: Patient name included in 404 error detail
+
+### No Issues Found
+(list files that were scanned and passed all checks)
+```
+
+Severity levels:
+- **CRITICAL**: Full model dumps or FHIR resources in logs, multiple PHI fields exposed
+- **HIGH**: Individual PHI fields in logs or error responses, PHI in URLs
+- **MEDIUM**: Over-fetching in API responses, debug/dev code with PHI
+- **LOW**: Architectural observations, missing sanitization utilities
+
+### Step 5: Aggregate
+
+After all sub-agents complete, read each file from `/tmp/phi-exposure-scan-results/` and compile a final summary. To avoid context limits, read one file at a time and extract only the findings.
+
+Write the final report to `/tmp/phi-exposure-scan-results/SUMMARY.md` with:
+
+1. **Executive Summary**: Total files scanned, total findings by severity (CRITICAL/HIGH/MEDIUM/LOW)
+2. **CRITICAL Findings**: All critical PHI exposure issues (immediate remediation needed)
+3. **HIGH Findings**: High-severity issues
+4. **MEDIUM Findings**: Medium-severity issues
+5. **LOW Findings & Observations**: Low-severity items and architectural notes
+6. **Clean Packages**: List of packages with no findings (names only)
+7. **Recommendations**: Actionable remediation steps, prioritized by severity
+
+Then output the summary to the user.
+
+Be thorough. Read the actual code — don't guess based on function names alone. When checking log statements, look at what the `extra` dict actually contains. When checking for model dumps, trace the model class to see what fields it includes. If a model only contains safe fields (IDs, timestamps, statuses), it's not a PHI exposure even if it's logged via `model_dump()`.b:["$","div","/Users/gabry/Desktop/platform-services/.claude/commands/phi-exposure-scan.md",{"className":"border border-border rounded-sm p-5 ","children":[["$","div",null,{"className":"flex items-center gap-2","children":[["$","h3",null,{"className":"text-sm font-medium","children":"phi-exposure-scan"}],["$","span",null,{"className":"inline-flex items-center px-2 py-0.5 text-xs font-medium rounded-sm bg-surface-raised text-text-muted","children":"platform-services"}]]}],["$","$L2",null,{"content":"$18","previewLines":3}]]}]
+19:T1b86,# Upgrade litellm in llm-proxy-service
+
+Upgrade the `litellm` dependency in `llm-proxy-service` to a new version, validating that all supported models have correct pricing.
+
+## Background
+
+- `litellm` contains bundled pricing data in `model_prices_and_context_window.json`
+- We disable litellm's automatic pricing fetch; we ONLY use the bundled pricing
+- If the bundled pricing is wrong or missing for a model, litellm reports $0 cost, which breaks our cost reporting
+- Overrides for incorrect pricing go in `platform-services/packages/llm_proxy_service/src/llm_proxy_service/service.py` via `litellm.register_model()`
+- **IMPORTANT**: Both `llm-proxy-service` and `embedding-service` depend on `litellm`. Their versions must always match. When upgrading, update BOTH `platform-services/packages/llm_proxy_service/pyproject.toml` and `platform-services/packages/embedding_service/pyproject.toml`.
+
+## Step 1: Ask the user what version to upgrade to
+
+First, read the current litellm version from `platform-services/packages/llm_proxy_service/pyproject.toml`. Then, fetch the latest available versions from PyPI:
+
+```bash
+curl -s "https://pypi.org/pypi/litellm/json" | python3 -c "import sys,json; releases=sorted(json.load(sys.stdin)['releases'].keys(), key=lambda v: [int(x) for x in v.split('.')[:3] if x.isdigit()], reverse=True); print('\n'.join(releases[:5]))"
+```
+
+Use AskUserQuestion to present the user with a selection of versions. Include the 3-4 most recent versions as options, labeling the latest one with "(Latest)". The user can also type a different version via the "Other" option. Mention the current version in the question text so the user knows what they're upgrading from.
+
+## Step 2: Identify all supported models
+
+Read the `LLMModel` type definition in `platform-services/packages/bioscope_types/src/bioscope_types/services/llm_proxy_service.py` to get all supported models. Group them by provider:
+
+- `bedrock/` models (Anthropic on AWS Bedrock)
+- `anthropic/` models (direct Anthropic API)
+- `vertex_ai/` models (Google Vertex AI)
+- `azure/` models (Azure OpenAI)
+- `groq/` models (Groq)
+- etc.
+
+Also read the current litellm version from `platform-services/packages/llm_proxy_service/pyproject.toml`.
+
+Also read `platform-services/packages/llm_proxy_service/src/llm_proxy_service/service.py` to identify any existing `litellm.register_model()` overrides.
+
+## Step 3: Create output directory and spin up sub-agents per provider
+
+First, create an output directory using Bash: `mkdir -p /tmp/litellm-upgrade`
+
+Then, for EACH provider (bedrock, anthropic, vertex_ai, azure, groq), spin up a sub-agent using the Task tool (subagent_type: "general-purpose"). Run all provider sub-agents **in parallel** (include all Task tool calls in a single message). **Do NOT run these in the background** — they need to be foreground agents so they can prompt for tool permissions.
+
+Each sub-agent should:
+
+1. **Check pricing in the NEW version** of litellm for every model belonging to that provider. Use `uv run` to inspect the bundled pricing data:
+
+   ```bash
+   uv run --with litellm==<NEW_VERSION> python -c "import litellm, json; print(json.dumps(litellm.model_cost.get('<model_key>', {}), indent=2))"
+   ```
+
+   Note: The key in `litellm.model_cost` may not exactly match the model string in `LLMModel`. For example, `bedrock/us.anthropic.claude-sonnet-4-5-20250929-v1:0` may be keyed as `us.anthropic.claude-sonnet-4-5-20250929-v1:0` or similar. If an exact match isn't found, search for partial matches:
+
+   ```bash
+   uv run --with litellm==<NEW_VERSION> python -c "import litellm; keys = [k for k in litellm.model_cost if '<partial_model_name>' in k]; print('\n'.join(sorted(keys)))"
+   ```
+
+2. **Fetch the provider's pricing page** (linked in the `LLMModel` comments) and compare the litellm pricing against the actual provider pricing. Key fields to validate:
+   - `input_cost_per_token`
+   - `output_cost_per_token`
+   - `cache_read_input_token_cost` (if applicable)
+   - `cache_creation_input_token_cost` (if applicable)
+
+3. **Also check the OLD (current) version** to see if any existing overrides can be removed because the new version has correct pricing:
+
+   ```bash
+   uv run --with litellm==<OLD_VERSION> python -c "import litellm, json; print(json.dumps(litellm.model_cost.get('<model_key>', {}), indent=2))"
+   ```
+
+4. **Write findings to a file** at `/tmp/litellm-upgrade/<provider>.md` with this format:
+
+```text
+   ## <provider> Models
+
+   ### <model_name>
+   - **Provider pricing page**: <url>
+   - **Expected input cost**: $X per 1M tokens
+   - **Expected output cost**: $X per 1M tokens
+   - **Expected cached input cost**: $X per 1M tokens (if applicable)
+   - **litellm (new version) input cost**: $X per 1M tokens
+   - **litellm (new version) output cost**: $X per 1M tokens
+   - **litellm (new version) cached input cost**: $X per 1M tokens
+   - **Status**: CORRECT / INCORRECT / MISSING
+   - **Override needed**: Yes (details) / No
+   ```
+
+5. **Return ONLY a single sentence** summarizing findings (e.g., "All 3 Anthropic models have correct pricing in the new version." or "2 of 5 Bedrock models have incorrect cached input pricing."). The full report is in the file — do NOT return it in the response.
+
+**IMPORTANT:** When calling the Task tool for each sub-agent, explicitly instruct it to write findings to the file and return only a brief single-sentence confirmation. The full report must go in the file, NOT in the return message. This prevents the main agent's context from overflowing.
+
+## Step 4: Spin up a final evaluation sub-agent
+
+After all provider sub-agents complete, spin up ONE final sub-agent (subagent_type: "general-purpose") that:
+
+1. Reads all files in `/tmp/litellm-upgrade/`
+2. Compiles a summary of which models need overrides and which are correct
+3. Writes a final report to `/tmp/litellm-upgrade/SUMMARY.md`
+4. Returns ONLY a single sentence summary (e.g., "3 models need pricing overrides, 15 are correct. See /tmp/litellm-upgrade/SUMMARY.md for details.")
+
+Then read `/tmp/litellm-upgrade/SUMMARY.md` and present the findings to the user.
+
+## Step 5: Implement the upgrade
+
+After presenting findings to the user and getting their approval:
+
+1. Update the litellm version in BOTH:
+   - `platform-services/packages/llm_proxy_service/pyproject.toml`
+   - `platform-services/packages/embedding_service/pyproject.toml`
+2. Add any needed `litellm.register_model()` overrides in `platform-services/packages/llm_proxy_service/src/llm_proxy_service/service.py`
+3. Remove any existing overrides that are no longer needed (because the new version has correct pricing)
+4. Run `uv sync --all-packages` from the `platform-services/` directory to update the lock file
+5. Run `pnpm exec nx run llm-proxy-service:test` to verify tests pass
+6. Run `pnpm exec nx run llm-proxy-service:lint` and `pnpm exec nx run llm-proxy-service:type-check`
+7. Run `pnpm exec nx run embedding-service:test`, `pnpm exec nx run embedding-service:lint`, and `pnpm exec nx run embedding-service:type-check`c:["$","div","/Users/gabry/Desktop/platform-services/.claude/commands/upgrade-litellm.md",{"className":"border border-border rounded-sm p-5 ","children":[["$","div",null,{"className":"flex items-center gap-2","children":[["$","h3",null,{"className":"text-sm font-medium","children":"upgrade-litellm"}],["$","span",null,{"className":"inline-flex items-center px-2 py-0.5 text-xs font-medium rounded-sm bg-surface-raised text-text-muted","children":"platform-services"}]]}],["$","$L2",null,{"content":"$19","previewLines":3}]]}]
+1a:T368e,# Broken Access Control Scan
+
+Scan ALL route handlers and Lambda handlers in platform-services for broken access control vulnerabilities beyond IDOR (which is covered by the separate `idor-scan` command).
+
+## How This Codebase Works
+
+This is a FastAPI-based backend. Key facts:
+
+- Routes live in `packages/*/src/*/routes/*.py`
+- App setup files are at `packages/*/src/*/app.py`
+- Lambda handlers are at `packages/*/src/*/handler.py`
+- Service-specific middleware may be at `packages/*/src/*/middleware.py`
+- Shared middleware is in `packages/shared_middleware/src/shared_middleware/`
+- Most routes are behind an API Gateway account authorizer that validates the JWT and sets trusted headers: `Bioscope-Account-Id`, `Bioscope-User-Id`, `Bioscope-User-Role`, `Bioscope-Is-Demo-User`
+- Some routes use a simpler JWT-only authorizer or no authorizer at all (public endpoints). The authorizer config lives in infrastructure and is not visible from this repo.
+
+### Standard Middleware Stack
+
+Every FastAPI service should mount these middlewares in this order in `app.py`:
+
+```python
+app = FastAPI(title="service-name", dependencies=[Depends(enforce_demo_read_only)])
+app.add_middleware(WithExceptionLoggingMiddleware)
+app.add_middleware(WithMetadataLoggingMiddleware)
+app.add_middleware(WithLoggerMiddleware)
+```
+
+And include routers via `app.include_router(...)`.
+
+### Role-Based Access Control
+
+The codebase has a single role validation dependency:
+
+- `require_owner_role` in `shared_middleware/role_validation.py` — checks `Bioscope-User-Role` header equals `"owner"`, raises 403 otherwise
+- Used as `RequireOwnerRoleDeps = Annotated[None, Depends(require_owner_role)]`
+
+Role is set by the API Gateway authorizer from the user's account membership record in DynamoDB.
+
+### Demo Mode
+
+- `enforce_demo_read_only` is applied as a global FastAPI dependency — blocks all non-GET/HEAD/OPTIONS requests for demo users
+- Routes can opt in to allow demo writes with the `@allow_demo_writes` decorator
+
+### Header Dependencies
+
+Trusted headers are injected via these typed dependencies (from `shared_middleware/headers.py`):
+
+- `BioscopeAccountIdHeaderDeps` — `Bioscope-Account-Id`
+- `BioscopeUserIdHeaderDeps` — `Bioscope-User-Id`
+- `BioscopeUserRoleHeaderDeps` — `Bioscope-User-Role`
+- `BioscopeCorrelationIdHeaderDeps` — `Bioscope-Correlation-Id`
+- `BioscopeInternalApiKeyHeaderDeps` — `Bioscope-Internal-Api-Key`
+- `BioscopeIsDemoUserHeaderDeps` — `Bioscope-Is-Demo-User`
+
+## Your Task
+
+### Step 1: Discover all services
+
+Use glob to find:
+1. All route files: `packages/*/src/*/routes/*.py`
+2. All app files: `packages/*/src/*/app.py`
+3. All handler files: `packages/*/src/*/handler.py`
+4. All handler directories: `packages/*/src/*/handlers/*.py`
+
+Group them by service. A service may have routes (FastAPI), handlers (Lambda), or both.
+
+### Step 2: Create an output directory and spin up sub-agents
+
+First, create an output directory using Bash: `mkdir -p access-control-scan-results` (in the repo root directory).
+
+Then, for **every service** (both route-based and handler-only), use the Task tool (subagent_type: "general-purpose") to scan that service.
+
+#### Parallelism guidelines
+
+**CRITICAL: Do NOT launch all agents at once.** This codebase has many services (typically 50+). Launching too many parallel agents causes resource contention, slow completions, and permission prompt overload.
+
+Instead, process services in **batches of 5 agents at a time**:
+
+1. **Batch 1**: Launch 5 route-based service agents in parallel (in a single message with 5 Task tool calls). Run them in background (`run_in_background: true`).
+2. **Wait**: After launching a batch, wait for all agents in the batch to complete before launching the next batch. Check completion by reading the output files or using TaskOutput.
+3. **Batch 2**: Launch the next 5 route-based services.
+4. **Continue**: Repeat until all route-based services are scanned, then do the same for handler-only services.
+
+For **handler-only services**, you may group 3-5 related services into a single agent (e.g., all `*_event_consumer` services in one agent) since they are simpler to scan. This reduces the total number of agents needed. Each grouped agent should write **separate report files** for each service it scans.
+
+#### What each sub-agent should do
+
+**For services with route files**, each sub-agent should:
+1. Read ALL route files for that service
+2. Read the service's `app.py` to check middleware mounting and global dependencies
+3. Read any service-specific `middleware.py` if it exists
+4. For each route handler, check for the vulnerabilities listed in Step 3
+5. **Write the report to a file** at `access-control-scan-results/<service-name>.md` (relative to the repo root) using the format in Step 4
+6. **Return ONLY a one-line confirmation** (e.g., "Wrote report to access-control-scan-results/chat_service.md. 2 findings."). Do NOT return the full report — it's in the file.
+
+**For handler-only services** (no route files, only `handler.py` and optionally `handlers/*.py`), each sub-agent should:
+1. Read the service's `handler.py` and all files in `handlers/` if present
+2. For each Lambda handler (decorated with `@handler.sqs`, `@handler.sns`, `@handler.direct_invocation`, `@handler.event_bridge`, `@handler.authorizer`), check for the vulnerabilities listed in Step 3 section E
+3. **Write the report to a file** at `access-control-scan-results/<service-name>.md` (relative to the repo root) using the format in Step 4
+4. **Return ONLY a one-line confirmation**
+
+**IMPORTANT:** When calling the Task tool for each sub-agent, explicitly instruct it to write findings to the file and return only a brief one-line confirmation. The full report must go in the file, NOT in the return message. This prevents the main agent's context from overflowing.
+
+### Step 3: What to check per service and route
+
+#### A. Middleware and App-Level Checks
+
+For each service's `app.py`, verify:
+
+- **Missing standard middleware**: The app MUST mount all three middlewares (`WithExceptionLoggingMiddleware`, `WithMetadataLoggingMiddleware`, `WithLoggerMiddleware`). Flag any that are missing.
+- **Missing demo mode enforcement**: The app MUST have `dependencies=[Depends(enforce_demo_read_only)]` on the `FastAPI()` constructor. Flag if missing.
+- **Non-standard middleware ordering**: Middlewares execute in reverse order of addition (LIFO). `WithLoggerMiddleware` must be added last so it executes first. Flag incorrect ordering.
+- **Routes mounted outside the app**: Check if any route files exist that are NOT included via `app.include_router(...)`. These routes would bypass all app-level middleware and dependencies.
+
+#### B. Role-Based Access Control Checks
+
+For each route handler, check:
+
+- **Sensitive mutations without role checks**: Routes that perform destructive or admin-level operations (DELETE endpoints, account settings changes, user management, billing operations) should use `RequireOwnerRoleDeps` or `Depends(require_owner_role)`. Flag mutation endpoints that handle sensitive operations without any role check. Use your judgment — not every POST/PATCH/DELETE needs a role check, but operations like deleting accounts, managing users, or changing account settings do.
+- **Role from untrusted source**: Any route that reads a role from path params, query params, or request body instead of the `Bioscope-User-Role` header. The role MUST come from the trusted header dependency.
+
+#### C. Authentication/Authorization Gaps
+
+For each route handler, check:
+
+- **Missing identity headers**: Routes that perform any data access or mutation but do NOT inject `BioscopeAccountIdHeaderDeps` or `BioscopeUserIdHeaderDeps`. Every non-public route should use at least the account ID header to scope its operations.
+- **Hardcoded or default account/user IDs**: Any route that uses a hardcoded UUID or default value for account_id or user_id instead of extracting from headers.
+- **Internal API key routes without validation**: Routes that accept `BioscopeInternalApiKeyHeaderDeps` should validate the key value against an expected secret, not just check that the header is present.
+
+#### D. Demo Mode Bypass
+
+- **Mutation routes with @allow_demo_writes that shouldn't have it**: The `@allow_demo_writes` decorator should only be on routes where demo users legitimately need write access (e.g., creating a chat for a demo walkthrough). Flag any destructive operations (DELETE, account mutations) that have this decorator.
+
+#### E. Lambda Handler Checks (for handler-only and hybrid services)
+
+Lambda handlers (`@handler.sqs`, `@handler.sns`, `@handler.direct_invocation`, `@handler.event_bridge`) are internal-facing and trust their event sources by design (IAM policies and queue/topic access policies control who can invoke them). The checks below focus on risks that remain even within that trust model.
+
+For each Lambda handler, check:
+
+- **Unscoped destructive operations**: Direct invocation or event-driven handlers that perform bulk deletes, account mutations, or data purges without scoping to a specific `account_id` or `patient_id` from the event payload. A handler that deletes "all matching records" rather than scoping by the account/patient in the event is dangerous if it ever receives malformed input.
+- **Missing account/patient scoping on queries**: Handlers that query DynamoDB or other data stores without filtering by `account_id` or `patient_id` when the event payload contains those identifiers. The handler should use the event's IDs to scope its operations, not fetch all records globally.
+- **Sensitive operations in direct invocation handlers without caller context**: Direct invocation handlers that perform admin-level operations (creating users, modifying account settings, issuing credentials) should accept and log a `correlation_id` or caller identifier for audit trail. Flag handlers that perform sensitive mutations with no traceability to the original caller.
+- **Event payload used to construct external requests without validation**: Handlers that take URLs, email addresses, or external identifiers from event payloads and pass them directly to external services (HTTP calls, email sends, S3 operations). Validate that the handler sanitizes or validates these inputs rather than blindly trusting them.
+- **Internal API key routes without key validation**: Any HTTP route (in hybrid services that have both routes and handlers) that accepts `BioscopeInternalApiKeyHeaderDeps` should validate the key value against an expected secret, not just check that the header is present.
+
+**Important context for sub-agents**: Do NOT flag handler-level findings for the following, as these are expected patterns:
+- Direct invocation handlers that don't have API Gateway-style JWT authorization — they're internal Lambda-to-Lambda calls secured by IAM
+- SQS/SNS handlers that trust `account_id` or `patient_id` from the event body — the event source is trusted
+- Handlers that don't inject `BioscopeAccountIdHeaderDeps` — header dependencies are for HTTP routes only, not Lambda handlers
+
+### Step 4: Report format
+
+Each sub-agent should write findings in this format:
+
+**For services with routes (FastAPI):**
+
+```text
+## <service-name>
+
+### App-Level Configuration
+- **Middleware**: [All present / Missing: <list>]
+- **Demo mode**: [Enforced / MISSING]
+- **Middleware order**: [Correct / INCORRECT: <details>]
+- **Unmounted routes**: [None / <list>]
+
+### Routes Scanned
+- `GET /path` — handler_name (file:line)
+- `POST /path` — handler_name (file:line)
+...
+
+### Findings
+
+#### Missing role check on sensitive mutation — `DELETE /resource/{id}`
+- **File**: path/to/file.py:123
+- **Handler**: `delete_resource`
+- **Issue**: Destructive operation with no role validation
+- **Confidence**: High / Medium / Low
+- **Notes**: <any relevant context>
+
+#### Missing identity headers — `GET /resource`
+...
+
+### No Issues Found
+(list routes that were scanned and passed all checks)
+```
+
+**For handler-only services (Lambda):**
+
+```text
+## <service-name>
+
+### Handlers Scanned
+- `@handler.sqs(queue_name="queue-name")` — handler_function (file:line)
+- `@handler.direct_invocation()` — handler_function (file:line)
+- `@handler.event_bridge()` — handler_function (file:line)
+...
+
+### Findings
+
+#### Unscoped destructive operation — handle_delete_event
+- **File**: path/to/handler.py:45
+- **Handler**: `handle_delete_event`
+- **Decorator**: `@handler.sqs(queue_name="...")`
+- **Issue**: Deletes records without scoping to account_id from event payload
+- **Confidence**: High / Medium / Low
+- **Notes**: <any relevant context>
+
+### No Issues Found
+(list handlers that were scanned and passed all checks)
+```
+
+### Step 5: Aggregate
+
+After all sub-agents complete, read each file from `access-control-scan-results/` and compile a final summary. To avoid context limits, read one file at a time and extract only the findings (skip the "No Issues Found" and "Routes Scanned" sections for clean services).
+
+Write the final report to `access-control-scan-results/SUMMARY.md` with:
+
+1. **Executive Summary**: Total services scanned (route-based + handler-only), total routes/handlers scanned, total findings by category
+2. **App-Level Issues**: Any services with middleware or configuration problems
+3. **Route-Level Findings**: All access control vulnerabilities in FastAPI routes, grouped by type
+4. **Handler-Level Findings**: All access control vulnerabilities in Lambda handlers, grouped by type
+5. **Clean Services**: List of services with no findings (names only)
+6. **Per-Service Details**: Full findings for services that had issues
+
+Then output the summary to the user.
+
+Be thorough. Read the actual code — don't guess based on function names alone. When checking for role validation, trace the full dependency chain. If a role check happens in a called function or middleware rather than at the route level, note it but don't flag it as a vulnerability.d:["$","div","/Users/gabry/Desktop/ps-copy/platform-services/.claude/commands/access-control-scan.md",{"className":"border border-border rounded-sm p-5 ","children":[["$","div",null,{"className":"flex items-center gap-2","children":[["$","h3",null,{"className":"text-sm font-medium","children":"access-control-scan"}],["$","span",null,{"className":"inline-flex items-center px-2 py-0.5 text-xs font-medium rounded-sm bg-surface-raised text-text-muted","children":"platform-services"}]]}],["$","$L2",null,{"content":"$1a","previewLines":3}]]}]
+1b:Tf1d,# Add a New Model to llm-proxy-service
+
+Add a new LLM model to `llm-proxy-service`, ensuring accurate cost reporting.
+
+## Background
+
+- `litellm` contains bundled pricing data in `model_prices_and_context_window.json`
+- We disable litellm's automatic pricing fetch; we ONLY use the bundled pricing
+- If the bundled pricing is wrong or missing for a model, litellm reports $0 cost, which breaks our cost reporting
+- Overrides for incorrect pricing go in `platform-services/packages/llm_proxy_service/src/llm_proxy_service/service.py` via `litellm.register_model()`
+- **IMPORTANT**: Both `llm-proxy-service` and `embedding-service` depend on `litellm`. Their versions must always match. If this skill requires upgrading litellm, update BOTH packages.
+
+## Step 1: Gather information
+
+Ask the user:
+
+1. What model do they want to add? (e.g., `anthropic/claude-opus-4-5-20251101`)
+2. What is the provider's pricing page URL for this model?
+
+## Step 2: Determine the current litellm version
+
+Read `platform-services/packages/llm_proxy_service/pyproject.toml` to find the currently-used litellm version.
+
+## Step 3: Validate pricing in the current litellm version
+
+Use `uv run` to check if the model has correct pricing in the bundled litellm data:
+
+```bash
+uv run --with litellm==<CURRENT_VERSION> python -c "import litellm, json; print(json.dumps(litellm.model_cost.get('<model_key>', {}), indent=2))"
+```
+
+Note: The key in `litellm.model_cost` may not exactly match the model string. If an exact match isn't found, search for partial matches:
+
+```bash
+uv run --with litellm==<CURRENT_VERSION> python -c "import litellm; keys = [k for k in litellm.model_cost if '<partial_model_name>' in k]; print('\n'.join(sorted(keys)))"
+```
+
+Fetch the provider's pricing page and compare against the litellm pricing. Validate ALL of these fields:
+
+- `input_cost_per_token`
+- `output_cost_per_token`
+- `cache_read_input_token_cost` (if applicable)
+- `cache_creation_input_token_cost` (if applicable)
+
+Present the comparison to the user.
+
+## Step 4: Add the model
+
+### 4a. Add to LLMModel type
+
+Add the model string to the `LLMModel` Literal type in `platform-services/packages/bioscope_types/src/bioscope_types/services/llm_proxy_service.py`.
+
+- Place it in the correct provider group (bedrock, anthropic, vertex_ai, azure, groq)
+- Ensure the provider group has a comment linking to the pricing page (add one if it's a new provider)
+
+### 4b. Add pricing override (if needed)
+
+If the pricing is incorrect or missing in litellm, add an override in `platform-services/packages/llm_proxy_service/src/llm_proxy_service/service.py`:
+
+```python
+litellm.register_model(
+    {
+        "<model_key>": {
+            "input_cost_per_token": <value>,  # $X per 1M tokens
+            "output_cost_per_token": <value>,  # $X per 1M tokens
+            "cache_read_input_token_cost": <value>,  # $X per 1M tokens (if applicable)
+            "cache_creation_input_token_cost": <value>,  # $X per 1M tokens (if applicable)
+            "litellm_provider": "<provider>",
+            "max_input_tokens": <value>,
+            "max_output_tokens": <value>,
+            "mode": "chat",
+        }
+    }
+)
+```
+
+Include inline comments showing the human-readable cost (e.g., `# $3.00 per 1M tokens`).
+
+### 4c. Add to health check warmup (if needed)
+
+If the model requires additional env vars (vertex_ai, groq, or anthropic models), consider adding a `set_additional_env_vars()` call in the health check in `platform-services/packages/llm_proxy_service/src/llm_proxy_service/handler.py`. Only one model per provider prefix is needed for warmup.
+
+## Step 5: Validate
+
+1. Run `pnpm exec nx run bioscope-types:type-check` to verify the type is valid
+2. Run `pnpm exec nx run llm-proxy-service:test` to verify tests pass
+3. Run `pnpm exec nx run llm-proxy-service:lint` and `pnpm exec nx run llm-proxy-service:type-check`e:["$","div","/Users/gabry/Desktop/ps-copy/platform-services/.claude/commands/add-llm-proxy-service-model.md",{"className":"border border-border rounded-sm p-5 ","children":[["$","div",null,{"className":"flex items-center gap-2","children":[["$","h3",null,{"className":"text-sm font-medium","children":"add-llm-proxy-service-model"}],["$","span",null,{"className":"inline-flex items-center px-2 py-0.5 text-xs font-medium rounded-sm bg-surface-raised text-text-muted","children":"platform-services"}]]}],["$","$L2",null,{"content":"$1b","previewLines":3}]]}]
+1c:T1c43,# IDOR & Authorization Vulnerability Scan
+
+Scan ALL route handlers in platform-services for IDOR (Insecure Direct Object Reference) and authorization vulnerabilities.
+
+## How This Codebase Works
+
+This is a FastAPI-based backend. Key facts:
+
+- Routes *should* live in `packages/*/src/*/routes/*.py` (flag any routes that do not)
+- App setup files are at `packages/*/src/*/app.py`
+- Service-specific middleware may be at `packages/*/src/*/middleware.py`
+- Shared middleware is in `packages/shared_middleware/src/shared_middleware/`
+- Most routes are behind an API Gateway account authorizer that validates the JWT and verifies the user is a member of the account in the `Bioscope-Account-Id` header. For these routes, `account_id`, `user_id`, and `user_role` from headers can be trusted.
+- Some routes use a simpler JWT-only authorizer (e.g. `/accounts/me`, `/users/me`) or no authorizer at all (public endpoints). The authorizer config lives in infrastructure and is not visible from this repo, so don't make assumptions about which authorizer a given route uses — just focus on whether the route handler code itself properly validates ownership.
+- With the above two bullets in mind, `account_id`, `user_id`, and `user_role` can ONLY come from these headers and can NEVER come from path params, query params, request body, etc.
+
+### Auth/Authorization Patterns in Route Handlers
+
+**Patient validation (cross-service ownership check):**
+Routes with `{patient_id}` in the path MUST use `Depends(validate_patient_account_from_path_as_patient)` (or the factory `get_validate_patient_account`). This calls account-service to verify the patient belongs to the requesting account. A route that takes a patient_id without this dependency is an IDOR unless the route is checking the patient belongs to the account in its internal implementation.
+
+**Inline account ownership checks:**
+For non-patient resources (orders, EHR connections, etc.), routes typically fetch the resource and then check `if resource.account_id != account_id`. Missing this check on a resource lookup by ID is a potential IDOR.
+
+## Your Task
+
+### Step 1: Discover all services with routes
+
+Use glob to find all route files matching `packages/*/src/*/routes/*.py`. Group them by service. Also check for any routes that aren't under a `routes` directory and flag them.
+
+### Step 2: Create an output directory and spin up sub-agents
+
+First, create an output directory using Bash: `mkdir -p /tmp/idor-scan-results`
+
+Then, for each service, use the Task tool (subagent_type: "general-purpose") to scan that service's routes. Run these in parallel (include all Task tool calls in a single message). Each sub-agent should:
+
+1. Read ALL route files for that service
+2. Read the service's `app.py` to check what global dependencies/middleware are applied
+3. Read any service-specific `middleware.py` if it exists
+4. For each route handler, check for the vulnerabilities listed in Step 3
+5. **Write the report to a file** at `/tmp/idor-scan-results/<service-name>.md` using the format in Step 4
+6. **Return ONLY a one-line confirmation** (e.g., "Wrote report to /tmp/idor-scan-results/chat_service.md. 2 findings."). Do NOT return the full report — it's in the file.
+
+**IMPORTANT:** When calling the Task tool for each sub-agent, explicitly instruct it to write findings to the file and return only a brief one-line confirmation. The full report must go in the file, NOT in the return message. This prevents the main agent's context from overflowing.
+
+### Step 3: What to check per route
+
+For every route handler function, check for these IDOR vulnerabilities:
+
+- **Missing patient validation**: Route path contains `{patient_id}` but handler does NOT use `Depends(validate_patient_account_from_path_as_patient)` or equivalent
+- **Patient dependency result discarded**: Route uses `validate_patient_account_from_path_as_patient` but assigns the result to `_` instead of `patient`. The presence of the dependency alone is NOT sufficient — if the route also takes a sub-resource ID (e.g., `{chat_id}`, `{file_id}`, `{order_id}`), the validated `patient.patient_id` MUST be passed to the service layer and checked against the fetched resource's `patient_id`. A discarded `_` is a strong signal that this check is missing. Trace the full call chain to verify.
+- **Missing resource-to-account ownership**: Route takes a resource ID as a path/query/body param, fetches the resource, but does NOT verify `resource.account_id == account_id` before returning or mutating it
+- **Missing resource-to-patient ownership**: Route takes both a `{patient_id}` and another resource ID, fetches the resource, but does NOT verify `resource.patient_id == patient_id`. This applies even if the patient validation dependency is present — the dependency only confirms the patient belongs to the account, NOT that the sub-resource belongs to the patient. You must trace into the service layer to verify this check exists.
+- **Unscoped list/query endpoints**: Route returns a collection of resources (list/search/query) but the underlying query does NOT filter by `account_id` (or `patient_id` where applicable). Follow the call chain into the repository/data access layer to verify the query includes the appropriate scope filter.
+- **Using account, user, or user role not from header**: Route uses account id, user id, or user role from query param, path param, or request body and not from the trusted `Bioscope-Account-Id`, `Bioscope-User-Id`, and `Bioscope-User-Role` headers.
+
+### Step 4: Compile the report
+
+Each sub-agent should return its findings in this format:
+
+```text
+## <service-name>
+
+### Routes Scanned
+- `GET /path` — handler_name (file:line)
+- `POST /path` — handler_name (file:line)
+...
+
+### Findings
+
+#### Missing patient validation — `POST /patients/{patient_id}/resource`
+- **File**: path/to/file.py:123
+- **Handler**: `create_resource`
+- **Issue**: Route includes `{patient_id}` in path but does not use `validate_patient_account_from_path_as_patient`
+- **Confidence**: High / Medium / Low
+- **Notes**: <any relevant context>
+
+#### Missing ownership check — `GET /resource/{resource_id}`
+...
+
+### No Issues Found
+(list routes that were scanned and passed all checks)
+```
+
+### Step 5: Aggregate
+
+After all sub-agents complete, read each file from `/tmp/idor-scan-results/` and compile a final summary. To avoid context limits, read one file at a time and extract only the findings (skip the "No Issues Found" and "Routes Scanned" sections for clean services).
+
+Write the final report to `/tmp/idor-scan-results/SUMMARY.md` with:
+
+1. **Executive Summary**: Total routes scanned, total findings
+2. **Findings**: All IDOR vulnerabilities grouped by type
+3. **Clean Services**: List of services with no findings (names only)
+4. **Per-Service Details**: Full findings for services that had issues
+
+Then output the summary to the user.
+
+Be thorough. Read the actual code — don't guess based on function names alone. When in doubt about whether a check exists, read the called functions to see if ownership validation happens deeper in the call chain. If validation happens in a called function rather than at the route level, note it but don't flag it as a vulnerability.f:["$","div","/Users/gabry/Desktop/ps-copy/platform-services/.claude/commands/idor-scan.md",{"className":"border border-border rounded-sm p-5 ","children":[["$","div",null,{"className":"flex items-center gap-2","children":[["$","h3",null,{"className":"text-sm font-medium","children":"idor-scan"}],["$","span",null,{"className":"inline-flex items-center px-2 py-0.5 text-xs font-medium rounded-sm bg-surface-raised text-text-muted","children":"platform-services"}]]}],["$","$L2",null,{"content":"$1c","previewLines":3}]]}]
+1d:T2543,# PHI/PII Data Exposure Scan
+
+Scan ALL application code in platform-services for Protected Health Information (PHI) and Personally Identifiable Information (PII) exposure vulnerabilities. This covers logging, error responses, API over-fetching, and any other channel where sensitive data could leak.
+
+## What Constitutes PHI/PII in This Codebase
+
+### Patient PHI Fields (from `bioscope_types/dynamodb/patients.py`)
+- `first_name`, `last_name` (names)
+- `date_of_birth` (DOB)
+- `sex`
+- `mrn` (medical record number)
+- `address_line_1`, `address_line_2`, `city`, `state`, `zip_code`, `country` (address)
+- `phone_number`
+- `email`
+
+### User PII Fields (from `bioscope_types/dynamodb/users.py`)
+- `first_name`, `last_name`
+- `email`
+- `npi_number` (healthcare provider identifier)
+
+### Account PII Fields (from `bioscope_types/dynamodb/accounts.py`)
+- Address fields: `address_line_1`, `address_line_2`, `city`, `state`, `zip_code`, `country`
+
+### Other PHI Sources
+- FHIR resources (contain full patient demographics, diagnoses, medical history)
+- EHR data (clinical records, lab results, immunizations)
+- Genomic/WGS data and results
+- Chat messages about patients (may contain clinical discussions)
+- File contents (uploaded documents, lab reports)
+
+### Safe to Log
+- UUIDs (patient_id, account_id, user_id, order_id, etc.)
+- Timestamps
+- Status values and enums
+- Counts and metrics
+- Operation names and types
+- File IDs (not file contents or names that might contain patient info)
+
+## How Logging Works
+
+- `BioscopeLogger` (from `bioscope_logger` package) is the standard logger
+- Uses Python's `logging.LoggerAdapter` with JSON formatting
+- Supports `.child()` for adding context fields
+- Extra fields passed via `extra={}` parameter are serialized into the JSON log output
+- Logs go to stdout and optionally CloudWatch — all log output is persisted
+- `BioscopeLoggerDeps` injects the logger into FastAPI routes
+- Lambda handlers receive `logger: BioscopeLogger` via dependency injection
+
+## Your Task
+
+### Step 1: Discover all scannable code
+
+Use glob to find:
+1. All route files: `packages/*/src/*/routes/*.py`
+2. All handler files: `packages/*/src/*/handler.py`
+3. All handlers directories: `packages/*/src/*/handlers/*.py`
+4. All service/business logic files: `packages/*/src/*/*.py` (excluding `__init__.py`, `aws.py`, `app.py`)
+5. Any standalone scripts or local dev files: `packages/*/src/*/local.py`
+
+Group them by service/package.
+
+### Step 2: Create an output directory and spin up sub-agents
+
+First, create an output directory using Bash: `mkdir -p /tmp/phi-exposure-scan-results`
+
+Then, for each service/package, use the Task tool (subagent_type: "general-purpose") to scan that package's code. Run these in parallel (include all Task tool calls in a single message). Each sub-agent should:
+
+1. Read ALL Python source files for that package (routes, handlers, service modules, utilities)
+2. Check for every vulnerability type listed in Step 3
+3. **Write the report to a file** at `/tmp/phi-exposure-scan-results/<package-name>.md` using the format in Step 4
+4. **Return ONLY a one-line confirmation** (e.g., "Wrote report to /tmp/phi-exposure-scan-results/chat_service.md. 3 findings."). Do NOT return the full report — it's in the file.
+
+**IMPORTANT:** When calling the Task tool for each sub-agent, include the full list of PHI/PII fields from the "What Constitutes PHI/PII" section above so the sub-agent knows exactly what to look for. Instruct it to write findings to the file and return only a brief one-line confirmation. The full report must go in the file, NOT in the return message.
+
+### Step 3: What to check
+
+#### A. PHI/PII in Log Statements (CRITICAL)
+
+Search for all `logger.info`, `logger.warning`, `logger.error`, `logger.debug`, `logger.exception`, and `logger.critical` calls. For each, check:
+
+- **Full model dumps in logs**: Calls like `logger.info("...", extra={"patient": patient.model_dump()})` or `model_dump_json()` that serialize an entire Pydantic model containing PHI fields. This includes Patient, User, Account, or any FHIR resource model.
+- **PHI field values in log messages**: Direct references to PHI fields in log strings or extra dicts, e.g., `extra={"name": patient.first_name}`, `extra={"email": user.email}`, `extra={"dob": patient.date_of_birth}`.
+- **F-string or format-string PHI**: Log messages that interpolate PHI values, e.g., `logger.info(f"Created patient {patient.first_name} {patient.last_name}")`.
+- **Logging raw request/response bodies**: Logging full HTTP request bodies or response payloads that may contain PHI, e.g., `logger.info("Request", extra={"body": request.body()})`.
+- **Logging full event payloads**: SQS/SNS/EventBridge event payloads logged in full when they may contain PHI fields.
+- **Logging FHIR resources**: Any FHIR Bundle, Patient, Observation, Immunization, or other clinical resource logged in full.
+
+#### B. PHI/PII in Error Responses (HIGH)
+
+Check all `HTTPException` raises and error response construction:
+
+- **PHI in HTTPException detail**: `raise HTTPException(status_code=..., detail=f"Patient {patient.first_name} not found")` — the detail message should never contain PHI, only IDs or generic messages.
+- **PHI in custom error response models**: Any error response class that includes PHI fields.
+- **Full exception messages with PHI**: Exception handlers that return `str(e)` where the exception message might contain PHI from a database query or validation error.
+
+#### C. PHI/PII in API Response Over-Fetching (MEDIUM)
+
+Check route return values and response models:
+
+- **Returning full patient/user records when not needed**: A route that returns a complete Patient object with all fields when the consumer only needs a subset (e.g., patient_id and status).
+
+#### D. PHI/PII in URLs and Query Parameters (HIGH)
+
+- **Patient data in query strings**: Routes that accept PHI as query parameters (e.g., `?name=John&dob=1990-01-01`). Query strings end up in access logs, browser history, and CDN logs. Only IDs should be in URLs.
+- **PHI in path parameters**: Path params should only contain UUIDs or opaque identifiers, never names, emails, or other PHI.
+
+#### E. PHI/PII in Development/Debug Code (MEDIUM)
+
+- **Local development files**: Files like `local.py` or scripts that log full records for debugging but exist in the production codebase.
+- **Commented-out debug logging**: Commented code that logs PHI — a developer might uncomment it and forget to remove it.
+- **Print statements with PHI**: Any `print()` calls that output PHI (should use logger instead, but print output also goes to CloudWatch).
+
+#### F. Missing Data Sanitization (LOW)
+
+- **No redaction utilities**: Note if the codebase lacks any sanitization/redaction utilities for PHI fields. This is an architectural observation, not a per-route vulnerability.
+- **PHI passed through multiple layers without scrubbing**: Trace data flow where PHI enters the system (e.g., from account-service or EHR) and check if it's ever inadvertently logged along the way.
+
+### Step 4: Report format
+
+Each sub-agent should write findings in this format:
+
+```text
+## <package-name>
+
+### Files Scanned
+- path/to/file.py
+- path/to/other_file.py
+...
+
+### Findings
+
+#### [CRITICAL] Full patient model logged — service.py:45
+- **File**: path/to/file.py:45
+- **Code**: `logger.info("Patient: ", extra={"patient": patient.model_dump_json()})`
+- **Category**: PHI in log statements
+- **PHI Fields Exposed**: first_name, last_name, date_of_birth, email, phone_number, address, mrn
+- **Notes**: Logs the entire Patient FHIR resource including all demographics
+
+#### [HIGH] PHI in error response — routes/patients.py:78
+- **File**: path/to/file.py:78
+- **Code**: `raise HTTPException(detail=f"Patient {patient.first_name} not found")`
+- **Category**: PHI in error responses
+- **PHI Fields Exposed**: first_name
+- **Notes**: Patient name included in 404 error detail
+
+### No Issues Found
+(list files that were scanned and passed all checks)
+```
+
+Severity levels:
+- **CRITICAL**: Full model dumps or FHIR resources in logs, multiple PHI fields exposed
+- **HIGH**: Individual PHI fields in logs or error responses, PHI in URLs
+- **MEDIUM**: Over-fetching in API responses, debug/dev code with PHI
+- **LOW**: Architectural observations, missing sanitization utilities
+
+### Step 5: Aggregate
+
+After all sub-agents complete, read each file from `/tmp/phi-exposure-scan-results/` and compile a final summary. To avoid context limits, read one file at a time and extract only the findings.
+
+Write the final report to `/tmp/phi-exposure-scan-results/SUMMARY.md` with:
+
+1. **Executive Summary**: Total files scanned, total findings by severity (CRITICAL/HIGH/MEDIUM/LOW)
+2. **CRITICAL Findings**: All critical PHI exposure issues (immediate remediation needed)
+3. **HIGH Findings**: High-severity issues
+4. **MEDIUM Findings**: Medium-severity issues
+5. **LOW Findings & Observations**: Low-severity items and architectural notes
+6. **Clean Packages**: List of packages with no findings (names only)
+7. **Recommendations**: Actionable remediation steps, prioritized by severity
+
+Then output the summary to the user.
+
+Be thorough. Read the actual code — don't guess based on function names alone. When checking log statements, look at what the `extra` dict actually contains. When checking for model dumps, trace the model class to see what fields it includes. If a model only contains safe fields (IDs, timestamps, statuses), it's not a PHI exposure even if it's logged via `model_dump()`.10:["$","div","/Users/gabry/Desktop/ps-copy/platform-services/.claude/commands/phi-exposure-scan.md",{"className":"border border-border rounded-sm p-5 ","children":[["$","div",null,{"className":"flex items-center gap-2","children":[["$","h3",null,{"className":"text-sm font-medium","children":"phi-exposure-scan"}],["$","span",null,{"className":"inline-flex items-center px-2 py-0.5 text-xs font-medium rounded-sm bg-surface-raised text-text-muted","children":"platform-services"}]]}],["$","$L2",null,{"content":"$1d","previewLines":3}]]}]
+1e:T1b86,# Upgrade litellm in llm-proxy-service
+
+Upgrade the `litellm` dependency in `llm-proxy-service` to a new version, validating that all supported models have correct pricing.
+
+## Background
+
+- `litellm` contains bundled pricing data in `model_prices_and_context_window.json`
+- We disable litellm's automatic pricing fetch; we ONLY use the bundled pricing
+- If the bundled pricing is wrong or missing for a model, litellm reports $0 cost, which breaks our cost reporting
+- Overrides for incorrect pricing go in `platform-services/packages/llm_proxy_service/src/llm_proxy_service/service.py` via `litellm.register_model()`
+- **IMPORTANT**: Both `llm-proxy-service` and `embedding-service` depend on `litellm`. Their versions must always match. When upgrading, update BOTH `platform-services/packages/llm_proxy_service/pyproject.toml` and `platform-services/packages/embedding_service/pyproject.toml`.
+
+## Step 1: Ask the user what version to upgrade to
+
+First, read the current litellm version from `platform-services/packages/llm_proxy_service/pyproject.toml`. Then, fetch the latest available versions from PyPI:
+
+```bash
+curl -s "https://pypi.org/pypi/litellm/json" | python3 -c "import sys,json; releases=sorted(json.load(sys.stdin)['releases'].keys(), key=lambda v: [int(x) for x in v.split('.')[:3] if x.isdigit()], reverse=True); print('\n'.join(releases[:5]))"
+```
+
+Use AskUserQuestion to present the user with a selection of versions. Include the 3-4 most recent versions as options, labeling the latest one with "(Latest)". The user can also type a different version via the "Other" option. Mention the current version in the question text so the user knows what they're upgrading from.
+
+## Step 2: Identify all supported models
+
+Read the `LLMModel` type definition in `platform-services/packages/bioscope_types/src/bioscope_types/services/llm_proxy_service.py` to get all supported models. Group them by provider:
+
+- `bedrock/` models (Anthropic on AWS Bedrock)
+- `anthropic/` models (direct Anthropic API)
+- `vertex_ai/` models (Google Vertex AI)
+- `azure/` models (Azure OpenAI)
+- `groq/` models (Groq)
+- etc.
+
+Also read the current litellm version from `platform-services/packages/llm_proxy_service/pyproject.toml`.
+
+Also read `platform-services/packages/llm_proxy_service/src/llm_proxy_service/service.py` to identify any existing `litellm.register_model()` overrides.
+
+## Step 3: Create output directory and spin up sub-agents per provider
+
+First, create an output directory using Bash: `mkdir -p /tmp/litellm-upgrade`
+
+Then, for EACH provider (bedrock, anthropic, vertex_ai, azure, groq), spin up a sub-agent using the Task tool (subagent_type: "general-purpose"). Run all provider sub-agents **in parallel** (include all Task tool calls in a single message). **Do NOT run these in the background** — they need to be foreground agents so they can prompt for tool permissions.
+
+Each sub-agent should:
+
+1. **Check pricing in the NEW version** of litellm for every model belonging to that provider. Use `uv run` to inspect the bundled pricing data:
+
+   ```bash
+   uv run --with litellm==<NEW_VERSION> python -c "import litellm, json; print(json.dumps(litellm.model_cost.get('<model_key>', {}), indent=2))"
+   ```
+
+   Note: The key in `litellm.model_cost` may not exactly match the model string in `LLMModel`. For example, `bedrock/us.anthropic.claude-sonnet-4-5-20250929-v1:0` may be keyed as `us.anthropic.claude-sonnet-4-5-20250929-v1:0` or similar. If an exact match isn't found, search for partial matches:
+
+   ```bash
+   uv run --with litellm==<NEW_VERSION> python -c "import litellm; keys = [k for k in litellm.model_cost if '<partial_model_name>' in k]; print('\n'.join(sorted(keys)))"
+   ```
+
+2. **Fetch the provider's pricing page** (linked in the `LLMModel` comments) and compare the litellm pricing against the actual provider pricing. Key fields to validate:
+   - `input_cost_per_token`
+   - `output_cost_per_token`
+   - `cache_read_input_token_cost` (if applicable)
+   - `cache_creation_input_token_cost` (if applicable)
+
+3. **Also check the OLD (current) version** to see if any existing overrides can be removed because the new version has correct pricing:
+
+   ```bash
+   uv run --with litellm==<OLD_VERSION> python -c "import litellm, json; print(json.dumps(litellm.model_cost.get('<model_key>', {}), indent=2))"
+   ```
+
+4. **Write findings to a file** at `/tmp/litellm-upgrade/<provider>.md` with this format:
+
+```text
+   ## <provider> Models
+
+   ### <model_name>
+   - **Provider pricing page**: <url>
+   - **Expected input cost**: $X per 1M tokens
+   - **Expected output cost**: $X per 1M tokens
+   - **Expected cached input cost**: $X per 1M tokens (if applicable)
+   - **litellm (new version) input cost**: $X per 1M tokens
+   - **litellm (new version) output cost**: $X per 1M tokens
+   - **litellm (new version) cached input cost**: $X per 1M tokens
+   - **Status**: CORRECT / INCORRECT / MISSING
+   - **Override needed**: Yes (details) / No
+   ```
+
+5. **Return ONLY a single sentence** summarizing findings (e.g., "All 3 Anthropic models have correct pricing in the new version." or "2 of 5 Bedrock models have incorrect cached input pricing."). The full report is in the file — do NOT return it in the response.
+
+**IMPORTANT:** When calling the Task tool for each sub-agent, explicitly instruct it to write findings to the file and return only a brief single-sentence confirmation. The full report must go in the file, NOT in the return message. This prevents the main agent's context from overflowing.
+
+## Step 4: Spin up a final evaluation sub-agent
+
+After all provider sub-agents complete, spin up ONE final sub-agent (subagent_type: "general-purpose") that:
+
+1. Reads all files in `/tmp/litellm-upgrade/`
+2. Compiles a summary of which models need overrides and which are correct
+3. Writes a final report to `/tmp/litellm-upgrade/SUMMARY.md`
+4. Returns ONLY a single sentence summary (e.g., "3 models need pricing overrides, 15 are correct. See /tmp/litellm-upgrade/SUMMARY.md for details.")
+
+Then read `/tmp/litellm-upgrade/SUMMARY.md` and present the findings to the user.
+
+## Step 5: Implement the upgrade
+
+After presenting findings to the user and getting their approval:
+
+1. Update the litellm version in BOTH:
+   - `platform-services/packages/llm_proxy_service/pyproject.toml`
+   - `platform-services/packages/embedding_service/pyproject.toml`
+2. Add any needed `litellm.register_model()` overrides in `platform-services/packages/llm_proxy_service/src/llm_proxy_service/service.py`
+3. Remove any existing overrides that are no longer needed (because the new version has correct pricing)
+4. Run `uv sync --all-packages` from the `platform-services/` directory to update the lock file
+5. Run `pnpm exec nx run llm-proxy-service:test` to verify tests pass
+6. Run `pnpm exec nx run llm-proxy-service:lint` and `pnpm exec nx run llm-proxy-service:type-check`
+7. Run `pnpm exec nx run embedding-service:test`, `pnpm exec nx run embedding-service:lint`, and `pnpm exec nx run embedding-service:type-check`11:["$","div","/Users/gabry/Desktop/ps-copy/platform-services/.claude/commands/upgrade-litellm.md",{"className":"border border-border rounded-sm p-5 ","children":[["$","div",null,{"className":"flex items-center gap-2","children":[["$","h3",null,{"className":"text-sm font-medium","children":"upgrade-litellm"}],["$","span",null,{"className":"inline-flex items-center px-2 py-0.5 text-xs font-medium rounded-sm bg-surface-raised text-text-muted","children":"platform-services"}]]}],["$","$L2",null,{"content":"$1e","previewLines":3}]]}]
+15:null