@bluestep-systems/bspecs 0.10.0

package/templates/claude/instructions/reference/design-system.md.template

@@ -0,0 +1,150 @@
+# BlueStep Design System
+
+## Contents
+
+- [Overview](#overview)
+- [Component Source Priority](#component-source-priority)
+- [Design Standards](#design-standards)
+- [Standard Components](#standard-components)
+- [Bootstrap Components](#bootstrap-components)
+- [Using the Design System](#using-the-design-system)
+- [Related Documentation](#related-documentation)
+- [Access](#access)
+
+> **Primary Reference**: The complete BlueStep Design System is available as an interactive merge report at:
+> **https://bluestepplatformsupport.bluestep.net/shared/layouts/singleblock.jsp?_event=view&_id=120130___195147**
+
+## Overview
+
+The BlueStep Design System is a comprehensive library of reusable components, design standards, and guidelines for BlueStep.js development. It serves three main purposes:
+
+1. **Establish clear standards** - Provide consistent design and development patterns for designers and developers
+2. **Component reference** - Serve as a comprehensive reference for UI components for both developers and AI agents
+3. **Rapid prototyping** - Enable AI agents to quickly create mockups based on user instructions
+
+## Component Source Priority
+
+When creating mockups and developing software, components should be sourced in the following priority order:
+
+1. **BlueStep Generic Components** - Use components from the genericComponents library first (e.g., `moduleF`, `headF`, `svgF`, `tableF`)
+2. **Bootstrap 3.3.7 Components** - Use standard Bootstrap components when no generic component exists (e.g., buttons, alerts, modals, panels)
+3. **Custom Components** - Create from scratch only when necessary, inferring styles from the above sources to maintain consistency
+
+This priority ensures consistency across BlueStep applications and leverages existing, tested components whenever possible.
+
+## Design Standards
+
+The design system includes comprehensive documentation for:
+
+### Color Palette
+
+**Standard Colors (CSS Variables)** - Available to all BlueStep pages:
+- `--bs-red: #c03b2b`
+- `--bs-orange: #F29D1F`
+- `--bs-yellow: #EFC319`
+- `--bs-green: #28AE60`
+- `--bs-blue: #2A81BA`
+- `--bs-logo-blue: #0063A6` (Brand logo color, used in email templates)
+- `--bs-purple: #894C9E`
+- `--bs-gray: #969FA0`
+- `--bs-default: #2D3F50` (Default theme color)
+
+**Custom Generated Colors (Style-Based)** - Generated based on currently selected color style:
+- `--bs-primaryColor`
+- `--bs-primaryColorHigh`
+- `--bs-accent1Color`
+- `--bs-accent2Color`
+- `--bs-secondaryColor`
+- `--bs-secondaryColorHigh`
+
+> **Note**: Custom generated colors vary based on the organization's color style selection. Always use CSS variables for colors to ensure consistency.
+
+### Typography
+
+The design system documents standard typography patterns, font sizes, and text styling conventions for BlueStep applications.
+
+### Spacing Scale
+
+Standard spacing values and guidelines for consistent layout spacing throughout BlueStep applications.
+
+## Standard Components
+
+The design system provides comprehensive documentation for all BlueStep generic components:
+
+- **SVG Icons** (`svgF` / `svgIconF`) - Icon generation with size, color, and modifier options
+- **Headers** (`headF`) - Standard and collapsible section headers
+- **Tables** (`tableF`) - Data table generation
+- **Fields** (`fieldF`) - Form field formatting
+- **Bootstrap Forms** (`bootstrapFormF`) - Complete form generation
+- **Modules** (`moduleF`) - Full page layouts with tabs
+- **Generic HTML Tags** (`tagF`) - Custom HTML element generation
+- **Anchor Tags** (`aF`) - Link generation
+- **Email Templates** (`emailF`) - Responsive email generation
+- **Breadcrumbs** (`breadcrumbF`) - Navigation breadcrumbs
+- **Search Components** (`searchHeadF`, `searchTextF`) - Search interface components
+- **Date Input** (`bsDateInput`) - Date picker components
+- **Date Range** (`jsDateRange`) - Date range selection
+- **Popin Hints** (`popinHintF`) - Contextual help tooltips
+- **SVG with Title** (`svgTitleF`) - Icons with text labels
+- **Horizontal Form Layout** (`bsHorizFormCol2F`, `bsHorizFieldCol2F`) - Two-column form layouts
+
+Each component includes:
+- Description and use cases
+- Code examples
+- Parameter documentation
+- Visual examples
+- Usage guidelines
+- Accessibility notes
+
+## Bootstrap Components
+
+The design system also documents standard Bootstrap 3.3.7 components:
+
+- Buttons
+- Alerts
+- Badges
+- Labels
+- Panels
+- Wells
+- Modals
+- Tooltips
+- Popovers
+- Tabs
+- Accordion
+- Pagination
+
+## Using the Design System
+
+### For AI Agents
+
+When creating mockups or building BlueStep.js applications:
+
+1. **Reference the design system first** - Check the interactive design system merge report for component examples and patterns
+2. **Follow component priority** - Use BlueStep generic components before Bootstrap, and Bootstrap before custom HTML
+3. **Use design standards** - Apply color palette, typography, and spacing scale consistently
+4. **Check component documentation** - Review parameter lists, examples, and usage guidelines in the design system
+
+### For Developers
+
+1. **Browse the interactive design system** - Use the merge report to see live examples of all components
+2. **Copy code examples** - Use the provided code examples as starting points
+3. **Follow usage guidelines** - Adhere to accessibility and best practice recommendations
+4. **Reference component API** - Check the design system for parameter documentation
+
+### For Designers
+
+1. **Review design standards** - Understand color palette, typography, and spacing conventions
+2. **Explore component library** - See all available components and their visual appearance
+3. **Understand component capabilities** - Know what's possible with existing components before requesting custom solutions
+
+## Related Documentation
+
+- **Component Library Usage** - See `agents-support/component-library.md` for quick reference on common components
+- **Component Source** - See `https://files.bluestep.net/script/530024___41/static/genericComponents.js` for complete API documentation
+- **Icon Reference** - See the BlueStep Icon Reference for complete icon list and categories
+
+## Access
+
+**Design System URL**: https://bluestepplatformsupport.bluestep.net/shared/layouts/singleblock.jsp?_event=view&_id=120130___195147
+
+The design system is also available in the workspace at `U129801/BlueStep.js Components` for local reference.

package/templates/claude/instructions/reference/dpn-dashboard-framework.md.template

@@ -0,0 +1,29 @@
+---
+description: "Parameterized data-endpoint + dashboard framework on rop — endpoint serves per-client/date-range JSON via URL params, dashboard fans out throttled parallel fetches; reference architecture for client-fed analytics dashboards"
+---
+
+DPN Scoring framework on **rop** — a reference architecture for a dashboard that pulls per-entity, per-date-range data from a parameterized JSON endpoint. Two files, server-thin/client-fat. **Do not modify — reference only.**
+
+- **Endpoint** `/b/dpnScoring` (file 1471219, key 363769___463) — the data service.
+- **Merge report** DPN Dashboard (file 1475679, key 530024___1162) — the consumer/UI.
+
+## Endpoint: parameterized data service
+`scripts/app.ts` reads four URL params and returns JSON. This is the part Brandon flagged — **same endpoint, many shapes of data via params**:
+
+- `clientid` — which entity (accepts short id OR full `Class___Short`; resolved via `allActiveDischarge.optById(clientId)`).
+- `startdate` / `enddate` — ISO `YYYY-MM-DD` window. Per-form entries are filtered with a plain string compare (`dateStr < startDate || dateStr > endDate`) since ISO sorts lexically. Top-level group-notes query instead uses `addSearch('groupNote','date','>=', MM/dd/yyyy)` — note the **format flip to MM/dd/yyyy** for `addSearch` (see [date format](../conventions/date-format.md)), wrapped in try/finally with `clearSearchAndSort()`.
+- `action` — the response mode discriminator: `daily` (default; per-day buckets), `weekly` (Mon–Sun aggregated week rows with phase-weighted scores), or `full` (daily buckets + weeks). One endpoint, three payload shapes.
+
+Response envelope is always `{ success, clientId, startDate, endDate, ... }` with `sendError(status, msg)` emitting `{ success:false, error }`. Missing params → 400 with a list of which were missing. Whole body in try/catch → 500. Reads via a query/field manifest (queries `allActiveDischarge` + `allGroupNotes`, each form listing the exact fields to load) — this component predates the move to platform form-import config and still uses a legacy `objects/imports.ts` `require` manifest; configure new components on the platform instead (see [api-patterns](api-patterns.md#query-access-patterns)). `config.json`: `transactionReadonly:false`, `transactionTimeout:3600`, `sandbox:SMALL`. Output via `response.out(JSON.stringify(...))` (see [endpoint output channel](endpoint-output-channel.md)).
+
+## Merge report: dashboard consumer
+`scripts/app.ts` (server) emits **only a roster** — a `<script type="application/json">` of `{clientId, firstLast, team}` for every active client — plus the mount div, Chart.js CDN, and `.build/script.js`. No per-client data server-side; `record.id().toString()` (full form) is the wire id the endpoint expects.
+
+`static/script.ts` (client) is where the framework lives:
+- On load, default window = **last 4 full Mon–Sun weeks**; date inputs + Apply let the user change it.
+- `loadWeeklyForAll()` builds one fetch task per roster entry and runs them through `runWithConcurrency(tasks, 10)` — a **throttled parallel pool (10 concurrent)** with a progress bar. This is the key pattern: dashboard does N calls to the same endpoint, one per client, varying `clientid` but sharing the date window.
+- `fetchWeeklyForClient` / `fetchFullForClient` build `/b/dpnScoring?clientid=…&startdate=…&enddate=…&action=weekly|full`. Weekly drives the overview (stoplight bar, component lines, phase doughnut, sortable client table with sparklines, flagged bands). Full is **lazy-fetched** only when a client is opened (radar of current-week domains), cached in `state.fullByClient`.
+- Changing the date range clears caches and refetches everything.
+
+## The reusable framework, in one line
+A stateless endpoint keyed by `(entity id, date range, action)` returning a `{success,...}` JSON envelope; a thin server that ships only an entity roster; a fat client that fans out throttled-parallel per-entity fetches over a user-chosen window, caches by id, and lazy-loads detail. Build on [merge report memo json](merge-report-memo-json.md)-style server-thin/client-fat but feed the client from a params endpoint instead of a hidden memo.

package/templates/claude/instructions/reference/endpoint-method-call.md.template

@@ -0,0 +1,10 @@
+---
+description: B.net.request.method is a method (call it), not a property — calling without parens type-checks but returns the Function reference at runtime
+---
+`B.net.request.method` is typed as `method(): string` in B.d.ts — call it as a function: `B.net.request.method()`.
+
+If you write `B.net.request.method` (no parens), TypeScript happily lets it through (the function reference is a truthy value), but at runtime you'll be comparing the Function object against `"GET"` and your method gate will never trigger.
+
+Same pattern likely applies to other `request.*` accessors that look property-shaped — check the .d.ts before assuming.
+
+Confirmed live on alpineacademy `/b/greatHair` endpoint, May 2026.

package/templates/claude/instructions/reference/endpoint-no-delete-method.md.template

@@ -0,0 +1,9 @@
+---
+description: "BlueStep endpoints don't route the DELETE (or likely other non-GET/POST/PUT) HTTP method — use a PUT/POST action discriminator instead"
+---
+
+BlueStep `/b/<alias>` endpoints do **not** dispatch the `DELETE` HTTP method to the script. A `fetch(url, {method:'DELETE'})` never reaches the handler — the platform returns a non-JSON error page, so client-side `r.json()` throws and you see a generic "Network error" (NOT your handler's JSON error). Symptom: delete fails with "Network error — please try again" while POST/PUT/GET actions on the same endpoint work fine.
+
+Fix: route mutations through `PUT` (or `POST`) with an `action` discriminator in the JSON body — e.g. `{action:'delete', entryId}` handled by `else if (action === 'delete')` in the `method === 'PUT'` branch. This is the same proven path as complete/reassign/completeWithResult on the WCWF endpoint (havenwoodslc/1523200). Confirmed GET/POST/PUT route; DELETE does not. (Likely PATCH/OPTIONS/etc. also don't — stick to GET/POST/PUT.)
+
+Relates to [endpoint method call](endpoint-method-call.md) (request.method() must be called with parens), tracer audit.

package/templates/claude/instructions/reference/endpoint-output-channel.md.template

@@ -0,0 +1,23 @@
+---
+description: "/b/ endpoints write their body via B.net.response.out(string), NOT B.out — B.out is the merge-report channel and yields a blank 'Error' page on an endpoint"
+---
+
+A BlueStep **`/b/<alias>` endpoint** must write its response body with **`B.net.response.out(stringBody)`** — a method on the Response object. Assigning **`B.out = ...`** does NOT work for an endpoint: `B.out` is the **merge-report** output channel, and using it on a `/b/` endpoint produces BlueStep's generic blank **"Error"** page (the script runs fine, but no endpoint output is ever emitted, so the framework reports failure). The same script type compiles either way — this is a runtime/routing distinction, not a type error.
+
+**Endpoint output pattern (confirmed working — alpine RISE endpoint 1515139, and the BEH finance data endpoint /b/financeData):**
+```js
+function writeJson(res, status, body) {
+  try { res.status(status); } catch (_e) {}            // may throw if already committed
+  try { res.contentType("application/json; charset=UTF-8"); } catch (_e) {}
+  res.out(JSON.stringify(body));                        // <-- the body channel
+}
+// entry:
+const res = B.net.response;
+const method = String(B.net.request.method() || "GET").toUpperCase();  // method() is a function — see endpoint method call
+// ...dispatch on B.net.request.optParameter('x').orElse('')...
+writeJson(res, 200, envelope);
+```
+
+Wrap `status()`/`contentType()` in try/catch (they throw `IllegalStateException` once the response is committed). `res.out()` takes the full string body. Read request via `B.net.request` (`.method()`, `.optParameter(name).orElse(...)`, `.parameter(name)`). Endpoints route GET/POST/PUT but not DELETE ([endpoint no delete method](endpoint-no-delete-method.md)); the friendly `/b/<alias>` is configured per-endpoint, not derivable from the script name ([endpoint urls](endpoint-urls.md)).
+
+Contrast: a **merge report** (e.g. the behavioral scorecard) renders via `B.out = htmlString`. So: merge report → `B.out`; `/b/` endpoint → `B.net.response.out(...)`.

package/templates/claude/instructions/reference/endpoint-urls.md.template

@@ -0,0 +1,15 @@
+---
+description: BlueStep endpoints are reached at /b/<alias>, not the /files/{id}/draft/ path — the alias is configured per-endpoint and is the URL to give users for testing
+---
+BlueStep endpoint scripts have a configured **friendly URL** at `/b/<alias>` that is what users actually hit in the browser. The `/files/{id}/draft/` path is the editor view, not the runtime endpoint.
+
+Example: Sprint Maestro (file id `1434036`, script name "Sprint Maestro") is exposed at `https://beh.bluestep.net/b/sprints?action=team`, not `https://beh.bluestep.net/files/1434036/draft/?action=team`.
+
+The alias is set per-endpoint in BlueStep admin and is not derivable from the script name alone — also not necessarily plural-vs-singular consistent (Sprint Maestro → `sprints`).
+
+**Symptom of a wrong alias:** the URL returns HTTP 500 with body literally just `Error` (BlueStep's generic page for "no endpoint at that path"). Status 500 + "Error" is NOT necessarily a script-side crash — first verify the alias before debugging the script.
+
+**How to apply:**
+- When reporting test URLs to the user, ask what the friendly alias is — do not guess from the script name or fall back to the `/files/.../draft/` URL.
+- The `.b6p_metadata.json` `url` field is the editor URL, not the runtime URL.
+- If the user reports "500 / Error" on an endpoint, ask them to confirm the alias before adding script-side error handling.

package/templates/claude/instructions/reference/entry-delete.md.template

@@ -0,0 +1,40 @@
+---
+description: Correct runtime API to delete a multi-entry-form entry — entry.entry().delete(), NOT entry.delete() — the typed declaration on the outer interface lies
+---
+When you have a typed multi-entry-form record entry (e.g. `MEFR_sprints`, `MEFR_medicalTasks`), the typed `B.d.ts` claims `delete(): boolean` exists directly on the outer interface (around line 207-210 in current B.d.ts). **It doesn't, at runtime.** Calling it throws:
+
+```
+TypeError: invokeMember (delete) on myassn.script.relate.FormRecordEntryScript failed due to: Unknown identifier: delete
+```
+
+The actual API is to first unwrap to the underlying `FormEntry` via `.entry()`, then call `.delete()`:
+
+```typescript
+// Correct
+(entry as any).entry().delete();
+B.commit();
+
+// Wrong — runtime "Unknown identifier: delete"
+entry.delete();
+B.commit();
+```
+
+`(entry as any)` is needed because the typed interface doesn't expose `.entry()` consistently across MEF entry types — but it exists at runtime on every form-entry-script object.
+
+## Existing usage to confirm pattern
+
+Real BlueStep scripts that use this pattern (all snapshotted and live):
+- `alpineacademy/Parent Opportunity API/draft/scripts/app.ts:82` — `entry.entry().delete()`
+- `summitridge/Videra Proxy-Login/draft/scripts/app.ts:206` — `newNote.entry().delete()`
+- `summitridge/1469686/draft/scripts/app.ts:779` — `entryOpt.get().entry().delete()`
+- `alpineacademy/1458534/draft/scripts/app.ts:183` — `appt.entry().delete()`
+- `summitridge/Report System/Report Data Maestro/draft/scripts/app.ts:825`
+
+Apparently universal — the typed `entry.delete()` may be aspirational or deprecated.
+
+## How to apply
+
+- For any "delete this MEF entry" code, write `(entry as any).entry().delete()` (or `entry.entry().delete()` if your entry variable already has FormEntry typing). Call `B.commit()` afterward to persist.
+- Don't trust the `delete(): boolean` signature in `B.d.ts` line ~210 — it lies.
+- The error "Unknown identifier: delete" is the diagnostic sign you've hit this trap.
+- This is for **deleting individual entries** of a multi-entry form. To delete a whole record, use `record.deleteRecord()` (line ~18490 in B.d.ts) — that one IS available at runtime.

package/templates/claude/instructions/reference/file-execution.md.template

@@ -0,0 +1,113 @@
+# File Execution Model
+
+⚠️ **Critical**: understanding which files execute, and when, is essential for BlueStep.js development. The core rule: **a file only runs if it is an automatic entry point or is explicitly imported/referenced.** Files that are neither never execute.
+
+## Contents
+
+- [Merge Reports](#merge-reports)
+- [Endpoints and Formulas](#endpoints-and-formulas)
+- [Workspace Sync](#workspace-sync)
+- [Common Mistakes](#common-mistakes)
+
+## Merge Reports
+
+### Execution entry points
+
+Only two files execute automatically:
+
+1. **`scripts/app.ts`** — server-side only. Executes on the server, can access `B` and BlueStep APIs, cannot access the DOM, and writes to `B.out` (rendered into the page).
+2. **`static/index.html`** — client-side only. Executes in the browser, can access the DOM, cannot access `B`, and must reference other client files explicitly.
+
+### File structure
+
+```
+/scripts/app.ts          ← SERVER-SIDE ONLY - executes on the server
+/static/index.html       ← CLIENT-SIDE ONLY - executes in the browser
+/static/script.js        ← CLIENT-SIDE ONLY - must be referenced by index.html
+/static/styles.css       ← CLIENT-SIDE ONLY - for custom HTML only; component-library output needs no extra CSS
+/objects/*.ts            ← imported by app.ts or other files
+```
+
+All other files must be explicitly imported or referenced. Creating files that aren't imported = wasted code.
+
+### HTML structure
+
+Merge-report HTML (`static/index.html`) is **embedded into an existing BlueStep page**, so it must NOT include `<!DOCTYPE html>`, `<html>`, `<head>`, or `<body>`. Include only external `<script>`/`<link>` references, the content markup, and the application script at the end.
+
+Connect/Manage sites provide the full HTML structure, navigation, branding, user context, and layout framework. Your merge report provides content (via `B.out` from `scripts/app.ts`), client markup (from `static/index.html`), and client scripts/styles. The content is rendered inside the site's content container, not as a standalone page — it is constrained by the site's layout.
+
+```html
+<!-- External libraries (optional) -->
+<link rel="stylesheet" href="styles.css" />
+
+<!-- Your content -->
+<div id="app-container"></div>
+
+<!-- Application script — use type="module" when script.ts uses ES imports (e.g. genericComponents) -->
+<script type="module" src=".build/script.js"></script>
+```
+
+> ⚠️ **`type="module"` is required** whenever `script.ts` uses ES `import` statements (including importing from `genericComponents`). Without it the browser throws `SyntaxError: Cannot use import statement outside a module` and the script will not run.
+
+## Endpoints and Formulas
+
+### Execution entry points
+
+Only one file executes automatically:
+
+1. **`scripts/app.ts`** — server-side only. Executes on the server, handles the request/event, can access `B`, cannot access the DOM.
+
+### File structure
+
+```
+/scripts/app.ts          ← SERVER-SIDE ONLY - handles the request/event
+/objects/*.ts            ← imported by app.ts
+```
+
+### Query access pattern
+
+Which queries are available in `app.ts` is set by the component's **form-import config on the platform**, regenerated into `declarations/index.d.ts` on `b6p pull`. A configured query is a **bare top-level variable** named after the query FID — directly iterable, no `.query()` call:
+
+```typescript
+// app.ts — query is a top-level variable (no .query() needed)
+const unit = topLevelUnit[0];
+const unitName = unit.forms.unitInformation.fields.unitName.opt().orElse('');
+topLevelUnit.forEach((record) => { /* ... */ });
+```
+
+The legacy `objects/imports.ts` `.require()` registration did this in code; it is not used in current modules. For full query patterns (writable context, ad-hoc queries) plus the legacy detail, see [api-patterns](api-patterns.md#query-access-patterns) and [code-patterns](code-patterns.md#query-patterns).
+
+## Workspace Sync
+
+Each project has a `.b6p_metadata.json` file tracking sync state between the local workspace and the BlueStep server: script metadata (name, org ID, WebDAV ID), per-file last-sync timestamps, and build state. The `draft/` directory holds the working version of the code; the `.build/` directories hold the compiled JavaScript output from the TypeScript source.
+
+## Common Mistakes
+
+### Creating files that aren't imported
+
+```typescript
+// ❌ Wrong - objects/helpers.ts exists but is never imported → it never executes
+// ✅ Correct - import it (in app.ts)
+import { helperFunction } from './objects/helpers';
+```
+
+### Mixing server and client code
+
+```typescript
+// ❌ Wrong - DOM access in server code (scripts/app.ts)
+document.getElementById('myElement'); // ERROR: document is not defined
+// ❌ Wrong - B object in client code (static/script.js)
+const user = B.user;                  // ERROR: B is not defined
+```
+
+### Incorrect HTML structure
+
+```html
+<!-- ❌ Wrong - full HTML document -->
+<!DOCTYPE html><html><head><title>My Report</title></head><body><div>Content</div></body></html>
+
+<!-- ✅ Correct - content and references only -->
+<link rel="stylesheet" href="styles.css" />
+<div>Content</div>
+<script src=".build/script.js"></script>
+```

package/templates/claude/instructions/reference/http-requester.md.template

@@ -0,0 +1,37 @@
+---
+description: Correct method names on B.net.httpRequester for non-GET calls — uses overloaded getter/setter style (.method(), .responseCode()), not Java-bean style (.setMethod, .getResponseCode)
+---
+`B.net.httpRequester(url)` returns an object whose mutators and accessors share the same name (overloaded). The Java-bean-style `setX`/`getX` names do **NOT** exist and are a TypeScript error.
+
+```typescript
+// Correct
+const req = B.net.httpRequester(url);
+req.method('POST');                         // setter (string arg)
+req.setHeader('Authorization', API_KEY);    // setHeader IS the right name (no overload)
+req.setHeader('Accept', 'application/json');
+req.doRequest();
+const status = req.responseCode();          // getter (no args) — returns number | null
+const body = req.getContent('UTF-8');       // getContent IS the right name
+```
+
+```typescript
+// Wrong — these do NOT exist
+req.setMethod('POST');
+req.getResponseCode();
+```
+
+**Methods that follow the bean naming**: `setHeader`, `getContent`, `doRequest`. **Methods that use the overloaded style**: `method`, `responseCode`. The split is inconsistent — when in doubt, look at `B.d.ts` declarations.
+
+## Reading POST body in an endpoint
+
+```typescript
+const bodyText = B.net.request.content() || '';   // returns string
+const body = JSON.parse(bodyText);
+```
+
+`request.content()` is the canonical accessor — confirmed in declarations, used by the existing Sprint Maestro endpoint.
+
+**How to apply:**
+- For DELETE / POST / PUT calls (e.g., ClickUp tag reconciliation, REST writes), use `req.method('POST')` not `req.setMethod('POST')`.
+- For checking response status to handle 404-as-success (idempotent deletes), use `req.responseCode()` not `req.getResponseCode()`.
+- If a TypeScript error says `Property 'setMethod' does not exist`, this memory is why.

package/templates/claude/instructions/reference/id-full-vs-short.md.template

@@ -0,0 +1,15 @@
+---
+description: Id.toString() returns ClassID___ShortID (full id); shortId() returns just the trailing number. optById needs the full form when round-tripping freshly-created entries.
+---
+
+`entry.id().toString()` returns the **full system id** in `ClassID___ShortID` form (e.g. `1000201__21584230_2178970123`). `entry.id().shortId()` returns just the trailing record number (`2178970123`).
+
+Declared at `B.d.ts:14373-14379`: *"Returns the standard System ID. That is ClassID___ShortID."*
+
+`query.optById(s)` accepts the full form reliably. Feeding it just a `shortId()` can produce a malformed reconstructed key with an empty ClassID segment (e.g. `1000201___1153030` — three underscores), and `FinderException: Could not load Model for key: ...` is thrown.
+
+**Why this matters for endpoint round-trips:** when an endpoint creates a new entry and returns its id to the client for a follow-up call (e.g. document upload after student creation), return `id().toString()`, not `id().shortId()`. If the UI also needs the short form for display, return both.
+
+Related: [new entry id](new-entry-id.md) (commit before reading shortId).
+
+**How to apply:** any time an id is going to be passed back to a server for `optById` lookup, use the full id. Reserve `shortId()` for human-readable display only.

package/templates/claude/instructions/reference/internal-loopback-fetch.md.template

@@ -0,0 +1,24 @@
+---
+description: "Endpoint-to-endpoint loopback within an org must use B.net.fetch on a relative path + credentials:true, NOT the external httpRequester"
+---
+
+For a BlueStep endpoint to call another endpoint in the SAME org (e.g. /b/aiAudio → /b/aiCredits), use `B.net.fetch(relativePath, {...})` — NOT `B.net.httpRequester(absoluteUrl)`.
+
+`httpRequester` dials the server's own public hostname over the network; the server can't hairpin back to itself (NAT/firewall), so `doRequest()` never connects: `responseCode()` returns null and `getContent()` throws `Cannot invoke "java.io.InputStream.read(...)" because "this.in" is null`.
+
+`B.net.fetch` on a RELATIVE path (`"/b/aiCredits"`) routes through BlueStep's internal dispatcher — no public round-trip — and `credentials: true` carries the caller's session so a login-required target doesn't 403. Read the result via `res.code()` (FetchedResource HTTP status) and `B.io.fromInputStream(res, "UTF-8")` for the body.
+
+```js
+const res = B.net.fetch("/b/aiCredits", {
+  method: "POST", credentials: true, followRedirects: false, enableErrorStream: true,
+  connectionTimeout: 10000, readTimeout: 15000,
+  headers: { "Content-Type": "application/json", "Accept": "application/json" },
+  body: JSON.stringify({ action: "check" })
+});
+const code = res.code();                          // HTTP status
+const text = B.io.fromInputStream(res, "UTF-8");  // body
+```
+
+`followRedirects:false` makes an auth bounce show as a non-2xx code instead of a login-page 200; `enableErrorStream:true` lets you still read the body on a non-2xx. FetchParams uses `connectionTimeout`/`readTimeout` (note the names). Confirmed working 2026-06-10 on summitridge /b/aiAudio (1471299) → /b/aiCredits (1471659): both the credit `check` gate and the `log` write now succeed and the BlueIQ ledger records spend.
+
+Complements [session cookie forwarding](session-cookie-forwarding.md) (the cookie-via-raw-header trick was for httpRequester loopbacks; prefer B.net.fetch + credentials instead). Related: [endpoint output channel](endpoint-output-channel.md), [http requester](http-requester.md) (httpRequester is still correct for EXTERNAL calls like api.openai.com), blueiq credit system.

package/templates/claude/instructions/reference/localdate-parse.md.template

@@ -0,0 +1,16 @@
+---
+description: Java.Time.LocalDate is a TypeScript namespace only; for runtime LocalDate.parse() / now() / etc. use B.time.LocalDate
+---
+For runtime LocalDate operations, use `B.time.LocalDate`:
+
+```ts
+const d = B.time.LocalDate.parse("2025-01-01");
+const today = B.time.LocalDate.now();
+if (d.isAfter(today)) { ... }
+```
+
+`Java.Time.LocalDate` exists in the .d.ts as a namespace for type annotations, but `Java.Time` is NOT a runtime symbol — calling `Java.Time.LocalDate.parse(...)` throws `Java is not defined` (or returns undefined). Same applies to `Java.Time.ZonedDateTime`, `Java.Time.LocalDateTime`, etc.
+
+**Use `Java.Time.X` only as type annotation; use `B.time.X` at runtime.**
+
+Confirmed on alpineacademy `/b/greatHair`, May 2026.

package/templates/claude/instructions/reference/merge-report-memo-json.md.template

@@ -0,0 +1,25 @@
+---
+description: "The \"merge report + memo field JSON hack\" — core framework for embedding a custom interactive widget on a BlueStep form that persists its state as JSON in a hidden memo field"
+---
+
+The recurring **"merge report + memo field JSON hack"** — how Brandon and I repeatedly build custom interactive UI on a BlueStep form without creating real sub-forms/MEF entries. This is the foundational framework; [multi entry in multi entry](multi-entry-in-multi-entry.md) and the permission layer [staff query permission gating](staff-query-permission-gating.md) are built on top of it.
+
+**The idea:** A BlueStep **merge report placed on a form** renders custom HTML/JS. All widget state is stored as a single JSON blob inside one **hidden memo (or JSON-memo) field** on that same form. The client hijacks the form's own Save to persist — no separate records, no MEF plumbing. One memo field = the entire data model.
+
+**Architecture (server-thin / client-fat), as separate files in a pulled component:**
+- `draft/scripts/app.ts` (server scriptlet) — thin. Gathers anything the client needs that requires server context (current user, permission flags, reference/query data), emits it as `<script id="server-data" type="application/json">{...}</script>` plus an empty mount `<div id="...-app"></div>`, assigned to `B.out`. Wrap everything in try/catch; on failure emit a safe payload so the client still degrades cleanly.
+- `draft/static/script.ts` (client) — the engine. On boot it:
+  1. Finds the memo via `document.querySelector('[data-fid="<fieldName>"]')` (it's a `<textarea>`).
+  2. **Hides the memo field's row** (`field.closest('tr')` → `display:none`) so users never see raw JSON.
+  3. Hydrates state from the live memo value (`memo.value`), falling back to server-emitted copy, else a default `{ schemaVersion, entries: [] }`.
+  4. Monkey-patches `window.submitForm`: wraps the original so it writes `memo.value = JSON.stringify(state)` right before the native save runs. The platform then persists the memo normally.
+  5. Renders custom UI into the mount; a single `mutate()` does state → syncToField → re-render.
+- `draft/static/styles.css` — lean on native BlueStep classes (`table table-striped`, `btn`, `sectionHeader sectionRuleB`); custom prefixed classes only for layout + modals.
+
+**Critical gotchas (all learned the hard way):**
+- Injected controls must have **NO `name` attribute** — named controls get submitted with the form → "problem storing the data". See [named controls submit](named-controls-submit.md).
+- Mount modals on `document.body` to escape the form's submit scope.
+- Borrow native relate icons (`/static/.../relate-icons/pencil.svg`, `trash.svg`) and call `window.fixAllSVG()` after render to recolor them like native lists.
+- Build pipeline / push rules: [tsc rootdir](../conventions/tsc-rootdir.md), [push inner draft](../conventions/push-inner-draft.md), [separate files](../conventions/separate-files.md), [always snapshot](../conventions/always-snapshot.md).
+
+**Reference implementations:** kaizenacademy/1465899 "Treatment Plan Review Comments Display" (original inspo, has Domains + lock); kaizenacademy/1466219 "Protocol Update Table" (notes-only + permission gating). Related JSON-in-memo dashboards: [crm dashboard inspo](crm-dashboard-inspo.md), visit dashboard.

package/templates/claude/instructions/reference/merge-report-static-index.md.template

@@ -0,0 +1,29 @@
+---
+description: BlueStep merge report with a static/ bundle renders static/index.html as the page; scripts/app.ts B.out is NOT injected — put the mount + config island in index.html and run the client on DOMContentLoaded
+---
+
+For a BlueStep merge report that ships a `static/` bundle (`static/index.html` +
+`static/.build/script.js` + `static/styles.css`), the **served page is
+`static/index.html`** — its `<script src=".build/script.js">` is what loads the
+client. The server `scripts/app.ts` `B.out` is **not injected into that page**, so
+a mount node / server-data island placed in `B.out` never appears in the DOM.
+
+Symptom we hit (summitridge Resources Hub merge report 1471799): client JS ran but
+`document.getElementById('rh-root')` and the `#rh-config` blob were both null,
+because the mount + config were emitted from `B.out`. Spinner hung forever.
+
+**Do this instead:**
+- Put the root mount (`<div id="rh-root">`) and any static config island
+  (`<script id="rh-config" type="application/json">…</script>`) **directly in
+  `static/index.html`**, before the `<script src=".build/script.js">` tag. (Mirror
+  of the working Treatment Targets widget: `<div id="tt-widget"></div>` lives in
+  index.html.)
+- Run the client on DOM-ready: `if (document.readyState==='loading')
+  document.addEventListener('DOMContentLoaded', start); else start();`
+- The client should fetch all dynamic data from its endpoint (server-thin/client-fat)
+  rather than expecting server-rendered data from `B.out`.
+- Server-side per-user data (e.g. current user for a form prefill) can't ride in via
+  `B.out`; defer it, fetch it from the endpoint, or use index.html merge tokens.
+
+Builds on [merge report memo json](merge-report-memo-json.md) and
+[separate files](../conventions/separate-files.md); relevant to bluestep resources.

package/templates/claude/instructions/reference/merge-report-urls.md.template

@@ -0,0 +1,67 @@
+---
+description: BSJS equivalents for relatescript form.System.lookupMergeReport / lookupMergeReportScript and how to get viewUrl/printUrl
+---
+# BSJS Merge Report URL Lookup
+
+Relatescript provides `form.System.lookupMergeReport("id","x")` and `lookupMergeReportScript("id","x")` returning `{name, label, viewURL, printURL, customProps}`. BSJS splits this across two APIs.
+
+## Direct id lookup (no record applicability filter)
+
+```typescript
+// Short id + lang ('js' BSJS, 'rs' relatescript):
+B.find.mergeReport("shortId", "js").viewUrl()
+
+// Full id, no lang:
+B.find.mergeReport("530024__FID_clientHeader").viewUrl()
+```
+
+Returns `MergeReportMetaData` (inherits `viewUrl()`, `editUrl()`, `id()`, `displayName()` from `BaseObject`). No `printUrl()` here.
+
+## Lookup by custom property, scoped to a record's form (true equivalent of `lookupMergeReport`)
+
+```typescript
+// BSJS reports (= lookupMergeReportScript):
+formEntry.optApplicableBsJsMergeReport("id", "x").get()
+
+// Relatescript reports (= lookupMergeReport):
+formEntry.optApplicableMergeReport("id", "x").get()
+```
+
+Returns full `MergeReport<T>` with `viewUrl()`, `printUrl()`, `profileUrl()`, `newEntryUrl()`, `copyUrl()`, `editUrl()`, `displayName()`, `id()`, `altIds()`, etc.
+
+Also: `applicableBsJsMergeReportResults(...)` returns `{results, message}` for error reporting.
+
+## Property mapping
+
+| relatescript | BSJS |
+|---|---|
+| `result.viewURL` | `.viewUrl()` |
+| `result.printURL` | `.printUrl()` (only on full `MergeReport`, not metadata) |
+| `result.name` | `.displayName()` (or `.id()` for the id) |
+| `result.label` | `.displayName()` |
+| `result.customProps` | no enumerator — pass as filter args, or walk `.altIds()` |
+
+## Gotchas
+
+- `viewUrl()` is **relative**. For absolute (emails etc.) wrap with `B.toFullyQualifiedUrl(rel)`.
+- `B.siteNavigation()` returns `SiteNavItem` (pages) — **does NOT** have `optLookupMergeReport`. The `optLookup*MergeReport` methods are on `RecordNavItem`, obtainable via `record.nav()`, but `record.nav()` is documented as expensive (30+ sec on uncached orgs). Prefer `B.find.mergeReport` or `optApplicableBsJsMergeReport`.
+- `B.find.mergeReport(id, 'js')` does NOT filter by record applicability — it's an id lookup. Only `optApplicable*` methods on FormEntry filter by applies-to-this-record.
+- Both APIs work in `MergeReportB` and `CommitableB` contexts (read-only).
+- **The `BsJs` prefix names the TARGET, not the caller.** Pick `optApplicableMergeReport` if the merge report you're looking up is a relatescript merge report — even when you're calling from a BSJS endpoint. Pick `optApplicableBsJsMergeReport` only if the target itself is a BSJS merge report. Confirmed in production on summitridge Report Viewer (Apr 2026): looking up the relatescript "unsignedForms" merge report from a BSJS CommitableB endpoint required `optApplicableMergeReport`, not the BsJs variant.
+
+## Existing examples in pulled code
+
+- `summitridge/Settings Events/draft/scripts/app.ts:52-54, 81, 276` — `B.find.mergeReport(shortId, 'rs').id()` / `.displayName()`
+- `alpineacademy/1463039/draft/scripts/medFunctions.ts:171` — `optApplicableMergeReport("id","medPrescribed").get().viewUrl()`
+- `beh/1433876/draft/scripts/app.ts:167` — `BaseObject.viewUrl()` on a record
+
+## Declarations source
+
+All in `declarations/B.d.ts`:
+- `B.find.mergeReport`: lines 23984-24001
+- `MergeReportMetaData`: line 11373
+- `MergeReport<T>` (printUrl 8398, profileUrl 8408, newEntryUrl 8413, copyUrl 8423): line 8389
+- `BaseObject.viewUrl()`: line 24613
+- `FormEntry.optApplicableBsJsMergeReport`: line 7585
+- `FormEntry.optApplicableMergeReport`: line 7573
+- `RecordNavItem.optLookupBsJsMergeReport`: line 10292