@gramatr/client 0.5.2 → 0.6.1

package/core/auth.ts

@@ -7,9 +7,9 @@
  *
  * Resolution chain (first non-empty wins):
  *   1. GRAMATR_API_KEY env var
- *   2. GMTR_TOKEN env var (legacy)
- *   3. ~/.gmtr.json `token` field
- *   4. ~/gmtr-client/settings.json `auth.api_key` (legacy, skips placeholder)
+ *   2. GRAMATR_TOKEN env var (legacy)
+ *   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,17 +44,19 @@ function getHome(): string {
 }
 
 function gmtrJsonPath(): string {
-  return join(getHome(), ".gmtr.json");
+  return join(getHome(), ".gramatr.json");
 }
 
 function legacySettingsPath(): string {
-  const gmtrDir = process.env.GMTR_DIR || join(getHome(), "gmtr-client");
+  const gmtrDir = process.env.GRAMATR_DIR || join(getHome(), ".gramatr");
   return join(gmtrDir, "settings.json");
 }
 
 function tokenFromEnv(): string | null {
+  // GRAMATR_API_KEY is the canonical env var for long-lived API keys.
+  // Legacy GMTR_TOKEN slot was removed in v0.6.0; see #512 for the full
+  // auth architecture refactor (split API keys from OAuth refresh tokens).
   if (process.env.GRAMATR_API_KEY) return process.env.GRAMATR_API_KEY;
-  if (process.env.GMTR_TOKEN) return process.env.GMTR_TOKEN;
   return null;
 }
 
@@ -88,7 +90,7 @@ function findGmtrLoginScript(): string | null {
   }
   // Fallback to installed client dir
   const installedCandidate = join(
-    process.env.GMTR_DIR || join(getHome(), "gmtr-client"),
+    process.env.GRAMATR_DIR || join(getHome(), ".gramatr"),
     "bin",
     "gmtr-login.ts",
   );
@@ -142,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/feedback.ts

@@ -33,7 +33,7 @@ export async function submitPendingClassificationFeedback(
   }
 
   const result = await callMcpToolDetailed(
-    'gmtr_classification_feedback',
+    'gramatr_classification_feedback',
     {
       timestamp: last.timestamp,
       was_correct: true,

package/core/install.ts

@@ -27,13 +27,13 @@ interface ClaudeHookOptions {
 }
 
 const CLAUDE_HOOKS: HookSpec[] = [
-  { event: 'PreToolUse', matcher: 'Bash', relativeCommand: 'hooks/GMTRSecurityValidator.hook.ts' },
-  { event: 'PreToolUse', matcher: 'Edit', relativeCommand: 'hooks/GMTRSecurityValidator.hook.ts' },
-  { event: 'PreToolUse', matcher: 'Write', relativeCommand: 'hooks/GMTRSecurityValidator.hook.ts' },
-  { event: 'PreToolUse', matcher: 'Read', relativeCommand: 'hooks/GMTRSecurityValidator.hook.ts' },
-  { event: 'PostToolUse', matcher: 'mcp__.*gramatr.*__', relativeCommand: 'hooks/GMTRToolTracker.hook.ts' },
-  { event: 'UserPromptSubmit', relativeCommand: 'hooks/GMTRRatingCapture.hook.ts' },
-  { event: 'UserPromptSubmit', relativeCommand: 'hooks/GMTRPromptEnricher.hook.ts' },
+  { event: 'PreToolUse', matcher: 'Bash', relativeCommand: 'hooks/gramatr-security-validator.hook.ts' },
+  { event: 'PreToolUse', matcher: 'Edit', relativeCommand: 'hooks/gramatr-security-validator.hook.ts' },
+  { event: 'PreToolUse', matcher: 'Write', relativeCommand: 'hooks/gramatr-security-validator.hook.ts' },
+  { event: 'PreToolUse', matcher: 'Read', relativeCommand: 'hooks/gramatr-security-validator.hook.ts' },
+  { event: 'PostToolUse', matcher: 'mcp__.*gramatr.*__', relativeCommand: 'hooks/gramatr-tool-tracker.hook.ts' },
+  { event: 'UserPromptSubmit', relativeCommand: 'hooks/gramatr-rating-capture.hook.ts' },
+  { event: 'UserPromptSubmit', relativeCommand: 'hooks/gramatr-prompt-enricher.hook.ts' },
   { event: 'SessionStart', relativeCommand: 'hooks/session-start.hook.ts' },
   { event: 'SessionEnd', relativeCommand: 'hooks/session-end.hook.ts' },
   { event: 'Stop', relativeCommand: 'hooks/StopOrchestrator.hook.ts' },

package/core/routing.ts

@@ -30,7 +30,7 @@ export async function routePrompt(options: {
   statuslineSize?: 'small' | 'medium' | 'large';
 }): Promise<{ route: RouteResponse | null; error: MctToolCallError | null }> {
   const result = await callMcpToolDetailed<RouteResponse>(
-    'gmtr_route_request',
+    'gramatr_route_request',
     {
       prompt: options.prompt,
       ...(options.projectId ? { project_id: options.projectId } : {}),
@@ -79,7 +79,7 @@ export function describeRoutingFailure(error: MctToolCallError): {
       return {
         title: 'Routing request failed before intelligence could be injected.',
         detail: error.detail,
-        action: `Inspect the response from ${resolveMcpUrl()} and the gmtr_route_request handler.`,
+        action: `Inspect the response from ${resolveMcpUrl()} and the gramatr_route_request handler.`,
       };
   }
 }

package/core/session.ts

@@ -28,7 +28,7 @@ export interface CurrentProjectContextPayload {
   project_name: string;
   working_directory: string;
   session_start: string;
-  gmtr_config_path: string;
+  gramatr_config_path: string;
   project_entity_id: string | null;
   action_required: string;
   project_id?: string;
@@ -114,7 +114,7 @@ export async function startRemoteSession(options: {
   directory: string;
 }): Promise<SessionStartResponse | null> {
   return (await callMcpTool(
-    'gmtr_session_start',
+    'gramatr_session_start',
     {
       client_type: options.clientType,
       project_id: options.projectId,
@@ -129,7 +129,7 @@ export async function startRemoteSession(options: {
 
 export async function loadProjectHandoff(projectId: string): Promise<HandoffResponse | null> {
   return (await callMcpTool(
-    'gmtr_load_handoff',
+    'gramatr_load_handoff',
     { project_id: projectId },
     15000,
   )) as HandoffResponse | null;
@@ -143,7 +143,7 @@ export function persistSessionRegistration(rootDir: string, response: SessionSta
   if (!config) return null;
   config.current_session = config.current_session || {};
   if (normalized.interactionId) config.current_session.interaction_id = normalized.interactionId;
-  if (normalized.entityId) config.current_session.gmtr_entity_id = normalized.entityId;
+  if (normalized.entityId) config.current_session.gramatr_entity_id = normalized.entityId;
   writeGmtrConfig(rootDir, config);
   return config;
 }
@@ -176,7 +176,7 @@ export function buildGitProjectContextPayload(options: {
     git_remote: options.git.remote,
     working_directory: options.workingDirectory,
     session_start: options.sessionStart,
-    gmtr_config_path: join(options.git.root, '.gmtr', 'settings.json'),
+    gramatr_config_path: join(options.git.root, '.gmtr', 'settings.json'),
     project_entity_id: options.projectEntityId,
     restore_needed: options.restoreNeeded,
     action_required: 'check_or_create_project_entity',
@@ -195,8 +195,8 @@ export function buildNonGitProjectContextPayload(options: {
     project_name: basename(options.cwd),
     working_directory: options.cwd,
     session_start: options.sessionStart,
-    gmtr_config_path: join(options.cwd, '.gmtr', 'settings.json'),
+    gramatr_config_path: join(options.cwd, '.gmtr', 'settings.json'),
     project_entity_id: options.projectEntityId,
-    action_required: 'gmtr_init_needed',
+    action_required: 'gramatr_init_needed',
   };
 }

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/desktop/install.ts

@@ -64,7 +64,7 @@ async function main(): Promise<void> {
   // Step 2: Validate server connectivity
   log('');
   log('Step 2: Validating server connectivity...');
-  const serverUrl = process.env.GMTR_URL || DEFAULT_MCP_URL;
+  const serverUrl = process.env.GRAMATR_URL || DEFAULT_MCP_URL;
   const serverReachable = await validateServer(serverUrl);
   if (serverReachable) {
     log(`  OK Server reachable at ${serverUrl.replace(/\/mcp$/, '')}`);

package/gemini/README.md

@@ -74,7 +74,7 @@ bun packages/client/bin/gmtr-login.ts
 
 This stores the token in `~/.gmtr.json`, which the installer reads automatically.
 
-API keys start with `gmtr_sk_` and can be created at [gramatr.com](https://gramatr.com) or via the `gmtr_create_api_key` MCP tool.
+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.
 
 ## Hook Event Mapping
 

package/gemini/install.ts

@@ -46,7 +46,7 @@ async function promptForApiKey(): Promise<string | null> {
   log('  gramatr requires authentication.');
   log('  Options:');
   log('    1. Run `bun gmtr-login.ts` first to authenticate via browser');
-  log('    2. Paste an API key below (starts with gmtr_sk_)');
+  log('    2. Paste an API key below (starts with gramatr_sk_)');
   log('');
   process.stdout.write('  API Key (enter to skip): ');
 
@@ -104,10 +104,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 +142,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 {
@@ -154,12 +154,12 @@ async function resolveApiKey(home: string): Promise<string | null> {
       }
       config.token = prompted;
       config.token_type =
-        prompted.startsWith('gmtr_sk_') || prompted.startsWith('aios_sk_')
+        prompted.startsWith('gramatr_sk_') || prompted.startsWith('aios_sk_')
           ? 'api_key'
           : '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 +244,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 +254,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 ──

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

@@ -67,7 +67,7 @@ export function buildExtensionManifest(): GeminiExtensionManifest {
         name: 'API Key',
         envVar: 'GRAMATR_API_KEY',
         sensitive: true,
-        description: 'gramatr API key (starts with gmtr_sk_). Get one at gramatr.com or via gmtr-login.',
+        description: 'gramatr API key (starts with gramatr_sk_). Get one at gramatr.com or via gmtr-login.',
       },
     ],
   };
@@ -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

@@ -36,11 +36,11 @@ async function main() {
 
   // Read server URL and token for direct HTTP feedback
   const gmtrDir = getGmtrDir();
-  let serverUrl = process.env.GMTR_URL || 'https://api.gramatr.com/mcp';
+  let serverUrl = process.env.GRAMATR_URL || 'https://api.gramatr.com/mcp';
   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 */ }
 
@@ -61,7 +61,7 @@ async function main() {
         id: 1,
         method: 'tools/call',
         params: {
-          name: 'gmtr_classification_feedback',
+          name: 'gramatr_classification_feedback',
           arguments: {
             original_prompt: parsed.userMessages?.[0] || '',
             session_id: hookInput.session_id,

package/hooks/gmtr-tool-tracker-utils.ts

@@ -1,7 +1,7 @@
 /**
  * gmtr-tool-tracker-utils.ts — Pure utility functions for the GMTR Tool Tracker hook.
  *
- * Extracted from GMTRToolTracker.hook.ts for testability. These are pure functions
+ * Extracted from gramatr-tool-tracker.hook.ts for testability. These are pure functions
  * with no Bun dependencies, no I/O, no side effects.
  */
 

package/hooks/{GMTRPromptEnricher.hook.ts → gramatr-prompt-enricher.hook.ts}

@@ -1,13 +1,13 @@
 #!/usr/bin/env node
 /**
- * GMTRPromptEnricher.hook.ts — grāmatr UserPromptSubmit Hook
+ * gramatr-prompt-enricher.hook.ts — grāmatr UserPromptSubmit Hook
  *
  * Fires before the agent processes a user prompt. Calls the grāmatr
  * decision router to pre-classify the request, then injects
  * the intelligence as additionalContext so the agent sees it.
  *
  * TRIGGER: UserPromptSubmit
- * TIMEOUT: 15s default (configurable via GMTR_TIMEOUT)
+ * TIMEOUT: 15s default (configurable via GRAMATR_TIMEOUT)
  * SAFETY: Never blocks. On any error, prompt passes through unmodified.
  *
  * What it injects:
@@ -42,8 +42,8 @@ interface HookInput {
 
 // ── Configuration ──
 
-const TIMEOUT_MS = parseInt(process.env.GMTR_TIMEOUT || '30000', 10);
-const ENABLED = process.env.GMTR_ENRICH !== '0'; // disable with GMTR_ENRICH=0
+const TIMEOUT_MS = parseInt(process.env.GRAMATR_TIMEOUT || '30000', 10);
+const ENABLED = process.env.GRAMATR_ENRICH !== '0'; // disable with GRAMATR_ENRICH=0
 
 // ── Project ID Resolution (Issue #76 — project-scoped memory) ──
 
@@ -398,9 +398,9 @@ function formatIntelligence(data: RouteResponse): string {
       lines.push(`  Context: ${ca.context_summary || 'memory-aware'}`);
       lines.push('  ACTION: Use the Task tool with subagent_type="general-purpose" and inject this system prompt:');
       lines.push('  --- AGENT SYSTEM PROMPT START ---');
-      // Truncate to avoid overwhelming the context — full prompt available via gmtr_invoke_agent
+      // Truncate to avoid overwhelming the context — full prompt available via gramatr_invoke_agent
       const promptPreview = (ca.system_prompt || '').substring(0, 800);
-      lines.push(`  ${promptPreview}${(ca.system_prompt || '').length > 800 ? '... [truncated — use gmtr_invoke_agent for full prompt]' : ''}`);
+      lines.push(`  ${promptPreview}${(ca.system_prompt || '').length > 800 ? '... [truncated — use gramatr_invoke_agent for full prompt]' : ''}`);
       lines.push('  --- AGENT SYSTEM PROMPT END ---');
     }
   }

package/hooks/{GMTRRatingCapture.hook.ts → gramatr-rating-capture.hook.ts}

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 /**
- * GMTRRatingCapture.hook.ts — gramatr-native Rating Capture (UserPromptSubmit)
+ * gramatr-rating-capture.hook.ts — gramatr-native Rating Capture (UserPromptSubmit)
  *
  * Captures explicit ratings (1-10 pattern) from user prompts and writes
- * to $GMTR_DIR/.state/ratings.jsonl for sparkline consumption.
+ * to $GRAMATR_DIR/.state/ratings.jsonl for sparkline consumption.
  *
  * TRIGGER: UserPromptSubmit
  *
@@ -15,7 +15,7 @@
  * - Self-contained: only depends on ./lib/paths
  *
  * SIDE EFFECTS:
- * - Writes to: $GMTR_DIR/.state/ratings.jsonl
+ * - Writes to: $GRAMATR_DIR/.state/ratings.jsonl
  * - macOS notification for low ratings (<= 3)
  *
  * PERFORMANCE:
@@ -100,13 +100,13 @@ function parseExplicitRating(prompt: string): { rating: number; comment?: string
 function writeRating(entry: RatingEntry): void {
   if (!existsSync(STATE_DIR)) mkdirSync(STATE_DIR, { recursive: true });
   appendFileSync(RATINGS_FILE, JSON.stringify(entry) + '\n', 'utf-8');
-  console.error(`[GMTRRatingCapture] Wrote rating ${entry.rating} to ${RATINGS_FILE}`);
+  console.error(`[gramatr-rating-capture] Wrote rating ${entry.rating} to ${RATINGS_FILE}`);
 }
 
 // ── Push to GMTR Server (fire-and-forget) ──
 
 function pushToServer(entry: RatingEntry): void {
-  const gmtrUrl = process.env.GMTR_URL || 'https://api.gramatr.com/mcp';
+  const gmtrUrl = process.env.GRAMATR_URL || 'https://api.gramatr.com/mcp';
   const apiBase = gmtrUrl.replace(/\/mcp$/, '/api/v1');
 
   fetch(`${apiBase}/feedback`, {
@@ -124,9 +124,9 @@ function pushToServer(entry: RatingEntry): void {
   })
     .then((res) => {
       if (res.ok) {
-        console.error(`[GMTRRatingCapture] Pushed rating ${entry.rating} to server`);
+        console.error(`[gramatr-rating-capture] Pushed rating ${entry.rating} to server`);
       } else {
-        console.error(`[GMTRRatingCapture] Server push failed: HTTP ${res.status}`);
+        console.error(`[gramatr-rating-capture] Server push failed: HTTP ${res.status}`);
       }
     })
     .catch(() => {
@@ -169,7 +169,7 @@ async function main() {
       process.exit(0);
     }
 
-    console.error(`[GMTRRatingCapture] Explicit rating: ${result.rating}${result.comment ? ` - ${result.comment}` : ''}`);
+    console.error(`[gramatr-rating-capture] Explicit rating: ${result.rating}${result.comment ? ` - ${result.comment}` : ''}`);
 
     const entry: RatingEntry = {
       timestamp: new Date().toISOString(),
@@ -190,7 +190,7 @@ async function main() {
 
     process.exit(0);
   } catch (err) {
-    console.error(`[GMTRRatingCapture] Error: ${err}`);
+    console.error(`[gramatr-rating-capture] Error: ${err}`);
     process.exit(0);
   }
 }

package/hooks/{GMTRSecurityValidator.hook.ts → gramatr-security-validator.hook.ts}

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * GMTRSecurityValidator.hook.ts — gramatr-native Security Validation (PreToolUse)
+ * gramatr-security-validator.hook.ts — gramatr-native Security Validation (PreToolUse)
  *
  * Validates Bash commands and file operations against security patterns
  * before execution. Prevents destructive operations and protects sensitive files.
@@ -10,7 +10,7 @@
  * This is the gramatr-native replacement for PAI's SecurityValidator.hook.ts.
  * Key differences:
  * - Inline default patterns (no yaml dependency, no PAI skill dir)
- * - Logs to $GMTR_DIR/.state/security/ (not PAI MEMORY/SECURITY/)
+ * - Logs to $GRAMATR_DIR/.state/security/ (not PAI MEMORY/SECURITY/)
  * - Self-contained: only depends on ./lib/paths
  *
  * OUTPUT:

package/hooks/{GMTRToolTracker.hook.ts → gramatr-tool-tracker.hook.ts}

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * GMTRToolTracker.hook.ts — grāmatr PostToolUse Hook
+ * gramatr-tool-tracker.hook.ts — grāmatr PostToolUse Hook
  *
  * Fires after any GMTR MCP tool call. Extracts execution metrics from
  * tool_result and surfaces them as a user-visible status line.
@@ -146,7 +146,7 @@ async function main() {
       try { stats = JSON.parse(readFileSync(statsFile, 'utf8')); } catch {}
 
       // Track search count
-      if (shortName.includes('search') || shortName === 'gmtr_execute_intent') {
+      if (shortName.includes('search') || shortName === 'gramatr_execute_intent') {
         stats.search_count = ((stats.search_count as number) || 0) + 1;
       }
 

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

@@ -46,7 +46,7 @@ export interface GmtrConfig {
     last_updated?: string;
     token_limit?: number;
     interaction_id?: string;
-    gmtr_entity_id?: string;
+    gramatr_entity_id?: string;
     helper_pid?: number | null;
     last_classification?: {
       timestamp?: string;
@@ -341,31 +341,31 @@ 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)
- *   2. GMTR_TOKEN env var (CI, headless override)
- *   3. ~/gmtr-client/settings.json auth.api_key (legacy, will be migrated)
+ *   1. ~/.gramatr.json (canonical, gramatr-owned, vendor-agnostic)
+ *   2. GRAMATR_TOKEN env var (CI, headless override)
+ *   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 {
     // No config file or parse error
   }
 
-  // 2. GMTR_TOKEN env var (CI, headless, or shell profile override)
-  if (process.env.GMTR_TOKEN) return process.env.GMTR_TOKEN;
+  // 2. GRAMATR_TOKEN env var (CI, headless, or shell profile override)
+  if (process.env.GRAMATR_TOKEN) return process.env.GRAMATR_TOKEN;
 
   // 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.GMTR_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 > GMTR_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.GMTR_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;
@@ -396,7 +396,7 @@ export function resolveMcpUrl(): string {
   }
 
   // 2. Environment variable
-  if (process.env.GMTR_URL) return process.env.GMTR_URL;
+  if (process.env.GRAMATR_URL) return process.env.GRAMATR_URL;
 
   // 3. ~/.claude.json (Claude-specific MCP config)
   try {

package/hooks/lib/identity.ts

@@ -10,8 +10,8 @@ import { readFileSync, existsSync } from 'fs';
 import { join } from 'path';
 
 const HOME = process.env.HOME!;
-const GMTR_DIR = process.env.GMTR_DIR || join(HOME, 'gmtr-client');
-const GMTR_SETTINGS_PATH = join(GMTR_DIR, 'settings.json');        // gramatr-owned, vendor-agnostic
+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
 
 // Default identity (fallback if settings.json doesn't have identity section)
@@ -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

@@ -28,15 +28,15 @@ export function expandPath(path: string): string {
 
 /**
  * Get the GMTR base directory (expanded)
- * Priority: GMTR_DIR env var → PAI_DIR env var (migration) → ~/.claude
+ * Priority: GRAMATR_DIR env var → PAI_DIR env var (migration) → ~/.claude
  */
 export function getGmtrDir(): string {
-  const envGmtrDir = process.env.GMTR_DIR;
+  const envGmtrDir = process.env.GRAMATR_DIR;
   if (envGmtrDir) {
     return expandPath(envGmtrDir);
   }
 
-  // Migration fallback: honor PAI_DIR if GMTR_DIR not set yet
+  // Migration fallback: honor PAI_DIR if GRAMATR_DIR not set yet
   const envPaiDir = process.env.PAI_DIR;
   if (envPaiDir) {
     return expandPath(envPaiDir);
@@ -49,15 +49,15 @@ export function getGmtrDir(): string {
 
 /**
  * Get the settings.json path
- * Always ~/.claude/settings.json — NOT relative to GMTR_DIR.
- * GMTR_DIR is the client payload directory (~/gmtr-client), not ~/.claude.
+ * Always ~/.claude/settings.json — NOT relative to GRAMATR_DIR.
+ * GRAMATR_DIR is the client payload directory (~/.gramatr), not ~/.claude.
  */
 export function getSettingsPath(): string {
   return join(homedir(), '.claude', 'settings.json');
 }
 
 /**
- * Get a path relative to GMTR_DIR
+ * Get a path relative to GRAMATR_DIR
  */
 export function gmtrPath(...segments: string[]): string {
   return join(getGmtrDir(), ...segments);

package/hooks/session-end.hook.ts

@@ -123,17 +123,17 @@ async function main(): Promise<void> {
         }
 
         // Get session state from config
-        const sessionEntityId = config?.current_session?.gmtr_entity_id || '';
+        const sessionEntityId = config?.current_session?.gramatr_entity_id || '';
         const interactionId = config?.current_session?.interaction_id || '';
 
         log('');
         log('Saving session state to gramatr...');
 
-        // Session lifecycle only — gmtr_session_end records git summary on the session entity.
-        // Handoffs are saved by the AGENT in the LEARN phase via gmtr_save_handoff (HARD GATE).
+        // Session lifecycle only — gramatr_session_end records git summary on the session entity.
+        // Handoffs are saved by the AGENT in the LEARN phase via gramatr_save_handoff (HARD GATE).
         // The hook does NOT save handoffs — it lacks conversation context.
         try {
-          const rawResult = await callMcpToolRaw('gmtr_session_end', {
+          const rawResult = await callMcpToolRaw('gramatr_session_end', {
             entity_id: sessionEntityId || sessionId,
             session_id: sessionId,
             interaction_id: interactionId,

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.GMTR_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';
@@ -336,9 +336,9 @@ async function main(): Promise<void> {
         log('   - Show observation timestamps');
         log(`3. Load related entities from \`${gmtrConfigPath}\`:`);
         log('   - Check .related_entities for linked databases, people, services, concepts');
-        log('   - Optionally fetch details for key related entities (use gmtr_execute_intent with detail_level: summary)');
+        log('   - Optionally fetch details for key related entities (use gramatr_execute_intent with detail_level: summary)');
         log('4. Keep summary concise - just enough context to resume work');
-        log('   NOTE: Using intelligent tools (gmtr_execute_intent) provides 80-95% token reduction vs direct get_entities calls');
+        log('   NOTE: Using intelligent tools (gramatr_execute_intent) provides 80-95% token reduction vs direct get_entities calls');
         log('');
       }
 

package/package.json

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