@hasna/contacts 0.7.0 → 0.9.0

package/dist/cli/index.js

@@ -47,7 +47,7 @@ var __export = (target, all) => {
 var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
 var __require = import.meta.require;
 
-// ../../node_modules/.bun/commander@13.1.0/node_modules/commander/lib/error.js
+// node_modules/commander/lib/error.js
 var require_error = __commonJS((exports) => {
   class CommanderError extends Error {
     constructor(exitCode, code, message) {
@@ -71,7 +71,7 @@ var require_error = __commonJS((exports) => {
   exports.InvalidArgumentError = InvalidArgumentError;
 });
 
-// ../../node_modules/.bun/commander@13.1.0/node_modules/commander/lib/argument.js
+// node_modules/commander/lib/argument.js
 var require_argument = __commonJS((exports) => {
   var { InvalidArgumentError } = require_error();
 
@@ -150,7 +150,7 @@ var require_argument = __commonJS((exports) => {
   exports.humanReadableArgName = humanReadableArgName;
 });
 
-// ../../node_modules/.bun/commander@13.1.0/node_modules/commander/lib/help.js
+// node_modules/commander/lib/help.js
 var require_help = __commonJS((exports) => {
   var { humanReadableArgName } = require_argument();
 
@@ -500,7 +500,7 @@ ${itemIndentStr}`);
   exports.stripColor = stripColor;
 });
 
-// ../../node_modules/.bun/commander@13.1.0/node_modules/commander/lib/option.js
+// node_modules/commander/lib/option.js
 var require_option = __commonJS((exports) => {
   var { InvalidArgumentError } = require_error();
 
@@ -678,7 +678,7 @@ var require_option = __commonJS((exports) => {
   exports.DualOptions = DualOptions;
 });
 
-// ../../node_modules/.bun/commander@13.1.0/node_modules/commander/lib/suggestSimilar.js
+// node_modules/commander/lib/suggestSimilar.js
 var require_suggestSimilar = __commonJS((exports) => {
   var maxDistance = 3;
   function editDistance(a, b) {
@@ -751,7 +751,7 @@ var require_suggestSimilar = __commonJS((exports) => {
   exports.suggestSimilar = suggestSimilar;
 });
 
-// ../../node_modules/.bun/commander@13.1.0/node_modules/commander/lib/command.js
+// node_modules/commander/lib/command.js
 var require_command = __commonJS((exports) => {
   var EventEmitter = __require("events").EventEmitter;
   var childProcess = __require("child_process");
@@ -1290,8 +1290,8 @@ Expecting one of '${allowedValues.join("', '")}'`);
       args = args.slice();
       let launchWithNode = false;
       const sourceExt = [".js", ".ts", ".tsx", ".mjs", ".cjs"];
-      function findFile(baseDir, baseName) {
-        const localBin = path.resolve(baseDir, baseName);
+      function findFile(baseDir2, baseName) {
+        const localBin = path.resolve(baseDir2, baseName);
         if (fs.existsSync(localBin))
           return localBin;
         if (sourceExt.includes(path.extname(baseName)))
@@ -2061,7 +2061,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
   exports.useColor = useColor;
 });
 
-// ../../node_modules/.bun/commander@13.1.0/node_modules/commander/index.js
+// node_modules/commander/index.js
 var require_commander = __commonJS((exports) => {
   var { Argument } = require_argument();
   var { Command } = require_command();
@@ -2182,7 +2182,7 @@ Only include fields that are actually visible in the document. Return valid JSON
 }
 var init_document_scanner = () => {};
 
-// ../events/dist/commander.js
+// node_modules/@hasna/events/dist/commander.js
 var exports_commander = {};
 __export(exports_commander, {
   registerEventsCommands: () => registerEventsCommands,
@@ -2193,12 +2193,12 @@ __export(exports_commander, {
 import { chmod, mkdir, readFile, rename, writeFile } from "fs/promises";
 import { Buffer as Buffer2 } from "buffer";
 import { existsSync as existsSync2 } from "fs";
-import { join as join2 } from "path";
+import { join as join3 } from "path";
 import { existsSync } from "fs";
+import { homedir as homedir2 } from "os";
+import { join as join2, resolve } from "path";
 import { homedir } from "os";
-import { join, resolve } from "path";
-import { homedir as pathsResolverHomedir } from "os";
-import { join as pathsResolverJoin } from "path";
+import { join } from "path";
 import { createHmac, timingSafeEqual } from "crypto";
 import { lookup as dnsLookup } from "dns/promises";
 import { isIP } from "net";
@@ -2302,72 +2302,75 @@ function channelMatchesEvent(channel, event) {
     return true;
   return channel.filters.some((filter) => eventMatchesFilter(event, filter));
 }
-var PATHS_RESOLVER_KIND_ENV = {
+var KIND_ENV = {
   config: "HASNA_CONFIG_HOME",
   data: "HASNA_DATA_HOME",
   state: "HASNA_STATE_HOME",
   cache: "HASNA_CACHE_HOME"
 };
-var PATHS_RESOLVER_APP_SLUG_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
-function pathsResolverAssertApp(app) {
+var APP_SLUG_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+function assertApp(app) {
   if (typeof app !== "string" || app.length === 0) {
     throw new TypeError("paths: app must be a non-empty string");
   }
-  if (!PATHS_RESOLVER_APP_SLUG_RE.test(app)) {
+  if (!APP_SLUG_RE.test(app)) {
     throw new TypeError(`paths: invalid app slug "${app}" \u2014 expected lowercase kebab-case ([a-z0-9]+(-[a-z0-9]+)*)`);
   }
 }
-function pathsResolverAssertKind(kind) {
-  if (!Object.keys(PATHS_RESOLVER_KIND_ENV).includes(kind)) {
-    throw new TypeError(`paths: invalid path kind "${kind}" \u2014 expected one of ${Object.keys(PATHS_RESOLVER_KIND_ENV).join(", ")}`);
-  }
+function envOf(options) {
+  return options.env ?? process.env;
 }
-function pathsResolverBaseDir(kind, options) {
-  pathsResolverAssertKind(kind);
-  const env = options.env ?? process.env;
-  const override = env[PATHS_RESOLVER_KIND_ENV[kind]];
-  if (typeof override === "string" && override.length > 0)
+function envValue(options, kind) {
+  const value = envOf(options)[KIND_ENV[kind]];
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+function isMacOS(platform) {
+  return platform === "darwin";
+}
+function baseDir(kind, options) {
+  const override = envValue(options, kind);
+  if (override)
     return override;
-  const home = options.home ?? pathsResolverHomedir();
+  const home = options.home ?? homedir();
   const platform = options.platform ?? process.platform;
-  if (platform === "darwin") {
+  if (isMacOS(platform)) {
     switch (kind) {
       case "config":
       case "data":
-        return pathsResolverJoin(home, "Library", "Application Support", "Hasna");
+        return join(home, "Library", "Application Support", "Hasna");
       case "cache":
-        return pathsResolverJoin(home, "Library", "Caches", "Hasna");
+        return join(home, "Library", "Caches", "Hasna");
       case "state":
-        return pathsResolverJoin(home, "Library", "Logs", "Hasna");
+        return join(home, "Library", "Logs", "Hasna");
     }
   }
   switch (kind) {
     case "config":
-      return pathsResolverJoin(home, ".config", "hasna");
+      return join(home, ".config", "hasna");
     case "data":
-      return pathsResolverJoin(home, ".local", "share", "hasna");
+      return join(home, ".local", "share", "hasna");
     case "state":
-      return pathsResolverJoin(home, ".local", "state", "hasna");
+      return join(home, ".local", "state", "hasna");
     case "cache":
-      return pathsResolverJoin(home, ".cache", "hasna");
+      return join(home, ".cache", "hasna");
   }
 }
-function pathsResolverResolve(kind, options) {
-  pathsResolverAssertApp(options.app);
-  const appSegment = options.internal === true ? pathsResolverJoin("internal", options.app) : options.app;
-  return pathsResolverJoin(pathsResolverBaseDir(kind, options), appSegment);
+function resolvePath(kind, options) {
+  assertApp(options.app);
+  const appSegment = options.internal === true ? join("internal", options.app) : options.app;
+  return join(baseDir(kind, options), appSegment);
 }
 function dataDir(options) {
-  return pathsResolverResolve("data", options);
+  return resolvePath("data", options);
 }
 var HASNA_EVENTS_DIR_ENV = "HASNA_EVENTS_DIR";
 var HASNA_EVENTS_HOME_ENV = "HASNA_EVENTS_HOME";
 var EVENTS_STORE_SENTINEL_FILE = "events.json";
 function effectiveHome() {
-  return process.env["HOME"] || process.env["USERPROFILE"] || homedir();
+  return process.env["HOME"] || process.env["USERPROFILE"] || homedir2();
 }
 function legacyHomeDir() {
-  return join(effectiveHome(), ".hasna", "events");
+  return join2(effectiveHome(), ".hasna", "events");
 }
 function resolverHome() {
   return dataDir({ app: "events", home: effectiveHome() || undefined });
@@ -2376,7 +2379,7 @@ function adoptResolverHome(resolved, env = process.env) {
   const dataOverride = env.HASNA_DATA_HOME;
   if (typeof dataOverride === "string" && dataOverride.trim().length > 0)
     return true;
-  return existsSync(join(resolved, EVENTS_STORE_SENTINEL_FILE));
+  return existsSync(join2(resolved, EVENTS_STORE_SENTINEL_FILE));
 }
 function exactEventsHome() {
   const dir = process.env[HASNA_EVENTS_DIR_ENV];
@@ -2417,9 +2420,9 @@ class JsonEventsStore {
   constructor(dataDir2 = getEventsDataDir()) {
     this.dataDir = dataDir2;
     this.runtime = localJsonRuntime(dataDir2);
-    this.channelsPath = join2(dataDir2, "channels.json");
-    this.eventsPath = join2(dataDir2, "events.json");
-    this.deliveriesPath = join2(dataDir2, "deliveries.json");
+    this.channelsPath = join3(dataDir2, "channels.json");
+    this.eventsPath = join3(dataDir2, "events.json");
+    this.deliveriesPath = join3(dataDir2, "deliveries.json");
   }
   async init() {
     await mkdir(this.dataDir, { recursive: true, mode: 448 });
@@ -2687,7 +2690,7 @@ async function getEventsStatus(dataDir2) {
   };
 }
 function statusFile(dataDir2, fileName, records) {
-  const path = join2(dataDir2, fileName);
+  const path = join3(dataDir2, fileName);
   return { path, exists: existsSync2(path), records };
 }
 var DEFAULT_SIGNATURE_TOLERANCE_MS = 5 * 60 * 1000;
@@ -3816,7 +3819,7 @@ function replaySummary(events, deliveries, nextCursor) {
   return `Replayed ${events} event(s), ${deliveries} delivery result(s)${suffix}`;
 }
 
-// ../../node_modules/.bun/commander@13.1.0/node_modules/commander/esm.mjs
+// node_modules/commander/esm.mjs
 var import__ = __toESM(require_commander(), 1);
 var {
   program,
@@ -3840,6 +3843,7 @@ import chalk2 from "chalk";
 
 // src/cloud/http-storage.ts
 import {
+  ClientTransportConfigurationError,
   createHasnaHttpTransport,
   resolveCredential,
   resolveClientTransport as resolveSharedClientTransport
@@ -3929,6 +3933,27 @@ function assertConfigurationUnchanged(env, expected) {
     invalid();
 }
 
+// src/cloud/resolver-inputs.ts
+import {
+  clientTransportEnvKeys as clientTransportEnvKeys2,
+  credentialOverrideEnvKey,
+  credentialPointerEnvKey,
+  CREDENTIAL_PROFILE_ENV_KEY
+} from "@hasna/contracts/client";
+var CONTRACTS_AMBIENT_ENVIRONMENT = Symbol.for("hasna:contracts:ambientClientEnvironment");
+function isAmbientContactsEnv(env) {
+  if (typeof process !== "undefined" && env === process.env)
+    return true;
+  return env[CONTRACTS_AMBIENT_ENVIRONMENT] === true;
+}
+function contactsResolverCredentials(env, credentials = {}) {
+  const keychain = { ...credentials.keychain };
+  if (keychain.enabled === undefined && keychain.run === undefined) {
+    keychain.enabled = isAmbientContactsEnv(env);
+  }
+  return { ...credentials, keychain };
+}
+
 // src/cloud/http-storage.ts
 var RETIRED_CLIENT_SELECTOR_KEYS = [
   "HASNA_CONTACTS_STORAGE_MODE",
@@ -3964,37 +3989,44 @@ class ContactsClientConfigurationError extends Error {
     this.name = "ContactsClientConfigurationError";
   }
 }
-function unconfiguredResolution(resolution, issue) {
+function unconfiguredResolution(issue, resolution, warning = null) {
   return {
     transport: "unconfigured",
     baseUrl: null,
-    apiUrlSource: resolution.apiUrlSource,
-    apiKeyPresent: resolution.apiKeyPresent,
-    apiKeySource: resolution.apiKeySource,
-    apiKeyTier: resolution.apiKeyTier,
+    apiUrlSource: resolution?.apiUrlSource ?? null,
+    apiKeyPresent: resolution?.apiKeyPresent ?? false,
+    apiKeySource: resolution?.apiKeySource ?? null,
+    apiKeyTier: resolution?.apiKeyTier ?? null,
     configured: false,
     misconfigured: true,
     issue,
-    warning: null
+    warning
   };
 }
-function resolveContactsClientTransport(name, env = process.env) {
+function resolveContactsClientTransport(name, env = process.env, credentials = {}) {
   if (name !== "contacts") {
     throw new ContactsClientConfigurationError("CONTACTS_CLIENT_NAME_INVALID", "This resolver only accepts the contacts app slug.");
   }
   assertNoRetiredClientSelectors(env);
   const stamp = clientConfigurationStamp(env);
-  const resolution = resolveSharedClientTransport(name, env);
-  assertConfigurationUnchanged(env, stamp);
-  if (resolution.transport !== "http" || !resolution.baseUrl) {
-    const issue = resolution.misconfigured ? "The configured contacts API URL or credential is invalid or incomplete." : "HASNA_CONTACTS_API_URL and a resolvable contacts API key are required; no local fallback exists.";
-    return unconfiguredResolution(resolution, issue);
+  let resolution;
+  try {
+    resolution = resolveSharedClientTransport(name, env, {
+      credentials: contactsResolverCredentials(env, credentials)
+    });
+  } catch (error) {
+    assertConfigurationUnchanged(env, stamp);
+    if (error instanceof ClientTransportConfigurationError) {
+      return unconfiguredResolution(error.message, null);
+    }
+    throw error;
   }
+  assertConfigurationUnchanged(env, stamp);
   try {
     assertHttpsBaseUrl(resolution.baseUrl);
   } catch (error) {
     return {
-      ...unconfiguredResolution(resolution, error instanceof Error ? error.message : String(error)),
+      ...unconfiguredResolution(error instanceof Error ? error.message : String(error), resolution),
       apiKeyPresent: resolution.apiKeyPresent
     };
   }
@@ -4008,7 +4040,7 @@ function resolveContactsClientTransport(name, env = process.env) {
     configured: true,
     misconfigured: false,
     issue: null,
-    warning: null
+    warning: resolution.warning
   };
 }
 function resourcePath(resource) {
@@ -4062,20 +4094,21 @@ function createStorageClient(name, transport) {
     }
   };
 }
-function resolveContactsStorageClient(name, env = process.env) {
-  const resolution = resolveContactsClientTransport(name, env);
+function resolveContactsStorageClient(name, env = process.env, credentials = {}) {
+  const resolution = resolveContactsClientTransport(name, env, credentials);
   if (!resolution.configured || !resolution.baseUrl) {
     throw new ContactsClientConfigurationError("CONTACTS_API_NOT_CONFIGURED", `${resolution.issue ?? "The contacts API client is not configured."} ` + "Configure HASNA_CONTACTS_API_URL and a contacts API key; the client will not read or create a local SQLite database.");
   }
   const baseUrl = resolution.baseUrl;
+  const chainOptions = contactsResolverCredentials(env, credentials);
   const request = async (method, path, body, opts) => {
     const stamp = clientConfigurationStamp(env);
     const snapshot = { ...env };
-    const current = resolveContactsClientTransport(name, snapshot);
+    const current = resolveContactsClientTransport(name, snapshot, chainOptions);
     if (!current.configured || current.baseUrl !== baseUrl) {
       throw new ContactsClientConfigurationError("CONTACTS_AUTHORITY_CHANGED", "Client authority changed or disappeared; construct a new client before sending data.");
     }
-    const credential = resolveCredential(name, snapshot);
+    const credential = resolveCredential(name, snapshot, chainOptions);
     if (!credential)
       throw new ContactsClientConfigurationError("CONTACTS_API_NOT_CONFIGURED", "No credential is available.");
     assertConfigurationUnchanged(env, stamp);
@@ -4125,6 +4158,39 @@ function stripUndefined(input) {
   return out;
 }
 
+class ContactsApiResponseError extends Error {
+  constructor(operation, detail) {
+    super(`contacts: malformed /v1 response for ${operation}: ${detail}`);
+    this.name = "ContactsApiResponseError";
+  }
+}
+function requireAppendedContact(response, contactId, collection, matchKey, value) {
+  const operation = collection === "emails" ? "addEmailToContact" : "addPhoneToContact";
+  const contact = pick(response, "contact");
+  if (!contact || typeof contact !== "object" || Array.isArray(contact)) {
+    throw new ContactsApiResponseError(operation, "expected an object at response.contact");
+  }
+  if (contact.id !== contactId) {
+    throw new ContactsApiResponseError(operation, "response.contact.id did not match the requested contact");
+  }
+  const items = contact[collection];
+  if (!Array.isArray(items)) {
+    throw new ContactsApiResponseError(operation, `response.contact.${collection} was not an array`);
+  }
+  const normalize = collection === "emails" ? (input) => input.toLowerCase() : (input) => input;
+  const wanted = normalize(value);
+  const appended = items.find((item) => {
+    if (!item || typeof item !== "object" || Array.isArray(item))
+      return false;
+    const record = item;
+    return typeof record.id === "string" && record.contact_id === contactId && typeof record[matchKey] === "string" && normalize(record[matchKey]) === wanted;
+  });
+  if (!appended) {
+    throw new ContactsApiResponseError(operation, `response.contact.${collection} did not contain the requested value`);
+  }
+  return contact;
+}
+
 class ApiStore {
   client;
   mode = "api";
@@ -4194,11 +4260,17 @@ class ApiStore {
   async mergeContacts() {
     return unavailable("mergeContacts");
   }
-  async addEmailToContact() {
-    return unavailable("addEmailToContact");
+  async addEmailToContact(contactId, email) {
+    const res = await this.patch(`/contacts/${this.enc(contactId)}`, {
+      emails_add: [stripUndefined(email)]
+    });
+    return requireAppendedContact(res, contactId, "emails", "address", email.address);
   }
-  async addPhoneToContact() {
-    return unavailable("addPhoneToContact");
+  async addPhoneToContact(contactId, phone) {
+    const res = await this.patch(`/contacts/${this.enc(contactId)}`, {
+      phones_add: [stripUndefined(phone)]
+    });
+    return requireAppendedContact(res, contactId, "phones", "number", phone.number);
   }
   async archiveContact() {
     return unavailable("archiveContact");
@@ -5369,18 +5441,117 @@ async function confirmUser(question) {
   return answer.toLowerCase() === "y" || answer.toLowerCase() === "yes";
 }
 
+// src/lib/compact-output.ts
+var CONTACTS_COMPACT_LIMIT = 20;
+var CONTACTS_MAX_LIMIT = 500;
+function normalizeContactsLimit(value, fallback = CONTACTS_COMPACT_LIMIT) {
+  const parsed = typeof value === "number" ? value : Number(value ?? fallback);
+  if (!Number.isFinite(parsed))
+    return fallback;
+  return Math.max(1, Math.min(CONTACTS_MAX_LIMIT, Math.trunc(parsed)));
+}
+function normalizeContactsOffset(value) {
+  const parsed = typeof value === "number" ? value : Number(value ?? 0);
+  if (!Number.isFinite(parsed))
+    return 0;
+  return Math.max(0, Math.trunc(parsed));
+}
+function summarizeContact(contact) {
+  return {
+    id: contact.id,
+    display_name: contact.display_name,
+    job_title: contact.job_title,
+    company: contact.company ? { id: contact.company.id, name: contact.company.name } : null,
+    primary_email: contact.emails?.find((email) => email.is_primary)?.address ?? contact.emails?.[0]?.address ?? null,
+    primary_phone: contact.phones?.find((phone) => phone.is_primary)?.number ?? contact.phones?.[0]?.number ?? null,
+    status: contact.status,
+    follow_up_at: contact.follow_up_at,
+    last_contacted_at: contact.last_contacted_at,
+    archived: contact.archived,
+    sensitivity: contact.sensitivity,
+    tags: (contact.tags ?? []).map((tag) => ({ id: tag.id, name: tag.name })),
+    updated_at: contact.updated_at
+  };
+}
+function compareContactsByDisplayNameAndId(left, right) {
+  return left.display_name.localeCompare(right.display_name) || left.id.localeCompare(right.id);
+}
+function compactContactsPage(contacts, options) {
+  const ordered = [...contacts].sort(compareContactsByDisplayNameAndId);
+  const nextCursor = options.offset + ordered.length < options.total ? options.offset + contacts.length : null;
+  return {
+    contacts: ordered.map(summarizeContact),
+    count: ordered.length,
+    total: options.total,
+    limit: options.limit,
+    cursor: options.offset,
+    next_cursor: nextCursor,
+    has_more: nextCursor !== null,
+    compact: true,
+    sort: { fields: ["display_name", "id"], direction: "asc" },
+    hint: "Use contacts show <id> for one full record; pass --full for the legacy list payload."
+  };
+}
+
+// src/mcp/profile.ts
+var CONTACTS_FULL_TOOL_COUNT = 190;
+var CONTACTS_CORE_TOOL_NAMES = [
+  "create_contact",
+  "get_contact",
+  "update_contact",
+  "delete_contact",
+  "list_contacts",
+  "search_contacts",
+  "find_or_create_contact",
+  "upsert_contact",
+  "get_contact_by_email",
+  "add_email_to_contact",
+  "add_phone_to_contact",
+  "create_company",
+  "get_company",
+  "update_company",
+  "delete_company",
+  "list_companies",
+  "search_companies",
+  "create_tag",
+  "list_tags",
+  "add_tag_to_contact",
+  "remove_tag_from_contact",
+  "add_relationship",
+  "list_relationships",
+  "delete_relationship",
+  "get_contact_brief",
+  "get_contact_timeline",
+  "get_recent_contact_events",
+  "send_feedback",
+  "contacts_connection_status",
+  "search_tools",
+  "describe_tools"
+];
+var CORE_TOOLS = new Set(CONTACTS_CORE_TOOL_NAMES);
+
 // src/cli/commands/core.tsx
 function collect(val, prev) {
   return [...prev, val];
 }
 function registerCoreCommands(program2, version) {
   program2.command("status").description("Show CLI version, API endpoint, storage mode, and record counts").option("--json", "Output as JSON").action(async (opts) => {
-    const baseUrl = process.env["HASNA_CONTACTS_API_URL"]?.trim();
-    const apiLine = baseUrl ? baseUrl : "(not configured \u2014 set HASNA_CONTACTS_API_URL plus a contacts API key)";
+    let apiLine = "(not configured \u2014 set HASNA_CONTACTS_API_URL plus a contacts API key)";
+    let apiUrlSource = null;
+    let apiKeySource = null;
+    let apiKeyTier = null;
+    let issue = null;
     let counts;
     let storage;
     let failure;
     try {
+      const resolution = resolveContactsClientTransport("contacts");
+      apiUrlSource = resolution.apiUrlSource;
+      apiKeySource = resolution.apiKeySource;
+      apiKeyTier = resolution.apiKeyTier;
+      issue = resolution.issue;
+      if (resolution.configured && resolution.baseUrl)
+        apiLine = resolution.baseUrl;
       const store = getStore();
       const [contacts, companies] = await Promise.all([
         store.listContacts({ limit: 1 }),
@@ -5400,7 +5571,11 @@ function registerCoreCommands(program2, version) {
       service: "contacts",
       version,
       api: apiLine,
+      api_url_source: apiUrlSource,
+      api_key_source: apiKeySource,
+      api_key_tier: apiKeyTier,
       storage,
+      ...issue !== null ? { issue } : {},
       ...failure !== undefined ? { error: failure } : {},
       ...counts ? { counts } : {}
     };
@@ -5410,7 +5585,13 @@ function registerCoreCommands(program2, version) {
     }
     console.log(chalk2.bold(`contacts v${version}`));
     console.log(`API:      ${apiLine}`);
+    if (apiUrlSource)
+      console.log(`API URL source: ${apiUrlSource}`);
+    if (apiKeySource)
+      console.log(`API key source: ${apiKeySource}${apiKeyTier ? ` (${apiKeyTier})` : ""}`);
     console.log(`Storage:  ${storage}`);
+    if (issue !== null)
+      console.log(chalk2.yellow(`Issue:    ${issue}`));
     if (failure !== undefined)
       console.log(chalk2.red(`Error:    ${failure}`));
     if (counts) {
@@ -5482,19 +5663,19 @@ Add New Contact
 \u2713 Contact created: ${contact.display_name} (${contact.id})
 `));
   });
-  program2.command("list").description("List contacts").option("--tag <tag_id>", "Filter by tag ID").option("--company <id>", "Filter by company ID").option("--include-restricted", "Include restricted-sensitivity contacts").option("-l, --limit <n>", "Max results", "50").option("-o, --offset <n>", "Skip first N results", "0").option("--order-by <field>", "Sort field: display_name|created_at|updated_at|last_contacted_at|follow_up_at", "display_name").option("--order-dir <dir>", "Sort direction: asc|desc", "asc").option("-j, --json", "Output JSON").action(async (opts) => {
+  program2.command("list").description("List contacts").option("--tag <tag_id>", "Filter by tag ID").option("--company <id>", "Filter by company ID").option("-l, --limit <n>", "Max results (default 20; --full defaults to 50)").option("-o, --offset <n>", "Skip first N results", "0").option("--status <status>", "Filter by hosted lifecycle status").option("-j, --json", "Output compact paged JSON").option("--full", "Return the legacy full-record list payload").action(async (opts) => {
     const store = getStore();
+    const limit = normalizeContactsLimit(opts.limit, opts.full ? 50 : 20);
+    const offset = normalizeContactsOffset(opts.offset);
     const result = await store.listContacts({
       tag_id: opts.tag,
       company_id: opts.company,
-      include_restricted: opts.includeRestricted,
-      limit: parseInt(opts.limit, 10),
-      offset: parseInt(opts.offset, 10),
-      order_by: opts.orderBy,
-      order_dir: opts.orderDir === "desc" ? "desc" : "asc"
+      status: opts.status,
+      limit,
+      offset
     });
     if (opts.json) {
-      console.log(JSON.stringify(result, null, 2));
+      console.log(JSON.stringify(opts.full ? result : compactContactsPage(result.contacts, { total: result.total, limit, offset }), null, 2));
       return;
     }
     if (result.contacts.length === 0) {
@@ -5835,33 +6016,22 @@ Invalid format: ${format}. Use csv, vcf, or json
       process.stdout.write(output);
     }
   });
-  program2.command("mcp").description("Print MCP server setup instructions").action(() => {
+  program2.command("mcp").description("Print truthful MCP server setup instructions").action(() => {
     const config = JSON.stringify({ contacts: { command: "contacts-mcp", args: [], env: {} } }, null, 4);
+    const coreCount = CONTACTS_CORE_TOOL_NAMES.length;
+    const fullCount = CONTACTS_FULL_TOOL_COUNT;
     console.log(`
 ${chalk2.bold.blue("\u2501\u2501\u2501 Contacts MCP Server Setup \u2501\u2501\u2501")}
 
-${chalk2.bold("1. Install the package:")}
-   ${chalk2.cyan("npm install -g @hasna/contacts")}
-   ${chalk2.gray("or:")} ${chalk2.cyan("bun add -g @hasna/contacts")}
-
-${chalk2.bold("2. Add to Claude Code (recommended):")}
-   ${chalk2.cyan("claude mcp add --transport stdio --scope user contacts -- contacts-mcp")}
+${chalk2.bold("Install:")} ${chalk2.cyan("npm install -g @hasna/contacts")}
+${chalk2.bold("Claude Code:")} ${chalk2.cyan("claude mcp add --transport stdio --scope user contacts -- contacts-mcp")}
+${chalk2.bold("Manual config:")} ${chalk2.yellow(config)}
 
-${chalk2.bold("3. Or add manually to ~/.claude.json:")}
-   ${chalk2.yellow(config)}
+Default profile: core (${coreCount} tools). It includes routine contact/company/tag/relationship reads and writes plus search_tools and describe_tools for complete discovery across the ${fullCount}-tool full inventory.
+Full compatibility profile: set HASNA_CONTACTS_MCP_PROFILE=full or run contacts-mcp --mcp-profile full.
+List ordering: display_name asc, then id asc. Hosted list filters: company_id, tag_id, status.
 
-${chalk2.bold("4. Restart Claude Code and verify with")} ${chalk2.cyan("/mcp")}
-
-${chalk2.bold("Available tools (24 total):")}
-  ${chalk2.gray("Contacts: ")}${chalk2.white("create_contact  get_contact  update_contact  delete_contact")}
-  ${chalk2.gray("          ")}${chalk2.white("list_contacts   search_contacts  merge_contacts")}
-  ${chalk2.gray("Companies:")}${chalk2.white("create_company  get_company  update_company  delete_company")}
-  ${chalk2.gray("          ")}${chalk2.white("list_companies  search_companies")}
-  ${chalk2.gray("Tags:     ")}${chalk2.white("create_tag  list_tags  delete_tag")}
-  ${chalk2.gray("          ")}${chalk2.white("add_tag_to_contact  remove_tag_from_contact")}
-  ${chalk2.gray("Rels:     ")}${chalk2.white("add_relationship  list_relationships  delete_relationship")}
-  ${chalk2.gray("I/O:      ")}${chalk2.white("import_contacts  export_contacts  get_stats")}
-`);
+Restart the client and verify the active profile in the MCP initialize instructions.`);
   });
   program2.command("recent").description("Show recently added or modified contacts").option("-l, --limit <n>", "Number to show", "10").option("-j, --json", "Output JSON").action(async (opts) => {
     const store = getStore();
@@ -7866,7 +8036,7 @@ Health data cleared for ${contact?.display_name ?? id}
 // src/cli/commands/audience.tsx
 import chalk5 from "chalk";
 
-// ../../node_modules/.bun/zod@3.25.76/node_modules/zod/v3/external.js
+// node_modules/zod/v3/external.js
 var exports_external = {};
 __export(exports_external, {
   void: () => voidType,
@@ -7978,7 +8148,7 @@ __export(exports_external, {
   BRAND: () => BRAND
 });
 
-// ../../node_modules/.bun/zod@3.25.76/node_modules/zod/v3/helpers/util.js
+// node_modules/zod/v3/helpers/util.js
 var util;
 (function(util2) {
   util2.assertEqual = (_) => {};
@@ -8109,7 +8279,7 @@ var getParsedType = (data) => {
   }
 };
 
-// ../../node_modules/.bun/zod@3.25.76/node_modules/zod/v3/ZodError.js
+// node_modules/zod/v3/ZodError.js
 var ZodIssueCode = util.arrayToEnum([
   "invalid_type",
   "invalid_literal",
@@ -8228,7 +8398,7 @@ ZodError.create = (issues) => {
   return error;
 };
 
-// ../../node_modules/.bun/zod@3.25.76/node_modules/zod/v3/locales/en.js
+// node_modules/zod/v3/locales/en.js
 var errorMap = (issue, _ctx) => {
   let message;
   switch (issue.code) {
@@ -8331,7 +8501,7 @@ var errorMap = (issue, _ctx) => {
 };
 var en_default = errorMap;
 
-// ../../node_modules/.bun/zod@3.25.76/node_modules/zod/v3/errors.js
+// node_modules/zod/v3/errors.js
 var overrideErrorMap = en_default;
 function setErrorMap(map) {
   overrideErrorMap = map;
@@ -8339,7 +8509,7 @@ function setErrorMap(map) {
 function getErrorMap() {
   return overrideErrorMap;
 }
-// ../../node_modules/.bun/zod@3.25.76/node_modules/zod/v3/helpers/parseUtil.js
+// node_modules/zod/v3/helpers/parseUtil.js
 var makeIssue = (params) => {
   const { data, path, errorMaps, issueData } = params;
   const fullPath = [...path, ...issueData.path || []];
@@ -8445,14 +8615,14 @@ var isAborted = (x) => x.status === "aborted";
 var isDirty = (x) => x.status === "dirty";
 var isValid = (x) => x.status === "valid";
 var isAsync = (x) => typeof Promise !== "undefined" && x instanceof Promise;
-// ../../node_modules/.bun/zod@3.25.76/node_modules/zod/v3/helpers/errorUtil.js
+// node_modules/zod/v3/helpers/errorUtil.js
 var errorUtil;
 (function(errorUtil2) {
   errorUtil2.errToObj = (message) => typeof message === "string" ? { message } : message || {};
   errorUtil2.toString = (message) => typeof message === "string" ? message : message?.message;
 })(errorUtil || (errorUtil = {}));
 
-// ../../node_modules/.bun/zod@3.25.76/node_modules/zod/v3/types.js
+// node_modules/zod/v3/types.js
 class ParseInputLazyPath {
   constructor(parent, value, path, key) {
     this._cachedPath = [];
@@ -12169,82 +12339,73 @@ function registerStorageCommands(program2) {
 // src/cli/legacy.ts
 import { createHash as createHash2 } from "crypto";
 import fs, { constants, closeSync, existsSync as existsSync6, fstatSync, lstatSync, readSync, realpathSync, statSync as statSync2, writeSync } from "fs";
-import { homedir as homedir2 } from "os";
-import { basename, dirname, join as join3, resolve as resolve2 } from "path";
+import { homedir as homedir3 } from "os";
+import { basename, dirname, join as join4, resolve as resolve2 } from "path";
 import chalk7 from "chalk";
 
 // src/db/paths.ts
-import { homedir as pathsResolverHomedir2 } from "os";
-import { join as pathsResolverJoin2 } from "path";
-var PATHS_RESOLVER_KIND_ENV2 = {
-  config: "HASNA_CONFIG_HOME",
+import { homedir as pathsResolverHomedir } from "os";
+import { join as pathsResolverJoin } from "path";
+var PATHS_RESOLVER_KIND_ENV = {
   data: "HASNA_DATA_HOME",
-  state: "HASNA_STATE_HOME",
-  cache: "HASNA_CACHE_HOME"
+  state: "HASNA_STATE_HOME"
 };
-var PATHS_RESOLVER_APP_SLUG_RE2 = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
-function pathsResolverAssertApp2(app) {
+var PATHS_RESOLVER_APP_SLUG_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+function pathsResolverAssertApp(app) {
   if (typeof app !== "string" || app.length === 0) {
     throw new TypeError("paths: app must be a non-empty string");
   }
-  if (!PATHS_RESOLVER_APP_SLUG_RE2.test(app)) {
+  if (!PATHS_RESOLVER_APP_SLUG_RE.test(app)) {
     throw new TypeError(`paths: invalid app slug "${app}" \u2014 expected lowercase kebab-case ([a-z0-9]+(-[a-z0-9]+)*)`);
   }
 }
-function pathsResolverAssertKind2(kind) {
-  if (!Object.keys(PATHS_RESOLVER_KIND_ENV2).includes(kind)) {
-    throw new TypeError(`paths: invalid path kind "${kind}" \u2014 expected one of ${Object.keys(PATHS_RESOLVER_KIND_ENV2).join(", ")}`);
+function pathsResolverAssertKind(kind) {
+  if (!Object.keys(PATHS_RESOLVER_KIND_ENV).includes(kind)) {
+    throw new TypeError(`paths: invalid path kind "${kind}" \u2014 expected one of ${Object.keys(PATHS_RESOLVER_KIND_ENV).join(", ")}`);
   }
 }
-function pathsResolverBaseDir2(kind, options) {
-  pathsResolverAssertKind2(kind);
+function pathsResolverBaseDir(kind, options) {
+  pathsResolverAssertKind(kind);
   const env = options.env ?? process.env;
-  const override = env[PATHS_RESOLVER_KIND_ENV2[kind]];
+  const override = env[PATHS_RESOLVER_KIND_ENV[kind]];
   if (typeof override === "string" && override.length > 0)
     return override;
-  const home = options.home ?? pathsResolverHomedir2();
+  const home = options.home ?? pathsResolverHomedir();
   const platform = options.platform ?? process.platform;
   if (platform === "darwin") {
     switch (kind) {
-      case "config":
       case "data":
-        return pathsResolverJoin2(home, "Library", "Application Support", "Hasna");
-      case "cache":
-        return pathsResolverJoin2(home, "Library", "Caches", "Hasna");
+        return pathsResolverJoin(home, "Library", "Application Support", "Hasna");
       case "state":
-        return pathsResolverJoin2(home, "Library", "Logs", "Hasna");
+        return pathsResolverJoin(home, "Library", "Logs", "Hasna");
     }
   }
   switch (kind) {
-    case "config":
-      return pathsResolverJoin2(home, ".config", "hasna");
     case "data":
-      return pathsResolverJoin2(home, ".local", "share", "hasna");
+      return pathsResolverJoin(home, ".local", "share", "hasna");
     case "state":
-      return pathsResolverJoin2(home, ".local", "state", "hasna");
-    case "cache":
-      return pathsResolverJoin2(home, ".cache", "hasna");
+      return pathsResolverJoin(home, ".local", "state", "hasna");
   }
 }
-function pathsResolverResolve2(kind, options) {
-  pathsResolverAssertApp2(options.app);
-  const appSegment = options.internal === true ? pathsResolverJoin2("internal", options.app) : options.app;
-  return pathsResolverJoin2(pathsResolverBaseDir2(kind, options), appSegment);
+function pathsResolverResolve(kind, options) {
+  pathsResolverAssertApp(options.app);
+  const appSegment = options.internal === true ? pathsResolverJoin("internal", options.app) : options.app;
+  return pathsResolverJoin(pathsResolverBaseDir(kind, options), appSegment);
 }
 function dataDir2(options) {
-  return pathsResolverResolve2("data", options);
+  return pathsResolverResolve("data", options);
 }
 
 // src/cli/legacy.ts
 function home(env = process.env) {
-  return env.HOME || env.USERPROFILE || homedir2();
+  return env.HOME || env.USERPROFILE || homedir3();
 }
 function legacyDatabaseCandidates(env = process.env) {
   const base = home(env);
   const paths = [
-    { source: "xdg", path: join3(dataDir2({ app: "contacts", home: base, env }), "contacts.db") },
-    { source: "legacy-hasna", path: join3(base, ".hasna", "contacts", "contacts.db") },
-    { source: "ancient", path: join3(base, ".contacts", "contacts.db") }
+    { source: "xdg", path: join4(dataDir2({ app: "contacts", home: base, env }), "contacts.db") },
+    { source: "legacy-hasna", path: join4(base, ".hasna", "contacts", "contacts.db") },
+    { source: "ancient", path: join4(base, ".contacts", "contacts.db") }
   ];
   return paths.map(({ source, path }) => {
     const exists = existsSync6(path) && lstatSync(path).isFile();
@@ -12391,6 +12552,175 @@ function registerLegacyCommands(program2) {
   });
 }
 
+// src/browser/install.ts
+import { chmodSync, cpSync, existsSync as existsSync7, mkdirSync, readFileSync as readFileSync4, writeFileSync as writeFileSync2 } from "fs";
+import { homedir as homedir5 } from "os";
+import { dirname as dirname2, join as join6, resolve as resolve3 } from "path";
+import { fileURLToPath } from "url";
+
+// src/browser/identity.ts
+var EXTENSION_ID = "ceegpmbcoiomonopbhpifdalooccfgjj";
+var HOST_NAME = "com.hasna.contacts";
+
+// src/browser/protocol.ts
+class BrowserError extends Error {
+  code;
+  constructor(code) {
+    super(code);
+    this.code = code;
+    this.name = "BrowserError";
+  }
+}
+function safeError(error) {
+  return error instanceof BrowserError ? error.code : "CONTACTS_UNAVAILABLE";
+}
+
+class NativeProtocol {
+  handlers;
+  buffer = Buffer.alloc(0);
+  queued = 0;
+  chain = Promise.resolve();
+  constructor(handlers) {
+    this.handlers = handlers;
+  }
+  accept(chunk) {
+    this.buffer = Buffer.concat([this.buffer, chunk]);
+    if (this.buffer.length > 1048576)
+      return this.handlers.fail();
+    while (this.buffer.length >= 4) {
+      const length = this.buffer.readUInt32LE(0);
+      if (!length || length > 65536)
+        return this.handlers.fail();
+      if (this.buffer.length < 4 + length)
+        break;
+      let message;
+      try {
+        message = JSON.parse(this.buffer.subarray(4, 4 + length).toString());
+      } catch {
+        return this.handlers.fail();
+      }
+      this.buffer = this.buffer.subarray(4 + length);
+      if (!message || typeof message.id !== "string" || !/^[0-9a-f-]{36}$/.test(message.id))
+        return this.handlers.fail();
+      if (++this.queued > 32)
+        return this.handlers.fail();
+      this.chain = this.chain.then(async () => {
+        try {
+          const result = await this.handlers.handle(message);
+          this.handlers.send({ id: message.id, ok: true, result });
+        } catch (e) {
+          this.handlers.send({ id: message.id, ok: false, error: safeError(e) });
+        } finally {
+          this.queued--;
+        }
+      });
+    }
+  }
+  async idle() {
+    await this.chain;
+  }
+}
+
+// src/browser/install.ts
+function packageRoot() {
+  let dir = dirname2(fileURLToPath(import.meta.url));
+  for (let i = 0;i < 5; i++, dir = dirname2(dir)) {
+    const p = join6(dir, "package.json");
+    if (existsSync7(p) && JSON.parse(readFileSync4(p, "utf8")).name === "@hasna/contacts")
+      return dir;
+  }
+  throw new BrowserError("PACKAGE_ROOT_NOT_FOUND");
+}
+function hostDirectories(home2 = homedir5(), userDataDir) {
+  const dirs = process.platform === "darwin" ? [
+    "Library/Application Support/Google/Chrome/NativeMessagingHosts",
+    "Library/Application Support/Chromium/NativeMessagingHosts",
+    "Library/Application Support/Google/Chrome for Testing/NativeMessagingHosts"
+  ] : [".config/google-chrome/NativeMessagingHosts", ".config/chromium/NativeMessagingHosts"];
+  const out = dirs.map((d) => join6(home2, d));
+  if (userDataDir)
+    out.push(join6(resolve3(userDataDir), "NativeMessagingHosts"));
+  return [...new Set(out)];
+}
+function installBrowser(options = {}) {
+  if (!["darwin", "linux"].includes(process.platform))
+    throw new BrowserError("UNSUPPORTED_PLATFORM");
+  const root = options.root ?? packageRoot();
+  const home2 = options.home ?? homedir5();
+  const install = join6(home2, ".hasna", "contacts", "chrome");
+  mkdirSync(install, { recursive: true, mode: 448 });
+  const extension = join6(install, "extension");
+  cpSync(join6(root, "extension"), extension, { recursive: true });
+  const host = join6(install, "native-host");
+  const entry = resolve3(root, "dist/browser/native.js");
+  if (!existsSync7(entry))
+    throw new BrowserError("BUILD_REQUIRED");
+  writeFileSync2(host, `#!${options.execPath ?? process.execPath}
+import ${JSON.stringify(entry)};
+`, { mode: 448 });
+  chmodSync(host, 448);
+  const manifests = hostDirectories(home2, options.userDataDir).map((dir) => {
+    mkdirSync(dir, { recursive: true, mode: 448 });
+    const path = join6(dir, `${HOST_NAME}.json`);
+    const manifest = {
+      name: HOST_NAME,
+      description: "Hasna Contacts autofill",
+      path: host,
+      type: "stdio",
+      allowed_origins: [`chrome-extension://${EXTENSION_ID}/`]
+    };
+    if (existsSync7(path)) {
+      const old = JSON.parse(readFileSync4(path, "utf8"));
+      if (old.name !== HOST_NAME || old.path !== host)
+        throw new BrowserError("EXISTING_HOST_CONFLICT");
+    }
+    writeFileSync2(path, `${JSON.stringify(manifest, null, 2)}
+`, { mode: 384 });
+    return path;
+  });
+  return {
+    ok: true,
+    extensionId: EXTENSION_ID,
+    extensionPath: extension,
+    nativeHost: host,
+    nativeManifests: manifests,
+    next: "In the desired Chrome profile, open chrome://extensions, enable Developer mode, choose Load unpacked, and select extensionPath. Pin Contacts."
+  };
+}
+function browserStatus(options = {}) {
+  const home2 = options.home ?? homedir5();
+  const host = join6(home2, ".hasna", "contacts", "chrome", "native-host");
+  const extension = join6(home2, ".hasna", "contacts", "chrome", "extension");
+  return {
+    ok: true,
+    extensionId: EXTENSION_ID,
+    extensionInstalled: existsSync7(join6(extension, "manifest.json")),
+    nativeHostInstalled: existsSync7(host),
+    manifests: hostDirectories(home2, options.userDataDir).map((dir) => ({
+      path: join6(dir, `${HOST_NAME}.json`),
+      present: existsSync7(join6(dir, `${HOST_NAME}.json`))
+    }))
+  };
+}
+
+// src/browser/cli.ts
+function registerBrowserCommands(program2) {
+  const output = (fn) => {
+    try {
+      const r = fn();
+      console.log(JSON.stringify(r));
+      if (r?.ok === false)
+        process.exitCode = 1;
+    } catch (e) {
+      console.log(JSON.stringify({ ok: false, error: safeError(e) }));
+      process.exitCode = 1;
+    }
+  };
+  const cmd = program2.command("browser").description("Chrome extension: inline contact autofill (hosted Contacts API)");
+  cmd.command("install").description("Install the native host and unpacked extension assets; no browser restart").option("--user-data-dir <path>", "Also register the native host in an automated Chrome user-data directory").action((opts) => output(() => installBrowser({ userDataDir: opts.userDataDir })));
+  cmd.command("status").description("Report where the native host manifests and extension assets are installed").option("--user-data-dir <path>", "Also check an automated Chrome user-data directory").action((opts) => output(() => browserStatus({ userDataDir: opts.userDataDir })));
+}
+
 // src/cli/index.tsx
 import { createRequire } from "module";
 var { registerEventCommands: registerEventCommands2 } = exports_commander;
@@ -12404,13 +12734,13 @@ registerAdvancedCommands(program);
 registerAudienceCommands(program);
 registerStorageCommands(program);
 registerLegacyCommands(program);
+registerBrowserCommands(program);
 registerWebhookCommands2?.(program, { source: "contacts" });
 registerEventCommands2(program, { source: "contacts", eventsCommandName: "hasna-events" });
 program.parseAsync(process.argv).catch((err) => {
   const message = err instanceof Error ? err.message : String(err);
   const isApiUnavailable = err instanceof Error && err.name === "ApiUnavailableError";
-  console.error(`
-` + (isApiUnavailable ? chalk8.yellow(message) : chalk8.red(message)) + `
+  console.error((isApiUnavailable ? chalk8.yellow(message) : chalk8.red(message)) + `
 `);
   process.exit(1);
 });