fg-devkit 1.22.0 → 1.24.0

package/scripts/fg-devkit.mjs

@@ -23,7 +23,6 @@
  *   pnpm exec fg-devkit sync-tooling-configs   (tooling sync only; overwrites config files)
  *   pnpm exec fg-devkit sync-dependency-check-suppressions-commit [--all]
  *   pnpm exec fg-devkit sync-vscode-settings
- *   pnpm exec fg-devkit sync-core-coding-standards
  *   pnpm exec fg-devkit sync-consumer-scripts
  *   pnpm exec fg-devkit setup-lefthook
  *   pnpm exec fg-devkit full-consumer-setup
@@ -31,8 +30,7 @@
  *   pnpm exec fg-devkit generate-release-notes [--tag=vX.Y.Z]
  *   pnpm exec fg-devkit verify-release-notes
  *   pnpm exec fg-devkit sync-release-notes-config
- *   pnpm exec fg-devkit commit [cz-args...]   (czg/cz-git with fg-devkit bundled config)
- *   pnpm exec fg-devkit commit-vuln           (staged package.json version bumps → vuln() commit)
+ *   pnpm exec fg-devkit commit [git-commit-args...]   (conventional commit prompts, then git commit)
  *   pnpm exec fg-devkit lint [eslint-args...]     (run ESLint with fg-devkit bundled packages)
  *   pnpm exec fg-devkit lint-fix [eslint-args...] (same as lint plus --fix)
  *   pnpm exec fg-devkit format [prettier-args...] (run Prettier with fg-devkit bundled package)
@@ -57,10 +55,11 @@ import fs from 'node:fs'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { createRequire } from 'node:module'
+import { styleText } from 'node:util'
+import { fgDevkitRoot } from './lib/common.mjs'
 
 const scriptDir = path.dirname(fileURLToPath(import.meta.url))
 const require = createRequire(import.meta.url)
-const fgRoot = path.resolve(scriptDir, '..')
 
 /** Run another script in this package via Node; inherits stdio and returns the child exit code. */
 function runNode(scriptRelative, args = [], options = {}) {
@@ -81,6 +80,18 @@ function runNode(scriptRelative, args = [], options = {}) {
   return r.status ?? 1
 }
 
+/**
+ * Menu label with dimmed tags: `Upgrade packages [interactive, auto-commit]`.
+ * interactive: the action stops and asks for input while it runs. autoCommit: it commits on its own.
+ */
+function tagged(name, { interactive = false, autoCommit = false }) {
+  const tags = [interactive && 'interactive', autoCommit && 'auto-commit'].filter(Boolean)
+  return `${name} ${styleText('dim', `[${tags.join(', ')}]`)}`
+}
+
+const autoCommit = (name) => tagged(name, { autoCommit: true })
+const interactive = (name) => tagged(name, { interactive: true })
+
 /**
  * Run release.sh (pnpm version bump, git push, gh release). Uses consumer cwd.
  * Args: [release|candidate] [patch|minor|major] or [patch|minor|major] [release|candidate].
@@ -149,10 +160,11 @@ function runSetupLefthook() {
 /**
  * Full consumer setup flow:
  * - Sync required consumer scripts for fgd commands
- * - Setup lefthook and migrate from husky/lint-staged
+ * - Setup lefthook
  * - Step 3: sync project configs
  * - Step 2: sync dependency policy
  * - Then run pnpm install
+ * - Set up the fg-ai-rules Claude Code plugins (a failure only warns, e.g. without Claude Code)
  */
 function runFullConsumerSetup() {
   console.log('[fg-devkit] Running full consumer sync and setup')
@@ -172,7 +184,13 @@ function runFullConsumerSetup() {
   const step2 = runNode('sync-dependency-policy.mjs')
   if (step2 !== 0) return step2
 
-  return runPnpmInstall()
+  const installStep = runPnpmInstall()
+  if (installStep !== 0) return installStep
+
+  if (runNode('setup-ai-rules.mjs') !== 0) {
+    console.warn('[fg-devkit] AI rules were not set up. Run "fgd setup-ai-rules" when Claude Code is available.')
+  }
+  return 0
 }
 
 /** Maintainer flow: run full repo vulnerability audit in fg-devkit root. */
@@ -184,7 +202,7 @@ function runMaintainerAuditAll() {
  * Prompt for a conventional commit message with fg-devkit's legacy question flow,
  * then run `git commit` directly.
  */
-async function runCzg(args = [], extraEnv = {}) {
+async function runCommit(args = [], extraEnv = {}) {
   let selectPrompt
   let inputPrompt
   try {
@@ -395,12 +413,18 @@ function runBundledTypeScript(args = []) {
   return r.status ?? 1
 }
 
-/** Run Fallow from fg-devkit's bundled dependency set. */
+const FALLOW_CONFIG_FILES = ['.fallowrc.json', '.fallowrc.jsonc', 'fallow.toml', '.fallow.toml']
+
+/**
+ * Run Fallow from fg-devkit's bundled dependency set. Uses fg-devkit's configs/fallowrc.json
+ * unless the repo has its own Fallow config or the caller passes -c/--config, so config
+ * fixes reach every repo on the next fg-devkit bump.
+ */
 function runBundledFallow(args = []) {
   let fallowBin
   try {
     const fallowPkgJson = require.resolve('fallow/package.json', {
-      paths: [fgRoot, process.cwd()],
+      paths: [fgDevkitRoot, process.cwd()],
     })
     const fallowPkgRoot = path.dirname(fallowPkgJson)
     fallowBin = path.join(fallowPkgRoot, 'bin', 'fallow')
@@ -413,7 +437,12 @@ function runBundledFallow(args = []) {
     return 1
   }
 
-  const r = spawnSync(process.execPath, [fallowBin, ...args], {
+  const hasConfig =
+    args.some((arg) => arg === '-c' || arg === '--config' || arg.startsWith('--config=')) ||
+    FALLOW_CONFIG_FILES.some((name) => fs.existsSync(path.join(process.cwd(), name)))
+  const configArgs = hasConfig ? [] : ['--config', path.join(fgDevkitRoot, 'configs', 'fallowrc.json')]
+
+  const r = spawnSync(process.execPath, [fallowBin, ...args, ...configArgs], {
     stdio: 'inherit',
     cwd: process.cwd(),
     env: process.env,
@@ -427,7 +456,7 @@ function runBundledFallow(args = []) {
 }
 
 function syncFileFromTemplate(relativeSourcePath, targetPath) {
-  const sourcePath = path.join(fgRoot, relativeSourcePath)
+  const sourcePath = path.join(fgDevkitRoot, relativeSourcePath)
   if (!fs.existsSync(sourcePath)) {
     console.error(`[fg-devkit] Missing template: ${sourcePath}`)
     return 1
@@ -447,9 +476,7 @@ function runSyncConfigTarget(target) {
   if (target === 'eslint') return syncFileFromTemplate('configs/eslint.sync-stub.js', 'eslint.config.js')
   if (target === 'prettier') return syncFileFromTemplate('configs/prettier.sync-stub.js', 'prettier.config.js')
   if (target === 'tsconfig') return syncFileFromTemplate('configs/tsconfig.app.sync.json', 'tsconfig.json')
-  if (target === 'fallow') return syncFileFromTemplate('configs/fallowrc.sync-stub.json', '.fallowrc.json')
   if (target === 'dependency-check') return runNode('sync-dependency-check-suppressions-commit.mjs')
-  if (target === 'cursor') return runNode('sync-core-coding-standards.mjs')
   if (target === 'vue-inspector') return runNode('sync-vite-plugin-vue-inspector.mjs')
   if (target === 'all') return runNode('sync-project-configs.mjs')
   console.error(`[fg-devkit] Unknown config sync target: ${target}`)
@@ -470,11 +497,8 @@ const DIRECT_COMMANDS = {
   'sync-node-toolchain': 'sync-node-toolchain.mjs',
   'sync-pnpm-toolchain': 'sync-pnpm-toolchain.mjs',
   'bump-node-toolchain': 'bump-node-toolchain.mjs',
-  'fleet-git-pull': 'fleet-git-pull.mjs',
   'fleet-git-pull-scoped': 'fleet-git-pull-scoped.mjs',
-  'fleet-git-commit-push': 'fleet-git-commit-push.mjs',
   'fleet-git-commit-push-scoped': 'fleet-git-commit-push-scoped.mjs',
-  'fleet-git-discard': 'fleet-git-discard.mjs',
   'fleet-git-discard-scoped': 'fleet-git-discard-scoped.mjs',
   'policy-upgrade': 'policy-upgrade.mjs',
   'policy-upgrade-commit': 'policy-upgrade-commit.mjs',
@@ -485,9 +509,9 @@ const DIRECT_COMMANDS = {
   'sync-tooling-configs': 'sync-tooling-configs.mjs',
   'sync-dependency-check-suppressions-commit': 'sync-dependency-check-suppressions-commit.mjs',
   'sync-vscode-settings': 'sync-vscode-settings.mjs',
-  'sync-core-coding-standards': 'sync-core-coding-standards.mjs',
   'sync-vite-plugin-vue-inspector': 'sync-vite-plugin-vue-inspector.mjs',
   'sync-consumer-scripts': 'sync-consumer-scripts.mjs',
+  'setup-ai-rules': 'setup-ai-rules.mjs',
   'sync-release-notes-config': 'sync-release-notes-config.mjs',
   'generate-release-notes': 'generate-release-notes.mjs',
   'verify-release-notes': 'verify-release-notes.mjs',
@@ -524,18 +548,12 @@ Commands:
   bump-node-toolchain [version] [projects-root] [options]
                                  Maintainer: set policy.node and sync Node toolchain across fleet
                                  Options: --dry-run, --skip-fleet, --no-engines, --engines=RANGE, --pick, --all, --only=a,b
-  fleet-git-pull [projects-root] [--dry-run]
-                                 Maintainer: git pull (current branch) for all git repos under projects root
   fleet-git-pull-scoped [projects-root] [options]
                                  Maintainer: git pull (current branch) for chosen repositories
                                  Options: --dry-run, --fg-devkit-only, --pick, --all, --only=a,b
-  fleet-git-commit-push --message="..." [projects-root] [--dry-run]
-                                 Maintainer: stage, commit, and push all git repos under projects root
   fleet-git-commit-push-scoped --message="..." [projects-root] [options]
                                  Maintainer: stage, commit, and push chosen repositories
                                  Options: --dry-run, --fg-devkit-only, --pick, --all, --only=a,b
-  fleet-git-discard [projects-root] [--dry-run]
-                                 Maintainer: discard tracked git changes in all git repos under projects root
   fleet-git-discard-scoped [projects-root] [options]
                                  Maintainer: discard tracked git changes in chosen repositories
                                  Options: --dry-run, --fg-devkit-only, --pick, --all, --only=a,b
@@ -546,6 +564,7 @@ Commands:
                                  --prune-overrides also drops unused workspace overrides in a second commit
   audit-override-commit [--no-verify] [--no-commit]
                                  Fix pnpm audit findings: refresh lockfile first, override only when a range blocks the fix, verify, auto-commit
+                                 Asks before forcing the rest; --allow-major, --allow-young, --bump-direct say yes without asking
   prune-overrides [--fix] [--commit]
                                  Report unused workspace overrides; --fix removes them; --commit also auto-commits
   prune-release-age-exclude [--fix] [--commit]
@@ -555,11 +574,11 @@ Commands:
   sync-dependency-check-suppressions-commit [--all]
                                  Write the dependency-check suppressions that match pnpm audit findings and auto-commit (--all: copy every entry)
   sync-vscode-settings            Copy shared VS Code settings into .vscode/settings.json
-  sync-core-coding-standards      Copy .cursor core coding standards with consumer package name
   sync-vite-plugin-vue-inspector  Add/pin vite-plugin-vue-inspector, wire vite.config, install, commit
   sync-consumer-scripts           Enforce standard fgd scripts in consumer package.json
-  setup-lefthook                  Setup lefthook and migrate from husky/lint-staged
-  full-consumer-setup             Run: scripts -> lefthook -> step 3 -> step 2 -> pnpm install
+  setup-lefthook                  Write lefthook.yml and install the git hooks
+  setup-ai-rules                  Enable the fg-ai-rules Claude Code plugins in this repo and install them
+  full-consumer-setup             Run: scripts -> lefthook -> step 3 -> step 2 -> pnpm install -> AI rules
   create-release [release|candidate] [patch|minor|major] [--skip-release-notes]
                                  Stable release or candidate (X.Y.Z-rc.N); omit = interactive menu
                                  (alias: createRelease)
@@ -567,8 +586,7 @@ Commands:
                                  Generate CHANGELOG.md and user changelog via git-cliff
   verify-release-notes           Interactive review step before committing release notes
   sync-release-notes-config      Add CHANGELOG.user.md and generate:release-notes script when missing
-  commit [args...]              czg/cz-git with fg-devkit bundled config
-  commit-vuln                   Commit staged dependency bumps as vuln() (alias: vuln-commit)
+  commit [args...]              Conventional commit prompts, then git commit [args...]
   lint [eslint-args...]         Run ESLint using fg-devkit bundled ESLint stack
   lint-fix [eslint-args...]     Run ESLint with --fix using fg-devkit bundled ESLint stack
   format [prettier-args...]     Run Prettier using fg-devkit bundled package
@@ -592,7 +610,7 @@ Options:
 }
 
 function isFgDevkitMaintainerContext() {
-  if (path.resolve(process.cwd()) !== fgRoot) {
+  if (path.resolve(process.cwd()) !== fgDevkitRoot) {
     return false
   }
   const pkgPath = path.join(process.cwd(), 'package.json')
@@ -644,52 +662,38 @@ async function runInteractiveMenu() {
   const isMaintainer = isFgDevkitMaintainerContext()
   const groups = [
     {
-      name: '1) Create commit',
+      name: interactive('Commit'),
       value: 'commit',
+      description: 'Write a conventional commit message step by step and commit the staged changes',
     },
+    { name: 'Release', value: 'release', description: 'Bump the version, tag it and publish a GitHub release' },
+    { name: 'Lint & typecheck', value: 'lint-typecheck', description: 'Run ESLint and TypeScript' },
+    { name: 'Translations', value: 'poeditor', description: 'Download or upload translations in POEditor' },
     {
-      name: '2) Create release',
-      value: 'release',
-    },
-    {
-      name: '3) Lint and typecheck',
-      value: 'lint-typecheck',
-    },
-    {
-      name: '4) Poeditor',
-      value: 'poeditor',
-    },
-    {
-      name: '5) Dependecy policy',
+      name: 'Dependency policy',
       value: 'dependency-policy',
+      description: 'Keep package.json in line with the shared policy and fix vulnerabilities',
     },
     {
-      name: '6) Sync configs',
+      name: 'Sync configs',
       value: 'sync-configs',
+      description: 'Overwrite shared config files with the versions in fg-devkit',
     },
+    { name: 'Setup', value: 'setup', description: 'Git hooks and first-time setup of a repo' },
     {
-      name: '7) Setup',
-      value: 'setup',
-    },
-    {
-      name: '8) Fallow analysis',
-      value: 'fallow-analysis',
-    },
-    {
-      name: '9) Piwik',
-      value: 'piwik',
+      name: 'Dead code (Fallow)',
+      value: 'fallow-dead-code',
+      description: 'Find unused files, exports and dependencies',
     },
+    { name: 'Piwik', value: 'piwik', description: 'Manage Piwik PRO custom dimensions' },
   ]
-  if (isMaintainer) {
-    groups.push({
-      name: '10) Maintainer',
+  if (isMaintainer) groups.push({
+      name: 'Maintainer',
       value: 'maintainer',
+      description: 'Dependency policy, toolchain and git across all repos',
     })
-  }
-  groups.push({
-    name: isMaintainer ? '11) Exit' : '10) Exit',
-    value: 'exit',
-  })
+  groups.push({ name: 'Exit', value: 'exit' })
+  for (const [index, group] of groups.entries()) group.name = `${index + 1}) ${group.name}`
 
   while (true) {
     const group = await selectPrompt({
@@ -700,26 +704,15 @@ async function runInteractiveMenu() {
     if (group === 'exit') return 0
 
     if (group === 'commit') {
-      const choice = await selectPrompt({
-        message: 'Create commit',
-        choices: [
-          { name: 'Commit', value: 'commit' },
-          { name: 'Commit vulnerability', value: 'commit-vuln' },
-          { name: 'Cancel', value: 'cancel' },
-        ],
-        default: 'commit',
-        loop: false,
-      })
-      if (choice === 'cancel') continue
-      return runSelectedAction(() => (choice === 'commit' ? runCzg() : runNode('vuln-commit.mjs')))
+      return runSelectedAction(() => runCommit())
     }
 
     if (group === 'release') {
       const releaseKind = await selectPrompt({
-        message: 'Create release',
+        message: 'Release',
         choices: [
-          { name: 'Release', value: 'release' },
-          { name: 'Candidate', value: 'candidate' },
+          { name: 'Release', value: 'release', description: 'Tag the next version and publish a GitHub release' },
+          { name: 'Release candidate', value: 'candidate', description: 'Tag a prerelease such as 2.8.0-rc.1' },
           { name: 'Cancel', value: 'cancel' },
         ],
         default: 'release',
@@ -728,10 +721,14 @@ async function runInteractiveMenu() {
       if (releaseKind === 'cancel') continue
 
       const releaseMode = await selectPrompt({
-        message: 'Create release',
+        message: 'Release notes',
         choices: [
-          { name: 'Release', value: 'without-notes' },
-          { name: 'Release + release notes', value: 'with-notes' },
+          { name: 'Without notes', value: 'without-notes', description: 'GitHub generates the release notes' },
+          {
+            name: interactive('With notes'),
+            value: 'with-notes',
+            description: 'Generate CHANGELOG.md and CHANGELOG.user.md with git-cliff and review them before release',
+          },
           { name: 'Cancel', value: 'cancel' },
         ],
         default: 'without-notes',
@@ -740,11 +737,11 @@ async function runInteractiveMenu() {
       if (releaseMode === 'cancel') continue
 
       const bumpChoice = await selectPrompt({
-        message: releaseKind === 'candidate' ? 'Candidate' : 'Release',
+        message: releaseKind === 'candidate' ? 'Release candidate' : 'Release',
         choices: [
-          { name: 'Patch', value: 'patch' },
-          { name: 'Minor', value: 'minor' },
-          { name: 'Major', value: 'major' },
+          { name: 'Patch', value: 'patch', description: 'Bug fixes only: 1.2.3 → 1.2.4' },
+          { name: 'Minor', value: 'minor', description: 'New features, backwards compatible: 1.2.3 → 1.3.0' },
+          { name: 'Major', value: 'major', description: 'Breaking changes: 1.2.3 → 2.0.0' },
           { name: 'Cancel', value: 'cancel' },
         ],
         default: 'patch',
@@ -764,11 +761,11 @@ async function runInteractiveMenu() {
 
     if (group === 'lint-typecheck') {
       const choice = await selectPrompt({
-        message: 'Lint and typecheck',
+        message: 'Lint & typecheck',
         choices: [
-          { name: 'Lint and typecheck', value: 'both' },
-          { name: 'Lint', value: 'lint' },
-          { name: 'Typecheck', value: 'typecheck' },
+          { name: 'Lint & typecheck', value: 'both', description: 'ESLint on the whole repo, then tsc --noEmit' },
+          { name: 'Lint', value: 'lint', description: 'ESLint on the whole repo' },
+          { name: 'Typecheck', value: 'typecheck', description: 'tsc --noEmit with tsconfig.json' },
           { name: 'Cancel', value: 'cancel' },
         ],
         default: 'both',
@@ -786,10 +783,10 @@ async function runInteractiveMenu() {
 
     if (group === 'poeditor') {
       const choice = await selectPrompt({
-        message: 'Poeditor',
+        message: 'Translations',
         choices: [
-          { name: 'Download', value: 'download' },
-          { name: 'Upload', value: 'upload' },
+          { name: 'Download', value: 'download', description: 'Download translations from POEditor into the repo' },
+          { name: 'Upload', value: 'upload', description: 'Upload the repo\'s translations to POEditor' },
           { name: 'Cancel', value: 'cancel' },
         ],
         default: 'download',
@@ -801,12 +798,13 @@ async function runInteractiveMenu() {
       }
 
       const uploadMode = await selectPrompt({
-        message: 'Upload mode',
+        message: 'Upload',
         choices: [
-          { name: 'Upload (keep terms missing from file)', value: 'upload' },
+          { name: 'Upload', value: 'upload', description: 'Terms missing from the file stay in POEditor' },
           {
-            name: 'Upload + sync terms (delete terms missing from file)',
+            name: 'Upload and delete missing terms',
             value: 'upload-sync',
+            description: 'Terms missing from the file are deleted in POEditor, with all their translations',
           },
           { name: 'Cancel', value: 'cancel' },
         ],
@@ -830,14 +828,38 @@ async function runInteractiveMenu() {
       const choice = await selectPrompt({
         message: 'Piwik PRO custom dimensions',
         choices: [
-          { name: 'List dimensions in Piwik', value: 'list' },
-          { name: 'List local dimension map', value: 'list-local' },
-          { name: 'Compare local map with Piwik', value: 'diff' },
-          { name: 'Add missing dimensions', value: 'add' },
-          { name: 'Update dimension names', value: 'update' },
-          { name: 'Sync from one side to another', value: 'sync' },
-          { name: 'Compare environments', value: 'compare' },
-          { name: 'Migrate between environments', value: 'migrate' },
+          { name: 'List in Piwik', value: 'list', description: 'Dimensions on a site from src/config/env.ts' },
+          {
+            name: 'List local',
+            value: 'list-local',
+            description: 'Slot map in dimensions.ts or piwikDimensions.ts. Does not call Piwik',
+          },
+          {
+            name: 'Compare local with Piwik',
+            value: 'diff',
+            description: 'Show where the local slot map and Piwik differ',
+          },
+          {
+            name: 'Add missing dimensions',
+            value: 'add',
+            description: 'Create local dimensions that are missing in Piwik, one slot at a time',
+          },
+          {
+            name: 'Update dimension names',
+            value: 'update',
+            description: 'Rename Piwik dimensions to the local names',
+          },
+          {
+            name: 'Sync',
+            value: 'sync',
+            description: 'Copy dimensions between the local map and a site, or between two sites',
+          },
+          { name: 'Compare environments', value: 'compare', description: 'Compare the dimensions on two Piwik sites' },
+          {
+            name: 'Migrate between environments',
+            value: 'migrate',
+            description: 'Copy dimensions from one Piwik site to another',
+          },
           { name: 'Cancel', value: 'cancel' },
         ],
         default: 'diff',
@@ -848,7 +870,7 @@ async function runInteractiveMenu() {
       if (choice === 'list-local') return runSelectedAction(() => runNode('piwik.mjs', ['list', '--local']))
       if (choice === 'diff') return runSelectedAction(() => runNode('piwik.mjs', ['diff']))
       if (choice === 'compare' || choice === 'migrate') {
-        const { defaultEnvironmentPair, listPiwikEnvironments } = await import('./piwik-common.mjs')
+        const { defaultEnvironmentPair, listPiwikEnvironments } = await import('./lib/piwik-common.mjs')
         const environments = listPiwikEnvironments(process.cwd())
         if (environments.length < 2) {
           console.log('[piwik] Need two Piwik sites in src/config/env.ts.')
@@ -874,8 +896,8 @@ async function runInteractiveMenu() {
         const writeMode = await selectPrompt({
           message: `Write dimensions from ${from} to ${to}?`,
           choices: [
-            { name: 'Dry run', value: 'dry-run' },
-            { name: 'Apply', value: 'apply' },
+            { name: 'Dry run', value: 'dry-run', description: 'Show what would change without writing anything' },
+            { name: 'Apply', value: 'apply', description: 'Write the changes' },
             { name: 'Cancel', value: 'cancel' },
           ],
           default: 'dry-run',
@@ -895,10 +917,10 @@ async function runInteractiveMenu() {
         return runSelectedAction(() => runNode('piwik.mjs', migrateArgs))
       }
       if (choice === 'sync') {
-        const { listPiwikEnvironments } = await import('./piwik-common.mjs')
+        const { listPiwikEnvironments } = await import('./lib/piwik-common.mjs')
         const environments = listPiwikEnvironments(process.cwd())
         const endpoints = [
-          { name: 'Local map', value: 'local' },
+          { name: 'Local map', value: 'local', description: 'dimensions.ts or piwikDimensions.ts in this repo' },
           ...environments.map((site) => ({ name: site.environment, value: site.environment })),
         ]
         const from = await selectPrompt({
@@ -922,8 +944,8 @@ async function runInteractiveMenu() {
         const writeMode = await selectPrompt({
           message: from === 'local' ? `Write the local map up to ${to}?` : to === 'local' ? `Write tracking ids from ${from} into the local map?` : `Write dimensions from ${from} to ${to}?`,
           choices: [
-            { name: 'Dry run', value: 'dry-run' },
-            { name: 'Apply', value: 'apply' },
+            { name: 'Dry run', value: 'dry-run', description: 'Show what would change without writing anything' },
+            { name: 'Apply', value: 'apply', description: 'Write the changes' },
             { name: 'Cancel', value: 'cancel' },
           ],
           default: 'dry-run',
@@ -950,8 +972,8 @@ async function runInteractiveMenu() {
       const writeMode = await selectPrompt({
         message: 'Write to Piwik?',
         choices: [
-          { name: 'Dry run', value: 'dry-run' },
-          { name: 'Apply', value: 'apply' },
+          { name: 'Dry run', value: 'dry-run', description: 'Show what would change without writing anything' },
+          { name: 'Apply', value: 'apply', description: 'Write the changes' },
           { name: 'Cancel', value: 'cancel' },
         ],
         default: 'dry-run',
@@ -973,20 +995,38 @@ async function runInteractiveMenu() {
 
     if (group === 'dependency-policy') {
       const choice = await selectPrompt({
-        message: 'Dependecy policy',
+        message: 'Dependency policy',
         choices: [
-          { name: 'Check', value: 'check' },
-          { name: 'Sync and auto-commit', value: 'sync-commit' },
-          { name: 'Upgrade package.json packages and auto-commit', value: 'upgrade-commit' },
-          { name: 'Upgrade package.json packages, prune overrides, and auto-commit', value: 'upgrade-commit-prune' },
           {
-            name: 'Fix vulnerabilities (refresh, override, prune) and auto-commit',
+            name: 'Check',
+            value: 'check',
+            description: 'Check package.json against the dependency policy without changing anything',
+          },
+          {
+            name: autoCommit('Sync'),
+            value: 'sync-commit',
+            description: 'Set package.json versions to the dependency policy and run pnpm install',
+          },
+          {
+            name: tagged('Upgrade packages', { interactive: true, autoCommit: true }),
+            value: 'upgrade-commit-prune',
+            description: 'Pick packages to upgrade with ncu, then prune unused overrides in a second commit',
+          },
+          {
+            name: tagged('Fix vulnerabilities', { interactive: true, autoCommit: true }),
             value: 'audit-override-commit',
+            description:
+              'Refresh the lockfile, override where ranges block, prune, verify. Asks before forcing a new major, a young release or a direct bump',
           },
-          { name: 'Prune unused vulnerability overrides and auto-commit', value: 'prune-overrides' },
           {
-            name: 'Prune unneeded minimumReleaseAgeExclude entries and auto-commit',
+            name: autoCommit('Prune overrides'),
+            value: 'prune-overrides',
+            description: 'Remove workspace overrides that no longer change pnpm audit',
+          },
+          {
+            name: autoCommit('Prune minimumReleaseAgeExclude'),
             value: 'prune-release-age-exclude',
+            description: 'Remove pinned versions that are old enough or no longer in the lockfile',
           },
           { name: 'Cancel', value: 'cancel' },
         ],
@@ -998,9 +1038,6 @@ async function runInteractiveMenu() {
       if (choice === 'sync-commit') {
         return runSelectedAction(() => runNode('sync-dependency-policy-commit.mjs'))
       }
-      if (choice === 'upgrade-commit') {
-        return runSelectedAction(() => runNode('policy-upgrade-commit.mjs'))
-      }
       if (choice === 'upgrade-commit-prune') {
         return runSelectedAction(() => runNode('policy-upgrade-commit.mjs', ['--prune-overrides']))
       }
@@ -1020,15 +1057,21 @@ async function runInteractiveMenu() {
       const choice = await selectPrompt({
         message: 'Sync configs',
         choices: [
-          { name: 'vscode', value: 'vscode' },
-          { name: 'eslint', value: 'eslint' },
-          { name: 'prettier', value: 'prettier' },
-          { name: 'tsconfig', value: 'tsconfig' },
-          { name: 'Fallow', value: 'fallow' },
-          { name: 'Dependency-Check suppressions (sync + commit)', value: 'dependency-check' },
-          { name: 'Cursor', value: 'cursor' },
-          { name: 'Vue inspector (vite-plugin-vue-inspector)', value: 'vue-inspector' },
-          { name: 'All', value: 'all' },
+          { name: 'VS Code', value: 'vscode', description: 'Overwrite .vscode/settings.json with the shared settings' },
+          { name: 'ESLint', value: 'eslint', description: 'Overwrite eslint.config.js with the shared config' },
+          { name: 'Prettier', value: 'prettier', description: 'Overwrite prettier.config.js with the shared config' },
+          { name: 'tsconfig', value: 'tsconfig', description: 'Overwrite tsconfig.json with the shared config' },
+          {
+            name: autoCommit('Dependency-Check suppressions'),
+            value: 'dependency-check',
+            description: 'Write the suppressions that match pnpm audit findings',
+          },
+          {
+            name: autoCommit('Vue inspector'),
+            value: 'vue-inspector',
+            description: 'Add vite-plugin-vue-inspector, wire it in vite.config and run pnpm install',
+          },
+          { name: 'All configs', value: 'all', description: 'VS Code, ESLint, Prettier and tsconfig' },
           { name: 'Cancel', value: 'cancel' },
         ],
         default: 'all',
@@ -1042,236 +1085,153 @@ async function runInteractiveMenu() {
       const choice = await selectPrompt({
         message: 'Setup',
         choices: [
-          { name: 'Lefthook', value: 'lefthook' },
-          { name: 'Full consumer setup', value: 'full-consumer-setup' },
+          {
+            name: 'Lefthook',
+            value: 'lefthook',
+            description: 'Write lefthook.yml and install the git hooks',
+          },
+          {
+            name: 'AI rules',
+            value: 'ai-rules',
+            description: 'Enable the fg-ai-rules plugins in .claude/settings.json and install them for Claude Code',
+          },
+          {
+            name: 'Full setup',
+            value: 'full-consumer-setup',
+            description: 'Sync scripts, Lefthook, configs and dependency policy, pnpm install, then set up AI rules',
+          },
           { name: 'Cancel', value: 'cancel' },
         ],
         default: 'lefthook',
         loop: false,
       })
       if (choice === 'cancel') continue
+      if (choice === 'ai-rules') return runSelectedAction(() => runNode('setup-ai-rules.mjs'))
       return runSelectedAction(() => (choice === 'lefthook' ? runSetupLefthook() : runFullConsumerSetup()))
     }
 
-    if (group === 'fallow-analysis') {
-      const choice = await selectPrompt({
-        message: 'Fallow analysis',
-        choices: [
-          { name: 'dead code', value: 'dead-code' },
-          { name: 'Cancel', value: 'cancel' },
-        ],
-        default: 'dead-code',
-        loop: false,
-      })
-      if (choice === 'cancel') continue
-      return runSelectedAction(() => runBundledFallow([choice]))
+    if (group === 'fallow-dead-code') {
+      return runSelectedAction(() => runBundledFallow(['dead-code']))
     }
 
     if (group === 'maintainer') {
       const choice = await selectPrompt({
         message: 'Maintainer',
         choices: [
-          { name: 'Show outdated dependency policy packages', value: 'm1' },
-          { name: 'Upgrade dependency policy (interactive) and auto-commit', value: 'm2' },
-          { name: 'Refresh dependency policy from repos (and scaffold/vue package.json)', value: 'm3' },
-          { name: 'Check policy vulnerabilities (audit)', value: 'm4' },
-          { name: 'Check fg-devkit repo vulnerabilities', value: 'm5' },
-          { name: 'Check vulnerabilities across all Vue repos', value: 'm6' },
-          { name: 'Bump fg-devkit in all Vue repos, run sync-deps, and pnpm install', value: 'm7' },
-          { name: 'Bump pnpm toolchain (latest)', value: 'm8' },
-          { name: 'Bump Node toolchain (fleet sync)', value: 'm9' },
-          { name: 'Git pull all repositories', value: 'm10' },
-          { name: 'Git pull (choose repositories)', value: 'm11' },
-          { name: 'Stage, commit and push all repositories', value: 'm12' },
-          { name: 'Stage, commit and push (choose repositories)', value: 'm13' },
-          { name: 'Discard tracked changes in all repositories', value: 'm14' },
-          { name: 'Discard tracked changes (choose repositories)', value: 'm15' },
+          {
+            name: 'Outdated policy packages',
+            value: 'policy-outdated',
+            description: 'Policy packages that have newer versions on npm',
+          },
+          {
+            name: tagged('Upgrade policy', { interactive: true, autoCommit: true }),
+            value: 'policy-upgrade',
+            description: 'Pick policy versions to upgrade with ncu',
+          },
+          {
+            name: 'Refresh policy from repos',
+            value: 'refresh-policy',
+            description: 'Rebuild the policy from the packages used in Vue repos, and update scaffold/vue/package.json',
+          },
+          { name: 'Policy vulnerabilities', value: 'policy-vulns', description: 'pnpm audit of the versions in the policy' },
+          { name: 'Vulnerabilities', value: 'vulns', description: 'pnpm audit across the Vue repos or in fg-devkit' },
+          {
+            name: interactive('Bump fg-devkit in Vue repos'),
+            value: 'bump-fg-devkit',
+            description: 'Bump fg-devkit to latest, sync the dependency policy and run pnpm install in each repo',
+          },
+          { name: 'Bump pnpm', value: 'bump-pnpm', description: 'Latest pnpm in the policy, scaffold and repos' },
+          { name: 'Bump Node', value: 'bump-node', description: 'Sync the Node version from the policy to the repos' },
+          { name: 'Git pull', value: 'git-pull', description: 'Pull the current branch in each repo' },
+          {
+            name: interactive('Commit & push'),
+            value: 'git-commit-push',
+            description: 'Stage all changes, commit and push in each repo',
+          },
+          { name: 'Discard changes', value: 'git-discard', description: 'Throw away uncommitted changes to tracked files in each repo' },
           { name: 'Cancel', value: 'cancel' },
         ],
-        default: 'm1',
+        default: 'policy-outdated',
         loop: false,
       })
       if (choice === 'cancel') continue
       const maintainerCode = maintainerOnly()
       if (maintainerCode !== 0) return maintainerCode
-      if (choice === 'm1') return runSelectedAction(() => runNode('policy-outdated.mjs'))
-      if (choice === 'm2') return runSelectedAction(() => runNode('policy-upgrade.mjs'))
-      if (choice === 'm3') return runSelectedAction(() => runNode('refresh-dependency-policy-from-repos.mjs'))
-      if (choice === 'm4') return runSelectedAction(() => runNode('policy-vulns.mjs'))
-      if (choice === 'm5') return runSelectedAction(() => runMaintainerAuditAll())
-      if (choice === 'm6') return runSelectedAction(() => runNode('fleet-vulns.mjs'))
-      if (choice === 'm7') return runSelectedAction(() => runNode('fleet-bump-fg-devkit.mjs'))
-      if (choice === 'm8') {
-        const scope = await selectPrompt({
-          message: 'Bump pnpm toolchain',
-          choices: [
-            { name: 'fg-devkit only (policy, scaffold, install)', value: 'fg-devkit' },
-            { name: 'fg-devkit + pick pnpm repos under projects root', value: 'fleet' },
-            { name: 'Dry run + pick pnpm repos', value: 'dry-run-fleet' },
-            { name: 'Cancel', value: 'cancel' },
-          ],
-          default: 'fg-devkit',
-          loop: false,
-        })
-        if (scope === 'cancel') continue
-        const bumpArgs = []
-        if (scope === 'fg-devkit') {
-          bumpArgs.push('--skip-fleet')
-        }
-        if (scope === 'fleet') {
-          bumpArgs.push('--pick')
-        }
-        if (scope === 'dry-run-fleet') {
-          bumpArgs.push('--dry-run', '--pick')
-        }
-        return runSelectedAction(() => runNode('bump-pnpm-toolchain.mjs', bumpArgs))
-      }
-      if (choice === 'm9') {
-        const scope = await selectPrompt({
-          message: 'Bump Node toolchain',
-          choices: [
-            { name: 'fg-devkit only (policy + local files)', value: 'fg-devkit' },
-            { name: 'fg-devkit + pick projects under projects root', value: 'fleet' },
-            { name: 'Dry run + pick projects', value: 'dry-run-fleet' },
-            { name: 'Cancel', value: 'cancel' },
-          ],
-          default: 'fleet',
-          loop: false,
-        })
-        if (scope === 'cancel') continue
-        const bumpArgs = []
-        if (scope === 'fg-devkit') {
-          bumpArgs.push('--skip-fleet')
-        }
-        if (scope === 'fleet') {
-          bumpArgs.push('--pick')
-        }
-        if (scope === 'dry-run-fleet') {
-          bumpArgs.push('--dry-run', '--pick')
-        }
-        return runSelectedAction(() => runNode('bump-node-toolchain.mjs', bumpArgs))
-      }
-      if (choice === 'm10') {
-        const scope = await selectPrompt({
-          message: 'Git pull all repositories',
-          choices: [
-            { name: 'Pull all git repos under projects root', value: 'pull' },
-            { name: 'Dry run (all repos)', value: 'dry-run' },
-            { name: 'Cancel', value: 'cancel' },
-          ],
-          default: 'pull',
-          loop: false,
-        })
-        if (scope === 'cancel') continue
-        const pullArgs = scope === 'dry-run' ? ['--dry-run'] : []
-        return runSelectedAction(() => runNode('fleet-git-pull.mjs', pullArgs))
-      }
-      if (choice === 'm11') {
-        const scope = await selectPrompt({
-          message: 'Git pull (choose repositories)',
-          choices: [
-            { name: 'fg-devkit only', value: 'fg-devkit' },
-            { name: 'Choose repositories under projects root', value: 'pick' },
-            { name: 'Dry run + choose repositories', value: 'dry-run-pick' },
-            { name: 'Cancel', value: 'cancel' },
-          ],
-          default: 'pick',
-          loop: false,
-        })
-        if (scope === 'cancel') continue
-        const pullArgs = []
-        if (scope === 'fg-devkit') {
-          pullArgs.push('--fg-devkit-only')
-        }
-        if (scope === 'pick') {
-          pullArgs.push('--pick')
-        }
-        if (scope === 'dry-run-pick') {
-          pullArgs.push('--dry-run', '--pick')
-        }
-        return runSelectedAction(() => runNode('fleet-git-pull-scoped.mjs', pullArgs))
-      }
-      if (choice === 'm12') {
-        const scope = await selectPrompt({
-          message: 'Stage, commit and push all repositories',
-          choices: [
-            { name: 'Stage, commit and push all repos', value: 'run' },
-            { name: 'Dry run (all repos)', value: 'dry-run' },
-            { name: 'Cancel', value: 'cancel' },
-          ],
-          default: 'run',
-          loop: false,
-        })
-        if (scope === 'cancel') continue
-        const commitArgs = scope === 'dry-run' ? ['--dry-run'] : []
-        return runSelectedAction(() => runNode('fleet-git-commit-push.mjs', commitArgs))
+      if (choice === 'policy-outdated') return runSelectedAction(() => runNode('policy-outdated.mjs'))
+      if (choice === 'policy-upgrade') return runSelectedAction(() => runNode('policy-upgrade.mjs'))
+      if (choice === 'refresh-policy') {
+        return runSelectedAction(() => runNode('refresh-dependency-policy-from-repos.mjs'))
       }
-      if (choice === 'm13') {
+      if (choice === 'policy-vulns') return runSelectedAction(() => runNode('policy-vulns.mjs'))
+      if (choice === 'bump-fg-devkit') return runSelectedAction(() => runNode('fleet-bump-fg-devkit.mjs'))
+      if (choice === 'vulns') {
         const scope = await selectPrompt({
-          message: 'Stage, commit and push (choose repositories)',
+          message: 'Vulnerabilities',
           choices: [
-            { name: 'fg-devkit only', value: 'fg-devkit' },
-            { name: 'Choose repositories under projects root', value: 'pick' },
-            { name: 'Dry run + choose repositories', value: 'dry-run-pick' },
+            {
+              name: 'All Vue repos',
+              value: 'all',
+              description: 'pnpm audit in every repo under the projects root, with a summary',
+            },
+            {
+              name: 'fg-devkit only',
+              value: 'fg-devkit',
+              description: 'pnpm audit in fg-devkit and its nested packages',
+            },
             { name: 'Cancel', value: 'cancel' },
           ],
-          default: 'pick',
+          default: 'all',
           loop: false,
         })
         if (scope === 'cancel') continue
-        const commitArgs = []
-        if (scope === 'fg-devkit') {
-          commitArgs.push('--fg-devkit-only')
-        }
-        if (scope === 'pick') {
-          commitArgs.push('--pick')
-        }
-        if (scope === 'dry-run-pick') {
-          commitArgs.push('--dry-run', '--pick')
-        }
-        return runSelectedAction(() => runNode('fleet-git-commit-push-scoped.mjs', commitArgs))
+        return runSelectedAction(() =>
+          scope === 'fg-devkit' ? runMaintainerAuditAll() : runNode('fleet-vulns.mjs'),
+        )
       }
-      if (choice === 'm14') {
-        const scope = await selectPrompt({
-          message: 'Discard tracked changes in all repositories',
-          choices: [
-            { name: 'Discard tracked changes in all repos', value: 'run' },
-            { name: 'Dry run (all repos)', value: 'dry-run' },
-            { name: 'Cancel', value: 'cancel' },
-          ],
-          default: 'run',
-          loop: false,
-        })
-        if (scope === 'cancel') continue
-        const discardArgs = scope === 'dry-run' ? ['--dry-run'] : []
-        return runSelectedAction(() => runNode('fleet-git-discard.mjs', discardArgs))
+
+      // Toolchain bumps always update fg-devkit itself; the git actions treat it as one repo among the rest.
+      const fleetActions = {
+        'bump-pnpm': { message: 'Bump pnpm', script: 'bump-pnpm-toolchain.mjs', toolchain: true, default: 'fg-devkit' },
+        'bump-node': { message: 'Bump Node', script: 'bump-node-toolchain.mjs', toolchain: true, default: 'pick' },
+        'git-pull': { message: 'Git pull', script: 'fleet-git-pull-scoped.mjs', default: 'pick' },
+        'git-commit-push': { message: 'Commit & push', script: 'fleet-git-commit-push-scoped.mjs', default: 'pick' },
+        'git-discard': { message: 'Discard changes', script: 'fleet-git-discard-scoped.mjs', default: 'pick' },
       }
-      if (choice === 'm15') {
-        const scope = await selectPrompt({
-          message: 'Discard tracked changes (choose repositories)',
-          choices: [
-            { name: 'fg-devkit only', value: 'fg-devkit' },
-            { name: 'Choose repositories under projects root', value: 'pick' },
-            { name: 'Dry run + choose repositories', value: 'dry-run-pick' },
-            { name: 'Cancel', value: 'cancel' },
-          ],
-          default: 'pick',
-          loop: false,
-        })
-        if (scope === 'cancel') continue
-        const discardArgs = []
-        if (scope === 'fg-devkit') {
-          discardArgs.push('--fg-devkit-only')
-        }
-        if (scope === 'pick') {
-          discardArgs.push('--pick')
-        }
-        if (scope === 'dry-run-pick') {
-          discardArgs.push('--dry-run', '--pick')
-        }
-        return runSelectedAction(() => runNode('fleet-git-discard-scoped.mjs', discardArgs))
+      const action = fleetActions[choice]
+      const scope = await selectPrompt({
+        message: action.message,
+        choices: [
+          {
+            name: action.toolchain ? 'fg-devkit + all repos' : 'All repos',
+            value: 'all',
+            description: 'Every repo under the projects root',
+          },
+          {
+            name: interactive(action.toolchain ? 'fg-devkit + choose repos' : 'Choose repos'),
+            value: 'pick',
+            description: 'Pick repos in a checklist',
+          },
+          { name: 'fg-devkit only', value: 'fg-devkit', description: 'Only this repo' },
+          { name: 'Dry run, all repos', value: 'dry-run-all', description: 'Show what would happen, change nothing' },
+          {
+            name: interactive('Dry run, choose repos'),
+            value: 'dry-run-pick',
+            description: 'Show what would happen, change nothing',
+          },
+          { name: 'Cancel', value: 'cancel' },
+        ],
+        default: action.default,
+        loop: false,
+      })
+      if (scope === 'cancel') continue
+      const scopeArgs = {
+        all: ['--all'],
+        pick: ['--pick'],
+        'fg-devkit': [action.toolchain ? '--skip-fleet' : '--fg-devkit-only'],
+        'dry-run-all': ['--dry-run', '--all'],
+        'dry-run-pick': ['--dry-run', '--pick'],
       }
-      return 1
+      return runSelectedAction(() => runNode(action.script, scopeArgs[scope]))
     }
   }
 
@@ -1300,11 +1260,7 @@ async function main() {
       return
     }
     if (sub === 'commit') {
-      process.exitCode = await runCzg(rest)
-      return
-    }
-    if (sub === 'commit-vuln' || sub === 'vuln-commit' || sub === 'commit:vuln') {
-      process.exitCode = runNode('vuln-commit.mjs', rest)
+      process.exitCode = await runCommit(rest)
       return
     }
     if (sub === 'scaffold-vue') {
@@ -1361,11 +1317,8 @@ async function main() {
       return
     }
     if (
-      (sub === 'fleet-git-pull' ||
-        sub === 'fleet-git-pull-scoped' ||
-        sub === 'fleet-git-commit-push' ||
+      (sub === 'fleet-git-pull-scoped' ||
         sub === 'fleet-git-commit-push-scoped' ||
-        sub === 'fleet-git-discard' ||
         sub === 'fleet-git-discard-scoped') &&
       !isFgDevkitMaintainerContext()
     ) {