@joshuafolkken/kit 1.983.0 → 1.1003.0

package/scripts/init/init-actions.ts

@@ -2,12 +2,14 @@ import { readFileSync } from 'node:fs'
 import path from 'node:path'
 import { json_format } from '#scripts/config-merge/json-format'
 import { string_array_schema, vscode_settings_schema } from '#scripts/lib/schemas'
+import { basic_path_migration } from './basic-path-migration'
 import { init_logic } from './init-logic'
 import { package_path, PROJECT_ROOT } from './init-paths'
 import type { ProjectShape } from './project-profile'
+import { session_language_environment } from './session-language-environment'
 
 const PRETTIER_CONFIG_JS = 'prettier.config.js'
-const STATIC_PRETTIER_CONFIG = 'prettier.config.mjs'
+const BASIC_PRETTIER_CONFIG = 'prettier.config.mjs'
 const VSCODE_EXTENSIONS_PATH = '.vscode/extensions.json'
 const VSCODE_SETTINGS_PATH = '.vscode/settings.json'
 const TSCONFIG_PATH = 'tsconfig.json'
@@ -17,6 +19,9 @@ interface FileAction {
 	dest: string
 	create: () => string
 	merge?: (existing: string) => string
+	// A merge that only migrates a kit-written line, for a file kit otherwise leaves to the project:
+	// when it changes nothing, the file is reported with the sample to add, as one with no merge is.
+	should_show_sample_when_unchanged?: boolean
 }
 
 function read_package_file(relative_path: string): string {
@@ -59,7 +64,7 @@ function build_vscode_actions(): ReadonlyArray<FileAction> {
 	]
 }
 
-const STATIC_EXTENSIONS = [
+const BASIC_EXTENSIONS = [
 	'streetsidesoftware.code-spell-checker',
 	'pkief.material-icon-theme',
 	'usernamehw.errorlens',
@@ -69,16 +74,16 @@ const STATIC_EXTENSIONS = [
 const PRETTIER_EXTENSION = 'esbenp.prettier-vscode'
 const DEFAULT_FORMATTER = 'editor.defaultFormatter'
 const FORMAT_ON_SAVE = 'editor.formatOnSave'
-const STATIC_LANGUAGES = ['[html]', '[css]', '[javascript]']
+const BASIC_LANGUAGES = ['[html]', '[css]', '[javascript]']
 
-function static_settings(): Record<string, Record<string, unknown>> {
+function basic_settings(): Record<string, Record<string, unknown>> {
 	const formatter = { [DEFAULT_FORMATTER]: PRETTIER_EXTENSION, [FORMAT_ON_SAVE]: true }
 
-	return Object.fromEntries(STATIC_LANGUAGES.map((language) => [language, formatter]))
+	return Object.fromEntries(BASIC_LANGUAGES.map((language) => [language, formatter]))
 }
 
-function build_static_settings_action(): FileAction {
-	const settings = static_settings()
+function build_basic_settings_action(): FileAction {
+	const settings = basic_settings()
 
 	return build_action(
 		VSCODE_SETTINGS_PATH,
@@ -87,10 +92,10 @@ function build_static_settings_action(): FileAction {
 	)
 }
 
-function build_static_vscode_actions(shape: ProjectShape): ReadonlyArray<FileAction> {
+function build_basic_vscode_actions(shape: ProjectShape): ReadonlyArray<FileAction> {
 	const recommendations = shape.has_web
-		? [...STATIC_EXTENSIONS, PRETTIER_EXTENSION]
-		: STATIC_EXTENSIONS
+		? [...BASIC_EXTENSIONS, PRETTIER_EXTENSION]
+		: BASIC_EXTENSIONS
 	const actions: Array<FileAction> = [
 		build_action(
 			VSCODE_EXTENSIONS_PATH,
@@ -99,12 +104,12 @@ function build_static_vscode_actions(shape: ProjectShape): ReadonlyArray<FileAct
 		),
 	]
 
-	if (shape.has_web) actions.push(build_static_settings_action())
+	if (shape.has_web) actions.push(build_basic_settings_action())
 
 	return actions
 }
 
-function build_static_tsconfig_action(): FileAction {
+function build_basic_tsconfig_action(): FileAction {
 	return build_action(
 		TSCONFIG_PATH,
 		() => json_format.format_json({ extends: init_logic.get_tsconfig_extends_entry() }),
@@ -187,26 +192,28 @@ function build_gitignore_action(): FileAction {
 	)
 }
 
-function build_static_actions(shape: ProjectShape): ReadonlyArray<FileAction> {
+function build_basic_actions(shape: ProjectShape): ReadonlyArray<FileAction> {
 	const actions: Array<FileAction> = []
 	if (shape.has_git) actions.push(build_gitignore_action())
-	if (shape.has_typescript) actions.push(build_static_tsconfig_action())
+	if (shape.has_typescript) actions.push(build_basic_tsconfig_action())
 
 	if (shape.has_web) {
 		actions.push({
-			dest: STATIC_PRETTIER_CONFIG,
+			dest: BASIC_PRETTIER_CONFIG,
 			create: () =>
-				"import { config } from '@joshuafolkken/kit/prettier/static'\n\nexport default config\n",
+				"import { config } from '@joshuafolkken/kit/prettier/basic'\n\nexport default config\n",
+			merge: (existing) => basic_path_migration.migrate_basic_paths(existing),
+			should_show_sample_when_unchanged: true,
 		})
 	}
 
-	actions.push(...build_static_vscode_actions(shape))
+	actions.push(...build_basic_vscode_actions(shape))
 
 	return actions
 }
 
 function build_file_actions(shape?: ProjectShape): ReadonlyArray<FileAction> {
-	if (shape?.profile === 'static') return build_static_actions(shape)
+	if (shape?.profile === 'basic') return build_basic_actions(shape)
 
 	return [
 		...(shape?.has_git === false ? [] : [build_gitignore_action()]),
@@ -226,10 +233,11 @@ function build_file_actions(shape?: ProjectShape): ReadonlyArray<FileAction> {
 		...build_config_file_actions().filter(
 			(action) => shape?.has_git !== false || action.dest !== LEFTHOOK_PATH,
 		),
+		...session_language_environment.build_session_lang_actions(),
 	]
 }
 
 const init_actions = { build_file_actions, read_package_json }
 
 export type { FileAction }
-export { init_actions, PRETTIER_CONFIG_JS }
+export { init_actions, PRETTIER_CONFIG_JS, BASIC_PRETTIER_CONFIG }

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

@@ -8,6 +8,8 @@ import {
 	copy_directory_failure,
 	directory_copy_blocker,
 } from '#scripts/sync/directory-copy-guard'
+import { basic_path_migration } from './basic-path-migration'
+import { distributed_paths } from './distributed-paths'
 import { transform_copied_content } from './init-copy-content'
 import { init_logic } from './init-logic'
 import { package_path, PROJECT_ROOT } from './init-paths'
@@ -16,12 +18,12 @@ import type { ProjectShape } from './project-profile'
 
 const WORKSPACE_YAML = 'pnpm-workspace.yaml'
 const CLAUDE_MD_FILENAME = 'CLAUDE.md'
-const STATIC_CLAUDE_IMPORT = '@node_modules/@joshuafolkken/kit/dist/CLAUDE.static.md'
+const BASIC_CLAUDE_IMPORT = '@node_modules/@joshuafolkken/kit/dist/CLAUDE.basic.md'
 const PRETTIER_IGNORE = '.prettierignore'
 const GIT_ATTRIBUTES = '.gitattributes'
 const CODE_OF_CONDUCT = 'CODE_OF_CONDUCT.md'
 const SECURITY_MD = 'SECURITY.md'
-const STATIC_AI_FILES = [
+const BASIC_AI_FILES = [
 	'AGENTS.md',
 	'GEMINI.md',
 	PRETTIER_IGNORE,
@@ -30,16 +32,16 @@ const STATIC_AI_FILES = [
 	SECURITY_MD,
 	WORKSPACE_YAML,
 ]
-// A static project gets its own template for these, not kit's development copy (joshuafolkken/kit#2693).
-const STATIC_SOURCES: Readonly<Record<string, string>> = {
-	[PRETTIER_IGNORE]: 'templates/prettierignore.static',
-	[WORKSPACE_YAML]: 'templates/pnpm-workspace.static.yaml',
+// A basic project gets its own template for these, not kit's development copy (joshuafolkken/kit#2693).
+const BASIC_SOURCES: Readonly<Record<string, string>> = {
+	[PRETTIER_IGNORE]: 'templates/prettierignore.basic',
+	[WORKSPACE_YAML]: 'templates/pnpm-workspace.basic.yaml',
 }
 const GITHUB_FILES = new Set([CODE_OF_CONDUCT, SECURITY_MD])
-const STATIC_POINTER_MAPPING = { src: 'templates/cursorrules.static', dest: '.cursorrules' }
+const BASIC_POINTER_MAPPING = { src: 'templates/cursorrules.basic', dest: '.cursorrules' }
 const PULL_REQUEST_TEMPLATE = '.github/pull_request_template.md'
 const RELEASE_CONFIG = '.github/release.yml'
-const STATIC_GITHUB_MAPPINGS = [
+const BASIC_GITHUB_MAPPINGS = [
 	{ src: PULL_REQUEST_TEMPLATE, dest: PULL_REQUEST_TEMPLATE },
 	{ src: RELEASE_CONFIG, dest: RELEASE_CONFIG },
 ]
@@ -117,9 +119,16 @@ function did_skip_workspace_yaml_copy(source_path: string, destination_path: str
 	return false
 }
 
+// The package file an AI file is copied from: a basic project gets its own template for a few of
+// them, every other file is copied from the path it is written to.
+function ai_file_source(filename: string, shape?: ProjectShape): string {
+	const basic_source = shape?.profile === 'basic' ? BASIC_SOURCES[filename] : undefined
+
+	return basic_source ?? filename
+}
+
 function did_skip_ai_file_copy(filename: string, shape?: ProjectShape): boolean {
-	const static_source = shape?.profile === 'static' ? STATIC_SOURCES[filename] : undefined
-	const source_path = package_path(static_source ?? filename)
+	const source_path = package_path(ai_file_source(filename, shape))
 	const destination_path = path.join(PROJECT_ROOT, filename)
 
 	if (filename === WORKSPACE_YAML) {
@@ -212,19 +221,61 @@ function did_skip_ai_directory_copy(directory_name: string): boolean {
 // 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.
+//
+// The one edit made to an existing file is the rules import written before joshuafolkken/kit#2829,
+// moved onto the basic path — only that kit-written line, never the consumer's additions.
+// An unreadable file is left as it is and reported as skipped, as it was before the migration.
+function read_if_readable(destination_path: string): string | undefined {
+	try {
+		return readFileSync(destination_path, 'utf8')
+	} catch {
+		return undefined
+	}
+}
+
+function report_existing_claude_md(destination_path: string): void {
+	const existing = read_if_readable(destination_path) ?? ''
+	const migrated = basic_path_migration.migrate_basic_paths(existing)
+
+	if (migrated === existing) {
+		console.info(`  ⏭ skipped   ${CLAUDE_MD_FILENAME} (already exists)`)
+
+		return
+	}
+
+	writeFileSync(destination_path, migrated)
+	console.info(`  ✔ updated   ${CLAUDE_MD_FILENAME} (rules import moved to the basic path)`)
+}
+
+function basic_claude_md(): string {
+	return `> If kit is not installed, run \`pnpm install\` first.\n\n${BASIC_CLAUDE_IMPORT}\n`
+}
+
+// A basic CLAUDE.md imports the basic rules alone: the full bootstrap and import are removed, a
+// pre-rename path is moved, and the basic header is restored when no basic import is left
+// (joshuafolkken/kit#2827). The project's own lines stay as they are.
+function ensure_basic_claude_md(existing: string | undefined): string {
+	if (existing === undefined) return basic_claude_md()
+	const kept = basic_path_migration.migrate_basic_paths(
+		distributed_paths.remove_claude_md_import(existing),
+	)
+
+	if (kept.includes(BASIC_CLAUDE_IMPORT)) return kept
+
+	return kept === '' ? basic_claude_md() : `${basic_claude_md()}\n${kept}`
+}
+
 function did_skip_claude_md_import(shape?: ProjectShape): boolean {
 	const destination_path = path.join(PROJECT_ROOT, CLAUDE_MD_FILENAME)
 
 	if (existsSync(destination_path)) {
-		console.info(`  ⏭ skipped   ${CLAUDE_MD_FILENAME} (already exists)`)
+		report_existing_claude_md(destination_path)
 
 		return true
 	}
 
 	const content =
-		shape?.profile === 'static'
-			? `> If kit is not installed, run \`pnpm install\` first.\n\n${STATIC_CLAUDE_IMPORT}\n`
-			: init_logic.ensure_claude_md_import(undefined)
+		shape?.profile === 'basic' ? basic_claude_md() : init_logic.ensure_claude_md_import(undefined)
 
 	writeFileSync(destination_path, content)
 	console.info(`  ✔ created   ${CLAUDE_MD_FILENAME}`)
@@ -251,8 +302,8 @@ function should_copy_github_file(filename: string, shape?: ProjectShape): boolea
 	return !GITHUB_FILES.has(filename) && !filename.startsWith('.github/')
 }
 
-function should_copy_static_file(filename: string, shape?: ProjectShape): boolean {
-	if (filename !== PRETTIER_IGNORE || shape?.profile !== 'static') return true
+function should_copy_basic_file(filename: string, shape?: ProjectShape): boolean {
+	if (filename !== PRETTIER_IGNORE || shape?.profile !== 'basic') return true
 
 	return shape.has_web
 }
@@ -261,35 +312,39 @@ function should_copy_ai_file(filename: string, shape?: ProjectShape): boolean {
 	return (
 		should_copy_git_file(filename, shape) &&
 		should_copy_github_file(filename, shape) &&
-		should_copy_static_file(filename, shape)
+		should_copy_basic_file(filename, shape)
 	)
 }
 
 function ai_files(shape?: ProjectShape): ReadonlyArray<string> {
-	const files = shape?.profile === 'static' ? STATIC_AI_FILES : init_logic.get_ai_copy_files()
+	const files = shape?.profile === 'basic' ? BASIC_AI_FILES : init_logic.get_ai_copy_files()
 
 	return files.filter((filename) => should_copy_ai_file(filename, shape))
 }
 
-function ai_mapping_skips(shape?: ProjectShape): ReadonlyArray<boolean> {
+type FileMappings = ReturnType<typeof init_logic.get_ai_copy_file_mappings>
+
+function ai_file_mappings(shape?: ProjectShape): FileMappings {
 	const mappings =
-		shape?.profile === 'static'
-			? [STATIC_POINTER_MAPPING, ...(shape.has_github ? STATIC_GITHUB_MAPPINGS : [])]
+		shape?.profile === 'basic'
+			? [BASIC_POINTER_MAPPING, ...(shape.has_github ? BASIC_GITHUB_MAPPINGS : [])]
 			: init_logic.get_ai_copy_file_mappings()
 
-	return mappings
-		.filter(({ dest }) => shape?.has_github !== false || !dest.startsWith('.github/'))
-		.map(({ src, dest }) => did_skip_ai_file_mapping(src, dest))
+	return mappings.filter(({ dest }) => shape?.has_github !== false || !dest.startsWith('.github/'))
+}
+
+function ai_mapping_skips(shape?: ProjectShape): ReadonlyArray<boolean> {
+	return ai_file_mappings(shape).map(({ src, dest }) => did_skip_ai_file_mapping(src, dest))
 }
 
 function repository_name(shape?: ProjectShape): string | undefined {
-	if (shape?.has_github === false || shape?.profile === 'static') return undefined
+	if (shape?.has_github === false || shape?.profile === 'basic') return undefined
 
 	return gh_spawn.get_repo_name_with_owner()
 }
 
 function report_sync_hint(has_skips: boolean, shape?: ProjectShape): void {
-	if (!has_skips || shape?.profile === 'static') return
+	if (!has_skips || shape?.profile === 'basic') return
 
 	console.info('\n  💡 Run `josh sync` to overwrite skipped AI files with the latest version.')
 }
@@ -307,7 +362,7 @@ function run_ai_copies(shape?: ProjectShape): string | undefined {
 
 	const name_with_owner = repository_name(shape)
 
-	if (shape?.profile !== 'static') init_sonar.copy_sonar_with_template(name_with_owner)
+	if (shape?.profile !== 'basic') init_sonar.copy_sonar_with_template(name_with_owner)
 
 	report_sync_hint(has_skips, shape)
 
@@ -318,6 +373,9 @@ const init_ai_copy = {
 	copy_ai_file,
 	run_ai_copies,
 	ai_files,
+	ai_file_source,
+	ai_file_mappings,
+	ensure_basic_claude_md,
 }
 
-export { init_ai_copy }
+export { init_ai_copy, CLAUDE_MD_FILENAME }

package/scripts/init/{init-static.ts → init-basic.ts}

@@ -10,7 +10,7 @@ function is_record(value: unknown): value is Record<string, unknown> {
 	return typeof value === 'object' && value !== null && !Array.isArray(value)
 }
 
-interface StaticVersions {
+interface BasicVersions {
 	kit: string
 	prettier: string
 }
@@ -30,10 +30,10 @@ function with_recorded_profile(content: string, profile: ProjectShape['profile']
 	return json_format.format_json(manifest)
 }
 
-function merge_static_manifest(
+function merge_basic_manifest(
 	content: string,
 	shape: ProjectShape,
-	versions: StaticVersions,
+	versions: BasicVersions,
 ): string {
 	const with_profile = with_recorded_profile(content, shape.profile)
 	const with_script = init_logic.merge_package_scripts(with_profile, {
@@ -50,6 +50,6 @@ function merge_static_manifest(
 	return init_logic.sort_package_json_keys(with_prettier)
 }
 
-const init_static = { initial_manifest, with_recorded_profile, merge_static_manifest }
-export { init_static }
-export type { StaticVersions }
+const init_basic = { initial_manifest, with_recorded_profile, merge_basic_manifest }
+export { init_basic }
+export type { BasicVersions }

package/scripts/init/init-bootstrap.ts

@@ -3,13 +3,14 @@ import path from 'node:path'
 import { z } from 'zod'
 import { init_install, type InstallStep } from './init-install'
 import { init_logic_workspace } from './init-logic-workspace'
+import { project_profile } from './project-profile'
 
 const KIT_PACKAGE_NAME = '@joshuafolkken/kit'
 const NODE_MODULES = 'node_modules'
 const PACKAGE_JSON = 'package.json'
-// The static template lists exactly the build scripts kit's own dependency tree carries, which is
+// The basic template lists exactly the build scripts kit's own dependency tree carries, which is
 // what installing kit alone needs approved (joshuafolkken/kit#2785).
-const KIT_BUILDS_TEMPLATE = 'templates/pnpm-workspace.static.yaml'
+const KIT_BUILDS_TEMPLATE = 'templates/pnpm-workspace.basic.yaml'
 const HANDOFF_FAILURE = 'josh init from the project-installed kit failed — see the output above'
 // Set on the handed-off run, so a kit that still does not find itself installed in the project — pnpm
 // put it somewhere else — stops instead of installing and handing off again without end.
@@ -62,7 +63,7 @@ function kit_install_step(has_kit: boolean, template: string): InstallStep {
 }
 
 function handoff_step(args: ReadonlyArray<string>): InstallStep {
-	const handoff_args = ['exec', 'josh', 'init', ...args]
+	const handoff_args = ['exec', 'josh', 'init', ...project_profile.with_legacy_profile_names(args)]
 
 	return {
 		label: `pnpm ${handoff_args.join(' ')}`,

package/scripts/init/init-install.ts

@@ -51,7 +51,7 @@ function did_step_succeed(step: InstallStep, project_root: string): boolean {
 
 // Returns the failure to report, or undefined once the install passed. A failed install stops
 // there: `josh format` runs prettier and the kit itself, both of which the install provides. A failed
-// format does not fail `init` — in a node project it also runs `eslint --fix`, which exits non-zero on
+// format does not fail `init` — in a full project it also runs `eslint --fix`, which exits non-zero on
 // the project's own unfixable errors, and those are the project's result, not the setup's (the
 // reason `josh gate` is left out of `init` too).
 function run_post_init_steps(project_root: string): string | undefined {

package/scripts/init/init-logic-templates.ts

@@ -132,7 +132,7 @@ ${stylesheet_line}}
 }
 
 // A named stylesheet is kept only while it exists: kit ≤1.929 wrote the SvelteKit default into every
-// node project, and keeping that line would leave `josh sync` unable to repair the aborting format.
+// full project, and keeping that line would leave `josh sync` unable to repair the aborting format.
 function existing_stylesheet(existing: string, project_root: string): string | undefined {
 	const named = TAILWIND_STYLESHEET_PATTERN.exec(existing)?.[1]
 

package/scripts/init/init-logic.ts

@@ -230,7 +230,7 @@ const PRETTIER_PLUGIN_DEV_DEPS: Record<string, string> = {
 // format_json rather than JSON.stringify: it lays arrays out the way prettier does — inline while
 // they fit within printWidth, one element per line once they do not — so the file kit writes is
 // `prettier --check`-clean in the consumer whatever the entry count happens to be (#660).
-// TypeScript 6 defaults `types` to `[]`, so a node project sees no `process` global — not even in the
+// TypeScript 6 defaults `types` to `[]`, so a full project sees no `process` global — not even in the
 // generated `playwright.config.ts` — until the Node types are named (joshuafolkken/kit#2710).
 function generate_tsconfig(): string {
 	return json_format.format_json({

package/scripts/init/init.ts

@@ -15,11 +15,12 @@ import { execaSync } from 'execa'
 import { z } from 'zod'
 import { init_actions, PRETTIER_CONFIG_JS, type FileAction } from './init-actions'
 import { init_ai_copy } from './init-ai-copy'
+import { init_basic } from './init-basic'
 import { init_bootstrap } from './init-bootstrap'
 import { init_install } from './init-install'
 import { init_logic } from './init-logic'
 import { PACKAGE_DIR, PROJECT_ROOT } from './init-paths'
-import { init_static } from './init-static'
+import { kit_setup_state } from './kit-setup-state'
 import { plugin_install_hint_module } from './plugin-install-hint'
 import { project_profile, type ProjectProfile, type ProjectShape } from './project-profile'
 
@@ -30,7 +31,7 @@ const SAMPLE_INDENT_WIDTH = 4
 const ARGUMENT_START_INDEX = 2
 const SAMPLE_INDENT = ' '.repeat(SAMPLE_INDENT_WIDTH)
 const INSTALL_HINT = '→ run `pnpm install` to install what package.json lists'
-const INIT_USAGE = 'josh init [--profile static|node] [--no-install]'
+const INIT_USAGE = 'josh init [--profile basic|full] [--no-install]'
 
 function write_new_file(action: FileAction, destination_path: string): void {
 	mkdirSync(path.dirname(destination_path), { recursive: true })
@@ -44,22 +45,27 @@ function show_sample(action: FileAction): void {
 	console.info(action.create().replaceAll(/^/gmu, () => SAMPLE_INDENT))
 }
 
+function report_unchanged(action: FileAction): void {
+	if (action.should_show_sample_when_unchanged === true) show_sample(action)
+	else console.info(`  ✔ unchanged ${action.dest}`)
+}
+
 function merge_existing_file(
 	merge_function: (existing: string) => string,
 	destination_path: string,
-	destination: string,
+	action: FileAction,
 ): void {
 	const existing = readFileSync(destination_path, 'utf8')
 	const merged = merge_function(existing)
 
 	if (merged === existing) {
-		console.info(`  ✔ unchanged ${destination}`)
+		report_unchanged(action)
 
 		return
 	}
 
 	writeFileSync(destination_path, merged)
-	console.info(`  ✔ updated   ${destination}`)
+	console.info(`  ✔ updated   ${action.dest}`)
 }
 
 function execute_file_action(action: FileAction): void {
@@ -78,7 +84,7 @@ function execute_file_action(action: FileAction): void {
 		return
 	}
 
-	merge_existing_file(action.merge, destination_path, action.dest)
+	merge_existing_file(action.merge, destination_path, action)
 }
 
 const engine_pin_schema = z.looseObject({ name: z.string(), version: z.string() })
@@ -181,7 +187,7 @@ function apply_package_json_merges(content: string, has_git = true): string {
 	return package_manager_version.align_development_engines_version(sorted)
 }
 
-function get_static_versions(): { kit: string; prettier: string } {
+function get_basic_versions(): { kit: string; prettier: string } {
 	const manifest = z
 		.object({
 			version: z.string(),
@@ -195,11 +201,11 @@ function get_static_versions(): { kit: string; prettier: string } {
 }
 
 function merged_manifest(existing: string, shape: ProjectShape): string {
-	if (shape.profile === 'static') {
-		return init_static.merge_static_manifest(existing, shape, get_static_versions())
+	if (shape.profile === 'basic') {
+		return init_basic.merge_basic_manifest(existing, shape, get_basic_versions())
 	}
 
-	return init_static.with_recorded_profile(
+	return init_basic.with_recorded_profile(
 		apply_package_json_merges(existing, shape.has_git),
 		shape.profile,
 	)
@@ -210,7 +216,7 @@ function merge_project_package_json(shape: ProjectShape): void {
 	const is_existing = existsSync(package_json_path)
 	const existing = is_existing
 		? readFileSync(package_json_path, 'utf8')
-		: init_static.initial_manifest()
+		: init_basic.initial_manifest()
 	const merged = merged_manifest(existing, shape)
 
 	if (is_existing && merged === existing) {
@@ -246,7 +252,7 @@ function run_config_file_actions(shape: ProjectShape): void {
 	console.info('Config files:')
 
 	if (
-		shape.profile === 'node' &&
+		shape.profile === 'full' &&
 		sync.migrate_prettierrc(path.join(PROJECT_ROOT, PRETTIER_CONFIG_JS))
 	) {
 		console.info('  ✔ migrated  .prettierrc → prettier.config.js')
@@ -286,7 +292,7 @@ function run_ai_file_actions(shape: ProjectShape): void {
 
 	if (shape.has_github) report_repository_settings(name_with_owner)
 
-	if (shape.profile === 'node') plugin_install_hint_module.report_plugin_install_hint()
+	if (shape.profile === 'full') plugin_install_hint_module.report_plugin_install_hint()
 }
 
 function initialize_project(shape: ProjectShape): void {
@@ -298,14 +304,14 @@ function initialize_project(shape: ProjectShape): void {
 	merge_project_package_json(shape)
 
 	run_ai_file_actions(shape)
-	if (shape.profile === 'node') project_config.sync_project_config(PROJECT_ROOT)
+	if (shape.profile === 'full') project_config.sync_project_config(PROJECT_ROOT)
 }
 
 // A tool `init` just listed is absent until the user installs it — and `josh lint` then fails on it
 // rather than skipping it (joshuafolkken/kit#2709). Saying so is what tells the user the next step.
 function report_manual_install(shape: ProjectShape): void {
 	console.info(`\nDependencies:\n  ${INSTALL_HINT}`)
-	if (shape.has_git && shape.profile === 'node') install_lefthook()
+	if (shape.has_git && shape.profile === 'full') install_lefthook()
 }
 
 // The install runs the `prepare` script, which installs the git hooks. A failure is thrown rather
@@ -340,18 +346,34 @@ function set_up_project(requested: ProjectProfile | undefined, is_install: boole
 	console.info('\n✅ Done.\n')
 }
 
-function main(args: ReadonlyArray<string> = []): void {
-	if (did_refuse_self_run(PACKAGE_DIR, PROJECT_ROOT)) return
+// True when this process set the project up — false when it refused, or handed the run to the
+// project's own kit, which then speaks for itself.
+function main(args: ReadonlyArray<string> = []): boolean {
+	if (did_refuse_self_run(PACKAGE_DIR, PROJECT_ROOT)) return false
 	const { is_install, rest } = init_install.split_install_flag(args)
 	// Validated before the hand-off, so a malformed invocation is refused before kit is installed.
 	const requested = project_profile.requested_profile(rest, INIT_USAGE)
 
-	if (!is_install || !did_hand_off(args)) set_up_project(requested, is_install)
+	const is_set_up_here = !is_install || !did_hand_off(args)
+
+	if (is_set_up_here) set_up_project(requested, is_install)
+
+	return is_set_up_here
+}
+
+// Only the command a person typed points onward to `josh start`: `josh start` calls `main` itself and
+// is already the next step (joshuafolkken/kit#2816).
+// A setup that failed after writing, such as a failed install, sets the exit code and points nowhere.
+function print_start_hint(): void {
+	if (process.exitCode !== undefined && process.exitCode !== 0) return
+	const hint = kit_setup_state.start_hint(PROJECT_ROOT)
+
+	if (hint !== undefined) console.info(`${hint}\n`)
 }
 
 function run_cli(args: ReadonlyArray<string>): void {
 	try {
-		main(args)
+		if (main(args)) print_start_hint()
 	} catch (error) {
 		console.error(`\n✖ ${error instanceof Error ? error.message : String(error)}\n`)
 		process.exitCode = 1

package/scripts/init/kit-setup-state.ts

@@ -0,0 +1,30 @@
+import { KIT_PACKAGE_NAME } from '#scripts/version/kit-descriptor'
+import { start_exec } from './start-exec'
+
+const START_HINT =
+	'To use the GitHub Issue workflow, run pnpm exec josh start next: it puts this setup on GitHub, through a pull request when main already has commits.'
+
+// Whether the commit checked out records kit in its manifest — the sign that kit's setup has already
+// reached the branch, so `josh start` has no setup pull request to open (joshuafolkken/kit#2816).
+function is_kit_committed(root: string): boolean {
+	// `./` resolves the path from `root` rather than from the repository's top level.
+	const manifest = start_exec.read_output('git', ['show', 'HEAD:./package.json'], root)
+
+	return manifest?.includes(`"${KIT_PACKAGE_NAME}"`) ?? false
+}
+
+function is_git_work_tree(root: string): boolean {
+	return start_exec.succeeds('git', ['rev-parse', '--is-inside-work-tree'], root)
+}
+
+// The line `josh init` ends with in a Git repository whose checkout does not hold kit yet: the setup is
+// still uncommitted, and `josh start` is what carries it to GitHub.
+function start_hint(root: string): string | undefined {
+	if (!is_git_work_tree(root) || is_kit_committed(root)) return undefined
+
+	return START_HINT
+}
+
+const kit_setup_state = { is_kit_committed, start_hint }
+
+export { kit_setup_state }

package/scripts/init/kit-written-paths.ts

@@ -0,0 +1,33 @@
+import { PROJECT_CONFIG_FILE } from '#scripts/safe-chain/project-config'
+import { managed_config_scope } from '#scripts/sync/managed-config-scope'
+import { BASIC_PRETTIER_CONFIG } from './init-actions'
+import { CLAUDE_MD_FILENAME } from './init-ai-copy'
+
+const MANIFEST_FILE = 'package.json'
+const LOCKFILE = 'pnpm-lock.yaml'
+
+// The paths `josh init` writes beyond what `managed_config_scope` enumerates. They stay out of that
+// scope on purpose: it also answers the pull-request gate on distributed config, which leaves
+// CLAUDE.md out by design. The manifest and lockfile are written by the install `josh init` runs.
+const SETUP_ONLY_PATHS: ReadonlySet<string> = new Set([
+	CLAUDE_MD_FILENAME,
+	BASIC_PRETTIER_CONFIG,
+	PROJECT_CONFIG_FILE,
+	MANIFEST_FILE,
+	LOCKFILE,
+])
+
+// Whether a changed path is one kit's setup wrote — what the setup pull request of `josh start`
+// carries, so a file the user keeps beside it (notes, an editor's own directory) never rides along
+// (joshuafolkken/kit#2816).
+function is_kit_written(file_path: string): boolean {
+	return SETUP_ONLY_PATHS.has(file_path) || managed_config_scope.has_managed_path([file_path])
+}
+
+function select(paths: ReadonlyArray<string>): Array<string> {
+	return paths.filter((file_path) => is_kit_written(file_path))
+}
+
+const kit_written_paths = { is_kit_written, select }
+
+export { kit_written_paths }