Update README with features checklist and profile examples

Author: ryukzak

CLAUDE.md

@@ -267,13 +267,6 @@ Located in `src/api/writer-generator/`:
 4. Use `build()` instead of `generate()` for testing
 5. Run `bun run quality` before committing (combines typecheck, lint, test:unit)
 
-## Roadmap Context
-
-This toolkit focuses on type generation and code generation:
-- **Current**: TypeScript, Python, C# interface/class generation from FHIR R4
-- **In Progress**: R5 support, profile/extension enhancements
-- **Planned**: Rust, GraphQL, OpenAPI, validation functions, mock data generation
-
 ## Useful External Resources
 
 - [FHIR Specification](https://www.hl7.org/fhir/)

README.md

@@ -23,7 +23,6 @@
     - [Generation](#generation)
       - [1. Writer-Based Generation (Programmatic)](#1-writer-based-generation-programmatic)
       - [2. Mustache Template-Based Generation (Declarative)](#2-mustache-template-based-generation-declarative)
-  - [Roadmap](#roadmap)
   - [Support](#support)
 - [Footnotes](#footnotes)
 
@@ -41,14 +40,32 @@ Guides:
 
 ## Features
 
-- 🚀 **High-Performance** - Built with Bun runtime for blazing-fast generation
-- 🔧 **Extensible Architecture** - Three-stage pipeline:
-  - FHIR package management & canonical resolution
-  - Optimized intermediate FHIR data entities representation via Type Schema
-  - Generation for different programming languages
-- 📦 **Multi-Package Support** - Generate from a list of FHIR packages
-- 🎯 **Type-Safe** - Generates fully typed interfaces with proper inheritance
-- 🛠️ **Developer Friendly** - Fluent API
+- [x] **Multi-Package Support** — Load packages from the [FHIR registry](examples/typescript-r4/), [remote TGZ files](examples/typescript-sql-on-fhir/), or a [local folder with custom StructureDefinitions](examples/local-package-folder/)
+  - Tested with hl7.fhir.r4.core, US Core, C-CDA, SQL on FHIR, etc.
+- [x] **Resources & Complex Types** — Generates typed definitions with proper inheritance
+- [x] **Value Set Bindings** — Strongly-typed enums from FHIR terminology bindings
+- [x] **Profiles & Extensions** — Factory methods with auto-populated fixed values and required slices ([R4 profiles](examples/typescript-r4/profile-bp.test.ts), [US Core](examples/typescript-us-core/))
+  - Extensions — flat typed accessors (e.g. `setRace()` on US Core Patient), [standalone extension profiles](examples/typescript-r4/extension-profile.test.ts)
+  - Slicing — typed get/set accessors with discriminator matching
+  - Validation — runtime `validate()` for required fields, fixed values, slice cardinality, enums, references
+- [x] **Extensible Architecture** — Three-stage pipeline: FHIR packages → [TypeSchema](https://www.health-samurai.io/articles/type-schema-a-pragmatic-approach-to-build-fhir-sdk) IR → code generation
+  - TypeSchema is a universal intermediate representation — add a new language by writing only the final generation stage
+  - Built-in generators: TypeScript, Python/Pydantic, C#, and Mustache templates
+- [x] **TypeSchema Transformations**:
+  - [x] Tree Shaking — include only the resources and fields you need; automatically resolves dependencies
+  - [x] Logical Model Promotion — promote FHIR logical models (e.g. CDA ClinicalDocument) to first-class resources
+  - [ ] Renaming — custom naming conventions for generated types, fields, packages, etc.
+- [ ] **Search Builders** — type-safe FHIR search query construction
+- [ ] **Operation Generation** — type-safe FHIR operation calls
+
+| Feature | TypeSchema | TypeScript | Python | C# | Mustache |
+|---|---|---|---|---|---|
+| Resources & Complex Types | yes | yes | yes | yes | template |
+| Value Set Bindings | yes | inline | inline | enum | template |
+| Profiles & Extensions | yes | yes | no | no | no |
+| Tree Shaking | yes | 〃 | 〃 | 〃 | 〃 |
+| Logical Model Promotion | yes | 〃 | 〃 | 〃 | 〃 |
+
 
 ## Versions & Release Cycle
 
@@ -298,107 +315,61 @@ Templates enable flexible code generation for any language or format (Go, Rust,
 
 ### Profile Classes
 
-When generating TypeScript with `generateProfile: true`, the generator creates profile wrapper classes that provide a fluent API for working with FHIR profiles (US Core, etc.). These classes handle complex profile constraints like slicing and extensions automatically.
+When generating TypeScript with `generateProfile: true`, the generator creates profile wrapper classes that provide a fluent API for working with FHIR profiles. These classes handle complex profile constraints like slicing and extensions automatically.
 
 ```typescript
-import { Patient } from "./fhir-types/hl7-fhir-r4-core/Patient";
-import { USCorePatientProfileProfile } from "./fhir-types/hl7-fhir-us-core/profiles/UscorePatientProfile";
-
-// Wrap a FHIR resource with a profile class
-const resource: Patient = { resourceType: "Patient" };
-const profile = new USCorePatientProfileProfile(resource);
+import { observation_bpProfile as bpProfile } from "./profiles/Observation_observation_bp";
 
-// Set extensions using flat API - complex extensions are simplified
-profile.setRace({
-    ombCategory: { system: "urn:oid:2.16.840.1.113883.6.238", code: "2106-3", display: "White" },
-    text: "White",
+// create() auto-sets fixed values (code, meta.profile) and required slice stubs
+const bp = bpProfile.create({
+    status: "final",
+    subject: { reference: "Patient/pt-1" },
 });
 
-// Set simple extensions directly
-profile.setSex({ system: "http://hl7.org/fhir/administrative-gender", code: "male" });
-
-// Get extension values - flat API returns simplified object
-const race = profile.getRace();
-console.log(race?.ombCategory?.display); // "White"
+// Slice setters — discriminator values (LOINC codes) applied automatically
+// Single-variant choice types (value[x] → valueQuantity) are flattened:
+bp.setVSCat({ text: "Vital Signs" })
+    .setSystolicBP({ value: 120, unit: "mmHg" })
+    .setDiastolicBP({ value: 80, unit: "mmHg" })
+    .setEffectiveDateTime("2024-06-15");
 
-// Get raw FHIR Extension when needed
-const raceExtension = profile.getRaceExtension();
-console.log(raceExtension?.url); // "http://hl7.org/fhir/us/core/StructureDefinition/us-core-race"
+bp.validate(); // [] — valid
 
-// Get the underlying resource
-const patientResource = profile.toResource();
+// Get plain FHIR JSON — ready for API calls, storage, etc.
+const obs = bp.toResource();
+// obs.component[0].valueQuantity.value === 120
+// obs.component[0].code.coding[0].code === "8480-6"
 ```
 
-**Slicing Support:**
-
-Profile classes also handle FHIR slicing, automatically applying discriminator values:
+**Slicing & Choice Type Flattening:**
 
 ```typescript
-import { Observation } from "./fhir-types/hl7-fhir-r4-core/Observation";
-import { USCoreBloodPressureProfileProfile } from "./fhir-types/hl7-fhir-us-core/profiles/UscoreBloodPressureProfile";
-
-const obs: Observation = { resourceType: "Observation", status: "final", code: {} };
-const bp = new USCoreBloodPressureProfileProfile(obs);
+// Simplified getter — discriminator stripped, choice type flattened
+bp.getSystolicBP();    // { value: 120, unit: "mmHg" }
 
-// Set slices - discriminator is applied automatically
-// No input needed when all fields are part of the discriminator
-bp.setSystolic({ valueQuantity: { value: 120, unit: "mmHg" } });
-bp.setDiastolic({ valueQuantity: { value: 80, unit: "mmHg" } });
-
-// Get simplified slice (without discriminator fields)
-const systolic = bp.getSystolic();
-console.log(systolic?.valueQuantity?.value); // 120
-
-// Get raw slice (includes discriminator)
-const systolicRaw = bp.getSystolicRaw();
-console.log(systolicRaw?.code?.coding?.[0]?.code); // "8480-6" (LOINC code for systolic BP)
+// Raw getter — full FHIR element including discriminator values
+bp.getSystolicBPRaw(); // { code: { coding: [...] }, valueQuantity: { value: 120, ... } }
 ```
 
-See [examples/typescript-us-core/](examples/typescript-us-core/) for complete profile usage examples.
-
-## Roadmap
-
-- [x] TypeScript generation
-- [x] FHIR R4 core package support
-- [x] Configuration file support
-- [x] Comprehensive test suite (72+ tests)
-- [x] **Value Set Generation** - Strongly-typed enums from FHIR bindings
-- [x] **Profile & Extension Support** - Basic parsing (US Core in development)
-- [ ] **Complete Multi-Package Support** - Custom packages and dependencies
-- [ ] **Smart Chained Search** - Intelligent search builders
+**Wrapping Existing Resources:**
 
-    ```typescript
-    // Intelligent search builders
-    const results = await client.Patient
-        .search()
-        .name().contains('Smith')
-        .birthdate().greaterThan('2000-01-01')
-        .address().city().equals('Boston')
-        .include('Patient:organization')
-        .sort('birthdate', 'desc')
-        .execute();
-    ```
+```typescript
+// Wrap any resource to read slices
+const bp2 = bpProfile.from(existingObservation);
+bp2.getSystolicBP();       // { value: 120, unit: "mmHg" }
+bp2.getVSCat();            // { text: "Vital Signs" }
+bp2.getEffectiveDateTime(); // "2024-06-15"
+```
 
-- [ ] **Operation Generation** - Type-safe FHIR operations
+**Validation:**
 
-    ```typescript
-    // Type-safe FHIR operations
-    const result = await client.Patient
-        .operation('$match')
-        .withParameters({
-            resource: patient,
-            onlyCertainMatches: true
-        })
-        .execute();
-    ```
+```typescript
+const errors = bp.validate();
+// [] — empty means valid
+// ["effective: at least one of effectiveDateTime, effectivePeriod is required"]
+```
 
-- [x] **Python generation**
-- [x] **C# generation**
-- [ ] **Rust generation**
-- [ ] **GraphQL schema generation**
-- [ ] **OpenAPI specification generation**
-- [ ] **Validation functions**
-- [ ] **Mock data generation**
+See [examples/typescript-r4/](examples/typescript-r4/) for R4 profile tests and [examples/typescript-us-core/](examples/typescript-us-core/) for US Core profile examples.
 
 ## Support
 

docs/posts/typescript-profiles-quick.md

@@ -1,60 +1,55 @@
-# TypeScript Profile Classes in Atomic EHR Codegen
+# Profile codegen for TypeScript
 
-We've added FHIR profile support to the TypeScript generator in [Atomic EHR Codegen](https://github.com/atomic-ehr/codegen). Profiles generate as wrapper classes with typed accessors, automatic slice handling, and runtime validation -- all on top of plain FHIR JSON.
-
-## Quick look
+[@atomic-ehr/codegen](https://github.com/atomic-ehr/codegen) is an open-source toolkit that generates strongly-typed code from FHIR packages. We've added **FHIR profile support** for TypeScript (dev preview) -- propagation of fixed values, slice & extension getters/setters, and primitive client-side validation:
 
 ```typescript
 import { observation_bpProfile } from "./profiles/Observation_observation_bp";
 
+// create() auto-sets fixed values and required slice stubs
 const bp = observation_bpProfile.create({
     status: "final",
     subject: { reference: "Patient/pt-1" },
 });
 
-// Slice setters -- discriminator values (LOINC codes) applied automatically
-// Single-variant choice types (value[x] → valueQuantity) are flattened:
+// Slice setters -- discriminator values applied automatically
+// Choice types constrained to a single variant are flattened (value[x] → Quantity fields):
 bp.setVSCat({ text: "Vital Signs" })
     .setSystolicBP({ value: 120, unit: "mmHg" })
     .setDiastolicBP({ value: 80, unit: "mmHg" })
     .setEffectiveDateTime("2024-06-15");
 
-// Validate against profile constraints
 bp.validate(); // [] -- valid
 
-// Get plain FHIR JSON -- ready for API calls, storage, etc.
+// Plain FHIR JSON -- ready for API calls, storage, etc.
 const obs = bp.toResource();
-// {
-//   resourceType: "Observation",
-//   meta: { profile: ["http://hl7.org/fhir/StructureDefinition/bp"] },
-//   status: "final",
-//   code: { coding: [{ code: "85354-9", system: "http://loinc.org" }] },
-//   category: [{ coding: [{ code: "vital-signs", system: "http://...observation-category" }] }],
-//   subject: { reference: "Patient/pt-1" },
-//   effectiveDateTime: "2024-06-15",
-//   component: [
-//     { code: { coding: [{ code: "8480-6", system: "http://loinc.org" }] }, valueQuantity: { value: 120, unit: "mmHg" } },
-//     { code: { coding: [{ code: "8462-4", system: "http://loinc.org" }] }, valueQuantity: { value: 80, unit: "mmHg" } },
-//   ],
-// }
-
-// Wrap any Observation back into a profile to read slices
-const bp2 = observation_bpProfile.from(obs);
-
-bp2.getSystolicBP();    // { value: 120, unit: "mmHg" }  -- flattened from valueQuantity
-bp2.getDiastolicBP();   // { value: 80, unit: "mmHg" }
-bp2.getVSCat();         // { text: "Vital Signs" }
+```
+
+Wrapping an existing resource to read slices back:
+
+```typescript
+const bp2 = observation_bpProfile.from(existingObservation);
+
+bp2.getSystolicBP();        // { value: 120, unit: "mmHg" }  -- flattened
+bp2.getDiastolicBP();       // { value: 80, unit: "mmHg" }
+bp2.getVSCat();             // { text: "Vital Signs" }
 bp2.getEffectiveDateTime(); // "2024-06-15"
 
 // Raw getters return the full FHIR element including discriminator values
-bp2.getSystolicBPRaw(); // { code: { coding: [{ code: "8480-6", ... }] }, valueQuantity: { value: 120, ... } }
+bp2.getSystolicBPRaw();
+// { code: { coding: [{ code: "8480-6", ... }] }, valueQuantity: { value: 120, ... } }
 ```
 
-Supports resource profiles, simple/complex extension profiles, slice accessors, choice types, and `validate()` checking required fields, fixed values, slice cardinality, enum bindings, and reference types.
+What's supported: resource profiles, extension profiles (simple and complex), slice accessors, choice type flattening, and `validate()` checking required fields, fixed values, slice cardinality, enum bindings, and reference types.
+
+Working examples:
+
+- [R4 profiles](https://github.com/atomic-ehr/codegen/tree/main/examples/typescript-r4) -- blood pressure, bodyweight, vitals, extensions
+- [US Core profiles](https://github.com/atomic-ehr/codegen/tree/main/examples/typescript-us-core) -- patient, conditions, observations, diagnostics
+
+## Current status and what's next
 
-## Looking for feedback
+This is a **dev preview**. Our main focus right now is stabilization across different profile shapes and edge cases. We're using it ourselves for a FHIR-to-CCDA converter, which is a good stress test for the generator. After stabilization, the plan is to bring profile support to Python next.
 
-This is an early iteration. We'd appreciate hearing about profiles that don't generate correctly, API patterns that feel awkward, or validation gaps.
+We'd appreciate any feedback -- profiles that don't generate correctly, API patterns that feel awkward, validation gaps, or anything else. Issues and discussions welcome on [GitHub](https://github.com/atomic-ehr/codegen).
 
-GitHub: https://github.com/atomic-ehr/codegen
-NPM: `@atomic-ehr/codegen`
+NPM: [`@atomic-ehr/codegen`](https://www.npmjs.com/package/@atomic-ehr/codegen)