@slats/claude-assets-sync 0.2.0 → 0.3.0

package/dist/commands/runCli/utils/resolvePackage.mjs

@@ -0,0 +1,74 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import { dirname, resolve } from 'node:path';
+import { logger } from '../../../utils/logger.mjs';
+
+async function resolvePackage(name, options = {}) {
+    const pkgJsonPath = resolvePackageJsonPath(name);
+    if (!pkgJsonPath) {
+        logger.error(`cannot resolve package "${name}". Install it in the current project or pass the correct name.`);
+        process.exit(2);
+    }
+    const packageRoot = dirname(pkgJsonPath);
+    const raw = await readFile(pkgJsonPath, 'utf-8');
+    const pkg = JSON.parse(raw);
+    if (typeof pkg.name !== 'string' || typeof pkg.version !== 'string') {
+        if (options.skipMissingAsset) {
+            logger.warn(`"${name}" package.json is missing a string "name" or "version" — skipping.`);
+            return null;
+        }
+        logger.error(`${pkgJsonPath} must define string "name" and "version".`);
+        process.exit(2);
+    }
+    const assetPath = pkg.claude?.assetPath;
+    if (typeof assetPath !== 'string' || assetPath.length === 0) {
+        if (options.skipMissingAsset) {
+            logger.warn(`"${name}" is missing "claude.assetPath" — skipping (the package does not ship Claude assets).`);
+            return null;
+        }
+        logger.error(`"${name}" is missing "claude.assetPath" in its package.json — the package does not ship Claude assets.`);
+        process.exit(2);
+    }
+    return {
+        packageRoot,
+        packageName: pkg.name,
+        packageVersion: pkg.version,
+        assetPath,
+    };
+}
+function resolvePackageJsonPath(name) {
+    const require = createRequire(import.meta.url);
+    try {
+        return require.resolve(`${name}/package.json`);
+    }
+    catch (err) {
+        const code = err?.code;
+        if (code !== 'ERR_PACKAGE_PATH_NOT_EXPORTED')
+            return null;
+    }
+    let mainEntry;
+    try {
+        mainEntry = require.resolve(name);
+    }
+    catch {
+        return null;
+    }
+    let dir = dirname(mainEntry);
+    while (dir && dir !== dirname(dir)) {
+        const candidate = resolve(dir, 'package.json');
+        if (existsSync(candidate)) {
+            try {
+                const pkg = JSON.parse(readFileSync(candidate, 'utf-8'));
+                if (pkg.name === name)
+                    return candidate;
+            }
+            catch {
+            }
+        }
+        dir = dirname(dir);
+    }
+    return null;
+}
+
+export { resolvePackage };

package/dist/commands/runCli/utils/resolveScopeAlias.cjs

@@ -0,0 +1,69 @@
+'use strict';
+
+var node_fs = require('node:fs');
+var promises = require('node:fs/promises');
+var node_path = require('node:path');
+var logger = require('../../../utils/logger.cjs');
+var resolvePackage = require('./resolvePackage.cjs');
+
+async function resolveScopeAlias(scope, rootCwd) {
+    const packagesRoot = findPackagesRoot(rootCwd);
+    if (!packagesRoot) {
+        logger.logger.error(`cannot locate a monorepo root with a "packages/" directory starting from "${rootCwd}". Scope alias "@${scope}" requires a workspace root.`);
+        process.exit(2);
+    }
+    const scopeDir = node_path.join(packagesRoot, 'packages', scope);
+    let entries;
+    try {
+        entries = await promises.readdir(scopeDir);
+    }
+    catch {
+        logger.logger.error(`scope alias "@${scope}" has no matching directory at ${scopeDir}.`);
+        process.exit(2);
+    }
+    const matchedNames = [];
+    const expectedPrefix = `@${scope}/`;
+    for (const entry of entries) {
+        const pkgJsonPath = node_path.join(scopeDir, entry, 'package.json');
+        if (!node_fs.existsSync(pkgJsonPath))
+            continue;
+        let parsed;
+        try {
+            const raw = await promises.readFile(pkgJsonPath, 'utf-8');
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            continue;
+        }
+        if (typeof parsed.name === 'string' &&
+            parsed.name.startsWith(expectedPrefix) &&
+            parsed.name.length > expectedPrefix.length) {
+            matchedNames.push(parsed.name);
+        }
+    }
+    if (matchedNames.length === 0) {
+        logger.logger.warn(`scope alias "@${scope}" matched no workspace packages under ${scopeDir}.`);
+        return [];
+    }
+    const resolved = [];
+    for (const name of matchedNames) {
+        const meta = await resolvePackage.resolvePackage(name, { skipMissingAsset: true });
+        if (meta)
+            resolved.push(meta);
+    }
+    return resolved;
+}
+function findPackagesRoot(start) {
+    let cur = node_path.resolve(start);
+    while (true) {
+        if (node_fs.existsSync(node_path.join(cur, 'package.json')) && node_fs.existsSync(node_path.join(cur, 'packages'))) {
+            return cur;
+        }
+        const parent = node_path.dirname(cur);
+        if (parent === cur)
+            return null;
+        cur = parent;
+    }
+}
+
+exports.resolveScopeAlias = resolveScopeAlias;

package/dist/commands/runCli/utils/resolveScopeAlias.d.ts

@@ -0,0 +1,2 @@
+import { type ResolvedMetadata } from './resolvePackage.js';
+export declare function resolveScopeAlias(scope: string, rootCwd: string): Promise<ResolvedMetadata[]>;

package/dist/commands/runCli/utils/resolveScopeAlias.mjs

@@ -0,0 +1,67 @@
+import { existsSync } from 'node:fs';
+import { readdir, readFile } from 'node:fs/promises';
+import { join, resolve, dirname } from 'node:path';
+import { logger } from '../../../utils/logger.mjs';
+import { resolvePackage } from './resolvePackage.mjs';
+
+async function resolveScopeAlias(scope, rootCwd) {
+    const packagesRoot = findPackagesRoot(rootCwd);
+    if (!packagesRoot) {
+        logger.error(`cannot locate a monorepo root with a "packages/" directory starting from "${rootCwd}". Scope alias "@${scope}" requires a workspace root.`);
+        process.exit(2);
+    }
+    const scopeDir = join(packagesRoot, 'packages', scope);
+    let entries;
+    try {
+        entries = await readdir(scopeDir);
+    }
+    catch {
+        logger.error(`scope alias "@${scope}" has no matching directory at ${scopeDir}.`);
+        process.exit(2);
+    }
+    const matchedNames = [];
+    const expectedPrefix = `@${scope}/`;
+    for (const entry of entries) {
+        const pkgJsonPath = join(scopeDir, entry, 'package.json');
+        if (!existsSync(pkgJsonPath))
+            continue;
+        let parsed;
+        try {
+            const raw = await readFile(pkgJsonPath, 'utf-8');
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            continue;
+        }
+        if (typeof parsed.name === 'string' &&
+            parsed.name.startsWith(expectedPrefix) &&
+            parsed.name.length > expectedPrefix.length) {
+            matchedNames.push(parsed.name);
+        }
+    }
+    if (matchedNames.length === 0) {
+        logger.warn(`scope alias "@${scope}" matched no workspace packages under ${scopeDir}.`);
+        return [];
+    }
+    const resolved = [];
+    for (const name of matchedNames) {
+        const meta = await resolvePackage(name, { skipMissingAsset: true });
+        if (meta)
+            resolved.push(meta);
+    }
+    return resolved;
+}
+function findPackagesRoot(start) {
+    let cur = resolve(start);
+    while (true) {
+        if (existsSync(join(cur, 'package.json')) && existsSync(join(cur, 'packages'))) {
+            return cur;
+        }
+        const parent = dirname(cur);
+        if (parent === cur)
+            return null;
+        cur = parent;
+    }
+}
+
+export { resolveScopeAlias };

package/dist/commands/runCli/utils/resolveTargets.cjs

@@ -0,0 +1,40 @@
+'use strict';
+
+var logger = require('../../../utils/logger.cjs');
+var classifyTarget = require('./classifyTarget.cjs');
+var resolvePackage = require('./resolvePackage.cjs');
+var resolveScopeAlias = require('./resolveScopeAlias.cjs');
+
+async function resolveTargets(targets, rootCwd) {
+    if (targets.length === 0)
+        return [];
+    const isSingleTarget = targets.length === 1;
+    const seen = new Set();
+    const results = [];
+    for (const target of targets) {
+        const classification = classifyTarget.classifyTarget(target);
+        if (classification.kind === 'invalid') {
+            logger.logger.error(classification.reason);
+            process.exit(2);
+        }
+        let candidates;
+        if (classification.kind === 'scope') {
+            candidates = await resolveScopeAlias.resolveScopeAlias(classification.scope, rootCwd);
+        }
+        else {
+            const meta = await resolvePackage.resolvePackage(classification.name, {
+                skipMissingAsset: !isSingleTarget,
+            });
+            candidates = meta ? [meta] : [];
+        }
+        for (const meta of candidates) {
+            if (!seen.has(meta.packageName)) {
+                seen.add(meta.packageName);
+                results.push(meta);
+            }
+        }
+    }
+    return results;
+}
+
+exports.resolveTargets = resolveTargets;

package/dist/commands/runCli/utils/resolveTargets.d.ts

@@ -0,0 +1,15 @@
+import { type ResolvedMetadata } from './resolvePackage.js';
+/**
+ * Classify each `--package` value, resolve them all, and dedupe the
+ * result by `packageName`.
+ *
+ * - `@<scope>` values enumerate through `resolveScopeAlias` (soft skip
+ *   when a workspace package lacks `claude.assetPath`).
+ * - `@<scope>/<name>` and `<name>` values go through `resolvePackage`.
+ *   When there is a single `--package` value, the call is strict
+ *   (asset-missing → exit 2); otherwise asset-missing is a soft skip
+ *   so the rest of the batch can proceed.
+ *
+ * Invalid `--package` values exit with code 2 before any filesystem IO.
+ */
+export declare function resolveTargets(targets: readonly string[], rootCwd: string): Promise<ResolvedMetadata[]>;

package/dist/commands/runCli/utils/resolveTargets.mjs

@@ -0,0 +1,38 @@
+import { logger } from '../../../utils/logger.mjs';
+import { classifyTarget } from './classifyTarget.mjs';
+import { resolvePackage } from './resolvePackage.mjs';
+import { resolveScopeAlias } from './resolveScopeAlias.mjs';
+
+async function resolveTargets(targets, rootCwd) {
+    if (targets.length === 0)
+        return [];
+    const isSingleTarget = targets.length === 1;
+    const seen = new Set();
+    const results = [];
+    for (const target of targets) {
+        const classification = classifyTarget(target);
+        if (classification.kind === 'invalid') {
+            logger.error(classification.reason);
+            process.exit(2);
+        }
+        let candidates;
+        if (classification.kind === 'scope') {
+            candidates = await resolveScopeAlias(classification.scope, rootCwd);
+        }
+        else {
+            const meta = await resolvePackage(classification.name, {
+                skipMissingAsset: !isSingleTarget,
+            });
+            candidates = meta ? [meta] : [];
+        }
+        for (const meta of candidates) {
+            if (!seen.has(meta.packageName)) {
+                seen.add(meta.packageName);
+                results.push(meta);
+            }
+        }
+    }
+    return results;
+}
+
+export { resolveTargets };

package/dist/commands/runCli/utils/runInject.cjs

@@ -6,31 +6,47 @@ var logger = require('../../../utils/logger.cjs');
 var injectOne = require('./injectOne.cjs');
 var resolveScopeFlag = require('./resolveScopeFlag.cjs');
 
-async function runInject(flags, options) {
-    if (!options.packageRoot ||
-        !options.packageName ||
-        !options.packageVersion ||
-        !options.assetPath) {
-        logger.logger.error('runCli requires { packageRoot, packageName, packageVersion, assetPath }.');
-        process.exit(2);
+async function runInject(flags, metadataList) {
+    if (metadataList.length === 0)
+        return;
+    for (const metadata of metadataList) {
+        if (!node_path.isAbsolute(metadata.packageRoot)) {
+            logger.logger.error(`packageRoot must be an absolute path; received: ${metadata.packageRoot}`);
+            process.exit(2);
+        }
     }
-    if (!node_path.isAbsolute(options.packageRoot)) {
-        logger.logger.error(`packageRoot must be an absolute path; received: ${options.packageRoot}`);
-        process.exit(2);
-    }
-    const assetRoot = node_path.resolve(options.packageRoot, options.assetPath);
-    const hashesPath = node_path.join(options.packageRoot, 'dist', 'claude-hashes.json');
-    const hashesPresent = await promises.stat(hashesPath).then(() => true, () => false);
-    const target = {
-        name: options.packageName,
-        version: options.packageVersion,
-        packageRoot: options.packageRoot,
-        assetRoot,
-        hashesPresent,
-    };
     const originCwd = flags.root ?? process.cwd();
     const scope = await resolveScopeFlag.resolveScopeFlag(flags.scope);
-    await injectOne.injectOne(target, scope, flags, originCwd);
+    const fatalOnError = metadataList.length === 1;
+    let failureCount = 0;
+    for (const metadata of metadataList) {
+        const assetRoot = node_path.resolve(metadata.packageRoot, metadata.assetPath);
+        const hashesPath = node_path.join(metadata.packageRoot, 'dist', 'claude-hashes.json');
+        const hashesPresent = await promises.stat(hashesPath).then(() => true, () => false);
+        const target = {
+            name: metadata.packageName,
+            version: metadata.packageVersion,
+            packageRoot: metadata.packageRoot,
+            assetRoot,
+            hashesPresent,
+        };
+        let exitCode;
+        try {
+            exitCode = await injectOne.injectOne(target, scope, flags, originCwd);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            logger.logger.error(`${target.name}: ${msg}`);
+            exitCode = 1;
+        }
+        if (exitCode !== 0) {
+            if (fatalOnError)
+                process.exit(exitCode);
+            failureCount += 1;
+        }
+    }
+    if (failureCount > 0)
+        process.exit(1);
 }
 
 exports.runInject = runInject;

package/dist/commands/runCli/utils/runInject.d.ts

@@ -1,2 +1,3 @@
-import type { DefaultFlags, RunCliOptions } from '../type.js';
-export declare function runInject(flags: DefaultFlags, options: RunCliOptions): Promise<void>;
+import type { DefaultFlags } from '../type.js';
+import type { ResolvedMetadata } from './resolvePackage.js';
+export declare function runInject(flags: DefaultFlags, metadataList: readonly ResolvedMetadata[]): Promise<void>;

package/dist/commands/runCli/utils/runInject.mjs

@@ -4,31 +4,47 @@ import { logger } from '../../../utils/logger.mjs';
 import { injectOne } from './injectOne.mjs';
 import { resolveScopeFlag } from './resolveScopeFlag.mjs';
 
-async function runInject(flags, options) {
-    if (!options.packageRoot ||
-        !options.packageName ||
-        !options.packageVersion ||
-        !options.assetPath) {
-        logger.error('runCli requires { packageRoot, packageName, packageVersion, assetPath }.');
-        process.exit(2);
+async function runInject(flags, metadataList) {
+    if (metadataList.length === 0)
+        return;
+    for (const metadata of metadataList) {
+        if (!isAbsolute(metadata.packageRoot)) {
+            logger.error(`packageRoot must be an absolute path; received: ${metadata.packageRoot}`);
+            process.exit(2);
+        }
     }
-    if (!isAbsolute(options.packageRoot)) {
-        logger.error(`packageRoot must be an absolute path; received: ${options.packageRoot}`);
-        process.exit(2);
-    }
-    const assetRoot = resolve(options.packageRoot, options.assetPath);
-    const hashesPath = join(options.packageRoot, 'dist', 'claude-hashes.json');
-    const hashesPresent = await stat(hashesPath).then(() => true, () => false);
-    const target = {
-        name: options.packageName,
-        version: options.packageVersion,
-        packageRoot: options.packageRoot,
-        assetRoot,
-        hashesPresent,
-    };
     const originCwd = flags.root ?? process.cwd();
     const scope = await resolveScopeFlag(flags.scope);
-    await injectOne(target, scope, flags, originCwd);
+    const fatalOnError = metadataList.length === 1;
+    let failureCount = 0;
+    for (const metadata of metadataList) {
+        const assetRoot = resolve(metadata.packageRoot, metadata.assetPath);
+        const hashesPath = join(metadata.packageRoot, 'dist', 'claude-hashes.json');
+        const hashesPresent = await stat(hashesPath).then(() => true, () => false);
+        const target = {
+            name: metadata.packageName,
+            version: metadata.packageVersion,
+            packageRoot: metadata.packageRoot,
+            assetRoot,
+            hashesPresent,
+        };
+        let exitCode;
+        try {
+            exitCode = await injectOne(target, scope, flags, originCwd);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            logger.error(`${target.name}: ${msg}`);
+            exitCode = 1;
+        }
+        if (exitCode !== 0) {
+            if (fatalOnError)
+                process.exit(exitCode);
+            failureCount += 1;
+        }
+    }
+    if (failureCount > 0)
+        process.exit(1);
 }
 
 export { runInject };

package/dist/core/injectDocs/utils/applyAction.cjs

@@ -13,7 +13,7 @@ async function applyAction(action, assetRoot) {
     else if (action.kind === 'delete')
         await promises.unlink(action.dstAbs).catch((error) => {
             if (error?.code !== 'ENOENT') {
-                logger.logger.warn(`[claude-sync] unlink failed: ${action.dstAbs} (${error?.code ?? error})`);
+                logger.logger.warn(`[claude-assets-sync] unlink failed: ${action.dstAbs} (${error?.code ?? error})`);
             }
         });
 }

package/dist/core/injectDocs/utils/applyAction.mjs

@@ -11,7 +11,7 @@ async function applyAction(action, assetRoot) {
     else if (action.kind === 'delete')
         await unlink(action.dstAbs).catch((error) => {
             if (error?.code !== 'ENOENT') {
-                logger.warn(`[claude-sync] unlink failed: ${action.dstAbs} (${error?.code ?? error})`);
+                logger.warn(`[claude-assets-sync] unlink failed: ${action.dstAbs} (${error?.code ?? error})`);
             }
         });
 }

package/dist/index.d.ts

@@ -1,3 +1,3 @@
-export { runCli, type RunCliOptions } from './commands/index.js';
+export { runCli } from './commands/index.js';
 export { HASH_MANIFEST_FILENAME, computeNamespacePrefixes, injectDocs, isInteractive, isValidScope, readHashManifest, resolveScope, type HashManifest, type InjectOptions, type InjectReport, type Scope, type ScopeResolution, } from './core/index.js';
 export type { AssetType } from './utils/types.js';

package/dist/utils/version.cjs

@@ -1,5 +1,5 @@
 'use strict';
 
-const VERSION = '0.2.0';
+const VERSION = '0.3.0';
 
 exports.VERSION = VERSION;

package/dist/utils/version.d.ts

@@ -2,4 +2,4 @@
  * Current package version from package.json
  * Automatically synchronized during build process
  */
-export declare const VERSION = "0.2.0";
+export declare const VERSION = "0.3.0";

package/dist/utils/version.mjs

@@ -1,3 +1,3 @@
-const VERSION = '0.2.0';
+const VERSION = '0.3.0';
 
 export { VERSION };

package/docs/claude/skills/claude-docs-asset-wiring/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: claude-docs-asset-wiring
+description: "Wire a consumer package's docs/claude assets into the @slats/claude-assets-sync engine. Adds package.json.claude.assetPath, points scripts.build:hashes at claude-build-hashes, declares the engine as a dependency, updates CLAUDE.md, and runs the dispatcher smoke test. Idempotent — asks before clobbering."
+user-invocable: true
+disable-model-invocation: true
+argument-hint: <target-package-path>
+---
+
+# claude-docs-asset-wiring
+
+Wire a consumer package's `docs/claude/**` into `@slats/claude-assets-sync`
+so end users can inject those assets via the engine's `inject-claude-settings`
+bin. Reference consumer: `packages/canard/schema-form`.
+
+The engine is single-dispatcher. Consumers do NOT ship their own bin stubs
+— they declare `claude.assetPath` in `package.json` and let the engine's
+`claude-build-hashes` bin regenerate `dist/claude-hashes.json` during
+build. `src/core/**` never reads `package.json`; only the engine's `bin/`
+layer resolves a single explicitly-named target.
+
+**Outcome**
+
+```bash
+npx -p @slats/claude-assets-sync inject-claude-settings \
+  --package=<PACKAGE_NAME> \
+  --scope=user|project [--dry-run] [--force]
+```
+
+## Role
+
+You are a monorepo wiring specialist. Execute the 6 steps below as a
+single, idempotent procedure. On any conflicting existing value — ask
+the user before overwriting. Never clobber silently.
+
+## Knowledge Resources
+
+Consult these files as needed during execution. Do NOT preload everything;
+load on demand.
+
+- `knowledge/reference-files.md` — what the consumer should (and should not) own
+- `knowledge/package-json-patches.md` — every required `package.json` edit, with guard conditions
+- `knowledge/claude-md-template.md` — the `## Claude Docs Injector` section to inject into the target `CLAUDE.md`
+- `knowledge/smoke-tests.md` — E2E 8-path matrix via the engine dispatcher
+- `knowledge/dependency-cruiser.md` — optional CI-time isolation rule
+- `knowledge/gotchas.md` — invariants and pitfalls
+
+## Inputs
+
+Resolve these before starting. If any is missing, stop and ask.
+
+| Variable       | Source                                                                                                    |
+|----------------|-----------------------------------------------------------------------------------------------------------|
+| `TARGET_PATH`  | Skill argument (e.g. `packages/lerx/promise-modal`). If absent, ask the user.                             |
+| `PACKAGE_NAME` | `name` field of `${TARGET_PATH}/package.json`.                                                            |
+| `SHORTCUT`     | Root `package.json` `scripts` entry whose value equals `yarn workspace ${PACKAGE_NAME}`; else unset.      |
+
+`SHORTCUT` is a convenience only. When unset, fall back to full workspace
+syntax: `yarn workspace ${PACKAGE_NAME} <subcommand>`.
+
+## Pre-Flight
+
+Stop and report on any failure. Do not attempt to fix silently.
+
+- [ ] `${TARGET_PATH}/docs/claude/skills/<name>/SKILL.md` and `knowledge/*.md` exist — the docs to be injected.
+- [ ] `${TARGET_PATH}/package.json` has `"type": "module"` and `"sideEffects": false`.
+- [ ] Build pipeline uses `rollup -c && yarn build:types` where `build:types` runs `node ../../aileron/script/build/buildTypes.mjs`.
+- [ ] `git status` in `${TARGET_PATH}` is clean. Unrelated changes present → confirm with user before proceeding.
+
+## Steps
+
+Execute in order. Each step is idempotent; on conflict, ask rather than overwrite.
+
+### Step 1 — Patch `${TARGET_PATH}/package.json`
+
+See `knowledge/package-json-patches.md` for the complete patch list:
+
+- `claude.assetPath` — set to `docs/claude` (or the consumer's chosen path).
+- `scripts.build` — ensure the chain ends with `&& yarn build:hashes`.
+- `scripts.build:hashes` — set to `claude-build-hashes` (the engine's bin).
+- `scripts.prepublishOnly` — `yarn build` if not already present.
+- `dependencies."@slats/claude-assets-sync"` — add (NOT `devDependencies`, NOT `peerDependencies`).
+- `files` — ensure `"dist"`, `"docs"`, `"README.md"` are listed. Never include `"bin"` or `"scripts"`.
+
+Do NOT add any `bin` entry. Do NOT add `./bin/*` or `./docs/*` to `exports`.
+Do NOT create `bin/` or `scripts/` directories in the consumer.
+
+### Step 2 — Patch `${TARGET_PATH}/CLAUDE.md`
+
+If `CLAUDE.md` exists, append or replace the `## Claude Docs Injector`
+section from `knowledge/claude-md-template.md`, substituting
+`${PACKAGE_NAME}`. Skip if `CLAUDE.md` does not exist (do not create one).
+
+### Step 3 — (Optional) Dependency-cruiser isolation gate
+
+Skip unless `${TARGET_PATH}/.dependency-cruiser.cjs` already exists or the
+user explicitly asks. See `knowledge/dependency-cruiser.md` for the single
+remaining forbidden rule (`src/**` → `docs/**`) and the `depcheck` script.
+
+### Step 4 — Install and build
+
+```bash
+yarn install
+yarn ${SHORTCUT:-workspace ${PACKAGE_NAME}} build
+```
+
+Expected: `rollup` → `buildTypes` → `claude-build-hashes` succeed, and
+`${TARGET_PATH}/dist/claude-hashes.json` is written.
+
+### Step 5 — E2E smoke via engine dispatcher
+
+Run from `/tmp/...`, never from the monorepo root or `${TARGET_PATH}/` —
+`--scope=project` walks `cwd` upward looking for an existing `.claude`,
+which would mutate the real repo's. See `knowledge/smoke-tests.md` for
+the full 8-path matrix, expected exit codes, and rationale.
+
+### Step 6 — Report
+
+Summarize:
+
+- Files patched vs. skipped (with reason for each skip).
+- Manifest file count from `dist/claude-hashes.json`.
+- Smoke-test exit codes (all 8).
+- Recommendation: commit this change on its own, separate from other work.
+
+## Report Template
+
+```markdown
+## claude-docs-asset-wiring — ${PACKAGE_NAME}
+
+**Files patched**
+- package.json                 — patched: [claude.assetPath, scripts.build, scripts.build:hashes, dependencies, files]
+- CLAUDE.md                    — section added | skipped (no CLAUDE.md)
+- .dependency-cruiser.cjs      — updated | skipped (not present)
+
+**Manifest**
+- dist/claude-hashes.json: <N> files
+
+**Smoke tests**
+| # | command                                                     | expected | actual |
+|---|-------------------------------------------------------------|----------|--------|
+| 1 | --package=${PACKAGE_NAME} --scope=project --dry-run         | 0        | <n>    |
+| 2 | --package=${PACKAGE_NAME} --scope=project                   | 0        | <n>    |
+| 3 | --package=${PACKAGE_NAME} --scope=project (up-to-date)      | 0        | <n>    |
+| 4 | CI=true --package=${PACKAGE_NAME} --scope=project (tampered)| 2        | <n>    |
+| 5 | CI=true --package=${PACKAGE_NAME} --scope=project --force   | 0        | <n>    |
+| 6 | CI=true --package=${PACKAGE_NAME} (missing --scope)         | 2        | <n>    |
+| 7 | (missing --package)                                         | 2        | <n>    |
+| 8 | --package=@does/not-exist                                   | 2        | <n>    |
+
+**Next**: commit on its own — do not bundle with unrelated changes.
+```
+
+## Termination Conditions
+
+- **Pre-Flight fails** → stop, report the failing check. Do not proceed.
+- **Conflict during patch** → stop, show the diff, ask user whether to overwrite.
+- **Build fails at Step 4** → stop, report error. Do not run smoke tests on a broken build.
+- **Smoke test mismatch** → stop, report the failing path with captured exit code.
+- **All steps pass** → emit the report from the template above.