@golba98/codexa 1.0.6 → 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
@@ -605,8 +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.6**
+**Current release: v1.0.7**
 
-v1.0.6 checks npm on every interactive startup and shows an update prompt as soon as Codexa is idle. The prompt offers the correct update command for the package manager that installed Codexa.
+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 v1.0.6 can wait for a cached result before discovering a new npm release. Update directly with `npm install -g @golba98/codexa@latest` if needed.
+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.6",
+  "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,
@@ -3830,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}`);
@@ -4470,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,

package/src/config/buildInfo.ts

@@ -1,3 +1,3 @@
 // Generated by scripts/gen-build-info.mjs — do not edit manually.
-export const BUILD_COMMIT = "8a275f0a19434d0cf59ff59cebe1aae734559bde" as const;
-export const APP_VERSION = "1.0.6" 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/core/debug/modelStateDebug.ts

@@ -1,5 +1,6 @@
 import { appendFileSync, mkdirSync } from "fs";
-import { dirname, join } from "path";
+import { dirname } from "path";
+import { resolveCodexaDebugLogPath } from "../workspace/appData.js";
 
 type ModelStateDebugDetails = Record<string, unknown>;
 
@@ -12,7 +13,7 @@ export function isModelStateDebugEnabled(): boolean {
 export function getModelStateDebugLogPath(): string {
   return process.env.CODEXA_RENDER_DEBUG_FILE?.trim()
     || process.env.CODEXA_DEBUG_MODEL_STATE_LOG?.trim()
-    || join(process.cwd(), ".codexa", "debug", "render-status.log");
+    || resolveCodexaDebugLogPath();
 }
 
 export function traceModelStateDebug(event: string, details: ModelStateDebugDetails = {}): void {

package/src/core/perf/renderDebug.ts

@@ -1,6 +1,7 @@
 import { appendFileSync, mkdirSync } from "fs";
-import { dirname, join } from "path";
-import { useEffect, useRef } from "react";
+import { dirname } from "path";
+import { useEffect, useRef } from "react";
+import { resolveCodexaDebugLogPath } from "../workspace/appData.js";
 
 type DebugEnv = Record<string, string | undefined>;
 
@@ -11,7 +12,7 @@ let renderTraceEnabled = false;
 let lifecycleEnabled = false;
 let flickerEnabled = false;
 let plainActionsEnabled = false;
-let logPath = join(process.cwd(), ".codexa", "debug", "render-status.log");
+let logPath = resolveCodexaDebugLogPath();
 let sessionId = `${Date.now()}-${process.pid}`;
 const counters = new Map<string, number>();
 
@@ -29,7 +30,7 @@ function configureFromEnv(env: DebugEnv = process.env): void {
   lifecycleEnabled = env["CODEXA_DEBUG_LIFECYCLE"] === "1";
   flickerEnabled = env["CODEXA_DEBUG_FLICKER"] === "1";
   plainActionsEnabled = env["CODEXA_DEBUG_PLAIN_ACTIONS"] === "1";
-  logPath = env["CODEXA_RENDER_DEBUG_FILE"]?.trim() || join(process.cwd(), ".codexa", "debug", "render-status.log");
+  logPath = env["CODEXA_RENDER_DEBUG_FILE"]?.trim() || resolveCodexaDebugLogPath(env);
   sessionId = `${Date.now()}-${process.pid}`;
   configured = true;
 }

package/src/core/providerLauncher/launcher.ts

@@ -39,7 +39,7 @@ export function buildProviderLaunchSpec(provider: ProviderConfig, cwd: string):
   if (!provider.enabled) {
     return {
       status: "disabled",
-      message: `${provider.displayName} is disabled. Configure a command in .codexa/providers.json before launching it.`,
+      message: `${provider.displayName} is disabled. Configure a command in Codexa's provider settings before launching it.`,
     };
   }
 

package/src/core/providerLauncher/workspaceConfig.ts

@@ -1,7 +1,8 @@
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "fs";
 import { dirname, join } from "path";
-import { DEFAULT_MODEL } from "../../config/settings.js";
-import { normalizeWorkspaceRoot } from "../workspace/workspaceRoot.js";
+import { DEFAULT_MODEL } from "../../config/settings.js";
+import { resolveCodexaWorkspaceDataDir } from "../workspace/appData.js";
+import { normalizeWorkspaceRoot } from "../workspace/workspaceRoot.js";
 import { isKnownProviderId } from "./registry.js";
 import { getDefaultRouteModel, getProviderRuntime, isProviderRouteConfigured, isProviderRoutableInCodexa } from "../providerRuntime/registry.js";
 import { normalizeGeminiModelId } from "../providerRuntime/models.js";
@@ -17,8 +18,12 @@ const DEPRECATED_ANTIGRAVITY_PROVIDER_ID = "antigravity";
 const DEPRECATED_ANTIGRAVITY_BACKENDS = new Set(["antigravity-cli-auth", "agy"]);
 const DEPRECATED_GOOGLE_PROVIDER_ID = "google";
 
-export function getProviderWorkspaceConfigFile(workspaceRoot: string): string {
-  return join(normalizeWorkspaceRoot(workspaceRoot), ".codexa", "providers.json");
+export function getProviderWorkspaceConfigFile(workspaceRoot: string): string {
+  return join(resolveCodexaWorkspaceDataDir(normalizeWorkspaceRoot(workspaceRoot)), "providers.json");
+}
+
+export function getLegacyProviderWorkspaceConfigFile(workspaceRoot: string): string {
+  return join(normalizeWorkspaceRoot(workspaceRoot), ".codexa", "providers.json");
 }
 
 function isRecord(value: unknown): value is Record<string, unknown> {
@@ -345,15 +350,24 @@ export function serializeProviderWorkspaceConfig(config: ProviderWorkspaceConfig
   };
 }
 
-export function loadProviderWorkspaceConfig(workspaceRoot: string): ProviderWorkspaceConfig {
-  const filePath = getProviderWorkspaceConfigFile(workspaceRoot);
-  if (!existsSync(filePath)) return {};
-  try {
-    return parseProviderWorkspaceConfig(JSON.parse(readFileSync(filePath, "utf-8")));
-  } catch {
-    return {};
-  }
-}
+export function loadProviderWorkspaceConfig(workspaceRoot: string): ProviderWorkspaceConfig {
+  const filePath = getProviderWorkspaceConfigFile(workspaceRoot);
+  if (existsSync(filePath)) {
+    try {
+      return parseProviderWorkspaceConfig(JSON.parse(readFileSync(filePath, "utf-8")));
+    } catch {
+      return {};
+    }
+  }
+
+  const legacyFilePath = getLegacyProviderWorkspaceConfigFile(workspaceRoot);
+  if (!existsSync(legacyFilePath)) return {};
+  try {
+    return parseProviderWorkspaceConfig(JSON.parse(readFileSync(legacyFilePath, "utf-8")));
+  } catch {
+    return {};
+  }
+}
 
 export function saveProviderWorkspaceConfig(workspaceRoot: string, config: ProviderWorkspaceConfig): void {
   const filePath = getProviderWorkspaceConfigFile(workspaceRoot);

package/src/core/shared/attachments.ts

@@ -74,16 +74,16 @@ export async function importExternalFile(
   return destPath;
 }
 
-export function rewritePromptWithImportedPaths(
-  prompt: string,
-  replacements: Array<{ rawPath: string; workspaceRelativePath: string }>,
-): string {
-  let result = prompt;
-  for (const { rawPath, workspaceRelativePath } of replacements) {
-    const needsQuotes = /\s/.test(workspaceRelativePath);
-    const quotedReplacement = needsQuotes
-      ? `"${workspaceRelativePath}"`
-      : workspaceRelativePath;
+export function rewritePromptWithImportedPaths(
+  prompt: string,
+  replacements: Array<{ rawPath: string; replacementPath: string }>,
+): string {
+  let result = prompt;
+  for (const { rawPath, replacementPath } of replacements) {
+    const needsQuotes = /\s/.test(replacementPath);
+    const quotedReplacement = needsQuotes
+      ? `"${replacementPath}"`
+      : replacementPath;
     // Replace quoted forms first so the unquoted pass doesn't double-replace
     result = result.split(`"${rawPath}"`).join(quotedReplacement);
     result = result.split(`'${rawPath}'`).join(quotedReplacement);

package/src/core/terminal/frameLock.ts

@@ -1,5 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
+import { resolveCodexaDebugLogPath } from "../workspace/appData.js";
 import { isTerminalResizing } from "./terminalControl.js";
 
 export interface FrameLockOptions {
@@ -28,7 +29,7 @@ export function wrapStdoutWithFrameLock({
   if (env.CODEXA_RENDER_DEBUG === "1") {
     try {
       const logPath = env.CODEXA_RENDER_DEBUG_FILE?.trim()
-        || path.join(process.cwd(), ".codexa", "debug", "render-status.log");
+        || resolveCodexaDebugLogPath(env);
       const logDir = path.dirname(logPath);
       if (!fs.existsSync(logDir)) {
         fs.mkdirSync(logDir, { recursive: true });

package/src/core/terminal/terminalTitle.ts

@@ -1,7 +1,8 @@
 import { APP_NAME, type TerminalTitleMode, formatTerminalTitlePath } from "../../config/settings.js";
 import { appendFileSync, mkdirSync } from "fs";
-import { dirname, join } from "path";
+import { dirname } from "path";
 import * as renderDebug from "../perf/renderDebug.js";
+import { resolveCodexaDebugLogPath } from "../workspace/appData.js";
 
 export const DEFAULT_TERMINAL_TITLE = APP_NAME;
 
@@ -52,7 +53,7 @@ function findIncompleteOscTitleStart(text: string): number {
 
 const TERMINAL_TITLE_DEBUG_LOG_PATH = process.env["CODEXA_TERMINAL_TITLE_DEBUG_FILE"]?.trim()
   || process.env["CODEXA_RENDER_DEBUG_FILE"]?.trim()
-  || join(process.cwd(), ".codexa", "debug", "render-status.log");
+  || resolveCodexaDebugLogPath();
 
 let terminalTitleLifecycleState = "unknown";
 

package/src/core/workspace/appData.ts

@@ -0,0 +1,45 @@
+import { createHash } from "node:crypto";
+import { homedir } from "node:os";
+import { isAbsolute, join, normalize } from "node:path";
+
+type Platform = "win32" | "darwin" | "linux" | string;
+type Environment = Record<string, string | undefined>;
+
+export function resolveCodexaDataDir(
+  platformOverride?: Platform,
+  env: Environment = process.env,
+  home = homedir(),
+): string {
+  const configuredDir = env["CODEXA_DATA_DIR"]?.trim();
+  if (configuredDir) return configuredDir;
+
+  const platform = platformOverride ?? process.platform;
+  if (platform === "win32") {
+    return join(env["LOCALAPPDATA"]?.trim() || env["APPDATA"]?.trim() || join(home, "AppData", "Local"), "Codexa");
+  }
+  if (platform === "darwin") {
+    return join(home, "Library", "Application Support", "Codexa");
+  }
+
+  return join(env["XDG_DATA_HOME"]?.trim() || join(home, ".local", "share"), "codexa");
+}
+
+export function workspaceStorageKey(workspaceRoot: string): string {
+  return createHash("sha256").update(workspaceRoot).digest("hex").slice(0, 16);
+}
+
+export function resolveCodexaWorkspaceDataDir(workspaceRoot: string): string {
+  return join(resolveCodexaDataDir(), "workspaces", workspaceStorageKey(workspaceRoot));
+}
+
+export function resolveCodexaAttachmentDir(workspaceRoot: string, configuredDir: string): string {
+  if (isAbsolute(configuredDir)) return configuredDir;
+
+  const normalized = configuredDir.trim().replace(/\\/g, "/").replace(/^\.codexa\/?/, "") || "attachments";
+  const safeRelativeDir = normalize(normalized).replace(/^(\.\.([/\\]|$))+/, "") || "attachments";
+  return join(resolveCodexaWorkspaceDataDir(workspaceRoot), safeRelativeDir);
+}
+
+export function resolveCodexaDebugLogPath(env: Environment = process.env): string {
+  return join(resolveCodexaDataDir(undefined, env), "debug", "render-status.log");
+}

package/src/core/workspace/planStorage.ts

@@ -1,9 +1,10 @@
 import { createHash } from "crypto";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
-import { homedir } from "os";
-import { join } from "path";
-import { isNoiseLine } from "../providers/codexTranscript.js";
-import { sanitizeTerminalOutput } from "../terminal/terminalSanitize.js";
+import { homedir } from "os";
+import { join } from "path";
+import { isNoiseLine } from "../providers/codexTranscript.js";
+import { sanitizeTerminalOutput } from "../terminal/terminalSanitize.js";
+import { resolveCodexaDataDir } from "./appData.js";
 
 type Platform = "win32" | "darwin" | "linux" | string;
 
@@ -91,15 +92,8 @@ export function resolvePlanDir(platformOverride?: Platform): string {
     return join(homedir(), "AppData", "Local", "Codexa", "plans");
   }
 
-  if (platform === "darwin") {
-    return join(homedir(), "Library", "Application Support", "Codexa", "plans");
-  }
-
-  // Linux and other Unix-like
-  const xdgDataHome = process.env["XDG_DATA_HOME"];
-  if (xdgDataHome) return join(xdgDataHome, "codexa", "plans");
-  return join(homedir(), ".local", "share", "codexa", "plans");
-}
+  return join(resolveCodexaDataDir(platform), "plans");
+}
 
 // SHA-256 of the workspace path ensures filename uniqueness across projects with the same name.
 function workspaceHash(workspaceRoot: string): string {

package/src/ui/panels/AttachmentImportPanel.tsx

@@ -43,7 +43,8 @@ export function AttachmentImportPanel({
     }
   }, { isActive: isFocused });
 
-  const relativeAttachmentsDir = path.relative(workspaceRoot, attachmentsDir).replace(/\\/g, "/");
+  const relativeAttachmentsDir = path.relative(workspaceRoot, attachmentsDir).replace(/\\/g, "/");
+  const displayedAttachmentsDir = relativeAttachmentsDir.startsWith("..") ? attachmentsDir : relativeAttachmentsDir;
   const hasImages = files.some((f) => f.isImage);
   const showVisionWarning = hasImages && modelSupportsVision === false;
   const fileLabel = files.length === 1 ? "file" : "files";
@@ -59,7 +60,7 @@ export function AttachmentImportPanel({
       >
         <Text color={theme.accent} bold>IMPORT FILE  </Text>
         <Text color={theme.textMuted}>
-          Copy {files.length} outside-workspace {fileLabel} into .codexa/attachments?
+          Copy {files.length} outside-workspace {fileLabel} into {displayedAttachmentsDir}?
         </Text>
       </Box>
 
@@ -76,7 +77,7 @@ export function AttachmentImportPanel({
           <Box key={i} flexDirection="column" marginBottom={i < files.length - 1 ? 1 : 0}>
             <Text color={theme.text}>{path.basename(file.srcPath)}</Text>
             <Text color={theme.textDim}>
-              {"→ "}{relativeAttachmentsDir}/{file.destFilename}
+              {"→ "}{displayedAttachmentsDir}/{file.destFilename}
             </Text>
           </Box>
         ))}