@joshuafolkken/kit 1.872.0

package/scripts/init/distributed-paths.ts

@@ -0,0 +1,100 @@
+// The path transform that makes kit's distributed AI documents resolve in a consumer, and the
+// one-line CLAUDE.md import that replaces the old byte-copy (joshuafolkken/kit#1878). Applied at
+// publish time to CLAUDE.md (scripts/build/build-claude-md.ts) and at copy time to the pointer files kit
+// still ships whole (AGENTS.md / GEMINI.md / .cursorrules, via init-copy-content.ts).
+
+// Where kit's own published files sit once a consumer has installed the package. Backtick-quoted
+// references to anything kit ships are rewritten to this location so a consumer opens the installed
+// copy rather than a path that exists only in the kit repository.
+const KIT_PACKAGE_PATH_PREFIX = 'node_modules/@joshuafolkken/kit/'
+
+const PROMPTS_PACKAGE_PREFIX = `${KIT_PACKAGE_PATH_PREFIX}prompts/`
+const ESLINT_PACKAGE_PREFIX = `${KIT_PACKAGE_PATH_PREFIX}eslint/`
+
+// kit files that are NOT published (tests, docs/) cannot be rewritten to a node_modules path — the
+// consumer never receives them — so their backtick references become full GitHub URLs instead. A
+// directory reference (trailing slash) points at the tree view, a file at the blob view.
+const GITHUB_REPO_BLOB_BASE = 'https://github.com/joshuafolkken/kit/blob/main/'
+const GITHUB_REPO_TREE_BASE = 'https://github.com/joshuafolkken/kit/tree/main/'
+
+// The single line a consumer's CLAUDE.md carries: an import of kit's published, already
+// path-transformed rules. The consumer's own additions sit below it. Distributed at publish time via
+// dist/CLAUDE.md (build-claude-md.ts) rather than byte-copied at sync time, so a package update alone
+// keeps the rules current (joshuafolkken/kit#1878).
+const CLAUDE_MD_IMPORT_LINE = '@node_modules/@joshuafolkken/kit/dist/CLAUDE.md'
+
+// A span containing `*` is excluded: it is a **glob**, not a reference to a file a consumer can
+// open. A distributed document that writes a directory set as `prompts/**` means "anything beneath
+// it", and rewriting that to `node_modules/@joshuafolkken/kit/prompts/**` would print a path that can
+// never appear in a consumer's diff and is not what the set matches (joshuafolkken/kit#907).
+function transform_prompt_paths(content: string): string {
+	return content.replaceAll(
+		/`prompts\/([^`*]+)`/gu,
+		(_match, prompt_path: string) => `\`${PROMPTS_PACKAGE_PREFIX}${prompt_path}\``,
+	)
+}
+
+// The eslint/ directory is published (package.json `files`), so its backtick references — the
+// distributed lint rules such as `eslint/rules/test-filename.js` — resolve in a consumer once
+// rewritten to the installed location. Globs are skipped for the same reason prompts globs are.
+function transform_eslint_paths(content: string): string {
+	return content.replaceAll(
+		/`eslint\/([^`*]+)`/gu,
+		(_match, eslint_path: string) => `\`${ESLINT_PACKAGE_PREFIX}${eslint_path}\``,
+	)
+}
+
+// Test files are excluded from the package (`files` carries `!**/*.test.ts`), so a backtick
+// reference to one would be dead in a consumer. Rewrite it to the GitHub source instead, wherever in
+// the tree it lives.
+function transform_test_file_paths(content: string): string {
+	return content.replaceAll(
+		/`([^`*]+\.(?:test|spec)\.ts)`/gu,
+		(_match, test_path: string) => `\`${GITHUB_REPO_BLOB_BASE}${test_path}\``,
+	)
+}
+
+function github_url_base(reference_path: string): string {
+	return reference_path.endsWith('/') ? GITHUB_REPO_TREE_BASE : GITHUB_REPO_BLOB_BASE
+}
+
+// docs/ is not published, so its backtick references become GitHub URLs too. A bare `docs/` points at
+// the tree view; a file underneath it at the blob view.
+function transform_documentation_paths(content: string): string {
+	return content.replaceAll(
+		/`(docs\/[^`*]*)`/gu,
+		(_match, documentation_path: string) =>
+			`\`${github_url_base(documentation_path)}${documentation_path}\``,
+	)
+}
+
+// Every rewrite applied to a file kit distributes verbatim, so its backtick path references resolve
+// in a consumer: bundled paths (prompts/, eslint/) point into node_modules, unbundled ones (tests,
+// docs/) point at GitHub.
+function transform_distributed_paths(content: string): string {
+	const with_prompts = transform_prompt_paths(content)
+	const with_eslint = transform_eslint_paths(with_prompts)
+	const with_tests = transform_test_file_paths(with_eslint)
+
+	return transform_documentation_paths(with_tests)
+}
+
+// The consumer CLAUDE.md is one @import of kit's published rules plus whatever the project adds below
+// it. Ensure the import line is present without disturbing those additions: an absent file becomes
+// the line alone, a file already carrying it is returned untouched, and any other file keeps all its
+// content with the import prepended. The substring check makes it idempotent.
+function ensure_claude_md_import(existing: string | undefined): string {
+	if (existing === undefined) return `${CLAUDE_MD_IMPORT_LINE}\n`
+	if (existing.includes(CLAUDE_MD_IMPORT_LINE)) return existing
+
+	return `${CLAUDE_MD_IMPORT_LINE}\n\n${existing}`
+}
+
+const distributed_paths = {
+	transform_prompt_paths,
+	transform_distributed_paths,
+	ensure_claude_md_import,
+	CLAUDE_MD_IMPORT_LINE,
+}
+
+export { distributed_paths }

package/scripts/init/hook-command-rewrite.ts

@@ -0,0 +1,85 @@
+import { claude_plugin_config } from './claude-plugin-config'
+import { hook_launch } from './hook-launch'
+
+// The consumer's `.claude/settings.json` runs its hooks off the published package directly, not
+// through `pnpm josh` (joshuafolkken/kit#1930, joshuafolkken/kit#2023). Two paths inside a hook
+// command are rebased onto the installed package: the per-hook bundle `dist/hooks/<name>.js` a hook
+// prefers, and the `pnpm josh <command>` fallback it drops to when that bundle is missing — which for
+// a consumer becomes the `dist/josh.js` dispatcher, since the published package always ships `dist`
+// and a `pnpm` launch would only add the wrapper this exists to remove.
+//
+// kit's own settings file keeps the `pnpm josh` fallback (`tsx scripts/josh/josh.ts` against live
+// source), so a fresh clone with no `dist/` still runs the current guards. The rewrite is gated on the
+// copy destination, exactly as the plugin injection is — kit's source tree is never transformed in
+// place.
+
+const PNPM_JOSH_PREFIX = 'pnpm josh '
+const CODEX_ADAPTER_SOURCE = 'pnpm exec tsx scripts/hooks/codex-hook-adapter.ts'
+// Relative to the consumer's project root, which is the working directory a Claude Code hook runs in.
+// The path is the plugin marketplace's `node_modules` location plus the built entry `bin.josh` names.
+const BUNDLE_INVOCATION = `node ${claude_plugin_config.MARKETPLACE_PATH}/dist/josh.js `
+// The per-hook bundle directory a fresh clone builds, and where it lives inside the installed package.
+const HOOK_BUNDLE_DIR = `${hook_launch.HOOK_DIST_DIR}/`
+const CONSUMER_HOOK_BUNDLE_DIR = `${claude_plugin_config.MARKETPLACE_PATH}/${HOOK_BUNDLE_DIR}`
+const CODEX_ADAPTER_BUNDLE = `node ${CONSUMER_HOOK_BUNDLE_DIR}codex-hook-adapter.js`
+const CODEX_HOOKS_DESTINATION = '.codex/hooks.json'
+const CODEX_ROOT_PREFIX = String.raw`cd \"$(git rev-parse --show-toplevel)\" && `
+// Capture the value of every `"command"` field, escapes and all, so the rewrites below touch command
+// values alone — never an echo reminder's prose or a `"description"` that merely mentions the string.
+const COMMAND_FIELD = /("command":\s*")((?:[^"\\]|\\.)*)(")/gu
+
+// Idempotent on its own: `CONSUMER_HOOK_BUNDLE_DIR` still contains `HOOK_BUNDLE_DIR`, so a blind
+// second pass would rebase an already-rebased path onto itself. A value already targeting the
+// installed package is left untouched, restoring the idempotency the earlier `pnpm josh`-anchored
+// rewrite had for free.
+function rebase_bundle_directory(value: string): string {
+	return value.includes(CONSUMER_HOOK_BUNDLE_DIR)
+		? value
+		: value.split(HOOK_BUNDLE_DIR).join(CONSUMER_HOOK_BUNDLE_DIR)
+}
+
+// Rebase both paths a hook command can carry: the bundle it prefers, then the `pnpm josh` fallback.
+// The bundle rewrite runs first — its replacement never contains `pnpm josh`, so the two are
+// independent whichever order they run. The fallback rewrite is idempotent too (`BUNDLE_INVOCATION`
+// holds no `pnpm josh `), so the whole rewrite is safe to run more than once.
+function rewrite_command_value(value: string): string {
+	return rebase_bundle_directory(value)
+		.split(PNPM_JOSH_PREFIX)
+		.join(BUNDLE_INVOCATION)
+		.split(CODEX_ADAPTER_SOURCE)
+		.join(CODEX_ADAPTER_BUNDLE)
+}
+
+function rewrite_hook_commands(content: string, is_codex = false): string {
+	return content.replaceAll(COMMAND_FIELD, (_match, open: string, value: string, close: string) => {
+		const rewritten = rewrite_command_value(value)
+		const prefix = is_codex && !rewritten.startsWith(CODEX_ROOT_PREFIX) ? CODEX_ROOT_PREFIX : ''
+
+		return `${open}${prefix}${rewritten}${close}`
+	})
+}
+
+// Rewrite copied Claude and Codex hook files only; kit's source files keep their live-source fallback.
+function apply_hook_command_rewrite_for_destination(
+	destination_path: string,
+	content: string,
+): string {
+	if (destination_path.endsWith(CODEX_HOOKS_DESTINATION)) {
+		return rewrite_hook_commands(content, true)
+	}
+
+	if (destination_path.endsWith(claude_plugin_config.CLAUDE_SETTINGS_DESTINATION)) {
+		return rewrite_hook_commands(content)
+	}
+
+	return content
+}
+
+const hook_command_rewrite = {
+	apply_hook_command_rewrite_for_destination,
+	BUNDLE_INVOCATION,
+	PNPM_JOSH_PREFIX,
+	rewrite_hook_commands,
+}
+
+export { hook_command_rewrite }

package/scripts/init/hook-launch.ts

@@ -0,0 +1,31 @@
+// The shell command a Claude Code hook is launched with, so it starts without a `pnpm` wrapper — and,
+// for a consumer, without the `dist/josh.js` dispatcher re-spawning `tsx` for the hook's `.ts`
+// (joshuafolkken/kit#2023). Each hook is pre-built to its own `dist/hooks/<name>.js`
+// (`scripts/build/build-hooks.ts`) and launched directly with `node`.
+//
+// **The fallback is a real branch, not a courtesy.** A fresh clone has no `dist/hooks/` until
+// `pnpm build` runs, so the command prefers the bundle and drops to `pnpm josh <command>` (the live
+// `tsx` source) when the bundle is absent, rather than passing silently. **An `if`/`else`, never
+// `&&`/`||`**: a guard's refusal is a non-zero exit, and a `node … || pnpm josh …` chain would read
+// that refusal as a missing bundle and run the hook twice. `[ -f ]` decides on the file alone and
+// leaves the chosen branch's exit code untouched.
+
+// Relative to the working directory a hook runs in — kit's own root, where the built `dist/hooks/`
+// sits. The consumer rewrite (`hook-command-rewrite.ts`) rebases this onto the installed package.
+const HOOK_DIST_DIR = 'dist/hooks'
+
+// Prefer `primary_path` (run as `node <path>`) when it exists, else run `fallback_command` verbatim.
+// Kept generic so a test can exercise the branch selection with stub commands rather than real hooks.
+function launch_command(primary_path: string, fallback_command: string): string {
+	return `if [ -f ${primary_path} ]; then node ${primary_path}; else ${fallback_command}; fi`
+}
+
+// `bundle` is the hook's file under `dist/hooks` (e.g. `pretool-guard.js`); `command` is the josh
+// subcommand the fallback runs (e.g. `pretool:guard`).
+function hook_launch_command(bundle: string, command: string): string {
+	return launch_command(`${HOOK_DIST_DIR}/${bundle}`, `pnpm josh ${command}`)
+}
+
+const hook_launch = { HOOK_DIST_DIR, hook_launch_command, launch_command }
+
+export { hook_launch }

package/scripts/init/init-actions.ts

@@ -0,0 +1,147 @@
+import { readFileSync } from 'node:fs'
+import path from 'node:path'
+import { string_array_schema, vscode_settings_schema } from '#scripts/lib/schemas'
+import { init_logic } from './init-logic'
+import { package_path, PROJECT_ROOT } from './init-paths'
+
+const PRETTIER_CONFIG_JS = 'prettier.config.js'
+
+interface FileAction {
+	dest: string
+	create: () => string
+	merge?: (existing: string) => string
+}
+
+function read_package_file(relative_path: string): string {
+	return readFileSync(package_path(relative_path), 'utf8')
+}
+
+function read_package_json(relative_path: string): unknown {
+	return JSON.parse(read_package_file(relative_path))
+}
+
+type MergeFunction = (existing: string) => string
+
+function build_action(destination: string, create: () => string, merge: MergeFunction): FileAction {
+	return { dest: destination, create, merge }
+}
+
+function build_vscode_actions(): ReadonlyArray<FileAction> {
+	const extensions_path = path.join('.vscode', init_logic.VSCODE_EXTENSIONS_FILENAME)
+	const settings_path = path.join('.vscode', init_logic.get_vscode_settings_filename())
+	const extensions_raw = vscode_settings_schema.parse(read_package_json(extensions_path))
+	const raw_recommendations = extensions_raw['recommendations']
+	const recommendations = string_array_schema.parse(raw_recommendations)
+	const settings_data = init_logic.strip_kit_only_vscode_settings(
+		vscode_settings_schema.parse(read_package_json(settings_path)),
+	)
+
+	return [
+		{
+			dest: '.vscode/extensions.json',
+			create: () => read_package_file(extensions_path),
+			merge: (existing) =>
+				init_logic.merge_json_array_field(existing, 'recommendations', recommendations),
+		},
+		{
+			dest: '.vscode/settings.json',
+			create: () =>
+				init_logic.strip_kit_only_vscode_settings_content(read_package_file(settings_path)),
+			merge: (existing) => init_logic.merge_json_object(existing, settings_data),
+		},
+	]
+}
+
+// Create-only: the rule list is a project-owned allowlist once it exists, so a consumer
+// that added custom rules or disabled a noisy one must not have that overwritten.
+function build_secretlint_action(): FileAction {
+	return {
+		dest: init_logic.get_secretlint_config_filename(),
+		create: () => init_logic.generate_secretlint_config(),
+	}
+}
+
+// PROJECT_ROOT is what the consumer's `extends` paths resolve against, which the merge needs to
+// migrate a retired `*.jsonc` preset path only once its renamed target is installed (#681).
+function build_tsconfig_action(): FileAction {
+	return build_action(
+		'tsconfig.json',
+		() => init_logic.generate_tsconfig(),
+		(existing) =>
+			init_logic.merge_tsconfig_exclude(
+				init_logic.merge_tsconfig_extends(
+					existing,
+					init_logic.get_tsconfig_extends_entry(),
+					PROJECT_ROOT,
+				),
+			),
+	)
+}
+
+function build_config_file_actions(): ReadonlyArray<FileAction> {
+	const lefthook_extends = init_logic.get_lefthook_extends_value()
+
+	return [
+		build_tsconfig_action(),
+		build_action(
+			'cspell.config.yaml',
+			() => init_logic.generate_cspell_config(),
+			(existing) => init_logic.merge_cspell_import(existing, init_logic.get_cspell_import_value()),
+		),
+		build_action(
+			'lefthook.yml',
+			() => init_logic.generate_lefthook_config(),
+			(existing) => init_logic.merge_lefthook_extends(existing, lefthook_extends),
+		),
+		build_secretlint_action(),
+		...build_vscode_actions(),
+	]
+}
+
+function build_playwright_action(): FileAction {
+	return { dest: 'playwright.config.ts', create: () => init_logic.generate_playwright_config() }
+}
+
+function build_eslint_action(): FileAction {
+	return build_action(
+		'eslint.config.js',
+		() => init_logic.generate_eslint_config(),
+		(existing) => init_logic.merge_eslint_config(existing),
+	)
+}
+
+// Union-merge (not byte-copy) so an existing consumer .gitignore keeps its project-local
+// entries while gaining any missing kit patterns.
+function build_gitignore_action(): FileAction {
+	const template = read_package_file('templates/gitignore')
+
+	return build_action(
+		'.gitignore',
+		() => template,
+		(existing) => init_logic.merge_gitignore(existing, template),
+	)
+}
+
+function build_file_actions(): ReadonlyArray<FileAction> {
+	return [
+		build_gitignore_action(),
+		build_action(
+			'.npmrc',
+			() => init_logic.generate_npmrc(),
+			(existing) => init_logic.merge_npmrc(existing),
+		),
+		build_eslint_action(),
+		build_action(
+			PRETTIER_CONFIG_JS,
+			() => init_logic.generate_prettier_config(),
+			(existing) => init_logic.merge_prettier_config(existing),
+		),
+		build_playwright_action(),
+		...build_config_file_actions(),
+	]
+}
+
+const init_actions = { build_file_actions, read_package_json }
+
+export type { FileAction }
+export { init_actions, PRETTIER_CONFIG_JS }

package/scripts/init/init-ai-copy.ts

@@ -0,0 +1,235 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import path from 'node:path'
+import { is_workflow_destination } from '#scripts/claude/workflow-destination'
+import { gh_spawn } from '#scripts/gh/gh-spawn'
+import { managed_marker_logic } from '#scripts/managed-marker/managed-marker-logic'
+import {
+	classify_path,
+	copy_directory_failure,
+	directory_copy_blocker,
+} from '#scripts/sync/directory-copy-guard'
+import { transform_copied_content } from './init-copy-content'
+import { init_logic } from './init-logic'
+import { package_path, PROJECT_ROOT } from './init-paths'
+import { init_sonar } from './init-sonar'
+
+const WORKSPACE_YAML = 'pnpm-workspace.yaml'
+const CLAUDE_MD_FILENAME = 'CLAUDE.md'
+
+// Whether the existing file is a workflow that carries no header. A read failure answers "no": the
+// point is to warn, and a warning is not worth failing a command that used to open nothing.
+function did_read_unstamped(destination_path: string): boolean {
+	try {
+		return !managed_marker_logic.is_marked(readFileSync(destination_path, 'utf8'))
+	} catch {
+		return false
+	}
+}
+
+function copy_ai_file(source_path: string, destination_path: string): void {
+	const content = readFileSync(source_path, 'utf8')
+
+	mkdirSync(path.dirname(destination_path), { recursive: true })
+	writeFileSync(destination_path, transform_copied_content(destination_path, content))
+}
+
+// `init` declines to modify a file that already exists, and that includes not stamping it: the
+// destination may hold a workflow the consumer wrote themselves, and a header claiming this package
+// owns it would hold every bump to it back on a false premise. But an unstamped workflow is not
+// merely out of date either — the consumer's auto-merge workflow reads the stamp, so until `sync`
+// writes one, a bump to a workflow this package does overwrite merges and the next sync reverts it
+// (joshuafolkken/kit#844). A warning is the honest middle: `sync` resolves it either way, and this
+// names the consequence rather than leaving it to be discovered from a revert.
+//
+// The destination is checked before the file is opened, and a read failure is stepped over, so
+// nothing here can turn a skipped file into a failed `init` the way it never was before.
+function did_warn_unstamped_workflow(destination_path: string, label: string): boolean {
+	if (!is_workflow_destination(destination_path) || !did_read_unstamped(destination_path)) {
+		return false
+	}
+
+	console.warn(`  ⚠ ${label} has no managed-workflow header — run josh sync before merging bumps`)
+
+	return true
+}
+
+function did_skip_copy_if_absent(
+	source_path: string,
+	destination_path: string,
+	label: string,
+): boolean {
+	if (existsSync(destination_path)) {
+		console.info(`  ⏭ skipped   ${label} (already exists — run josh sync to update)`)
+		did_warn_unstamped_workflow(destination_path, label)
+
+		return true
+	}
+
+	copy_ai_file(source_path, destination_path)
+	console.info(`  ✔ created   ${label}`)
+
+	return false
+}
+
+function did_skip_workspace_yaml_copy(source_path: string, destination_path: string): boolean {
+	if (!existsSync(destination_path)) {
+		copy_ai_file(source_path, destination_path)
+		console.info(`  ✔ created   ${WORKSPACE_YAML}`)
+
+		return false
+	}
+
+	const template = readFileSync(source_path, 'utf8')
+	const existing = readFileSync(destination_path, 'utf8')
+	const merged = init_logic.merge_workspace_yaml(existing, template)
+
+	if (merged !== existing) writeFileSync(destination_path, merged)
+	console.info(`  ✔ updated   ${WORKSPACE_YAML}`)
+
+	return false
+}
+
+function did_skip_ai_file_copy(filename: string): boolean {
+	const source_path = package_path(filename)
+	const destination_path = path.join(PROJECT_ROOT, filename)
+
+	if (filename === WORKSPACE_YAML) {
+		return did_skip_workspace_yaml_copy(source_path, destination_path)
+	}
+
+	return did_skip_copy_if_absent(source_path, destination_path, filename)
+}
+
+function did_skip_ai_file_mapping(source: string, destination: string): boolean {
+	return did_skip_copy_if_absent(
+		package_path(source),
+		path.join(PROJECT_ROOT, destination),
+		destination,
+	)
+}
+
+interface DirectorySkip {
+	reason: string
+	is_blocked: boolean
+}
+
+// Two different skips, and telling them apart is what keeps the advice honest. A destination that is
+// already a directory is `josh init` declining to overwrite, and `josh sync` is the answer. Anything
+// the shared guard blocks — a source the package does not carry, a destination that is a file or a
+// symlink — is a condition `josh sync` refuses in exactly the same way, so it is reported as a
+// warning and not with a hint that would send the user around the same loop. The blocker runs first
+// for that reason: it is the more specific reading of the same destination.
+function directory_copy_skip(
+	source_path: string,
+	destination_path: string,
+): DirectorySkip | undefined {
+	const blocker = directory_copy_blocker(source_path, destination_path)
+
+	if (blocker !== undefined) return { reason: blocker, is_blocked: true }
+
+	if (classify_path(destination_path) !== 'absent') {
+		return { reason: 'already exists — run josh sync to update', is_blocked: false }
+	}
+
+	return undefined
+}
+
+function report_directory_skip(directory_name: string, skip: DirectorySkip): void {
+	const line = `${directory_name}/ (${skip.reason})`
+
+	if (skip.is_blocked) console.warn(`  ⚠ skipped   ${line}`)
+	else console.info(`  ⏭ skipped   ${line}`)
+}
+
+// The boolean answers "would `josh sync` overwrite this?", which is what the hint at the end of the
+// run offers — not "did anything happen?". A blocked copy, and one whose walk failed part way, are
+// both refused by `sync` for the same reason they were refused here, so raising the hint on either
+// would send the user around the loop rather than at the cause.
+function did_copy_directory(directory_name: string): boolean {
+	const failure = copy_directory_failure(
+		package_path(directory_name),
+		path.join(PROJECT_ROOT, directory_name),
+	)
+
+	if (failure !== undefined) {
+		console.warn(`  ⚠ skipped   ${directory_name}/ (${failure})`)
+
+		return false
+	}
+
+	console.info(`  ✔ created   ${directory_name}/`)
+
+	return true
+}
+
+function did_skip_ai_directory_copy(directory_name: string): boolean {
+	const skip = directory_copy_skip(
+		package_path(directory_name),
+		path.join(PROJECT_ROOT, directory_name),
+	)
+
+	if (skip === undefined) {
+		did_copy_directory(directory_name)
+
+		return false
+	}
+
+	report_directory_skip(directory_name, skip)
+
+	return !skip.is_blocked
+}
+
+// `josh init` writes the one-line CLAUDE.md import when the consumer has none, and — like every other
+// AI file — leaves an existing one untouched so a consumer's additions are never disturbed. `josh sync`
+// is what ensures the import line on an existing file (sync.ts). CLAUDE.md is no longer byte-copied
+// (joshuafolkken/kit#1878), so it is handled here rather than through AI_COPY_FILES.
+function did_skip_claude_md_import(): boolean {
+	const destination_path = path.join(PROJECT_ROOT, CLAUDE_MD_FILENAME)
+
+	if (existsSync(destination_path)) {
+		console.info(`  ⏭ skipped   ${CLAUDE_MD_FILENAME} (already exists — run josh sync to update)`)
+
+		return true
+	}
+
+	writeFileSync(destination_path, init_logic.ensure_claude_md_import(undefined))
+	console.info(`  ✔ created   ${CLAUDE_MD_FILENAME}`)
+
+	return false
+}
+
+// Returns the repository name resolved for the Sonar config, so `josh init` can reuse it for the
+// security-updates report instead of spawning a second `gh repo view` (joshuafolkken/kit#805).
+// Resolving it here rather than in the caller keeps every AI-file write ahead of the network call.
+function run_ai_copies(): string | undefined {
+	const did_skip_claude_md = did_skip_claude_md_import()
+	const file_skips = init_logic
+		.get_ai_copy_files()
+		.map((filename) => did_skip_ai_file_copy(filename))
+	const mapping_skips = init_logic
+		.get_ai_copy_file_mappings()
+		.map(({ src: source, dest: destination }) => did_skip_ai_file_mapping(source, destination))
+	const directory_skips = init_logic
+		.get_ai_copy_directories()
+		.map((directory_name) => did_skip_ai_directory_copy(directory_name))
+	const has_skips = [did_skip_claude_md, ...file_skips, ...mapping_skips, ...directory_skips].some(
+		Boolean,
+	)
+
+	const name_with_owner = gh_spawn.get_repo_name_with_owner()
+
+	init_sonar.copy_sonar_with_template(name_with_owner)
+
+	if (has_skips) {
+		console.info('\n  💡 Run `josh sync` to overwrite skipped AI files with the latest version.')
+	}
+
+	return name_with_owner
+}
+
+const init_ai_copy = {
+	copy_ai_file,
+	run_ai_copies,
+}
+
+export { init_ai_copy }

package/scripts/init/init-copy-content.ts

@@ -0,0 +1,50 @@
+import { managed_marker_logic } from '#scripts/managed-marker/managed-marker-logic'
+import { workflow_pin_logic } from '#scripts/sync/workflow-pin-logic'
+import { KIT_PACKAGE_NAME } from '#scripts/version/kit-descriptor'
+import { claude_plugin_config } from './claude-plugin-config'
+import { hook_command_rewrite } from './hook-command-rewrite'
+import { init_logic } from './init-logic'
+
+/**
+ * The single transform applied to every file kit copies verbatim into a consumer
+ * repository, by both `josh init` and `josh sync`.
+ *
+ * Workflow destinations get two further passes. Their action pins are resolved from
+ * .github/workflows, so the committed template refs never have to be current; and they are
+ * stamped as written by this package, so the consumer's auto-merge workflow can tell a bump
+ * kit will overwrite from one the consumer owns. Keeping both write paths on this one
+ * function is what makes either guarantee hold: a path that called only
+ * transform_prompt_paths would ship whatever ref the template happens to carry, and an
+ * unstamped workflow would read as consumer-owned and merge itself into a revert loop. See
+ * workflow-pin-logic.ts for why the template refs are not authoritative, and
+ * managed-marker-logic.ts for why the stamp is on the file rather than in a list.
+ *
+ * The consumer's `.claude/settings.json` gets two further passes. The kit plugin's marketplace and
+ * `enabledPlugins` declaration is injected, because the skills that used to be copied now ship as the
+ * `kit` plugin and load from that declaration (joshuafolkken/kit#1879). And its hook commands are
+ * rewritten from `pnpm josh` to the published bundle invoked directly with node
+ * (joshuafolkken/kit#1930), so a consumer's guarded call does not pay a `pnpm` launch it never needed.
+ * Keeping both on this one function is the same guarantee as the workflow passes — a copy path that
+ * skipped the plugin block would ship a settings file that never enables the plugin, and one that
+ * skipped the rewrite would leave every consumer hook slower than it has to be.
+ */
+function transform_copied_content(destination_path: string, content: string): string {
+	const with_paths = init_logic.transform_distributed_paths(content)
+	const with_pins = workflow_pin_logic.apply_pins_for_destination(destination_path, with_paths)
+	const with_marker = managed_marker_logic.apply_marker_for_destination(
+		destination_path,
+		with_pins,
+		KIT_PACKAGE_NAME,
+	)
+	const with_plugin = claude_plugin_config.apply_plugin_config_for_destination(
+		destination_path,
+		with_marker,
+	)
+
+	return hook_command_rewrite.apply_hook_command_rewrite_for_destination(
+		destination_path,
+		with_plugin,
+	)
+}
+
+export { transform_copied_content }