@slats/claude-assets-sync 0.2.0 → 0.3.0

package/docs/consumer-integration.md

@@ -1,6 +1,6 @@
 # Consumer Integration Template
 
-How to make a package "claude-sync aware" so `claude-sync` discovers and injects its `docs/claude/` tree into end-user `.claude` directories.
+How to make a package ship Claude Code assets through the `inject-claude-settings` dispatcher. Two fields in `package.json`; no stub code.
 
 ## 1. `package.json` additions
 
@@ -8,146 +8,87 @@ How to make a package "claude-sync aware" so `claude-sync` discovers and injects
 {
   "name": "@your-scope/your-package",
   "version": "…",
-  "bin": {
-    "claude-sync": "./bin/claude-sync.mjs"
-  },
-  "files": [
-    "dist",
-    "docs",
-    "dist/claude-hashes.json",
-    "bin",
-    "README.md"
-  ],
   "scripts": {
     "build": "… && yarn build:hashes",
-    "build:hashes": "node scripts/build-hashes.mjs"
+    "build:hashes": "claude-build-hashes"
   },
   "dependencies": {
-    "@slats/claude-assets-sync": "workspace:^",
+    "@slats/claude-assets-sync": "workspace:^"
   },
+  "files": ["dist", "docs", "README.md"],
   "claude": {
     "assetPath": "docs/claude"
   }
 }
 ```
 
-Do **not** expose `./bin/*` in `exports`. That would let consumer bundlers accidentally pull CLI code into app bundles.
-
-## 2. `bin/claude-sync.mjs` (3-line re-export stub)
-
-```javascript
-#!/usr/bin/env node
-import { runCli } from '@slats/claude-assets-sync';
-
-runCli(process.argv, { invokedFromBin: import.meta.url }).catch((err) => {
-  process.stderr.write(
-    `[@your-scope/your-package] claude-sync failed: ${err instanceof Error ? err.message : String(err)}\n`,
-  );
-  process.exit(1);
-});
-```
-
-`runCli` determines the implicit `--package` target in this priority order:
+- `@slats/claude-assets-sync` MUST be in `dependencies`, not `devDependencies` or `peerDependencies`.
+- Do **not** add any `bin` field. Bin names collide across consumers under `node_modules/.bin/` and the engine is the sole CLI surface.
+- Do **not** expose `./bin/*` or `./docs/*` in `exports`. Exposing them would let bundlers pull CLI code or the docs tree into app bundles.
+- Do **not** create a `bin/` or `scripts/` directory in the consumer. The engine's `claude-build-hashes` bin (resolved via `node_modules/.bin/`) handles build-time hashing.
 
-1. `--all` or `--package=<name>` (explicit)
-2. The consumer that owns `process.cwd()` (i.e. the terminal you launched from). When you `cd` into a consumer's package directory and run `yarn claude-sync`, that consumer is picked automatically.
-3. The consumer that owns `invokedFromBin` (fallback). This keeps bare `npx <pkg> claude-sync` working from arbitrary cwds — including from inside another consumer's directory where option 2 would have picked a different package.
-4. The sole discovered consumer, if exactly one exists.
-5. Otherwise an error asking for `--package=<name>` or `--all`.
+## 2. `docs/claude/` authoring
 
-Passing `invokedFromBin: import.meta.url` remains the mechanism for the fallback case. Omit it in slats's own global bin so it behaves as a cross-consumer dispatcher.
-
-Remember `chmod +x bin/claude-sync.mjs` (or rely on `files` entry to ship executable bit via npm).
-
-## 3. `scripts/build-hashes.mjs` (one line import)
+Any file tree works, but the recommended layout is:
 
-```javascript
-#!/usr/bin/env node
-import { buildHashes } from '@slats/claude-assets-sync/buildHashes';
-
-try {
-  const { outPath, fileCount } = await buildHashes();
-  console.log(`✓ claude-hashes.json written: ${fileCount} file(s) → ${outPath}`);
-} catch (err) {
-  console.error('❌ buildHashes failed:', err?.message ?? err);
-  process.exit(1);
-}
+```
+docs/claude/
+├── skills/
+│   └── <skill-name>/
+│       ├── SKILL.md
+│       └── knowledge/...
+├── rules/...
+└── commands/...
 ```
 
-This reads the current `package.json` + its `claude.assetPath`, hashes every file under the asset root (ignoring `.omc/**`, `*.log`, `.DS_Store`), and writes `dist/claude-hashes.json`.
+The build step (`yarn build:hashes` → `claude-build-hashes`) hashes every file under `docs/claude/` relative to the asset root and writes `dist/claude-hashes.json`. On inject, the CLI copies `skills`/`rules`/`commands` into the matching subtree under `.claude/`.
 
-## 4. Isolation guardrails (optional but recommended)
+## 3. Isolation guardrails (optional but recommended)
 
 In a `.dependency-cruiser.cjs`:
 
 ```javascript
-{
-  name: 'src-no-bin',
-  severity: 'error',
-  from: { path: '^src/' },
-  to: { path: '^bin/' },
-},
 {
   name: 'src-no-docs',
   severity: 'error',
+  comment:
+    'src/ must not import from docs/. docs/claude/** contains pure markdown ' +
+    'assets meant only for the engine dispatcher, not for the library runtime.',
   from: { path: '^src/' },
   to: { path: '^docs/' },
 },
-{
-  name: 'src-no-claude-assets-sync',
-  severity: 'error',
-  from: { path: '^src/' },
-  to: { path: 'node_modules/@slats/claude-assets-sync' },
-},
 ```
 
-Plus `"sideEffects": false` in `package.json`. The guardrails ensure the CLI engine never leaks into consumer runtime bundles.
+Plus `"sideEffects": false` in `package.json`. These ensure the docs tree never leaks into consumer runtime bundles.
 
-## 5. End-user invocations
+The legacy `src-no-bin` and `src-no-claude-assets-sync` rules are no longer load-bearing — the consumer owns no `bin/`, and the engine isn't referenced from `src/` anyway. Do not reintroduce them.
 
-| Install topology | Working invocations |
+## 4. End-user invocations
+
+| Install topology | Invocation |
 |---|---|
-| Consumer is a **direct dep** of the user's project | `npx claude-sync --scope=user` *(bare)* |
-| Always works (preferred in docs) | `npx -p @your-scope/your-package claude-sync --scope=user` |
-| Consumer is a **transitive dep** | `npx -p @your-scope/your-package claude-sync --scope=user` |
-| User has no consumer installed | `npx @slats/claude-assets-sync --package=@your-scope/your-package --scope=user` |
-| Multiple consumers discovered | `npx claude-sync --package=@your-scope/your-package` *or* `npx claude-sync --all` |
+| End user installs consumer as a **direct dep** on npm / yarn-classic | `npx inject-claude-settings --package=@your-scope/your-package --scope=user` |
+| End user installs consumer as a **direct dep** on pnpm strict / yarn-berry PnP | `npx -p @slats/claude-assets-sync inject-claude-settings --package=@your-scope/your-package --scope=user` |
+| End user has **no consumer installed** yet | `npx -p @slats/claude-assets-sync inject-claude-settings --package=@your-scope/your-package --scope=user` (resolves to whatever is on the registry under that exact name) |
+| End user has **multiple consumers installed** | Call `inject-claude-settings --package=<one-name>` per target. There is no `--all`. |
 
 ### Scope resolution (project)
 
-For `--scope=project`, the target `.claude` directory is resolved by walking up from `process.cwd()` and reusing the first existing `.claude` directory found. Only if no ancestor owns a `.claude` does the CLI fall back to `process.cwd()/.claude`.
+For `--scope=project`, the target `.claude` directory is resolved by walking up from `process.cwd()` and reusing the first existing `.claude` directory found. Only if no ancestor owns a `.claude` does the CLI fall back to `process.cwd()/.claude`. The CLI logs `(auto-located)` when this happens.
 
 ```
 workspace/
-  .claude/                            ← reused target (auto-located)
+  .claude/                        ← reused target (auto-located)
   packages/
-    @your-scope/your-package/         ← cd here and run claude-sync
-      bin/claude-sync.mjs
-```
-
-Running `yarn claude-sync --scope=project` from `packages/@your-scope/your-package/` injects into `workspace/.claude`, not `packages/@your-scope/your-package/.claude`. The CLI logs `(auto-located)` in its resolution line when this happens.
-
-## 6. Authoring `docs/claude/`
-
-Any file tree works, but the recommended layout is:
-
-```
-docs/claude/
-├── skills/
-│   └── <skill-name>/
-│       ├── SKILL.md
-│       └── knowledge/...
-├── rules/...
-└── commands/...
+    @your-scope/your-package/     ← cd here and run inject-claude-settings
 ```
 
-The hash manifest tracks every file under `docs/claude/` relative to the asset root. On inject, the CLI copies skills/rules/commands into the matching subtree under `.claude/`.
+Running `inject-claude-settings --package=@your-scope/your-package --scope=project` from `packages/@your-scope/your-package/` injects into `workspace/.claude`, not `packages/@your-scope/your-package/.claude`.
 
-## 7. Verification checklist
+## 5. Verification checklist
 
 - [ ] `yarn build` succeeds and emits `dist/claude-hashes.json` alongside the rest of `dist/`.
-- [ ] `node bin/claude-sync.mjs --help` prints the `claude-sync` subcommand tree.
-- [ ] `node bin/claude-sync.mjs list --json` emits an entry for your package with `hashesPresent: true`.
-- [ ] `node bin/claude-sync.mjs --scope=project --dry-run --package=@your-scope/your-package` emits a copy plan.
-- [ ] `yarn depcheck` (or whatever your dep-cruiser invocation is named) reports zero new violations.
-- [ ] Consumer bundler tree-shakes away CLI code (verify by greping the built bundle: should contain zero references to `@slats/claude-assets-sync`).
+- [ ] `node packages/slats/claude-assets-sync/bin/inject-claude-settings.mjs --help` prints the dispatcher usage.
+- [ ] `node packages/slats/claude-assets-sync/bin/inject-claude-settings.mjs --package=@your-scope/your-package --scope=project --dry-run` emits a copy plan when run from `/tmp/...`.
+- [ ] If you enabled Section 3's depcheck, `yarn depcheck` reports zero violations.
+- [ ] Consumer bundler tree-shakes away docs — grep the built bundle for `@slats/claude-assets-sync`, `inject-claude-settings`, and `docs/claude`; all three should be absent.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@slats/claude-assets-sync",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Shared CLI engine that lets consumer packages inject their Claude docs (skills, rules, commands) into a user's .claude directory via a thin bin/inject-docs wrapper.",
   "keywords": [
     "claude",
@@ -39,7 +39,7 @@
   "types": "dist/index.d.ts",
   "bin": {
     "claude-build-hashes": "./scripts/claude-build-hashes.mjs",
-    "claude-sync": "./bin/claude-sync.mjs"
+    "inject-claude-settings": "./bin/inject-claude-settings.mjs"
   },
   "files": [
     "dist",

package/bin/claude-sync.mjs

@@ -1,24 +0,0 @@
-#!/usr/bin/env node
-import { runCli } from '@slats/claude-assets-sync';
-import { readFile } from 'node:fs/promises';
-import { dirname, resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
-
-const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
-const pkg = JSON.parse(
-  await readFile(resolve(packageRoot, 'package.json'), 'utf-8'),
-);
-
-if (typeof pkg.claude?.assetPath === 'string') {
-  runCli(process.argv, {
-    packageRoot,
-    packageName: pkg.name,
-    packageVersion: pkg.version,
-    assetPath: pkg.claude.assetPath,
-  }).catch((err) => {
-    process.stderr.write(
-      `[${pkg.name}] claude-sync failed: ${err instanceof Error ? err.message : String(err)}\n`,
-    );
-    process.exit(1);
-  });
-}

package/docs/claude/skills/claude-sync-applier/SKILL.md

@@ -1,195 +0,0 @@
----
-name: claude-sync-applier
-description: "Wire the claude-sync CLI onto a consumer package in this monorepo. Copies verbatim bin/claude-sync.mjs and scripts/build-hashes.mjs stubs, patches package.json, updates CLAUDE.md, runs E2E smoke tests, and verifies bundle isolation. Idempotent — asks before clobbering."
-user-invocable: true
-disable-model-invocation: true
-argument-hint: <target-package-path>
----
-
-# claude-sync-applier
-
-Replicate the `claude-sync` bin setup on a target consumer package. The engine
-is `@slats/claude-assets-sync`; the reference consumer is `packages/canard/schema-form`.
-
-The bin stub reads its own `package.json` via `import.meta.url` and hands the
-engine `{ packageRoot, packageName, packageVersion, assetPath }`. Each invocation
-targets exactly one consumer — it does not discover other packages.
-
-**Outcome**
-
-```bash
-npx <PACKAGE_NAME> claude-sync --scope=user|project [--dry-run] [--force] [--root=<cwd>]
-```
-
-## Role
-
-You are a monorepo wiring specialist. Execute the 10 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` — source stubs (`bin/claude-sync.mjs`, `scripts/build-hashes.mjs`) with expected contents and rationale
-- `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/dependency-cruiser.md` — optional Step 4: three forbidden rules + config shape for static isolation
-- `knowledge/smoke-tests.md` — E2E 6-path matrix with expected exit codes and why
-- `knowledge/gotchas.md` — invariants, isolation guardrails, 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 — Create `${TARGET_PATH}/bin/claude-sync.mjs`
-
-Copy verbatim from the reference consumer. See `knowledge/reference-files.md`
-for the expected content and the source path. `chmod +x` the result.
-
-### Step 2 — Create `${TARGET_PATH}/scripts/build-hashes.mjs`
-
-Copy verbatim. See `knowledge/reference-files.md`.
-
-### Step 3 — Patch `${TARGET_PATH}/package.json`
-
-See `knowledge/package-json-patches.md` for the complete patch list:
-
-- `bin` entry
-- `files` append
-- `scripts.build` append (guarded)
-- `scripts.build:hashes`
-- `scripts.prepublishOnly`
-- `dependencies."@slats/claude-assets-sync"` (NOT devDependencies)
-- `claude.assetPath` default
-
-Do NOT add `./bin/*` to `exports` — ever.
-
-### Step 4 — (Optional) dependency-cruiser isolation gate
-
-Skip unless `${TARGET_PATH}/.dependency-cruiser.cjs` already exists or the user
-explicitly asks. Legacy `.dependency-cruiser.js` → out of scope; flag to user.
-
-When applicable, see `knowledge/dependency-cruiser.md` for the three forbidden
-rules, `no-orphans` adjustment, `includeOnly` expansion, and `depcheck` script.
-
-### Step 5 — Patch `${TARGET_PATH}/CLAUDE.md`
-
-If `CLAUDE.md` exists, append the `## Claude Docs Injector` section from
-`knowledge/claude-md-template.md`, substituting `@canard/schema-form` →
-`${PACKAGE_NAME}`. Keep the Isolation Guardrails subsection. Skip if
-`CLAUDE.md` does not exist.
-
-### Step 6 — Install and build
-
-```bash
-yarn install
-yarn ${SHORTCUT:-workspace ${PACKAGE_NAME}} build
-```
-
-Expected: `rollup` → `buildTypes` → `build:hashes` succeed, and
-`${TARGET_PATH}/dist/claude-hashes.json` is written.
-
-### Step 7 — E2E smoke tests (6 paths)
-
-Run from `/tmp/...`, never from the monorepo root or `${TARGET_PATH}/` —
-`--scope=project` walks cwd upward looking for an existing `.claude`, and would
-mutate the real repo's. See `knowledge/smoke-tests.md` for the full 6-path
-matrix, expected exit codes, and rationale.
-
-Split into two bash calls (paths 1–3, then 4–6). cwd resets between calls; the
-`[ -d ... ] && find -delete` prefix keeps it idempotent. Never use `rm -rf` or
-unquoted `*` globs.
-
-### Step 8 — Bundle isolation grep (must be empty)
-
-```bash
-grep -rE "@slats/claude-assets-sync|docs/claude|claude-sync" \
-  ${TARGET_PATH}/dist/index.mjs ${TARGET_PATH}/dist/index.cjs
-```
-
-Pass = exit code 1 (no matches). Any match → stop; CLI has leaked into the
-library bundle. See `knowledge/gotchas.md` for the three-layer isolation model.
-
-### Step 9 — depcheck (only if Step 4 ran)
-
-```bash
-yarn ${SHORTCUT:-workspace ${PACKAGE_NAME}} depcheck
-```
-
-Zero errors. Pre-existing `no-orphans` warnings are acceptable.
-
-### Step 10 — Report
-
-Summarize:
-
-- Files written vs. skipped (with reason for each skip)
-- Manifest file count from `dist/claude-hashes.json`
-- Smoke-test exit codes (all 6)
-- Grep result (expected: no matches)
-- depcheck result (or "static isolation not enforced" if Step 4 skipped)
-- Recommendation: commit this change on its own, separate from other work
-
-## Report Template
-
-```markdown
-## apply-claude-sync — ${PACKAGE_NAME}
-
-**Files**
-- bin/claude-sync.mjs          — created | unchanged | asked-user
-- scripts/build-hashes.mjs     — created | unchanged | asked-user
-- package.json                 — patched: [bin, files, scripts.build, …]
-- 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 | --scope=project --dry-run                       | 0        | <n>    |
-| 2 | --scope=project                                 | 0        | <n>    |
-| 3 | --scope=project (up-to-date)                    | 0        | <n>    |
-| 4 | CI=true --scope=project (tampered)              | 2        | <n>    |
-| 5 | CI=true --scope=project --force                 | 0        | <n>    |
-| 6 | CI=true (missing --scope)                       | 2        | <n>    |
-
-**Isolation**
-- grep on dist/index.{mjs,cjs}: no matches ✓
-- depcheck: <result | "static isolation not enforced">
-
-**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 6** → stop, report error. Do not run smoke tests on a broken build.
-- **Smoke test mismatch** → stop, report the failing path with captured exit code.
-- **Bundle grep finds matches** → stop, report which file leaked. Isolation is broken.
-- **All steps pass** → emit the report from the template above.

package/docs/claude/skills/claude-sync-applier/knowledge/claude-md-template.md

@@ -1,77 +0,0 @@
-# `CLAUDE.md` — `## Claude Docs Injector` section
-
-Reference: `packages/canard/schema-form/CLAUDE.md`.
-
-Append the section below to `${TARGET_PATH}/CLAUDE.md` if the file exists.
-Substitute `@canard/schema-form` → `${PACKAGE_NAME}`. Skip the entire step if
-`CLAUDE.md` does not exist (do not create one).
-
-The template is intentionally terse: CLI usage + essential isolation warnings.
-Architectural rationale (three-layer isolation model, silent no-op design,
-stub mechanics) lives in this skill's `knowledge/gotchas.md` — do not
-duplicate it into every consumer's `CLAUDE.md`.
-
----
-
-## Template
-
-````markdown
-## Claude Docs Injector
-
-Thin CLI stub that injects `docs/claude/` assets into the user's `.claude`
-directory. Engine: `@slats/claude-assets-sync`.
-
-```bash
-npx claude-sync --scope=user                 # ~/.claude
-npx claude-sync --scope=project              # nearest existing .claude walking up from cwd
-npx claude-sync --scope=user --dry-run       # preview
-npx claude-sync --scope=user --force         # overwrite local edits
-
-npx -p @canard/schema-form claude-sync --scope=user  # transitive-dep context
-```
-
-### Isolation Guardrails
-
-- `src/**` MUST NOT import from `bin/**`, `docs/**`, or `@slats/claude-assets-sync`.
-- **Never add `./bin/*` to `exports`.**
-- `yarn depcheck` enforces the isolation in CI.
-````
-
----
-
-## Substitution Rules
-
-- Replace `@canard/schema-form` with `${PACKAGE_NAME}` (one occurrence, in the
-  `npx -p` line).
-- Preserve the Isolation Guardrails bullets verbatim — these are the sharp
-  invariants that must stay consistent across consumers.
-
----
-
-## Placement & Skip Conditions
-
-- Append to end of `CLAUDE.md`. Ensure one blank line before the injected
-  section.
-- `${TARGET_PATH}/CLAUDE.md` does not exist → skip, report "skipped (no CLAUDE.md)".
-- Section already present with identical content → skip, report "unchanged".
-- Section present with different content → ask user, do not clobber.
-
----
-
-## What Was Deliberately Removed
-
-If a previous version of this skill injected a longer template, these parts
-were intentionally dropped:
-
-- Intro paragraph explaining the stub mechanics — belongs in `gotchas.md`,
-  not per-package docs.
-- `--scope=project` cwd-walk blockquote — the comment beside the command is
-  enough.
-- Per-package structure list (`bin/`, `scripts/`, `docs/claude/`,
-  `claude.assetPath` convention) — mechanical, same across all consumers,
-  not useful as per-package documentation.
-- Verbose Isolation Guardrails prose — reduced to three one-line rules.
-
-The principle: per-package `CLAUDE.md` should carry only what an agent or
-human needs **specific to this package**. Shared architecture belongs in the
-skill's knowledge files.

package/docs/claude/skills/claude-sync-applier/knowledge/dependency-cruiser.md

@@ -1,126 +0,0 @@
-# Step 4 — dependency-cruiser isolation gate (optional)
-
-This step is **only** executed when:
-
-- `${TARGET_PATH}/.dependency-cruiser.cjs` already exists (static isolation
-  was previously enforced), OR
-- The user explicitly asks for it.
-
-Do **not** introduce a new `.dependency-cruiser.cjs` into a target package that
-has not already opted into static analysis — the runtime isolation (import
-graph + `sideEffects: false` + no `bin` in `exports`) is sufficient on its own.
-
-**Legacy**: `.dependency-cruiser.js` (not `.cjs`) → out of scope. Flag to user
-and do not rename.
-
-Reference: `packages/canard/schema-form/.dependency-cruiser.cjs`.
-
----
-
-## Changes to Apply
-
-When applicable, mirror the reference config. Four edits total:
-
-### 1. Append three `forbidden` rules
-
-Append each with `severity: 'error'`:
-
-```js
-{
-  name: 'src-no-bin',
-  severity: 'error',
-  comment:
-    'src/ must not import from bin/. bin/ is a CLI-only entry point and must ' +
-    'never leak into the library bundle.',
-  from: { path: '^src/' },
-  to: { path: '^bin/' },
-},
-{
-  name: 'src-no-docs',
-  severity: 'error',
-  comment:
-    'src/ must not import from docs/. docs/claude/** contains pure markdown assets ' +
-    'meant only for the inject-docs CLI, not for the library runtime.',
-  from: { path: '^src/' },
-  to: { path: '^docs/' },
-},
-{
-  name: 'src-no-claude-assets-sync',
-  severity: 'error',
-  comment:
-    '@slats/claude-assets-sync is a CLI-only dependency. It is allowed only ' +
-    'from bin/. Importing it from src/ would leak the CLI engine into ' +
-    'consumer production bundles.',
-  from: { path: '^src/' },
-  to: { path: 'node_modules/@slats/claude-assets-sync' },
-},
-```
-
-Place these alongside the existing `forbidden` rules in the reference config.
-Do not duplicate if any of these rule names already exist.
-
-### 2. Extend `no-orphans` rule
-
-Add `'^bin/'` to the existing `no-orphans` rule's `from.pathNot` array. `bin`
-entry points are orphans by design (they're invoked as executables, not
-imported).
-
-```js
-from: {
-  orphan: true,
-  pathNot: [
-    '(^|/)[.][^/]+[.](?:js|cjs|mjs|ts|cts|mts|json)$',
-    '[.]d[.]ts$',
-    '(^|/)tsconfig[.]json$',
-    '(^|/)(?:babel|webpack)[.]config[.](?:js|cjs|mjs|ts|cts|mts|json)$',
-    '^bin/',
-  ],
-},
-```
-
-### 3. Expand `options.includeOnly`
-
-Change to include both `src` and `bin` so dependency-cruiser scans the bin
-entry points as well:
-
-```js
-includeOnly: ['^src', '^bin'],
-```
-
-### 4. Add `depcheck` script
-
-In `${TARGET_PATH}/package.json` `scripts`:
-
-```json
-"depcheck": "depcruise src bin --config .dependency-cruiser.cjs --no-progress"
-```
-
-If an existing `depcheck` script points elsewhere, ask the user.
-
----
-
-## Post-Step Verification
-
-After Steps 1–6 complete and this Step 4 has been applied, Step 9 runs:
-
-```bash
-yarn ${SHORTCUT:-workspace ${PACKAGE_NAME}} depcheck
-```
-
-Must exit 0 with no errors. Pre-existing `no-orphans` warnings are acceptable.
-
----
-
-## Why This Step Is Optional
-
-The three-layer isolation works without static analysis:
-
-1. Import graph: `src/**` never references `bin/**`, `docs/**`, or
-   `@slats/claude-assets-sync`.
-2. `"sideEffects": false` + `"type": "module"` — dead-code elimination of any
-   accidental reference.
-3. No `./bin/*` in `exports` — consumer bundlers cannot deep-import into bin.
-
-dependency-cruiser adds a fourth layer (CI-time regression detection) but is
-not required for correctness. Don't force-enable it on a package that hasn't
-opted in — it carries real maintenance cost.