@gramatr/client 0.6.1 → 0.6.3

package/CLAUDE.md

@@ -10,7 +10,7 @@ ISC scaffold, capability audit, phase templates, and composed agents.
 **Memory:** Use gramatr MCP tools (`search_semantic`, `create_entity`, `add_observation`),
 not local markdown files.
 
-**Identity:** Read from `~/gmtr-client/settings.json` — `daidentity` for your name,
+**Identity:** Read from `~/.gramatr/settings.json` — `daidentity` for your name,
 `principal` for the user's name.
 
 **If the server is unreachable:** Use 7-phase structure (OBSERVE → THINK → PLAN → BUILD →

package/README.md

@@ -72,14 +72,14 @@ The client never stores intelligence locally. The server delivers everything: be
 ## What gets installed
 
 ```
-~/gmtr-client/          # Client runtime
+~/.gramatr/          # Client runtime
   hooks/                # 8 lifecycle hooks
   core/                 # Shared routing + session logic
   bin/                  # Status line, login, utilities
   CLAUDE.md             # Minimal behavioral framework
 ~/.claude/settings.json # Hook configuration (merged, not overwritten)
 ~/.claude.json          # MCP server registration
-~/.gmtr.json            # Auth token (canonical source)
+~/.gramatr.json            # Auth token (canonical source)
 ```
 
 ## Commands

package/bin/clear-creds.ts

@@ -40,7 +40,7 @@ function showHelp(): void {
   log(`gramatr clear-creds — Remove every stored gramatr credential
 
 Usage:
-  gramatr clear-creds   Sweep ~/.gramatr.json + auth.api_key from gmtr-client/settings.json
+  gramatr clear-creds   Sweep ~/.gramatr.json + auth.api_key from ~/.gramatr/settings.json
 
 After running, the next install or login will be forced through OAuth.
 

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 ──
 
@@ -513,8 +518,8 @@ 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}/.gramatr/bin:/usr/local/bin:/usr/bin:/bin`;
@@ -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;
 
@@ -737,6 +743,10 @@ async function main(): Promise<void> {
       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/uninstall.ts

@@ -170,7 +170,7 @@ async function main(): Promise<void> {
       try {
         const settings = JSON.parse(readFileSync(claudeSettings, 'utf8'));
         if (settings.hooks) {
-          // Remove hook entries that reference gmtr-client
+          // Remove hook entries that reference .gramatr or gramatr paths
           for (const [event, hooks] of Object.entries(settings.hooks)) {
             if (Array.isArray(hooks)) {
               settings.hooks[event] = (hooks as any[]).filter(

package/chatgpt/README.md

@@ -19,7 +19,7 @@ bun chatgpt/install.ts
 ```
 
 The installer will:
-1. Find your API key from `~/.gmtr.json`, `GRAMATR_API_KEY` env, or prompt you
+1. Find your API key from `~/.gramatr.json`, `GRAMATR_API_KEY` env, or prompt you
 2. Validate connectivity to the gramatr server
 3. Detect your platform and locate the ChatGPT config file
 4. Merge the gramatr MCP server entry without overwriting existing servers

package/codex/README.md

@@ -21,8 +21,8 @@ Install locally with:
 - `pnpm --filter @gramatr/client install-codex`
 
 The installer:
-- syncs this Codex runtime into `~/gmtr-client/codex`
-- syncs the shared `gmtr-hook-utils.ts` dependency into `~/gmtr-client/hooks/lib`
+- syncs this Codex runtime into `~/.gramatr/codex`
+- syncs the shared `gmtr-hook-utils.ts` dependency into `~/.gramatr/hooks/lib`
 - merges `~/.codex/hooks.json`
 - enables `codex_hooks` in `~/.codex/config.toml`
 - upserts a managed gramatr block in `~/.codex/AGENTS.md`

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 -->';
@@ -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/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-check.ts

@@ -2,7 +2,7 @@
  * version-check.ts — opportunistic npm registry version check.
  *
  * Queries https://registry.npmjs.org/gramatr/latest on a 3s timeout, caches
- * the result for one hour under ~/.gmtr-client/.cache/version-check.json, and
+ * the result for one hour under ~/.gramatr/.cache/version-check.json, and
  * reports whether the installed client is behind the published version.
  *
  * Design constraints (see issue #468 sibling work):
@@ -56,7 +56,7 @@ export function compareVersions(a: string, b: string): number {
 }
 
 export function getCachePath(home: string = homedir()): string {
-  return join(home, '.gmtr-client', '.cache', 'version-check.json');
+  return join(home, '.gramatr', '.cache', 'version-check.json');
 }
 
 function readCache(path: string): CacheFile | null {

package/desktop/README.md

@@ -12,7 +12,7 @@ bun packages/client/desktop/install.ts
 ```
 
 The installer:
-1. Resolves your API key from `~/.gmtr.json`, `GRAMATR_API_KEY` env, or prompts
+1. Resolves your API key from `~/.gramatr.json`, `GRAMATR_API_KEY` env, or prompts
 2. Validates connectivity to the gramatr server
 3. Detects platform (macOS or Windows)
 4. Reads existing `claude_desktop_config.json` without overwriting other MCP servers

package/gemini/README.md

@@ -62,7 +62,7 @@ echo "GRAMATR_API_KEY=your-key-here" > ~/.gemini/extensions/gramatr/.env
 
 gramatr requires a Bearer token for all MCP calls. The installer handles this by:
 
-1. Checking `~/.gmtr.json` for an existing token (shared with Claude Code / Codex)
+1. Checking `~/.gramatr.json` for an existing token (shared with Claude Code / Codex)
 2. Checking the `GRAMATR_API_KEY` environment variable
 3. Prompting for a token interactively
 
@@ -72,7 +72,7 @@ To authenticate before installing, run:
 bun packages/client/bin/gmtr-login.ts
 ```
 
-This stores the token in `~/.gmtr.json`, which the installer reads automatically.
+This stores the token in `~/.gramatr.json`, which the installer reads automatically.
 
 API keys start with `gramatr_sk_` and can be created at [gramatr.com](https://gramatr.com) or via the `gramatr_create_api_key` MCP tool.
 
@@ -92,4 +92,4 @@ After installing and restarting Gemini CLI:
 > @gramatr search for recent learning signals
 ```
 
-If the MCP server responds, the extension is working. If you see auth errors, re-run the installer or check `~/.gmtr.json`.
+If the MCP server responds, the extension is working. If you see auth errors, re-run the installer or check `~/.gramatr.json`.

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`);
@@ -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/hooks/session-start.hook.ts

@@ -321,7 +321,7 @@ async function main(): Promise<void> {
         log('This will:');
         log(`  1. Search gramatr for existing project: ${git.projectName}`);
         log('  2. Create project entity if not found');
-        log('  3. Link entity to .gmtr.json');
+        log('  3. Link entity to .gramatr.json');
         log('  4. Enable full memory persistence');
         log('');
       } else {

package/package.json

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