@gramatr/client 0.6.0 → 0.6.2

package/bin/add-api-key.ts

@@ -8,9 +8,9 @@
  *   3. Env-sourced:           gramatr add-api-key --from-env GRAMATR_API_KEY
  *
  * The key is validated against the gramatr server before being written
- * to ~/.gmtr.json. Use --force to skip server validation when offline.
+ * to ~/.gramatr.json. Use --force to skip server validation when offline.
  *
- * This command is the ONLY way to put an API key into ~/.gmtr.json.
+ * This command is the ONLY way to put an API key into ~/.gramatr.json.
  * Installers never prompt for API keys — see packages/client/core/auth.ts.
  */
 
@@ -20,7 +20,7 @@ import { join } from "path";
 import { createInterface } from "readline";
 
 function gmtrJsonPath(): string {
-  return join(process.env.HOME || process.env.USERPROFILE || homedir(), ".gmtr.json");
+  return join(process.env.HOME || process.env.USERPROFILE || homedir(), ".gramatr.json");
 }
 const SERVER_BASE = (process.env.GRAMATR_URL || "https://api.gramatr.com").replace(/\/mcp\/?$/, "");
 
@@ -59,7 +59,7 @@ function parseArgs(argv: string[]): {
 }
 
 function showHelp(): void {
-  log(`gramatr add-api-key — Add a gramatr API key to ~/.gmtr.json
+  log(`gramatr add-api-key — Add a gramatr API key to ~/.gramatr.json
 
 Usage:
   gramatr add-api-key                      Interactive prompt for the key

package/bin/clean-legacy-install.ts

@@ -15,7 +15,7 @@ function main(): void {
 
   const apply = process.argv.includes('--apply');
   const includeOptionalUx = process.env.GRAMATR_ENABLE_OPTIONAL_CLAUDE_UX === '1';
-  const clientDir = process.env.GRAMATR_DIR || join(home, 'gmtr-client');
+  const clientDir = process.env.GRAMATR_DIR || join(home, '.gramatr');
   runLegacyMigration({
     homeDir: home,
     clientDir,

package/bin/clear-creds.ts

@@ -2,13 +2,13 @@
 /**
  * gramatr clear-creds — Nuke ALL stored gramatr credentials.
  *
- * Stronger than `gramatr logout` (which only removes ~/.gmtr.json).
+ * Stronger than `gramatr logout` (which only removes ~/.gramatr.json).
  * This sweeps every credential location in the resolveAuthToken chain
  * (core/auth.ts), so the next install/login is forced through OAuth.
  *
  * Locations cleared:
- *   1. ~/.gmtr.json                              — deleted entirely
- *   2. ~/gmtr-client/settings.json `auth.api_key` — stripped, file preserved
+ *   1. ~/.gramatr.json                              — deleted entirely
+ *   2. ~/.gramatr/settings.json `auth.api_key` — stripped, file preserved
  *
  * Env vars (GRAMATR_API_KEY, GRAMATR_TOKEN) cannot be cleared from a child
  * process — they live in the parent shell. We detect them and warn.
@@ -24,11 +24,11 @@ function getHome(): string {
 }
 
 function gmtrJsonPath(): string {
-  return join(getHome(), ".gmtr.json");
+  return join(getHome(), ".gramatr.json");
 }
 
 function legacySettingsPath(): string {
-  const gmtrDir = process.env.GRAMATR_DIR || join(getHome(), "gmtr-client");
+  const gmtrDir = process.env.GRAMATR_DIR || join(getHome(), ".gramatr");
   return join(gmtrDir, "settings.json");
 }
 
@@ -40,7 +40,7 @@ function showHelp(): void {
   log(`gramatr clear-creds — Remove every stored gramatr credential
 
 Usage:
-  gramatr clear-creds   Sweep ~/.gmtr.json + auth.api_key from gmtr-client/settings.json
+  gramatr clear-creds   Sweep ~/.gramatr.json + auth.api_key from gmtr-client/settings.json
 
 After running, the next install or login will be forced through OAuth.
 
@@ -61,14 +61,14 @@ export function clearAll(): ClearResult {
     envVarsSet: [],
   };
 
-  // 1. ~/.gmtr.json — delete entirely
+  // 1. ~/.gramatr.json — delete entirely
   const gj = gmtrJsonPath();
   if (existsSync(gj)) {
     unlinkSync(gj);
     result.removedGmtrJson = true;
   }
 
-  // 2. ~/gmtr-client/settings.json — strip auth.api_key, preserve rest
+  // 2. ~/.gramatr/settings.json — strip auth.api_key, preserve rest
   const ls = legacySettingsPath();
   if (existsSync(ls)) {
     try {

package/bin/gmtr-login.ts

@@ -3,7 +3,7 @@
  * gmtr-login — Authenticate with the gramatr server
  *
  * Opens the grāmatr dashboard login flow, captures a Firebase ID token
- * on localhost, and stores it in ~/.gmtr.json.
+ * on localhost, and stores it in ~/.gramatr.json.
  *
  * Usage:
  *   bun gmtr-login.ts                    # Interactive browser login via Firebase dashboard
@@ -11,7 +11,7 @@
  *   bun gmtr-login.ts --status           # Check current auth status
  *   bun gmtr-login.ts --logout           # Remove stored credentials
  *
- * Token is stored in ~/.gmtr.json under the "token" key.
+ * Token is stored in ~/.gramatr.json under the "token" key.
  * The GMTRPromptEnricher hook reads this on every prompt.
  */
 
@@ -23,7 +23,7 @@ import { createServer, type IncomingMessage, type ServerResponse } from 'http';
 // ── Config ──
 
 const HOME = process.env.HOME || process.env.USERPROFILE || '';
-const CONFIG_PATH = join(HOME, '.gmtr.json');
+const CONFIG_PATH = join(HOME, '.gramatr.json');
 const DEFAULT_SERVER = process.env.GRAMATR_URL || 'https://api.gramatr.com/mcp';
 // Strip /mcp suffix to get base URL
 const SERVER_BASE = DEFAULT_SERVER.replace(/\/mcp\/?$/, '');
@@ -317,7 +317,7 @@ async function logout(): Promise<void> {
   delete config.token_expires;
   delete config.authenticated_at;
   writeConfig(config);
-  console.log('\n  ✓ Logged out. Token removed from ~/.gmtr.json\n');
+  console.log('\n  ✓ Logged out. Token removed from ~/.gramatr.json\n');
 }
 
 async function loginWithToken(token: string): Promise<void> {
@@ -330,7 +330,7 @@ async function loginWithToken(token: string): Promise<void> {
     config.token_type = token.startsWith('aios_sk_') || token.startsWith('gramatr_sk_') ? 'api_key' : 'oauth';
     config.authenticated_at = new Date().toISOString();
     writeConfig(config);
-    console.log('  ✓ Token valid. Saved to ~/.gmtr.json');
+    console.log('  ✓ Token valid. Saved to ~/.gramatr.json');
     console.log('  gramatr intelligence is now active.\n');
   } else {
     console.log(`  ✗ Token rejected: ${result.error}`);
@@ -396,7 +396,7 @@ async function loginBrowser(): Promise<void> {
 
       console.log('');
       console.log('  ✓ Authenticated successfully');
-      console.log('  Token saved to ~/.gmtr.json');
+      console.log('  Token saved to ~/.gramatr.json');
       console.log('  gramatr intelligence is now active.\n');
       return;
     } catch (e: any) {
@@ -503,7 +503,7 @@ async function loginBrowser(): Promise<void> {
 
     console.log('');
     console.log('  ✓ Authenticated successfully');
-    console.log('  Token saved to ~/.gmtr.json');
+    console.log('  Token saved to ~/.gramatr.json');
     console.log('  gramatr intelligence is now active.\n');
   } catch (e: any) {
     console.log(`\n  ✗ Authentication failed: ${e.message}\n`);
@@ -570,7 +570,7 @@ export async function main(): Promise<void> {
     gmtr-login --logout     Remove stored credentials
     gmtr-login --help       Show this help
 
-  Token storage: ~/.gmtr.json
+  Token storage: ~/.gramatr.json
   Server: ${SERVER_BASE}
   Dashboard: ${DASHBOARD_BASE}
 `);

package/bin/gramatr.ts

@@ -205,7 +205,7 @@ function installTarget(targetId: IntegrationTargetId): void {
 
 function migrate(apply: boolean, deep: boolean = false): void {
   const homeDir = homedir();
-  const clientDir = process.env.GRAMATR_DIR || join(homeDir, 'gmtr-client');
+  const clientDir = process.env.GRAMATR_DIR || join(homeDir, '.gramatr');
   runLegacyMigration({
     homeDir,
     clientDir,
@@ -220,7 +220,7 @@ function migrate(apply: boolean, deep: boolean = false): void {
 }
 
 function doctor(): void {
-  const gmtrDir = process.env.GRAMATR_DIR || join(homedir(), 'gmtr-client');
+  const gmtrDir = process.env.GRAMATR_DIR || join(homedir(), '.gramatr');
   const stale = findStaleArtifacts(homedir(), gmtrDir, existsSync);
   for (const line of formatDoctorLines(detectTargets(), gmtrDir, existsSync(gmtrDir), stale)) log(line);
   renderRemoteGuidance();
@@ -228,7 +228,7 @@ function doctor(): void {
 
 function upgrade(): void {
   const homeDir = homedir();
-  const clientDir = process.env.GRAMATR_DIR || join(homeDir, 'gmtr-client');
+  const clientDir = process.env.GRAMATR_DIR || join(homeDir, '.gramatr');
   const stale = findStaleArtifacts(homeDir, clientDir, existsSync);
   if (stale.length > 0) {
     log('Cleaning stale legacy artifacts before upgrade...');
@@ -344,7 +344,7 @@ function main(): void {
       log('  install [target]   Install gramatr (claude-code, codex, gemini-cli, all)');
       log('  login              Authenticate with the gramatr server (OAuth)');
       log('  add-api-key        Add an API key explicitly (interactive / piped / --from-env)');
-      log('  logout             Clear session token (~/.gmtr.json)');
+      log('  logout             Clear session token (~/.gramatr.json)');
       log('  clear-creds        Nuke ALL stored credentials, force OAuth on next login');
       log('  detect             Show detected CLI platforms');
       log('  doctor             Check installation health');

package/bin/install.ts

@@ -20,6 +20,11 @@ import { createInterface } from 'readline';
 import { buildClaudeHooksFile } from '../core/install.ts';
 import { VERSION } from '../core/version.ts';
 import { resolveAuthToken } from '../core/auth.ts';
+import {
+  sanitizeLegacyEnvBlock,
+  detectShellRcLegacyEnv,
+  formatShellRcLegacyWarning,
+} from '../core/migration.ts';
 
 // ── Constants ──
 
@@ -27,8 +32,8 @@ const HOME = process.env.HOME || process.env.USERPROFILE || '';
 const CLAUDE_DIR = join(HOME, '.claude');
 const CLAUDE_SETTINGS = join(CLAUDE_DIR, 'settings.json');
 const CLAUDE_JSON = join(HOME, '.claude.json');
-const CLIENT_DIR = join(HOME, 'gmtr-client');
-const GMTR_JSON = join(HOME, '.gmtr.json');
+const CLIENT_DIR = join(HOME, '.gramatr');
+const GMTR_JSON = join(HOME, '.gramatr.json');
 const SCRIPT_DIR = dirname(dirname(resolve(import.meta.filename || __filename)));
 const DEFAULT_URL = 'https://api.gramatr.com/mcp';
 
@@ -398,13 +403,13 @@ async function handleAuth(legacyToken: string): Promise<{ url: string; token: st
   const url = await prompt('gramatr server URL', DEFAULT_URL) || DEFAULT_URL;
 
   // Legacy aios token migration: if we cherry-picked a token from a prior
-  // aios install and there is no current ~/.gmtr.json token, seed it so the
+  // aios install and there is no current ~/.gramatr.json token, seed it so the
   // shared resolver picks it up.
   if (legacyToken && !existsSync(GMTR_JSON)) {
     try {
       writeFileSync(GMTR_JSON, `${JSON.stringify({ token: legacyToken }, null, 2)}\n`, 'utf8');
       try { chmodSync(GMTR_JSON, 0o600); } catch { /* ok */ }
-      log('OK Seeded ~/.gmtr.json from legacy aios installation token');
+      log('OK Seeded ~/.gramatr.json from legacy aios installation token');
     } catch { /* ignore */ }
   }
 
@@ -513,11 +518,11 @@ function updateClaudeSettings(url: string, token: string): void {
 
   const settings = readJson(CLAUDE_SETTINGS);
 
-  // Env vars
-  settings.env = settings.env || {};
+  // Env vars — sanitize legacy GMTR_* keys before writing (v0.6.2+ fix)
+  settings.env = sanitizeLegacyEnvBlock(settings.env);
   settings.env.GRAMATR_DIR = CLIENT_DIR;
   settings.env.GRAMATR_URL = url;
-  settings.env.PATH = `${HOME}/.gmtr/bin:/usr/local/bin:/usr/bin:/bin`;
+  settings.env.PATH = `${HOME}/.gramatr/bin:/usr/local/bin:/usr/bin:/bin`;
   if (token) settings.env.AIOS_MCP_TOKEN = token;
 
   // Identity defaults (don't overwrite)
@@ -564,7 +569,7 @@ function registerMcpServer(url: string, token: string): void {
   const backup = `${CLAUDE_JSON}.backup-${timestamp()}`;
   cpSync(CLAUDE_JSON, backup);
 
-  // Store token in ~/.gmtr.json
+  // Store token in ~/.gramatr.json
   if (token) {
     mergeJson(GMTR_JSON, (data) => ({
       ...data,
@@ -572,10 +577,10 @@ function registerMcpServer(url: string, token: string): void {
       token_updated_at: new Date().toISOString(),
     }));
     try { chmodSync(GMTR_JSON, 0o600); } catch { /* ok */ }
-    log('OK Token stored in ~/.gmtr.json (canonical source)');
+    log('OK Token stored in ~/.gramatr.json (canonical source)');
   }
 
-  // Write tool paths to ~/.gmtr.json
+  // Write tool paths to ~/.gramatr.json
   mergeJson(GMTR_JSON, (data) => ({
     ...data,
     jq_binary: which('jq') || '',
@@ -584,7 +589,8 @@ function registerMcpServer(url: string, token: string): void {
 
   // Register in ~/.claude.json
   mergeJson(CLAUDE_JSON, (data) => {
-    data.env = data.env || {};
+    // Sanitize legacy GMTR_* keys before writing (v0.6.2+ fix)
+    data.env = sanitizeLegacyEnvBlock(data.env);
     if (token) data.env.GRAMATR_TOKEN = token;
     delete data.env.AIOS_MCP_TOKEN;
 
@@ -734,9 +740,13 @@ async function main(): Promise<void> {
     if (!token) {
       log('    2. Run /gmtr-login in Claude Code to authenticate');
     } else {
-      log('    2. Already authenticated (token found in ~/.gmtr.json)');
+      log('    2. Already authenticated (token found in ~/.gramatr.json)');
     }
     log('');
+
+    // v0.6.2+: detect legacy GMTR_* exports in user shell rc files and warn
+    const rcHits = detectShellRcLegacyEnv(HOME);
+    if (rcHits.length > 0) log(formatShellRcLegacyWarning(rcHits));
   } else {
     log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
     log('  Install completed with warnings');

package/bin/lib/config.ts

@@ -2,14 +2,14 @@
  * gramatr client config resolver (statusline refactor, #495).
  *
  * Single-purpose helper that returns the server URL + auth token with
- * NO reads of ~/.claude* or ~/gmtr-client/settings.json. This is the
+ * NO reads of ~/.claude* or ~/.gramatr/settings.json. This is the
  * statusline-specific config path; the richer installer auth lives in
  * core/auth.ts for a reason — this file must stay small and side-effect-free
  * so it can be loaded in a 2s shim without touching disk more than once.
  *
  * Resolution:
- *   URL   — GRAMATR_URL → ~/.gmtr.json.url → https://api.gramatr.com
- *   Token — GRAMATR_TOKEN → AIOS_MCP_TOKEN → ~/.gmtr.json.token → null
+ *   URL   — GRAMATR_URL → ~/.gramatr.json.url → https://api.gramatr.com
+ *   Token — GRAMATR_API_KEY → ~/.gramatr.json.token → null
  */
 import { existsSync, readFileSync } from 'fs';
 import { homedir } from 'os';
@@ -27,7 +27,7 @@ function getHome(): string {
 }
 
 function readGmtrJson(): Record<string, any> | null {
-  const path = join(getHome(), '.gmtr.json');
+  const path = join(getHome(), '.gramatr.json');
   if (!existsSync(path)) return null;
   try {
     return JSON.parse(readFileSync(path, 'utf8'));

package/bin/logout.ts

@@ -2,8 +2,8 @@
 /**
  * gramatr logout — Clear stored gramatr credentials (issue #484).
  *
- * Removes ~/.gmtr.json. With --keep-backup, renames it to
- * ~/.gmtr.json.bak.<timestamp> instead of deleting.
+ * Removes ~/.gramatr.json. With --keep-backup, renames it to
+ * ~/.gramatr.json.bak.<timestamp> instead of deleting.
  *
  * Not-logged-in is not an error: exits 0 with a clean message.
  */
@@ -13,7 +13,7 @@ import { homedir } from "os";
 import { join } from "path";
 
 function gmtrJsonPath(): string {
-  return join(process.env.HOME || process.env.USERPROFILE || homedir(), ".gmtr.json");
+  return join(process.env.HOME || process.env.USERPROFILE || homedir(), ".gramatr.json");
 }
 
 function log(msg: string = ""): void {
@@ -34,8 +34,8 @@ function showHelp(): void {
   log(`gramatr logout — Clear stored gramatr credentials
 
 Usage:
-  gramatr logout                Delete ~/.gmtr.json
-  gramatr logout --keep-backup  Rename to ~/.gmtr.json.bak.<timestamp> instead`);
+  gramatr logout                Delete ~/.gramatr.json
+  gramatr logout --keep-backup  Rename to ~/.gramatr.json.bak.<timestamp> instead`);
 }
 
 export function main(argv: string[] = process.argv.slice(2)): number {

package/bin/uninstall.ts

@@ -5,7 +5,7 @@
  * Usage:
  *   bun uninstall.ts              # Interactive — confirms each step
  *   bun uninstall.ts --yes        # Non-interactive — uninstall everything
- *   bun uninstall.ts --keep-auth  # Keep ~/.gmtr.json (preserve login)
+ *   bun uninstall.ts --keep-auth  # Keep ~/.gramatr.json (preserve login)
  *   npx tsx uninstall.ts          # Without bun
  */
 
@@ -97,8 +97,8 @@ async function main(): Promise<void> {
   log('  ===================');
   log('');
 
-  const gmtrClient = join(HOME, 'gmtr-client');
-  const gmtrJson = join(HOME, '.gmtr.json');
+  const gmtrClient = join(HOME, '.gramatr');
+  const gmtrJson = join(HOME, '.gramatr.json');
   const gmtrDotDir = join(HOME, '.gmtr');
   const claudeSettings = join(HOME, '.claude', 'settings.json');
   const claudeJson = join(HOME, '.claude.json');
@@ -111,9 +111,9 @@ async function main(): Promise<void> {
 
   // Detect what's installed
   const installed: string[] = [];
-  if (existsSync(gmtrClient)) installed.push(`~/gmtr-client (${dirSize(gmtrClient)})`);
+  if (existsSync(gmtrClient)) installed.push(`~/.gramatr (${dirSize(gmtrClient)})`);
   if (existsSync(gmtrDotDir)) installed.push(`~/.gmtr/ (${dirSize(gmtrDotDir)})`);
-  if (existsSync(gmtrJson)) installed.push('~/.gmtr.json');
+  if (existsSync(gmtrJson)) installed.push('~/.gramatr.json');
   if (existsSync(claudeSettings)) installed.push('~/.claude/settings.json (hooks)');
   if (existsSync(claudeJson)) installed.push('~/.claude.json (MCP server)');
   if (existsSync(codexHooks)) installed.push('~/.codex/hooks.json');
@@ -136,10 +136,10 @@ async function main(): Promise<void> {
 
   log('');
 
-  // 1. Remove ~/gmtr-client (hooks, bin, skills, agents, tools)
+  // 1. Remove ~/.gramatr (hooks, bin, skills, agents, tools)
   if (existsSync(gmtrClient)) {
     rmSync(gmtrClient, { recursive: true, force: true });
-    log('  OK Removed ~/gmtr-client');
+    log('  OK Removed ~/.gramatr');
   }
 
   // 2. Remove ~/.gmtr/ (bun binary, PATH additions)
@@ -148,13 +148,13 @@ async function main(): Promise<void> {
     log('  OK Removed ~/.gmtr/');
   }
 
-  // 3. Remove ~/.gmtr.json (auth token) — unless --keep-auth
+  // 3. Remove ~/.gramatr.json (auth token) — unless --keep-auth
   if (existsSync(gmtrJson)) {
     if (KEEP_AUTH) {
-      log('  -- Kept ~/.gmtr.json (--keep-auth)');
+      log('  -- Kept ~/.gramatr.json (--keep-auth)');
     } else {
       rmSync(gmtrJson);
-      log('  OK Removed ~/.gmtr.json');
+      log('  OK Removed ~/.gramatr.json');
     }
   }
 
@@ -174,14 +174,14 @@ async function main(): Promise<void> {
           for (const [event, hooks] of Object.entries(settings.hooks)) {
             if (Array.isArray(hooks)) {
               settings.hooks[event] = (hooks as any[]).filter(
-                (h: any) => !h.command?.includes('gmtr-client') && !h.command?.includes('gramatr')
+                (h: any) => !h.command?.includes('.gramatr') && !h.command?.includes('gramatr')
               );
               if (settings.hooks[event].length === 0) delete settings.hooks[event];
             }
           }
           if (Object.keys(settings.hooks).length === 0) delete settings.hooks;
         }
-        if (settings.statusLine?.command?.includes('gmtr-client')) {
+        if (settings.statusLine?.command?.includes('.gramatr')) {
           delete settings.statusLine;
         }
         writeFileSync(claudeSettings, JSON.stringify(settings, null, 2) + '\n');
@@ -242,7 +242,7 @@ async function main(): Promise<void> {
         for (const [event, eventHooks] of Object.entries(hooks.hooks)) {
           if (Array.isArray(eventHooks)) {
             hooks.hooks[event] = (eventHooks as any[]).filter(
-              (h: any) => !h.command?.includes('gmtr-client') && !h.command?.includes('gramatr')
+              (h: any) => !h.command?.includes('.gramatr') && !h.command?.includes('gramatr')
             );
             if (hooks.hooks[event].length === 0) delete hooks.hooks[event];
           }
@@ -278,7 +278,7 @@ async function main(): Promise<void> {
   log('  Uninstall complete.');
   log('  Restart Claude Code / Codex / Gemini CLI to apply changes.');
   if (KEEP_AUTH) {
-    log('  Auth token preserved in ~/.gmtr.json (use --token with next install).');
+    log('  Auth token preserved in ~/.gramatr.json (use --token with next install).');
   }
   log('');
 }

package/codex/install.ts

@@ -9,6 +9,10 @@ import {
   mergeHooksFile,
   upsertManagedBlock,
 } from './lib/codex-install-utils.ts';
+import {
+  detectShellRcLegacyEnv,
+  formatShellRcLegacyWarning,
+} from '../core/migration.ts';
 
 const START_MARKER = '<!-- GMTR-CODEX-START -->';
 const END_MARKER = '<!-- GMTR-CODEX-END -->';
@@ -47,7 +51,7 @@ export function main(): void {
     throw new Error('HOME is not set');
   }
 
-  const gmtrDir = process.env.GRAMATR_DIR || join(home, 'gmtr-client');
+  const gmtrDir = process.env.GRAMATR_DIR || join(home, '.gramatr');
   const codexHome = join(home, '.codex');
   const hooksPath = join(codexHome, 'hooks.json');
   const configPath = join(codexHome, 'config.toml');
@@ -107,6 +111,10 @@ export function main(): void {
   log('');
   log('Codex installer complete.');
   log('Restart Codex or start a new session to load the updated hook configuration.');
+
+  // v0.6.2+: detect legacy GMTR_* exports in shell rc and warn
+  const rcHits = detectShellRcLegacyEnv(home);
+  if (rcHits.length > 0) log(formatShellRcLegacyWarning(rcHits));
 }
 
 // Run directly when executed as a script

package/core/auth.ts

@@ -8,8 +8,8 @@
  * Resolution chain (first non-empty wins):
  *   1. GRAMATR_API_KEY env var
  *   2. GRAMATR_TOKEN env var (legacy)
- *   3. ~/.gmtr.json `token` field
- *   4. ~/gmtr-client/settings.json `auth.api_key` (legacy, skips placeholder)
+ *   3. ~/.gramatr.json `token` field
+ *   4. ~/.gramatr/settings.json `auth.api_key` (legacy, skips placeholder)
  *   5. If interactive + TTY: spawn gmtr-login.ts (OAuth)
  *   6. Otherwise: throw clean actionable error
  *
@@ -44,11 +44,11 @@ function getHome(): string {
 }
 
 function gmtrJsonPath(): string {
-  return join(getHome(), ".gmtr.json");
+  return join(getHome(), ".gramatr.json");
 }
 
 function legacySettingsPath(): string {
-  const gmtrDir = process.env.GRAMATR_DIR || join(getHome(), "gmtr-client");
+  const gmtrDir = process.env.GRAMATR_DIR || join(getHome(), ".gramatr");
   return join(gmtrDir, "settings.json");
 }
 
@@ -90,7 +90,7 @@ function findGmtrLoginScript(): string | null {
   }
   // Fallback to installed client dir
   const installedCandidate = join(
-    process.env.GRAMATR_DIR || join(getHome(), "gmtr-client"),
+    process.env.GRAMATR_DIR || join(getHome(), ".gramatr"),
     "bin",
     "gmtr-login.ts",
   );
@@ -144,7 +144,7 @@ export async function resolveAuthToken(opts: ResolveAuthTokenOptions): Promise<s
   const envToken = tokenFromEnv();
   if (envToken) return envToken;
 
-  // 3: ~/.gmtr.json
+  // 3: ~/.gramatr.json
   const stored = tokenFromGmtrJson();
   if (stored) return stored;
 

package/core/migration.ts

@@ -308,6 +308,33 @@ function stripLegacyEntriesFromHookEvent(value: unknown): unknown {
     .filter(Boolean);
 }
 
+/**
+ * Env-var key prefixes that were used by earlier gramatr versions and are
+ * now either renamed or removed. Any key matching one of these prefixes that
+ * survives in a user's config file across an upgrade is a legacy leak and
+ * must be scrubbed before we write the new env block.
+ *
+ * Issue: v0.6.0 renamed GMTR_* → GRAMATR_* but the installer's env merge
+ * only SET new keys without removing old ones. Users upgrading from v0.5.x
+ * kept the stale GMTR_DIR, GMTR_URL, GMTR_TOKEN in their config files
+ * forever. v0.6.2 fixes this by sanitizing on every install.
+ */
+export const LEGACY_ENV_KEY_PREFIXES: ReadonlyArray<string> = ['GMTR_'];
+
+/**
+ * Strip any env-var key matching a legacy prefix. Returns a new object;
+ * input is not mutated. Safe on null/undefined (returns {}).
+ */
+export function sanitizeLegacyEnvBlock(env: unknown): JsonObject {
+  if (!isRecord(env)) return {};
+  const next: JsonObject = {};
+  for (const [key, value] of Object.entries(env)) {
+    if (LEGACY_ENV_KEY_PREFIXES.some((prefix) => key.startsWith(prefix))) continue;
+    next[key] = value;
+  }
+  return next;
+}
+
 export function sanitizeClaudeSettings(
   settings: JsonObject,
   clientDir: string,
@@ -326,14 +353,103 @@ export function sanitizeClaudeSettings(
   }
 
   next.hooks = hooks;
+  // Sanitize legacy env keys (v0.6.2+)
+  next.env = sanitizeLegacyEnvBlock(next.env);
   return next;
 }
 
 export function sanitizeClaudeJson(claudeJson: JsonObject): JsonObject {
-  if (!isRecord(claudeJson.mcpServers)) return claudeJson;
-  const mcpServers = { ...claudeJson.mcpServers };
-  delete mcpServers.aios;
-  return { ...claudeJson, mcpServers };
+  const next = { ...claudeJson };
+  if (isRecord(claudeJson.mcpServers)) {
+    const mcpServers = { ...claudeJson.mcpServers };
+    delete mcpServers.aios;
+    next.mcpServers = mcpServers;
+  }
+  // Sanitize legacy env keys (v0.6.2+)
+  next.env = sanitizeLegacyEnvBlock(claudeJson.env);
+  return next;
+}
+
+// ── Shell rc legacy env detection (v0.6.2+) ──────────────────────────────
+//
+// Users who added `export GMTR_TOKEN=...` lines to their shell rc files
+// before v0.6.0 will keep those vars live across every new shell until they
+// manually edit the files. Our installer cannot mutate user dotfiles
+// without permission, but it CAN detect and warn.
+
+export interface ShellRcLegacyHit {
+  file: string;
+  lineNumber: number;
+  line: string;
+  variableName: string;
+}
+
+const SHELL_RC_CANDIDATES: ReadonlyArray<string> = [
+  '.bashrc',
+  '.bash_profile',
+  '.zshrc',
+  '.zprofile',
+  '.profile',
+];
+
+const LEGACY_EXPORT_RE = /^\s*export\s+(GMTR_[A-Z_]+)=/;
+
+/**
+ * Scan shell rc files for `export GMTR_*=...` lines. Returns a list of hits,
+ * each with file path, line number, raw line, and the variable name. Never
+ * mutates any file — read-only detection.
+ */
+export function detectShellRcLegacyEnv(homeDir: string): ShellRcLegacyHit[] {
+  const out: ShellRcLegacyHit[] = [];
+  for (const basename of SHELL_RC_CANDIDATES) {
+    const path = `${homeDir}/${basename}`;
+    if (!existsSync(path)) continue;
+    let content: string;
+    try {
+      content = readFileSync(path, 'utf8');
+    } catch {
+      continue;
+    }
+    const lines = content.split(/\r?\n/);
+    for (let i = 0; i < lines.length; i++) {
+      const match = lines[i].match(LEGACY_EXPORT_RE);
+      if (match) {
+        out.push({
+          file: path,
+          lineNumber: i + 1,
+          line: lines[i],
+          variableName: match[1],
+        });
+      }
+    }
+  }
+  return out;
+}
+
+/**
+ * Format shell-rc legacy hits as a human-readable block of warning text.
+ * Returns an empty string if there are no hits. Writes no files.
+ */
+export function formatShellRcLegacyWarning(hits: ShellRcLegacyHit[]): string {
+  if (hits.length === 0) return '';
+  const lines: string[] = [];
+  lines.push('');
+  lines.push('⚠  Legacy GMTR_* exports detected in your shell rc files:');
+  lines.push('');
+  for (const hit of hits) {
+    lines.push(`   ${hit.file}:${hit.lineNumber}`);
+    lines.push(`     ${hit.line.trim()}`);
+  }
+  const uniqueVars = Array.from(new Set(hits.map((h) => h.variableName)));
+  lines.push('');
+  lines.push('   These vars are no longer read by gramatr (since v0.6.0) but');
+  lines.push('   remain in your shell environment on every login. To clean up:');
+  lines.push('');
+  lines.push('     1. Edit the files above and delete the matching export lines');
+  lines.push(`     2. Run in each open terminal: unset ${uniqueVars.join(' ')}`);
+  lines.push('     3. Or just start a fresh shell session');
+  lines.push('');
+  return lines.join('\n');
 }
 
 export function findStaleArtifacts(

package/core/version.ts

@@ -8,8 +8,8 @@
  * Works in two environments:
  *   1. Source checkout: packages/client/core/version.ts →
  *      packages/client/package.json (found one directory up).
- *   2. Installed client: ~/gmtr-client/core/version.ts →
- *      ~/gmtr-client/package.json (copied by installClientFiles()).
+ *   2. Installed client: ~/.gramatr/core/version.ts →
+ *      ~/.gramatr/package.json (copied by installClientFiles()).
  *
  * If the file cannot be resolved (unexpected layout), falls back to '0.0.0'
  * rather than throwing — the version check is opportunistic and must never

package/gemini/install.ts

@@ -17,6 +17,10 @@ import {
   getGramatrExtensionDir,
   readStoredApiKey,
 } from './lib/gemini-install-utils.ts';
+import {
+  detectShellRcLegacyEnv,
+  formatShellRcLegacyWarning,
+} from '../core/migration.ts';
 
 function log(message: string): void {
   process.stdout.write(`${message}\n`);
@@ -104,10 +108,10 @@ async function testApiKey(key: string): Promise<boolean> {
 }
 
 async function resolveApiKey(home: string): Promise<string | null> {
-  // 1. Check if already stored in ~/.gmtr.json (shared with other platforms)
+  // 1. Check if already stored in ~/.gramatr.json (shared with other platforms)
   const stored = readStoredApiKey(home);
   if (stored) {
-    log(`  Found existing token in ~/.gmtr.json`);
+    log(`  Found existing token in ~/.gramatr.json`);
     log('  Testing token...');
     const valid = await testApiKey(stored);
     if (valid) {
@@ -142,8 +146,8 @@ async function resolveApiKey(home: string): Promise<string | null> {
     const valid = await testApiKey(prompted);
     if (valid) {
       log('  OK Token is valid');
-      // Save to ~/.gmtr.json for cross-platform reuse
-      const configPath = join(home, '.gmtr.json');
+      // Save to ~/.gramatr.json for cross-platform reuse
+      const configPath = join(home, '.gramatr.json');
       let config: Record<string, unknown> = {};
       if (existsSync(configPath)) {
         try {
@@ -159,7 +163,7 @@ async function resolveApiKey(home: string): Promise<string | null> {
           : 'oauth';
       config.authenticated_at = new Date().toISOString();
       writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n');
-      log('  OK Saved to ~/.gmtr.json');
+      log('  OK Saved to ~/.gramatr.json');
       return prompted;
     }
     log('  Token rejected by server.');
@@ -244,9 +248,9 @@ export async function main(): Promise<void> {
   );
   log('  OK Wrote hooks/hooks.json');
 
-  // ── Store token in ~/.gmtr.json (canonical source, not in extension dir) ──
+  // ── Store token in ~/.gramatr.json (canonical source, not in extension dir) ──
   if (apiKey) {
-    const gmtrJsonPath = join(home, '.gmtr.json');
+    const gmtrJsonPath = join(home, '.gramatr.json');
     let gmtrConfig: Record<string, unknown> = {};
     if (existsSync(gmtrJsonPath)) {
       try { gmtrConfig = JSON.parse(readFileSync(gmtrJsonPath, 'utf8')); } catch {}
@@ -254,7 +258,7 @@ export async function main(): Promise<void> {
     gmtrConfig.token = apiKey;
     gmtrConfig.token_updated_at = new Date().toISOString();
     writeFileSync(gmtrJsonPath, JSON.stringify(gmtrConfig, null, 2) + '\n');
-    log('  OK Token stored in ~/.gmtr.json (hooks read from here at runtime)');
+    log('  OK Token stored in ~/.gramatr.json (hooks read from here at runtime)');
   }
 
   // ── Summary ──
@@ -272,6 +276,10 @@ export async function main(): Promise<void> {
   log('');
   log('  Restart Gemini CLI to load the extension.');
   log('');
+
+  // v0.6.2+: detect legacy GMTR_* exports in shell rc and warn
+  const rcHits = detectShellRcLegacyEnv(home);
+  if (rcHits.length > 0) log(formatShellRcLegacyWarning(rcHits));
 }
 
 // Run directly when executed as a script

package/gemini/lib/gemini-install-utils.ts

@@ -155,10 +155,10 @@ export function getGramatrExtensionDir(home: string): string {
 }
 
 /**
- * Read the stored API key from ~/.gmtr.json (shared with other platforms).
+ * Read the stored API key from ~/.gramatr.json (shared with other platforms).
  */
 export function readStoredApiKey(home: string): string | null {
-  const configPath = join(home, '.gmtr.json');
+  const configPath = join(home, '.gramatr.json');
   if (!existsSync(configPath)) return null;
   try {
     const config = JSON.parse(readFileSync(configPath, 'utf8'));

package/hooks/StopOrchestrator.hook.ts

@@ -40,7 +40,7 @@ async function main() {
   let token = '';
 
   try {
-    const gmtrJson = JSON.parse(readFileSync(`${process.env.HOME}/.gmtr.json`, 'utf8'));
+    const gmtrJson = JSON.parse(readFileSync(`${process.env.HOME}/.gramatr.json`, 'utf8'));
     token = gmtrJson.token || '';
   } catch { /* no token */ }
 

package/hooks/lib/gmtr-hook-utils.ts

@@ -341,16 +341,16 @@ export function createDefaultConfig(options: {
  * Resolve auth token. gramatr credentials NEVER live in CLI-specific config files.
  *
  * Priority:
- *   1. ~/.gmtr.json (canonical, gramatr-owned, vendor-agnostic)
+ *   1. ~/.gramatr.json (canonical, gramatr-owned, vendor-agnostic)
  *   2. GRAMATR_TOKEN env var (CI, headless override)
- *   3. ~/gmtr-client/settings.json auth.api_key (legacy, will be migrated)
+ *   3. ~/.gramatr/settings.json auth.api_key (legacy, will be migrated)
  *
  * Token is NEVER stored in ~/.claude.json, ~/.codex/, or ~/.gemini/.
  */
 export function resolveAuthToken(): string | null {
-  // 1. ~/.gmtr.json (canonical source — written by installer, read by all platforms)
+  // 1. ~/.gramatr.json (canonical source — written by installer, read by all platforms)
   try {
-    const configPath = join(HOME, '.gmtr.json');
+    const configPath = join(HOME, '.gramatr.json');
     const config = JSON.parse(readFileSync(configPath, 'utf8'));
     if (config.token) return config.token;
   } catch {
@@ -363,9 +363,9 @@ export function resolveAuthToken(): string | null {
   // 3. Legacy: AIOS_MCP_TOKEN env var (deprecated)
   if (process.env.AIOS_MCP_TOKEN) return process.env.AIOS_MCP_TOKEN;
 
-  // 4. Legacy: ~/gmtr-client/settings.json (will be migrated to ~/.gmtr.json)
+  // 4. Legacy: ~/.gramatr/settings.json (will be migrated to ~/.gramatr.json)
   try {
-    const gmtrDir = process.env.GRAMATR_DIR || join(HOME, 'gmtr-client');
+    const gmtrDir = process.env.GRAMATR_DIR || join(HOME, '.gramatr');
     const settingsPath = join(gmtrDir, 'settings.json');
     const settings = JSON.parse(readFileSync(settingsPath, 'utf8'));
     if (settings.auth?.api_key && settings.auth.api_key !== 'REPLACE_WITH_YOUR_API_KEY') {
@@ -382,12 +382,12 @@ export function resolveAuthToken(): string | null {
 
 /**
  * Resolve MCP server URL from config files.
- * Priority: ~/gmtr-client/settings.json > GRAMATR_URL env > ~/.claude.json > default
+ * Priority: ~/.gramatr/settings.json > GRAMATR_URL env > ~/.claude.json > default
  */
 export function resolveMcpUrl(): string {
-  // 1. ~/gmtr-client/settings.json (canonical, vendor-agnostic)
+  // 1. ~/.gramatr/settings.json (canonical, vendor-agnostic)
   try {
-    const gmtrDir = process.env.GRAMATR_DIR || join(HOME, 'gmtr-client');
+    const gmtrDir = process.env.GRAMATR_DIR || join(HOME, '.gramatr');
     const settingsPath = join(gmtrDir, 'settings.json');
     const settings = JSON.parse(readFileSync(settingsPath, 'utf8'));
     if (settings.auth?.server_url) return settings.auth.server_url;

package/hooks/lib/identity.ts

@@ -10,7 +10,7 @@ import { readFileSync, existsSync } from 'fs';
 import { join } from 'path';
 
 const HOME = process.env.HOME!;
-const GRAMATR_DIR = process.env.GRAMATR_DIR || join(HOME, 'gmtr-client');
+const GRAMATR_DIR = process.env.GRAMATR_DIR || join(HOME, '.gramatr');
 const GMTR_SETTINGS_PATH = join(GRAMATR_DIR, 'settings.json');        // gramatr-owned, vendor-agnostic
 const CLAUDE_SETTINGS_PATH = join(HOME, '.claude/settings.json');   // legacy fallback only
 
@@ -82,7 +82,7 @@ let cachedSettings: Settings | null = null;
  * Load settings — gramatr-owned config first, Claude vendor file as legacy fallback.
  *
  * Priority:
- *   1. ~/gmtr-client/settings.json (gramatr-owned, vendor-agnostic)
+ *   1. ~/.gramatr/settings.json (gramatr-owned, vendor-agnostic)
  *   2. ~/.claude/settings.json (Claude vendor file — legacy fallback only)
  *
  * Merges both: gramatr settings take precedence for identity fields,

package/hooks/lib/paths.ts

@@ -50,7 +50,7 @@ export function getGmtrDir(): string {
 /**
  * Get the settings.json path
  * Always ~/.claude/settings.json — NOT relative to GRAMATR_DIR.
- * GRAMATR_DIR is the client payload directory (~/gmtr-client), not ~/.claude.
+ * GRAMATR_DIR is the client payload directory (~/.gramatr), not ~/.claude.
  */
 export function getSettingsPath(): string {
   return join(homedir(), '.claude', 'settings.json');

package/hooks/session-start.hook.ts

@@ -171,7 +171,7 @@ function displayBanner(): void {
 // ── Sync Ratings (background, non-blocking) ──
 
 function syncRatingsInBackground(): void {
-  const syncScript = join(process.env.GRAMATR_DIR || join(process.env.HOME || '', 'gmtr-client'), 'hooks', 'sync-ratings.hook.ts');
+  const syncScript = join(process.env.GRAMATR_DIR || join(process.env.HOME || '', '.gramatr'), 'hooks', 'sync-ratings.hook.ts');
   if (existsSync(syncScript)) {
     try {
       const npxBin = process.platform === 'win32' ? 'npx.cmd' : 'npx';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gramatr/client",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "publishConfig": {
     "access": "public"
   },