@golba98/codexa 1.0.5 → 1.0.7

package/README.md

@@ -26,8 +26,10 @@ codexa --version
 | Local dev / running from source | [Bun](https://bun.sh) |
 | Codex/OpenAI route | Codex CLI installed and authenticated |
 | Claude/Anthropic route | Claude Code CLI installed and authenticated |
-| Gemini/Google route | Gemini CLI installed and authenticated |
+| Mistral Vibe route | Mistral Vibe CLI (`vibe`) installed and authenticated |
+| Antigravity route | Antigravity CLI (`agy`) installed and authenticated |
 | Local route | LM Studio (or any OpenAI-compatible server) |
+| Gemini/Google route | *(Legacy)* Gemini CLI installed and authenticated (falls back to OpenAI route) |
 
 ## Installing Codexa
 
@@ -73,6 +75,8 @@ Codexa and provider CLIs are independent tools with separate version numbers. Up
 |------|---------|---------------|--------|
 | Codex CLI | OpenAI coding agent | `codex --version` | `codex update` or reinstall |
 | Claude Code CLI | Anthropic coding agent | `claude --version` | `npm install -g @anthropic-ai/claude-code@latest` |
+| Mistral Vibe CLI | Mistral coding agent | `vibe --version` | `vibe --setup` or reinstall |
+| Antigravity CLI | Antigravity coding agent | `agy --version` | Reinstall via package manager |
 | Codexa | TUI wrapper / workspace experience | `codexa --version` | `npm install -g @golba98/codexa@latest` |
 
 ## Provider CLI Setup
@@ -146,9 +150,12 @@ claude
 npm install -g @anthropic-ai/claude-code@latest
 ```
 
-### Installing Gemini CLI
+### Installing Gemini CLI (Legacy / Deprecated)
 
-Codexa routes to the `gemini` executable. Install the Gemini CLI separately and authenticate per Google's instructions. Once installed and authenticated, Codexa can use it without additional configuration.
+> [!NOTE]
+> Google/Gemini is no longer supported as an active provider route inside Codexa and falls back automatically to the OpenAI/Codex route.
+
+If you are using legacy features that route to the `gemini` executable, install the Gemini CLI separately and authenticate per Google's instructions.
 
 If the Gemini executable is not on PATH or has a non-standard name, specify it explicitly:
 
@@ -160,6 +167,30 @@ export GEMINI_EXECUTABLE="/path/to/gemini"
 gemini_command_path = "/path/to/gemini"
 ```
 
+### Installing Mistral Vibe CLI
+
+Codexa supports routing through the Mistral Vibe CLI (`vibe`).
+
+1. **Install Vibe CLI** — Install the Mistral Vibe CLI tool.
+2. **Authenticate Vibe** — Run `vibe` or `vibe --setup` in a terminal and sign in when prompted.
+3. **Environment & Config (Optional)**:
+   - Codexa automatically detects the active model from your environment (`VIBE_ACTIVE_MODEL`) or configuration files (`.vibe/config.toml` in your project/workspace, or `~/.vibe/config.toml`).
+   - You can customize the active session location using the `VIBE_HOME` environment variable.
+
+### Installing Antigravity CLI
+
+Codexa supports routing through the Antigravity CLI (`agy`).
+
+1. **Install Antigravity CLI** — Install the Antigravity CLI tool (`agy`).
+2. **Authenticate Antigravity** — Authenticate the CLI according to your provider setup.
+3. **Environment & Config (Optional)**:
+   - Specifying the `agy` command path:
+     ```toml
+     # in .codex/config.toml
+     antigravity_command_path = "/path/to/agy"
+     ```
+   - Alternatively, set the `AGY_EXECUTABLE` environment variable.
+
 ### Using Local Models (LM Studio)
 
 Codexa can route the Local provider through any OpenAI-compatible server.
@@ -178,7 +209,15 @@ export CODEXA_LOCAL_API_KEY="lm-studio"
 export CODEXA_LOCAL_MODEL="google/gemma-4-26b-a4b"
 ```
 
-Workspace provider config in `.codexa/providers.json`:
+Provider configuration is stored in Codexa user data and remains isolated per workspace:
+
+- Windows: `%LOCALAPPDATA%\\Codexa\\workspaces\\<workspace-hash>\\providers.json`
+- macOS: `~/Library/Application Support/Codexa/workspaces/<workspace-hash>/providers.json`
+- Linux: `$XDG_DATA_HOME/codexa/workspaces/<workspace-hash>/providers.json` (or `~/.local/share/codexa/...`)
+
+Existing `.codexa/providers.json` files are read as a legacy fallback and are never deleted. New saves go to user data, so opening or configuring Codexa no longer adds `.codexa` files to projects.
+
+The provider config format is:
 
 ```json
 {
@@ -305,6 +344,7 @@ Type `/` in the composer to access in-app commands. Key commands:
 | `/verbose` | Toggle verbose output |
 | `/copy` | Copy last response to clipboard |
 | `/diagnose github` | Run GitHub connectivity diagnostics |
+| `/diagnose providers` | Collect diagnostics for all configured providers |
 | `!<command>` | Run a shell command inline |
 
 ## Layered Config
@@ -425,6 +465,12 @@ UI-only preferences are stored in `~/.codexa-settings.json` (separate from runti
 
 > **Gotcha:** When testing local changes, confirm you are running the local build and not the global one. Use `Get-Command codexa` (Windows) or `which -a codexa` (Linux/macOS) to check.
 
+## Maintainer Documentation
+
+- [Architecture](docs/ARCHITECTURE.md) explains Codexa's entry points, subsystem boundaries, prompt and rendering flows, provider layers, state model, persistence, and maintenance invariants with diagrams.
+- [Source Guide](docs/SOURCE_GUIDE.md) catalogs the purpose of every file under `src/` and records the maintenance rules for each source area.
+- [Developer Scripts](scripts/README.md) lists every package command and explains launcher, shim, audit, build-metadata, smoke, and test behavior.
+
 ## Local Development
 
 **Requirement:** [Bun](https://bun.sh) installed.
@@ -486,6 +532,63 @@ This replaces the global `codexa` with a symlink to the repo. Undo with `npm unl
 npm install -g .
 ```
 
+## Maintainer release and NPM publishing
+
+The package name is `@golba98/codexa`. Publish from the repository root, and
+increment `version` in `package.json` before each release. NPM versions are
+immutable, so never reuse a version that has already been published.
+
+Check the current local and registry versions:
+
+```bash
+npm pkg get name version
+npm whoami
+npm view @golba98/codexa version
+npm view @golba98/codexa dist-tags --json
+```
+
+Run the release checks:
+
+```bash
+bun install
+bun run typecheck
+bun test
+git diff --check
+```
+
+Inspect exactly what will be included in the package:
+
+```bash
+npm pack --dry-run
+```
+
+Publish the next version publicly:
+
+```bash
+npm publish --access public
+```
+
+`npm publish` automatically runs `prepublishOnly`, which regenerates build
+metadata, typechecks, and runs the full test suite. Verify the registry and
+the installed command after publishing:
+
+```bash
+npm view @golba98/codexa version
+npm view @golba98/codexa dist-tags --json
+npm install -g @golba98/codexa@latest
+codexa --version
+```
+
+If the release is tracked in Git, commit the version and generated build-info
+change, then tag and push it:
+
+```bash
+git add package.json src/config/buildInfo.ts README.md scripts/README.md
+git commit -m "release: publish Codexa vX.Y.Z"
+git tag vX.Y.Z
+git push origin main --follow-tags
+```
+
 ## Testing
 
 ```bash
@@ -577,7 +680,7 @@ npm install -g @golba98/codexa@latest
 
 ### Update notice does not appear
 
-Codexa checks for updates on startup and caches the result for 6 hours (stored in `~/.codexa-update-check.json`). The update notice only appears when the npm registry `latest` version is newer than the running version.
+Codexa checks npm for updates on every interactive startup. The local cache at `~/.codexa-update-check.json` is only used as a best-effort fallback if npm is temporarily unavailable. The update notice appears when the npm registry `latest` version is newer than the running version.
 
 Published npm versions are immutable. Versions before the fixed update checker may not show update notices even when a newer package exists. If in doubt, update directly:
 
@@ -588,9 +691,8 @@ npm install -g @golba98/codexa@latest
 If you expect a notice but don't see one:
 
 1. Check the current registry state: `npm view @golba98/codexa dist-tags --json`
-2. Clear the cache to force a fresh check: delete `~/.codexa-update-check.json`, then restart Codexa
-3. Force an explicit check in-app: `/update check`
-4. Update checks are disabled for local dev builds (`codexa-dev` / `cxd`)
+2. Force an explicit check in-app: `/update check`
+3. Update checks are disabled for local dev builds (`codexa-dev` / `cxd`)
 
 | Symptom | Fix |
 |---------|-----|
@@ -606,11 +708,14 @@ If you expect a notice but don't see one:
 
 See [CHANGELOG.md](CHANGELOG.md) for the full release history.
 
-**Current release: v1.0.4**
+**Current release: v1.0.7**
 
-v1.0.4 is an update-notice reliability fix:
-- Older installed versions can detect when npm `latest` is newer
-- `/update check` bypasses stale cache and reports a useful status
-- Failed registry lookups do not get cached as “up to date”
+v1.0.7 keeps workspaces clean: provider choices, imported attachments, and default diagnostic logs now live in Codexa user data instead of a project-local `.codexa` directory.
 
-> Versions before the fixed update checker may not show update notices. Update directly with `npm install -g @golba98/codexa@latest`.
+Other recent releases introduce major additions, including:
+- **Mistral Vibe CLI Routing**: Connect through the `vibe` CLI tool (`vibe --setup`).
+- **Antigravity CLI Routing**: Connect through the `agy` CLI tool (`agy`).
+- **Dynamic Model Discovery & Caching**: Models are discovered dynamically and cached locally at `~/.codexa-model-cache.json` for instant launch, with instant provider sync for the model picker.
+- **Native Terminal Scrollback**: History follows native scrollback with composer anchored at the bottom.
+- **Kitty Keyboard Protocol Fix**: Corrected probe output leak.
+- **Google/Gemini Route Deprecation**: In-Codexa routing for Google/Gemini now falls back to OpenAI/Codex.

package/bin/codexa.js

@@ -1,11 +1,22 @@
 #!/usr/bin/env node
 
 import { spawn } from "child_process";
-import { appendFileSync, mkdirSync, readFileSync } from "fs";
+import { appendFileSync, mkdirSync, readFileSync } from "fs";
+import { homedir } from "os";
 import { dirname, join } from "path";
 import { fileURLToPath } from "url";
 
-process.title = "CODEXA";
+process.title = "CODEXA";
+
+function resolveLauncherDebugDir() {
+  const dataDir = process.env.CODEXA_DATA_DIR?.trim()
+    || (process.platform === "win32"
+      ? join(process.env.LOCALAPPDATA?.trim() || process.env.APPDATA?.trim() || join(homedir(), "AppData", "Local"), "Codexa")
+      : process.platform === "darwin"
+        ? join(homedir(), "Library", "Application Support", "Codexa")
+        : join(process.env.XDG_DATA_HOME?.trim() || join(homedir(), ".local", "share"), "codexa"));
+  return join(dataDir, "debug");
+}
 
 const currentFile = fileURLToPath(import.meta.url);
 const packageRoot = dirname(dirname(currentFile));
@@ -21,7 +32,7 @@ function writeRenderDebugRecord(kind, fields) {
   }
 
   try {
-    const debugDir = join(workspaceRoot, ".codexa", "debug");
+    const debugDir = resolveLauncherDebugDir();
     mkdirSync(debugDir, { recursive: true });
     appendFileSync(
       process.env.CODEXA_RENDER_DEBUG_FILE?.trim() || join(debugDir, "render-status.log"),
@@ -56,7 +67,7 @@ function writeTerminalTitleDebugRecord(fields) {
   }
 
   try {
-    const debugDir = join(workspaceRoot, ".codexa", "debug");
+    const debugDir = resolveLauncherDebugDir();
     mkdirSync(debugDir, { recursive: true });
     appendFileSync(
       process.env.CODEXA_TERMINAL_TITLE_DEBUG_FILE?.trim()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@golba98/codexa",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "description": "Terminal UI for Codexa — TypeScript + Bun + Ink",
   "type": "module",
   "bin": {

package/src/app.tsx

@@ -154,7 +154,8 @@ import {
   type ModelContextMetadata,
 } from "./core/providerRuntime/contextMetadata.js";
 import { captureWorkspaceSnapshot, createWorkspaceActivityTracker, diffWorkspaceSnapshots } from "./core/workspace/workspaceActivity.js";
-import { resolveWorkspaceRoot } from "./core/workspace/workspaceRoot.js";
+import { resolveWorkspaceRoot } from "./core/workspace/workspaceRoot.js";
+import { resolveCodexaAttachmentDir } from "./core/workspace/appData.js";
 import {
   importExternalFile,
   isImageFile,
@@ -270,9 +271,10 @@ import { AppShell } from "./ui/chrome/AppShell.js";
 import { TranscriptShell } from "./ui/timeline/TranscriptShell.js";
 import type { RuntimeAvailability } from "./ui/chrome/RuntimeStatusBar.js";
 import { checkForUpdates, formatLocalDevUpdateStatus, formatUpdateInstructions, shouldRunStartupUpdateCheck, type UpdateCheckResult } from "./core/version/updateCheck.js";
+import { detectGlobalPackageManager, getUpdateCommand } from "./core/version/packageManager.js";
 import { isLocalDevChannel } from "./core/version/channel.js";
 import {
-  isCacheValid,
+  isCacheForRunningVersion,
   loadUpdateCheckCache,
   saveUpdateCheckCache,
 } from "./config/updateCheckCache.js";
@@ -394,9 +396,6 @@ export function App({ launchArgs }: AppProps) {
     ? projectInstructionsLoad.instructions
     : null;
   const initialSettings = useRef(loadSettings());
-  const skippedUpdateVersionRef = useRef<string | null>(
-    initialSettings.current.updateCheck.skippedUpdateVersion ?? null,
-  );
   const initialProviderWorkspaceConfig = useRef<ProviderWorkspaceConfig>(loadProviderWorkspaceConfig(workspaceRoot));
   const initialLayeredConfig = useRef<LayeredConfigResult | null>(null);
   if (initialLayeredConfig.current === null) {
@@ -550,6 +549,9 @@ export function App({ launchArgs }: AppProps) {
   const [planFlow, setPlanFlow] = useState<PlanFlowState>(createInitialPlanFlowState);
   const [initialRevisionText, setInitialRevisionText] = useState("");
   const [updateCheckResult, setUpdateCheckResult] = useState<UpdateCheckResult | null>(null);
+  const [startupUpdateDismissed, setStartupUpdateDismissed] = useState(false);
+  // Launcher path is fixed for the process lifetime, so detect once.
+  const globalPackageManager = useMemo(() => detectGlobalPackageManager(), []);
   // Transcript mode leaves mouse reporting off so wheel/trackpad input scrolls
   // the terminal emulator's native scrollback instead of an in-app viewport.
   const mouseCapture = (mouseOverride ?? (terminalMouseMode === "wheel")) && !isMouseIdle;
@@ -1625,54 +1627,53 @@ export function App({ launchArgs }: AppProps) {
   // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [workspaceRoot]);
 
-  // Non-blocking background update check — runs once at startup.
+  // Non-blocking background update check — fetches npm on every interactive startup.
   useEffect(() => {
     const ucSettings = initialSettings.current.updateCheck ?? DEFAULT_UPDATE_CHECK_SETTINGS;
     if (!shouldRunStartupUpdateCheck(process.env, ucSettings.enabled)) return;
 
-    const timer = setTimeout(() => {
-      void (async () => {
-        try {
-          const cache = loadUpdateCheckCache();
-          if (cache && isCacheValid(cache, ucSettings.intervalHours, APP_VERSION)) {
-            if (cache.updateAvailable && cache.latestVersion) {
-              setUpdateCheckResult({
-                status: "update-available",
-                currentVersion: cache.currentVersion,
-                latestVersion: cache.latestVersion,
-                checkedAt: cache.lastChecked,
-              });
-              if (cache.latestVersion !== skippedUpdateVersionRef.current) {
-                setScreen("update-prompt");
-              }
-            }
-            return;
-          }
-          const result = await checkForUpdates({ enabled: true });
-          if (result.status !== "error") {
-            setUpdateCheckResult(result);
-            saveUpdateCheckCache({
-              lastChecked: result.checkedAt,
-              currentVersion: result.currentVersion,
-              latestVersion: result.latestVersion,
-              updateAvailable: result.status === "update-available",
-            });
-            if (result.status === "update-available" && result.latestVersion) {
-              if (result.latestVersion !== skippedUpdateVersionRef.current) {
-                setScreen("update-prompt");
-              }
-            }
-          }
-        } catch {
-          // Never crash the TUI on a failed update check.
-        }
-      })();
-    }, 2000);
-
-    return () => clearTimeout(timer);
+    void (async () => {
+      const cache = loadUpdateCheckCache();
+      try {
+        const result = await checkForUpdates({ enabled: true });
+        if (result.status === "error") {
+          // A previously confirmed update is still useful when npm is briefly
+          // unreachable, but it must never suppress the next fresh startup check.
+          if (cache?.updateAvailable && cache.latestVersion && isCacheForRunningVersion(cache, APP_VERSION)) {
+            setUpdateCheckResult({
+              status: "update-available",
+              currentVersion: cache.currentVersion,
+              latestVersion: cache.latestVersion,
+              checkedAt: cache.lastChecked,
+              source: "cache",
+            });
+          }
+          return;
+        }
+
+        setUpdateCheckResult(result);
+        saveUpdateCheckCache({
+          lastChecked: result.checkedAt,
+          currentVersion: result.currentVersion,
+          latestVersion: result.latestVersion,
+          updateAvailable: result.status === "update-available",
+        });
+      } catch {
+        // Never crash the TUI on a failed update check.
+      }
+    })();
   // eslint-disable-next-line react-hooks/exhaustive-deps
   }, []);
 
+  // A startup update prompt must not interrupt an active run or another panel.
+  // Keep the result until the user returns to the idle main screen instead.
+  useEffect(() => {
+    if (startupUpdateDismissed || busy || screen !== "main") return;
+    if (updateCheckResult?.status === "update-available" && updateCheckResult.latestVersion) {
+      setScreen("update-prompt");
+    }
+  }, [busy, screen, startupUpdateDismissed, updateCheckResult]);
+
   // Track clear epoch to suppress stale command result events
   useEffect(() => {
     clearEpochRef.current = sessionState.clearEpoch;
@@ -2160,32 +2161,10 @@ export function App({ launchArgs }: AppProps) {
   }, [applyWorkspaceDisplayMode, showBusyLoader, terminalMouseMode, terminalTitleMode, workspaceDisplayMode]);
 
   const handleSkipUpdateForSession = useCallback(() => {
+    setStartupUpdateDismissed(true);
     setScreen("main");
   }, []);
 
-  const handleSkipUpdateVersion = useCallback((version: string) => {
-    initialSettings.current.updateCheck = {
-      ...initialSettings.current.updateCheck,
-      skippedUpdateVersion: version,
-    };
-    saveSettings({
-      ui: {
-        layoutStyle: initialSettings.current.ui.layoutStyle,
-        theme: themeSelection.committedTheme,
-        workspaceDisplayMode,
-        terminalTitleMode,
-        showBusyLoader,
-        terminalMouseMode,
-        customTheme,
-      },
-      auth: { preference: authPreference },
-      header: headerConfig,
-      updateCheck: initialSettings.current.updateCheck,
-    });
-    skippedUpdateVersionRef.current = version;
-    setScreen("main");
-  }, [authPreference, customTheme, headerConfig, showBusyLoader, terminalMouseMode, terminalTitleMode, themeSelection.committedTheme, workspaceDisplayMode]);
-
   const setApprovalPolicyWithNotice = useCallback((nextValue: RuntimeApprovalPolicy) => {
     const gate = guardConfigMutation("mode", busy);
     if (!gate.allowed) {
@@ -3852,13 +3831,12 @@ export function App({ launchArgs }: AppProps) {
 
   const handleImportConfirm = useCallback(async () => {
     if (!pendingImport) return;
-    const replacements: Array<{ rawPath: string; workspaceRelativePath: string }> = [];
+    const replacements: Array<{ rawPath: string; replacementPath: string }> = [];
     for (const file of pendingImport.files) {
       try {
         const destPath = await importExternalFile(file.srcPath, pendingImport.attachmentsDir);
         if (destPath) {
-          const relPath = path.relative(workspaceRoot, destPath).replace(/\\/g, "/");
-          replacements.push({ rawPath: file.rawPath, workspaceRelativePath: relPath });
+          replacements.push({ rawPath: file.rawPath, replacementPath: destPath });
         }
       } catch (err: any) {
         appendErrorEvent("Import failed", `Could not import ${path.basename(file.srcPath)}: ${err.message}`);
@@ -4435,7 +4413,10 @@ export function App({ launchArgs }: AppProps) {
             if (freshResult?.status === "update-available" && freshResult.latestVersion) {
               setScreen("update-prompt");
             } else {
-              appendSystemEvent("Update", formatUpdateInstructions(freshResult));
+              appendSystemEvent(
+                "Update",
+                formatUpdateInstructions(freshResult, getUpdateCommand(globalPackageManager).displayCommand),
+              );
             }
           })();
           return;
@@ -4489,9 +4470,7 @@ export function App({ launchArgs }: AppProps) {
 
     if (outsideViolations.length > 0) {
       if (runtimeConfig.policy.allowExternalFileImport) {
-        const attachmentsDir = path.isAbsolute(runtimeConfig.policy.attachmentDir)
-          ? runtimeConfig.policy.attachmentDir
-          : path.join(workspaceRoot, runtimeConfig.policy.attachmentDir);
+        const attachmentsDir = resolveCodexaAttachmentDir(workspaceRoot, runtimeConfig.policy.attachmentDir);
         const importFiles: PendingImportFile[] = outsideViolations.map((v) => ({
           srcPath: v.normalizedPath,
           rawPath: v.rawPath,
@@ -4527,6 +4506,7 @@ export function App({ launchArgs }: AppProps) {
     dispatchSession,
     findUserPromptForTurn,
     focusManager,
+    globalPackageManager,
     handleCopy,
     handleClear,
     handleQuit,
@@ -4751,8 +4731,12 @@ export function App({ launchArgs }: AppProps) {
           clearCount={sessionState.clearCount}
           headerConfig={effectiveHeaderConfig}
           updateAvailable={
-            updateCheckResult?.status === "update-available" && updateCheckResult.latestVersion
-              ? { latestVersion: updateCheckResult.latestVersion, currentVersion: updateCheckResult.currentVersion }
+            screen !== "update-prompt" && updateCheckResult?.status === "update-available" && updateCheckResult.latestVersion
+              ? {
+                latestVersion: updateCheckResult.latestVersion,
+                currentVersion: updateCheckResult.currentVersion,
+                updateCommand: getUpdateCommand(globalPackageManager).displayCommand,
+              }
               : null
           }
           panel={
@@ -5010,9 +4994,9 @@ export function App({ launchArgs }: AppProps) {
                 focusId={FOCUS_IDS.updatePrompt}
                 currentVersion={updateCheckResult.currentVersion}
                 latestVersion={updateCheckResult.latestVersion}
-                onSkip={handleSkipUpdateForSession}
-                onSkipUntilNextVersion={handleSkipUpdateVersion}
-              />
+                packageManager={globalPackageManager}
+                onSkip={handleSkipUpdateForSession}
+              />
             )}
             </>
           }

package/src/commands/handler.ts

@@ -391,12 +391,12 @@ function buildHelpMessage(context: CommandContext): string {
     `  Current reasoning: ${formatReasoningLabel(context.runtime.reasoningLevel)}`,
     `  Current plan mode: ${context.runtime.planMode ? "Enabled" : "Disabled"}`,
     "  /copy              Copy last response to clipboard",
-    "  /update [check]    Show update status and instructions for updating Codexa",
+    "  /update [status]   Check for updates and install the latest Codexa (status: cached result only)",
     "  /help              Show this help",
-    "",
-    "Local development:",
-    "  npm run install:dev-bin  Install the codexa-dev command",
-    "  codexa-dev               Run this repo without replacing codexa",
+    "",
+    "Local development:",
+    "  npm run install:dev-bin  Install the codexa-dev command",
+    "  codexa-dev               Run this repo without replacing codexa",
     "",
     "Shortcuts:",
     "  Ctrl+B    Open backend picker",
@@ -515,11 +515,11 @@ export function handleCommand(text: string, context: CommandContext): CommandRes
             message: `Unknown reasoning level for ${context.runtime.model}: ${arg}. Valid: ${valid}`,
           };
         }
-        return {
-          action: "reasoning",
-          value: normalized,
-          message: `Reasoning level switched to ${formatReasoningLabel(normalized)} (runtime metadata unavailable; unverified until runtime)`,
-        };
+        return {
+          action: "reasoning",
+          value: normalized,
+          message: `Reasoning level switched to ${formatReasoningLabel(normalized)} (runtime metadata unavailable; unverified until runtime)`,
+        };
       }
 
       case "plan": {
@@ -846,7 +846,9 @@ export function handleCommand(text: string, context: CommandContext): CommandRes
         return { action: "help", message: buildHelpMessage(context) };
 
       case "update":
-        return { action: "update", value: normalizedArg || "status" };
+        // Bare /update forces a fresh registry check; /update status is the
+        // explicit no-network path that reuses the cached/in-memory result.
+        return { action: "update", value: normalizedArg || "check" };
 
       default:
         return {

package/src/config/appVersion.ts

@@ -0,0 +1,65 @@
+import { readFileSync } from "fs";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+import { APP_VERSION as BUILD_INFO_VERSION } from "./buildInfo.js";
+
+// Leaf module: must not import settings.ts or anything under src/core/version
+// (settings.ts re-exports APP_VERSION from here, so that would be a cycle).
+
+const CODEXA_PACKAGE_NAME = "@golba98/codexa";
+const SEMVER_RE = /^\d+\.\d+\.\d+(-[\w.]+)?$/;
+
+function readPackageVersion(packageJsonPath: string, requireName?: string): string | null {
+  try {
+    const parsed = JSON.parse(readFileSync(packageJsonPath, "utf8")) as {
+      name?: unknown;
+      version?: unknown;
+    };
+    if (requireName !== undefined && parsed.name !== requireName) return null;
+    if (typeof parsed.version !== "string") return null;
+    const version = parsed.version.trim();
+    return SEMVER_RE.test(version) ? version : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Resolves the version of the running Codexa install:
+ * 1. `CODEXA_PACKAGE_ROOT` (set by bin/codexa.js) → that package.json's version
+ * 2. Walk up from this module for a package.json named "@golba98/codexa" (local dev)
+ * 3. The committed buildInfo.ts APP_VERSION as the last resort
+ *
+ * `startDir` overrides the walk-up starting directory (test seam).
+ */
+export function resolveAppVersion(
+  env: NodeJS.ProcessEnv = process.env,
+  startDir?: string,
+): string {
+  const packageRoot = env.CODEXA_PACKAGE_ROOT?.trim();
+  if (packageRoot) {
+    const version = readPackageVersion(join(packageRoot, "package.json"));
+    if (version) return version;
+  }
+
+  let dir = startDir ?? dirname(fileURLToPath(import.meta.url));
+  for (;;) {
+    const version = readPackageVersion(join(dir, "package.json"), CODEXA_PACKAGE_NAME);
+    if (version) return version;
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+
+  return BUILD_INFO_VERSION;
+}
+
+let cachedVersion: string | null = null;
+
+/** Cached form of resolveAppVersion() — the installed version cannot change mid-process. */
+export function getAppVersion(): string {
+  if (cachedVersion === null) {
+    cachedVersion = resolveAppVersion();
+  }
+  return cachedVersion;
+}

package/src/config/buildInfo.ts

@@ -1,3 +1,3 @@
 // Generated by scripts/gen-build-info.mjs — do not edit manually.
-export const BUILD_COMMIT = "aaffb655176a0acb1bc7800ddbb3e6402e5933f4" as const;
-export const APP_VERSION = "1.0.5" as const;
+export const BUILD_COMMIT = "c04f84f315a4b2c4b8bea27d41ac370a27467572" as const;
+export const APP_VERSION = "1.0.7" as const;

package/src/config/runtimeConfig.ts

@@ -130,7 +130,7 @@ export const DEFAULT_RUNTIME_POLICY: RuntimePolicyConfig = {
   serviceTier: "flex",
   personality: "none",
   allowExternalFileImport: true,
-  attachmentDir: ".codexa/attachments",
+  attachmentDir: "attachments",
 };
 
 export const DEFAULT_RUNTIME_CONFIG: RuntimeConfig = {

package/src/config/settings.ts

@@ -9,7 +9,11 @@ function smartJoin(base: string, ...parts: string[]): string {
   return isWindowsStylePath(base) ? win32.join(base, ...parts) : join(base, ...parts);
 }
 
-export { APP_VERSION } from "./buildInfo.js";
+import { getAppVersion } from "./appVersion.js";
+
+// Authoritative runtime version: resolved from the installed package.json at
+// startup (buildInfo.ts is only the committed fallback and can drift).
+export const APP_VERSION: string = getAppVersion();
 export const APP_NAME = "Codexa";
 export const DEFAULT_BACKEND = "codex-subprocess";
 export const DEFAULT_MODEL = "gpt-5.4";