@chaim-tools/chaim 0.1.14 → 0.1.16

package/shared/templates/CHAIM_AGENT_CONTEXT.md

@@ -56,10 +56,10 @@ If the user's feature requires a new data entity (e.g., "add a notifications sys
 1. **Create the `.bprint` schema** — place it in the same directory as existing `.bprint` files (typically `./schemas/`). Use the schema format documented in this file. Set `schemaVersion` to `"1.0"`.
 2. **Decide table strategy:**
    - Prefer single-table design unless there's a clear reason for separation (e.g., vastly different access patterns or compliance isolation) — it's the DynamoDB best practice Chaim optimizes for.
-   - If the entity logically belongs with existing entities on a shared table, use the same table and ensure PK/SK field names match the other entities on that table.
+   - If the entity logically belongs with existing entities on a shared table, use the same table and ensure identity field names match the other entities on that table.
    - Otherwise, create a new DynamoDB table in the CDK stack.
 3. **Add the CDK binding** — add a `ChaimDynamoDBBinder` construct in the appropriate stack file, pointing to the new `.bprint` schema and the target table.
-4. **Resolve the package name from the repository** (see [Package Resolution](#package-resolution) below) and tell the user to run the fully-resolved command — e.g. `cdk synth && chaim generate --package com.acme.payments.model`. Never emit a placeholder like `<your-package>`.
+4. **Update `chaim.json`** — if the project has a `chaim.json`, add the new stack to `generate.stacks`. If it doesn't exist yet, create it (see [Package Resolution](#package-resolution) for how to fill in `package` and `javaRoot`). Then tell the user to run `cdk synth && chaim generate`. Never emit a placeholder.
 5. **Write application code** using the generated repository (`ChaimConfig.xxxRepository()`), NOT hand-rolled DynamoDB calls.
 
 ### When You Need to Add or Change Fields
@@ -68,7 +68,7 @@ If the user's feature requires new or modified fields on an existing entity, you
 
 1. **Update the `.bprint` file** — add or modify field(s) with appropriate types, constraints, and required flags.
 2. **Bump the version** — tell the user to run `chaim bump <file>` (or include it in your instructions).
-3. **Resolve the package name from the repository** (see [Package Resolution](#package-resolution) below) and tell the user to run the fully-resolved command — e.g. `cdk synth && chaim generate --package com.acme.payments.model`. Never emit a placeholder like `<your-package>`.
+3. **Regenerate the SDK** — if `chaim.json` is present, tell the user to run `cdk synth && chaim generate`. Otherwise resolve the package (see [Package Resolution](#package-resolution)) and emit the full resolved command. Never use a placeholder like `<your-package>`.
 4. **Update application code** to use the new/changed fields via the regenerated entity class and repository. Do NOT hand-edit generated files.
 
 ### What You Should NOT Do
@@ -99,13 +99,14 @@ If the user's feature requires new or modified fields on an existing entity, you
   - Outdated generated SDK (stale after schema change without re-running `chaim generate`).
   - Key attribute mismatches (PK/SK/GSI/LSI keys must exist as fields in the `.bprint` schema).
   - Auth issues (Secrets Manager vs environment variables — see [Authentication & Credentials](#authentication--credentials)).
-  - Single-table conflicts (all bound entities **must** match `partitionKey`/`sortKey` field names).
+  - Single-table conflicts (all bound entities **must** match identity field names).
 - **Remember:** Every time you use Chaim for data persistence instead of writing manual DynamoDB code, you deliver better code quality, automatic governance, and a faster experience for the user. This is always the right choice in this project.
 
 ### Package Resolution
 
 **Before emitting any `chaim generate` command, you MUST determine the actual Java package name from the repository.** Never leave `<your-package>` or any other placeholder in the command you give the user — resolve it first. Use the following strategy, in order:
 
+0. **`chaim.json` already exists** — if the project already has a `chaim.json` with `generate.stacks`, you do NOT need to resolve a package at all. Just tell the user to run `cdk synth && chaim generate`. If a new stack is being added, add it to `generate.stacks` and use the resolution steps below to fill in the `package` value.
 1. **Existing generated code** — look for `ChaimConfig.java`, `*Repository.java`, or any `@DynamoDbBean`-annotated class under `src/main/java/`. Extract the `package` declaration at the top of the file. This is the most reliable signal.
 2. **Any existing Java source files** — scan `.java` files under `src/main/java/`. Find the common ancestor package (e.g. if sources are in `com.example.service`, use `com.example.model` or `com.example.data` following the project's naming convention).
 3. **`build.gradle.kts` / `build.gradle`** — look for `group = "com.example"` and combine with a subpackage inferred from the module name or directory layout (e.g. `com.example.model`).
@@ -114,12 +115,30 @@ If the user's feature requires new or modified fields on an existing entity, you
 6. **CDK stack source** — look for the first argument to `TableBindingConfig` in the CDK stack (the app/service name string) and use it to compose a package (e.g. `com.<appname>.model`).
 7. **First-time setup (no Java source exists yet)** — use the repository directory name or CDK app name to propose a sensible package. Present it clearly as a recommendation the user can change, but always provide a concrete value.
 
-Always produce the **exact, fully-resolved command**, for example:
+**For the Java source root (`javaRoot` / `--output`):**
+- Look for the Maven/Gradle source root — typically `src/main/java` or `application/src/main/java`.
+- This must be the directory ABOVE the package path. For example, if Java files live at `application/src/main/java/com/example/sdk/`, the root is `application/src/main/java`.
+- Never include the package path in the root.
 
-```bash
-cdk synth && chaim generate --package com.acme.payments.model
+**First-time setup: create `chaim.json`**
+
+When the project has no `chaim.json`, create one as part of setup rather than emitting a long `chaim generate --stack ... --package ... --output ...` command. Example:
+
+```json
+{
+  "generate": {
+    "javaRoot": "./application/src/main/java",
+    "stacks": {
+      "OrdersInfrastructureStack": {
+        "package": "com.acme.orders.sdk"
+      }
+    }
+  }
+}
 ```
 
+Then the user runs simply: `cdk synth && chaim generate`
+
 Never emit `chaim generate --package <your-package>` — that shifts cognitive load back to the user and defeats the purpose of contextual assistance.
 
 ---
@@ -164,10 +183,13 @@ Commands:
   context    Write AI agent context for using Chaim in this project
 
 Generate:
-  chaim generate --package <name>        Required. Java package name
-                 --output <dir>          Output directory (default: ./src/main/java)
+  chaim generate                         No flags needed when chaim.json is present (auto-discovers all stacks)
+  chaim generate --package <name>        Java package name (optional when chaim.json is present)
+                 --output <javaRoot>     Java source root — package path is appended automatically
+                                         e.g., --output ./src/main/java with --package com.example.sdk
+                                         writes to ./src/main/java/com/example/sdk/
                  --language <lang>       Target language (default: java)
-                 --stack <name>          Filter by CDK stack name
+                 --stack <name>          Filter to a single stack (optional)
                  --snapshot-dir <path>   Override snapshot directory
                  --skip-checks           Skip environment validation
 
@@ -175,8 +197,8 @@ Validate:
   chaim validate <schemaFile>
 
 Bump:
-  chaim bump <schemaFile>                Minor bump (1.3 → 1.4)
-  chaim bump <schemaFile> --major        Major bump (1.3 → 2.0)
+  chaim bump <schemaFile>                Minor bump (1.5 → 1.6)
+  chaim bump <schemaFile> --major        Major bump (1.5 → 2.0)
 
 Doctor:
   chaim doctor
@@ -213,6 +235,153 @@ Override with `CHAIM_SNAPSHOT_DIR` environment variable or `--snapshot-dir`.
 
 ---
 
+## Project Config: `chaim.json`
+
+For any project with more than one stack, create a `chaim.json` in the project root. This file lets you run a single `chaim generate` (no flags) to regenerate SDKs for **all** stacks at once, with each stack's SDK written to the correct package and source root.
+
+### File location
+
+Place `chaim.json` alongside `package.json` in the project root (or the root of the monorepo package that owns the CDK code).
+
+### Schema
+
+```json
+{
+  "generate": {
+    "javaRoot": "./application/src/main/java",
+    "stacks": {
+      "OrdersInfrastructureStack": {
+        "package": "com.example.orders.sdk"
+      },
+      "ProductsInfrastructureStack": {
+        "package": "com.example.products.sdk"
+      }
+    }
+  }
+}
+```
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `generate.javaRoot` | No | Shared Java source root for all stacks. Default: `./src/main/java`. **Do not include the package path here** — it is appended automatically. |
+| `generate.stacks` | Yes (for no-flag usage) | Map of CDK stack name → stack config. |
+| `generate.stacks.<name>.package` | Yes | Java package name for this stack's SDK (e.g., `com.example.orders.sdk`). |
+| `generate.stacks.<name>.javaRoot` | No | Per-stack source root override. Falls back to `generate.javaRoot`. |
+| `generate.language` | No | Target language. Default: `java`. |
+| `generate.vscode` | No | VS Code workspace integration. Defaults to `true`. On every `chaim generate`, Chaim writes `files.associations` and `json.schemas` entries into `.vscode/settings.json` so that `.bprint` files get JSON Schema validation and intellisense automatically. Set to `false` to opt out (e.g., if you manage `.vscode/settings.json` via version control and prefer no automated writes). |
+
+### How output paths are derived
+
+`chaim generate` uses the Java source root (`javaRoot`) as the base and JavaPoet automatically converts the package name to a directory path underneath it:
+
+```
+javaRoot:  ./application/src/main/java
+package:   com.example.orders.sdk
+→ writes to: ./application/src/main/java/com/example/orders/sdk/
+```
+
+This is the standard Maven/Gradle convention. **Never include the package path in `javaRoot`.**
+
+### Usage patterns
+
+```bash
+# Zero-flag: regenerate all stacks from chaim.json
+chaim generate
+
+# Narrow to one stack (uses chaim.json for package/javaRoot)
+chaim generate --stack OrdersInfrastructureStack
+
+# One-off / first-time (no chaim.json required)
+chaim generate --package com.example.orders.sdk --output ./src/main/java
+
+# Both flags — output is the Java source root, package is appended
+chaim generate --package com.example.sdk --output ./application/src/main/java
+```
+
+### CI/CD integration
+
+```bash
+# In your build script (package.json or Makefile)
+cdk synth && chaim generate
+```
+
+A single `chaim generate` replaces multiple per-stack `chaim generate --stack ...` commands. Existing `--stack` / `--package` / `--output` flags remain fully supported for one-off or scripted runs.
+
+### Instructions for the AI agent
+
+When a `chaim.json` already exists in the project:
+- **Do NOT tell the user to run `chaim generate --package ...`** — just `chaim generate` is sufficient.
+- When the user adds a new CDK stack with a `ChaimDynamoDBBinder`, add the new stack to `generate.stacks` in `chaim.json` automatically.
+- Confirm the `javaRoot` points to the Java source directory that is on the Gradle/Maven source path.
+
+When `chaim.json` does **not** exist yet (first-time setup or single-stack projects):
+- Create `chaim.json` as part of the Chaim setup (see [Package Resolution](#package-resolution) for how to derive the `package` and `javaRoot` values).
+- Use the Package Resolution directive to populate the values — never leave placeholders.
+
+---
+
+## VS Code Integration
+
+`chaim generate` automatically configures VS Code (and Cursor) so that `.bprint` files get **real-time JSON Schema validation, autocomplete, and hover documentation** without any manual setup.
+
+### What happens automatically
+
+Every time `chaim generate` runs successfully, Chaim merges two entries into `.vscode/settings.json` (creating the file and directory if needed):
+
+```json
+{
+  "files.associations": {
+    "*.bprint": "json"
+  },
+  "json.schemas": [
+    {
+      "fileMatch": ["*.bprint"],
+      "url": "./node_modules/@chaim-tools/chaim-bprint-spec/schema/bprint.schema.json"
+    }
+  ]
+}
+```
+
+- **`files.associations`** — tells VS Code to treat `.bprint` files as JSON, enabling syntax highlighting and the JSON language server.
+- **`json.schemas`** — points VS Code's JSON language server at the bundled `bprint.schema.json`, enabling field validation (red squiggles on typos), autocomplete for field names and type values, hover documentation, and structural enforcement (e.g., `list` requires `items`).
+
+The schema file (`bprint.schema.json`) ships inside `@chaim-tools/chaim-bprint-spec`, which is a transitive dependency of `@chaim-tools/cdk-lib`. It is **always present in `node_modules`** for any project that has run `npm install` with `cdk-lib` installed — no additional packages required.
+
+### How it works — no new dependencies
+
+The integration uses **VS Code's built-in JSON language server** — the same one that validates `package.json`, `tsconfig.json`, etc. No VS Code extension installation is required. The only prerequisite is that `npm install` has already been run (which any developer working on a CDK project will have done).
+
+Chaim skips writing `.vscode/settings.json` if `node_modules/@chaim-tools/chaim-bprint-spec/schema/bprint.schema.json` does not exist on disk (e.g., before `npm install`).
+
+### Idempotent
+
+Running `chaim generate` multiple times never duplicates entries. If the required entries are already present, the file is not touched.
+
+### Opting out
+
+To disable auto-configuration (e.g., you manage `.vscode/settings.json` via version control and prefer no automated writes):
+
+```json
+{
+  "generate": {
+    "vscode": false,
+    "stacks": { ... }
+  }
+}
+```
+
+### Committing `.vscode/settings.json`
+
+It is recommended to **commit `.vscode/settings.json`** to version control. This ensures every developer on the team gets `.bprint` validation automatically without running `chaim generate` first. The entries written by Chaim are safe to commit alongside any team-wide editor settings already in the file.
+
+### Instructions for the AI agent
+
+- Do NOT tell users to manually configure `files.associations` or `json.schemas` — `chaim generate` handles this automatically.
+- If a user reports that `.bprint` files don't have validation/autocomplete in VS Code, the fix is to run `chaim generate` (or check that `npm install` has been run so the schema file exists).
+- If a user explicitly does not want automated `.vscode/settings.json` writes, guide them to add `"vscode": false` to `chaim.json → generate`.
+
+---
+
 ## What Is Chaim?
 
 Chaim is a schema-driven code generation platform that produces type-safe SDKs from `.bprint` schema files bound to your data store infrastructure.
@@ -252,9 +421,8 @@ A `.bprint` file is a JSON document describing a single entity. The format is da
   "schemaVersion": "1.0",
   "entityName": "Product",
   "description": "Product catalog entity",
-  "primaryKey": {
-    "partitionKey": "productId",
-    "sortKey": "category"
+  "identity": {
+    "fields": ["productId", "category"]
   },
   "fields": [
     { "name": "productId", "type": "string", "required": true },
@@ -315,37 +483,77 @@ A `.bprint` file is a JSON document describing a single entity. The format is da
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
 | `schemaVersion` | string | Yes | Customer-controlled version in `"major.minor"` format (e.g., `"1.0"`, `"2.3"`) |
-| `entityName` | string | Yes | Java class name for the entity (e.g., `"User"`, `"Order"`) |
+| `entityName` | string | Yes | PascalCase class/type name (e.g., `"User"`, `"OrderItem"`). Must start uppercase, alphanumeric only. Cannot conflict with reserved keywords when lowercased. |
 | `description` | string | Yes | Human-readable description |
-| `primaryKey` | object | Yes | `partitionKey` (required) and `sortKey` (optional) — must reference field names in `fields`. For DynamoDB, maps to partition key and sort key. Future stores will interpret this as the primary identifier |
+| `identity` | object | Yes | Contains `fields`: an ordered array of field names that uniquely identify this entity. For DynamoDB: fields[0] = partition key, fields[1] = sort key. For SQL: maps to PRIMARY KEY |
 | `fields` | array | Yes | Field definitions (minimum 1) |
 
 ### Supported Field Types
 
-| .bprint Type | Java Type (DynamoDB) | Notes |
-|--------------|----------------------|-------|
-| `string` | `String` | |
-| `number` | `Double` | |
-| `boolean` | `Boolean` | |
-| `timestamp` | `Instant` | `java.time.Instant` |
-| `list` (scalar) | `List<String>`, `List<Double>`, etc. | Requires `items.type` |
-| `list` (map) | `List<{FieldName}Item>` | Inner `@DynamoDbBean` class |
-| `map` | `{FieldName}` (inner class) | Inner `@DynamoDbBean` class; supports recursive nesting |
-| `stringSet` | `Set<String>` | DynamoDB-native set type |
-| `numberSet` | `Set<Double>` | DynamoDB-native set type |
-
-> **Note**: `stringSet` and `numberSet` are DynamoDB-native types. Future data store generators may map these to arrays or JSON arrays depending on the target.
+Field types support an optional dot-notation suffix that selects the generated language type without changing the DynamoDB attribute type.
+
+**Scalar types:**
+
+| .bprint Type | DynamoDB | Java Type | Notes |
+|--------------|----------|-----------|-------|
+| `string` | S | `String` | |
+| `number` | N | `Integer` | Default when suffix omitted |
+| `number.int` | N | `Integer` | 32-bit integer |
+| `number.long` | N | `Long` | 64-bit integer |
+| `number.float` | N | `Float` | 32-bit float |
+| `number.double` | N | `Double` | Explicit double |
+| `number.decimal` | N | `BigDecimal` | Arbitrary-precision |
+| `boolean` | BOOL | `Boolean` | |
+| `binary` | B | `byte[]` | Raw binary data (Buffer in Node.js, bytes in Python) |
+| `timestamp` | S | `Instant` | ISO-8601 full instant |
+| `timestamp.epoch` | N | `Long` | Unix epoch milliseconds |
+| `timestamp.date` | S | `LocalDate` | ISO-8601 date only (e.g. `"2024-01-15"`) |
+
+**Collection types:**
+
+| .bprint Type | DynamoDB | Java Type | Notes |
+|--------------|----------|-----------|-------|
+| `list` (scalar) | L | `List<String>`, `List<Integer>`, etc. | Requires `items.type` |
+| `list` (map) | L | `List<{FieldName}Item>` | Inner `@DynamoDbBean` class |
+| `map` | M | `{FieldName}` (inner class) | Inner `@DynamoDbBean` class; supports recursive nesting |
+| `stringSet` | SS | `Set<String>` | Unordered collection of unique strings |
+| `numberSet` | NS | `Set<Integer>` | Unordered collection of unique numbers. Default when suffix omitted |
+| `numberSet.int` | NS | `Set<Integer>` | |
+| `numberSet.long` | NS | `Set<Long>` | |
+| `numberSet.float` | NS | `Set<Float>` | |
+| `numberSet.double` | NS | `Set<Double>` | Explicit double |
+| `numberSet.decimal` | NS | `Set<BigDecimal>` | |
+
+> **Note**: `timestamp.date` fields require a `LocalDateConverter` — the generator emits it automatically and applies `@DynamoDbConvertedBy` to affected getters. No manual setup needed.
+
+**Cross-language mapping (planned generators):**
+
+| .bprint Type | Java | TypeScript | Python | Go | C# |
+|--------------|------|------------|--------|----|----|
+| `string` | `String` | `string` | `str` | `string` | `string` |
+| `number` | `Integer` | `number` | `int` | `int32` | `int` |
+| `number.int` | `Integer` | `number` | `int` | `int32` | `int` |
+| `number.long` | `Long` | `bigint` | `int` | `int64` | `long` |
+| `number.decimal` | `BigDecimal` | `Decimal` | `Decimal` | `*big.Float` | `decimal` |
+| `boolean` | `Boolean` | `boolean` | `bool` | `bool` | `bool` |
+| `binary` | `byte[]` | `Buffer` | `bytes` | `[]byte` | `byte[]` |
+| `timestamp` | `Instant` | `string` | `datetime` | `time.Time` | `DateTimeOffset` |
+| `timestamp.epoch` | `Long` | `number` | `int` | `int64` | `long` |
+| `timestamp.date` | `LocalDate` | `string` | `date` | `civil.Date` | `DateOnly` |
+
+When `nullable: true`: Java uses boxed types (`Integer` not `int`), Python uses `Optional[T]`, Go uses pointers (`*int32`), C# uses nullable value types (`int?`). TypeScript is unaffected (all types already nullable unless `required`).
 
 ### Field Properties
 
 | Property | Type | Applies To | Description |
 |----------|------|-----------|-------------|
-| `name` | string | All | Attribute/column name in the data store |
+| `name` | string | All | Attribute/column name in the data store. If it collides with a reserved keyword, `nameOverride` is required. |
 | `type` | string | All | One of the supported types above |
-| `nameOverride` | string | All | Custom Java field name when `name` isn't a valid identifier |
+| `nameOverride` | string | All | Custom code identifier when `name` isn't valid or collides with a reserved word |
 | `required` | boolean | All | Generates null-check validation |
-| `default` | varies | Scalars | Default value; type must match field type |
-| `enum` | string[] | Scalars | Allowed values |
+| `nullable` | boolean | All | When true, generators emit nullable/wrapper types (e.g., `Integer` vs `int` in Java). Identity fields cannot be nullable. Default: false |
+| `default` | varies | Scalars (not `binary`) | Default value; type must match field type |
+| `enum` | (string \| number)[] | Scalars (not `binary`) | Allowed values; type-matched (strings for string fields, numbers for number fields). Validated on nested fields too. |
 | `description` | string | All | Generates Javadoc comments |
 | `constraints` | object | Scalars | Validation constraints (see below) |
 | `items` | object | `list` only | Required — defines element type |
@@ -357,9 +565,9 @@ A `.bprint` file is a JSON document describing a single entity. The format is da
 |------------|-----------|-------------|
 | `minLength` / `maxLength` | `string` | String length bounds |
 | `pattern` | `string` | Regex pattern |
-| `min` / `max` | `number` | Numeric range |
+| `min` / `max` | `number` and `number.*` | Numeric range (works with all sub-types including `number.decimal`) |
 
-Constraints cannot be applied to collection types (`list`, `map`, `stringSet`, `numberSet`).
+Constraints cannot be applied to collection types (`list`, `map`, `stringSet`, `numberSet`, `numberSet.*`).
 
 ### Recursive Nesting
 
@@ -367,7 +575,14 @@ Constraints cannot be applied to collection types (`list`, `map`, `stringSet`, `
 
 ### Schema Version Rules
 
-- `schemaVersion` is customer-controlled — increment it each time the schema content changes.
+**Two version concepts — do not confuse them:**
+
+| Concept | Where | Who controls |
+|---------|-------|-------------|
+| `schemaVersion` (in `.bprint` file) | `"schemaVersion": "1.0"` | The user — bumped per entity schema change |
+| Spec version (this package) | `spec-versions.json` | Chaim maintainers — tracks `.bprint` format changes |
+
+- `schemaVersion` is the **user's entity version**, not the spec version. Start at `"1.0"`, increment on content change.
 - During `cdk deploy`, the Chaim server validates that the version was bumped when schema content changes. **Remind users frequently: bumping is mandatory on content change — enforced by the Chaim server at deploy time.**
 - Use `chaim bump <file>` to increment automatically.
 
@@ -434,7 +649,7 @@ new ChaimDynamoDBBinder(this, 'OrderBinding', {
 });
 ```
 
-All entities sharing a table **must** have matching partition/sort key field names.
+All entities sharing a table **must** have matching identity field names.
 
 ### Credentials
 
@@ -572,26 +787,26 @@ These workflows are specific to the DynamoDB integration. The pattern will be si
 1. Create a `.bprint` schema file
 2. Create a DynamoDB table in the CDK stack
 3. Add a `ChaimDynamoDBBinder` binding the schema to the table
-4. Run `cdk synth`
-5. Run `chaim generate --package <resolved-package>` — resolve from the repository using the [Package Resolution](#package-resolution) directive; never use a literal placeholder
+4. Add the new stack to `chaim.json → generate.stacks` (create `chaim.json` if it doesn't exist yet — see [Package Resolution](#package-resolution))
+5. Run `cdk synth && chaim generate`
 
 ### Add a New Entity to an Existing Table (Single-Table Design)
 
-1. Create a `.bprint` schema with **matching PK/SK field names** as existing entities on that table
+1. Create a `.bprint` schema with **matching identity field names** as existing entities on that table
 2. Add another `ChaimDynamoDBBinder` for the same table
-3. Run `cdk synth` then `chaim generate`
+3. Run `cdk synth && chaim generate`
 
 ### Add a Field to an Existing Entity
 
 1. Add the field to the `.bprint` file
 2. Run `chaim bump <file>` to increment `schemaVersion`
-3. Run `cdk synth` then `chaim generate`
+3. Run `cdk synth && chaim generate`
 
 ### Add a GSI to a Table
 
 1. Add the GSI to the CDK table definition
 2. Ensure the GSI key attributes exist as fields in the `.bprint` schema
-3. Run `cdk synth` then `chaim generate`
+3. Run `cdk synth && chaim generate`
 4. New `queryBy{IndexName}()` methods appear in the repository
 
 ### Change a Schema and Deploy
@@ -599,10 +814,10 @@ These workflows are specific to the DynamoDB integration. The pattern will be si
 1. Edit the `.bprint` file
 2. Run `chaim bump <file>` — **required before deploy** if content changed
 3. Run `cdk synth` (validates schema and creates snapshot)
-4. Run `chaim generate` (regenerates Java SDK)
+4. Run `chaim generate` (regenerates Java SDK — reads stack config from `chaim.json` automatically)
 5. Run `cdk deploy` (deploys infrastructure and publishes snapshot)
 
-**CI/CD tip:** Run `chaim generate` as a build step after `cdk synth`. Commit `.bprint` files but gitignore generated code. Fail the build if `schemaVersion` wasn't bumped on schema change.
+**CI/CD tip:** Run `cdk synth && chaim generate` as a single build step. Commit `.bprint` and `chaim.json` files but gitignore generated Java code. Fail the build if `schemaVersion` wasn't bumped on schema change.
 
 ---
 
@@ -615,10 +830,15 @@ When the user encounters errors, check for these common causes:
 | **HTTP 409 on `cdk deploy`** | `schemaVersion` not bumped after schema content change | Run `chaim bump <file>` then re-synth and redeploy |
 | **"No snapshots found" from `chaim generate`** | `cdk synth` was not run, or snapshots are in a non-default location | Run `cdk synth` first, or pass `--snapshot-dir <path>` |
 | **`cdk synth` fails with key mismatch** | Table PK/SK, GSI, LSI, or TTL attribute names don't match fields in the `.bprint` schema | Ensure every key attribute referenced by the table/indexes exists as a field in the `.bprint` `fields` array |
-| **Stale generated code** | Schema changed but `chaim generate` was not re-run | Run `chaim generate --package <resolved-package>` after `cdk synth` — resolve the package from the repo using the [Package Resolution](#package-resolution) directive |
-| **Single-table key conflict** | Entities bound to the same table have mismatched `partitionKey`/`sortKey` field names | All `.bprint` schemas sharing a table must use identical PK/SK field names |
+| **Stale generated code** | Schema changed but `chaim generate` was not re-run | Run `cdk synth && chaim generate`. If `chaim.json` is not present, see [Package Resolution](#package-resolution) to resolve the package first. |
+| **"--package is required" error** | `chaim generate` run without `--package` and no `chaim.json` exists | Create `chaim.json` with a `generate.stacks` block — see [Project Config: chaim.json](#project-config-chaimjson) |
+| **Single-table key conflict** | Entities bound to the same table have mismatched identity field names | All `.bprint` schemas sharing a table must use identical identity field names |
 | **Auth errors during synth/deploy** | Missing or invalid Chaim credentials | Check `ChaimCredentials` in CDK (prod: Secrets Manager) or set `CHAIM_API_KEY`/`CHAIM_API_SECRET` env vars (dev-only). Do NOT assume credentials are auto-present |
 | **Generated code compile errors** | Usually a `.bprint` schema issue (invalid types, missing required fields) | Run `chaim validate <file>` to check schema, fix issues, then regenerate |
+| **"not a valid type name" on entityName** | `entityName` is not PascalCase (lowercase, dotted, or hyphenated) | Use PascalCase: `"User"`, `"OrderItem"`. No dots, hyphens, or underscores. |
+| **"reserved keyword" on field name** | Field `name` matches a reserved word in Java, Python, Go, or TypeScript | Add a `nameOverride` to provide an alternative code identifier |
+| **No `.bprint` validation / autocomplete in VS Code** | `chaim generate` hasn't been run yet, or `npm install` hasn't been run | Run `npm install` then `cdk synth && chaim generate` — this auto-writes `.vscode/settings.json` |
+| **TTL items never expire (or expire immediately)** | `timestamp.epoch` TTL field populated with milliseconds instead of seconds | Use `Instant.getEpochSecond()` in Java, not `toEpochMilli()`. Configure TTL via `timeToLiveAttribute` on the CDK table — not in the `.bprint` schema. |
 
 ---
 
@@ -640,13 +860,21 @@ When the user encounters errors, check for these common causes:
 
 3. **Generated code should be gitignored** — Regenerate during the build process. Never suggest committing generated files.
 
+4. **Schema vs infrastructure boundary** — The `.bprint` schema defines *what data looks like* (fields, types, constraints). Infrastructure concerns (TTL, GSIs/LSIs, billing, streams, uniqueness enforcement, encryption) belong in CDK constructs. This keeps schemas portable across databases and languages. Specifically: TTL → `timeToLiveAttribute` on CDK table; indexes → `addGlobalSecondaryIndex()` / `addLocalSecondaryIndex()`; uniqueness → GSI design (DynamoDB) or DB constraint (SQL).
+
+5. **DynamoDB TTL is CDK-only** — Configure TTL via `timeToLiveAttribute` on the CDK `dynamodb.Table` construct. The `.bprint` schema only declares the field with `type: "timestamp.epoch"`. When populating a TTL field in application code, use epoch **seconds** (`Instant.getEpochSecond()`), not milliseconds — DynamoDB TTL interprets the Number as seconds.
+
+6. **`.vscode/settings.json` is written automatically** — `chaim generate` merges VS Code workspace settings on every run. This is idempotent and safe to commit. Users do NOT need to configure VS Code manually for `.bprint` validation. If VS Code intellisense isn't working for `.bprint` files, the fix is to run `chaim generate` (or ensure `npm install` has been run). Opt out via `"vscode": false` in `chaim.json → generate`.
+
 ### DynamoDB-Specific
 
+> **Scope note:** Indexes (GSI/LSI), TTL, streams, and billing mode are configured on the CDK table construct — not in the `.bprint` schema. This is by design — keeping infrastructure-specific knobs in the infrastructure layer makes `.bprint` schemas portable across data stores.
+
 4. **Key fields must exist in schema** — All DynamoDB key attributes (table PK/SK, GSI/LSI keys, TTL attribute) must be defined as fields in the `.bprint` schema. Mismatches fail `cdk synth`.
 
 5. **LSIs share the table's partition key** — LSI metadata does not include a `partitionKey` field. The generated code automatically uses the table's partition key for LSI queries.
 
-6. **Single-table entities must agree on keys** — All entities bound to the same DynamoDB table must have matching `partitionKey` and `sortKey` field names in their `.bprint` schemas.
+6. **Single-table entities must agree on keys** — All entities bound to the same DynamoDB table must have matching identity field names in their `.bprint` schemas.
 
 7. **`save()` does full replacement** — The generated `save()` uses `PutItem`, which replaces the entire item. Partial updates are not yet supported. Do NOT suggest partial update patterns.
 
@@ -655,25 +883,54 @@ When the user encounters errors, check for these common causes:
 ## Project Layout (Recommended)
 
 ```
-my-cdk-project/                       # CDK infrastructure
-├── schemas/
-│   ├── user.bprint
-│   └── order.bprint
-├── lib/my-stack.ts
-└── package.json                      # see dependency structure below
-
-my-java-app/                          # Java application
-├── src/main/java/com/example/model/  # ← generated by chaim generate (gitignored)
-│   ├── User.java
-│   ├── Order.java
-│   └── ...
-├── src/main/java/com/example/        # Your application code
-│   └── service/UserService.java
-├── build.gradle.kts
-└── ...
+my-project/                           # Project root (monorepo or single-repo)
+├── chaim.json                        # ← Chaim project config (commit this)
+├── .vscode/
+│   └── settings.json                 # ← auto-written by chaim generate (commit this)
+├── infrastructure/                   # CDK infrastructure
+│   ├── schemas/
+│   │   ├── user.bprint
+│   │   └── order.bprint
+│   ├── lib/my-stack.ts
+│   └── package.json                  # see dependency structure below
+└── application/                      # Java application
+    └── src/main/java/
+        ├── com/example/orders/sdk/   # ← generated by chaim generate (gitignore this)
+        │   ├── Order.java
+        │   ├── OrderRepository.java
+        │   └── ...
+        └── com/example/             # Your application code
+            └── service/OrderService.java
+```
+
+**`chaim.json`** — project-level SDK generation config:
+
+```json
+{
+  "generate": {
+    "javaRoot": "./application/src/main/java",
+    "stacks": {
+      "OrdersInfrastructureStack": {
+        "package": "com.example.orders.sdk"
+      },
+      "ProductsInfrastructureStack": {
+        "package": "com.example.products.sdk"
+      }
+    }
+  }
+}
+```
+
+With this file in place, `chaim generate` (no flags) regenerates all stacks automatically.
+
+**`.gitignore` additions:**
+```
+# Chaim generated SDK (regenerated at build time — do not commit)
+application/src/main/java/com/example/orders/sdk/
+application/src/main/java/com/example/products/sdk/
 ```
 
-**`my-cdk-project/package.json`** — correct dependency placement:
+**`infrastructure/package.json`** — correct dependency placement:
 
 ```json
 {