buildflow-dev 1.0.2 → 1.0.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "buildflow-dev",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "description": "Adaptive AI-powered development orchestration. Works with Claude Code, Gemini CLI, Codex CLI, Cursor, and more.",
   "keywords": [
     "ai",

package/src/commands/install.js

@@ -26,6 +26,9 @@ const TOOLS = {
       return hasCli || hasClaudeDir
     },
 
+    isInstalledLocal()  { return existsSync(join(process.cwd(), '.claude', 'commands', 'buildflow-start.md')) },
+    isInstalledGlobal() { return existsSync(join(homedir(), '.claude', 'commands', 'buildflow-start.md')) },
+
     installGlobal(commandFiles) {
       const dir = join(homedir(), '.claude', 'commands')
       mkdirSync(dir, { recursive: true })
@@ -56,17 +59,29 @@ const TOOLS = {
     docsUrl: 'https://github.com/google-gemini/gemini-cli',
 
     detect() {
-      try { which.sync('gemini'); return true } catch { return false }
+      const hasCli = (() => { try { which.sync('gemini'); return true } catch { return false } })()
+      // Also check config dir — binary may not be on PATH in all shells
+      const hasGeminiDir = existsSync(join(homedir(), '.gemini'))
+      return hasCli || hasGeminiDir
+    },
+
+    isInstalledLocal() {
+      const cmdFile = existsSync(join(process.cwd(), '.gemini', 'commands', 'start.md'))
+      const ctxFile = existsSync(join(process.cwd(), 'GEMINI.md')) &&
+        readFileSafe(join(process.cwd(), 'GEMINI.md')).includes('BuildFlow')
+      return cmdFile || ctxFile
+    },
+    isInstalledGlobal() {
+      const cmdFile = existsSync(join(homedir(), '.gemini', 'commands', 'start.md'))
+      const ctxFile = existsSync(join(homedir(), '.gemini', 'GEMINI.md')) &&
+        readFileSafe(join(homedir(), '.gemini', 'GEMINI.md')).includes('BuildFlow')
+      return cmdFile || ctxFile
     },
 
     installGlobal(commandFiles) {
       const dir = join(homedir(), '.gemini', 'commands')
       mkdirSync(dir, { recursive: true })
-      const contextPath = join(homedir(), '.gemini', 'GEMINI.md')
-      const existingContent = existsSync(contextPath) ? readFileSync(contextPath, 'utf8') : ''
-      if (!existingContent.includes('## BuildFlow Commands')) {
-        writeFileSync(contextPath, existingContent + '\n\n' + geminiContextBlock(commandFiles))
-      }
+      patchGeminiContext(join(homedir(), '.gemini', 'GEMINI.md'), commandFiles)
       for (const [name, content] of Object.entries(commandFiles)) {
         writeFileSync(join(dir, `${name}.md`), content)
       }
@@ -76,18 +91,14 @@ const TOOLS = {
     installLocal(commandFiles) {
       const dir = join(process.cwd(), '.gemini', 'commands')
       mkdirSync(dir, { recursive: true })
-      const contextPath = join(process.cwd(), 'GEMINI.md')
-      const existingContent = existsSync(contextPath) ? readFileSync(contextPath, 'utf8') : ''
-      if (!existingContent.includes('## BuildFlow Commands')) {
-        writeFileSync(contextPath, existingContent + '\n\n' + geminiContextBlock(commandFiles))
-      }
+      patchGeminiContext(join(process.cwd(), 'GEMINI.md'), commandFiles)
       for (const [name, content] of Object.entries(commandFiles)) {
         writeFileSync(join(dir, `${name}.md`), content)
       }
       return dir
     },
 
-    triggerNote: 'In Gemini CLI, type "/" or @buildflow to use commands',
+    triggerNote: 'In Gemini CLI, type "/buildflow-start" or ask Gemini to run a buildflow command',
   },
 
   codex: {
@@ -98,35 +109,40 @@ const TOOLS = {
     docsUrl: 'https://github.com/openai/codex',
 
     detect() {
-      try { which.sync('codex'); return true } catch { return false }
+      const hasCli = (() => { try { which.sync('codex'); return true } catch { return false } })()
+      const hasCodexDir = existsSync(join(homedir(), '.codex'))
+      return hasCli || hasCodexDir
+    },
+
+    isInstalledLocal()  { return existsSync(join(process.cwd(), '.codex', 'instructions', 'buildflow-start.md')) },
+    isInstalledGlobal() { return existsSync(join(homedir(), '.codex', 'instructions', 'buildflow-start.md')) },
+
+    installGlobal(commandFiles) {
+      const dir = join(homedir(), '.codex', 'instructions')
+      const skillsDir = join(homedir(), '.codex', 'skills')
+      mkdirSync(dir, { recursive: true })
+      for (const [name, content] of Object.entries(commandFiles)) {
+        writeFileSync(join(dir, `buildflow-${name}.md`), content)
+        writeCodexSkill(skillsDir, name, content)
+      }
+      patchAgentsMd(join(homedir(), '.codex', 'AGENTS.md'), 'global')
+      return `${dir} + ${skillsDir}`
+    },
+
+    installLocal(commandFiles) {
+      const dir = join(process.cwd(), '.codex', 'instructions')
+      const skillsDir = join(process.cwd(), '.codex', 'skills')
+      mkdirSync(dir, { recursive: true })
+      for (const [name, content] of Object.entries(commandFiles)) {
+        writeFileSync(join(dir, `buildflow-${name}.md`), content)
+        writeCodexSkill(skillsDir, name, content)
+      }
+      patchAgentsMd(join(process.cwd(), 'AGENTS.md'), 'local')
+      return `${dir} + ${skillsDir}`
     },
 
-    installGlobal(commandFiles) {
-      const dir = join(homedir(), '.codex', 'instructions')
-      const skillsDir = join(homedir(), '.codex', 'skills')
-      mkdirSync(dir, { recursive: true })
-      for (const [name, content] of Object.entries(commandFiles)) {
-        writeFileSync(join(dir, `buildflow-${name}.md`), content)
-        writeCodexSkill(skillsDir, name, content)
-      }
-      patchAgentsMd(join(homedir(), '.codex', 'AGENTS.md'), 'global')
-      return `${dir} + ${skillsDir}`
-    },
-
-    installLocal(commandFiles) {
-      const dir = join(process.cwd(), '.codex', 'instructions')
-      const skillsDir = join(process.cwd(), '.codex', 'skills')
-      mkdirSync(dir, { recursive: true })
-      for (const [name, content] of Object.entries(commandFiles)) {
-        writeFileSync(join(dir, `buildflow-${name}.md`), content)
-        writeCodexSkill(skillsDir, name, content)
-      }
-      patchAgentsMd(join(process.cwd(), 'AGENTS.md'), 'local')
-      return `${dir} + ${skillsDir}`
-    },
-
-    triggerNote: 'In Codex CLI, use $buildflow-start or say "use buildflow-start". Slash menu commands are not exposed by Codex.',
-  },
+    triggerNote: 'In Codex CLI, use $buildflow-start or say "use buildflow-start". Slash menu commands are not exposed by Codex.',
+  },
 
   cursor: {
     id: 'cursor',
@@ -143,6 +159,9 @@ const TOOLS = {
       return hasCursorApp || hasCursorDir
     },
 
+    isInstalledLocal()  { return existsSync(join(process.cwd(), '.cursor', 'rules', 'buildflow.mdc')) },
+    isInstalledGlobal() { return this.isInstalledLocal() },
+
     installGlobal(commandFiles) {
       return this.installLocal(commandFiles)
     },
@@ -175,6 +194,11 @@ const TOOLS = {
       )
     },
 
+    isInstalledLocal() {
+      return readFileSafe(join(process.cwd(), '.clinerules')).includes('BuildFlow')
+    },
+    isInstalledGlobal() { return this.isInstalledLocal() },
+
     installGlobal(commandFiles) {
       return this.installLocal(commandFiles)
     },
@@ -198,6 +222,9 @@ const TOOLS = {
       return existsSync(join(homedir(), '.continue', 'config.json'))
     },
 
+    isInstalledLocal()  { return existsSync(join(process.cwd(), '.continue', 'buildflow', 'start.md')) },
+    isInstalledGlobal() { return existsSync(join(homedir(), '.continue', 'buildflow', 'start.md')) },
+
     installGlobal(commandFiles) {
       const dir = join(homedir(), '.continue', 'buildflow')
       mkdirSync(dir, { recursive: true })
@@ -222,41 +249,64 @@ const TOOLS = {
 
 }
 
+const UPDATE_CHECK_INSTRUCTION = `
+## BuildFlow Update Check (Run Every Session)
+
+At the very start of every session, before anything else:
+1. Check if \`.buildflow/core/UPDATE.md\` exists
+2. If it does, show the user this notice:
+   > "BuildFlow update available — run \`npx buildflow-dev update\` in your terminal to upgrade."
+   Then show the contents of UPDATE.md so the user sees the version details.
+3. If the file does not exist, proceed silently.
+`
+
 function geminiContextBlock(commandFiles) {
   const commandList = Object.keys(commandFiles)
     .map(name => `- \`/buildflow-${name}\`: see .gemini/commands/${name}.md`)
     .join('\n')
-  return `## BuildFlow Commands\n\nWhen the user types a /buildflow-* command, load and execute the corresponding file from .gemini/commands/.\n\n${commandList}`
+  return `## BuildFlow Commands
+
+When the user types a /buildflow-* command, load and execute the corresponding file from .gemini/commands/.
+
+${commandList}
+${UPDATE_CHECK_INSTRUCTION}`
 }
 
-function patchAgentsMd(filePath, scope) {
-  const existing = existsSync(filePath) ? readFileSync(filePath, 'utf8') : ''
-  if (existing.includes('BuildFlow')) return
-  const dir = scope === 'global' ? '~/.codex/instructions/' : '.codex/instructions/'
-  const block = `\n\n## BuildFlow Instructions\n\nWhen the user types $buildflow-<command> or /buildflow-<command>, load the matching file from ${dir} and follow those instructions.\n\nAvailable commands: start, think, plan, build, check, ship, onboard, modify, refactor, audit, status, explain, back, help\n`
-  writeFileSync(filePath, existing + block)
-}
-
-function writeCodexSkill(skillsDir, name, commandContent) {
-  const skillName = `buildflow-${name}`
-  const skillDir = join(skillsDir, skillName)
-  mkdirSync(skillDir, { recursive: true })
-  writeFileSync(join(skillDir, 'SKILL.md'), codexSkillContent(skillName, commandContent))
-}
-
-function codexSkillContent(skillName, commandContent) {
-  const description = extractFrontmatterValue(commandContent, 'description') || `Run ${skillName}`
-  return `---\nname: "${skillName}"\ndescription: "${escapeYamlString(description)}"\nmetadata:\n  short-description: "${escapeYamlString(description)}"\n---\n\n<objective>\nExecute the BuildFlow workflow below end-to-end.\nTreat any user text after $${skillName} as arguments for this workflow.\n</objective>\n\n<workflow>\n${commandContent}\n</workflow>\n`
-}
-
-function extractFrontmatterValue(content, key) {
-  const match = content.match(new RegExp(`^${key}:\\s*(.+)$`, 'm'))
-  return match?.[1]?.trim().replace(/^["']|["']$/g, '')
-}
-
-function escapeYamlString(value) {
-  return value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')
-}
+function patchAgentsMd(filePath, scope) {
+  const existing = readFileSafe(filePath)
+  const dir = scope === 'global' ? '~/.codex/instructions/' : '.codex/instructions/'
+  const block = `## BuildFlow Instructions\n\nWhen the user types $buildflow-<command> or /buildflow-<command>, load the matching file from ${dir} and follow those instructions.\n\nAvailable commands: start, think, plan, build, check, ship, onboard, modify, refactor, audit, status, explain, back, help\n${UPDATE_CHECK_INSTRUCTION}`
+  if (existing.includes('## BuildFlow Instructions')) {
+    const updated = existing.replace(
+      /## BuildFlow Instructions[\s\S]*?(?=\n## |\n# |$)/,
+      block
+    )
+    writeFileSync(filePath, updated)
+  } else {
+    writeFileSync(filePath, existing + (existing ? '\n\n' : '') + block)
+  }
+}
+
+function writeCodexSkill(skillsDir, name, commandContent) {
+  const skillName = `buildflow-${name}`
+  const skillDir = join(skillsDir, skillName)
+  mkdirSync(skillDir, { recursive: true })
+  writeFileSync(join(skillDir, 'SKILL.md'), codexSkillContent(skillName, commandContent))
+}
+
+function codexSkillContent(skillName, commandContent) {
+  const description = extractFrontmatterValue(commandContent, 'description') || `Run ${skillName}`
+  return `---\nname: "${skillName}"\ndescription: "${escapeYamlString(description)}"\nmetadata:\n  short-description: "${escapeYamlString(description)}"\n---\n\n<objective>\nExecute the BuildFlow workflow below end-to-end.\nTreat any user text after $${skillName} as arguments for this workflow.\n</objective>\n\n<workflow>\n${commandContent}\n</workflow>\n`
+}
+
+function extractFrontmatterValue(content, key) {
+  const match = content.match(new RegExp(`^${key}:\\s*(.+)$`, 'm'))
+  return match?.[1]?.trim().replace(/^["']|["']$/g, '')
+}
+
+function escapeYamlString(value) {
+  return value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')
+}
 
 function cursorRulesContent(commandFiles) {
   const commandDescriptions = Object.keys(commandFiles)
@@ -271,7 +321,7 @@ alwaysApply: false
 # BuildFlow v3.0
 
 You are integrated with BuildFlow, an adaptive development orchestration system.
-
+${UPDATE_CHECK_INSTRUCTION}
 ## Available Commands
 
 When the user types @buildflow-<command> or references a buildflow command, execute the corresponding workflow:
@@ -308,7 +358,7 @@ function clineRulesContent(commandFiles) {
     .map(name => `- /buildflow-${name}`)
     .join('\n')
   return `# BuildFlow v3.0 Rules for Cline
-
+${UPDATE_CHECK_INSTRUCTION}
 ## Slash Commands
 
 When the user types any of the following commands, load the corresponding instruction file from .buildflow/commands/:
@@ -371,6 +421,27 @@ function readdirSafe(dir) {
   }
 }
 
+function readFileSafe(filePath) {
+  try { return readFileSync(filePath, 'utf8') } catch { return '' }
+}
+
+// Writes or replaces the BuildFlow block in a GEMINI.md context file.
+// Always overwrites the block so updates pick up new commands.
+function patchGeminiContext(contextPath, commandFiles) {
+  const existing = readFileSafe(contextPath)
+  const block = geminiContextBlock(commandFiles)
+  if (existing.includes('## BuildFlow Commands')) {
+    // Replace old block — from the marker to the next top-level ## or end of file
+    const updated = existing.replace(
+      /## BuildFlow Commands[\s\S]*?(?=\n## |\n# |$)/,
+      block.trimStart()
+    )
+    writeFileSync(contextPath, updated)
+  } else {
+    writeFileSync(contextPath, existing + (existing ? '\n\n' : '') + block)
+  }
+}
+
 function detectAppName() {
   const pkgPath = join(process.cwd(), 'package.json')
   if (existsSync(pkgPath)) {
@@ -384,6 +455,55 @@ function detectAppName() {
   return process.cwd().split(/[/\\]/).pop() || 'my-project'
 }
 
+export async function refreshInstalledTools(opts = {}) {
+  const commandFiles = loadCommandTemplates()
+  const commandCount = Object.keys(commandFiles).length
+  const results = []
+
+  for (const tool of Object.values(TOOLS)) {
+    const local  = tool.isInstalledLocal()
+    const global = tool.isInstalledGlobal()
+    if (!local && !global) continue
+
+    const sp = ora(`  ${tool.icon}  Refreshing ${tool.name}...`).start()
+    try {
+      if (local)  tool.installLocal(commandFiles)
+      if (global && !local) tool.installGlobal(commandFiles)
+      sp.succeed(chalk.green(`  ${tool.icon}  ${tool.name}`) + chalk.dim(` — ${commandCount} commands refreshed`))
+      results.push({ tool, success: true })
+    } catch (err) {
+      sp.fail(chalk.red(`  ${tool.icon}  ${tool.name} — ${err.message}`))
+      results.push({ tool, success: false, error: err })
+    }
+  }
+
+  if (results.length === 0) {
+    console.log(chalk.yellow('  No previously installed tools found.'))
+    console.log(chalk.dim('  Run: buildflow install\n'))
+  } else {
+    const failed = results.filter(r => !r.success)
+    if (failed.length > 0) {
+      console.log(chalk.red('\n  Some tools failed to update:'))
+      for (const { tool, error } of failed) {
+        console.log(chalk.red(`  ✗ ${tool.name}: ${error.message}`))
+      }
+    }
+  }
+
+  return results
+}
+
+export function getToolStatus() {
+  return Object.values(TOOLS).map(tool => ({
+    id:              tool.id,
+    name:            tool.name,
+    icon:            tool.icon,
+    detected:        tool.detect(),
+    installedLocal:  tool.isInstalledLocal(),
+    installedGlobal: tool.isInstalledGlobal(),
+  }))
+}
+
 function loadCommandTemplates() {
   const templatesDir = join(__dirname, '../../templates/commands')
   const commands = {}
@@ -418,17 +538,30 @@ export async function run(opts = {}) {
   const detectedList = Object.entries(detected).filter(([, found]) => found)
   const notFoundList = Object.entries(detected).filter(([, found]) => !found)
 
+  // Tools detected on the system but BuildFlow not yet installed into them
+  const newlyDetected = detectedList.filter(([id]) => {
+    const t = TOOLS[id]
+    return !t.isInstalledLocal() && !t.isInstalledGlobal()
+  })
+
   if (detectedList.length > 0) {
     console.log(chalk.green('  ✓ Detected on your system:'))
     for (const [id] of detectedList) {
       const t = TOOLS[id]
-      console.log(chalk.green(`    ${t.icon}  ${t.name}`) + chalk.dim(` — ${t.description}`))
+      const installed = t.isInstalledLocal() || t.isInstalledGlobal()
+      const badge = installed ? chalk.dim(' (already installed)') : chalk.yellow(' (not yet installed)')
+      console.log(chalk.green(`    ${t.icon}  ${t.name}`) + badge)
     }
   } else {
     console.log(chalk.yellow('  ⚠  No AI tools detected automatically.'))
     console.log(chalk.dim('     You can still install for tools not on this list.\n'))
   }
 
+  if (newlyDetected.length > 0) {
+    console.log(chalk.yellow(`\n  ${newlyDetected.length} tool(s) detected but BuildFlow not installed yet.`))
+    console.log(chalk.dim('  They are pre-selected below.\n'))
+  }
+
   if (notFoundList.length > 0) {
     console.log(chalk.dim('\n  Not detected (can still install):'))
     for (const [id] of notFoundList) {
@@ -453,11 +586,19 @@ export async function run(opts = {}) {
       return
     }
   } else {
-    const choices = Object.entries(TOOLS).map(([id, tool]) => ({
-      name: id,
-      message: `${tool.icon}  ${tool.name}${detected[id] ? chalk.green(' ✓') : ''}`,
-      hint: tool.description,
-    }))
+    const choices = Object.entries(TOOLS).map(([id, tool]) => {
+      const isInstalled = tool.isInstalledLocal() || tool.isInstalledGlobal()
+      const statusBadge = !detected[id]
+        ? ''
+        : isInstalled
+          ? chalk.dim(' (reinstall)')
+          : chalk.yellow(' ← new')
+      return {
+        name: id,
+        message: `${tool.icon}  ${tool.name}${statusBadge}`,
+        hint: tool.description,
+      }
+    })
 
     const { tools } = await prompt({
       type: 'multiselect',
@@ -465,7 +606,10 @@ export async function run(opts = {}) {
       message: 'Which AI tools do you want to install BuildFlow into?',
       hint: '(Space to select, Enter to confirm)',
       choices,
-      initial: detectedList.map(([id]) => id),
+      // Pre-select newly detected tools (detected but not yet installed)
+      initial: newlyDetected.length > 0
+        ? newlyDetected.map(([id]) => id)
+        : detectedList.map(([id]) => id),
     })
 
     if (!tools || tools.length === 0) {
@@ -561,18 +705,18 @@ export async function run(opts = {}) {
     }
   }
 
-  if (succeeded.length > 0) {
-    console.log(chalk.bold('\n  Next steps:\n'))
-    console.log(chalk.white('  1. Open your AI tool in this project'))
-    if (succeeded.every(({ tool }) => tool.id === 'codex')) {
-      console.log(chalk.white('  2. Restart Codex CLI so new skills are loaded'))
-      console.log(chalk.white('  3. Start with: ') + chalk.cyan('$buildflow-start'))
-      console.log(chalk.white('     Or for existing projects: ') + chalk.cyan('$buildflow-onboard'))
-    } else {
-      console.log(chalk.white('  2. Type "/" to see BuildFlow commands'))
-      console.log(chalk.white('  3. Start with: ') + chalk.cyan('/buildflow-start'))
-      console.log(chalk.white('     Or for existing projects: ') + chalk.cyan('/buildflow-onboard'))
-    }
-    console.log('')
-  }
-}
+  if (succeeded.length > 0) {
+    console.log(chalk.bold('\n  Next steps:\n'))
+    console.log(chalk.white('  1. Open your AI tool in this project'))
+    if (succeeded.every(({ tool }) => tool.id === 'codex')) {
+      console.log(chalk.white('  2. Restart Codex CLI so new skills are loaded'))
+      console.log(chalk.white('  3. Start with: ') + chalk.cyan('$buildflow-start'))
+      console.log(chalk.white('     Or for existing projects: ') + chalk.cyan('$buildflow-onboard'))
+    } else {
+      console.log(chalk.white('  2. Type "/" to see BuildFlow commands'))
+      console.log(chalk.white('  3. Start with: ') + chalk.cyan('/buildflow-start'))
+      console.log(chalk.white('     Or for existing projects: ') + chalk.cyan('/buildflow-onboard'))
+    }
+    console.log('')
+  }
+}

package/src/commands/status.js

@@ -1,6 +1,7 @@
 import chalk from 'chalk'
 import { existsSync, readFileSync, readdirSync, statSync } from 'fs'
 import { join } from 'path'
+import { getToolStatus } from './install.js'
 
 export async function run(opts = {}) {
   const base = join(process.cwd(), '.buildflow')
@@ -35,10 +36,44 @@ export async function run(opts = {}) {
      onboarded === 'n/a'  ? chalk.dim('N/A (greenfield)') :
                             chalk.yellow('No — run /buildflow-onboard')))
 
-  const hasDebt = debt.includes('## Active') && !debt.includes('[None]')
+  const hasDebt = debt.includes('## Active') && !debt.includes('*None')
   console.log(chalk.dim('  Security debt: ') +
     (hasDebt ? chalk.red('⚠ Issues pending — see .buildflow/security/DEBT.md') : chalk.green('Clean')))
 
+  // ── AI Tool Status ──────────────────────────────────────────────────────────
+  console.log(chalk.dim('\n  AI Tools:\n'))
+
+  const tools = getToolStatus()
+  const uninstalled = []
+
+  for (const t of tools) {
+    if (!t.detected) {
+      console.log(chalk.dim(`    ${t.icon}  ${t.name}`) + chalk.dim('  — not installed on this machine'))
+      continue
+    }
+
+    const local  = t.installedLocal
+    const global = t.installedGlobal
+
+    if (local || global) {
+      const scope = local && global ? 'local + global' : local ? 'local' : 'global'
+      console.log(chalk.green(`    ${t.icon}  ${t.name}`) + chalk.dim(`  ✓ BuildFlow installed (${scope})`))
+    } else {
+      console.log(chalk.yellow(`    ${t.icon}  ${t.name}`) + chalk.yellow('  ⚠ Detected but BuildFlow not installed'))
+      uninstalled.push(t)
+    }
+  }
+
+  if (uninstalled.length > 0) {
+    console.log('')
+    console.log(chalk.yellow('  Some tools are missing BuildFlow commands.'))
+    console.log(chalk.dim('  Run one of:'))
+    for (const t of uninstalled) {
+      console.log(chalk.white(`    buildflow install --tool ${t.id}`))
+    }
+    console.log(chalk.dim('  Or: buildflow install  (interactive)'))
+  }
+
   if (opts.verbose) {
     console.log(chalk.dim('\n  .buildflow/ structure:'))
     const walk = (dir, prefix = '    ') => {

package/src/commands/update.js

@@ -3,7 +3,8 @@ import ora from 'ora'
 import { existsSync, readFileSync } from 'fs'
 import { join, dirname } from 'path'
 import { fileURLToPath } from 'url'
-import { run as runInstall } from './install.js'
+import { refreshInstalledTools } from './install.js'
+import { checkVersion, clearUpdateNotice } from '../utils/checkVersion.js'
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
 
@@ -15,21 +16,30 @@ export async function run(opts = {}) {
     return
   }
 
+  const pkg = JSON.parse(readFileSync(join(__dirname, '../../package.json'), 'utf8'))
+
   if (opts.check) {
     console.log('\n' + chalk.bold.white('  BuildFlow Update Check\n'))
-    const pkgPath = join(__dirname, '../../package.json')
-    const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'))
-    console.log(chalk.dim(`  Local version: ${pkg.version}`))
-    console.log(chalk.dim('  Run: npx buildflow-dev update  to update commands\n'))
+    const sp = ora('Checking npm registry...').start()
+    const update = await checkVersion(pkg.version)
+    sp.stop()
+
+    if (update) {
+      console.log(chalk.yellow(`  Update available: ${update.current} → ${update.latest}`))
+      console.log(chalk.white('  Run: npx buildflow-dev update\n'))
+    } else {
+      console.log(chalk.green(`  ✓ Up to date (v${pkg.version})\n`))
+    }
     return
   }
 
   console.log('\n' + chalk.bold.white('  Updating BuildFlow...\n'))
 
-  const sp = ora('Updating command files...').start()
-  await new Promise(r => setTimeout(r, 400))
-  sp.succeed(chalk.green('  ✓ Command files updated'))
+  // Re-push latest command templates to all previously installed tools
+  await refreshInstalledTools()
+
+  // Clear the update notice now that we've updated
+  clearUpdateNotice()
 
-  console.log('')
-  await runInstall({ yes: opts.yes })
+  console.log(chalk.green(`\n  ✓ BuildFlow updated to v${pkg.version}\n`))
 }

package/src/utils/checkVersion.js

@@ -0,0 +1,72 @@
+import { existsSync, writeFileSync, unlinkSync, mkdirSync } from 'fs'
+import { join } from 'path'
+
+const REGISTRY_URL = 'https://registry.npmjs.org/buildflow-dev/latest'
+const UPDATE_FILE  = '.buildflow/core/UPDATE.md'
+
+export async function checkVersion(currentVersion) {
+  try {
+    const res = await fetch(REGISTRY_URL, {
+      signal: AbortSignal.timeout(3000),
+      headers: { Accept: 'application/json' },
+    })
+    if (!res.ok) return null
+
+    const { version: latest } = await res.json()
+    const updatePath = join(process.cwd(), UPDATE_FILE)
+
+    if (latest === currentVersion) {
+      // Remove stale notice if we're already up to date
+      if (existsSync(updatePath)) unlinkSync(updatePath)
+      return null
+    }
+
+    // Only write the file if .buildflow/ exists (i.e. project is initialized)
+    const coreDir = join(process.cwd(), '.buildflow', 'core')
+    if (!existsSync(coreDir)) return { current: currentVersion, latest }
+
+    mkdirSync(coreDir, { recursive: true })
+    writeFileSync(updatePath, buildUpdateNotice(currentVersion, latest))
+
+    return { current: currentVersion, latest }
+  } catch {
+    return null  // Network timeout or offline — silently skip
+  }
+}
+
+export function clearUpdateNotice() {
+  const updatePath = join(process.cwd(), UPDATE_FILE)
+  if (existsSync(updatePath)) unlinkSync(updatePath)
+}
+
+function buildUpdateNotice(current, latest) {
+  return `# BuildFlow Update Available
+
+> A new version of BuildFlow is available.
+> Your AI tool detected this file at session start.
+
+| | Version |
+|---|---|
+| **Installed** | ${current} |
+| **Latest** | ${latest} |
+
+## How to Update
+
+Run this in your terminal:
+
+\`\`\`bash
+npx buildflow-dev update
+\`\`\`
+
+Or if installed globally:
+
+\`\`\`bash
+npm install -g buildflow-dev@latest
+\`\`\`
+
+After updating, this notice will disappear automatically.
+
+---
+*Generated by BuildFlow CLI · ${new Date().toISOString().split('T')[0]}*
+`
+}

package/src/utils/welcome.js

@@ -1,8 +1,21 @@
 import chalk from 'chalk'
 import { existsSync, readFileSync } from 'fs'
-import { join } from 'path'
+import { join, dirname } from 'path'
+import { fileURLToPath } from 'url'
+import { checkVersion } from './checkVersion.js'
+import { getToolStatus } from '../commands/install.js'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
 
 export async function showWelcome() {
+  const pkg = JSON.parse(readFileSync(join(__dirname, '../../package.json'), 'utf8'))
+  // Fire-and-forget version check — writes UPDATE.md if behind, doesn't block output
+  checkVersion(pkg.version).then(update => {
+    if (update) {
+      console.log(chalk.yellow(`\n  Update available: ${update.current} → ${update.latest}`))
+      console.log(chalk.dim('  Run: npx buildflow-dev update\n'))
+    }
+  }).catch(() => {})
   const isInitialized = existsSync(join(process.cwd(), '.buildflow'))
 
   console.log('\n' + chalk.bold.white('  BuildFlow v3.0'))
@@ -56,6 +69,16 @@ export async function showWelcome() {
     console.log(chalk.white('    buildflow status  ') + chalk.dim('  Show project status'))
     console.log(chalk.white('    buildflow audit   ') + chalk.dim('  Run security audit from terminal'))
     console.log(chalk.white('    buildflow update  ') + chalk.dim('  Update BuildFlow commands'))
+
+    // Surface any newly installed AI tools that don't have BuildFlow yet
+    const uninstalled = getToolStatus().filter(t => t.detected && !t.installedLocal && !t.installedGlobal)
+    if (uninstalled.length > 0) {
+      console.log('')
+      console.log(chalk.yellow(`  New AI tool(s) detected — BuildFlow not installed yet:`))
+      for (const t of uninstalled) {
+        console.log(chalk.yellow(`    ${t.icon}  ${t.name}`) + chalk.dim(`  → buildflow install --tool ${t.id}`))
+      }
+    }
   } else {
     console.log(chalk.yellow('  Not initialized in this directory.\n'))
     console.log(chalk.bold('  Get started:\n'))

package/templates/CLAUDE.md

@@ -2,6 +2,20 @@
 
 This project uses **BuildFlow v3.0** for adaptive AI-powered development orchestration.
 
+## Session Start Checklist (Run Every Time)
+
+Before doing anything else at the start of every session:
+
+1. **Check for updates** — if `.buildflow/core/UPDATE.md` exists, show the user this notice:
+   > "BuildFlow update available — run `npx buildflow-dev update` in your terminal."
+   Then display the contents of UPDATE.md so the user sees the version details.
+   If the file does not exist, proceed silently.
+
+2. **Load memory** — read `.buildflow/memory/light.md` for project context
+3. **Load state** — read `.buildflow/core/state.md` for current phase and status
+
+---
+
 ## Quick Start
 
 Type `/` in Claude Code to see available commands: