@empirical-gauzza/cli 1.0.25 → 1.0.27

package/README.md

@@ -1,63 +1,63 @@
-# @empirical-gauzza/cli
-
-Command-line installer and local MCP wiring helper for [Empirical](https://empirical.gauzza.com) — portable memory infrastructure for AI agents, assistants, and coding tools.
-
-Full documentation: **[empirical.gauzza.com/docs/cli-details](https://empirical.gauzza.com/docs/cli-details)**
-
-## Install
-
-```bash
-npm install -g @empirical-gauzza/cli
-```
-
-## Quick start
-
-```bash
-empirical install       # interactive setup for Claude Code, Codex, or Copilot CLI
-empirical auth login    # browser-based OAuth login
-empirical doctor        # verify token, API connectivity, and workspace status
-```
-
-Full walkthrough: [empirical.gauzza.com/docs/install](https://empirical.gauzza.com/docs/install)
-
-## What it does
-
-- Installs and configures the Empirical MCP plugin for supported coding agents (Claude Code, Codex CLI, Copilot CLI)
-- Manages OAuth login, including headless/CI bootstrap and Docker token flows
-- Reads, writes, and maintains memories from the command line
-- Manages Skills Kits — create, sync, and push authored Skills across machines
-- Manages workspaces, invites, and registered devices
-- Exposes agent-readable docs and a connectivity `doctor` check
-
-## Commands
-
-| Command | Docs |
-| --- | --- |
-| `empirical install` | [/docs/install](https://empirical.gauzza.com/docs/install#connect) |
-| `empirical plugin install / check` | [/docs/cli-plugins](https://empirical.gauzza.com/docs/cli-plugins) |
-| `empirical auth login / logout` | [/docs/cli-auth](https://empirical.gauzza.com/docs/cli-auth) |
-| `empirical oauth bootstrap / refresh` | [/docs/cli-oauth](https://empirical.gauzza.com/docs/cli-oauth) |
-| `empirical policy show / set` | [/docs/cli-policy](https://empirical.gauzza.com/docs/cli-policy) |
-| `empirical memory query / record / update / delete / export ...` | [/docs/cli-memory](https://empirical.gauzza.com/docs/cli-memory) |
-| `empirical workspace list / create / invite ...` | [/docs/cli-workspaces](https://empirical.gauzza.com/docs/cli-workspaces) |
-| `empirical kit create / sync / use ...` | [/docs/cli-kit](https://empirical.gauzza.com/docs/cli-kit) |
-| `empirical skill push / history / rollback` | [/docs/cli-skill](https://empirical.gauzza.com/docs/cli-skill) |
-| `empirical device list / show` | [/docs/cli-devices](https://empirical.gauzza.com/docs/cli-devices) |
-| `empirical doc [topic]` | [/docs/cli-doc-command](https://empirical.gauzza.com/docs/cli-doc-command) |
-| `empirical doctor` | [/docs/cli-doctor](https://empirical.gauzza.com/docs/cli-doctor) |
-
-Run `empirical --help` at any time for the full, current command list, or `empirical doc` for agent-readable topic docs.
-
-## Security model
-
-API keys and OAuth tokens are stored locally and are never printed in full after initial issuance. See [empirical.gauzza.com/docs/security-model](https://empirical.gauzza.com/docs/security-model) for details on credential handling and headless/CI usage.
-
-## Links
-
-- [Documentation](https://empirical.gauzza.com/docs/install)
-- [Homepage](https://empirical.gauzza.com)
-- [Support](https://empirical.gauzza.com/support/)
-
-## License
-
-MIT
+# @empirical-gauzza/cli
+
+Command-line installer and local MCP wiring helper for [Empirical](https://empirical.gauzza.com) — portable memory infrastructure for AI agents, assistants, and coding tools.
+
+Full documentation: **[empirical.gauzza.com/docs/cli-details](https://empirical.gauzza.com/docs/cli-details)**
+
+## Install
+
+```bash
+npm install -g @empirical-gauzza/cli
+```
+
+## Quick start
+
+```bash
+empirical install       # interactive setup for Claude Code, Codex, or Copilot CLI
+empirical auth login    # browser-based OAuth login
+empirical doctor        # verify token, API connectivity, and workspace status
+```
+
+Full walkthrough: [empirical.gauzza.com/docs/install](https://empirical.gauzza.com/docs/install)
+
+## What it does
+
+- Installs and configures the Empirical MCP plugin for supported coding agents (Claude Code, Codex CLI, Copilot CLI)
+- Manages OAuth login, including headless/CI bootstrap and Docker token flows
+- Reads, writes, and maintains memories from the command line
+- Manages Skills Kits — create, sync, and push authored Skills across machines
+- Manages workspaces, invites, and registered devices
+- Exposes agent-readable docs and a connectivity `doctor` check
+
+## Commands
+
+| Command | Docs |
+| --- | --- |
+| `empirical install` | [/docs/install](https://empirical.gauzza.com/docs/install#connect) |
+| `empirical plugin install / check` | [/docs/cli-plugins](https://empirical.gauzza.com/docs/cli-plugins) |
+| `empirical auth login / logout` | [/docs/cli-auth](https://empirical.gauzza.com/docs/cli-auth) |
+| `empirical oauth bootstrap / refresh` | [/docs/cli-oauth](https://empirical.gauzza.com/docs/cli-oauth) |
+| `empirical policy show / set` | [/docs/cli-policy](https://empirical.gauzza.com/docs/cli-policy) |
+| `empirical memory query / record / update / delete / export ...` | [/docs/cli-memory](https://empirical.gauzza.com/docs/cli-memory) |
+| `empirical workspace list / create / invite ...` | [/docs/cli-workspaces](https://empirical.gauzza.com/docs/cli-workspaces) |
+| `empirical kit create / sync / use ...` | [/docs/cli-kit](https://empirical.gauzza.com/docs/cli-kit) |
+| `empirical skill push / history / rollback` | [/docs/cli-skill](https://empirical.gauzza.com/docs/cli-skill) |
+| `empirical device list / show` | [/docs/cli-devices](https://empirical.gauzza.com/docs/cli-devices) |
+| `empirical doc [topic]` | [/docs/cli-doc-command](https://empirical.gauzza.com/docs/cli-doc-command) |
+| `empirical doctor` | [/docs/cli-doctor](https://empirical.gauzza.com/docs/cli-doctor) |
+
+Run `empirical --help` at any time for the full, current command list, or `empirical doc` for agent-readable topic docs.
+
+## Security model
+
+API keys and OAuth tokens are stored locally and are never printed in full after initial issuance. See [empirical.gauzza.com/docs/security-model](https://empirical.gauzza.com/docs/security-model) for details on credential handling and headless/CI usage.
+
+## Links
+
+- [Documentation](https://empirical.gauzza.com/docs/install)
+- [Homepage](https://empirical.gauzza.com)
+- [Support](https://empirical.gauzza.com/support/)
+
+## License
+
+MIT

package/lib/constants.js

@@ -58,7 +58,12 @@ Flags:
 ### record
 Save a new memory.
 
-    empirical memory record --category build --summary "Use ESM modules for all new packages" [--tags ts,node] [--node-type observation]
+    empirical memory record --category build --summary "Use ESM modules for all new packages" [--tags ts,node] [--node-type observation] [--author-type user|agent]
+
+\`--author-type\` records WHO the fact belongs to, which the transport cannot know. Use
+\`user\` for something the user said, decided or prefers; \`agent\` for your own session notes
+and findings. Omitted, it is left unresolved rather than guessed. Retrieval reads it to keep
+agent notes out of answers about the user's own life and work.
 
 Passing text that contains code (backticks, \${...}, $(...)): do NOT put it in a double-quoted
 \`--summary "..."\` -- the shell substitutes those away before the CLI runs and the write still

package/lib/doc.js

@@ -11,7 +11,7 @@ function runDoc(args) {
     user: 'Get current user identity (MCP: get_user; CLI: doctor --output json)',
     workspace: 'List, view, and switch workspaces',
     doctor: 'Check token, connectivity, and workspace health',
-    agents: 'Supported agents, integration modes, and native plugin setup',
+    agents: 'Supported agents, integration modes, and native plugin setup',
     auth: 'Token types, bootstrap, refresh, resolution order',
     install: 'Install Empirical for Codex / Copilot / Claude Code',
     kit: 'Create, source, activate, and sync Skills Kits',

package/lib/env.js

@@ -1,49 +1,49 @@
-'use strict';
-
-const { ask } = require('./ui');
-
-function getEnv(name, fallback = '') {
-  return String(process.env[name] ?? fallback).trim();
-}
-
-function requireEnv(name) {
-  const value = getEnv(name);
-  if (!value) {
-    throw new Error(`Missing required env var: ${name}`);
-  }
-  return value;
-}
-
-async function resolveRequiredValueFromEnvOrPrompt(envName, promptLabel) {
-  const value = getEnv(envName);
-  if (value) return value;
-
-  if (!process.stdin.isTTY) {
-    throw new Error(`Missing required env var: ${envName}`);
-  }
-
-  const answer = (await ask(`${promptLabel}: `)).trim();
-  if (!answer) {
-    throw new Error(`${promptLabel} is required`);
-  }
-
-  return answer;
-}
-
-function parseFlag(args, flagName) {
-  return args.includes(flagName);
-}
-
-function parseOption(args, optionName, fallback = '') {
-  const index = args.indexOf(optionName);
-  if (index === -1) return fallback;
-  return String(args[index + 1] || '').trim() || fallback;
-}
-
-module.exports = {
-  getEnv,
-  requireEnv,
-  resolveRequiredValueFromEnvOrPrompt,
-  parseFlag,
-  parseOption
-};
+'use strict';
+
+const { ask } = require('./ui');
+
+function getEnv(name, fallback = '') {
+  return String(process.env[name] ?? fallback).trim();
+}
+
+function requireEnv(name) {
+  const value = getEnv(name);
+  if (!value) {
+    throw new Error(`Missing required env var: ${name}`);
+  }
+  return value;
+}
+
+async function resolveRequiredValueFromEnvOrPrompt(envName, promptLabel) {
+  const value = getEnv(envName);
+  if (value) return value;
+
+  if (!process.stdin.isTTY) {
+    throw new Error(`Missing required env var: ${envName}`);
+  }
+
+  const answer = (await ask(`${promptLabel}: `)).trim();
+  if (!answer) {
+    throw new Error(`${promptLabel} is required`);
+  }
+
+  return answer;
+}
+
+function parseFlag(args, flagName) {
+  return args.includes(flagName);
+}
+
+function parseOption(args, optionName, fallback = '') {
+  const index = args.indexOf(optionName);
+  if (index === -1) return fallback;
+  return String(args[index + 1] || '').trim() || fallback;
+}
+
+module.exports = {
+  getEnv,
+  requireEnv,
+  resolveRequiredValueFromEnvOrPrompt,
+  parseFlag,
+  parseOption
+};

package/lib/http.js

@@ -1,179 +1,187 @@
-'use strict';
-
-const http = require('http');
-const https = require('https');
-const { warn } = require('./ui');
-
-function httpGet(urlString, timeoutMs = 8000) {
-  return new Promise((resolve, reject) => {
-    const parsed = new URL(urlString);
-    const lib = parsed.protocol === 'https:' ? https : http;
-    const req = lib.request(
-      parsed,
-      {
-        method: 'GET',
-        headers: {
-          'User-Agent': 'empirical-installer/1.0'
-        }
-      },
-      (res) => {
-        let body = '';
-        res.setEncoding('utf8');
-        res.on('data', (chunk) => {
-          body += chunk;
-        });
-        res.on('end', () => {
-          resolve({
-            statusCode: res.statusCode || 0,
-            headers: res.headers || {},
-            body
-          });
-        });
-      }
-    );
-
-    req.setTimeout(timeoutMs, () => {
-      req.destroy(new Error('request timeout'));
-    });
-    req.on('error', reject);
-    req.end();
-  });
-}
-
-function httpErrorFromResponse(method, urlString, statusCode, data) {
-  const baseMsg = data.error_description || data.message || data.error || `HTTP ${statusCode}`;
-  const upgradeUrl = data.upgrade_url || data.details?.upgradeUrl || null;
-  const retryAfterSeconds = data.retry_after_seconds ?? null;
-
-  const parts = [`${method} ${urlString} failed: ${baseMsg}`];
-  if (retryAfterSeconds != null) parts.push(`Retry after ${retryAfterSeconds}s.`);
-  if (upgradeUrl) parts.push(`Upgrade: ${upgradeUrl}`);
-
-  const error = new Error(parts.join(' '));
-  error.statusCode = statusCode;
-  error.code = data.code || null;
-  error.upgradeUrl = upgradeUrl;
-  error.retryAfterSeconds = retryAfterSeconds;
-  return error;
-}
-
-// Prints a structured JSON error line to stderr so scripts/agents parsing CLI
-// output can branch on `code` (e.g. RATE_LIMITED, PLAN_LIMIT_MEMORY_REACHED)
-// and act on `upgradeUrl`/`retryAfterSeconds` without string-parsing `message`.
-function printApiError(error) {
-  warn(JSON.stringify({
-    error: true,
-    code: error.code || 'api_error',
-    message: error.message,
-    ...(error.retryAfterSeconds != null && { retryAfterSeconds: error.retryAfterSeconds }),
-    ...(error.upgradeUrl && { upgradeUrl: error.upgradeUrl })
-  }));
-}
-
-function httpJson(urlString, method, payload, headers = {}, timeoutMs = 0) {
-  return new Promise((resolve, reject) => {
-    const parsed = new URL(urlString);
-    const lib = parsed.protocol === 'https:' ? https : http;
-    const body = payload ? JSON.stringify(payload) : null;
-
-    const req = lib.request(
-      parsed,
-      {
-        method,
-        headers: {
-          Accept: 'application/json',
-          ...(body ? { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(body) } : {}),
-          ...headers
-        }
-      },
-      (res) => {
-        let raw = '';
-        res.setEncoding('utf8');
-        res.on('data', (chunk) => {
-          raw += chunk;
-        });
-        res.on('end', () => {
-          let data = {};
-          try {
-            data = raw ? JSON.parse(raw) : {};
-          } catch (_error) {
-            data = { raw };
-          }
-
-          const statusCode = res.statusCode || 0;
-          if (statusCode < 200 || statusCode >= 300) {
-            reject(httpErrorFromResponse(method, urlString, statusCode, data));
-            return;
-          }
-
-          resolve(data);
-        });
-      }
-    );
-
-    req.on('error', reject);
-    if (Number.isFinite(timeoutMs) && timeoutMs > 0) {
-      req.setTimeout(timeoutMs, () => {
-        req.destroy(new Error(`request timeout after ${timeoutMs}ms`));
-      });
-    }
-    if (body) req.write(body);
-    req.end();
-  });
-}
-
-function httpForm(urlString, method, params, headers = {}) {
-  return new Promise((resolve, reject) => {
-    const parsed = new URL(urlString);
-    const lib = parsed.protocol === 'https:' ? https : http;
-    const body = new URLSearchParams(params).toString();
-
-    const req = lib.request(
-      parsed,
-      {
-        method,
-        headers: {
-          Accept: 'application/json',
-          'Content-Type': 'application/x-www-form-urlencoded',
-          'Content-Length': Buffer.byteLength(body),
-          ...headers
-        }
-      },
-      (res) => {
-        let raw = '';
-        res.setEncoding('utf8');
-        res.on('data', (chunk) => {
-          raw += chunk;
-        });
-        res.on('end', () => {
-          let data = {};
-          try {
-            data = raw ? JSON.parse(raw) : {};
-          } catch (_error) {
-            data = { raw };
-          }
-
-          const statusCode = res.statusCode || 0;
-          if (statusCode < 200 || statusCode >= 300) {
-            reject(httpErrorFromResponse(method, urlString, statusCode, data));
-            return;
-          }
-
-          resolve(data);
-        });
-      }
-    );
-
-    req.on('error', reject);
-    req.write(body);
-    req.end();
-  });
-}
-
-module.exports = {
-  httpGet,
-  httpErrorFromResponse,
-  printApiError,
-  httpJson,
-  httpForm
-};
+'use strict';
+
+const http = require('http');
+const https = require('https');
+const { warn } = require('./ui');
+
+function httpGet(urlString, timeoutMs = 8000) {
+  return new Promise((resolve, reject) => {
+    const parsed = new URL(urlString);
+    const lib = parsed.protocol === 'https:' ? https : http;
+    const req = lib.request(
+      parsed,
+      {
+        method: 'GET',
+        headers: {
+          'User-Agent': 'empirical-cli/1.0'
+        }
+      },
+      (res) => {
+        let body = '';
+        res.setEncoding('utf8');
+        res.on('data', (chunk) => {
+          body += chunk;
+        });
+        res.on('end', () => {
+          resolve({
+            statusCode: res.statusCode || 0,
+            headers: res.headers || {},
+            body
+          });
+        });
+      }
+    );
+
+    req.setTimeout(timeoutMs, () => {
+      req.destroy(new Error('request timeout'));
+    });
+    req.on('error', reject);
+    req.end();
+  });
+}
+
+function httpErrorFromResponse(method, urlString, statusCode, data) {
+  const baseMsg = data.error_description || data.message || data.error || `HTTP ${statusCode}`;
+  const upgradeUrl = data.upgrade_url || data.details?.upgradeUrl || null;
+  const retryAfterSeconds = data.retry_after_seconds ?? null;
+
+  const parts = [`${method} ${urlString} failed: ${baseMsg}`];
+  if (retryAfterSeconds != null) parts.push(`Retry after ${retryAfterSeconds}s.`);
+  if (upgradeUrl) parts.push(`Upgrade: ${upgradeUrl}`);
+
+  const error = new Error(parts.join(' '));
+  error.statusCode = statusCode;
+  error.code = data.code || null;
+  error.upgradeUrl = upgradeUrl;
+  error.retryAfterSeconds = retryAfterSeconds;
+  return error;
+}
+
+// Prints a structured JSON error line to stderr so scripts/agents parsing CLI
+// output can branch on `code` (e.g. RATE_LIMITED, PLAN_LIMIT_MEMORY_REACHED)
+// and act on `upgradeUrl`/`retryAfterSeconds` without string-parsing `message`.
+function printApiError(error) {
+  warn(JSON.stringify({
+    error: true,
+    code: error.code || 'api_error',
+    message: error.message,
+    ...(error.retryAfterSeconds != null && { retryAfterSeconds: error.retryAfterSeconds }),
+    ...(error.upgradeUrl && { upgradeUrl: error.upgradeUrl })
+  }));
+}
+
+function httpJson(urlString, method, payload, headers = {}, timeoutMs = 0) {
+  return new Promise((resolve, reject) => {
+    const parsed = new URL(urlString);
+    const lib = parsed.protocol === 'https:' ? https : http;
+    const body = payload ? JSON.stringify(payload) : null;
+
+    const req = lib.request(
+      parsed,
+      {
+        method,
+        headers: {
+          Accept: 'application/json',
+          // Identifies the client so the server can tell a CLI write from a portal write
+          // (services/memoryAuthorship.ts). Writes also send source: 'cli' in the body,
+          // which is authoritative; this covers every other endpoint.
+          'User-Agent': 'empirical-cli/1.0',
+          ...(body ? { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(body) } : {}),
+          ...headers
+        }
+      },
+      (res) => {
+        let raw = '';
+        res.setEncoding('utf8');
+        res.on('data', (chunk) => {
+          raw += chunk;
+        });
+        res.on('end', () => {
+          let data = {};
+          try {
+            data = raw ? JSON.parse(raw) : {};
+          } catch (_error) {
+            data = { raw };
+          }
+
+          const statusCode = res.statusCode || 0;
+          if (statusCode < 200 || statusCode >= 300) {
+            reject(httpErrorFromResponse(method, urlString, statusCode, data));
+            return;
+          }
+
+          resolve(data);
+        });
+      }
+    );
+
+    req.on('error', reject);
+    if (Number.isFinite(timeoutMs) && timeoutMs > 0) {
+      req.setTimeout(timeoutMs, () => {
+        req.destroy(new Error(`request timeout after ${timeoutMs}ms`));
+      });
+    }
+    if (body) req.write(body);
+    req.end();
+  });
+}
+
+function httpForm(urlString, method, params, headers = {}) {
+  return new Promise((resolve, reject) => {
+    const parsed = new URL(urlString);
+    const lib = parsed.protocol === 'https:' ? https : http;
+    const body = new URLSearchParams(params).toString();
+
+    const req = lib.request(
+      parsed,
+      {
+        method,
+        headers: {
+          Accept: 'application/json',
+          // Identifies the client so the server can tell a CLI write from a portal write
+          // (services/memoryAuthorship.ts). Writes also send source: 'cli' in the body,
+          // which is authoritative; this covers every other endpoint.
+          'User-Agent': 'empirical-cli/1.0',
+          'Content-Type': 'application/x-www-form-urlencoded',
+          'Content-Length': Buffer.byteLength(body),
+          ...headers
+        }
+      },
+      (res) => {
+        let raw = '';
+        res.setEncoding('utf8');
+        res.on('data', (chunk) => {
+          raw += chunk;
+        });
+        res.on('end', () => {
+          let data = {};
+          try {
+            data = raw ? JSON.parse(raw) : {};
+          } catch (_error) {
+            data = { raw };
+          }
+
+          const statusCode = res.statusCode || 0;
+          if (statusCode < 200 || statusCode >= 300) {
+            reject(httpErrorFromResponse(method, urlString, statusCode, data));
+            return;
+          }
+
+          resolve(data);
+        });
+      }
+    );
+
+    req.on('error', reject);
+    req.write(body);
+    req.end();
+  });
+}
+
+module.exports = {
+  httpGet,
+  httpErrorFromResponse,
+  printApiError,
+  httpJson,
+  httpForm
+};

package/lib/installers/coreMemoryBlock.js

@@ -51,6 +51,11 @@ picking up previously completed work), query Empirical first - do not assume you
 enough context. After completing meaningful work, or discovering a mistake worth not repeating,
 record it in Empirical, not in a local file.
 
+When you record, say who authored the fact: \`authorType: "user"\` for something the user said,
+decided or prefers, \`"agent"\` for your own work and findings. Nothing infers this - not the
+transport, not the client - so an omitted value stays unknown forever, and a wrong one puts your
+session notes into answers about the user's own life.
+
 Installed Empirical skills in this environment:
 ${skillLines}