@bluestep-systems/bspecs 0.10.0

package/templates/claude/instructions/reference/api-patterns.md.template

@@ -0,0 +1,487 @@
+# API Patterns
+
+> **Note**: for the complete API reference, see `declarations/B.d.ts`. This file contains usage patterns and examples, not API documentation.
+
+## Contents
+
+- [Working with Java Optionals](#working-with-java-optionals)
+- [Field Types and Access Patterns](#field-types-and-access-patterns)
+- [mergeTag() Method](#mergetag-method)
+- [Safe Field Value Extraction](#safe-field-value-extraction)
+- [Record and Form Access](#record-and-form-access)
+- [Multi-Entry Form (MEF) Entries](#multi-entry-form-mef-entries)
+- [Query Access Patterns](#query-access-patterns)
+- [Java Collections](#java-collections)
+- [Writing Date and DateTime Fields](#writing-date-and-datetime-fields)
+- [Committing Writes and Formula Triggers](#committing-writes-and-formula-triggers)
+- [Endpoint (Maestro) Request/Response](#endpoint-maestro-requestresponse)
+- [Merge Report Client-Side Integration](#merge-report-client-side-integration)
+- [Base64 and Byte Arrays](#base64-and-byte-arrays)
+- [User and Session Access](#user-and-session-access)
+- [Type Safety](#type-safety)
+
+## Working with Java Optionals
+
+⚠️ BlueStep uses Java optionals, NOT standard JavaScript undefined/null checks.
+
+```typescript
+// Get value with default
+const value = field.opt().orElse('default value');
+
+// Transform and unwrap
+const transformed = field.opt().map(v => v.toUpperCase()).orElse('');
+
+// Check if present
+if (field.opt().isPresent()) {
+  const value = field.opt().get();
+}
+
+// Chain operations
+const result = field.opt().map(v => v.trim()).filter(v => v.length > 0).orElse('empty');
+```
+
+Common mistakes:
+
+```typescript
+// ❌ Wrong - JavaScript optional chaining doesn't work with Java optionals
+const value = record.forms.someForm?.fields.someField?.val();
+// ✅ Correct - use Java optional methods
+const value = record.forms.someForm.fields.someField.opt().orElse('');
+
+// ❌ Wrong - direct value access may throw
+if (field.val()) { ... }
+// ✅ Correct - check with the optional first
+if (field.opt().isPresent()) { const value = field.opt().get(); }
+```
+
+## Field Types and Access Patterns
+
+```typescript
+// Text / Memo (MemoField behaves like a text field)
+const text = textField.opt().orElse('');
+const trimmed = textField.opt().map(v => v.trim()).orElse('');
+
+// Number
+const num = numberField.opt().orElse(0);
+
+// Boolean
+const bool = boolField.opt().orElse(false);
+```
+
+### Date/Time Fields (reading)
+
+Date/Time fields return Java `LocalDateTime`, `LocalDate`, or `LocalTime` objects.
+
+```typescript
+const dateTime = dateTimeField.opt().orElse(null);
+if (dateTime) {
+  const year = dateTime.getYear();
+  const month = dateTime.getMonthValue();
+  const day = dateTime.getDayOfMonth();
+  const isoString = dateTime.toString(); // ISO string (common pattern)
+}
+```
+
+(For *writing* date/datetime fields, see [Writing Date and DateTime Fields](#writing-date-and-datetime-fields).)
+
+### Document Fields
+
+```typescript
+const doc = docField.filename() ? { filename: docField.filename(), url: docField.permUrl() } : null;
+```
+
+### Signature Fields
+
+```typescript
+const sig = sigField.optTimeStamp().map(ts => ({
+  user: sigField.optUser().map(u => u.fullName()).orElse(null),
+  dateTime: ts
+})).orElse(null);
+```
+
+### Single-Select Fields
+
+`.val()` returns the `OptionItem` object, not a string, and `.selectedName()` does NOT exist. To get the display label, use `optSelected().map(o => o.displayName())`.
+
+```typescript
+// ✅ Correct
+const qType: string = fields.questionType.optSelected().map((o: any) => o.displayName()).orElse('');
+
+// ❌ Wrong - selectedName() does not exist on SingleSelectField
+fields.questionType.selectedName();
+// ❌ Wrong - String(o) returns the Java object toString, not the label
+fields.questionType.opt().map((o: any) => String(o)).orElse('');
+```
+
+### Multi-Select Fields
+
+```typescript
+// Array of selected option names — .selectedNames() returns EList<string>; use .toArray()
+const selectedNames = multiSelectField.selectedNames().toArray();
+const count = multiSelectField.selectedCount();
+
+// Selected OptionItem objects (for display name + export value)
+multiSelectField.selected().forEach((item: Bluestep.Relate.OptionItem) => {
+  const name = item.displayName();
+  const exportValue = item.exportValue();
+});
+```
+
+⚠️ Use `.toArray()` to convert an `EList` to a real JavaScript array before JSON serialization or array operations.
+
+## mergeTag() Method
+
+`mergeTag()` is available on all Field objects and generates the HTML for form-field components. It is used with the `fieldF` and `bsHorizFieldCol2F` components to produce properly formatted fields with labels, validation images, and inputs.
+
+```typescript
+field.mergeTag(options?: string): string
+```
+
+### Option codes
+
+| Option Code | Description |
+|------------|-------------|
+| `""` (empty) | View-only field (read-only display) |
+| `"L"` | Label only |
+| `"H"` | Hint/tooltip |
+| `"F"` | Editable field (input element) |
+| `"I"` | Validation image (must be used with `"F"`) |
+
+⚠️ The validation-image code `"I"` should only be used in combination with the editable-field code `"F"`. Codes can be combined in one string to generate multiple tags at once (e.g. `"FI"`, `"LF"`, `"LFI"`).
+
+```typescript
+const input    = field.mergeTag("F");   // editable field
+const label    = field.mergeTag("L");   // label
+const hint     = field.mergeTag("H");   // hint
+const viewOnly = field.mergeTag("");    // view-only
+const complete = field.mergeTag("LFI"); // label + field + validation image
+```
+
+### Using with `fieldF` / `bsHorizFieldCol2F`
+
+```typescript
+import { fieldF, bsHorizFormCol2F, bsHorizFieldCol2F } from 'genericComponents';
+
+const firstNameField = record.forms.userInfo.fields.firstName;
+
+// Separate calls
+const fieldHtml = fieldF({
+  label: firstNameField.mergeTag("L"),
+  validationImg: firstNameField.mergeTag("I"),
+  field: firstNameField.mergeTag("F")
+});
+
+// More efficient: generate field + validation together with "FI"
+const fieldHtml2 = fieldF({
+  label: firstNameField.mergeTag("L"),
+  validationImg: '',
+  field: firstNameField.mergeTag("FI")
+});
+```
+
+Best practices: always use `mergeTag()` with `fieldF`/`bsHorizFieldCol2F` (they integrate with BlueStep's validation system); combine codes (`"FI"`/`"IF"`) rather than separate calls; never use `"I"` without `"F"`.
+
+## Safe Field Value Extraction
+
+```typescript
+function getFieldValue(field: any, fieldType: string): any {
+  switch (fieldType) {
+    case 'Text Field':
+    case 'Text Area Field':
+    case 'Memo Field':
+      return field.opt().orElse(null);
+    case 'Number Field':
+      return field.opt().orElse(null);
+    case 'Boolean Field':
+      return field.opt().orElse(false);
+    case 'Date/Time Field':
+      return field.opt().orElse(null); // Java date object
+    case 'Document Field':
+      return field.filename() ? { filename: field.filename(), url: field.permUrl() } : null;
+    case 'Signature Field':
+      return field.optTimeStamp().map(ts => ({
+        user: field.optUser().map(u => u.fullName()).orElse(null),
+        dateTime: ts
+      })).orElse(null);
+    case 'Multiple Select List Field':
+      return (field as Bluestep.Relate.MultiSelectField).selectedNames().length > 0
+        ? (field as Bluestep.Relate.MultiSelectField).selectedNames().toArray()
+        : [];
+    default:
+      return field.opt().orElse(null);
+  }
+}
+```
+
+## Record and Form Access
+
+Access forms and fields by direct property (the FID string). `byFID['...']` is unnecessary for runtime field/form access and should not be used (it appears only inside `require()` in the legacy `imports.ts` registration — see [Query Access Patterns](#query-access-patterns)).
+
+```typescript
+// ✅ Correct - direct property access
+entry.fields.title.val()
+client.forms.medicalTasks
+const value = record.forms.formName.fields.fieldName.opt().orElse('default');
+
+// ❌ Wrong - byFID is unnecessary at runtime
+entry.fields.byFID['title'].val()
+client.forms.byFID['medicalTasks']
+```
+
+### Linking to a record — `summaryUrl()`
+
+There is no universal `/records/{id}` route. Use `record.summaryUrl()` for the relative URL to any record's page.
+
+```typescript
+const url = client.summaryUrl(); // e.g. "/rop/connect/..."
+// ❌ Wrong - no such universal route
+const url = `/rop/records/${clientId}`;
+```
+
+### Record lookup by ID — use the `sysId` field, not `id().shortId()`
+
+`client.id().shortId()` returns the internal relate record ID, which does NOT resolve with `optById`. Use the `sysId` field from the `name` form.
+
+```typescript
+// ✅ Correct
+const clientId = client.forms.name.fields.sysId.val();
+// In a CURRENT_RECORD merge report:
+const clientId = (name as any).fields.sysId.val();
+
+// ❌ Wrong - shortId doesn't match what optById expects
+const clientId = client.id().shortId();
+```
+
+<!-- CONFLICT: client-ID field key — 01-Platform-Reference states the field key is `sysId` (not `systemID`/`systemId`) and that `id().shortId()` does NOT resolve with optById; Brandon's bluestep-knowledge merge-report examples read `name.fields.systemID.val()`. This may be form/org-specific (the field key depends on the form's schema). Needs human confirmation of the canonical key. -->
+
+## Multi-Entry Form (MEF) Entries
+
+`mefReports` does NOT exist at runtime. Create entries on the form, and find them by iterating the form directly.
+
+```typescript
+// Create a new entry — newEntry() is on the form
+const entry = client.forms.medicalTasks.newEntry();
+entry.fields.title.val('Task title');
+entry.fields.status.val(false);
+// ❌ Wrong - client.forms.medicalTasks.mefReports.newEntry();
+
+// Find a specific entry by ID — iterate the pre-loaded entries
+let foundEntry: any = null;
+for (const e of client.forms.medicalTasks) {
+  if (e.id().shortId() === entryId) { foundEntry = e; break; }
+}
+// ❌ Wrong - mefReports is undefined at runtime
+// client.forms.medicalTasks.mefReports.allEntries.query().optById(entryId);
+```
+
+- **Entry IDs:** use `entry.id().shortId()` to get the string ID for serialization or comparison — it matches when iterating.
+- **Entry creation date:** `entry.created()` returns a Java `Instant`. Convert to compare against a `LocalDate`:
+
+```typescript
+const createdDate = B.time.LocalDate.ofInstant(entry.created(), B.time.ZoneId.systemDefault());
+if (createdDate.isAfter(someLocalDate)) return; // e.g. exclude targets created after a note's service date
+```
+
+### Iterating single vs multi-entry forms
+
+```typescript
+const isMultiEntry = formMetaData.isMultiEntry();
+if (isMultiEntry) {
+  record.forms.multiEntryForm.entries().forEach((entry: any) => {
+    const value = entry.fields.fieldName.opt().orElse('');
+  });
+} else {
+  const value = record.forms.singleEntryForm.fields.fieldName.opt().orElse('');
+}
+```
+
+## Query Access Patterns
+
+Which queries, forms, and fields a script can use are defined by the component's **form-import config on the platform**, regenerated into `declarations/index.d.ts` on `b6p pull`. A configured query is available in `app.ts` as a **bare top-level variable** named after the query FID — directly iterable, no `.query()` call:
+
+```typescript
+// app.ts — the query is a top-level variable (configured on the platform, generated into declarations)
+const unit = topLevelUnit[0];
+const unitName = unit.forms.unitInformation.fields.unitName.opt().orElse('');
+topLevelUnit.forEach((record: Record_topLevelUnit) => { /* ... */ });
+```
+
+To add a query/field, or make a form writable, update the form-import config **on the platform** and `b6p pull` — do not hand-edit `declarations/index.d.ts`. A configured query's top-level variable carries the writable transaction context, so writes go through it directly (writable access is set per form in the import config, not chained in code).
+
+For an ad-hoc query that is *not* in the import config, run it explicitly. This is a fresh **read-only** execution — use it for reads only; writes against it fail:
+
+```typescript
+B.queries.byFID['staffQuery'].query().forEach((record: Bluestep.Relate.Record) => {
+  console.log(record.forms.nameForm.fields.firstName.opt().orElse(''));
+});
+```
+
+<details>
+<summary>Legacy: <code>objects/imports.ts</code> registration (older modules only)</summary>
+
+Older modules registered queries by hand in `objects/imports.ts` with `.require()`, which produced the same bare top-level variable and selected fields / writable context in code. **This file is not updated on pull and is not hand-written in current modules** — the platform form-import config replaces it. You may still encounter it:
+
+```typescript
+// objects/imports.ts (legacy)
+{
+  const forms = B.queries.byFID['topLevelUnit'].require().forms;
+  forms.byFID['unitInformation'].require({fields: ['unitName']});
+  // writable was an option INSIDE require(), never a chained .writable():
+  forms.byFID['medicalTasks'].mefReports.allEntries.require({fields: ['title','status'], writable: true});
+}
+```
+
+</details>
+
+## Java Collections
+
+Query results and other Java collections do NOT have JavaScript array methods (`.filter()`, `.map()`). Use `.forEach()` and build an array.
+
+```typescript
+// ❌ Wrong
+const filtered = query.query().filter(r => condition);
+// ✅ Correct
+const results = [];
+query.query().forEach((record: any) => { if (condition) results.push(record); });
+```
+
+## Writing Date and DateTime Fields
+
+Use `B.time`, never `Java.Time` — `Java.Time` is a TypeScript type namespace only and does not exist at runtime.
+
+```typescript
+// DateField — accepts B.time.LocalDate, B.time.Instant, or millis (number)
+entry.fields.dueDate.dateVal(B.time.LocalDate.parse('2025-04-01'));
+// ❌ Wrong - Java.Time is undefined at runtime
+entry.fields.dueDate.dateVal(Java.Time.LocalDate.parse('2025-04-01'));
+
+// DateTimeField — expects a ZonedDateTime, NOT epoch millis
+entry.fields.completedAt.val(B.time.ZonedDateTime.now());
+// ❌ Wrong - toEpochMilli() returns a Long → ClassCastException: Long cannot be cast to ZonedDateTime
+entry.fields.completedAt.val(B.time.Instant.now().toEpochMilli());
+```
+
+(For setting search values against date fields in MEF queries, that format differs — see [date-format](../conventions/date-format.md). For the `.val()` vs `.dateTimeVal()` overload trap, see [datetime-field-write](datetime-field-write.md).)
+
+## Committing Writes and Formula Triggers
+
+- **Form-attached formulas have NO `B.commit()`.** There `B` is `Bluestep.Relate.CurrentRecordB`, which does not extend `IsCommitable`; field writes auto-flush when the form save completes. (Cross-record writes need the target form configured writable in the platform form-import config — legacy modules declared `writable: true` in `objects/imports.ts`.)
+- **Endpoints, on-demand formulas, and scheduled formulas** — `B` IS `IsCommitable`; call `B.commit()` after writes.
+- **Gate on create vs edit** in a form-attached formula (`cur` is a `FormEntry`):
+
+```typescript
+if (cur.entry().justCreated()) { /* first-save path */ }
+if (!cur.entry().justCreated() && cur.entry().triggerFormulas()) { /* edit-only path */ }
+```
+
+## Endpoint (Maestro) Request/Response
+
+In endpoint (Maestro) scripts, the HTTP request/response are on `B.net`. `B.request`, `B.response`, and `B.out` do NOT exist in this context (`B.out` is a merge-report construct).
+
+```typescript
+const { request, response } = B.net;
+const action = request.parameter('action');     // string or null
+const id = request.optParameter('id').orElse(''); // Java Optional
+const body = JSON.parse(request.content() || '{}'); // request body as string
+response.contentType('application/json; charset=UTF-8');
+response.out(JSON.stringify({ success: true }));
+```
+
+(For the full request/response method surface and an action-based router, see [code-patterns](code-patterns.md). For the no-`delete`-method endpoint rule and output channel, see [endpoint-method-call](endpoint-method-call.md) and [endpoint-output-channel](endpoint-output-channel.md).)
+
+## Merge Report Client-Side Integration
+
+### Intercepting the save — wrap `window.submitForm`
+
+BlueStep's save button is `<a href="javascript:submitForm('Relate','commit')">`, which calls `submitForm()` → `form.submit()`. **`form.submit()` does NOT fire `addEventListener('submit', ...)`.** Wrap `window.submitForm` to intercept the save:
+
+```javascript
+var _orig = window.submitForm;
+window.submitForm = function() {
+  // your logic here
+  if (_orig) return _orig.apply(this, arguments);
+};
+```
+
+### Disable widget inputs before the POST
+
+If a merge report renders inputs with `name` attributes, BlueStep tries to save them as form fields and any unknown `name` causes "There was a problem storing the data." Disable widget inputs inside the override before calling through:
+
+```javascript
+var _orig = window.submitForm;
+window.submitForm = function() {
+  document.querySelectorAll('input[name^="tt-"], input[data-target-id], textarea[data-target-id]')
+    .forEach(function(el) { el.disabled = true; });
+  if (_orig) return _orig.apply(this, arguments);
+};
+```
+
+(See also [named-controls-submit](named-controls-submit.md).)
+
+### Script timing — native fields below the widget
+
+A merge report's `<script>` is injected mid-page. Native BlueStep fields that render **after** the widget are not yet in the DOM when the script runs — defer those with `DOMContentLoaded`. Fields rendered **before** the script (inside the widget's own HTML) are accessible immediately.
+
+```javascript
+document.addEventListener('DOMContentLoaded', function() {
+  var field = document.querySelector('[data-fid="treatmentTargetJSON"]');
+  if (field) field.closest('tr').style.display = 'none';
+});
+```
+
+(For passing per-row server data without a `DOMContentLoaded` race, see the queue/lazy-init pattern in [code-patterns](code-patterns.md).)
+
+## Base64 and Byte Arrays
+
+The base64 helpers take `Java.ByteArray`, not `string`. Convert with the I/O round-trip:
+
+```typescript
+const bytes = B.io.toByteArray(B.io.toInputStream(myString, "UTF-8"));
+
+// Standard base64 — exposed on B
+const standard = B.toBase64(bytes);
+// URL-safe base64 — ONLY on B.text (RFC 4648 §5, e.g. Gmail messages/send raw field)
+const encoded = B.text.toBaseUrl64(bytes);
+// ❌ Wrong - B.toBaseUrl64 does not exist
+const wrong = B.toBaseUrl64(bytes);
+```
+
+`B.io.toInputStream(input, charset?)` and `B.io.toByteArray(inputStream)` are the canonical pair — don't reach for `Java.type('java.lang.String')...getBytes(...)`.
+
+## User and Session Access
+
+```typescript
+// B.optUser — Java Optional (preferred, safe)
+const fullName = B.optUser.map(u => u.fullName()).orElse('Anonymous');
+const isSuper = B.optUser.map(u => u.isGlobalSuper()).orElse(false);
+const email = B.optUser.map(u => u.email()).orElse('');
+if (B.optUser.isPresent()) {
+  const user = B.optUser.get();
+  // user.firstName(), user.fullName(), user.email(), user.userName()
+  // user.unit(), user.record(), user.entry()
+}
+
+// B.user — direct access, returns User|null (equivalent to B.optUser.orElse(null)); prefer B.optUser
+const user = B.user;
+if (user) { const name = user.fullName(); }
+
+// Layout detection
+if (B.isLayout("MANAGE")) { /* Manage-specific behavior */ }
+```
+
+⚠️ `B.optUser` is a Java Optional — never serialize it directly into a template literal (it produces `"function () { [native code] }"`). Always resolve with `.map(...).orElse(...)` first.
+
+## Type Safety
+
+BlueStep APIs often return `any`. Add safety with casts/annotations and type guards.
+
+```typescript
+const value: string = field.opt().orElse('');
+
+function isRecord(obj: any): obj is Bluestep.Relate.Record {
+  return obj && typeof obj.recordId === 'function';
+}
+if (isRecord(someObj)) { const id = someObj.recordId(); }
+```
+
+(For broader TypeScript guidance, see the [BsJs development overview](../bsjs-development.md).)

package/templates/claude/instructions/reference/blueiq-credit-integration-playbook.md.template

@@ -0,0 +1,31 @@
+---
+description: Step-by-step playbook for wiring any new OpenAI/AI feature on summitridge into the BlueIQ credit gate + ledger — do this every time we build an AI feature
+---
+
+**Whenever we build a new AI feature on summitridge, it MUST be wired into the BlueIQ credit system** (gate + ledger at `/b/aiCredits`, file 1471659 — see blueiq credit system for the endpoint spec). This is the repeatable recipe. Two integration patterns depending on context.
+
+## The contract (both patterns produce the same ledger row)
+Per OpenAI "call" (define the granularity sensibly — e.g. one chat turn that fans out to many internal calls = ONE log with summed usage):
+- **check** before spending → `{ok, allowed, used, limit, remaining, period}`. Proceed ONLY when `ok===true && allowed===true`. **Fail-closed.**
+- **log** after the response → row fields: `function` (Text), `user` (Text), `model` (SingleSelect by export value), `promptTokens`, `cachedInputTokens`, `completionTokens`, `audioInputTokens`, `audioOutputTokens`, `audioSeconds`, `cost`, `credits` (all Number). Endpoint prices from its PRICING table; `credits = cost × 1000` (exact decimal, no rounding).
+- **Token mapping:** `promptTokens` = TOTAL input (cached nested inside); pass `cachedInputTokens` too so cached is priced cheaply. Chat models: audio fields = 0. The model id passed MUST exist in `/b/aiCredits` PRICING or `log` hard-errors.
+
+## Pattern A — user-context consumer (endpoint or merge report with a session)
+Used by `/b/aiAudio` (1471299), the Shift-Note Assistant (1471399), the Patient Record Chatbot (1470299/1470459). **Copy the helpers verbatim from `/b/aiAudio` (1471299) `draft/scripts/app.ts`:** `creditFetch`, `currentUserName`, `CreditCheck` interface, `checkCredits`, `logCredits`.
+- Loopback is **internal `B.net.fetch("/b/aiCredits", {method:"POST", credentials:true, followRedirects:false, enableErrorStream:true, ...})`** — NOT external httpRequester (can't hairpin to the org's own host → `this.in is null`). `credentials:true` carries the caller's session so the login-required endpoint doesn't 403. See [internal loopback fetch](internal-loopback-fetch.md).
+- Gate BEFORE the spend; on `!allowed` return distinct flags: `creditLimitReached:true` (out_of_credits) vs `creditCheckFailed:true` (gate_unreachable/gate_error). `checkCredits` returns a structured `reason` so the UI tells the true story, not a false "out of credits".
+- Log AFTER (best-effort, never block the user's result; return a `creditLogWarning` on failure).
+- Client UX: on `creditLimitReached` show a styled banner + disable input; on `creditCheckFailed` show a softer banner but allow retry.
+
+## Pattern B — scheduled / system-wide formula (NO session)
+Used by the Daily Milieu Summary morning formula (1471599). A scheduled `CurrentRecordB` formula has **no user session and no inbound request**, so it CANNOT authenticate a loopback (would 403). Instead **write the `openAILogs` entry directly**:
+- Prereq: add an `openAILogs` reference path to the formula in the BlueStep UI (multi-entry, writable) — it lives on the Facility/`community` record alongside `openAIIntegration`. Then `openAILogs.newEntry()` works.
+- Price inline (mirror the relevant model's row from `/b/aiCredits` PRICING; comment it as a mirror). gpt-4o = in 2.50 / cached 1.25 / out 10.00 per 1M; `textIn = promptTokens − cached`; `credits = cost × 1000`.
+- Set fields directly: `timestamp.val(B.time.ZonedDateTime.now())` (DateTimeField — use `.val()`, not `.dateTimeVal()`), `function`, `user:"System (scheduled)"`, `model` via `field.optionsByExport()[modelId]`, token fields, `cost`, `credits`, then `B.commit()`. Wrap best-effort (try/catch) AFTER the feature's own commit so logging can't lose the real output. No gate (background job — log only).
+
+## Always also
+- **API key from the form**, never hardcoded: read `openAIIntegration.fields.apiKey` (SecretField) via a memoized `getOpenAiKey()` (endpoints use `community[0].forms.openAIIntegration...`; CurrentRecord formulas access `openAIIntegration` directly).
+- **No "AI" in front-facing text** — brand is always "BlueIQ". The ledger `function` label is admin-facing and feature-named (e.g. "Shift Note Recorder", "Patient Record Chatbot", "Daily Milieu Summary", optionally "– {sub-context}"). See [blueiq no ai branding](../conventions/blueiq-no-ai-branding.md).
+- Build (`tsc --rootDir . --skipLibCheck`) and snapshot every touched component.
+
+Related: blueiq credit system, [internal loopback fetch](internal-loopback-fetch.md), [blueiq no ai branding](../conventions/blueiq-no-ai-branding.md), ai audio, [datetime field write](datetime-field-write.md), [singleselect null copy](singleselect-null-copy.md).

package/templates/claude/instructions/reference/chronounit-months.md.template

@@ -0,0 +1,37 @@
+---
+description: "ChronoUnit.MONTHS.between counts complete elapsed months (day-aware), NOT calendar-month boundaries — use (year-year)*12 + (month-month) when porting SQL DATEDIFF(MONTH) semantics"
+---
+
+`B.time.ChronoUnit.MONTHS.between(a, b)` and SQL `DATEDIFF(MONTH, a, b)`
+compute *different* numbers whenever `day(b) < day(a)`:
+
+- **ChronoUnit.MONTHS.between** — counts *complete elapsed* months, day-aware.
+  `between(2024-06-07, 2026-05-05)` = 22 (because 23 complete months would
+  end on 2026-05-07).
+- **SQL DATEDIFF(MONTH)** — counts calendar-month boundary crossings, day-blind.
+  Same input = 23 (`(2026-2024)*12 + (5-6)`).
+
+For "treatment-month ordinal" / "Nth-month bucket" math (where month 1
+starts on the admit date and month 2 begins on the next same-day-of-month),
+you want the SQL semantic. Implement with a plain calendar diff:
+
+```ts
+const calMonths = (Number(note.getYear()) - Number(admit.getYear())) * 12
+                + (Number(note.getMonthValue()) - Number(admit.getMonthValue()));
+const adj = note.getDayOfMonth() >= admit.getDayOfMonth() ? calMonths : (calMonths - 1);
+const treatmentMonth = adj + 1; // 1-indexed
+```
+
+`ChronoUnit.WEEKS / DAYS / YEARS .between` have the same elapsed-count
+semantics. DAYS happens to match SQL DATEDIFF(DAY) because both ignore
+sub-day resolution, but WEEKS and YEARS will drift the same way MONTHS
+does. When porting SQL date math, port the SQL formula faithfully — don't
+substitute ChronoUnit conveniences.
+
+**Discovered:** RISE Maestro v1 (alpineacademy/1515139) shipped with
+`ChronoUnit.MONTHS.between` and was off-by-one on `monthsSinceAdmit` for
+12 of 53 overlapping rows in the verification diff. See
+treatment targets sibling project — also does treatment-month
+math.
+
+Related: [localdate parse](localdate-parse.md) (LocalDate.parse — use B.time).