@indigoai-us/hq-cli 5.328.0 → 5.330.0

package/dist/command-help.d.ts

@@ -0,0 +1,2 @@
+export declare function runCommandHelp(argv: readonly string[]): Promise<void>;
+//# sourceMappingURL=command-help.d.ts.map

package/dist/command-help.js

@@ -0,0 +1,13 @@
+import { Command } from "commander";
+import { CLI_VERSION } from "./cli-version.js";
+import { registerCommandCatalog } from "./lazy-commands.js";
+export async function runCommandHelp(argv) {
+    const program = new Command()
+        .name("hq")
+        .description("HQ management CLI — modules, packages, and cloud sync")
+        .version(CLI_VERSION)
+        .option("--verbose", "Show verbose diagnostics, including SDK runtime warnings");
+    registerCommandCatalog(program);
+    await program.parseAsync([...argv]);
+}
+//# sourceMappingURL=command-help.js.map

package/dist/commands/cloud.d.ts

@@ -239,6 +239,11 @@ export interface ShareCallResult {
 export interface PushAllDeps {
     vaultClient: PullAllVaultClient;
     share: (options: ShareCallOptions) => Promise<ShareCallResult>;
+    beforeShare?: (input: {
+        slug: string;
+        companyUid: string;
+        companyRoot: string;
+    }) => Promise<void>;
     /** DEV-1768: resolve membership push scope (same as pull). */
     resolveScope?: (companyUid: string, slug: string) => Promise<PullScope>;
 }

package/dist/commands/cloud.js

@@ -17,10 +17,11 @@ import chalk from "chalk";
 import * as fs from "fs";
 import * as path from "path";
 import { share, sync, getStateDir, listJournals, VaultClient, computePersonalVaultPaths, PERSONAL_VAULT_JOURNAL_SLUG, resolvePullScope, syncDoctor, } from "@indigoai-us/hq-cloud";
-import { DEFAULT_HQ_ROOT, ensureCognitoToken, buildVaultConfig, } from "../utils/cognito-session.js";
+import { DEFAULT_HQ_ROOT, ensureCognitoToken, buildVaultConfig, loadCachedTokens, } from "../utils/cognito-session.js";
 import { resolveUploadAuthor } from "../utils/upload-author.js";
 import { companyFolderExceedsThreshold, emitNarrowHint, isStrictRefusal, resolveBannerLevel, resolveNarrowHintPresentationLevel, resolveNarrowHintMinBytes, } from "../lib/narrow-hint-banner.js";
 import { beginSyncHealthReport, } from "../utils/client-health.js";
+import { companySlugFromSyncPaths, warnAboutInvalidOntologyEntities, } from "../lib/sync-invalid-entity-warning.js";
 import { isWorkBearingSyncResult, recordFirstWorkBearingSync, } from "../lib/first-sync-next-step.js";
 import { maybeShowCliInviteNudge } from "../lib/cli-invite-nudge.js";
 import { createPlanLimitRefusalTracker, describeRefusedCount, describeRefusedFiles, mergePlanLimitRefusals, renderPlanLimitRefusalLines, trackingProgressRecorder, } from "../lib/billing/plan-limit-refusals.js";
@@ -504,6 +505,22 @@ export async function pushAll(options, deps) {
             }
         }
         try {
+            if (entry.slug !== "personal") {
+                try {
+                    await deps.beforeShare?.({
+                        slug: entry.slug,
+                        companyUid: entry.companyUid,
+                        companyRoot: path.join(options.hqRoot, "companies", entry.slug),
+                    });
+                }
+                catch (error) {
+                    const name = error instanceof Error ? error.name : "UnknownError";
+                    const errorClass = /^[A-Za-z][A-Za-z0-9]{0,63}$/.test(name)
+                        ? name
+                        : "UnknownError";
+                    process.stderr.write(`HQ Sync entity diagnostic failed (${errorClass}); continuing upload.\n`);
+                }
+            }
             const r = await deps.share(entry.shareOptions);
             result.filesUploaded += r.filesUploaded;
             result.bytesUploaded += r.bytesUploaded;
@@ -926,6 +943,20 @@ export function registerCloudCommands(program) {
             });
             const planLimitTracker = createPlanLimitRefusalTracker(companySlugForBilling(progressCompany));
             syncHealth = beginSyncHealthReport();
+            if (!personalMode) {
+                const companyUid = entityContext?.uid ??
+                    (targetCompany?.startsWith("cmp_") ? targetCompany : "");
+                const companySlug = companySlugFromSyncPaths(options.hqRoot, targetPaths);
+                if (companySlug) {
+                    await warnAboutInvalidOntologyEntities({
+                        hqRoot: options.hqRoot,
+                        companyRoot: path.join(options.hqRoot, "companies", companySlug),
+                        companyUid,
+                        companySlug,
+                        idToken: loadCachedTokens()?.idToken ?? "",
+                    });
+                }
+            }
             const result = await share({
                 paths: targetPaths,
                 company: targetCompany,
@@ -1541,6 +1572,13 @@ async function runPushAll(hqRoot, message, onConflict, skipPersonal) {
         }, {
             vaultClient: adapter,
             resolveScope: (companyUid, slug) => resolvePullScope(realClient, companyUid, slug, hqRoot),
+            beforeShare: async ({ slug, companyUid, companyRoot }) => warnAboutInvalidOntologyEntities({
+                hqRoot,
+                companyRoot,
+                companyUid,
+                companySlug: slug,
+                idToken: loadCachedTokens()?.idToken ?? "",
+            }),
             share: async (opts) => {
                 const progressCompany = opts.personalMode
                     ? null
@@ -1692,6 +1730,18 @@ async function runNowSingle(hqRoot, company, personal, message, onConflict, mode
             const pushScope = await resolveCliPullScope(scopeClient, targetCompany ?? pushSlug, hqRoot, (companyUid) => { nudgeResolvedCompanyUid = companyUid; });
             nowPushPrefixSet = pushScope?.prefixSet;
         }
+        if (!personalMode) {
+            const companySlug = companySlugFromSyncPaths(hqRoot, pushPaths);
+            if (companySlug) {
+                await warnAboutInvalidOntologyEntities({
+                    hqRoot,
+                    companyRoot: path.join(hqRoot, "companies", companySlug),
+                    companyUid: targetCompany?.startsWith("cmp_") ? targetCompany : "",
+                    companySlug,
+                    idToken: loadCachedTokens()?.idToken ?? "",
+                });
+            }
+        }
         const pushProgressCompany = personalMode ? null : (pushSlug ?? null);
         const planLimitTracker = createPlanLimitRefusalTracker(companySlugForBilling(pushProgressCompany));
         const pushResult = await share({

package/dist/commands/install-global.d.ts

@@ -17,6 +17,12 @@ export interface GlobalInstallOptions {
     log?: (line: string) => void;
     /** Is the hq daemon installed? Default: look for its launchd/systemd unit under `home`. */
     daemonInstalled?: boolean;
+    /** Install Claude Code through a local plugin marketplace instead of direct hooks/MCP. */
+    via?: 'direct' | 'plugin';
+    /** Local Claude Code marketplace directory (or HQ_CLAUDE_PLUGIN_MARKETPLACE). */
+    marketplaceDir?: string;
+    /** Test seam for the Claude Code CLI; production uses `claude`. */
+    runClaude?: (args: string[], home: string, env: NodeJS.ProcessEnv) => void;
 }
 /** True when an hq daemon unit (launchd plist or systemd unit) exists. */
 export declare function isDaemonInstalled(home: string, platform?: NodeJS.Platform, queryTask?: (task: string) => boolean): boolean;
@@ -25,6 +31,14 @@ export declare function isDaemonInstalled(home: string, platform?: NodeJS.Platfo
  * the hqd shim; otherwise to master-hook.sh / the Codex adapter.
  */
 export declare function hookTargetFor(hqRoot: string, home: string, daemonInstalled?: boolean, env?: NodeJS.ProcessEnv): HookTarget;
+export interface ClaudePluginSource {
+    sourceDir: string;
+    marketplaceName: string;
+    pluginName: string;
+    pluginId: string;
+}
+/** Resolve the local marketplace source; published hosting remains an operator decision. */
+export declare function resolveClaudePluginSource(explicitDir?: string, env?: NodeJS.ProcessEnv): ClaudePluginSource;
 export { AnywhereRuntimeDisabledError as AnywhereDisabledError };
 export declare const isAnywhereEnabled: (_home: string, env?: NodeJS.ProcessEnv) => boolean;
 /** Install HQ into Claude Code user scope. Returns the files touched (or that would be). */
@@ -37,6 +51,8 @@ export interface GlobalUninstallOptions {
     env?: NodeJS.ProcessEnv;
     registryFile?: string;
     log?: (line: string) => void;
+    /** Test seam for the Claude Code CLI; production uses `claude`. */
+    runClaude?: (args: string[], home: string, env: NodeJS.ProcessEnv) => void;
 }
 /** Reverse every install step; non-HQ entries are left untouched. */
 export declare function uninstallGlobalClaude(opts?: GlobalUninstallOptions): string[];
@@ -49,6 +65,11 @@ export interface GlobalCommandOpts {
     runtime?: string;
     dryRun?: boolean;
     hqRoot?: string;
+    via?: 'direct' | 'plugin';
+    marketplaceDir?: string;
+    /** Dependency injection for tests. */
+    env?: NodeJS.ProcessEnv;
+    log?: (line: string) => void;
 }
 /** Entry used by `hq install --global` (wired from pkg-install.ts). */
 export declare function runInstallGlobal(opts: GlobalCommandOpts): void;

package/dist/commands/install-global.js

@@ -15,6 +15,9 @@ import { buildCodexServerDef, claudeConfigFormat, codexConfigFormat, isCodexInst
 import { seedRegistryFromHqRoot } from './link.js';
 import { resolveHqRoot } from './doctor.js';
 import { anywhereRuntimeEnabled, AnywhereRuntimeDisabledError } from './anywhere-runtime-flag.js';
+import { resolveHqMcpEndpoint } from '../lib/daemon/mcp-endpoint.js';
+import { chatgptConnectorInstructions } from '../lib/install/chatgpt-targets.js';
+import { grokConnectorInstructions } from '../lib/install/grok-targets.js';
 import { readRegistry, registryDir, registryFile, writeRegistry } from '../lib/registry/registry.js';
 import { DAEMON_LAUNCHD_LABEL, DAEMON_SYSTEMD_UNIT, DAEMON_WINDOWS_TASK, SYSTEM_UNIT_DIR } from '../lib/daemon/install.js';
 import { readDaemonConfig } from '../lib/daemon/config.js';
@@ -42,6 +45,64 @@ export function hookTargetFor(hqRoot, home, daemonInstalled, env = process.env)
     const daemonMatchesRoot = configuredRoot !== undefined && realpathOrSelf(configuredRoot) === realpathOrSelf(hqRoot);
     return installed && daemonMatchesRoot && fs.existsSync(shimPath(hqRoot)) ? 'shim' : 'master';
 }
+/** Resolve the local marketplace source; published hosting remains an operator decision. */
+export function resolveClaudePluginSource(explicitDir, env = process.env) {
+    const configured = explicitDir?.trim() || env.HQ_CLAUDE_PLUGIN_MARKETPLACE?.trim();
+    if (!configured) {
+        throw Object.assign(new Error('Published HQ Claude plugin source is not configured; its repository/host awaits an operator decision. Pass --marketplace-dir <dir> or set HQ_CLAUDE_PLUGIN_MARKETPLACE.'), { expected: true });
+    }
+    const sourceDir = path.resolve(configured);
+    const manifestPath = path.join(sourceDir, '.claude-plugin', 'marketplace.json');
+    let manifest;
+    try {
+        manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+    }
+    catch (error) {
+        throw Object.assign(new Error(`Cannot read Claude marketplace manifest at ${manifestPath}: ${error.message}`), { expected: true });
+    }
+    if (typeof manifest.name !== 'string' || !Array.isArray(manifest.plugins)) {
+        throw Object.assign(new Error(`Invalid Claude marketplace manifest at ${manifestPath}: expected string name and plugins array.`), { expected: true });
+    }
+    const hqPlugin = manifest.plugins.find((p) => !!p && typeof p === 'object' && p.name === 'hq');
+    if (!hqPlugin) {
+        throw Object.assign(new Error(`Claude marketplace ${manifest.name} does not contain the HQ plugin named "hq".`), { expected: true });
+    }
+    return { sourceDir, marketplaceName: manifest.name, pluginName: hqPlugin.name, pluginId: `${hqPlugin.name}@${manifest.name}` };
+}
+function runClaudeCli(args, home, env) {
+    const childEnv = { ...process.env, ...env, HOME: home, CLAUDE_CONFIG_DIR: path.join(home, '.claude') };
+    const result = spawnSync('claude', ['plugin', ...args], { encoding: 'utf8', env: childEnv, timeout: 120_000, windowsHide: true });
+    if (result.error || result.status !== 0) {
+        const cause = result.error?.message ?? `exit status ${String(result.status)}`;
+        throw Object.assign(new Error(`Claude Code plugin command failed (${cause}). Ensure the Claude Code CLI is installed and try again.`), { expected: true });
+    }
+}
+function removePluginSettings(doc, plugin, removePlugin, removeMarketplace, pluginSettingBefore) {
+    const next = { ...doc };
+    const enabled = next.enabledPlugins;
+    if (removePlugin && enabled && typeof enabled === 'object' && !Array.isArray(enabled)) {
+        const entries = { ...enabled };
+        delete entries[plugin.pluginId];
+        if (pluginSettingBefore !== undefined)
+            entries[plugin.pluginId] = pluginSettingBefore;
+        if (Object.keys(entries).length === 0)
+            delete next.enabledPlugins;
+        else
+            next.enabledPlugins = entries;
+    }
+    const marketplaces = next.extraKnownMarketplaces;
+    if (marketplaces && typeof marketplaces === 'object' && !Array.isArray(marketplaces)) {
+        const entries = { ...marketplaces };
+        const registration = entries[plugin.marketplaceName];
+        if (removeMarketplace && registration?.source?.source === 'directory' && registration.source.path === plugin.sourceDir)
+            delete entries[plugin.marketplaceName];
+        if (Object.keys(entries).length === 0)
+            delete next.extraKnownMarketplaces;
+        else
+            next.extraKnownMarketplaces = entries;
+    }
+    return canonical(next) === canonical(doc) ? doc : next;
+}
 export { AnywhereRuntimeDisabledError as AnywhereDisabledError };
 export const isAnywhereEnabled = (_home, env = process.env) => anywhereRuntimeEnabled(env);
 function readOrNull(file) {
@@ -80,8 +141,9 @@ function settingsInstallFormat(hqRoot, target) {
  * Removal format: verifies no HQ hook remains, and serializes a doc that equals
  * the pre-install document back to the ORIGINAL bytes (byte-identical uninstall).
  */
-function settingsRemovalFormat(hqRoot, original) {
-    return restoringRemovalFormat(original, (doc) => removeHqHooks(doc, hqRoot) !== doc);
+function settingsRemovalFormat(hqRoots, original) {
+    const roots = Array.isArray(hqRoots) ? hqRoots : [hqRoots];
+    return restoringRemovalFormat(original, (doc) => roots.reduce((current, root) => removeHqHooks(current, root), doc) !== doc);
 }
 /** Shared removal format for a JSON hooks file (see settingsRemovalFormat). */
 function restoringRemovalFormat(original, stillPresent) {
@@ -153,6 +215,30 @@ function planSkills(hqRoot, t) {
     }
     return plan;
 }
+function hqSkillLinksForRoot(skillsDir, hqRoot) {
+    let names;
+    try {
+        names = fs.readdirSync(skillsDir).filter((name) => name.startsWith(SKILL_LINK_PREFIX));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return [];
+        throw error;
+    }
+    return names.filter((name) => {
+        const link = path.join(skillsDir, name);
+        try {
+            if (!fs.lstatSync(link).isSymbolicLink())
+                return false;
+            return path.dirname(path.resolve(skillsDir, fs.readlinkSync(link))) === hqSkillsSource(hqRoot);
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return false;
+            throw error;
+        }
+    }).map((name) => path.join(skillsDir, name));
+}
 function removeSeeded(seeded, regFile) {
     if (seeded.length === 0 || !fs.existsSync(regFile))
         return;
@@ -192,21 +278,58 @@ export function installGlobalClaude(opts) {
         throw new AnywhereRuntimeDisabledError();
     const t = claudeTargets(home);
     const prior = readState(t);
+    const pluginSource = opts.via === 'plugin' ? resolveClaudePluginSource(opts.marketplaceDir, env) : undefined;
+    if (prior?.plugin && !pluginSource) {
+        throw Object.assign(new Error('HQ is installed through a Claude plugin marketplace. Run `hq uninstall --global --runtime claude` before switching back to direct installation.'), { expected: true });
+    }
+    if (prior?.plugin && pluginSource && (prior.plugin.pluginId !== pluginSource.pluginId || prior.plugin.sourceDir !== pluginSource.sourceDir)) {
+        throw Object.assign(new Error('A different HQ Claude plugin marketplace is already recorded for this install. Uninstall it before changing marketplace source.'), { expected: true });
+    }
+    const runClaude = opts.runClaude ?? runClaudeCli;
     const regFile = opts.registryFile ?? registryFile(registryDir(home, env));
-    const manifest = mcpManifest(opts);
+    const manifest = pluginSource ? undefined : mcpManifest(opts);
     const touched = [];
     const pointerOld = readOrNull(t.hqPointer);
     const pointerNew = `${hqRoot}\n`;
     const mdOld = readOrNull(t.claudeMd);
-    const mdNew = addClaudeMdBlock(mdOld, hqRoot);
-    const skills = planSkills(hqRoot, t);
+    const legacyRoot = prior?.hqRoot ?? (pluginSource ? pointerOld?.trim() : undefined);
+    const cleanupRoots = [...new Set([hqRoot, ...(legacyRoot ? [legacyRoot] : [])])];
+    const mdOriginal = pluginSource
+        ? (prior && mdOld === prior.claudeMd.installed
+            ? prior.claudeMd.original
+            : mdOld === null ? null : (removeClaudeMdBlock(mdOld) || null))
+        : prior ? prior.claudeMd.original : mdOld;
+    const mdNew = pluginSource ? mdOriginal : addClaudeMdBlock(mdOld, hqRoot);
+    const skills = pluginSource ? { link: [], already: [], skipped: [] } : planSkills(hqRoot, t);
     const settingsOld = readOrNull(t.settingsJson);
     const settingsDoc = readConfigDoc(t.settingsJson, jsonFormat).doc;
+    const directHooksRemoved = pluginSource
+        ? cleanupRoots.reduce((doc, root) => removeHqHooks(doc, root), settingsDoc)
+        : settingsDoc;
+    const settingsOriginal = prior
+        ? prior.settings.original
+        : pluginSource && directHooksRemoved !== settingsDoc ? jsonFormat.serialize(directHooksRemoved) : settingsOld;
+    const enabledPlugins = settingsDoc.enabledPlugins;
+    const knownMarketplaces = settingsDoc.extraKnownMarketplaces;
+    const existingMarketplace = pluginSource ? knownMarketplaces?.[pluginSource.marketplaceName] : undefined;
+    if (pluginSource && existingMarketplace && (existingMarketplace.source?.source !== 'directory' || existingMarketplace.source.path !== pluginSource.sourceDir)) {
+        throw Object.assign(new Error(`Claude marketplace "${pluginSource.marketplaceName}" is already registered from a different source. Remove or rename that marketplace before installing HQ.`), { expected: true });
+    }
+    const hadPluginSetting = !!pluginSource && !!enabledPlugins && Object.prototype.hasOwnProperty.call(enabledPlugins, pluginSource.pluginId);
+    const currentPluginSetting = pluginSource && hadPluginSetting ? enabledPlugins[pluginSource.pluginId] : undefined;
+    const pluginSettingBefore = prior?.plugin ? prior.plugin.pluginSettingBefore : currentPluginSetting;
+    const pluginNeedsInstall = !!pluginSource && currentPluginSetting !== true;
+    const marketplaceNeedsAdd = !!pluginSource && existingMarketplace === undefined;
+    const pluginAdded = !!pluginSource && (prior?.plugin?.pluginAdded === true || pluginNeedsInstall);
+    const marketplaceAdded = !!pluginSource && (prior?.plugin?.marketplaceAdded === true || marketplaceNeedsAdd);
     const hookTarget = hookTargetFor(hqRoot, home, opts.daemonInstalled, env);
-    const settingsNext = addHqHooks(settingsDoc, hqRoot, hookTarget);
+    const settingsNext = pluginSource
+        ? cleanupRoots.reduce((doc, root) => removeHqHooks(doc, root), settingsDoc)
+        : addHqHooks(settingsDoc, hqRoot, hookTarget);
+    const skillLinksToRemove = pluginSource ? cleanupRoots.flatMap((root) => hqSkillLinksForRoot(t.skillsDir, root)) : [];
     const claudeDoc = readConfigDoc(t.claudeJson, claudeConfigFormat).doc;
     // Collision check runs here too, so a dry run surfaces a conflicting "hq" server.
-    const claudeNext = mergeClaudeServer(HQ_MCP_SERVER_NAME, {
+    const claudeNext = pluginSource ? claudeDoc : mergeClaudeServer(HQ_MCP_SERVER_NAME, {
         ...manifest,
         _hqPack: HQ_ANYWHERE_PACK,
     })(claudeDoc);
@@ -216,10 +339,13 @@ export function installGlobalClaude(opts) {
         touched.push(t.claudeMd);
     for (const s of skills.link)
         touched.push(path.join(t.skillsDir, `${SKILL_LINK_PREFIX}${s}`));
+    touched.push(...skillLinksToRemove);
     if (settingsNext !== settingsDoc)
         touched.push(t.settingsJson);
     if (claudeNext !== claudeDoc)
         touched.push(t.claudeJson);
+    if (pluginSource)
+        touched.push(t.settingsJson);
     touched.push(regFile, t.stateFile);
     if (opts.dryRun) {
         log(`hq install --global --runtime claude --dry-run (HQ root ${hqRoot})`);
@@ -233,23 +359,86 @@ export function installGlobalClaude(opts) {
         log(lineDiff(jsonFormat.serialize(settingsDoc), jsonFormat.serialize(settingsNext)));
         log(`\n--- ${t.claudeJson}`);
         log(lineDiff(jsonFormat.serialize(claudeDoc), jsonFormat.serialize(claudeNext)));
+        if (pluginSource)
+            log(`Would run: claude plugin marketplace add --scope user ${pluginSource.sourceDir}; claude plugin install --scope user -y ${pluginSource.pluginId}`);
         return touched;
     }
+    if (pluginSource && (marketplaceNeedsAdd || pluginNeedsInstall)) {
+        let marketplaceMayNeedRollback = false;
+        try {
+            if (marketplaceNeedsAdd) {
+                marketplaceMayNeedRollback = true;
+                runClaude(['marketplace', 'add', '--scope', 'user', '--json', pluginSource.sourceDir], home, env);
+            }
+            if (pluginNeedsInstall)
+                runClaude(['install', '--scope', 'user', '--json', '-y', pluginSource.pluginId], home, env);
+        }
+        catch (error) {
+            const rollbackErrors = [];
+            if (pluginNeedsInstall && pluginAdded) {
+                try {
+                    runClaude(['uninstall', '--scope', 'user', '--json', pluginSource.pluginId], home, env);
+                }
+                catch (rollbackError) {
+                    rollbackErrors.push(`plugin uninstall: ${rollbackError.message}`);
+                }
+            }
+            if (marketplaceMayNeedRollback) {
+                try {
+                    runClaude(['marketplace', 'remove', '--scope', 'user', '--json', pluginSource.marketplaceName], home, env);
+                }
+                catch (rollbackError) {
+                    rollbackErrors.push(`marketplace removal: ${rollbackError.message}`);
+                }
+            }
+            if (rollbackErrors.length > 0)
+                throw Object.assign(new Error(`Claude plugin installation failed and rollback was incomplete (${rollbackErrors.join('; ')})`), { cause: error, expected: true });
+            throw error;
+        }
+    }
     writeFileAtomic(t.hqPointer, pointerNew);
-    writeFileAtomic(t.claudeMd, mdNew);
-    fs.mkdirSync(t.skillsDir, { recursive: true });
+    if (mdOld !== mdNew) {
+        if (mdNew === null) {
+            if (fs.existsSync(t.claudeMd))
+                fs.unlinkSync(t.claudeMd);
+        }
+        else
+            writeFileAtomic(t.claudeMd, mdNew);
+    }
+    if (!pluginSource)
+        fs.mkdirSync(t.skillsDir, { recursive: true });
     for (const name of skills.link) {
         fs.symlinkSync(path.join(hqSkillsSource(hqRoot), name), path.join(t.skillsDir, `${SKILL_LINK_PREFIX}${name}`));
     }
-    writeConfigAtomic({
-        target: t.settingsJson,
-        pack: HQ_ANYWHERE_PACK,
-        format: settingsInstallFormat(hqRoot, hookTarget),
-        merge: (doc) => addHqHooks(doc, hqRoot, hookTarget),
-        assertName: 'hooks',
-        env: { home },
-    });
-    registerClaudeServer({ name: HQ_MCP_SERVER_NAME, manifest, pack: HQ_ANYWHERE_PACK, env: { home } });
+    if (pluginSource)
+        for (const link of skillLinksToRemove)
+            fs.unlinkSync(link);
+    if (pluginSource) {
+        // Migrate a prior direct install: remove only our old hook/MCP entries while
+        // retaining the original user settings for a later uninstall restore.
+        if (fs.existsSync(t.settingsJson)) {
+            writeConfigAtomic({
+                target: t.settingsJson,
+                pack: HQ_ANYWHERE_PACK,
+                format: settingsRemovalFormat(cleanupRoots, settingsOriginal),
+                merge: (doc) => cleanupRoots.reduce((current, root) => removeHqHooks(current, root), doc),
+                assertName: 'hooks',
+                env: { home },
+            });
+        }
+        unregisterClaudeServer({ name: HQ_MCP_SERVER_NAME, pack: HQ_ANYWHERE_PACK, env: { home } });
+    }
+    else {
+        writeConfigAtomic({
+            target: t.settingsJson,
+            pack: HQ_ANYWHERE_PACK,
+            format: settingsInstallFormat(hqRoot, hookTarget),
+            merge: (doc) => addHqHooks(doc, hqRoot, hookTarget),
+            assertName: 'hooks',
+            env: { home },
+        });
+        registerClaudeServer({ name: HQ_MCP_SERVER_NAME, manifest: manifest, pack: HQ_ANYWHERE_PACK, env: { home } });
+    }
     // Seeding is best-effort: the runtime wiring above is already in place, so a
     // missing or unreadable manifest is reported rather than aborting the install.
     let seeded = [];
@@ -262,25 +451,38 @@ export function installGlobalClaude(opts) {
     catch (e) {
         log(`Registry not seeded from companies/manifest.yaml: ${e.message}`);
     }
+    const recoveredDirectPointer = !!pluginSource && !prior && legacyRoot === pointerOld?.trim() && (directHooksRemoved !== settingsDoc || (mdOld !== null && removeClaudeMdBlock(mdOld) !== mdOld) || skillLinksToRemove.length > 0);
     const state = {
         version: 1,
         hqRoot,
         // A re-install keeps the FIRST install's originals so uninstall restores pre-HQ bytes.
-        hqPointer: { original: prior ? prior.hqPointer.original : pointerOld },
-        claudeMd: { original: prior ? prior.claudeMd.original : mdOld, installed: readOrNull(t.claudeMd) ?? '' },
-        settings: { original: prior ? prior.settings.original : settingsOld, installed: readOrNull(t.settingsJson) ?? '' },
+        hqPointer: { original: prior ? prior.hqPointer.original : recoveredDirectPointer ? null : pointerOld },
+        claudeMd: { original: mdOriginal, installed: readOrNull(t.claudeMd) ?? '' },
+        settings: { original: settingsOriginal, installed: readOrNull(t.settingsJson) ?? '' },
         skills: {
-            linked: [...new Set([...(prior?.skills.linked ?? []), ...skills.link, ...skills.already])].sort(),
+            linked: pluginSource ? [] : [...new Set([...(prior?.skills.linked ?? []), ...skills.link, ...skills.already])].sort(),
             skipped: skills.skipped,
         },
         mcp: { name: HQ_MCP_SERVER_NAME, pack: HQ_ANYWHERE_PACK },
+        ...(pluginSource ? { plugin: {
+                pluginId: pluginSource.pluginId,
+                marketplaceName: pluginSource.marketplaceName,
+                sourceDir: pluginSource.sourceDir,
+                pluginAdded,
+                marketplaceAdded,
+                ...(hadPluginSetting ? { pluginSettingBefore } : {}),
+            } } : {}),
         seeded: [...new Set([...(prior?.seeded ?? []), ...ownedSeeded])].sort(),
     };
     writeFileAtomic(t.stateFile, `${JSON.stringify(state, null, 2)}\n`);
     log(`HQ installed for Claude Code from ${hqRoot}.`);
     log(`  skills linked: ${skills.link.length} new, ${skills.already.length} already present, ${skills.skipped.length} skipped`);
-    log(`  hooks: ${hookTarget === 'shim' ? 'hqd-hook-shim.sh' : 'master-hook.sh'} registered in ${t.settingsJson}`);
-    log(`  MCP: "${HQ_MCP_SERVER_NAME}" registered in ${t.claudeJson}`);
+    if (pluginSource)
+        log(`  plugin: ${pluginSource.pluginId} installed from ${pluginSource.sourceDir}; direct hooks and MCP entries removed`);
+    else {
+        log(`  hooks: ${hookTarget === 'shim' ? 'hqd-hook-shim.sh' : 'master-hook.sh'} registered in ${t.settingsJson}`);
+        log(`  MCP: "${HQ_MCP_SERVER_NAME}" registered in ${t.claudeJson}`);
+    }
     log(`  registry: ${seeded.length} manifest entr${seeded.length === 1 ? 'y' : 'ies'} seeded`);
     return touched;
 }
@@ -294,6 +496,13 @@ export function uninstallGlobalClaude(opts = {}) {
     const hqRoot = state?.hqRoot ?? opts.hqRoot ?? readOrNull(t.hqPointer)?.trim();
     if (!hqRoot)
         throw new Error('No HQ global install found (no install state and no ~/.hq/root).');
+    const pluginSource = state?.plugin ? {
+        sourceDir: state.plugin.sourceDir,
+        marketplaceName: state.plugin.marketplaceName,
+        pluginName: state.plugin.pluginId.slice(0, state.plugin.pluginId.lastIndexOf('@')),
+        pluginId: state.plugin.pluginId,
+    } : undefined;
+    const runClaude = opts.runClaude ?? runClaudeCli;
     const regFile = opts.registryFile ?? registryFile(registryDir(home, env));
     const touched = [];
     // MCP server (provenance-scoped: a foreign "hq" server is never removed).
@@ -304,7 +513,9 @@ export function uninstallGlobalClaude(opts = {}) {
     // settings.json hooks.
     const settingsOriginal = state ? state.settings.original : null;
     const settingsDoc = readConfigDoc(t.settingsJson, jsonFormat).doc;
-    const settingsNext = removeHqHooks(settingsDoc, hqRoot);
+    const settingsNext = pluginSource
+        ? removePluginSettings(removeHqHooks(settingsDoc, hqRoot), pluginSource, state?.plugin?.pluginAdded ?? true, state?.plugin?.marketplaceAdded ?? true, state?.plugin?.pluginSettingBefore)
+        : removeHqHooks(settingsDoc, hqRoot);
     if (settingsNext !== settingsDoc)
         touched.push(t.settingsJson);
     // Skills: only symlinks that point into this HQ checkout's skills dir.
@@ -349,15 +560,27 @@ export function uninstallGlobalClaude(opts = {}) {
             log(`  ${f}`);
         log(`\n--- ${t.settingsJson}`);
         log(lineDiff(jsonFormat.serialize(settingsDoc), jsonFormat.serialize(settingsNext)));
+        if (pluginSource)
+            log(`Would run: ${state?.plugin?.pluginAdded ? `claude plugin uninstall --scope user ${pluginSource.pluginId}` : '(plugin was pre-existing; leave it installed)'}${state?.plugin?.marketplaceAdded ? `; claude plugin marketplace remove --scope user ${pluginSource.marketplaceName}` : ''}`);
         return touched;
     }
+    if (pluginSource && state?.plugin?.pluginAdded) {
+        runClaude(['uninstall', '--scope', 'user', '--json', pluginSource.pluginId], home, env);
+    }
+    if (pluginSource && state?.plugin?.marketplaceAdded) {
+        runClaude(['marketplace', 'remove', '--scope', 'user', '--json', pluginSource.marketplaceName], home, env);
+    }
     unregisterClaudeServer({ name: HQ_MCP_SERVER_NAME, pack: HQ_ANYWHERE_PACK, env: { home } });
     if (fs.existsSync(t.settingsJson)) {
         writeConfigAtomic({
             target: t.settingsJson,
             pack: HQ_ANYWHERE_PACK,
-            format: settingsRemovalFormat(hqRoot, settingsOriginal),
-            merge: (doc) => removeHqHooks(doc, hqRoot),
+            format: restoringRemovalFormat(settingsOriginal, (doc) => (pluginSource
+                ? removePluginSettings(removeHqHooks(doc, hqRoot), pluginSource, state?.plugin?.pluginAdded ?? true, state?.plugin?.marketplaceAdded ?? true, state?.plugin?.pluginSettingBefore) !== doc
+                : removeHqHooks(doc, hqRoot) !== doc)),
+            merge: (doc) => pluginSource
+                ? removePluginSettings(removeHqHooks(doc, hqRoot), pluginSource, state?.plugin?.pluginAdded ?? true, state?.plugin?.marketplaceAdded ?? true, state?.plugin?.pluginSettingBefore)
+                : removeHqHooks(doc, hqRoot),
             assertName: 'hooks',
             env: { home },
         });
@@ -393,7 +616,7 @@ export function uninstallGlobalClaude(opts = {}) {
                 throw e;
         }
     }
-    log(`HQ removed from Claude Code user scope (${links.length} skill link(s), hooks, MCP server, CLAUDE.md block).`);
+    log(`HQ removed from Claude Code user scope (${links.length} skill link(s), ${pluginSource ? 'plugin' : 'hooks and MCP server'}, CLAUDE.md block).`);
     return touched;
 }
 function readCodexState(t) {
@@ -686,8 +909,8 @@ export function uninstallGlobalCodex(opts = {}) {
 }
 function assertRuntime(runtime) {
     const r = runtime ?? 'claude';
-    if (r !== 'claude' && r !== 'codex') {
-        throw Object.assign(new Error(`--runtime ${r} is not supported. Use --runtime claude or --runtime codex.`), {
+    if (r !== 'claude' && r !== 'codex' && r !== 'chatgpt' && r !== 'grok') {
+        throw Object.assign(new Error(`--runtime ${r} is not supported. Use --runtime claude, codex, chatgpt, or grok.`), {
             expected: true,
         });
     }
@@ -704,8 +927,17 @@ function resolveInstallRoot(explicit) {
 /** Entry used by `hq install --global` (wired from pkg-install.ts). */
 export function runInstallGlobal(opts) {
     const runtime = assertRuntime(opts.runtime);
+    if (runtime === 'chatgpt' || runtime === 'grok') {
+        if (!anywhereRuntimeEnabled(opts.env ?? process.env))
+            throw new AnywhereRuntimeDisabledError();
+        const endpoint = resolveHqMcpEndpoint(opts.env ?? process.env).toString();
+        const lines = runtime === 'chatgpt' ? chatgptConnectorInstructions(endpoint) : grokConnectorInstructions(endpoint);
+        for (const line of lines)
+            (opts.log ?? console.log)(line);
+        return;
+    }
     const install = runtime === 'codex' ? installGlobalCodex : installGlobalClaude;
-    install({ hqRoot: resolveInstallRoot(opts.hqRoot), dryRun: opts.dryRun });
+    install({ hqRoot: resolveInstallRoot(opts.hqRoot), dryRun: opts.dryRun, via: opts.via, marketplaceDir: opts.marketplaceDir });
 }
 export function registerUninstallCommand(program) {
     program
@@ -721,7 +953,10 @@ export function registerUninstallCommand(program) {
             process.exitCode = 1;
             return;
         }
-        const runtime = assertRuntime(opts.runtime);
+        const runtime = opts.runtime ?? 'claude';
+        if (runtime !== 'claude' && runtime !== 'codex') {
+            throw Object.assign(new Error(`--runtime ${runtime} has no local configuration to uninstall; remove its connector in the host application.`), { expected: true });
+        }
         const uninstall = runtime === 'codex' ? uninstallGlobalCodex : uninstallGlobalClaude;
         uninstall({ hqRoot: opts.hqRoot, dryRun: opts.dryRun });
     });