infra-kit 0.1.114 → 0.1.115

package/src/commands/init/__tests__/migrate-factory-config.test.ts

@@ -0,0 +1,93 @@
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+import { logger } from 'src/lib/logger'
+
+import { migrateFactoryConfigToJson } from '../migrate-config'
+
+let home: string
+let dir: string
+let oldTs: string
+let newJson: string
+let infoSpy: ReturnType<typeof vi.spyOn>
+
+const messages = (): string => {
+  return infoSpy.mock.calls
+    .map((c: unknown[]) => {
+      return String(c[0])
+    })
+    .join('\n')
+}
+
+beforeEach(() => {
+  home = fs.mkdtempSync(path.join(os.tmpdir(), 'migrate-factory-test-'))
+  vi.spyOn(os, 'homedir').mockReturnValue(home)
+  dir = path.join(home, '.infra-kit')
+  oldTs = path.join(dir, 'vendor.config.ts')
+  newJson = path.join(dir, 'vendor.json')
+  fs.mkdirSync(dir, { recursive: true })
+  infoSpy = vi.spyOn(logger, 'info').mockImplementation(() => {})
+})
+
+afterEach(() => {
+  vi.restoreAllMocks()
+  fs.rmSync(home, { recursive: true, force: true })
+})
+
+describe('migrateFactoryConfigToJson', () => {
+  it('converts an object-form vendor.config.ts to vendor.json and removes the .ts (plain ✓, no warning)', async () => {
+    fs.writeFileSync(oldTs, `export default { workspaceDir: '~/projects', targets: ['repo-a'] }`)
+
+    await migrateFactoryConfigToJson()
+
+    expect(fs.existsSync(oldTs)).toBe(false)
+    expect(JSON.parse(fs.readFileSync(newJson, 'utf-8'))).toEqual({ workspaceDir: '~/projects', targets: ['repo-a'] })
+    expect(messages()).toMatch(/✓ Migrated/)
+    expect(messages()).not.toMatch(/STATIC SNAPSHOT/)
+  })
+
+  it('converts a factory-function form AND emits the STATIC SNAPSHOT warning (not a plain ✓)', async () => {
+    fs.writeFileSync(oldTs, `export default () => ({ workspaceDir: '/abs/repos', targets: ['repo-b'] })`)
+
+    await migrateFactoryConfigToJson()
+
+    expect(fs.existsSync(oldTs)).toBe(false)
+    expect(JSON.parse(fs.readFileSync(newJson, 'utf-8'))).toEqual({ workspaceDir: '/abs/repos', targets: ['repo-b'] })
+    expect(messages()).toMatch(/STATIC SNAPSHOT/)
+    expect(messages()).not.toMatch(/✓ Migrated/)
+  })
+
+  it('is a no-op when there is no legacy vendor.config.ts (idempotent)', async () => {
+    await migrateFactoryConfigToJson()
+
+    expect(fs.existsSync(newJson)).toBe(false)
+    expect(infoSpy).not.toHaveBeenCalled()
+  })
+
+  it('never overwrites an existing vendor.json; leaves the .ts in place and warns', async () => {
+    const existing = { workspaceDir: '~/active', targets: ['keep-me'] }
+
+    fs.writeFileSync(oldTs, `export default { workspaceDir: '~/stale', targets: ['old'] }`)
+    fs.writeFileSync(newJson, JSON.stringify(existing))
+
+    await migrateFactoryConfigToJson()
+
+    // Active vendor.json untouched; the stale .ts is preserved (not deleted).
+    expect(JSON.parse(fs.readFileSync(newJson, 'utf-8'))).toEqual(existing)
+    expect(fs.existsSync(oldTs)).toBe(true)
+    expect(messages()).toMatch(/already exists/)
+  })
+
+  it('leaves an invalid old .ts in place (non-fatal) and writes no vendor.json', async () => {
+    // Missing required `targets` → fails factoryConfigSchema.
+    fs.writeFileSync(oldTs, `export default { workspaceDir: '~/projects' }`)
+
+    await expect(migrateFactoryConfigToJson()).resolves.toBeUndefined()
+
+    expect(fs.existsSync(oldTs)).toBe(true)
+    expect(fs.existsSync(newJson)).toBe(false)
+    expect(messages()).toMatch(/invalid factory config/)
+  })
+})

package/src/commands/init/__tests__/seed-user-global-config.test.ts

@@ -0,0 +1,64 @@
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+import { seedUserGlobalConfig } from '../init'
+
+let home: string
+let dir: string
+
+beforeEach(() => {
+  home = fs.mkdtempSync(path.join(os.tmpdir(), 'seed-user-global-test-'))
+  vi.spyOn(os, 'homedir').mockReturnValue(home)
+  dir = path.join(home, '.infra-kit')
+})
+
+afterEach(() => {
+  vi.restoreAllMocks()
+  fs.rmSync(home, { recursive: true, force: true })
+})
+
+describe('seedUserGlobalConfig', () => {
+  it('seeds the infra-kit.json stub and both fully-commented example files', () => {
+    seedUserGlobalConfig()
+
+    expect(fs.readFileSync(path.join(dir, 'infra-kit.json'), 'utf-8')).toBe('{}\n')
+
+    const infraExample = fs.readFileSync(path.join(dir, 'infra-kit.example.jsonc'), 'utf-8')
+
+    // Every recognized infra-kit property is documented.
+    for (const key of ['environments', 'envManagement', 'ide', 'taskManager', 'worktrees']) {
+      expect(infraExample).toContain(key)
+    }
+
+    const vendorExample = fs.readFileSync(path.join(dir, 'vendor.example.jsonc'), 'utf-8')
+
+    expect(vendorExample).toContain('workspaceDir')
+    expect(vendorExample).toContain('targets')
+  })
+
+  it('never seeds a real vendor.json (only the example)', () => {
+    seedUserGlobalConfig()
+
+    expect(fs.existsSync(path.join(dir, 'vendor.example.jsonc'))).toBe(true)
+    expect(fs.existsSync(path.join(dir, 'vendor.json'))).toBe(false)
+  })
+
+  it('refreshes the example files on a re-run while leaving an existing infra-kit.json byte-unchanged', () => {
+    fs.mkdirSync(dir, { recursive: true })
+    const realConfig = '{ "environments": ["dev"] }\n'
+
+    fs.writeFileSync(path.join(dir, 'infra-kit.json'), realConfig)
+    // Stale example a previous version might have written.
+    fs.writeFileSync(path.join(dir, 'infra-kit.example.jsonc'), '// stale\n')
+
+    seedUserGlobalConfig()
+
+    // Real config preserved exactly…
+    expect(fs.readFileSync(path.join(dir, 'infra-kit.json'), 'utf-8')).toBe(realConfig)
+    // …examples refreshed to the current template (no longer "stale").
+    expect(fs.readFileSync(path.join(dir, 'infra-kit.example.jsonc'), 'utf-8')).not.toBe('// stale\n')
+    expect(fs.existsSync(path.join(dir, 'vendor.example.jsonc'))).toBe(true)
+  })
+})

package/src/commands/init/__tests__/shell-body.test.ts

@@ -0,0 +1,30 @@
+import { describe, expect, it } from 'vitest'
+
+import { buildShellBody } from '../init'
+
+describe('buildShellBody — env auto-load shell-startup block', () => {
+  const body = buildShellBody()
+
+  it('defines and invokes the one-shot startup autoload function', () => {
+    expect(body).toContain('_infra_kit_startup_autoload()')
+    expect(body).toContain('_infra_kit_startup_autoload\n')
+  })
+
+  it('gates on a session and skips subshells that already inherited an env', () => {
+    expect(body).toContain('[[ -z "$INFRA_KIT_SESSION" ]] && return')
+    expect(body).toContain('[[ -n "$INFRA_KIT_ENV_CONFIG" ]] && return')
+  })
+
+  it('walks up for infra-kit.json (project/worktree gate) before spawning node', () => {
+    expect(body).toContain('[[ -f "$dir/infra-kit.json" ]]')
+    expect(body).toContain('while [[ "$dir" != / ]]')
+  })
+
+  it('spawns env-autoload backgrounded and silenced (precmd does the sourcing)', () => {
+    expect(body).toContain('infra-kit env-autoload & ) >/dev/null 2>&1')
+  })
+
+  it('keeps the precmd hook as the sole sourcer of env-load.sh', () => {
+    expect(body).toContain('add-zsh-hook precmd _infra_kit_autoload')
+  })
+})

package/src/commands/init/agent-files.ts

@@ -3,7 +3,7 @@ import path from 'node:path'
 
 import { getInfraKitConfigPaths } from 'src/lib/infra-kit-config'
 import { logger } from 'src/lib/logger'
-import { hasManagedBlock, upsertManagedBlock } from 'src/lib/managed-block'
+import { hasManagedBlock, removeManagedBlock, upsertManagedBlock } from 'src/lib/managed-block'
 
 import packageJson from '../../../package.json' with { type: 'json' }
 
@@ -13,23 +13,18 @@ export const AGENTS_MARKER_END = '<!-- infra-kit:end -->'
 /** The version line lives on its own line (OMC `OMC:VERSION:` precedent) so the markers stay constant-matchable. */
 const AGENTS_VERSION_PREFIX = '<!-- infra-kit:version '
 
-/** Separate marker pair for the small `@AGENTS.md` import region injected into CLAUDE.md. */
+/**
+ * Marker pair for the legacy `@AGENTS.md` import region once injected into CLAUDE.md.
+ * Migration-only now: `writeAgentFiles` strips this region so the full guidance body
+ * can take its place. TODO(remove after ~2 release cycles once repos have re-run init).
+ */
 export const AGENTS_IMPORT_START = '<!-- infra-kit:import:begin -->'
 export const AGENTS_IMPORT_END = '<!-- infra-kit:import:end -->'
 
 const AGENTS_FILE = 'AGENTS.md'
 const CLAUDE_FILE = 'CLAUDE.md'
-const CURSOR_RULE_REL = path.join('.cursor', 'rules', 'infra-kit.mdc')
 
-const CURSOR_FRONTMATTER = [
-  '---',
-  'description: infra-kit CLI usage and conventions',
-  'alwaysApply: true',
-  '---',
-  '',
-].join('\n')
-
-export type WriteAction = 'created' | 'updated' | 'unchanged'
+export type WriteAction = 'created' | 'updated' | 'unchanged' | 'removed'
 
 export interface AgentFileWrite {
   path: string
@@ -66,9 +61,9 @@ const buildAgentsBody = (version: string): string => {
     '## Commands (`ik` = `pnpm exec infra-kit`)',
     '',
     '- `ik env-load -c <config>` / `ik env-clear` / `ik env-status` — load, clear, or inspect Doppler env vars for a config (e.g. `dev`). Source the returned file to apply.',
-    '- `ik worktrees-add` / `worktrees-list` / `worktrees-open` / `worktrees-remove` / `worktrees-sync` — manage release and feature git worktrees.',
-    '- `ik release-create` / `release-list` / `release-deploy-all` / `release-deploy-selected` / `release-deliver` / `release-desc-edit` — release-branch and deploy flow.',
-    '- `ik merge-dev` — merge the dev branch into every release branch.',
+    '- `ik worktrees add` / `worktrees list` / `worktrees reload` / `worktrees remove` / `worktrees sync` — manage release and feature git worktrees.',
+    '- `ik release create` / `release list` / `release deploy-all` / `release deploy-selected` / `release deliver` / `release desc-edit` — release-branch and deploy flow.',
+    '- `ik release merge-dev` — merge the dev branch into every release branch.',
     '- `ik audit` — audit packages against `infra-kit.config.ts` rules.',
     '- `ik doctor` — check gh / doppler / aws / rtk install + auth and repo setup.',
     '- `ik init` — (re)install shell integration and regenerate these agent-instruction files.',
@@ -86,6 +81,13 @@ const assertNotSymlink = (filePath: string): void => {
   }
 }
 
+/** Copy a file to a timestamped `<file>.backup.<timestamp>` sibling. */
+const backupFile = (filePath: string): void => {
+  const stamp = new Date().toISOString().replace(/[:.]/g, '-')
+
+  fs.copyFileSync(filePath, `${filePath}.backup.${stamp}`)
+}
+
 /**
  * Write `nextContent` to `filePath` with OMC-style safety: refuse symlinks,
  * back up the prior file with a timestamp before overwriting, and skip the
@@ -99,11 +101,7 @@ const writeManaged = (filePath: string, nextContent: string): WriteAction => {
 
   if (previous === nextContent) return 'unchanged'
 
-  if (existed) {
-    const stamp = new Date().toISOString().replace(/[:.]/g, '-')
-
-    fs.copyFileSync(filePath, `${filePath}.backup.${stamp}`)
-  }
+  if (existed) backupFile(filePath)
 
   fs.mkdirSync(path.dirname(filePath), { recursive: true })
   fs.writeFileSync(filePath, nextContent, 'utf-8')
@@ -124,10 +122,39 @@ const assertBlockPresent = (filePath: string, start: string, end: string): void
 }
 
 /**
- * Generate (or refresh) the repo agent-instruction files: the `AGENTS.md`
- * guidance block, a managed `@AGENTS.md` import region in `CLAUDE.md`
- * (preserving existing content), and a `.cursor/rules` rule file. Repo-gated:
- * a no-op outside an infra-kit repo. Idempotent and non-destructive.
+ * Migrate a legacy `AGENTS.md` now that the guidance lives solely in `CLAUDE.md`.
+ * Strips the infra-kit managed block, then asymmetrically:
+ * - no infra-kit block at all (hand-authored, not ours) → leave untouched (`unchanged`),
+ * - file was purely generated (nothing but whitespace remains) → back up + delete (`removed`),
+ * - hand-authored content surrounds the block → back up + write the block-free remainder (`updated`).
+ * Every destructive path leaves a timestamped `.backup.` first.
+ */
+const migrateLegacyAgentsFile = (agentsPath: string): WriteAction => {
+  if (!fs.existsSync(agentsPath)) return 'unchanged'
+
+  assertNotSymlink(agentsPath)
+
+  const content = fs.readFileSync(agentsPath, 'utf-8')
+  const stripped = removeManagedBlock(content, AGENTS_MARKER_START, AGENTS_MARKER_END)
+
+  if (stripped === null) return 'unchanged'
+
+  if (stripped.trim() === '') {
+    backupFile(agentsPath)
+    fs.rmSync(agentsPath)
+
+    return 'removed'
+  }
+
+  return writeManaged(agentsPath, stripped)
+}
+
+/**
+ * Generate (or refresh) the repo agent-instruction guidance, now hosted solely in
+ * `CLAUDE.md` (preserving hand-authored content outside the markers). Also migrates
+ * legacy setups — stripping the old `@AGENTS.md` import region from `CLAUDE.md` and
+ * backing up/removing a now-redundant `AGENTS.md`. Repo-gated: a no-op outside an
+ * infra-kit repo. Idempotent (within a CLI version) and non-destructive.
  *
  * @example
  * await writeAgentFiles()
@@ -156,40 +183,33 @@ export const writeAgentFiles = async (): Promise<WriteAgentFilesResult> => {
 
   const agentsPath = path.join(root, AGENTS_FILE)
   const claudePath = path.join(root, CLAUDE_FILE)
-  const cursorPath = path.join(root, CURSOR_RULE_REL)
 
-  const agentsContent = upsertManagedBlock({
-    content: readOr(agentsPath, ''),
-    body,
-    startMarker: AGENTS_MARKER_START,
-    endMarker: AGENTS_MARKER_END,
-  })
+  // CLAUDE.md now hosts the full guidance body. Strip the legacy `@AGENTS.md`
+  // import region first (if present), then upsert the body under the begin/end
+  // markers — disjoint marker pairs, so the two operations never collide.
+  let claudeContent = readOr(claudePath, '')
 
-  const claudeContent = upsertManagedBlock({
-    content: readOr(claudePath, ''),
-    body: `@${AGENTS_FILE}`,
-    startMarker: AGENTS_IMPORT_START,
-    endMarker: AGENTS_IMPORT_END,
-  })
-
-  const cursorContent = upsertManagedBlock({
-    content: readOr(cursorPath, CURSOR_FRONTMATTER),
+  claudeContent = removeManagedBlock(claudeContent, AGENTS_IMPORT_START, AGENTS_IMPORT_END) ?? claudeContent
+  claudeContent = upsertManagedBlock({
+    content: claudeContent,
     body,
     startMarker: AGENTS_MARKER_START,
     endMarker: AGENTS_MARKER_END,
+    placement: 'replace-in-place',
   })
 
+  // CLAUDE.md is the only file we manage. A legacy AGENTS.md is migrated away.
   const written: AgentFileWrite[] = [
-    { path: agentsPath, action: writeManaged(agentsPath, agentsContent) },
     { path: claudePath, action: writeManaged(claudePath, claudeContent) },
-    { path: cursorPath, action: writeManaged(cursorPath, cursorContent) },
+    { path: agentsPath, action: migrateLegacyAgentsFile(agentsPath) },
   ]
 
-  assertBlockPresent(agentsPath, AGENTS_MARKER_START, AGENTS_MARKER_END)
-  assertBlockPresent(claudePath, AGENTS_IMPORT_START, AGENTS_IMPORT_END)
-  assertBlockPresent(cursorPath, AGENTS_MARKER_START, AGENTS_MARKER_END)
+  assertBlockPresent(claudePath, AGENTS_MARKER_START, AGENTS_MARKER_END)
 
   for (const file of written) {
+    // Always report CLAUDE.md; only mention a migrated file when it actually changed.
+    if (file.action === 'unchanged' && file.path !== claudePath) continue
+
     logger.info(`  ${file.action.padEnd(9)} ${path.relative(root, file.path)}`)
   }
 

package/src/commands/init/init.ts

@@ -1,12 +1,18 @@
 import fs from 'node:fs'
 import os from 'node:os'
 import path from 'node:path'
+import process from 'node:process'
 
 import { logger } from 'src/lib/logger'
 import { removeManagedBlock, upsertManagedBlock } from 'src/lib/managed-block'
 
 import { writeAgentFiles } from './agent-files'
-import { migrateLegacyConfig, normalizeLegacyIdeStructures } from './migrate-config'
+import {
+  migrateFactoryConfigToJson,
+  migrateLegacyConfig,
+  migrateUserGlobalConfigFilename,
+  normalizeLegacyIdeStructures,
+} from './migrate-config'
 
 export const MARKER_START = '# -- infra-kit:begin --'
 export const MARKER_END = '# -- infra-kit:end --'
@@ -18,22 +24,34 @@ const LEGACY_SINGLE = '# infra-kit shell functions'
 const USER_GLOBAL_CONFIG_STUB = '{}\n'
 
 // …and the annotated guidance lives next to it in a non-loaded .example.jsonc
-// (the loader only reads the three exact `infra-kit.json` / `config.json` files).
-const USER_GLOBAL_CONFIG_EXAMPLE = `// infra-kit user-global config — ~/.infra-kit/config.json
+// (the loader only reads the three exact `infra-kit.json` files).
+const USER_GLOBAL_CONFIG_EXAMPLE = `// infra-kit user-global config — ~/.infra-kit/infra-kit.json
 //
 // Merge chain (later layers override earlier ones at top-level keys):
 //   1. <repo>/infra-kit.json                            — committed project config (required)
-//   2. ~/.infra-kit/config.json                         — user-global (the sibling of this file)
+//   2. ~/.infra-kit/infra-kit.json                      — user-global (the sibling of this file)
 //   3. ~/.infra-kit/projects/<repo-name>/infra-kit.json — user-scope per-project override
 //
 // Merge is shallow: setting a top-level key replaces that whole section from
 // layer 1. Arrays do not concatenate. Top-level keys recognized:
-// environments, envManagement, ide, taskManager, worktrees.
+// environments, envManagement, ide, taskManager, worktrees, envAutoLoad.
 //
 // This .example.jsonc is reference only — it is NOT loaded. Put real global
-// overrides in the sibling config.json (strict JSON: no comments, double-quoted
+// overrides in the sibling infra-kit.json (strict JSON: no comments, double-quoted
 // keys). Per-project tweaks belong in layer 3 — run \`infra-kit config edit\`.
+//
+// Every recognized key is documented below. NOTE: \`environments\` and
+// \`envManagement\` are REQUIRED in the committed project infra-kit.json (layer 1)
+// and are usually NOT set in this user-global layer — they are shown here only to
+// document the full, valid config shape.
 {
+  // "environments": ["dev", "staging", "prod"],   // string[] (>=1) — required in layer 1
+  //
+  // "envManagement": {                            // required in layer 1; provider-tagged
+  //   "provider": "doppler",
+  //   "config": { "name": "my-doppler-project" }
+  // },
+  //
   // "ide": {
   //   "provider": "cursor",
   //   "config": { "workspaceConfigPath": "/path/to/your.code-workspace" }
@@ -45,23 +63,60 @@ const USER_GLOBAL_CONFIG_EXAMPLE = `// infra-kit user-global config — ~/.infra
   //   { "provider": "cursor", "config": { "workspaceConfigPath": "/path/to/your.code-workspace" } },
   //   { "provider": "zed", "config": {} }
   // ],
-  // "worktrees": { "openInGithubDesktop": false, "openInCmux": true }
+  //
+  // "taskManager": {
+  //   "provider": "jira",
+  //   "config": { "baseUrl": "https://acme.atlassian.net", "projectId": 123 }
+  // },
+  //
+  // "worktrees": {
+  //   "openInGithubDesktop": false,
+  //   "openInCmux": true,
+  //   // cmux pane layout for opened worktrees: "two-columns" (default, left | right)
+  //   // or "three-pane" (left split top/bottom + full-height right).
+  //   "cmux": { "layout": "two-columns" }
+  // },
+  //
+  // // Auto-load Doppler env when working inside this project/worktree. Omit to
+  // // disable. "trigger" (pick one): "shell-startup" (new shells) | "cli-invocation"
+  // // (before each infra-kit command, primes subsequent commands). "config" is the
+  // // environment to load (must be one of "environments"). Requires the committed
+  // // infra-kit.json at the git repo root, and the zsh shell integration
+  // // (infra-kit init + a new shell). zsh only.
+  // "envAutoLoad": { "trigger": "shell-startup", "config": "dev" }
+}
+`
+
+// The machine-local factory registry lives at ~/.infra-kit/vendor.json (strict
+// JSON). This annotated sibling documents every property; the real file is
+// scaffolded by \`infra-kit vendor config --init\`, NOT by init.
+const VENDOR_CONFIG_EXAMPLE = `// infra-kit factory registry — ~/.infra-kit/vendor.json
+//
+// Machine-local registry the vendor commands (sync/manifest/diff) read to know
+// where your project repos live and which ones to stamp. This .example.jsonc is
+// reference only — it is NOT loaded. The real file is the strict-JSON sibling
+// vendor.json (no comments, double-quoted keys); run \`infra-kit vendor config --init\`
+// to scaffold it.
+{
+  // "workspaceDir": "~/projects",   // string (absolute or ~-prefixed) — where target repos are cloned
+  // "targets": ["my-repo-a", "my-repo-b"]   // string[] (>=1) — repo dir names resolved under workspaceDir
 }
 `
 
 /**
- * Append infra-kit shell functions to .zshrc, migrate any legacy
- * `infra-kit.yml` config layers to JSON, normalize existing JSON configs from
- * the old IDE structure to the new one (strip the removed `ide.config.mode`),
- * and seed the user-global config at ~/.infra-kit/config.json on first run.
- * Idempotent: a subsequent run replaces the existing zshrc block in place, has
- * nothing left to migrate or normalize, and leaves the user-global config
- * untouched.
+ * Append infra-kit shell functions to .zshrc, migrate any legacy `infra-kit.yml`
+ * config layers to JSON, normalize existing JSON configs from the old IDE structure
+ * (strip the removed `ide.config.mode`), convert a legacy factory `vendor.config.ts`
+ * to `vendor.json`, and seed the user-global config at ~/.infra-kit/infra-kit.json on
+ * first run. Idempotent: a subsequent run replaces the existing zshrc block in place,
+ * has nothing left to migrate or normalize, and leaves the REAL config files
+ * (infra-kit.json / vendor.json) untouched — but the annotated `.example.jsonc`
+ * reference files are refreshed on every run so they always reflect the current schema.
  *
  * @example
  * // CLI: `infra-kit init`  (or via the `pnpm dx-init` alias)
  * // INFO: Added infra-kit shell functions to /Users/me/.zshrc
- * // INFO: Wrote user-global config to /Users/me/.infra-kit/config.json (see …/config.example.jsonc …)
+ * // INFO: Wrote user-global config to /Users/me/.infra-kit/infra-kit.json (see …/infra-kit.example.jsonc …)
  * // INFO: Run `source ~/.zshrc` or open a new terminal to activate.
  */
 export const init = async (): Promise<void> => {
@@ -85,50 +140,79 @@ export const init = async (): Promise<void> => {
   logger.info(`Added infra-kit shell functions to ${zshrcPath}`)
 
   // Convert any legacy infra-kit.yml config layers to JSON before seeding, so a
-  // migrated config.json is not re-seeded as an empty stub.
+  // migrated infra-kit.json is not re-seeded as an empty stub.
   await migrateLegacyConfig()
 
   // Migrate existing JSON configs from the old IDE structure to the new one
   // (strip the removed `ide.config.mode` field). No-op for already-clean configs.
   await normalizeLegacyIdeStructures()
 
+  // Rename a legacy user-global config.json → infra-kit.json (single canonical
+  // filename). MUST run before seeding: otherwise the seeder checks the new name,
+  // doesn't find it, and writes an empty stub that shadows the user's real config.
+  await migrateUserGlobalConfigFilename()
+
+  // Convert a legacy machine-local factory config from executable TS
+  // (~/.infra-kit/vendor.config.ts) to static JSON (~/.infra-kit/vendor.json).
+  // Independent of the infra-kit.json layers; grouped with the other migrations.
+  await migrateFactoryConfigToJson()
+
   seedUserGlobalConfig()
 
   // Best-effort, non-fatal, repo-gated: keep the agent-instruction files in sync
   // with the CLI surface. A no-op outside an infra-kit repo.
   await writeAgentFiles()
 
+  // The shell integration is zsh-only (zmodload zsh/stat, add-zsh-hook, ${dir:h}).
+  // Warn non-fatally if the user's login shell isn't zsh so the block isn't a
+  // silent no-op for them.
+  const shell = process.env.SHELL ?? ''
+
+  if (!shell.includes('zsh')) {
+    logger.warn(
+      `Your login shell ($SHELL=${shell || 'unset'}) is not zsh. The infra-kit shell integration (env-load/env-clear/auto-load) is zsh-only and won't activate in bash/fish.`,
+    )
+  }
+
   logger.info('Run `source ~/.zshrc` or open a new terminal to activate.')
 }
 
 /**
- * Create `~/.infra-kit/config.json` (empty `{}`) plus an annotated
- * `~/.infra-kit/config.example.jsonc` reference when absent. Skips silently if
- * the config already exists so user edits are preserved.
+ * Seed the user-global config on first run and (re)write the annotated reference
+ * files. The real `~/.infra-kit/infra-kit.json` (empty `{}`) is written only when
+ * absent so user edits are preserved. The non-loaded `.example.jsonc` reference
+ * files (`infra-kit.example.jsonc` + `vendor.example.jsonc`) are rewritten on EVERY
+ * run so existing users always get the current, complete schema documentation.
+ *
+ * Deliberately seeds NO real `vendor.json` — that is scaffolded by
+ * `infra-kit vendor config --init` (a stub here would block `--init`, trip the
+ * factory migration's no-overwrite guard, and fail the schema's `targets.min(1)`).
  *
  * @example
  * seedUserGlobalConfig()
- * // first call:  writes ~/.infra-kit/config.json ({}) + config.example.jsonc
- * // later calls: leaves the config alone, logs that it is already present
+ * // first call:  writes ~/.infra-kit/infra-kit.json ({}) + both .example.jsonc files
+ * // later calls: leaves infra-kit.json alone, refreshes both .example.jsonc files
  */
-const seedUserGlobalConfig = (): void => {
+export const seedUserGlobalConfig = (): void => {
   const userConfigDir = path.join(os.homedir(), '.infra-kit')
-  const userConfigPath = path.join(userConfigDir, 'config.json')
-  const userConfigExamplePath = path.join(userConfigDir, 'config.example.jsonc')
+  const userConfigPath = path.join(userConfigDir, 'infra-kit.json')
+
+  fs.mkdirSync(userConfigDir, { recursive: true })
+
+  // Reference examples are non-loaded docs — always refresh them so re-running init
+  // delivers the current schema (and the newly-added vendor example) to existing users.
+  fs.writeFileSync(path.join(userConfigDir, 'infra-kit.example.jsonc'), USER_GLOBAL_CONFIG_EXAMPLE, 'utf-8')
+  fs.writeFileSync(path.join(userConfigDir, 'vendor.example.jsonc'), VENDOR_CONFIG_EXAMPLE, 'utf-8')
 
   if (fs.existsSync(userConfigPath)) {
-    logger.info(`User-global config already present at ${userConfigPath}`)
+    logger.info(`User-global config already present at ${userConfigPath} (refreshed reference examples)`)
 
     return
   }
 
-  fs.mkdirSync(userConfigDir, { recursive: true })
   fs.writeFileSync(userConfigPath, USER_GLOBAL_CONFIG_STUB, 'utf-8')
-  fs.writeFileSync(userConfigExamplePath, USER_GLOBAL_CONFIG_EXAMPLE, 'utf-8')
 
-  logger.info(
-    `Wrote user-global config to ${userConfigPath} (see ${userConfigExamplePath} for the annotated reference)`,
-  )
+  logger.info(`Wrote user-global config to ${userConfigPath} (see the sibling .example.jsonc files for reference)`)
 }
 
 const isBlockLine = (line: string): boolean => {
@@ -168,7 +252,7 @@ const removeExistingBlock = (content: string): string => {
 
   if (legacyIdx === -1) return content
 
-  // eslint-disable-next-line sonarjs/slow-regex
+  // eslint-disable-next-line sonarjs/super-linear-regex
   const before = content.slice(0, legacyIdx).replace(/\n+$/, '')
   const afterLines = content.slice(legacyIdx).split('\n')
 
@@ -238,6 +322,31 @@ export const buildShellBody = (): string => {
     'if (( _INFRA_KIT_SHELL_STARTED > 0 )); then',
     '  add-zsh-hook precmd _infra_kit_autoload',
     'fi',
+    // One-shot env auto-load when a NEW shell opens inside an infra-kit project
+    // or worktree (config: envAutoLoad.trigger "shell-startup"). Cheap pure-zsh
+    // project gate (walk up for infra-kit.json) avoids spawning node in unrelated
+    // shells; the INFRA_KIT_ENV_CONFIG guard skips subshells that already inherited
+    // a loaded env. The spawn is DETACHED+backgrounded ( ... & ) so it never blocks
+    // the prompt; it only WRITES env-load.sh and the precmd hook above is the sole
+    // sourcer (picked up on a subsequent prompt). Trade-off: the gate can't read the
+    // merged JSON config, so a fresh shell in a project WITHOUT envAutoLoad still
+    // spawns one background process that resolves config, finds nothing, and exits.
+    '_infra_kit_startup_autoload() {',
+    '  [[ -z "$INFRA_KIT_SESSION" ]] && return',
+    '  [[ -n "$INFRA_KIT_ENV_CONFIG" ]] && return',
+    '  local dir="$PWD"',
+    '  while [[ "$dir" != / ]]; do',
+    '    if [[ -f "$dir/infra-kit.json" ]]; then',
+    `      ( ${runCmd} env-autoload & ) >/dev/null 2>&1`,
+    '      return',
+    '    fi',
+    // eslint-disable-next-line no-template-curly-in-string
+    '    dir="${dir:h}"',
+    '  done',
+    '}',
+    'if (( _INFRA_KIT_SHELL_STARTED > 0 )); then',
+    '  _infra_kit_startup_autoload',
+    'fi',
   ].join('\n')
 }