@softspark/ai-toolkit 3.0.2 → 3.1.0

package/app/skills/kotlin-rules/SKILL.md

@@ -0,0 +1,271 @@
+---
+name: kotlin-rules
+description: "Kotlin coding rules from ai-toolkit: coding-style, frameworks, patterns, security, testing. Triggers: .kt, .kts, build.gradle.kts, Ktor, Jetpack Compose, coroutines, kotlinx. Load when writing, reviewing, or editing Kotlin code."
+effort: medium
+user-invocable: false
+allowed-tools: Read
+---
+
+# Kotlin Rules
+
+These rules come from `app/rules/kotlin/` in ai-toolkit. They cover
+the project's standards for coding style, frameworks, patterns,
+security, and testing in Kotlin. Apply them when writing or
+reviewing Kotlin code.
+
+# Kotlin Coding Style
+
+## Naming
+- PascalCase: classes, interfaces, objects, type aliases, enum entries.
+- camelCase: functions, properties, local variables, parameters.
+- UPPER_SNAKE: compile-time constants (`const val`), top-level `val` constants.
+- Backing properties: prefix with `_` (`private val _items`, `val items: List<T>`).
+- Package names: lowercase, no underscores (`com.company.project.feature`).
+
+## Null Safety
+- Use nullable types only when nullability is semantically meaningful.
+- Prefer `?.let { }`, `?:` (Elvis), and safe calls over `!!`.
+- Never use `!!` except in tests or when null is truly impossible.
+- Use `requireNotNull()` and `require()` for preconditions at public API boundaries.
+- Use `checkNotNull()` and `check()` for state assertions.
+
+## Data Classes
+- Use `data class` for DTOs, value objects, and state containers.
+- Use `copy()` for immutable updates. Avoid mutable `var` in data classes.
+- Use `sealed class` / `sealed interface` for restricted hierarchies.
+- Use `value class` (inline class) for type-safe wrappers with zero overhead.
+- Use `object` for singletons and namespace-like utility groupings.
+
+## Functions
+- Use expression body (`= expr`) for single-expression functions.
+- Use named arguments for functions with >2 parameters of the same type.
+- Use default parameter values instead of overloaded functions.
+- Use extension functions to add behavior without inheritance.
+- Use `suspend` functions for async operations, not callbacks.
+
+## Collections
+- Prefer `listOf`, `mapOf`, `setOf` (immutable) over `mutableListOf`.
+- Use collection operators: `map`, `filter`, `groupBy`, `associate`.
+- Use `sequence {}` for lazy evaluation on large collections.
+- Prefer `firstOrNull()` over `first()` for safe access.
+- Use destructuring: `val (name, age) = user`.
+
+## Scope Functions
+- `let`: null-safe chaining and local scoping.
+- `apply`: configure object after creation.
+- `also`: side effects (logging, validation) in chains.
+- `run`: compute a result using receiver's context.
+- `with`: multiple operations on an object without chaining.
+- Avoid nesting scope functions more than 1 level deep.
+
+## Formatting
+- Use ktlint or detekt for automated formatting and linting.
+- Use trailing commas in multi-line parameter/argument lists.
+- Max line length: 120 characters (Kotlin convention).
+- Use `when` expression over if-else chains for 3+ branches.
+
+# Kotlin Frameworks
+
+## Ktor (Server)
+- Use routing DSL: `routing { get("/users") { call.respond(users) } }`.
+- Use `install()` for plugins: ContentNegotiation, Authentication, CORS.
+- Use `call.receive<T>()` for typed request body parsing with kotlinx.serialization.
+- Use `StatusPages` plugin for centralized error handling.
+- Use `Routing` with nested `route("/api/v1") { }` blocks for URL grouping.
+
+## Ktor (Client)
+- Use `HttpClient` with engine configuration (CIO, OkHttp, Apache).
+- Use `install(ContentNegotiation) { json() }` for JSON serialization.
+- Use `client.get<T>()` with reified type for typed responses.
+- Use `HttpTimeout` plugin for connection and request timeouts.
+- Close `HttpClient` when done or use DI lifecycle management.
+
+## Spring Boot (Kotlin)
+- Use constructor injection (Kotlin classes are `final` by default).
+- Apply `kotlin-spring` plugin for open classes (required for proxying).
+- Use `@ConfigurationProperties` with data classes for typed config.
+- Use `WebFlux` with coroutines: `coRouter { }` and `suspend` handler functions.
+- Use `spring-boot-starter-validation` with `@Valid` on Kotlin data classes.
+
+## Exposed (ORM)
+- Use DSL API for type-safe queries: `Users.select { Users.name eq "Ada" }`.
+- Use DAO API for Active Record-style: `User.find { Users.age greaterEq 18 }`.
+- Wrap database operations in `transaction { }` blocks.
+- Use `SchemaUtils.create(Users)` for schema management in development.
+
+## kotlinx.serialization
+- Use `@Serializable` annotation on data classes for compile-time serialization.
+- Use `@SerialName("field_name")` for JSON field name mapping.
+- Use `Json { ignoreUnknownKeys = true }` for lenient deserialization.
+- Use polymorphic serialization with `sealed class` and `@Polymorphic`.
+- Prefer `kotlinx.serialization` over Jackson for pure Kotlin projects.
+
+## Koin (DI)
+- Define modules: `module { single { UserService(get()) } }`.
+- Use `by inject<T>()` for lazy injection in Android/Ktor.
+- Use `factory { }` for new instance per injection, `single { }` for singleton.
+- Use `checkModules()` in tests to verify DI graph completeness.
+
+## Compose (Multiplatform UI)
+- Use `@Composable` functions for UI components. Keep them stateless.
+- Use `remember { }` and `mutableStateOf()` for local state.
+- Hoist state to callers: pass state down, events up.
+- Use `LaunchedEffect` for side effects tied to composition lifecycle.
+- Use `ViewModel` with `StateFlow` for screen-level state management.
+
+# Kotlin Patterns
+
+## Error Handling
+- Use `Result<T>` for operations that can fail without exceptions.
+- Use `runCatching { }` to wrap exception-throwing code into `Result`.
+- Use `sealed class` hierarchies for domain errors: `sealed class AppError`.
+- Prefer `fold()`, `getOrElse()`, `getOrNull()` over `getOrThrow()`.
+- Use `require()` / `check()` for preconditions; they throw `IllegalArgumentException` / `IllegalStateException`.
+
+## Coroutines
+- Use `suspend` functions for sequential async operations.
+- Use `coroutineScope { }` for structured concurrency with parallel work.
+- Use `async { }` + `await()` for concurrent independent operations.
+- Use `supervisorScope { }` when child failures should not cancel siblings.
+- Use `withContext(Dispatchers.IO)` for blocking I/O in coroutine context.
+- Use `flow { }` for cold asynchronous streams. Collect in lifecycle-aware scope.
+
+## Flow Patterns
+- Use `stateIn()` and `shareIn()` to convert cold flows to hot shared state.
+- Use `combine()` to merge multiple flows into derived state.
+- Use `flatMapLatest` for search-as-you-type patterns (cancel previous).
+- Use `catch { }` operator for upstream error handling in flows.
+- Use `flowOn(Dispatchers.IO)` to shift upstream execution context.
+
+## Sealed Hierarchies
+- Use `sealed interface` over `sealed class` when no shared state is needed.
+- Use `when` expressions exhaustively on sealed types (compiler-enforced).
+- Combine sealed types with data classes for typed state machines.
+- Use sealed hierarchies for API responses: `Success<T>`, `Error`, `Loading`.
+
+## Delegation
+- Use `by lazy { }` for thread-safe lazy initialization.
+- Use `by map` for delegated properties backed by a `Map`.
+- Use class delegation (`class Foo : Bar by impl`) to favor composition.
+- Use `observable` / `vetoable` delegates for reactive property changes.
+
+## Builder Patterns
+- Use DSL-style builders with `@DslMarker` annotation to prevent scope leakage.
+- Use trailing lambda syntax for configuration blocks.
+- Use `apply { }` for inline object configuration without a dedicated builder.
+- Use `buildList { }`, `buildMap { }`, `buildString { }` for collection construction.
+
+## Anti-Patterns
+- Overusing `!!`: masks null-safety guarantees. Use safe calls or require.
+- Nesting scope functions: `foo.let { it.also { ... }.run { } }` -- flatten logic.
+- Blocking the main thread: use `withContext(Dispatchers.IO)` for I/O.
+- Using `GlobalScope.launch`: leaks coroutines. Use structured concurrency.
+- Mutable shared state without synchronization: use `Mutex` or `StateFlow`.
+
+# Kotlin Security
+
+## Input Validation
+- Validate all inputs at API boundaries using Bean Validation or manual checks.
+- Use `require()` for argument validation: `require(age > 0) { "Age must be positive" }`.
+- Use data class `init` blocks for domain validation on construction.
+- Never trust client-provided IDs. Verify resource ownership server-side.
+- Sanitize strings before using in HTML, SQL, or shell commands.
+
+## Null Safety as Security
+- Kotlin's null safety prevents null pointer exceptions. Do not circumvent with `!!`.
+- Use `?.` and `?:` chains for safe fallback values at boundaries.
+- Treat Java interop as untrusted: platform types can still be null.
+- Use `@Nullable` / `@NotNull` annotations on Java code consumed by Kotlin.
+
+## SQL Injection
+- Use Exposed DSL or JPA with parameterized queries. Never concatenate input.
+- Use `PreparedStatement` if writing raw JDBC.
+- Use `CriteriaBuilder` or Exposed conditions for dynamic query construction.
+- Audit `@Query(nativeQuery = true)` for parameter interpolation risks.
+
+## Serialization
+- Use `kotlinx.serialization` with `@Serializable` for compile-time safety.
+- Use `Json { ignoreUnknownKeys = true }` but validate after deserialization.
+- Never use Java `ObjectInputStream` for deserialization (RCE risk).
+- Restrict polymorphic deserialization to known sealed class subtypes.
+
+## Authentication
+- Use Spring Security or Ktor Authentication plugin. Do not roll your own.
+- Hash passwords with BCrypt or Argon2. Never store plaintext.
+- Use short-lived JWTs (15 min) with refresh token rotation.
+- Validate JWT signature, issuer, audience, and expiration on every request.
+
+## Coroutine Security
+- Use `withTimeout()` to prevent unbounded coroutine execution (DoS vector).
+- Use `Mutex` for critical sections. Do not use `synchronized` in suspend functions.
+- Propagate security context through `CoroutineContext` elements.
+- Cancel coroutine scopes on authentication failure or session expiry.
+
+## Secrets Management
+- Use environment variables or Vault for secrets. Never hardcode.
+- Use `@ConfigurationProperties` with injected secrets, not string literals.
+- Never log request headers containing Authorization tokens.
+- Use separate configuration profiles for dev/staging/prod secrets.
+
+## Dependencies
+- Use Dependabot or Renovate for automated dependency updates.
+- Run OWASP Dependency-Check or Gradle `dependencyCheckAnalyze`.
+- Audit transitive dependencies with `gradle dependencies`.
+- Pin dependency versions. Avoid dynamic versions like `1.+`.
+
+## Logging
+- Use parameterized logging: `logger.info("User {} logged in", userId)`.
+- Never log passwords, tokens, or PII.
+- Sanitize user input before logging to prevent log injection.
+- Use structured logging (JSON) for machine-parseable audit trails.
+
+# Kotlin Testing
+
+## Framework
+- Use JUnit 5 as the test runner.
+- Use Kotest for Kotlin-idiomatic BDD-style testing (alternative).
+- Use MockK for mocking (Kotlin-native, supports coroutines).
+- Use Testcontainers for integration tests with external services.
+
+## File Naming
+- Test files: `FooTest.kt` in `src/test/kotlin/` mirroring source package.
+- Integration tests: `FooIT.kt` or use `@Tag("integration")`.
+- Use `@Nested` inner classes to group related test cases.
+
+## Structure
+- Use `@DisplayName` for human-readable test names.
+- Use backtick function names for readable test names: `` `returns 404 when user not found` ``.
+- Use `@BeforeEach` for per-test setup. Avoid shared mutable state.
+- Use `@ParameterizedTest` with `@MethodSource` for table-driven tests.
+
+## MockK
+- Use `mockk<UserRepository>()` to create mocks.
+- Use `every { mock.find(any()) } returns user` for stubbing.
+- Use `coEvery { ... }` and `coVerify { ... }` for coroutine mocking.
+- Use `spyk()` for partial mocks on real objects.
+- Use `slot<T>()` and `captured` to inspect arguments.
+- Clear mocks in `@AfterEach` to prevent state leakage.
+
+## Coroutine Testing
+- Use `runTest { }` from `kotlinx-coroutines-test` for coroutine tests.
+- Use `TestDispatcher` to control coroutine execution timing.
+- Use `advanceUntilIdle()` to complete all pending coroutines.
+- Use `turbine` library for testing `Flow` emissions.
+
+## Assertions
+- Use AssertJ or Kotest assertions for fluent, readable checks.
+- Use `shouldBe`, `shouldThrow`, `shouldContain` (Kotest matchers).
+- Use `assertSoftly { }` to collect multiple assertion failures.
+- Use `assertThrows<FooException> { ... }` for exception testing.
+
+## Test Data
+- Use factory functions for test data: `fun aUser(name: String = "Ada") = User(...)`.
+- Use default parameters for minimal test data setup.
+- Use `copy()` on data classes for variations of base test objects.
+- Use `faker` library for realistic test data generation.
+
+## Spring Integration
+- Use `@SpringBootTest` with `@AutoConfigureMockMvc` for API tests.
+- Use `@WebMvcTest` for controller-only tests (faster).
+- Use `@MockkBean` instead of `@MockBean` for MockK integration.
+- Use `@Transactional` on test classes for automatic rollback.

package/app/skills/medplum-rules/SKILL.md

@@ -0,0 +1,271 @@
+---
+name: medplum-rules
+description: "Medplum (FHIR healthcare) coding rules from ai-toolkit: coding-style, frameworks, patterns, security, testing. Triggers: medplum.config.mts, medplum.config.ts, FHIR, Medplum, Bot, Subscription, Questionnaire. Load when writing, reviewing, or editing Medplum (FHIR healthcare) code."
+effort: medium
+user-invocable: false
+allowed-tools: Read
+---
+
+# Medplum (FHIR healthcare) Rules
+
+These rules come from `app/rules/medplum/` in ai-toolkit. They cover
+the project's standards for coding style, frameworks, patterns,
+security, and testing in Medplum (FHIR healthcare). Apply them when writing or
+reviewing Medplum (FHIR healthcare) code.
+
+# Medplum / FHIR Coding Style
+
+## Resource Structure
+- Every FHIR object must include `resourceType` as first field.
+- Use PascalCase for resource types (`Patient`, `ServiceRequest`), camelCase for fields (`birthDate`, `valueQuantity`).
+- Never hardcode resource IDs. Let the server assign them on create.
+- Include `meta.profile` when creating resources that must conform to a StructureDefinition.
+
+## References
+- Use `createReference(resource)` from `@medplum/core` to build Reference objects.
+- Always include `display` on references for human readability.
+- Use `getReferenceString(resource)` for comparisons and logging — returns `ResourceType/id`.
+- Use `parseReference(ref)` to extract resourceType and id from a reference string.
+- Never concatenate strings to build references manually.
+
+## CodeableConcepts & Coding
+- Always include `system`, `code`, and `display` in every Coding element.
+- Use standard terminology URIs: `http://loinc.org`, `http://snomed.info/sct`, `http://hl7.org/fhir/sid/icd-10-cm`.
+- Use `getCodeBySystem(cc, system)` to find codes; `setCodeBySystem(cc, system, code)` to set them.
+- Prefer `CodeableConcept` over plain `Coding` when the FHIR spec allows both — it supports multiple codings and free text.
+
+## Identifiers
+- Use `identifier` arrays with `system` + `value` for external IDs (MRN, NPI, SSN).
+- Use `getIdentifier(resource, system)` and `setIdentifier(resource, system, value)` helpers.
+- Identifier systems must be absolute URIs (e.g., `http://hl7.org/fhir/sid/us-npi`).
+- Use `createResourceIfNoneExist(resource, 'identifier=system|value')` for idempotent creates.
+
+## Extensions
+- Use the `extension` array with `url` and typed `value[x]` fields.
+- Prefer official HL7/US Core extensions over custom ones where they exist.
+- Use `getExtension(resource, url)` and `getExtensionValue(resource, url)` helpers.
+
+## Bundles
+- Use `urn:uuid:<uuid>` for internal references between entries in a transaction Bundle.
+- Every Bundle entry must have `request.method` (`POST`, `PUT`, `DELETE`) and `request.url`.
+- Include `fullUrl` on entries that are referenced by other entries.
+- Use conditional references (`Practitioner?identifier=npi|123`) for existing resources.
+
+## HIPAA-Aware Coding
+- Identifiers like SSN, MRN, and insurance IDs are PHI — never log raw values to console or external services.
+- Use a safe logging utility (e.g., `safeLog()`) for any output that might contain patient data. Never `console.log` raw FHIR resources.
+- Reference `display` strings may contain patient names — treat as PHI in logs and error messages.
+- Every new data access path or admin operation must include corresponding `AuditEvent` creation. No exceptions.
+- When audit logging fails (Medplum unreachable), write to a fallback store — audit events must never be silently dropped.
+- See `security.md` rules for full HIPAA, access policy, and PHI handling requirements.
+
+## Formatting
+- Use `formatHumanName()`, `formatAddress()`, `formatDate()`, `formatQuantity()` for display strings.
+- Use `getDisplayString(resource)` as a universal fallback for any resource's display name.
+- Never manually concatenate name parts — FHIR names have `given[]`, `family`, `prefix[]`, `suffix[]`.
+
+# Medplum Frameworks
+
+## @medplum/core — SDK Client
+- Use `MedplumClient` for all FHIR operations. Never use raw `fetch` against Medplum endpoints.
+- Use `medplum.createResource()`, `readResource()`, `updateResource()`, `deleteResource()` for CRUD.
+- Use `medplum.searchResources()` for typed arrays. Use `medplum.searchOne()` when expecting a single result.
+- Use `medplum.executeBatch()` for transaction Bundles — groups multiple operations atomically.
+- Use `medplum.upsertResource(resource, query)` for atomic create-or-update.
+- Use `medplum.createResourceIfNoneExist(resource, query)` for idempotent creation.
+- Configure `autoBatchTime` on MedplumClient to auto-batch concurrent GET requests. Use `Promise.all()` instead of sequential `await` to benefit from batching.
+
+## @medplum/fhirtypes — Type Safety
+- Import FHIR types directly: `import { Patient, Observation } from '@medplum/fhirtypes'`.
+- Use TypeScript types for all FHIR resources — never use `any` for resource data.
+- Cast `event.input` in bot handlers: `const patient = event.input as Patient`.
+- Use optional chaining for nested FHIR fields: `patient.name?.[0]?.given?.[0]`.
+
+## @medplum/react — UI Components
+- Wrap app with `<MedplumProvider client={medplum}>` at the root.
+- Use `useMedplum()` hook to access the MedplumClient instance in components.
+- Use `useMedplumContext()` for client + profile + loading state together.
+- Use `<ResourceForm>` for auto-generated CRUD forms, `<ResourceTable>` for display.
+- Use `<SearchControl>` for searchable/filterable resource lists.
+- Use `<QuestionnaireForm>` to render FHIR Questionnaires and capture responses.
+- Use `useSubscription(criteria)` for real-time WebSocket data in React components.
+- Requires Mantine 7+ and PostCSS with Mantine preset. Import `@mantine/core/styles.css`.
+
+## Bot Development
+- Export a single `handler` function: `export async function handler(medplum: MedplumClient, event: BotEvent)`.
+- Access trigger resource via `event.input`. Access secrets via `event.secrets`.
+- Use `event.contentType` to determine input format (`application/fhir+json`, `text/plain`, `x-application/hl7-v2+er7`).
+- Deploy bots via CLI for CI/CD: `medplum bot deploy <bot-name>`.
+- Apply AccessPolicies to bots — restrict to minimum required resource types.
+- Use Subscriptions with `channel.type: 'rest-hook'` and `channel.endpoint: 'Bot/<ID>'` for event-driven execution.
+
+## GraphQL
+- Append `List` to resource type for searches: `PatientList(name: "Eve")`.
+- Use snake_case for search parameters in GraphQL (not kebab-case): `address_city`, not `address-city`.
+- Use inline fragments for reference resolution: `... on Observation { valueQuantity { value } }`.
+- Use `_reference` for reverse lookups: `EncounterList(_reference: patient)`.
+
+## CLI (@medplum/cli)
+- Use `medplum login` for auth, `medplum get`/`medplum post` for FHIR operations.
+- Use `medplum bot deploy` for bot deployment in CI/CD pipelines.
+- Use `medplum bulk export` for bulk data operations.
+
+# Medplum / FHIR Patterns
+
+## Bundle Transactions
+- Use `type: 'transaction'` for atomic multi-resource operations — all-or-nothing.
+- Use `type: 'batch'` when operations are independent and partial failure is acceptable.
+- Use `urn:uuid:<uuid>` in `fullUrl` for forward references between entries.
+- Reference other entries via `{ reference: 'urn:uuid:<uuid>' }`.
+- Use `ifNoneExist` on POST entries for conditional creation (idempotent).
+- Use `ifMatch: 'W/"versionId"'` on PUT entries for optimistic concurrency.
+- Use conditional references for existing resources: `Practitioner?identifier=http://hl7.org/fhir/sid/us-npi|123`.
+- For large bundles (>50MB), use `Prefer: respond-async` header.
+
+## Search Patterns
+- Use `_include=ResourceType:searchParam` to fetch referenced resources in one call.
+- Use `_revinclude=ResourceType:searchParam` to fetch resources referencing your results.
+- Use `:iterate` modifier for multi-hop traversal: `_include:iterate=Patient:general-practitioner`.
+- Use `_count` + `_offset` for pagination; use `searchResourcePages()` for async iteration.
+- Use `:contains` modifier for substring search on string params: `name:contains=eve`.
+- Use `:not` modifier to exclude: `status:not=completed`.
+- Use comma-separated values for OR: `status=active,on-hold`.
+- Use multiple parameters for AND: `name=Simpson&birthdate=1940-03-29`.
+- Prefer `searchResources()` over `search()` — returns typed array, not raw Bundle.
+
+## Subscription & Bot Workflows
+- Create a `Subscription` resource with `criteria` (FHIR search query) and `channel.type: 'rest-hook'`.
+- Point `channel.endpoint` to `Bot/<BOT_ID>` for automated processing.
+- Use `subscribeToCriteria()` client-side for WebSocket real-time updates.
+- Never subscribe to `AuditEvent` changes — prevents notification spirals.
+- Use cron-based bots for scheduled tasks (e.g., daily reports, batch processing).
+
+## Access Policies
+- Define `AccessPolicy.resource[]` with `resourceType` and optional `criteria`, `readonly`, `hiddenFields`, `readonlyFields`.
+- Use `%profile` variable to scope data to the current user: `Observation?performer=%profile`.
+- Use `%patient` variable for patient-portal access: `Observation?subject=%patient`.
+- Use compartment-based access for patient-scoped isolation.
+- Use `writeConstraint` with FHIRPath for state machine enforcement (e.g., prevent status rollback).
+- Apply least privilege: start with no access, add specific resource types.
+
+## Conditional Operations
+- Use `createResourceIfNoneExist(resource, query)` for idempotent creates keyed on identifier.
+- Use `upsertResource(resource, query)` for atomic create-or-update in a single request.
+- Use `If-None-Exist` header on POST for server-side conditional creation.
+
+## Patient Deduplication
+- Match on `identifier` systems (MRN, SSN, insurance ID) for deterministic matching.
+- Use probabilistic matching on name + birthdate + address for fuzzy matches.
+- Use Patient `link` field with `type: 'replaced-by'` for merge workflows.
+- Prefer `createResourceIfNoneExist()` at ingestion to prevent duplicates.
+
+## Questionnaire Workflows
+- Create `Questionnaire` resources for form definitions. Use `linkId` for question identification.
+- Use `QuestionnaireResponse` for captured answers. Link to Questionnaire via `questionnaire` field.
+- Use `getQuestionnaireAnswers(response)` to extract answers as a map keyed by `linkId`.
+- Automate post-submission processing with a Bot subscribed to `QuestionnaireResponse` creation.
+- Use SDC (Structured Data Capture) extensions for advanced rendering and extraction.
+
+# Medplum / FHIR Security
+
+## Authentication
+- Use client credentials flow (`startClientLogin`) for backend services and integrations.
+- Use authorization code flow (`startLogin` + `processCode`) for user-facing web apps.
+- Never store tokens in `localStorage` in production — use secure HTTP-only cookies or server-side sessions.
+- Use `refreshIfExpired()` before critical operations. Set `gracePeriod` to refresh proactively.
+- Use `setBasicAuth(clientId, clientSecret)` only for server-side code, never in browser.
+- Rotate client secrets via `$rotate-client-secret` operation periodically.
+
+## Access Policies
+- Every non-admin user must have an AccessPolicy. Never leave users with default full access.
+- Scope to specific resource types: list only the types the user needs.
+- Use `readonly: true` or explicit `interaction` arrays to restrict write access.
+- Use `criteria` with FHIR search syntax to filter visible resources (e.g., `Patient?organization=Organization/123`).
+- Use `hiddenFields` to prevent sensitive fields from being returned (e.g., SSN).
+- Use `readonlyFields` to allow viewing but prevent modification of specific fields.
+- Use `writeConstraint` FHIRPath expressions for business rules (e.g., prevent status rollback on finalized resources).
+- Test access policies by logging in as a test user with the policy applied.
+
+## HIPAA & Audit Logging
+- Medplum automatically creates AuditEvent resources for all FHIR operations.
+- Never log PHI (patient names, identifiers, health data) to application console or external services.
+- Use structured audit references: reference the Patient and the accessing Practitioner in audit records.
+- For custom audit trails, create AuditEvent resources with `type`, `agent`, `entity`, and `outcome`.
+- Ensure audit events are never silently dropped — if Medplum is unreachable, write to a fallback store.
+
+## PHI Handling
+- Never include PHI in URLs, query parameters, or HTTP headers.
+- Use POST-based search for queries containing sensitive criteria.
+- Use `Binary` resources with `securityContext` for sensitive file attachments.
+- Encrypt data at rest and in transit (TLS 1.2+). Medplum hosted handles this automatically.
+- Apply data retention policies — use `$expunge` operation for permanent deletion when required.
+
+## SMART Scopes
+- Use `patient/*.read` style scopes for patient-facing apps.
+- Use `user/*.read` style scopes for practitioner-facing apps.
+- Validate scopes server-side on every request — do not trust client-side scope claims.
+- Use `launch/patient` context for apps launched within a patient context.
+- Define minimal scopes: request only the resource types and operations needed.
+
+## Multi-Tenant Isolation
+- Use Medplum Projects for tenant isolation — each project is a separate data silo.
+- Never share AccessPolicies across projects/tenants.
+- Validate `meta.project` on operations when building multi-tenant middleware.
+- Use separate ClientApplications per tenant for backend integrations.
+
+## Secrets Management
+- Use Bot secrets (`event.secrets`) for API keys, connection strings, and credentials.
+- Never hardcode secrets in bot source code or resource data.
+- Use Medplum project-level secrets storage — accessible only by project admins.
+- Rotate secrets on a regular schedule and after any suspected compromise.
+
+# Medplum / FHIR Testing
+
+## MockClient
+- Use `MockClient` from `@medplum/mock` for unit tests — it simulates the full MedplumClient API in memory.
+- Pre-populate test data with `mockClient.createResource()` before running test assertions.
+- MockClient supports `search`, `searchResources`, `searchOne`, `readResource`, `updateResource`, `deleteResource`.
+- MockClient does not require network access — tests run fast and offline.
+- Use `new MockClient()` per test to ensure isolation between test cases.
+
+## Bot Unit Testing
+- Test the handler function directly: `await handler(mockClient, mockEvent)`.
+- Create mock `BotEvent` objects with `input`, `contentType`, `secrets`, and `bot` fields.
+- Verify resource creation: call `mockClient.searchResources()` after handler execution.
+- Test error paths: pass invalid input resources and assert the handler throws or returns errors.
+- Test different content types: `application/fhir+json`, `text/plain`, `x-application/hl7-v2+er7`.
+- Mock `event.secrets` for bots that depend on external API keys.
+
+## Resource Validation
+- Use `validateResource(resource)` from `@medplum/core` to check resources against StructureDefinitions.
+- Test that required fields produce `OperationOutcome` errors when missing.
+- Test custom profiles: create a `StructureDefinition` resource, then validate resources against it.
+- Use the `$validate` operation for server-side validation in integration tests.
+- Test the Data Absent Reason extension when required fields may legitimately be empty.
+
+## Search Testing
+- Test search parameter behavior: exact match vs prefix match vs substring (`name`, `name:exact`, `name:contains`).
+- Verify `_include` returns related resources in the Bundle.
+- Test pagination with `_count` and `_offset` parameters.
+- Test token search with and without system namespace: `identifier=value` vs `identifier=system|value`.
+- Test date range searches with comparison prefixes: `ge`, `le`, `gt`, `lt`.
+
+## Integration Testing
+- Use Medplum Docker image (`medplum/medplum-server`) for local integration tests.
+- Test full workflows end-to-end: create patient → create observation → search → verify.
+- Verify Bundle transactions are atomic: intentionally fail one entry and confirm rollback.
+- Test access policies by authenticating as users with different policies.
+- Test Subscription triggers: create a Subscription, modify a matching resource, verify Bot execution.
+
+## Test Data Factories
+- Create typed factory functions: `createTestPatient(overrides?)`, `createTestObservation(overrides?)`.
+- Use realistic but synthetic data — never use real patient data in tests.
+- Include only minimal required fields by default. Let tests add specific fields via overrides.
+- Use `generateId()` from `@medplum/core` for unique test identifiers.
+- Use standard test identifier systems: `http://example.com/test-mrn` to avoid collision with real systems.
+
+## Assertions
+- Assert on `OperationOutcome` for error responses: check `issue[].severity`, `issue[].code`, `issue[].expression`.
+- Use `isOk(outcome)` and `isNotFound(outcome)` from `@medplum/core` for status checks.
+- Use `deepEquals(a, b)` for resource comparison (ignores `meta.versionId` and `meta.lastUpdated`).
+- Assert reference integrity: verify `subject.reference` matches expected `Patient/id` format.