@slats/claude-assets-sync 0.2.0 → 0.3.1

package/dist/ui/hooks/usePlanStep.mjs

@@ -0,0 +1,94 @@
+import { useRef, useEffect } from 'react';
+import 'node:crypto';
+import 'node:fs/promises';
+import { readHashManifest, computeNamespacePrefixes } from '../../core/hashManifest/hashManifest.mjs';
+import 'node:path';
+import 'picocolors';
+import { buildPlan } from '../../core/buildPlan/buildPlan.mjs';
+import { resolveScope } from '../../core/scope/scope.mjs';
+
+function usePlanStep({ targets, scope, originCwd, force, dispatch, onPlansReady, }) {
+    const startedRef = useRef(false);
+    useEffect(() => {
+        if (!scope || startedRef.current)
+            return;
+        startedRef.current = true;
+        let cancelled = false;
+        (async () => {
+            const results = [];
+            const warnings = [];
+            for (const target of targets) {
+                if (cancelled)
+                    return;
+                dispatch({
+                    type: 'plan-step',
+                    step: { packageName: target.name, status: 'running' },
+                });
+                try {
+                    if (!target.hashesPresent) {
+                        dispatch({
+                            type: 'plan-step',
+                            step: {
+                                packageName: target.name,
+                                status: 'failed',
+                                error: 'dist/claude-hashes.json missing',
+                            },
+                        });
+                        continue;
+                    }
+                    const manifest = await readHashManifest(target.packageRoot);
+                    const scopeResolution = resolveScope(scope, originCwd);
+                    const plan = await buildPlan({
+                        sourceHashes: manifest.files,
+                        targetRoot: scopeResolution.targetRoot,
+                        namespacePrefixes: computeNamespacePrefixes(manifest),
+                        force,
+                    });
+                    results.push({ target, scope: scopeResolution, plan });
+                    for (const action of plan.actions) {
+                        if (action.kind === 'warn-diverged' || action.kind === 'warn-orphan') {
+                            warnings.push({
+                                packageName: target.name,
+                                kind: action.kind,
+                                relPath: action.relPath,
+                                description: action.kind === 'warn-diverged'
+                                    ? 'local differs from source (user edit or version change)'
+                                    : 'exists locally but not in manifest',
+                            });
+                        }
+                    }
+                    dispatch({
+                        type: 'plan-step',
+                        step: { packageName: target.name, status: 'done' },
+                    });
+                }
+                catch (error) {
+                    dispatch({
+                        type: 'plan-step',
+                        step: {
+                            packageName: target.name,
+                            status: 'failed',
+                            error: error instanceof Error ? error.message : String(error),
+                        },
+                    });
+                }
+            }
+            if (cancelled)
+                return;
+            dispatch({ type: 'plans-ready', plans: results });
+            onPlansReady(results, warnings);
+        })().catch((error) => {
+            if (!cancelled) {
+                dispatch({
+                    type: 'fail',
+                    error: error instanceof Error ? error : new Error(String(error)),
+                });
+            }
+        });
+        return () => {
+            cancelled = true;
+        };
+    }, [targets, scope, originCwd, force, dispatch, onPlansReady]);
+}
+
+export { usePlanStep };

package/dist/ui/hooks/useResolveStep.d.ts

@@ -0,0 +1,18 @@
+import type { ConsumerPackage } from '../../commands/runCli/type.js';
+import type { Scope } from '../../core/index.js';
+import type { InjectEvent } from '../types/index.js';
+interface UseResolveStepOptions {
+    readonly targets: readonly ConsumerPackage[];
+    readonly flags: {
+        readonly scope?: string;
+    };
+    readonly dispatch: (event: InjectEvent) => void;
+    readonly onScopeResolved: (scope: Scope) => void;
+}
+/**
+ * Ink path is guaranteed TTY by `renderOrFallback`, so interactive
+ * scope selection is always safe. Non-TTY invocations go through
+ * `renderPlain` + `resolveScopeFlag` which exits 2 on missing scope.
+ */
+export declare function useResolveStep({ targets, flags, dispatch, onScopeResolved, }: UseResolveStepOptions): void;
+export {};

package/dist/ui/hooks/useResolveStep.mjs

@@ -0,0 +1,21 @@
+import { useEffect } from 'react';
+
+function useResolveStep({ targets, flags, dispatch, onScopeResolved, }) {
+    useEffect(() => {
+        if (flags.scope === 'user' || flags.scope === 'project') {
+            const resolved = flags.scope;
+            dispatch({ type: 'scope-selected', scope: resolved });
+            dispatch({ type: 'planning-started', targets, scope: resolved });
+            onScopeResolved(resolved);
+            return;
+        }
+        const pending = (scope) => {
+            dispatch({ type: 'scope-selected', scope });
+            dispatch({ type: 'planning-started', targets, scope });
+            onScopeResolved(scope);
+        };
+        dispatch({ type: 'scope-needed', pending });
+    }, [targets, flags.scope, dispatch, onScopeResolved]);
+}
+
+export { useResolveStep };

package/dist/ui/hooks/useTerminalWidth.d.ts

@@ -0,0 +1 @@
+export declare function useTerminalWidth(): number;

package/dist/ui/index.d.ts

@@ -0,0 +1,2 @@
+export { renderInjectApp } from './InjectApp/index.js';
+export type { Phase, InjectEvent, RenderInput, TargetPlan, Warning, ApplyProgress, PlanStepState, } from './types/index.js';

package/dist/ui/index.mjs

@@ -0,0 +1,16 @@
+import { renderInjectApp } from './InjectApp/utils/renderInjectApp.mjs';
+import 'react/jsx-runtime';
+import 'react';
+import 'ink';
+import 'ink-select-input';
+import 'ink-spinner';
+import 'node:fs/promises';
+import 'node:path';
+import 'picocolors';
+import 'node:crypto';
+import 'node:os';
+import 'node:fs';
+
+
+
+export { renderInjectApp };

package/dist/ui/theme/colors.d.ts

@@ -0,0 +1,12 @@
+export declare const colors: {
+    readonly primary: "cyan";
+    readonly success: "green";
+    readonly warn: "yellow";
+    readonly danger: "red";
+    readonly muted: "gray";
+    readonly accent: "magenta";
+    readonly info: "blue";
+    readonly dim: "gray";
+};
+export declare const gradientStops: readonly ["#22d3ee", "#a78bfa", "#f59e0b"];
+export type ColorName = (typeof colors)[keyof typeof colors];

package/dist/ui/theme/colors.mjs

@@ -0,0 +1,9 @@
+const colors = {
+    primary: 'cyan',
+    success: 'green',
+    warn: 'yellow',
+    danger: 'red',
+    muted: 'gray',
+    accent: 'magenta'};
+
+export { colors };

package/dist/ui/theme/icons.d.ts

@@ -0,0 +1,29 @@
+export declare const icons: {
+    readonly bulletDone: "●";
+    readonly bulletActive: "◐";
+    readonly bulletPending: "○";
+    readonly triangleRight: "▸";
+    readonly check: "✓";
+    readonly cross: "✗";
+    readonly warning: "⚠";
+    readonly question: "?";
+    readonly plus: "+";
+    readonly equals: "=";
+    readonly minus: "−";
+    readonly tilde: "~";
+    readonly blockFull: "█";
+    readonly blockEmpty: "░";
+    readonly dash: "─";
+    readonly divider: "───";
+    readonly boxTopLeft: "╭";
+    readonly boxTopRight: "╮";
+    readonly boxBottomLeft: "╰";
+    readonly boxBottomRight: "╯";
+    readonly boxHorizontal: "─";
+    readonly boxVertical: "│";
+    readonly boxDoubleTopLeft: "┌";
+    readonly boxDoubleTopRight: "┐";
+    readonly boxDoubleBottomLeft: "└";
+    readonly boxDoubleBottomRight: "┘";
+};
+export type IconName = keyof typeof icons;

package/dist/ui/theme/icons.mjs

@@ -0,0 +1,17 @@
+const icons = {
+    bulletDone: '●',
+    bulletActive: '◐',
+    bulletPending: '○',
+    triangleRight: '▸',
+    check: '✓',
+    cross: '✗',
+    warning: '⚠',
+    question: '?',
+    plus: '+',
+    equals: '=',
+    minus: '−',
+    blockFull: '█',
+    blockEmpty: '░',
+    divider: '───'};
+
+export { icons };

package/dist/ui/theme/layout.d.ts

@@ -0,0 +1,20 @@
+export declare const spacing: {
+    readonly xs: 0;
+    readonly sm: 1;
+    readonly md: 2;
+    readonly lg: 3;
+    readonly xl: 4;
+};
+export declare const widths: {
+    readonly statusBadge: 10;
+    readonly pathColumn: 60;
+    readonly progressBarDefault: 28;
+    readonly targetCardCount: 18;
+    readonly minTerminalWidth: 60;
+    readonly idealTerminalWidth: 120;
+};
+export declare const limits: {
+    readonly maxWarningsBeforeCollapse: 10;
+    readonly maxPlanRowsBeforeTruncate: 40;
+    readonly planTruncatedReveal: 15;
+};

package/dist/ui/theme/layout.mjs

@@ -0,0 +1,9 @@
+const widths = {
+    progressBarDefault: 28};
+const limits = {
+    maxWarningsBeforeCollapse: 10,
+    maxPlanRowsBeforeTruncate: 40,
+    planTruncatedReveal: 15,
+};
+
+export { limits, widths };

package/dist/ui/types/event.d.ts

@@ -0,0 +1,45 @@
+import type { ConsumerPackage } from '../../commands/runCli/type.js';
+import type { InjectReport, Scope } from '../../core/index.js';
+import type { PlanStepState, TargetPlan, Warning } from './target.js';
+export type InjectEvent = {
+    readonly type: 'scope-needed';
+    readonly pending: (scope: Scope) => void;
+} | {
+    readonly type: 'scope-selected';
+    readonly scope: Scope;
+} | {
+    readonly type: 'planning-started';
+    readonly targets: readonly ConsumerPackage[];
+    readonly scope: Scope;
+} | {
+    readonly type: 'plan-step';
+    readonly step: PlanStepState;
+} | {
+    readonly type: 'plans-ready';
+    readonly plans: readonly TargetPlan[];
+} | {
+    readonly type: 'force-confirm-required';
+    readonly warnings: readonly Warning[];
+    readonly pending: (ok: boolean) => void;
+} | {
+    readonly type: 'force-answer';
+    readonly ok: boolean;
+} | {
+    readonly type: 'apply-start';
+    readonly total: number;
+} | {
+    readonly type: 'apply-progress';
+    readonly done: number;
+    readonly current?: string;
+} | {
+    readonly type: 'done';
+    readonly reports: readonly InjectReport[];
+    readonly exitCode: 0 | 1 | 2;
+    readonly dryRun: boolean;
+} | {
+    readonly type: 'fail';
+    readonly error: Error;
+} | {
+    readonly type: 'focus-target';
+    readonly index: number;
+};

package/dist/ui/types/index.d.ts

@@ -0,0 +1,4 @@
+export type { Phase } from './phase.js';
+export type { InjectEvent } from './event.js';
+export type { RenderInput } from './render.js';
+export type { ApplyProgress, PlanStepState, TargetPlan, Warning, } from './target.js';

package/dist/ui/types/phase.d.ts

@@ -0,0 +1,44 @@
+import type { ConsumerPackage } from '../../commands/runCli/type.js';
+import type { InjectReport, Scope } from '../../core/index.js';
+import type { ApplyProgress, PlanStepState, TargetPlan, Warning } from './target.js';
+export type Phase = {
+    readonly kind: 'booting';
+} | {
+    readonly kind: 'resolving';
+    readonly targets: readonly ConsumerPackage[];
+} | {
+    readonly kind: 'scope-select';
+    readonly targets: readonly ConsumerPackage[];
+    readonly pending: (scope: Scope) => void;
+} | {
+    readonly kind: 'planning';
+    readonly targets: readonly ConsumerPackage[];
+    readonly scope: Scope;
+    readonly progress: ReadonlyMap<string, PlanStepState>;
+} | {
+    readonly kind: 'diff-review';
+    readonly plans: readonly TargetPlan[];
+    readonly focusedIndex: number;
+    readonly scope: Scope;
+} | {
+    readonly kind: 'force-confirm';
+    readonly plans: readonly TargetPlan[];
+    readonly warnings: readonly Warning[];
+    readonly pending: (ok: boolean) => void;
+    readonly scope: Scope;
+} | {
+    readonly kind: 'applying';
+    readonly plans: readonly TargetPlan[];
+    readonly progress: ApplyProgress;
+    readonly scope: Scope;
+} | {
+    readonly kind: 'summary';
+    readonly reports: readonly InjectReport[];
+    readonly plans: readonly TargetPlan[];
+    readonly exitCode: 0 | 1 | 2;
+    readonly scope: Scope;
+    readonly dryRun: boolean;
+} | {
+    readonly kind: 'error';
+    readonly error: Error;
+};

package/dist/ui/types/render.d.ts

@@ -0,0 +1,6 @@
+import type { ConsumerPackage, DefaultFlags } from '../../commands/runCli/type.js';
+export interface RenderInput {
+    readonly targets: readonly ConsumerPackage[];
+    readonly flags: DefaultFlags;
+    readonly originCwd: string;
+}

package/dist/ui/types/target.d.ts

@@ -0,0 +1,25 @@
+import type { InjectPlan } from '../../core/buildPlan/index.js';
+import type { ScopeResolution } from '../../core/index.js';
+import type { ConsumerPackage } from '../../commands/runCli/type.js';
+export interface PlanStepState {
+    readonly packageName: string;
+    readonly status: 'pending' | 'running' | 'done' | 'failed';
+    readonly error?: string;
+}
+export interface TargetPlan {
+    readonly target: ConsumerPackage;
+    readonly scope: ScopeResolution;
+    readonly plan: InjectPlan;
+}
+export interface Warning {
+    readonly packageName: string;
+    readonly kind: 'warn-diverged' | 'warn-orphan';
+    readonly relPath: string;
+    readonly description: string;
+}
+export interface ApplyProgress {
+    readonly total: number;
+    readonly done: number;
+    readonly current?: string;
+    readonly startedAt: number;
+}

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.1";

package/dist/utils/version.mjs

@@ -1,3 +1,3 @@
-const VERSION = '0.2.0';
+const VERSION = '0.3.1';
 
 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.
+- `devDependencies."@slats/claude-assets-sync"` — add (NOT `dependencies`, NOT `peerDependencies`). The engine is CLI-only and must not leak into end-user production installs.
+- `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.

package/docs/claude/skills/claude-docs-asset-wiring/knowledge/claude-md-template.md

@@ -0,0 +1,78 @@
+# `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 the sample package name in the chosen template
+with `${PACKAGE_NAME}` — four occurrences. 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 lives in `knowledge/gotchas.md` —
+do not duplicate it into every consumer's `CLAUDE.md`.
+
+---
+
+## Template (Korean — used by all consumers except `@winglet/style-utils`)
+
+````markdown
+## Claude Docs Injector
+
+`docs/claude/**` 자산을 사용자 `.claude/` 에 주입. 엔진: `@slats/claude-assets-sync` (bin: `inject-claude-settings`). 엔진은 `devDependencies` 에만 있으므로 항상 `npx -p @slats/claude-assets-sync ...` 로 호출합니다.
+
+```bash
+npx -p @slats/claude-assets-sync inject-claude-settings --package=@canard/schema-form --scope=user
+npx -p @slats/claude-assets-sync inject-claude-settings --package=@canard/schema-form --scope=project
+npx -p @slats/claude-assets-sync inject-claude-settings --package=@canard/schema-form --scope=user --dry-run
+npx -p @slats/claude-assets-sync inject-claude-settings --package=@canard/schema-form --scope=user --force
+```
+
+### Isolation Guardrails
+
+- `src/**` 는 `docs/**` 와 `@slats/claude-assets-sync` 어느 것도 import 금지.
+- **절대 `exports` 에 `./docs/*` 를 추가하지 말 것.**
+````
+
+---
+
+## Template (English — `@winglet/style-utils` convention)
+
+````markdown
+## Claude Docs Injector
+
+Inject `docs/claude/**` into the user's `.claude/`. Engine: `@slats/claude-assets-sync` (bin: `inject-claude-settings`). The engine is declared only in `devDependencies`, so always invoke via `npx -p @slats/claude-assets-sync ...`.
+
+```bash
+npx -p @slats/claude-assets-sync inject-claude-settings --package=@winglet/style-utils --scope=user
+npx -p @slats/claude-assets-sync inject-claude-settings --package=@winglet/style-utils --scope=project
+npx -p @slats/claude-assets-sync inject-claude-settings --package=@winglet/style-utils --scope=user --dry-run
+npx -p @slats/claude-assets-sync inject-claude-settings --package=@winglet/style-utils --scope=user --force
+```
+
+### Isolation Guardrails
+
+- `src/**` MUST NOT import from `docs/**` or `@slats/claude-assets-sync`.
+- **Never add `./docs/*` to `exports`.**
+````
+
+---
+
+## Substitution Rules
+
+- Replace the sample package name in the chosen template with
+  `${PACKAGE_NAME}` — four occurrences.
+- 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.