@bluestep-systems/bspecs 0.13.0 → 0.15.0

package/README.md

@@ -98,7 +98,7 @@ my-project/
     ├── bspecs.lock                    ← lock file for bspecs sync
     ├── settings.json                  ← Claude Code permissions and hooks
     ├── hooks/                         ← 3 scripts executed by Claude Code
-    ├── skills/                        ← 8 skills (/spec-create, /b6p-pull, etc.)
+    ├── skills/                        ← 9 skills (/spec-create, /b6p-pull, /bspecs-feedback, etc.)
     ├── agents/                        ← 3 BlueStep subagents (implementer, commenter, reviewer)
     ├── instructions/                  ← development rules for Claude
     ├── spec-templates/                ← spec file templates

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bluestep-systems/bspecs",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "description": "Spec-driven BlueStep development with AI agents — scaffolder and project conventions for Claude Code",
   "type": "module",
   "bin": {

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

@@ -10,7 +10,8 @@ When a BlueStep pull contains dedicated files (`styles.css`, `index.html`, `scri
 
 - 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 merge reports **with a `static/` bundle**: `static/styles.css` and `static/.build/script.js` load automatically while `B.out` renders the page body — leave CSS in `styles.css`; do **not** read or `B.net.fetch` your own stylesheet to inline it. See [merge report static index](../reference/merge-report-static-index.md).
+- For older merge reports **without** a `static/` bundle: 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.
 

package/templates/claude/instructions/index.md.template

@@ -11,6 +11,7 @@ Entries read: `path — what it covers. Load when <trigger>.` Match the trigger
 ## reference/ — single-topic platform and API detail
 
 - [reference/api-patterns.md](reference/api-patterns.md) — B API usage: Java optionals (`.opt()/.orElse()`), field types and access, `mergeTag()` L/F/I/H codes, multi-entry-form (MEF) entries, query access, Java collections, writing date/datetime fields, `B.commit()` and formula triggers, endpoint request/response, base64, user/session. Load when calling the `B` API, reading or writing fields, or wiring an endpoint's request/response.
+- [reference/b-include-element.md](reference/b-include-element.md) — `<b-include>` browser custom element that fetches HTML from a URL and renders it inline (client-side `<jsp:include>`/SSI); `src`/`run-scripts`/`csrf` attrs, spinner/error behavior, trusted-template-only (neutralized in user HTML). Load when injecting a dynamic async HTML fragment in the browser.
 - [reference/blueiq-credit-integration-playbook.md](reference/blueiq-credit-integration-playbook.md) — step-by-step playbook for wiring a new OpenAI/AI feature into the BlueIQ credit gate and ledger. Load when adding an AI feature that must consume BlueIQ credits.
 - [reference/chronounit-months.md](reference/chronounit-months.md) — `ChronoUnit.MONTHS.between` counts elapsed (day-aware) months, not calendar-month boundaries. Load when computing a month difference or porting SQL `DATEDIFF(MONTH)`.
 - [reference/code-patterns.md](reference/code-patterns.md) — working BsJs skeletons: queries, MergeReport server/client bridge, endpoints, error handling, performance (per-row queue, lazy init), component import, debugging. Load when starting a query, MergeReport, or endpoint and you want a known-good pattern.
@@ -31,8 +32,9 @@ Entries read: `path — what it covers. Load when <trigger>.` Match the trigger
 - [reference/id-full-vs-short.md](reference/id-full-vs-short.md) — `Id.toString()` is the full `ClassID___ShortID`; `shortId()` is just the trailing number; `optById` needs the full form. Load when round-tripping an entry id or calling `optById`.
 - [reference/internal-loopback-fetch.md](reference/internal-loopback-fetch.md) — endpoint-to-endpoint loopback within an org uses `B.net.fetch` on a relative path with `credentials:true`, not the external `httpRequester`. Load when one endpoint calls another in the same org.
 - [reference/localdate-parse.md](reference/localdate-parse.md) — `Java.Time.LocalDate` is a TypeScript namespace only; use `B.time.LocalDate` for runtime `parse()`/`now()`. Load when parsing or creating a LocalDate.
+- [reference/merge-report-async-loading.md](reference/merge-report-async-loading.md) — the "Asynchronous Loading" option on a Data Merge Report lazy-loads it AFTER the page resolves (BSJS used an `async` metadata property, not the checkbox); parent→child fan-out, the obsolete `formFooter` hack, and the script-timing gotcha. Load when a merge report is slow or should lazy-load, or page script depends on async merge content.
 - [reference/merge-report-memo-json.md](reference/merge-report-memo-json.md) — the "MergeReport + memo field JSON" framework: embed a custom interactive widget on a form that persists its state as JSON in a hidden memo field. Load when building a stateful custom widget on a form.
-- [reference/merge-report-static-index.md](reference/merge-report-static-index.md) — with a `static/` bundle, `static/index.html` is the page and `app.ts` `B.out` is NOT injected; put the mount + config island in `index.html` and run the client on `DOMContentLoaded`. Load when a MergeReport has a `static/` bundle.
+- [reference/merge-report-static-index.md](reference/merge-report-static-index.md) — with a `static/` bundle, `B.out` (server content) and `static/index.html` (client markup) both render but are completely disjoint (B.out is injected as a tag that runs *after* index.html), and `static/styles.css` + `.build/script.js` load automatically; put the mount + config island in `index.html`, keep CSS in `styles.css` (never fetch/inline it), use `B.out` only for final server-rendered markup, and get client data from the endpoint — not a `B.out` config island. Load when a MergeReport has a `static/` bundle.
 - [reference/merge-report-urls.md](reference/merge-report-urls.md) — BSJS equivalents of relatescript `lookupMergeReport`/`lookupMergeReportScript`, and how to get `viewUrl`/`printUrl`. Load when looking up a MergeReport URL in code.
 - [reference/multi-entry-in-multi-entry.md](reference/multi-entry-in-multi-entry.md) — the "multi entry in a multi entry" pattern: many notes/updates against one MEF entry, stored as JSON in one memo field. Load when users need repeated sub-entries under a single form entry.
 - [reference/named-controls-submit.md](reference/named-controls-submit.md) — any HTML control with a `name` attribute inside a MergeReport form gets submitted and breaks the save. Load when adding form controls to a MergeReport settings UI.

package/templates/claude/instructions/reference/b-include-element.md.template

@@ -0,0 +1,46 @@
+---
+description: "`<b-include>` is a browser custom element that fetches HTML from a URL and renders it inline — client-side `<jsp:include>`/SSI for dynamic async content; trusted-template only (neutralized in user-supplied HTML)"
+---
+
+`<b-include>` is a **browser custom element** (defined in `dom.ts:432-560`) that
+**fetches HTML from a URL and renders it inline** — think client-side `<jsp:include>`
+/ server-side-include for the browser. Use it for dynamic, async page fragments.
+
+**Syntax** — must use an explicit closing tag (it is **not** self-closing):
+```html
+<b-include src="/path/to/fragment.jsp"></b-include>
+```
+
+**Attributes**
+
+| Attribute     | Values                | Purpose |
+| ------------- | --------------------- | ------- |
+| `src`         | URL                   | Content to fetch. **Reactive** — changing it re-fetches automatically. |
+| `run-scripts` | `"true"` \| (omit)    | When `"true"`, `<script>` tags in the fetched HTML are re-inserted so the browser executes them. Default: scripts are inert. |
+| `csrf`        | `"true"` \| `"false"` \| (omit) | Force CSRF handling. Omit for auto-detect: same-origin → `csrf.fetch`, cross-origin → plain fetch. |
+
+**Examples**
+```html
+<!-- Basic same-origin include (CSRF token auto-attached) -->
+<b-include src="/shared/content/fragment.jsp"></b-include>
+
+<!-- Include a fragment and run its <script> tags -->
+<b-include src="/path/with/scripts.html" run-scripts="true"></b-include>
+
+<!-- Cross-origin with forced CSRF off (remote must send CORS headers) -->
+<b-include src="https://other.example.com/widget" csrf="false"></b-include>
+```
+
+**Behavior**
+- Shows a spinner while loading; shows an error box with a **"Reload"** link on failure.
+- Re-setting `src` aborts the in-flight request and re-fetches.
+- Removal from the DOM aborts any pending request.
+- Drivable from JS via properties: `el.src`, `el.runScripts`, `el.csrf`.
+
+**Security — trusted templates only.** `<b-include>` is **neutralized in user-supplied
+content** by `HTMLFilter.java:46` (rewritten to `<xxb-includexx>`) to prevent injection.
+Only use it in **trusted templates**, never in user-editable HTML. The Zesty editor
+whitelists it as `b-include[src|run-scripts|csrf]` (`zesty3.ts:130`).
+
+For the server-side config alternative (a merge report that lazy-loads after the page),
+see [merge-report-async-loading](merge-report-async-loading.md).

package/templates/claude/instructions/reference/csv-parsing.md.template

@@ -9,7 +9,7 @@ A server-side BSJS merge report CAN access and parse an uploaded CSV at runtime.
 **Three ways to get the file's bytes (priority order):**
 1. **DocumentLinkField on a form/record (preferred)** — an uploaded-file field. `field.content()` → string; `field.forReader(r => B.csv(r).toListOfObjects())` streams it. Also `.forInputStream()`, `.toBytes()`, `.filename()`, `.contentType()`, `.permUrl()/.davUrl()`. No HTTP hop, no auth ambiguity.
 2. **Document in a folder** — `folder.documents()['name.csv']` → same `.content()/.forReader()/.toBytes()` accessors. For file-system uploads not on a record.
-3. **Fetch by URL** — same `B.net.fetch(url)` pattern we use to inline styles.css; `B.csv(fetcher, fetcher.charset)`. Fallback only — reliability depends on URL + session auth. Prefer 1/2 for uploaded files.
+3. **Fetch by URL** — `B.net.fetch(url)` then `B.csv(fetcher, fetcher.charset)`. Fallback only — reliability depends on URL + session auth. Prefer 1/2 for uploaded files.
 
 **Permissions:** merge report runs in current user's context; routes 1/2 read via the platform object model subject to record/folder security.
 

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

@@ -0,0 +1,41 @@
+---
+description: A Data Merge Report's "Asynchronous Loading" option makes it lazy-load AFTER the rest of the page resolves instead of as part of the initial request; in BSJS this was an `async` metadata property rather than the checkbox
+---
+
+A BlueStep **Data Merge Report** has an **"Asynchronous Loading"** checkbox under
+*Advanced Usage Options* (Step 3 of the merge-report edit wizard). Turning it on
+makes the merge report **resolve in a lazy-load rather than as part of the initial
+page request** — the rest of the page renders first, then the merge report loads
+in separately so a heavy merge doesn't slow everything else down.
+
+This is **not a new feature**. It maps directly to the underlying DB object and has
+existed for a long time. **BSJS had no toggle** — you set an `async` property in the
+component metadata, which inserted a layer of indirection over that same DB object.
+Removing that BSJS layer is what surfaced the plain checkbox; it only *looks* new to
+anyone who previously only used BSJS.
+
+**Parent → child behavior.** When a merge report calls another async merge report,
+the **parent's HTML resolves first**, the page loads, and then each async child
+loads separately — so a parent merge report that fans out to N children can give
+each child its own independent loader. (The resident-med report does exactly this:
+a nasty merge that renders per resident, switched to async, **loads in batches of
+3 at a time**.)
+
+**Good use cases:** heavy/slow merges; merge reports embedded on a form; a parent
+merge report aggregating several child merge reports; query-driven layouts where
+displayed merge-report fields can stream in after the header data.
+
+**Gotcha — script timing.** Because the content is no longer present at initial page
+load, any page script that **expects the async merge report's DOM/data to already be
+there will break**. If you have client code depending on the merge report, gate it on
+the async content actually arriving rather than on initial `DOMContentLoaded`.
+
+**Obsolete hack.** Older setups added a marker like
+`htmlCode += '<span id="formFooter"></span>'` to force the async merge report to load
+properly. With the current setup this should **no longer be necessary** — don't carry
+it forward into new code.
+
+For dynamic async content driven from the client (rather than this server-side
+config), see [b-include element](b-include-element.md). Related merge-report detail:
+[merge-report-static-index](merge-report-static-index.md),
+[merge-report-memo-json](merge-report-memo-json.md).

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

@@ -1,29 +1,52 @@
 ---
-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
+description: BlueStep merge report with a static/ bundle — B.out (server content) and static/index.html (client markup) BOTH render but are completely disjoint (B.out is injected as a tag that runs AFTER index.html), and static/styles.css + .build/script.js load automatically. Put the mount/config/markup/CSS in static/, use B.out only for final server-rendered markup; never fetch/inline your own styles.css and never use a B.out config island as a data channel to the index.html client script.
 ---
 
-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.
+In a BlueStep merge report that ships a `static/` bundle (`static/index.html` +
+`static/.build/script.js` + `static/styles.css`), **both entry points render into
+the page together** (see [file execution](file-execution.md)):
+
+- `scripts/app.ts` writes **server content** to `B.out` — this **does** render.
+- `static/index.html` supplies the **client markup**; its `<link rel="stylesheet"
+  href="styles.css">` and `<script src=".build/script.js">` load **automatically**.
+
+But the two are **completely disjoint**: `B.out` is injected as a tag on the page
+that runs **after** `static/index.html` has been put on the page. They share no DOM
+context you can bridge — a node emitted from `B.out` is **not** something the
+index.html client script can reliably reach, and ordering tricks like
+`DOMContentLoaded` won't fix it (B.out arrives later, in a separate region).
+
+The platform serves `static/styles.css` (and `static/.build/script.js`) for you
+while `B.out` renders the page body. So you do **not** need to read or fetch your
+own stylesheet — `B.net.fetch("static/styles.css")` + inlining it into a `<style>`
+block in `app.ts` is pointless work. CSS stays in `static/styles.css` per
+[separate files](../conventions/separate-files.md).
+
+**Where each piece goes:**
+- Root mount (`<div id="…-root">`) and static config islands (`<script id="…-config"
+  type="application/json">…</script>`) → put in `static/index.html`, before the
+  `<script src=".build/script.js">` tag. (Mirror of the Treatment Targets widget:
+  `<div id="tt-widget"></div>` lives in index.html.)
+- CSS → `static/styles.css`. Client JS → `static/script.ts` (→ `.build/script.js`).
+- `B.out` (from `app.ts`) → **final server-rendered markup only**: HTML with
+  server-computed values baked straight in, e.g. record-scoped section URLs (see
+  [merge report urls](merge-report-urls.md)), current-user values, or query results
+  rendered as the visible content. Because B.out is disjoint from index.html, do
+  **not** emit a mount or a `<script type="application/json">` config island from
+  `B.out` and expect the index.html client script to read it — that's the trap below.
+
+**Getting server data to the client widget:** when a client-side widget (booted by
+the index.html script) needs server context, don't route it through `B.out` — fetch
+it from the component's **endpoint** (server-thin/client-fat), or use **index.html
+merge tokens**. Reserve `B.out` for content it renders directly.
 
 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.
+`document.getElementById('rh-root')` and the `#rh-config` blob were both null —
+because the mount + config island were emitted from `B.out`, a separate region that
+is injected *after* index.html and disjoint from the index.html client script. We
+*wrongly* concluded `B.out` wasn't injected — it is. The fix is to put the mount +
+config island in `static/index.html` (the client-markup file), and fetch any dynamic
+data from the endpoint.
 
 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/skills/bspecs-feedback/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: bspecs-feedback
+description: Send a bspecs tooling-change request (a rule, skill, subagent, hook, instruction, spec/module template, or the CLI) to the canonical bspecs repo as a prefilled GitHub issue. Use when you or the user notice something about the bspecs tooling itself that should change — local `.claude/` edits do not survive `bspecs sync`, so the fix has to go upstream.
+---
+
+# /bspecs-feedback — Send a tooling-change request upstream
+
+This project's `.claude/` tree (skills, hooks, instructions, settings, this very file) is a **scaffolded copy** that `bspecs sync` overwrites. Editing it locally does not reach the canonical repo and does not survive the next sync. This skill routes feedback to **`github.com/Bluestep-Systems/bspecs`** as a prefilled GitHub issue, so a fix can land there and ship to every project.
+
+It needs **no token and no backend**: the repo is public, the issue form is prefilled via a deep link, and GitHub authenticates the user through their existing browser session.
+
+**Scope check first.** This skill is for the **bspecs tooling** (a skill is wrong, a hook misfires, an instruction template is misleading, a `CLAUDE.md` rule is stale, a missing capability), or for a B6P rule general enough to belong in **every** scaffolded project. For project-local B6P domain knowledge that only matters here, capture it locally instead (see the Self-improvement section of this project's `CLAUDE.md`).
+
+## Steps
+
+### 1. Draft from context — don't cold-quiz
+
+The skill usually runs right after you and the user discussed the thing to change, so the relevant detail is already in the conversation. Draft the submission from it:
+
+- **kind(s)** — one or more of: `add rule`, `change rule`, `remove rule`, `report error/bug`, `request capability`, `report friction`. Multi-valued — a misleading rule is often `report error/bug` **and** `change rule`.
+- **target(s)** — one or more artifacts the feedback hits: instruction / skill / subagent / hook / settings-permission / spec template / module template / `CLAUDE.md` / CLI.
+- **file_path**, **current_text**, **proposal** — see step 2.
+
+Only when there is nothing to infer from (e.g. the user just types `/bspecs-feedback "the STOP messages are annoying"`) do you ask directly for kind(s) and target(s) and a one-line description.
+
+### 2. Capture context conditioned on kind
+
+The kind set drives what you collect (pull from the conversation first; read the tree to fill gaps):
+
+- **change rule / remove rule** → the affected **file path** + the **current rule text quoted verbatim** (read it from the `.claude/` tree). Keep the excerpt focused — do not paste a whole file.
+- **report error/bug** → a repro: what was run, what happened, what was expected.
+- **request capability** → the use case: what the user is trying to do that no skill/hook/CLI feature supports.
+- **add rule** → where the guidance should live + the proposed text.
+- **report friction** → what is painful and why (no fix required).
+
+Always capture the **bspecs version** — read `bspecs_version` from `.claude/bspecs.lock`:
+
+```
+node -e "try{const fs=require('fs');process.stdout.write(JSON.parse(fs.readFileSync('.claude/bspecs.lock','utf8')).bspecs_version||'unknown')}catch(e){process.stdout.write('unknown')}"
+```
+
+(Read + `JSON.parse` explicitly — `require('./.claude/bspecs.lock')` does **not** work, because Node's `require` only resolves `.js`/`.json`/`.node`, not a `.lock` extension.)
+
+Fall back to `unknown` if the lock is missing; never block on it.
+
+### 3. Confirm with the user
+
+Show the drafted submission — kind(s), target(s), file path, and the proposal/rationale — and ask:
+
+> File this to the bspecs repo?
+
+Adjust whatever the user corrects. Do **not** file without explicit confirmation.
+
+### 4. Build the prefilled issue link
+
+Target the structured issue form (`feedback.yml`) and prefill its fields by `id`, applying the `feedback` label. Assemble and URL-encode with node's `URLSearchParams` (node is guaranteed present — it backs `npx b6p`):
+
+```
+node -e '
+const fs=require("fs");
+const f=JSON.parse(fs.readFileSync(process.argv[1],"utf8"));   // {title, file_path, current_text, proposal, version}
+const p=new URLSearchParams({template:"feedback.yml", labels:"feedback", ...f});
+process.stdout.write("https://github.com/Bluestep-Systems/bspecs/issues/new?"+p.toString());
+' /path/to/fields.json
+```
+
+Write the field values to a temp JSON file first (in the scratchpad) so multi-line `current_text` / `proposal` survive without shell-quoting pitfalls.
+
+**Kind/target safety net.** The form's `kind` and `target` are multi-select dropdowns, and GitHub's query-param prefill for multi-selects is unreliable — and we use a **single `feedback` label** (no `kind:*` labels), so kind cannot ride the `labels=` param either. Therefore **embed kind(s) and target(s) as text** so the signal never gets lost:
+
+- Put a short kind summary in the **title**, e.g. `[feedback] change rule: b6p-push auth preflight wording`.
+- Lead the **proposal** field with a `Kind: … · Target: …` line, then the rationale/repro/use-case.
+
+`current_text`, `proposal`, `title`, `file_path`, `version` prefill reliably (the textareas have no `render:` attribute, which is required for query-param prefill). The dropdowns are best-effort on top.
+
+### 5. Open it, and always print the URL
+
+Open with the platform opener, falling back across environments, then echo the URL regardless:
+
+```
+url="<assembled url>"
+( command -v wslview >/dev/null 2>&1 && wslview "$url" ) \
+  || ( command -v xdg-open >/dev/null 2>&1 && xdg-open "$url" ) \
+  || ( command -v open >/dev/null 2>&1 && open "$url" ) \
+  || true
+echo "$url"
+```
+
+If auto-open fails (headless, no opener), the printed URL is the fallback — the user clicks it. The user reviews the prefilled form in their browser and submits; GitHub handles auth. The form applies the `feedback` label on submit even if the `labels=` param is dropped.
+
+## What this skill must NOT do
+
+- **No token, no backend, no server call.** The only network action is the user's browser opening a public GitHub URL.
+- **No local file fallback** (no `.jsonl`, no scratch capture as the "real" record). A scaffolded project is never meaningfully offline (the platform needs connectivity), and a local file never reaches the repo. The sole fallback for a failed auto-open is printing the URL.
+- **Do not edit the local `.claude/` tree to "fix" the rule.** `bspecs sync` overwrites it; the fix must land in the repo via the issue.
+- **Do not create `kind:*` labels** or pass them on `labels=` — only the `feedback` label exists; kind travels as text.
+- **Do not file without the user's confirmation** (step 3).

package/templates/claude/skills/spec-create/SKILL.md

@@ -9,7 +9,7 @@ A spec lives at `.claude/specs/<feature-name>/` and consists of three files: `re
 
 ## Prerequisite
 
-Read the `draft/README.md` of each component this feature will touch (see `CLAUDE.md` → "Reading module context — scoped to the task"). Read only the relevant components' READMEs, not the whole workspace. Those READMEs are your baseline for what each component does today — design decisions in Phase 2 should reference that knowledge, not re-derive it. If a relevant module's README is missing, ask the user to `/b6p-pull` it (or scaffold the README) before continuing.
+Read the `draft/README.md` of each component this feature will touch (see `CLAUDE.md` → "Module context — read scoped to the task"). Read only the relevant components' READMEs, not the whole workspace. Those READMEs are your baseline for what each component does today — design decisions in Phase 2 should reference that knowledge, not re-derive it. If a relevant module's README is missing, ask the user to `/b6p-pull` it (or scaffold the README) before continuing.
 
 ## Steps
 

package/templates/root/CLAUDE.md.template

@@ -13,7 +13,7 @@ This workspace is a **local copy** of components that live on the BlueStep platf
 - A project may span **one or more Unit folders** (`U######/`). Unit folders are created by `b6p pull` — never by hand.
 - Each Unit folder contains one or more **components** of any type (MergeReport, Endpoint, Formula, OnDemand, Scheduled, Post-Save). A single project mixes types freely.
 - New B6P **components** are created on the platform, never locally. Inside an existing component, creating new `.ts` files locally is fine.
-- Sync with the platform via `b6p pull "<DAV URL>"` (first pull or re-sync) and `b6p push --file "<component-path>/..."` (deploy). See the Sync workflow section below for the exact invocation.
+- Sync with the platform via the `/b6p-pull`, `/b6p-push`, and `/b6p-audit` skills (see the Skill quick reference).
 
 ## Critical rules (always apply)
 
@@ -44,43 +44,18 @@ This workspace is a **local copy** of components that live on the BlueStep platf
 
 Component type is encoded in `draft/info/metadata.json` (and the matching `config.json`). When you need to know whether a component is an Endpoint, MergeReport, etc., read those — don't infer from folder names.
 
-**Two distinct docs, by lifecycle:**
-
-- `<Component>/draft/README.md` — describes what the module **does today**. Lives inside `draft/` so it ships to the platform on push; anyone who pulls the module gets the doc. Scaffolded automatically by `/b6p-pull` when missing; if you change documented behavior, update the README in the same change.
-- `.claude/specs/<feature>/` — describes what you are about to **change or add** (requirements → design → tasks). Per feature, not per component. Created by `/spec-create`.
-
 ## The `B` object (platform API)
 
-| Namespace     | Purpose                                       |
-|---------------|-----------------------------------------------|
-| `B.net`       | Outbound HTTP (`B.net.fetch()`)               |
-| `B.util`      | Utilities (logging, parsing, formatting)      |
-| `B.io`        | I/O, WebSocket push (`B.io.sendMessage()`)    |
-| `B.db`        | Database access                               |
-| `B.time`      | Date/time — use this instead of native `Date` |
-| `B.queries`   | Query objects defined on the platform         |
-| `B.exports`   | Cross-formula data sharing                    |
-| `B.user`      | Current user (null in scheduled/cron scripts) |
-| `B.commit()`  | Force a mid-script transaction commit         |
-
-Full API patterns: read `.claude/instructions/bsjs-development.md` when writing or reviewing BsJs (load on demand — it is not auto-imported).
-
-## Reading module context — scoped to the task
-
-**Read `draft/README.md` only for the component(s) the current task touches** — not every component in the workspace. A workspace can hold dozens of components totalling thousands of lines of README; loading all of them into every session is wasteful and slow.
-
-When a task names (or clearly implies) one or more components, read those READMEs before suggesting or implementing anything. Each module's `draft/README.md` describes what the module does today; it was scaffolded by `/b6p-pull` from the code, so treat it as the source of truth for current behavior. If you're unsure which component a request maps to, ask — don't pre-load everything to be safe.
-
-To discover which components exist without reading their READMEs, list the `U######/*/` directories or read a single `draft/info/metadata.json`.
+All platform interaction goes through the global `B` object (`B.net`, `B.io`, `B.db`, `B.queries`, `B.exports`, `B.util`, …). Two inline gotchas worth never missing: use **`B.time`** for date/time, never native `Date`; **`B.user` is null** in scheduled/cron scripts. For the full namespace table and API patterns, read `.claude/instructions/bsjs-development.md` on demand (not auto-imported).
 
-If the component a task touches has no `draft/README.md` (or it's empty boilerplate), ask the user to run `/b6p-pull <DAV URL>` against that component to scaffold one. Don't proceed to edit code in a module whose README is missing.
+## Module context — read scoped to the task
 
-## Documentation and planning workflow
+**Read `draft/README.md` only for the component(s) the current task touches** — not every component in the workspace. A workspace can hold dozens of components totalling thousands of lines of README; loading all of them into every session is wasteful and slow. If a request is ambiguous about which component it maps to, ask — don't pre-load everything to be safe. To discover which components exist without reading their READMEs, list the `U######/*/` directories or read a single `draft/info/metadata.json`.
 
-Two distinct artifacts, separated by lifecycle:
+Two distinct docs, separated by lifecycle:
 
-- **`<Component>/draft/README.md`** — what the module **does today**. Read it for the component(s) a task touches (see "Reading module context" above). Update only when documented behavior changes. Ships to the platform on push, so other devs who pull the module get the doc.
-- **`.claude/specs/<feature>/`** — what we're about to **change or add** (requirements → design → tasks). Per feature, not per component. Created by `/spec-create`. Archived/deleted when the feature is done.
+- **`<Component>/draft/README.md`** — what the module **does today**. Lives inside `draft/`, so it ships to the platform on push and anyone who pulls the module gets it. Scaffolded by `/b6p-pull` from the code (the source of truth for current behavior); if a missing or empty README blocks a task, ask the user to run `/b6p-pull <DAV URL>` rather than editing code blind. Update it in the same change whenever documented behavior changes.
+- **`.claude/specs/<feature>/`** — what you're about to **change or add** (requirements → design → tasks). Per feature, not per component. Created by `/spec-create`; archived/deleted when the feature is done.
 
 ## Skill quick reference
 
@@ -117,24 +92,17 @@ For sync, status, and audit operations, infer naturally from what the user asks
 
 You don't need explicit confirmation to invoke these — they're either read-only or already have their own internal confirmation steps.
 
-## Sync workflow (b6p CLI internals)
+## Sync workflow (b6p CLI)
 
-The skills above wrap these commands. You can run them directly if you need to, but prefer the skills for guidance and consistency.
+The `/b6p-pull`, `/b6p-push`, and `/b6p-audit` skills own the exact `npx b6p …` invocations and their guidance — prefer them over running the CLI by hand. `b6p` ships as a devDependency (`@bluestep-systems/b6p-cli`) and is invoked as `npx b6p` (resolves `node_modules/.bin/b6p` cross-platform — no global install); run `npm install` once if `node_modules` is missing.
 
-`b6p` ships as a devDependency of this project (`@bluestep-systems/b6p-cli`). Invoke it with `npx b6p`, which resolves `node_modules/.bin/b6p` cross-platform — no global install, no shell or PATH detection. Run `npm install` once if `node_modules` is missing.
-
-**One-time platform auth (required before any pull/push/audit).** `b6p` needs BlueStep platform credentials, stored globally in `~/.b6p/` (once per machine — not per project). On a machine that has never run it, the **first** `b6p` command prompts for credentials interactively, which hangs Claude (`--yes` does not cover the credentials prompt). Before the first sync command, verify credentials exist with `test -f ~/.b6p/secrets.enc`; if absent, run `npx b6p auth set` once, then retry. The `/b6p-*` skills do this preflight automatically.
-
-- **Pull (DAV URL required):** `npx b6p --yes pull "<DAV URL>"`. The DAV URL is copied from the component's page in the BlueStep platform UI — `b6p pull` does not accept display names. First pull creates the `U######/` folder and the component skeleton.
-- **Push (file-driven):** `npx b6p --yes push --file "U######/<Component>/draft/scripts/app.ts"`. `--file` lets the CLI derive the destination from local metadata.
-- **Audit (read-only):** `npx b6p --yes --json audit --file "U######/<Component>/draft/scripts/app.ts"`. Lists files that differ between local and platform.
-- Always pass `--yes` so the CLI does not show interactive prompts that Claude cannot answer.
-- Both pull and push verify per-file integrity and only transfer files whose content changed.
-- If `npx b6p` cannot be resolved, run `npm install` in the project root (see the "Install dependencies" section of the project's `README.md`). For other errors, the VS Code b6p extension is an equivalent fallback.
+**One-time platform auth:** `b6p` needs BlueStep credentials stored in `~/.b6p/` (once per machine). The first command on a fresh machine prompts interactively and would hang Claude, so run `npx b6p auth set` once before the first sync. The `/b6p-*` skills preflight this automatically.
 
 ## Self-improvement
 
-If you discover a B6P rule or pattern that is not documented here:
+When you discover something worth changing, route it by **what** it is.
+
+**B6P domain knowledge** not documented here (a platform rule, a BsJs pattern) — capture it **locally**:
 
 1. Apply it for the current task.
 2. Capture the rule in the right place:
@@ -143,6 +111,11 @@ If you discover a B6P rule or pattern that is not documented here:
    - A single-topic detail or sharp edge → a new or existing atomic file under `.claude/instructions/{reference,conventions,gotchas}/`, and add (or update) its one-line entry in `.claude/instructions/index.md` so it's discoverable.
 3. Note in your response: "Added rule: <description>".
 
+**A bspecs tooling problem, or a rule that should reach _every_ project** — file it upstream with `/bspecs-feedback`. This `.claude/` tree is a scaffolded copy that `bspecs sync` overwrites, so a local edit here does not reach the canonical bspecs repo and does not survive the next sync. Use `/bspecs-feedback` when:
+
+- a bspecs **tooling artifact** is wrong, broken, or missing — a skill, hook, subagent, instruction _template_, settings rule, or a `CLAUDE.md` rule that came from bspecs; or
+- a B6P rule you found is general enough to belong in **every** scaffolded project (bspecs' shipped instruction templates), not just this one.
+
 ## Deep reference
 
 The deep platform and BsJs reference lives under `.claude/instructions/`. None of it is auto-imported — read on demand, only when the task needs it, so it doesn't sit in context every session.
@@ -154,6 +127,4 @@ The two on-demand overviews come first for high-frequency material:
 - `.claude/instructions/bsjs-development.md` — BsJs/TypeScript patterns, the `B` API, TS narrowing pitfalls. Read when writing or reviewing component code.
 - `.claude/instructions/b6p-platform.md` — platform architecture and concepts (Relate/Connect/Manage, component types, sync model, declarations). Read when a task hinges on platform behavior.
 
-Reach past the overviews into the indexed atomic files when you need a specific topic the overview only summarizes.
-
-The critical rules above (declarations, `.writable()`, `tsc`, `npx b6p`, per-component imports) are the must-always-apply subset — you don't need the deep files to honor them.
+Reach past the overviews into the indexed atomic files when you need a specific topic the overview only summarizes. The Critical rules above are the must-always-apply subset — honor them without needing the deep files.