@gramatr/client 0.5.1 → 0.6.0

package/bin/add-api-key.ts

@@ -4,7 +4,7 @@
  *
  * Three modes:
  *   1. Interactive prompt:    gramatr add-api-key
- *   2. Piped stdin:           echo "gmtr_sk_..." | gramatr add-api-key
+ *   2. Piped stdin:           echo "gramatr_sk_..." | gramatr add-api-key
  *   3. Env-sourced:           gramatr add-api-key --from-env GRAMATR_API_KEY
  *
  * The key is validated against the gramatr server before being written
@@ -22,11 +22,11 @@ import { createInterface } from "readline";
 function gmtrJsonPath(): string {
   return join(process.env.HOME || process.env.USERPROFILE || homedir(), ".gmtr.json");
 }
-const SERVER_BASE = (process.env.GMTR_URL || "https://api.gramatr.com").replace(/\/mcp\/?$/, "");
+const SERVER_BASE = (process.env.GRAMATR_URL || "https://api.gramatr.com").replace(/\/mcp\/?$/, "");
 
-// Accept gmtr_sk_, gmtr_pk_, aios_sk_, aios_pk_ (legacy), and Firebase-style
+// Accept gramatr_sk_, gramatr_pk_, aios_sk_, aios_pk_ (legacy), and Firebase-style
 // long opaque tokens (length >= 32, base64url-ish characters).
-const KEY_FORMAT = /^(gmtr|aios)_(sk|pk)_[A-Za-z0-9_-]+$/;
+const KEY_FORMAT = /^(gramatr|gmtr|aios)_(sk|pk)_[A-Za-z0-9_-]+$/;
 const LEGACY_OPAQUE = /^[A-Za-z0-9_.-]{32,}$/;
 
 function log(msg: string = ""): void {
@@ -63,7 +63,7 @@ function showHelp(): void {
 
 Usage:
   gramatr add-api-key                      Interactive prompt for the key
-  echo "gmtr_sk_..." | gramatr add-api-key Read key from piped stdin
+  echo "gramatr_sk_..." | gramatr add-api-key Read key from piped stdin
   gramatr add-api-key --from-env VAR       Read key from named env variable
   gramatr add-api-key --force              Skip server validation (offline use)
 
@@ -94,7 +94,7 @@ async function readPipedStdin(): Promise<string | null> {
 async function readInteractive(): Promise<string> {
   log("");
   log("Paste your gramatr API key below.");
-  log("(Get one at https://gramatr.com/settings — keys start with gmtr_sk_)");
+  log("(Get one at https://gramatr.com/settings — keys start with gramatr_sk_)");
   log("");
   process.stdout.write("  Key: ");
   const rl = createInterface({ input: process.stdin, output: process.stdout });
@@ -168,7 +168,7 @@ function writeKey(key: string): void {
   }
   existing.token = key;
   existing.token_type =
-    key.startsWith("gmtr_sk_") || key.startsWith("aios_sk_") ? "api_key" : "oauth";
+    key.startsWith("gramatr_sk_") || key.startsWith("aios_sk_") ? "api_key" : "oauth";
   existing.authenticated_at = new Date().toISOString();
   writeFileSync(gmtrJsonPath(), `${JSON.stringify(existing, null, 2)}\n`, "utf8");
   try {
@@ -214,7 +214,7 @@ export async function main(argv: string[] = process.argv.slice(2)): Promise<numb
 
   // Format validation
   if (!validateFormat(key)) {
-    err("ERROR: key format is invalid. Expected gmtr_sk_... or gmtr_pk_...");
+    err("ERROR: key format is invalid. Expected gramatr_sk_... or gramatr_pk_...");
     return 1;
   }
 

package/bin/clean-legacy-install.ts

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

package/bin/clear-creds.ts

@@ -10,7 +10,7 @@
  *   1. ~/.gmtr.json                              — deleted entirely
  *   2. ~/gmtr-client/settings.json `auth.api_key` — stripped, file preserved
  *
- * Env vars (GRAMATR_API_KEY, GMTR_TOKEN) cannot be cleared from a child
+ * 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.
  *
  * Not-logged-in is not an error: exits 0 with a clean message.
@@ -28,7 +28,7 @@ function gmtrJsonPath(): string {
 }
 
 function legacySettingsPath(): string {
-  const gmtrDir = process.env.GMTR_DIR || join(getHome(), "gmtr-client");
+  const gmtrDir = process.env.GRAMATR_DIR || join(getHome(), "gmtr-client");
   return join(gmtrDir, "settings.json");
 }
 
@@ -44,7 +44,7 @@ Usage:
 
 After running, the next install or login will be forced through OAuth.
 
-Env vars (GRAMATR_API_KEY, GMTR_TOKEN) cannot be unset from this process.
+Env vars (GRAMATR_API_KEY, GRAMATR_TOKEN) cannot be unset from this process.
 If they are set, this command warns and tells you the shell command to run.`);
 }
 
@@ -86,7 +86,7 @@ export function clearAll(): ClearResult {
   }
 
   // 3. Env vars — detect only, cannot mutate parent shell
-  for (const v of ["GRAMATR_API_KEY", "GMTR_TOKEN"]) {
+  for (const v of ["GRAMATR_API_KEY", "GRAMATR_TOKEN"]) {
     if (process.env[v]) result.envVarsSet.push(v);
   }
 

package/bin/gmtr-login.ts

@@ -24,7 +24,7 @@ import { createServer, type IncomingMessage, type ServerResponse } from 'http';
 
 const HOME = process.env.HOME || process.env.USERPROFILE || '';
 const CONFIG_PATH = join(HOME, '.gmtr.json');
-const DEFAULT_SERVER = process.env.GMTR_URL || 'https://api.gramatr.com/mcp';
+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\/?$/, '');
 const DASHBOARD_BASE = process.env.GMTR_DASHBOARD_URL || (() => {
@@ -327,7 +327,7 @@ async function loginWithToken(token: string): Promise<void> {
   if (result.valid) {
     const config = readConfig();
     config.token = token;
-    config.token_type = token.startsWith('aios_sk_') || token.startsWith('gmtr_sk_') ? 'api_key' : 'oauth';
+    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');
@@ -539,7 +539,7 @@ export async function main(): Promise<void> {
     if (!token) {
       // Interactive paste mode — like Claude's login
       console.log('\n  Paste your gramatr token below.');
-      console.log('  (API keys start with aios_sk_ or gmtr_sk_)\n');
+      console.log('  (API keys start with aios_sk_ or gramatr_sk_)\n');
       process.stdout.write('  Token: ');
 
       const { createInterface } = await import('readline');

package/bin/gramatr.ts

@@ -205,11 +205,11 @@ function installTarget(targetId: IntegrationTargetId): void {
 
 function migrate(apply: boolean, deep: boolean = false): void {
   const homeDir = homedir();
-  const clientDir = process.env.GMTR_DIR || join(homeDir, 'gmtr-client');
+  const clientDir = process.env.GRAMATR_DIR || join(homeDir, 'gmtr-client');
   runLegacyMigration({
     homeDir,
     clientDir,
-    includeOptionalUx: process.env.GMTR_ENABLE_OPTIONAL_CLAUDE_UX === '1',
+    includeOptionalUx: process.env.GRAMATR_ENABLE_OPTIONAL_CLAUDE_UX === '1',
     apply,
     log,
   });
@@ -220,7 +220,7 @@ function migrate(apply: boolean, deep: boolean = false): void {
 }
 
 function doctor(): void {
-  const gmtrDir = process.env.GMTR_DIR || join(homedir(), 'gmtr-client');
+  const gmtrDir = process.env.GRAMATR_DIR || join(homedir(), 'gmtr-client');
   const stale = findStaleArtifacts(homedir(), gmtrDir, existsSync);
   for (const line of formatDoctorLines(detectTargets(), gmtrDir, existsSync(gmtrDir), stale)) log(line);
   renderRemoteGuidance();
@@ -228,14 +228,14 @@ function doctor(): void {
 
 function upgrade(): void {
   const homeDir = homedir();
-  const clientDir = process.env.GMTR_DIR || join(homeDir, 'gmtr-client');
+  const clientDir = process.env.GRAMATR_DIR || join(homeDir, 'gmtr-client');
   const stale = findStaleArtifacts(homeDir, clientDir, existsSync);
   if (stale.length > 0) {
     log('Cleaning stale legacy artifacts before upgrade...');
     runLegacyMigration({
       homeDir,
       clientDir,
-      includeOptionalUx: process.env.GMTR_ENABLE_OPTIONAL_CLAUDE_UX === '1',
+      includeOptionalUx: process.env.GRAMATR_ENABLE_OPTIONAL_CLAUDE_UX === '1',
       apply: true,
       log,
     });

package/bin/install.ts

@@ -6,7 +6,7 @@
  * Usage:
  *   npx tsx install.ts                # Universal (Node + tsx)
  *   bun install.ts                    # If bun is available
- *   GMTR_TOKEN=xxx npx tsx install.ts # Headless with token
+ *   GRAMATR_TOKEN=xxx npx tsx install.ts # Headless with token
  *   npx tsx install.ts --yes          # Non-interactive (auto-accept defaults)
  */
 
@@ -284,19 +284,43 @@ function installClientFiles(): void {
   copyFileIfExists(join(SCRIPT_DIR, 'bin/render-claude-hooks.ts'), join(CLIENT_DIR, 'bin/render-claude-hooks.ts'), true);
 
   // Bin lib helpers (statusline shim depends on these — see #495)
-  // Copies git.ts, config.ts, stdin.ts and any future helpers without enumerating each file.
+  // Walks the directory but filters out test files / __tests__ subdir so
+  // we don't ship .test.ts to user installs.
   const binLibSrc = join(SCRIPT_DIR, 'bin', 'lib');
   if (existsSync(binLibSrc)) {
-    copyDir(binLibSrc, join(CLIENT_DIR, 'bin', 'lib'));
-    log('OK Installed bin/lib (statusline shim helpers)');
+    mkdirSync(join(CLIENT_DIR, 'bin', 'lib'), { recursive: true });
+    let binLibCount = 0;
+    for (const f of readdirSync(binLibSrc)) {
+      const src = join(binLibSrc, f);
+      if (!statSync(src).isFile()) continue;
+      if (!f.endsWith('.ts')) continue;
+      if (f.endsWith('.test.ts')) continue;
+      copyFileIfExists(src, join(CLIENT_DIR, 'bin', 'lib', f));
+      binLibCount++;
+    }
+    log(`OK Installed bin/lib (${binLibCount} statusline shim helpers)`);
   }
   log('OK Installed bin (statusline, gmtr-login, render-claude-hooks)');
 
-  // Core dependencies (routing.ts required by GMTRPromptEnricher hook)
-  for (const f of ['install.ts', 'version.ts', 'types.ts', 'routing.ts']) {
-    copyFileIfExists(join(SCRIPT_DIR, 'core', f), join(CLIENT_DIR, 'core', f));
+  // Core dependencies — directory walk so new hook deps don't silently break.
+  // Hook imports include: routing.ts (enricher), session.ts (session-start),
+  // version-check.ts (session-start), version.ts (session-start), types.ts (transitive).
+  // Past bugs (#495 bin/lib, this same class repeated): hardcoded file lists drift
+  // when a hook grows a new core import. Walking the directory + filtering tests
+  // makes the installer self-healing.
+  const coreSrc = join(SCRIPT_DIR, 'core');
+  if (existsSync(coreSrc)) {
+    let coreCount = 0;
+    for (const f of readdirSync(coreSrc)) {
+      const src = join(coreSrc, f);
+      if (!statSync(src).isFile()) continue;
+      if (!f.endsWith('.ts')) continue;
+      if (f.endsWith('.test.ts')) continue;
+      copyFileIfExists(src, join(CLIENT_DIR, 'core', f));
+      coreCount++;
+    }
+    log(`OK Installed ${coreCount} core modules`);
   }
-  log('OK Installed core modules');
 
   // package.json — copied so core/version.ts can resolve the installed
   // version at runtime. Single source of truth; see core/version.ts.
@@ -484,15 +508,15 @@ function updateClaudeSettings(url: string, token: string): void {
   cpSync(CLAUDE_SETTINGS, backup);
   log(`OK Backed up settings to ${basename(backup)}`);
 
-  const includeOptionalUx = process.env.GMTR_ENABLE_OPTIONAL_CLAUDE_UX === '1';
+  const includeOptionalUx = process.env.GRAMATR_ENABLE_OPTIONAL_CLAUDE_UX === '1';
   const hooksConfig = buildClaudeHooksFile(CLIENT_DIR, { includeOptionalUx });
 
   const settings = readJson(CLAUDE_SETTINGS);
 
   // Env vars
   settings.env = settings.env || {};
-  settings.env.GMTR_DIR = CLIENT_DIR;
-  settings.env.GMTR_URL = url;
+  settings.env.GRAMATR_DIR = CLIENT_DIR;
+  settings.env.GRAMATR_URL = url;
   settings.env.PATH = `${HOME}/.gmtr/bin:/usr/local/bin:/usr/bin:/bin`;
   if (token) settings.env.AIOS_MCP_TOKEN = token;
 
@@ -515,7 +539,7 @@ function updateClaudeSettings(url: string, token: string): void {
   if (includeOptionalUx) {
     log('OK   Optional Claude UX hooks enabled');
   } else {
-    log('OK   Thin-client hook set (set GMTR_ENABLE_OPTIONAL_CLAUDE_UX=1 for optional hooks)');
+    log('OK   Thin-client hook set (set GRAMATR_ENABLE_OPTIONAL_CLAUDE_UX=1 for optional hooks)');
   }
 
   // Status line
@@ -561,14 +585,14 @@ function registerMcpServer(url: string, token: string): void {
   // Register in ~/.claude.json
   mergeJson(CLAUDE_JSON, (data) => {
     data.env = data.env || {};
-    if (token) data.env.GMTR_TOKEN = token;
+    if (token) data.env.GRAMATR_TOKEN = token;
     delete data.env.AIOS_MCP_TOKEN;
 
     data.mcpServers = data.mcpServers || {};
     data.mcpServers.gramatr = {
       type: 'http',
       url,
-      headers: { Authorization: 'Bearer ${GMTR_TOKEN}' },
+      headers: { Authorization: 'Bearer ${GRAMATR_TOKEN}' },
       autoApprove: true,
     };
     return data;
@@ -594,16 +618,26 @@ function verify(url: string, token: string): boolean {
     }
   };
 
-  // Critical files
+  // Critical files — every runtime hook + bin import target must be present.
+  // If you add a new ../core/X.ts or ./lib/X.ts import in hooks/ or bin/, add the
+  // corresponding entry here so a partial install fails loudly instead of
+  // exploding at hook execution time. The hook-imports-shipped.test.ts
+  // regression guard catches missing entries at PR review.
   for (const f of [
-    'hooks/GMTRToolTracker.hook.ts',
-    'hooks/GMTRPromptEnricher.hook.ts',
-    'hooks/GMTRRatingCapture.hook.ts',
-    'hooks/GMTRSecurityValidator.hook.ts',
+    'hooks/gramatr-tool-tracker.hook.ts',
+    'hooks/gramatr-prompt-enricher.hook.ts',
+    'hooks/gramatr-rating-capture.hook.ts',
+    'hooks/gramatr-security-validator.hook.ts',
     'hooks/lib/notify.ts',
     'core/routing.ts',
+    'core/session.ts',
+    'core/version.ts',
+    'core/version-check.ts',
+    'core/types.ts',
+    'core/install.ts',
     'bin/statusline.ts',
     'bin/gmtr-login.ts',
+    'bin/render-claude-hooks.ts',
     'bin/lib/git.ts',
     'bin/lib/config.ts',
     'bin/lib/stdin.ts',

package/bin/lib/config.ts

@@ -8,8 +8,8 @@
  * so it can be loaded in a 2s shim without touching disk more than once.
  *
  * Resolution:
- *   URL   — GMTR_URL → ~/.gmtr.json.url → https://api.gramatr.com
- *   Token — GMTR_TOKEN → AIOS_MCP_TOKEN → ~/.gmtr.json.token → null
+ *   URL   — GRAMATR_URL → ~/.gmtr.json.url → https://api.gramatr.com
+ *   Token — GRAMATR_TOKEN → AIOS_MCP_TOKEN → ~/.gmtr.json.token → null
  */
 import { existsSync, readFileSync } from 'fs';
 import { homedir } from 'os';
@@ -40,15 +40,15 @@ export function getGramatrConfig(): GramatrConfig {
   const json = readGmtrJson();
 
   const rawUrl =
-    process.env.GMTR_URL ||
+    process.env.GRAMATR_URL ||
     (typeof json?.url === 'string' && json.url) ||
     DEFAULT_URL;
-  // GMTR_URL is conventionally the MCP endpoint (e.g. https://api.gramatr.com/mcp).
+  // GRAMATR_URL is conventionally the MCP endpoint (e.g. https://api.gramatr.com/mcp).
   // REST calls need the API base — strip a trailing /mcp segment.
   const url = (rawUrl as string).replace(/\/mcp\/?$/, '');
 
   const token =
-    process.env.GMTR_TOKEN ||
+    process.env.GRAMATR_TOKEN ||
     process.env.AIOS_MCP_TOKEN ||
     (typeof json?.token === 'string' && json.token) ||
     null;

package/bin/render-claude-hooks.ts

@@ -8,7 +8,7 @@ function main(): void {
     throw new Error('Usage: render-claude-hooks.ts <client-dir>');
   }
 
-  const includeOptionalUx = process.env.GMTR_ENABLE_OPTIONAL_CLAUDE_UX === '1';
+  const includeOptionalUx = process.env.GRAMATR_ENABLE_OPTIONAL_CLAUDE_UX === '1';
   const hooks = buildClaudeHooksFile(clientDir, { includeOptionalUx });
   process.stdout.write(`${JSON.stringify(hooks.hooks, null, 2)}\n`);
 }

package/bin/uninstall.ts

@@ -53,7 +53,7 @@ function removeGramatrFromJson(filePath: string, keys: string[]): boolean {
         delete data[key];
         changed = true;
       }
-      // Handle nested keys like "env.GMTR_TOKEN"
+      // Handle nested keys like "env.GRAMATR_TOKEN"
       if (key.includes('.')) {
         const [parent, child] = key.split('.');
         if (data[parent] && child in data[parent]) {
@@ -194,7 +194,7 @@ async function main(): Promise<void> {
 
   // 5. Remove gramatr from ~/.claude.json (MCP server + env vars)
   if (existsSync(claudeJson)) {
-    const cleaned = removeGramatrFromJson(claudeJson, ['env.GMTR_TOKEN', 'env.AIOS_MCP_TOKEN']);
+    const cleaned = removeGramatrFromJson(claudeJson, ['env.GRAMATR_TOKEN', 'env.AIOS_MCP_TOKEN']);
     if (cleaned) log('  OK Removed gramatr MCP server + env vars from ~/.claude.json');
   }
 

package/chatgpt/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/codex/install.ts

@@ -47,7 +47,7 @@ export function main(): void {
     throw new Error('HOME is not set');
   }
 
-  const gmtrDir = process.env.GMTR_DIR || join(home, 'gmtr-client');
+  const gmtrDir = process.env.GRAMATR_DIR || join(home, 'gmtr-client');
   const codexHome = join(home, '.codex');
   const hooksPath = join(codexHome, 'hooks.json');
   const configPath = join(codexHome, 'config.toml');

package/core/auth.ts

@@ -7,7 +7,7 @@
  *
  * Resolution chain (first non-empty wins):
  *   1. GRAMATR_API_KEY env var
- *   2. GMTR_TOKEN env var (legacy)
+ *   2. GRAMATR_TOKEN env var (legacy)
  *   3. ~/.gmtr.json `token` field
  *   4. ~/gmtr-client/settings.json `auth.api_key` (legacy, skips placeholder)
  *   5. If interactive + TTY: spawn gmtr-login.ts (OAuth)
@@ -48,13 +48,15 @@ function gmtrJsonPath(): string {
 }
 
 function legacySettingsPath(): string {
-  const gmtrDir = process.env.GMTR_DIR || join(getHome(), "gmtr-client");
+  const gmtrDir = process.env.GRAMATR_DIR || join(getHome(), "gmtr-client");
   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(), "gmtr-client"),
     "bin",
     "gmtr-login.ts",
   );

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/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): ');
 
@@ -154,7 +154,7 @@ 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();

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.',
       },
     ],
   };

package/hooks/StopOrchestrator.hook.ts

@@ -36,7 +36,7 @@ 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 {
@@ -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;
@@ -342,7 +342,7 @@ export function createDefaultConfig(options: {
  *
  * Priority:
  *   1. ~/.gmtr.json (canonical, gramatr-owned, vendor-agnostic)
- *   2. GMTR_TOKEN env var (CI, headless override)
+ *   2. GRAMATR_TOKEN env var (CI, headless override)
  *   3. ~/gmtr-client/settings.json auth.api_key (legacy, will be migrated)
  *
  * Token is NEVER stored in ~/.claude.json, ~/.codex/, or ~/.gemini/.
@@ -357,15 +357,15 @@ export function resolveAuthToken(): string | null {
     // 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)
   try {
-    const gmtrDir = process.env.GMTR_DIR || join(HOME, 'gmtr-client');
+    const gmtrDir = process.env.GRAMATR_DIR || join(HOME, 'gmtr-client');
     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: ~/gmtr-client/settings.json > GRAMATR_URL env > ~/.claude.json > default
  */
 export function resolveMcpUrl(): string {
   // 1. ~/gmtr-client/settings.json (canonical, vendor-agnostic)
   try {
-    const gmtrDir = process.env.GMTR_DIR || join(HOME, 'gmtr-client');
+    const gmtrDir = process.env.GRAMATR_DIR || join(HOME, 'gmtr-client');
     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, 'gmtr-client');
+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)

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 (~/gmtr-client), 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 || '', 'gmtr-client'), '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.1",
+  "version": "0.6.0",
   "publishConfig": {
     "access": "public"
   },