@bluestep-systems/bspecs 0.11.1 → 0.13.0

package/README.md

@@ -46,11 +46,21 @@ devDependency; bare `npx b6p` resolves only inside a scaffolded project, where `
 From the parent directory where you want to create the project:
 
 ```sh
-bspecs
+bspecs new
 ```
 
 The interactive wizard asks for the project name, client, and an optional description. When done, it generates the project directory with the full structure and (unless you opt out) runs `git init`.
 
+### Add the tooling to an existing project
+
+Already have a project and just want the Claude Code tooling? From inside that project's directory:
+
+```sh
+bspecs init
+```
+
+`bspecs init` installs the full tooling tree **in place** and is strictly non-destructive: any file that already exists is left untouched. The one exception is `package.json` — the `@bluestep-systems/b6p-cli` devDependency (and the `b6p` script) are merged in, preserving everything else. It then writes the `bspecs.lock` so `bspecs sync` works going forward. At the end it prints a report of every file it skipped because the name already existed; to install the `bspecs` version of any of them, rename or move your local copy and run `bspecs init` again. The client-name prompt is optional — press Enter to default to `BlueStep Client`. (No `git init` — an existing project owns its own VCS.)
+
 ### Keep a project up to date
 
 When a new version of `bspecs` is published with improvements to skills, hooks, or instructions, update your global install and sync the project:

package/cli.js

@@ -3,8 +3,8 @@ import { intro, outro, cancel, log } from '@clack/prompts';
 import { readFileSync } from 'fs';
 import { dirname, join } from 'path';
 import { fileURLToPath } from 'url';
-import { runPrompts } from './src/prompts.js';
-import { scaffold } from './src/scaffold.js';
+import { runPrompts, runInitPrompts } from './src/prompts.js';
+import { scaffold, init } from './src/scaffold.js';
 import { sync } from './src/sync.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -12,17 +12,22 @@ const pkg = JSON.parse(readFileSync(join(__dirname, 'package.json'), 'utf8'));
 
 const HELP = `bspecs — spec-driven BlueStep development with AI agents
 
-Scaffold a new BlueStep project with Claude Code skills, hooks, and
+Scaffold and maintain BlueStep projects with Claude Code skills, hooks, and
 project conventions for spec-driven development.
 
 Usage:
-  bspecs           Run the interactive scaffolder in the current directory.
+  bspecs new       Scaffold a brand-new project in a new subdirectory.
+  bspecs init      Install the tooling into the current directory (non-destructive).
   bspecs sync      Sync infrastructure files in the current project.
   bspecs -v        Print version.
   bspecs -h        Print this help.
 
 Options for bspecs sync:
   --silent         Suppress all output (used by the SessionStart hook).
+
+bspecs init never overwrites an existing file (package.json has the b6p-cli
+devDependency merged in) and reports what it skipped so you can rename/move and
+re-run. Its client-name prompt is optional — press Enter for "BlueStep Client".
 `;
 
 function parseArgs(argv) {
@@ -31,7 +36,9 @@ function parseArgs(argv) {
   if (flags.has('-v') || flags.has('--version')) return { mode: 'version' };
   if (flags.has('-h') || flags.has('--help'))    return { mode: 'help' };
   if (positional[0] === 'sync') return { mode: 'sync', silent: flags.has('--silent') };
-  return { mode: 'interactive' };
+  if (positional[0] === 'new')  return { mode: 'new' };
+  if (positional[0] === 'init') return { mode: 'init' };
+  return { mode: 'help' };
 }
 
 async function main() {
@@ -52,6 +59,25 @@ async function main() {
 
   intro('bspecs — spec-driven BlueStep development with AI agents');
 
+  if (mode === 'init') {
+    const answers = await runInitPrompts();
+    if (!answers) {
+      cancel('Cancelled.');
+      process.exit(0);
+    }
+
+    await init(answers);
+
+    outro(
+      `bspecs tooling installed in ${process.cwd()}\n` +
+      `  Next steps:\n` +
+      `    npm install   (if it did not run automatically)\n` +
+      `    npx -p @bluestep-systems/b6p-cli b6p auth set   (platform credentials, once per machine)`
+    );
+    return;
+  }
+
+  // mode === 'new'
   const answers = await runPrompts();
   if (!answers) {
     cancel('Cancelled.');

package/package.json

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

package/src/prompts.js

@@ -1,6 +1,6 @@
 import { text, confirm, isCancel, cancel } from '@clack/prompts';
 import { existsSync } from 'fs';
-import { join } from 'path';
+import { basename, join } from 'path';
 
 function titleCase(s) {
   return s
@@ -72,3 +72,39 @@ export async function runPrompts() {
     initGit,
   };
 }
+
+// Prompts for `bspecs init` (install into the current directory). No folder-name
+// question — the project name defaults to the cwd basename — and no git prompt.
+// Client name is optional, falling back to 'BlueStep Client' on an empty Enter.
+export async function runInitPrompts() {
+  const cwd = process.cwd();
+
+  const clientName = bail(
+    await text({
+      message: 'Client name (optional — press Enter for "BlueStep Client")',
+      placeholder: 'BlueStep Client',
+    })
+  );
+
+  const projectDescription = bail(
+    await text({
+      message: 'Project description (optional — gives Claude project context)',
+      placeholder: 'What does this project do? Press Enter to skip.',
+    })
+  );
+
+  const proceed = bail(
+    await confirm({
+      message: `Install bspecs tooling into ${cwd}?`,
+      initialValue: true,
+    })
+  );
+
+  if (!proceed) return null;
+
+  return {
+    projectName: basename(cwd),
+    clientName: (clientName && clientName.trim()) || 'BlueStep Client',
+    projectDescription: projectDescription || '',
+  };
+}

package/src/scaffold.js

@@ -1,9 +1,9 @@
 import { execSync } from 'child_process';
-import { join, dirname } from 'path';
+import { join, dirname, basename, relative } from 'path';
 import { fileURLToPath } from 'url';
 import { readFileSync, writeFileSync, existsSync } from 'fs';
 import { log } from '@clack/prompts';
-import { ensureDir, copyTemplateTree, applyTemplate, TEMPLATES_DIR, sha256 } from './utils.js';
+import { ensureDir, copyTemplateTree, applyTemplate, writeFile, mergePackageJson, TEMPLATES_DIR, sha256 } from './utils.js';
 import { SYNC_TARGETS } from './sync.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -79,6 +79,11 @@ export async function scaffold(answers) {
     );
   }
 
+  printAuthReminder();
+}
+
+// One-time-per-machine BlueStep credential reminder, shared by `scaffold` and `init`.
+function printAuthReminder() {
   log.info(
     [
       'Next step — set your BlueStep platform credentials (required, once per machine):',
@@ -93,6 +98,102 @@ export async function scaffold(answers) {
   );
 }
 
+// `bspecs init`: install the template tree into the current directory without
+// overwriting anything that already exists (package.json is the one exception —
+// its devDependencies are merged). Writes the lock so `bspecs sync` works after.
+export async function init(answers) {
+  const projectDir = process.cwd();
+
+  const vars = {
+    PROJECT_NAME: answers.projectName,
+    CLIENT_NAME: answers.clientName,
+    PROJECT_DESCRIPTION: answers.projectDescription,
+    SCAFFOLD_DATE: new Date().toISOString().split('T')[0],
+  };
+
+  const collect = { written: [], skipped: [] };
+
+  copyTemplateTree('root', projectDir, vars, {
+    skipExisting: true,
+    collect,
+    exclude: ['package.json.template'],
+  });
+  copyTemplateTree('claude', join(projectDir, '.claude'), vars, {
+    skipExisting: true,
+    collect,
+    makeExecutable: true,
+  });
+  copyTemplateTree('module', join(projectDir, '.claude', 'templates'), vars, {
+    skipExisting: true,
+    collect,
+  });
+
+  const pkgStatus = handlePackageJson(projectDir, vars, collect);
+
+  writeBspecsLock(projectDir, vars);
+
+  log.success('Tooling installed.');
+
+  checkPrettierOnPath();
+  installDependencies(basename(projectDir), projectDir);
+  printAuthReminder();
+
+  reportInstall(projectDir, collect, pkgStatus);
+
+  return { collect, pkgStatus };
+}
+
+// End-of-`init` summary. Lists every file left untouched because it already
+// existed, with guidance to rename/move and re-run for the pristine version.
+function reportInstall(projectDir, collect, pkgStatus) {
+  const parts = [`${collect.written.length} added`];
+  if (pkgStatus === 'merged') parts.push('1 merged (package.json)');
+  parts.push(`${collect.skipped.length} skipped`);
+  log.info(`Install summary: ${parts.join(', ')}.`);
+
+  if (collect.skipped.length > 0) {
+    const list = collect.skipped.map((p) => '  ' + relative(projectDir, p)).join('\n');
+    log.warn(
+      'These files already existed and were left untouched:\n' +
+        list +
+        '\n\nTo install the bspecs version of any of them, rename or move your local copy and run `bspecs init` again.'
+    );
+  }
+}
+
+// package.json is the one file `init` may modify: if absent we write the template;
+// if present we merge in the missing b6p-cli devDependency (mergePackageJson fails
+// soft on malformed JSON). Returns 'written' | 'merged' | 'unchanged' | 'merge-failed'.
+function handlePackageJson(projectDir, vars, collect) {
+  const dest = join(projectDir, 'package.json');
+  const rendered = applyTemplate(
+    readFileSync(join(TEMPLATES_DIR, 'root', 'package.json.template'), 'utf8'),
+    vars
+  );
+
+  if (!existsSync(dest)) {
+    writeFile(dest, rendered);
+    collect.written.push(dest);
+    return 'written';
+  }
+
+  const existing = readFileSync(dest, 'utf8');
+  const merged = mergePackageJson(existing, rendered);
+  if (merged === null) {
+    log.warn(
+      'Existing package.json is not valid JSON — left untouched. Add the b6p CLI by hand:\n' +
+        '    "devDependencies": { "@bluestep-systems/b6p-cli": "^0.1.0" }'
+    );
+    collect.skipped.push(dest);
+    return 'merge-failed';
+  }
+  if (merged !== existing) {
+    writeFile(dest, merged);
+    return 'merged';
+  }
+  return 'unchanged';
+}
+
 // Detect whether the freshly created project directory sits inside an existing
 // git repository (a parent has a .git). Running `git init` here would nest a
 // repo inside another, which surprises users and breaks the implementer agent's

package/src/utils.js

@@ -1,6 +1,6 @@
 import { mkdirSync, writeFileSync, readFileSync, existsSync, chmodSync, readdirSync, statSync } from 'fs';
 import { createHash } from 'node:crypto';
-import { dirname, join } from 'path';
+import { dirname, join, relative } from 'path';
 import { fileURLToPath } from 'url';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -25,11 +25,22 @@ export function readTemplate(relativePath) {
   return readFileSync(join(TEMPLATES_DIR, relativePath), 'utf8');
 }
 
+// Extra opts (all default off, so plain calls overwrite everything as before):
+// skipExisting leaves existing dest files untouched (bspecs init); collect is a
+// { written, skipped } accumulator of absolute paths; exclude lists source-relative
+// paths (forward-slashed) to omit so the caller can handle them separately.
 export function copyTemplateTree(srcRel, destAbs, vars, opts = {}) {
-  const { makeExecutable = false, stripTemplateExt = true } = opts;
+  const {
+    makeExecutable = false,
+    stripTemplateExt = true,
+    skipExisting = false,
+    collect = null,
+    exclude = [],
+  } = opts;
   const srcAbs = join(TEMPLATES_DIR, srcRel);
   if (!existsSync(srcAbs)) return;
-  walk(srcAbs, srcAbs, destAbs, vars, { makeExecutable, stripTemplateExt });
+  const skip = new Set(exclude);
+  walk(srcAbs, srcAbs, destAbs, vars, { makeExecutable, stripTemplateExt, skipExisting, collect, skip });
 }
 
 function walk(rootSrc, src, dest, vars, opts) {
@@ -39,16 +50,26 @@ function walk(rootSrc, src, dest, vars, opts) {
     if (stats.isDirectory()) {
       walk(rootSrc, srcEntry, join(dest, entry), vars, opts);
     } else {
+      const srcRelPath = relative(rootSrc, srcEntry).split('\\').join('/');
+      if (opts.skip.has(srcRelPath)) continue;
+
       const targetName = opts.stripTemplateExt && entry.endsWith('.template')
         ? entry.slice(0, -'.template'.length)
         : entry;
       const destFile = join(dest, targetName);
+
+      if (opts.skipExisting && existsSync(destFile)) {
+        if (opts.collect) opts.collect.skipped.push(destFile);
+        continue;
+      }
+
       const raw = readFileSync(srcEntry, 'utf8');
       const rendered = applyTemplate(raw, vars);
       writeFile(destFile, rendered);
       if (opts.makeExecutable && destFile.endsWith('.sh')) {
         try { chmodSync(destFile, 0o755); } catch { /* Windows can't chmod, ignore */ }
       }
+      if (opts.collect) opts.collect.written.push(destFile);
     }
   }
 }
@@ -93,3 +114,32 @@ export function exists(path) {
 export function sha256(str) {
   return createHash('sha256').update(str, 'utf8').digest('hex');
 }
+
+// Add only-missing template devDependencies and the `b6p` script into an existing
+// package.json (bspecs init); existing values are never changed. Returns merged
+// JSON text, or null if the existing content isn't valid JSON (caller fails soft).
+export function mergePackageJson(existingContent, templateContent) {
+  let existing;
+  try {
+    existing = JSON.parse(existingContent);
+  } catch {
+    return null;
+  }
+  const template = JSON.parse(templateContent);
+
+  const tplDeps = template.devDependencies || {};
+  if (Object.keys(tplDeps).length > 0) {
+    existing.devDependencies = existing.devDependencies || {};
+    for (const [name, version] of Object.entries(tplDeps)) {
+      if (!(name in existing.devDependencies)) existing.devDependencies[name] = version;
+    }
+  }
+
+  const tplScripts = template.scripts || {};
+  if ('b6p' in tplScripts) {
+    existing.scripts = existing.scripts || {};
+    if (!('b6p' in existing.scripts)) existing.scripts.b6p = tplScripts.b6p;
+  }
+
+  return JSON.stringify(existing, null, 2) + '\n';
+}

package/templates/claude/instructions/b6p-platform.md.template

@@ -1,6 +1,5 @@
 ---
 description: BlueStep Platform overview — architecture (Relate/Connect/Manage/BsJs), the b6p CLI, sync, and component lifecycle. Read when orienting on the platform, working with the b6p CLI, or troubleshooting pull/push sync.
-applyTo: "**/.b6p_metadata.json"
 ---
 
 # B6P Platform Workflow
@@ -14,7 +13,7 @@ Platform orientation plus the workflow reference for sync, lifecycle, and the b6
 - [Data hierarchy](#data-hierarchy)
 - [Script types](#script-types)
 - [b6p CLI workflow](#b6p-cli-workflow)
-- [`.b6p_metadata.json`](#b6p_metadatajson)
+- [Sync metadata](#sync-metadata)
 - [Files Claude must never edit](#files-claude-must-never-edit)
 - [Imports — verification flow](#imports--verification-flow)
 - [When the CLI fails](#when-the-cli-fails)
@@ -113,27 +112,27 @@ A successful first pull:
 - Creates the `U######/` folder (if not present) and the `<ComponentName>/` subfolder under it
 - Populates `draft/scripts/`, `draft/info/`, and (in older modules) `draft/objects/`
 - Populates `declarations/` with the platform-generated `.d.ts` files, including `declarations/index.d.ts` (field/query/form declarations)
-- Writes `.b6p_metadata.json` at the component root for future pulls/pushes
+- Records the component's sync metadata (WebDAV id, file hashes, script key) so future pulls/pushes can resolve it
 
 Subsequent pulls verify per-file integrity and only rewrite files whose content changed.
 
 ### Push a component
 
-The cleanest way to push an already-pulled component is `--file`, which lets the CLI derive the destination DAV URL from local `.b6p_metadata.json`:
+The cleanest way to push an already-pulled component is `--file`, which lets the CLI derive the destination DAV URL from the recorded sync metadata:
 
 ```
 npx b6p push --file "U######/<Component>/draft/scripts/app.ts"
 ```
 
-Any file inside the component works as the `--file` argument; the CLI walks up to find `.b6p_metadata.json`. Same per-file integrity check applies — only changed files are uploaded. The platform compiles after receiving the push.
+Any file inside the component works as the `--file` argument; the CLI walks up to find the component root and looks up its recorded sync metadata. Same per-file integrity check applies — only changed files are uploaded. The platform compiles after receiving the push.
 
 ### Fallback: VS Code extension
 
 If the `b6p` CLI fails (network, lock, auth), the VS Code **b6p extension** is an equivalent fallback for pull/push operations.
 
-## `.b6p_metadata.json`
+## Sync metadata
 
-Auto-managed by the CLI. Tracks WebDAV IDs, last-pull / last-push timestamps, file hashes, and script keys. **Never edit manually.**
+Auto-managed by the CLI and stored internally (no longer a `.b6p_metadata.json` file in the workspace; legacy files are migrated on first run). Tracks WebDAV IDs, last-pull / last-push timestamps, file hashes, and script keys, so pull/push/audit can resolve each component. Not something you edit.
 
 ## Files Claude must never edit
 
@@ -173,7 +172,7 @@ Common causes:
 Fallbacks:
 
 1. The VS Code b6p extension provides the same pull/push operations through the editor UI.
-2. As a last resort, the platform UI lets you download/upload component files manually — but losing `.b6p_metadata.json` consistency makes future CLI sync fragile.
+2. As a last resort, the platform UI lets you download/upload component files manually — but manual uploads bypass the CLI's recorded sync metadata, making future CLI sync fragile.
 
 ## When `B.commit()` is required
 

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

@@ -327,7 +327,7 @@ Each project root has a `tsconfig.json`. BlueStep projects run with **`strict: f
 }
 ```
 
-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`.
+Do not run `tsc` locally — the platform compiles on push (a hook blocks local `tsc`).
 
 ### Graal compatibility (server-side)
 

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

@@ -47,19 +47,15 @@ Entries read: `path — what it covers. Load when <trigger>.` Match the trigger
 
 ## conventions/ — build, deploy, and workflow directives
 
-- [conventions/always-snapshot.md](conventions/always-snapshot.md) — pull/push/snapshot workflow: use the CLI scripts (never fetch manually) and snapshot after every change via push → pull → snapshot. Load when syncing a component or unsure of the snapshot routine.
 - [conventions/blueiq-no-ai-branding.md](conventions/blueiq-no-ai-branding.md) — never put "AI" in front-facing BlueIQ text; the brand is always "BlueIQ". Load when writing user-visible BlueIQ copy.
 - [conventions/date-format.md](conventions/date-format.md) — `addSearch` needs `MM/DD/YYYY` for date fields; `YYYY/MM/DD` passes validation but silently fails to filter, and raw Java `LocalDate` objects also fail. Load when filtering a query by a date field.
 - [conventions/endpoint-approach.md](conventions/endpoint-approach.md) — research-first: gather API docs, read type declarations, and study existing examples before writing an endpoint. Load when starting a new endpoint.
 - [conventions/formula-patterns.md](conventions/formula-patterns.md) — correct BSJS formula patterns: form access, field reads/writes, HTTP, error handling, `B.*` utilities, DocumentLinkField. Load when writing a Formula or Post-Save script.
 - [conventions/no-global-dollar.md](conventions/no-global-dollar.md) — never define a global `$` in MergeReport scripts; pages use jQuery and you will silently break Save and all page interactivity. Load when adding client JS to a MergeReport.
-- [conventions/push-inner-draft.md](conventions/push-inner-draft.md) — pass the inner `draft/` folder (not the component root) to `push.js`, or files land in a `draft/draft/*` dead zone. Load when pushing a component with `push.js`.
 - [conventions/separate-files.md](conventions/separate-files.md) — don't pile CSS/HTML/JS into `app.ts`; use the `styles.css`/`index.html`/`script.ts` files the pulled folder already has. Load when structuring MergeReport files.
 - [conventions/single-script.md](conventions/single-script.md) — the server-side build compiles only root `static/script.ts` to `.build/script.js`; subdirectory `.ts` files are NOT compiled. Load when splitting client scripts into multiple files.
-- [conventions/snapshot-integrity.md](conventions/snapshot-integrity.md) — snapshots register cleanly only when `push.js` sends locally-compiled `.build/*` alongside source, otherwise a manual re-snapshot is needed. Load when a push leaves the snapshot needing manual re-registration.
 - [conventions/top-level-const-tdz.md](conventions/top-level-const-tdz.md) — endpoint/MergeReport scripts run top-down; declare every `const`/`let` above the entry `try` block or they are in TDZ when the handler fires. Load when ordering declarations in an endpoint or MergeReport.
 - [conventions/ts-in-template-literal.md](conventions/ts-in-template-literal.md) — the inline `<script>` inside a `B.out` template literal must be plain JS; any TypeScript syntax ships verbatim to the browser and breaks parsing. Load when emitting client JS through a `B.out` string.
-- [conventions/tsc-rootdir.md](conventions/tsc-rootdir.md) — compile endpoints with `--rootDir .` so output mirrors `scripts/app.ts` → `.build/scripts/app.js`; `--rootDir ./scripts` emits to `.build/app.js`, which the runtime ignores. Load when configuring the local TypeScript build for an endpoint.
 
 ## gotchas/ — sharp edges
 

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

@@ -15,4 +15,4 @@ A server-side BSJS merge report CAN access and parse an uploaded CSV at runtime.
 
 **Gotchas:** strip UTF-8 BOM (`` corrupts first header key on Excel/QuickBooks exports); handle `\r\n`; sanitize currency (`$`, thousands commas, `(123)` negatives) before parseFloat; pass charset if Windows-1252; streaming `.forReader()` avoids buffering huge files and sidesteps the "code 0 but real content" issue seen with `B.io.fromInputStream`.
 
-**Relevance:** unlocks the behavioral scorecard placeholder metrics that aren't in relational data — MRR, Monthly Profitability, Avg Contribution Margin (QuickBooks exports), NPS (survey results). Pattern: upload CSV to a Document field on a settings record; in app.ts `field.forReader(r => B.csv(r).toListOfObjects())`; the metric's Verify table can show the parsed rows. Docs: ~/.bluestep/docs/classes/CSV.md, DocumentLinkField.md, Document.md, Folder.md, B.Bluestep.IO.md.
+**Relevance:** unlocks the behavioral scorecard placeholder metrics that aren't in relational data — MRR, Monthly Profitability, Avg Contribution Margin (QuickBooks exports), NPS (survey results). Pattern: upload CSV to a Document field on a settings record; in app.ts `field.forReader(r => B.csv(r).toListOfObjects())`; the metric's Verify table can show the parsed rows.

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

@@ -11,5 +11,5 @@ The alias is set per-endpoint in BlueStep admin and is not derivable from the sc
 
 **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.
+- The DAV `url` the CLI recorded for the component 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/file-execution.md.template

@@ -79,7 +79,7 @@ The legacy `objects/imports.ts` `.require()` registration did this in code; it i
 
 ## 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.
+The b6p CLI tracks 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 — in its own internal store (no longer a `.b6p_metadata.json` file in the workspace). The `draft/` directory holds the working version of the code; the `.build/` directories hold the compiled JavaScript output from the TypeScript source.
 
 ## Common Mistakes
 

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

@@ -20,6 +20,6 @@ The recurring **"merge report + memo field JSON hack"** — how Brandon and I re
 - 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).
+- File structure: [separate files](../conventions/separate-files.md). For sync, use the `/b6p-push` and `/b6p-pull` skills (`npx b6p`).
 
 **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/skills/b6p-audit/SKILL.md

@@ -44,7 +44,7 @@ test -f ~/.b6p/secrets.enc && echo OK
 
 If `$ARGUMENTS` contains a component path (e.g. `U######/Combined Scheduler`), use it. If empty, ask the user which component to audit.
 
-Confirm `.b6p_metadata.json` exists at the component root — without it, audit cannot determine the destination URL.
+Confirm the component was pulled with `b6p` (so its sync metadata is recorded) — without that, audit cannot determine the destination URL. If it was never pulled here, pull it first.
 
 ### 2. Run the audit
 

package/templates/claude/skills/b6p-pull/SKILL.md

@@ -16,7 +16,7 @@ b6p pull [options] <formula-url>
 
 The user copies the DAV URL from the component's page in the BlueStep platform UI. You cannot discover or infer it. There is no fallback that takes a name.
 
-A first pull creates the `U######/<ComponentName>/` folder (creating the U-folder if it does not exist) and populates `declarations/`, `draft/`, and `.b6p_metadata.json`.
+A first pull creates the `U######/<ComponentName>/` folder (creating the U-folder if it does not exist), populates `declarations/` and `draft/`, and records the component's sync metadata.
 
 ## How to invoke `b6p`
 
@@ -49,7 +49,7 @@ test -f ~/.b6p/secrets.enc && echo OK
 - If `$ARGUMENTS` looks like a URL (starts with `http://` or `https://`), use it.
 - If `$ARGUMENTS` is empty or looks like a display name (no scheme), STOP and ask the user:
   > I need the **DAV URL** of the component, not its name. Copy it from the component's page in the BlueStep platform UI and paste it here.
-- Do NOT guess the URL. Do NOT try to derive it from `.b6p_metadata.json` of other components.
+- Do NOT guess the URL. Do NOT try to derive it from another component's recorded metadata.
 
 ### 2. Run the pull
 
@@ -66,7 +66,6 @@ Capture the output — it prints the local path where the component landed.
 Parse the CLI output, or scan for the most recently modified `U######/<Name>/` directory under the project root. Confirm:
 
 - `declarations/` is populated
-- `.b6p_metadata.json` exists at the component root
 - `draft/info/metadata.json` and `draft/info/config.json` exist
 - `draft/scripts/app.ts` (or whatever `config.json:main` points at) exists
 

package/templates/claude/skills/b6p-push/SKILL.md

@@ -8,13 +8,13 @@ allowed-tools: Bash(npx b6p *) Bash(git*) Bash(test -f *)
 
 ## How `b6p push` actually works
 
-`b6p push` is most reliably driven by `--file <path>`, which tells the CLI to derive the destination DAV URL from the local file's metadata (via `.b6p_metadata.json`):
+`b6p push` is most reliably driven by `--file <path>`, which tells the CLI to derive the destination DAV URL from the sync metadata it recorded for that component when it was pulled:
 
 ```
 b6p push --file <path-inside-component>
 ```
 
-Any file inside the component works as the `--file` argument; the CLI walks up to find `.b6p_metadata.json`.
+Any file inside the component works as the `--file` argument; the CLI walks up to find the component root and looks up its recorded sync metadata.
 
 ## How to invoke `b6p`
 
@@ -44,7 +44,7 @@ If `$ARGUMENTS` contains a component path (relative to the project root), use it
 
 - Run `git status` to surface what changed and flag anything unexpected.
 - Briefly summarise the diff scope: "X files changed in `U######/<Component>/draft/`".
-- Confirm `.b6p_metadata.json` exists inside the component — without it, `--file` cannot derive the destination URL.
+- Confirm the component was pulled with `b6p` (so its sync metadata is recorded) — `--file` resolves the destination URL from that metadata. If the component was never pulled here, pull it first.
 
 ### 3. Confirm with the user
 

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

@@ -1,25 +0,0 @@
----
-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/push-inner-draft.md.template

@@ -1,21 +0,0 @@
----
-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/snapshot-integrity.md.template

@@ -1,23 +0,0 @@
----
-description: "BlueStep snapshots register cleanly only when push.js sends locally-compiled .build/* alongside source — otherwise the user has to re-snapshot manually"
----
-
-For BlueStep snapshots to register cleanly in the web UI without a manual re-snapshot, include the locally-compiled `.build/*.js` (and `.build/scripts/*.js`) files alongside the source `.ts`/`.html`/`.css` in the `saveState` that `push.js`'s `recordHistory` mutation records.
-
-**Why:** `push.js`'s `buildSaveState(localFolder, files)` reads files from `walkDir`, which respects `SKIP_DIRS`. If `.build` is in `SKIP_DIRS`, the `saveState` is source-only. BlueStep's snapshot UI compares the recorded `saveState` against the live filesystem (which has `.build/*.js` from server-side compilation), sees a mismatch, and flags the snapshot as incomplete — surfaced to the user as the familiar "go re-snapshot manually" pattern. When `.build/` IS included, source ↔ compiled match, the snapshot finalizes cleanly, and there is no need to touch the BlueStep UI to finish the operation.
-
-**How to apply:**
-
-- `~/.bluestep/push.js`'s `SKIP_DIRS` MUST be `new Set(['declarations', 'info'])` — NOT `new Set(['.build', 'declarations', 'info'])`. (`declarations/` and `info/` are genuinely server-generated and should stay excluded; `.build/` is locally compiled and should be included.) Changed 2026-05-01.
-- ALWAYS run `tsc` locally in each folder containing a `tsconfig.json` BEFORE invoking `push.js --snapshot`. Multi-tsconfig projects (e.g. root + `static/`) need a separate `tsc` per directory. Skipping the compile uploads a stale `.build/` that doesn't reflect current source, and the runtime silently diverges from what the snapshot's `.ts` says.
-- A second, independent reason to compile locally: BlueStep's server-side TS recompile after a `.ts` push has been observed to be unreliable. Pushing the locally-compiled `.build/*.js` directly bypasses any server-side compile lag or failure (the `export {};` `SyntaxError` saga from 2026-05-01 was caused by exactly this).
-- Verified empirically across many edits to `alpineacademy/1513841` and `1513859` (chatbot project) on 2026-05-01: with `.build/` included, every snapshot finalized cleanly in the BlueStep UI.
-
-**The pattern in shorthand:**
-
-1. Edit source.
-2. `cd <folder-with-tsconfig> && tsc` (repeat for each tsconfig in the project).
-3. `node ~/.bluestep/push.js --snapshot --comment "..." <folder>`.
-4. Done. No BlueStep UI interaction needed.
-
-Related: [always snapshot](always-snapshot.md), [tsc rootdir](tsc-rootdir.md), [push inner draft](push-inner-draft.md).

package/templates/claude/instructions/conventions/tsc-rootdir.md.template

@@ -1,17 +0,0 @@
----
-description: "Compile BlueStep endpoints with --rootDir . so output mirrors scripts/app.ts → .build/scripts/app.js; --rootDir ./scripts emits to .build/app.js which the runtime ignores"
----
-
-When compiling a BlueStep endpoint locally, use:
-
-```
-tsc --rootDir . --ignoreDeprecations 6.0 --skipLibCheck
-```
-
-NOT `tsc --rootDir ./scripts ...`.
-
-**Why:** The BlueStep runtime loads `.build/scripts/app.js` (mirroring `scripts/app.ts`). With `--rootDir ./scripts`, tsc emits to `.build/app.js` (one level too high). The push succeeds and the snapshot succeeds, but the runtime keeps serving the old `.build/scripts/app.js`. Symptom: code edits appear to have no effect after pushing and snapshotting — silent staleness, no error, just wrong output.
-
-**How to apply:** Always run tsc from the `draft/` folder with `--rootDir .` (or omit `rootDir` entirely — tsc infers it from `tsconfig`). After compile, verify `.build/scripts/app.js` was updated, not `.build/app.js`. If a stale `.build/app.js` orphan exists from a past mistake, it can be left in place — the runtime ignores it.
-
-Confirmed on alpineacademy `/b/greatHair`, May 2026.