@bluestep-systems/bspecs 0.10.0

package/templates/claude/instructions/bsjs-development.md.template

@@ -0,0 +1,430 @@
+---
+description: Deep technical reference for BsJs (BlueStep TypeScript). Read when writing or modifying component code.
+applyTo: "**/draft/scripts/**/*.ts"
+---
+
+# BsJs Development Reference
+
+Deep reference for BlueStep TypeScript development. Critical rules live in `CLAUDE.md`; this file covers patterns, APIs, and conventions that apply when actually writing code.
+
+## Contents
+
+- [Module structure](#module-structure)
+- [The `B` object — full API](#the-b-object--full-api)
+- [Reading and writing fields](#reading-and-writing-fields)
+- [Patterns by script type](#patterns-by-script-type)
+- [`info/` configuration](#info-configuration)
+- [TypeScript configuration & Graal compatibility](#typescript-configuration--graal-compatibility)
+- [Imports — never fabricate](#imports--never-fabricate)
+- [TS narrowing pitfalls (Graal/Java types)](#ts-narrowing-pitfalls-graaljava-types)
+- [Error handling](#error-handling)
+
+## Module structure
+
+```
+<project-root>/
+└── U######/                       ← Unit folder, created by `b6p pull`
+    └── ComponentName/
+        ├── declarations/          ← platform-generated, DO NOT EDIT
+        │   ├── B.d.ts
+        │   ├── scriptlibrary.d.ts
+        │   ├── Globals.d.ts
+        │   └── index.d.ts         ← platform-generated field/query/form declarations
+        └── draft/
+            ├── scripts/           ← TypeScript source
+            │   ├── app.ts         ← entry point
+            │   └── <feature>.ts   ← split modules
+            ├── objects/
+            │   └── imports.ts     ← legacy artifact in older modules; not updated on pull
+            ├── static/            ← MergeReport only: HTML, CSS, client JS
+            └── info/
+                ├── config.json
+                ├── metadata.json  ← identifies component type (read to know what this is)
+                └── permissions.json
+```
+
+A project may contain multiple Unit folders, each with multiple components of varying types. **Module split convention:** split complex logic into focused files under `scripts/`. `app.ts` is the entry point.
+
+**Multi-file components with ES imports are supported** (verified on the platform — `SMS Data Diagnostics`, `app.ts` importing `cleanupDuplicates.ts`). A sibling file `export`s a symbol and `app.ts` pulls it in with a standard relative ES import (no file extension); it compiles and links correctly after push. Use this to split a large `app.ts` into focused modules:
+
+```typescript
+// scripts/cleanupDuplicates.ts
+export function cleanupDuplicates(): void { /* ... */ }
+
+// scripts/app.ts
+import { cleanupDuplicates } from "./cleanupDuplicates";
+```
+
+## The `B` object — full API
+
+### `B.net` — outbound HTTP
+
+```typescript
+const response = B.net.fetch("https://api.example.com/data", {
+  method: "POST",
+  headers: { "Content-Type": "application/json" },
+  body: JSON.stringify({ key: "value" }),
+  timeout: 30000,
+});
+
+if (response.ok) {
+  const data = JSON.parse(response.body);
+}
+```
+
+### `B.time` — date/time
+
+Use `B.time` for any date/time work. Native `Date` is not supported.
+
+```typescript
+const now = B.time.now();
+const formatted = B.time.format(now, "yyyy-MM-dd HH:mm:ss");
+const parsed = B.time.parse("2026-05-15", "yyyy-MM-dd");
+```
+
+### `B.queries` — query objects
+
+Queries are defined on the platform and exposed in `declarations/index.d.ts` (platform-generated). Reference them only after pulling.
+
+```typescript
+const results = B.queries.activeClients.execute();
+for (const record of results) {
+  // ...
+}
+```
+
+**Unit scoping:** queries are unit-scoped by default. When re-using a query across units, call `clearSearchAndSort()` to reset filters:
+
+```typescript
+const query = B.queries.allRecords;
+query.execute();             // current unit
+query.clearSearchAndSort();
+query.unit = otherUnit;
+query.execute();             // other unit
+```
+
+### `B.exports` — cross-formula data
+
+Used to pass data between formulas in the same execution context.
+
+```typescript
+B.exports.totalScore = computeScore();
+B.clearExports();            // when starting fresh
+```
+
+### `B.user` — current user
+
+`B.user` is **null** in scheduled / cron scripts. Always guard:
+
+```typescript
+if (B.user) {
+  const userId = B.user.id;
+}
+```
+
+### `B.commit()` — manual transaction commit
+
+The platform calls `B.commit()` automatically when the script finishes. Only call it manually when:
+
+- You need a newly created entry's ID before the script ends.
+- You need post-saves to fire before subsequent reads.
+
+```typescript
+const newEntry = B.queries.someForm.getNewEntry();
+newEntry.name.set("test");
+B.commit();
+const id = newEntry.id;      // now available
+```
+
+## Reading and writing fields
+
+### Read
+
+```typescript
+const value = entry.fieldName.val();                          // current value
+const exportValue = entry.statusField.selectedExportValue();  // dropdown export value
+const all = entry.tagsField.allValues();                       // multi-select
+```
+
+`.val()` returns the field's value typed loosely (often `any`). When a field may be empty, prefer the Java-optional accessor with a default instead of null-checking the raw value:
+
+```typescript
+const name = entry.nameField.opt().orElse("");   // string, never null
+const score = entry.scoreField.opt().orElse(0);
+```
+
+Because projects compile with `strict: false` (see "TypeScript configuration & Graal compatibility"), `.opt().orElse()` plus explicit annotations are the main defense against silent `null`/`undefined` bugs.
+
+### Write
+
+Do not call `.writable()`. Field writability is configured on the platform — if the field is not configured as writable for this script type, the write will throw at runtime. Write directly:
+
+```typescript
+entry.nameField.set("new value");
+entry.statusField.setByExportValue("active");
+entry.tagsField.add("priority");
+entry.tagsField.remove("legacy");
+```
+
+### Multi-entry forms
+
+```typescript
+for (const entry of record.someForm.allEntries) {
+  entry.field.set("value");
+}
+
+const newEntry = record.someForm.getNewEntry();
+newEntry.name.set("new");
+
+oldEntry.delete();
+```
+
+## Patterns by script type
+
+### Post-Save
+
+Runs after a record is saved. Use `justCreated()` to distinguish new vs. updated records. `curEntry` is the entry being saved.
+
+```typescript
+export function run(): void {
+  if (curEntry.justCreated()) {
+    sendWelcomeEmail();
+  } else {
+    syncToExternal();
+  }
+}
+```
+
+### Endpoint
+
+Receives an HTTP request, returns a response. **Set `contentType` before writing the body. Use exactly one output method per request** (`out`, `stream`, or `redirect`).
+
+```typescript
+export function run(): void {
+  const action = request.param("action");
+  switch (action) {
+    case "list":  return listAll();
+    case "get":   return getOne();
+    default:      return badRequest();
+  }
+}
+
+function listAll(): void {
+  response.contentType = "application/json";
+  response.out(JSON.stringify({ items: getItems() }));
+}
+
+function badRequest(): void {
+  response.status = 400;
+  response.contentType = "text/plain";
+  response.out("Unknown action");
+}
+```
+
+#### Streaming (large responses)
+
+NDJSON pattern for streaming large datasets:
+
+```typescript
+response.contentType = "application/x-ndjson";
+const stream = response.stream();
+for (const record of B.queries.largeQuery.execute()) {
+  stream.write(JSON.stringify({ id: record.id, name: record.name.val() }) + "\n");
+}
+stream.close();
+```
+
+#### Redirect
+
+```typescript
+response.redirect("/some/path");
+```
+
+### MergeReport
+
+Backend logic in `scripts/`; **frontend in `static/`** (R3). Inject content into pages via `pageContent()`:
+
+```typescript
+export function run(): void {
+  pageContent("main").write(renderMain());
+  HEADER_SCRIPTS_BOTTOM().write(`<script src="${staticUrl("client.js")}"></script>`);
+  BODY().write(`<div class="footer">...</div>`);
+}
+```
+
+### OnDemand / Field Formula
+
+OnDemand formulas run on the **task pod** — well-suited for heavy or long-running work because they keep load off production pods. Trigger them asynchronously and let the result land in a record the caller can poll or react to.
+
+**Critical latency caveat:** OnDemand has a ~5 second scheduler-queue delay before it starts, by design. This is fine for background / async work. It is the wrong tool for anything on a user's synchronous wait path — if a user is waiting for a response, an OnDemand hop adds ~5 s of irreducible latency before the work even begins. Prefer a synchronous task-pod **Endpoint** for user-facing create or update paths.
+
+```typescript
+export function run(): void {
+  const result = runFormula();
+  B.message.info(`Result: ${result}`);
+}
+```
+
+### Scheduled / cron
+
+`B.user` is null. Use stored credentials or hardcoded service identities, and guard accordingly.
+
+```typescript
+export function run(): void {
+  if (B.user) {
+    log.warn("Scheduled script should not have a user context");
+    return;
+  }
+  doScheduledWork();
+}
+```
+
+### WebSocket push
+
+```typescript
+B.io.sendMessage(channelId, JSON.stringify({ type: "update", payload: data }));
+```
+
+## `info/` configuration
+
+### `config.json` (required)
+
+```json
+{
+  "language": "BsJs",
+  "entryPoint": "scripts/app.ts"
+}
+```
+
+### `metadata.json`
+
+Identifies the component type. Examples:
+
+- `"triggerType": "POST_SAVE"` — post-save
+- `"triggerType": "ENDPOINT"` — endpoint
+- `"triggerType": "ON_DEMAND"` — on-demand
+- `"triggerType": "SCHEDULED"` — scheduled
+
+### `permissions.json`
+
+Defines who can execute / view this component. Managed on the platform; usually pulled, rarely hand-edited.
+
+## TypeScript configuration & Graal compatibility
+
+### tsconfig and strict mode
+
+Each project root has a `tsconfig.json`. BlueStep projects run with **`strict: false`**, so the compiler will *not* catch every null/type error — compensate with `.opt().orElse()` and explicit type annotations. Typical settings:
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "strict": false,
+    "moduleResolution": "node",
+    "types": ["./declarations"]
+  }
+}
+```
+
+Do not run `tsc` locally — the platform compiles on push (a hook blocks local `tsc`). For why local builds / `rootDir` are avoided, see `conventions/tsc-rootdir.md`.
+
+### Graal compatibility (server-side)
+
+Server-side BsJs runs on **GraalVM**, not Node. Avoid relying on the newest language features there:
+
+- Stage-3 / very new ECMAScript proposals
+- Newer `Intl` APIs
+- `WeakRef` and `FinalizationRegistry` (limited support)
+
+Server-side `B.net.fetch` is **synchronous** — no `await`/Promise round-trip (see "`B.net` — outbound HTTP"). The `async`/`await` and browser `fetch().json()` patterns apply only to client JS shipped in a MergeReport's `static/`, which runs in the browser under normal compatibility rules.
+
+## Imports — never fabricate
+
+Query, form, and field references must exist in **the component you are editing**'s `declarations/index.d.ts` **before** you reference them in code. Form-field imports are per-component — another component's declarations file tells you nothing about this one. If a name is missing:
+
+1. Add it to **this component's** form-import config on the platform.
+2. Run `npx b6p pull "<DAV URL>"` to update this component's declarations.
+3. Then reference it in TypeScript.
+
+Hallucinating an import name silently passes type-check locally if the file is missing, but will fail at platform compile.
+
+## TS narrowing pitfalls (Graal/Java types)
+
+Some TypeScript patterns fail silently with the Java types exposed by `B` (especially `Java.Time.Instant`, `Java.Time.ZonedDateTime`, and any `Optional`-like interface). Avoiding them upfront saves edit → diagnostic → fix cycles.
+
+### Narrowing broken in closures
+
+**Anti-pattern:**
+
+```typescript
+let latest: Java.Time.Instant | null = null;
+collection.forEach((item) => {
+  const inst = item.getInstant();
+  if (!latest || inst.isAfter(latest)) {  // ❌ TS narrowing collapses to `never`
+    latest = inst;
+  }
+});
+```
+
+TypeScript cannot guarantee that the captured variable is still non-null when the next line of the callback executes, so it collapses the type to `never` and `.isAfter()` stops existing.
+
+**Solutions, in order of preference:**
+
+1. **Compare primitive values** (best): avoid the nullable union entirely by using epoch millis, ISO strings, or a sentinel value.
+
+   ```typescript
+   let latestMs = -1;
+   collection.forEach((item) => {
+     const ms = item.getInstant().toEpochMilli();
+     if (ms > latestMs) latestMs = ms;
+   });
+   ```
+
+2. **Local alias with explicit type** (when the Java type must be kept): capture the variable in a `const` with the declared type before the comparison, forcing TS to re-narrow within the local scope.
+
+   ```typescript
+   let latest: Java.Time.Instant | null = null;
+   collection.forEach((item) => {
+     const inst = item.getInstant();
+     const prev: Java.Time.Instant | null = latest;  // explicit alias
+     if (prev === null || inst.isAfter(prev)) {
+       latest = inst;
+     }
+   });
+   ```
+
+3. **Accumulate then reduce**: when the above feels forced, `forEach` into an array and sort/reduce outside the loop.
+
+### Symptoms to recognize
+
+- `Property '<x>' does not exist on type 'never'.` inside a callback that captures a nullable `let`: 99% of the time this is this pitfall.
+- "Works the first time but breaks after refactoring to multi-step": suspect broken narrowing.
+
+## Error handling
+
+The platform surfaces uncaught exceptions in the script log. Patterns:
+
+```typescript
+try {
+  const response = B.net.fetch(url, { timeout: 5000 });
+  if (!response.ok) {
+    log.error(`Upstream returned ${response.status}`);
+    return;
+  }
+  process(response.body);
+} catch (err) {
+  log.error(`Fetch failed: ${err.message}`);
+}
+```
+
+For endpoints, prefer explicit status codes over throwing:
+
+```typescript
+if (!validInput) {
+  response.status = 400;
+  response.contentType = "application/json";
+  response.out(JSON.stringify({ error: "invalid input" }));
+  return;
+}
+```

package/templates/claude/instructions/conventions/always-snapshot.md.template

@@ -0,0 +1,25 @@
+---
+description: "BlueStep pull/push/snapshot workflow — always use the CLI scripts (never fetch manually) and always snapshot after every change via push → pull → snapshot"
+---
+
+Always use the BlueStep CLI scripts. Never use WebFetch, curl, or the Write tool to interact with BlueStep files manually.
+
+- Pull:     `node ~/.bluestep/pull.js <url>`
+- Push:     `node ~/.bluestep/push.js [folder]`
+- Snapshot: `node ~/.bluestep/push.js --snapshot --comment "message" [folder]`
+
+**Why:** A full system handles auth, WebDAV, folder naming by display name, `.b6p_url.json` tracking, and GraphQL snapshot-history recording. Bypassing it breaks the whole workflow.
+
+**How to apply:** Any time the user says "pull", "push", or "snapshot" in a BlueStep context, use the CLI scripts. Credentials are in `~/.bluestep/config.json` — never prompt for them. Always snapshot after every code change — do not wait to be asked. Always include a `--comment` with a 1–3 sentence summary of what changed and why.
+
+## Snapshot workflow — always push → pull → snapshot
+
+Never run `--snapshot` directly after editing. The correct sequence is:
+
+1. `node ~/.bluestep/push.js [folder]` — push source files to draft (BlueStep compiles TypeScript server-side).
+2. `node ~/.bluestep/pull.js <url>` — pull to get the freshly compiled `.build/` files from the server.
+3. `node ~/.bluestep/push.js --snapshot --comment "summary of changes" [folder]` — now the snapshot has the correct compiled JS and records history.
+
+**Why:** `push.js` skips `.build/` directories (compiled artifacts), and BlueStep compiles TypeScript on the server. Snapshotting without pulling first captures stale local `.build/` files and reverts the compiled output to an older version. The pull step fetches the server-compiled JS before snapshotting. The `--comment` flag records a GraphQL history entry (author, timestamp, message) matching what the VS Code extension does.
+
+Related: [snapshot integrity](snapshot-integrity.md) (including locally-compiled `.build/*` in the snapshot `saveState`), [push inner draft](push-inner-draft.md), [tsc rootdir](tsc-rootdir.md).

package/templates/claude/instructions/conventions/blueiq-no-ai-branding.md.template

@@ -0,0 +1,11 @@
+---
+description: "On BlueStep BlueIQ work, never use \"AI\" in front-facing/user-visible text — the brand is always \"BlueIQ\""
+---
+
+On the BlueStep BlueIQ stack (summitridge: `/b/aiAudio` 1471299, `/b/aiCredits` 1471659, Shift Note Assistant 1471399, AI Audio Tester 1471304), never use the word "AI" in any front-facing / user-visible text. The user-facing brand is always **BlueIQ**. E.g. "out of monthly credits" (not "AI credits"), "BlueIQ Audio endpoint alive" (not "AI Audio"), "BlueIQ Assistant" (not "AI Audio Tester").
+
+**Why:** BlueIQ is the brand name customers see; AI is not the front-facing branding for this product line.
+
+**How to apply:** Scrub "AI" only from user-visible strings: HTML/UI text, button/panel labels, status messages, and JSON `error`/`status`/`message` fields that surface to a user. Leave as-is (exempt): the provider's real name "OpenAI"; internal identifiers and URL paths (`/b/aiCredits`, `/b/aiAudio`, `AI_CREDITS_PATH`, `openAIIntegration`, `openAILogs`, `aiaud-*` CSS classes); and code comments. Admin-only ledger "function" labels were also rebranded to "BlueIQ …" for consistency, but they are lower priority.
+
+Related: [blueiq credit integration playbook](../reference/blueiq-credit-integration-playbook.md).

package/templates/claude/instructions/conventions/date-format.md.template

@@ -0,0 +1,27 @@
+---
+description: "BlueStep addSearch needs MM/DD/YYYY for date fields — YYYY/MM/DD passes validation but silently fails to filter; raw Java LocalDate objects also fail"
+---
+
+When building MEF queries with `addSearch(field, op, value)` against a date or date/time field, pass the value as a string in `MM/DD/YYYY` format (US-order, slash-separated) — what BlueStep's `parseDate` documents as its default at `B.d.ts:2660`.
+
+**Why:** Two BlueStep date formats coexist and they are NOT interchangeable for search input:
+
+- `B.time.B6P_LOCAL_DATE = ofPattern("uuuu/MM/dd")` — the serialization/display format. `YYYY/MM/DD` strings ARE accepted by `addSearch` validation as "well-formatted" (no error thrown), but the comparison silently fails to apply — the predicate is dropped and all rows pass through unfiltered. Learned the hard way on the summitridge Report System (twice).
+- `B.time.parseDate` default = `MM/dd/yyyy` — the actual parser BlueStep uses for date search values. This is the format `addSearch` wants.
+
+ISO-8601 `YYYY-MM-DD` (with dashes, what HTML `<input type="date">` emits) throws the explicit error: *"Searching a date/time field requires a null, a date/time value or a String containing a well formatted date/time value."*
+
+Passing a raw Java `LocalDate` object from `B.time.LocalDate` also fails — Graal.js's JS↔Java marshalling does not produce a usable string representation when the value flows into `addSearch`. (However, `B.time.ZonedDateTime` instances appear to work — see `gardenplazaofvalleyview\(DOR) Daily Occupancy Report` for a working example.)
+
+**How to apply:**
+
+- Format a JS `Date` to BlueStep search format as `MM/DD/YYYY` with slashes: `${m}/${day}/${y}`, zero-padded.
+- Convert ISO `YYYY-MM-DD` from HTML date inputs to `MM/DD/YYYY` before calling `addSearch`.
+- Working precedent: `rop\DPN Scoring\draft\scripts\app.ts:261` — `toMDY = (iso) => "${m}/${d}/${y}"`.
+- Do NOT pass raw `LocalDate` / `LocalDateTime` Java objects to `addSearch` — always convert to BlueStep-format strings first.
+- For datetime fields specifically, the format is unverified but likely `MM/DD/YYYY hh:mm:ss a` (the input-side analog of `B6P_LOCAL_DATETIME`'s output format). The summitridge Report System catalog has no datetime fields yet, so this is theoretical.
+
+**The trap that bit twice on the summitridge Report System:**
+
+1. Initial bug 2026-04-24: passed ISO `YYYY-MM-DD` → got the well-formatted-date error → fixed by switching to `YYYY/MM/DD`.
+2. Regression 2026-04-26: `YYYY/MM/DD` made the error stop, but filters silently returned all rows. Real fix: switch to `MM/DD/YYYY`. Don't be fooled by the absence of an error — a date filter that's actually applied produces a *narrower* row count.

package/templates/claude/instructions/conventions/endpoint-approach.md.template

@@ -0,0 +1,9 @@
+---
+description: "Research-first approach for BlueStep endpoints — gather API docs, read type declarations, study existing examples before writing"
+---
+
+For any new BlueStep endpoint or integration, front-load research before writing code: read the external API docs, study the `B.d.ts` declarations for HTTP/request/response patterns, and look at existing endpoint examples in the org. Write with full context.
+
+**Why:** This avoids trial-and-error iteration on BlueStep's GraalJS environment, where testing requires pushing to the server. The research-first pass has produced correct code on the first try.
+
+**How to apply:** Gather API docs + type declarations + existing examples up front. When delegating to a `bluestep-dev` agent, pass comprehensive context including exact method signatures and patterns.

package/templates/claude/instructions/conventions/formula-patterns.md.template

@@ -0,0 +1,71 @@
+---
+description: "Correct BSJS formula patterns — form access, field reads/writes, HTTP, error handling, B.* utilities, DocumentLinkField"
+---
+
+Use these patterns as the baseline for every BlueStep post-save (or any) formula. Do not deviate without first checking a working formula — endpoints and merge reports behave differently, and formulas need special care.
+
+**Why:** Hard-won from multiple failed iterations on a document-summarizer formula. The recurring failures were wrong form access and wrong HTTP response reading.
+
+## Structure
+
+- Line 1 is ALWAYS: `/// <reference path='../../../scriptlibrary' />`
+- Formulas run as bare top-level statements — NO IIFE, no `main()`, no `export default`.
+- No bare `return` statements — use a guard `if` block, or `throw` inside try/catch, for early exits.
+
+## Form / field access
+
+- A form/query configured in the component's platform form-import config (regenerated into `declarations/index.d.ts` on pull) is available as a **top-level variable directly in `app.ts`**, named after its FID — do NOT use `B.currentRecord()`. (Older modules registered this by hand in a now-legacy `objects/imports.ts`.)
+- Fields: `myForm.fields.fieldName`.
+- Field read: `.val()` (direct) or `.opt().orElse(default)` (safe).
+- Field write: `.val(newValue)` for scalars (string, bool, date, number).
+- Clear a field: `.clear()`.
+- Single-select dropdown (200): `.val(exportValueString)` — `.options()` does NOT exist on these, it throws "Unknown identifier: options".
+- Multi-select checkbox (201): `.options().filter(op => ...).forEach(op => op.selected(true))`.
+- Set by ID: `.set(B.util.toId(idString))`.
+
+## HTTP + response reading
+
+```typescript
+const stream = B.net.fetch(url, {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json', 'Authorization': 'Bearer ...' },
+  body: JSON.stringify(payload),
+  connectionTimeout: 60_000,
+  readTimeout: 60_000
+});
+const responseText = B.io.fromInputStream(stream); // ← always use this, not BufferedReader
+const data = JSON.parse(responseText);
+```
+
+## Error handling
+
+```typescript
+try {
+  // logic — use throw "message" for controlled early exits
+} catch (e) {
+  const sw = B.io.stringWriter();
+  if (e.printStackTrace) e.printStackTrace(B.io.toPrintWriter(sw));
+  else sw.write(e.toString());
+  myForm.fields.resultField.val('[Error: ' + sw.toString() + ']');
+  B.net.sendMessage('Formula failed: ' + sw.toString(), true); // modal alert to user
+  B.io.printStackTrace(e); // server log
+}
+```
+
+## B.* utilities
+
+- `B.io.fromInputStream(stream)` — read HTTP response to string.
+- `B.io.stringWriter()` + `B.io.toPrintWriter(sw)` — capture Java stack traces.
+- `B.io.printStackTrace(e)` — write exception to server log.
+- `B.toBase64(javaByteArray)` — base64-encode a `Java.ByteArray`.
+- `B.net.fetch(url, params)` — outbound HTTP.
+- `B.net.sendMessage(html, true)` — modal alert to current user.
+- `B.util.toId(string)` — convert a string to a `Bluestep.Id`.
+- `B.time.ZonedDateTime.now()` — current timestamp.
+
+## DocumentLinkField
+
+- Cast: `formEntry.fields.document as unknown as Bluestep.Relate.DocumentLinkField`.
+- `docField.toBytes({})` — get the file as a `Java.ByteArray`.
+- `docField.filename()` — get the filename string.
+- `docField.contentSize()` — size in bytes (0 = no file attached).

package/templates/claude/instructions/conventions/no-global-dollar.md.template

@@ -0,0 +1,9 @@
+---
+description: "BlueStep pages use jQuery — never define a global $ function or variable in merge-report scripts or you silently break Save and all page interactivity"
+---
+
+Never define a global function or variable named `$` in BlueStep merge-report scripts. BlueStep loads jQuery, and the entire page (form submission, change management, modals, navigation) depends on `$` being jQuery. Overwriting it with a `querySelector` wrapper silently breaks the Save button and all page interactivity.
+
+**Why:** This caused a hard-to-diagnose bug where Save did nothing — jQuery's `$` was replaced by a plain `querySelector` helper, breaking `submitForm` and all BlueStep internals.
+
+**How to apply:** Use `qs()` (or another non-colliding name) for `querySelector` helpers. Also avoid overwriting other common globals like `el` if they might collide with BlueStep or library internals.

package/templates/claude/instructions/conventions/push-inner-draft.md.template

@@ -0,0 +1,21 @@
+---
+description: "Always pass the inner draft/ folder (not the component root) to push.js, otherwise files land in a draft/draft/* dead zone on BlueStep"
+---
+
+When pushing a BlueStep component, always pass the **inner `draft/` folder** as the local-folder argument to `push.js`, never the component root.
+
+```bash
+# CORRECT — relative paths come out as "scripts/app.ts", "static/script.ts"
+node ~/.bluestep/push.js [--snapshot --comment "..."] \
+  "C:\...\Bluestep Pull Requests\<org>\<...path>\<Component Name>\draft" \
+  "https://<org>.bluestep.net/files/<id>/draft/"
+
+# WRONG — relative paths come out as "draft/scripts/app.ts" and land in draft/draft/*
+node ~/.bluestep/push.js "...\<Component Name>" "..."
+```
+
+**Why:** `push.js` (`~/.bluestep/push.js`, lines 388–396) walks the supplied local folder and computes each file's path relative to it, then appends that relative path to the target URL. If the local folder is the component root (which contains `draft/` as a subfolder), every file's relative path starts with `draft/`, and concatenated with a target URL that already ends in `/draft/` you get `.../draft/draft/scripts/app.ts` — a parallel ghost tree BlueStep does not load from. The live files BlueStep serves live at the URL root (`.../draft/scripts/...`), not under a nested `draft/`.
+
+**How to apply:** Every time you invoke `push.js` for a BlueStep component, the `localFolder` argument's last path segment must be `draft` (or `snapshot`). If you accidentally push at the wrong level, the symptom is silent staleness — pushes "succeed" but the live JS never updates, and browser caches and source maps mislead you into thinking the bug is in code that is actually fine. Diagnose by inspecting the BlueStep file tree for a duplicate `draft/` subfolder or unexpected files at the root.
+
+**Related — the deriver fails when components are nested deeper than `<org>/<scriptName>`.** `push.js`'s URL deriver expects exactly three path segments before `draft/` (org / scriptName / type). The Report System uses `summitridge/Report System/<Component>/draft` — four segments — so auto-derive fails. Fix: read each component's `.b6p_metadata.json` and pass the `url` explicitly as the second argument. All three Report System components (Maestro, Viewer, Builder) need this on every push.

package/templates/claude/instructions/conventions/separate-files.md.template

@@ -0,0 +1,17 @@
+---
+description: "Don't pile CSS/HTML/JS into app.ts — use the dedicated files (styles.css, index.html, script.ts) that the pulled folder already has"
+---
+
+When a BlueStep pull contains dedicated files (`styles.css`, `index.html`, `script.ts`, etc.) alongside `app.ts`, put each kind of content in the file that is named for it. Do not dump all CSS and HTML into a single giant `B.out = ` template literal in `app.ts`.
+
+**Why:** The folder layout exists precisely so concerns are separated — CSS in `styles.css`, markup in `index.html`, client interactivity in `script.ts`. Stuffing everything into `app.ts` defeats the structure and makes the code unmaintainable. The user has called this out multiple times.
+
+**How to apply:**
+
+- Before writing or modifying a BlueStep file, list the folder contents and identify which dedicated files exist.
+- Route content to its natural file: CSS → `styles.css`, markup template → `index.html` (or a separate template file), client-side JS → `script.ts`, server-side logic → `app.ts`.
+- For merge reports specifically: the server-side TS can read sibling files via `B.io.fromInputStream(...)` (or the appropriate API) and inject them into `B.out` — investigate the existing API rather than inlining.
+- For endpoints with `static/` folders: HTML/CSS/JS load from their own files; `app.ts` is the request handler only.
+- If unsure how multiple files relate in a given BlueStep component type, check [api patterns](../reference/api-patterns.md) and look at how other working components are organized.
+
+**Repeated offense — do not do this again.**

package/templates/claude/instructions/conventions/single-script.md.template

@@ -0,0 +1,28 @@
+---
+description: "BlueStep's server-side build compiles only root static/script.ts to .build/script.js — subdirectory .ts files are NOT compiled"
+---
+
+Keep all BlueStep merge-report client code in ONE file: `static/script.ts`. BlueStep compiles only the root `static/script.ts` → `.build/script.js`. It does NOT recursively compile `static/util/*.ts`, `static/pages/*.ts`, etc. — even though a `tsconfig.json` with `"include": ["**/*.ts"]` suggests it should.
+
+Symptom when you get this wrong: silent 404s on every subdirectory `.build/*.js`, producing a completely blank page (no errors — the scripts just don't load).
+
+**Why:** Discovered 2026-04-15 while building the CRM Intelligence Dashboard (beh/1433876). A modular architecture with `util/escape.ts`, `util/dates.ts`, `pages/overview.ts`, etc. produced an empty `.build/` and a blank page. Consolidating everything into a single `static/script.ts` (matching the Havenwood Census Dashboard pattern) fixed it immediately.
+
+**How to apply:**
+
+- Put all merge-report client code in one file: `static/script.ts`.
+- Use banner comments to organize logical sections (TYPES, UTILITIES, COMPONENTS, PAGES, ENTRY POINT).
+- `static/index.html` should load only `styles.css`, any CDN scripts (e.g. Chart.js), and `.build/script.js`.
+- Server endpoint code follows the same rule: `scripts/app.ts` is the only runtime-loaded entry. Confirmed on server-side endpoints 2026-04-24 — a sibling `scripts/runAction.ts` containing runtime functions compiled to its own `.build/scripts/runAction.js`, but BlueStep never loaded it, so `handleRunAction is not defined` at runtime.
+
+**Exception — pure type files are safe to keep separate:**
+
+- A `scripts/types.ts` that contains ONLY `interface`/`type`/type-alias declarations (zero runtime emit) can live alongside `app.ts`. TypeScript sees it at compile time; no JS is emitted for it; BlueStep has nothing to load or miss. Verified on the summitridge Report System Maestro.
+- The moment you add a runtime value (a `const`, `function`, or `class` that emits), it becomes invisible unless merged into `app.ts`.
+
+**Gotcha — module-level `const` + top-level dispatcher = temporal dead zone (TDZ) errors:**
+
+- If `scripts/app.ts` starts with a top-level `try { ... switch(action) { case "x": handleX(); } }` and `handleX` references a `const` declared *later* in the same file, Graal.js throws `ReferenceError: X is not defined` at runtime. Function declarations hoist; `const` bindings do NOT. See [top level const tdz](top-level-const-tdz.md).
+- Fix: put all module-level constants ABOVE the top-level dispatcher block. Seen on the Report Data Maestro 2026-04-24 (`MAX_PAGE_SIZE`, `OPS_BY_TYPE`, etc.).
+
+If the architecture is genuinely too big for one file, concatenate at author time (source section comments, clear banners) rather than relying on module resolution — BlueStep's compiler does not do it for you.