@indigoai-us/hq-cli 5.50.0 → 5.50.2

package/dist/commands/packs.js

@@ -18,7 +18,7 @@
  * Spec: knowledge/public/hq-core/package-yaml-spec.md.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="527d0e7d-2101-5438-8251-2579a40453e6")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="69746edd-f9d8-528e-8902-de799c58bd8a")}catch(e){}}();
 import * as fs from 'fs';
 import * as path from 'path';
 import * as readline from 'readline';
@@ -27,7 +27,7 @@ import chalk from 'chalk';
 import semverSatisfies from 'semver/functions/satisfies.js';
 import { findHqRoot } from '../utils/manifest.js';
 import { classify, resolveLatest, resolveLatestMarketplace, runScanPackages, installPack, } from './pack-install.js';
-import { contributionLinks, linkStatus, listInstalledPacks, readPackManifest, unwirePack, readHqVersion, readRecommendedPackages, packagesDir, } from '../utils/pack-contributions.js';
+import { contributionLinks, linkStatus, listInstalledPacks, findDependentPacks, readPackManifest, unwirePack, unwirePackMcp, readHqVersion, readRecommendedPackages, packagesDir, } from '../utils/pack-contributions.js';
 function resolveRoot(opts) {
     return opts.hqRoot ? path.resolve(opts.hqRoot) : findHqRoot();
 }
@@ -246,6 +246,7 @@ async function runUpdate(name, opts) {
             try {
                 await installPack(source, {
                     allowHooks: opts.yes || opts.allowHooks,
+                    allowMcp: opts.yes || opts.allowMcp,
                     followBranch: opts.branch,
                     quiet: wantsJson(opts),
                 });
@@ -277,8 +278,43 @@ async function runUninstall(name, opts) {
     if (!manifest) {
         warnings.push('package.yaml unreadable -- host symlinks could not be computed precisely; ran a re-scan to reconcile.');
     }
+    // 0. Dependents guard (M0): refuse to remove a pack that another installed pack
+    // lists in its `requires.packs`, unless --force. Filesystem presence is the
+    // source of truth (listInstalledPacks), consistent with the install-time
+    // assertPackDependencies check. Runs BEFORE any un-wiring so a blocked uninstall
+    // leaves the pack fully intact.
+    if (!opts.force) {
+        const dependents = findDependentPacks(listInstalledPacks(hqRoot), name);
+        if (dependents.length > 0) {
+            const who = dependents.map((p) => p.manifest?.name ?? p.name).join(', ');
+            throw new Error(`Cannot uninstall "${name}": required by ${who}. ` +
+                `Uninstall the dependent pack(s) first, or pass --force to override.`);
+        }
+    }
     // 1. Un-wire only our symlinks.
     const { unlinked, skipped } = unwirePack(hqRoot, packDir, contributes);
+    // 1b. Un-register the pack's MCP (`wire: 'merge'`) servers — invisible to the
+    // symlink unwire above. Provenance-scoped: removes ONLY entries stamped with this
+    // pack's `_hqPack`, and skip-and-warns on any foreign/unstamped same-named entry.
+    // Tolerant of a Codex-less host / absent config; idempotent on re-run.
+    try {
+        const mcp = unwirePackMcp(name, contributes);
+        for (const server of mcp.servers) {
+            if ('skipped' in server.claude)
+                continue; // (claude is always inspected; never skipped)
+            if (server.claude.outcome === 'skipped-foreign' && server.claude.reason) {
+                warnings.push(server.claude.reason);
+            }
+            if (!('skipped' in server.codex) && server.codex.outcome === 'skipped-foreign' && server.codex.reason) {
+                warnings.push(server.codex.reason);
+            }
+        }
+    }
+    catch (e) {
+        // Never let an MCP un-registration failure abort the rest of the uninstall
+        // (symlink unwire already ran; the pack dir still gets archived). Surface it.
+        warnings.push(`MCP un-registration encountered an error: ${e.message}`);
+    }
     // 2. Archive (or delete) the pack dir -- BEFORE re-scan so it isn't re-wired.
     let archived = null;
     if (opts.archive === false) {
@@ -358,8 +394,9 @@ export function registerPacksCommand(parent) {
         .option('--json', 'Machine-readable JSON output')
         .option('--hq-root <path>', 'HQ root (default: auto-detect)')
         .option('--check-only', 'Report availability without installing')
-        .option('-y, --yes', 'Non-interactive (implies --allow-hooks)')
+        .option('-y, --yes', 'Non-interactive (implies --allow-hooks and --allow-mcp)')
         .option('--allow-hooks', 'Install pack hooks without prompting')
+        .option('--allow-mcp', 'Register pack MCP servers without prompting')
         .option('--branch', 'Follow the source branch instead of SHA-pinning')
         .action(async (name, opts) => {
         try {
@@ -393,6 +430,7 @@ export function registerPacksCommand(parent) {
         .option('--hq-root <path>', 'HQ root (default: auto-detect)')
         .option('-y, --yes', 'Skip confirmation')
         .option('--no-archive', 'Delete instead of archiving')
+        .option('--force', 'Uninstall even if other installed packs require this one')
         .action(async (name, opts) => {
         try {
             if (!opts.yes) {
@@ -425,4 +463,4 @@ export function registerPacksCommand(parent) {
     });
 }
 //# sourceMappingURL=packs.js.map
-//# debugId=527d0e7d-2101-5438-8251-2579a40453e6
+//# debugId=69746edd-f9d8-528e-8902-de799c58bd8a

package/dist/commands/pkg-install.js

@@ -13,7 +13,7 @@
  * 9. Print next-step message
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="ac6f26b7-5678-5b4e-b0d8-2f5901adf9fe")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="ccc2e70c-f577-5a47-9a29-31a206194392")}catch(e){}}();
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
@@ -33,12 +33,14 @@ export function registerPackageInstallCommand(parent) {
         '@scope/name[@ver] (npm pack), git URL[#ref], or local path.')
         .option('--company <co>', 'Scope the package to a specific company (registry flow only)')
         .option('--allow-hooks', 'Skip the hooks confirmation prompt (content-pack flow)')
+        .option('--allow-mcp', 'Skip the MCP server confirmation prompt (content-pack flow)')
         .option('--branch', 'Follow a ref instead of SHA-pinning (git content-pack flow)')
         .action(async (source, opts) => {
         try {
             if (sourceMatchesPackPattern(source)) {
                 await installPack(source, {
                     allowHooks: opts.allowHooks,
+                    allowMcp: opts.allowMcp,
                     followBranch: opts.branch,
                 });
             }
@@ -49,6 +51,7 @@ export function registerPackageInstallCommand(parent) {
                 // listings transport — the live install path — instead.
                 await installPack(`${MARKETPLACE_PREFIX}${source}`, {
                     allowHooks: opts.allowHooks,
+                    allowMcp: opts.allowMcp,
                     followBranch: opts.branch,
                 });
             }
@@ -163,4 +166,4 @@ async function installPackage(slug, company) {
     }
 }
 //# sourceMappingURL=pkg-install.js.map
-//# debugId=ac6f26b7-5678-5b4e-b0d8-2f5901adf9fe
+//# debugId=ccc2e70c-f577-5a47-9a29-31a206194392

package/dist/index.js

@@ -3,7 +3,7 @@
  * HQ CLI - Module management, package management, and cloud sync for HQ
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="d57c1cc3-6dd3-5c7f-8eef-c7692d41b836")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="34e9e978-4c0a-5113-82af-9a33e30686c6")}catch(e){}}();
 import { Command } from "commander";
 import { initSentry, Sentry } from "./sentry.js";
 import { registerAddCommand } from "./commands/add.js";
@@ -44,6 +44,7 @@ import { registerSourcesCommand } from "./commands/sources.js";
 import { registerSignalsCommand } from "./commands/signals.js";
 import { registerReindexCommand } from "./commands/reindex.js";
 import { registerRescueCommand } from "./commands/rescue.js";
+import { registerMcpCommand } from "./commands/mcp-status.js";
 import { sanitizeArgv } from "./utils/feedback-diagnostics.js";
 import { environmentalFsErrorMessage } from "./utils/environmental-error.js";
 import { maybeWarnNewVersion, refreshVersionCache, } from "./utils/version-check.js";
@@ -159,6 +160,10 @@ registerReindexCommand(program);
 // the HQ Sync app's "Update / Restore" pill; drives the same replace-rescue.sh
 // shipped from @indigoai-us/hq-cloud.
 registerRescueCommand(program);
+// MCP pack observability (subcommand group — `hq mcp status`). Read-only
+// provenance-based status across BOTH Claude + Codex runtimes (reads `_hqPack`
+// off the configs, NOT linkStatus), with secret-redacted output + `--json`.
+registerMcpCommand(program);
 (async () => {
     try {
         Sentry.addBreadcrumb({
@@ -198,4 +203,4 @@ registerRescueCommand(program);
     }
 })();
 //# sourceMappingURL=index.js.map
-//# debugId=d57c1cc3-6dd3-5c7f-8eef-c7692d41b836
+//# debugId=34e9e978-4c0a-5113-82af-9a33e30686c6

package/dist/types.d.ts

@@ -7,6 +7,7 @@
  *                            (new in hq-core v12.0.0; see
  *                            knowledge/public/hq-core/package-yaml-spec.md)
  */
+import type { ContributionKey } from './utils/contribution-table.js';
 export type LegacyStrategy = 'link' | 'merge' | 'copy';
 export type SyncStrategy = LegacyStrategy | 'package';
 export type AccessLevel = 'public' | 'team' | `role:${string}`;
@@ -56,7 +57,13 @@ export interface SyncResult {
     message?: string;
     filesChanged?: number;
 }
-export type PackContributeKey = 'workers' | 'knowledge' | 'skills' | 'commands' | 'hooks' | 'policies' | 'scripts';
+/**
+ * The `contributes.*` keys a pack may declare. DERIVED (US-003) from the single
+ * declarative contribution registry in `utils/contribution-table.ts` -- adding
+ * a contribution type is one row there, and this union updates automatically.
+ * Do NOT restate the keys here.
+ */
+export type PackContributeKey = ContributionKey;
 /**
  * Pack authorship attribution (US-001). OPTIONAL and backwards-compatible —
  * packs published before this field still validate. When present, install can
@@ -68,13 +75,31 @@ export interface PackAuthor {
     handle: string;
     displayName: string;
 }
+/**
+ * A pack-to-pack dependency (M0). OPTIONAL and backwards-compatible — packs
+ * published before this field omit `requires.packs` and install unchanged. When
+ * present, each entry names another content pack that MUST already be installed
+ * before this one (enforced at install time by `assertPackDependencies`, which
+ * tracks installed packs by FILESYSTEM PRESENCE — not `modules.yaml`). `version`
+ * is an optional semver RANGE the installed dependency must satisfy.
+ */
+export interface PackDependency {
+    name: string;
+    version?: string;
+}
 export interface PackManifest {
     name: string;
     version: string;
     publisher: string;
     access: 'public' | 'private';
+    /**
+     * Host + pack prerequisites. `hqCore` is a required semver RANGE the host HQ
+     * must satisfy. `packs` (M0) is an OPTIONAL list of other content packs that
+     * must be installed first — see PackDependency.
+     */
     requires: {
         hqCore: string;
+        packs?: PackDependency[];
     };
     contributes: Partial<Record<PackContributeKey, string[]>>;
     description?: string;

package/dist/utils/contribution-table.d.ts

@@ -0,0 +1,103 @@
+/**
+ * The contribution registry -- the SINGLE declarative source of truth (US-003)
+ * for the `contributes.* -> host` mapping. Every other surface DERIVES from
+ * this table:
+ *
+ *   - `PackContributeKey` (types.ts)              = `keyof typeof CONTRIBUTION_TABLE`
+ *   - `linkFor` / `contributionLinks`             read `payload` + `host`
+ *   - `validateManifest`'s payload check          reads `payload`
+ *   - `core/scripts/scan-packages.sh`             reads a data block GENERATED
+ *                                                 from this table
+ *                                                 (scripts/generate-scan-packages-table.mjs)
+ *
+ * Adding a contribution type is ONE row here, not a five-site edit. The parity
+ * test (`pack-contributions.test.ts`) asserts every surface agrees on the full
+ * key-set, the payload suffix, and the wire mode.
+ *
+ * Row fields:
+ *   - `payload`: path INSIDE the pack, with the literal token `{item}` for the
+ *     declared name. The suffix after `{item}` (e.g. `.md`, `.json`, or none)
+ *     IS the load-bearing per-key shape.
+ *   - `host`: for `wire: 'symlink'`, the host DIRECTORY (relative to the HQ
+ *     root) the symlink is created under -- the symlink dst is
+ *     `<host>/<expanded-item-basename>`. For `wire: 'merge'`, a non-path
+ *     SENTINEL describing the merge target (e.g. `merge:claude+codex`); it is
+ *     NEVER used as a filesystem path.
+ *   - `wire`: `symlink` (a single `ln -s` into `host`) or `merge` (merged into
+ *     a shared host config; see US-004/US-005). Symlink-only readers MUST skip
+ *     `merge` rows.
+ *
+ * NOTE: the `mcp` row is DECLARED here as data only. US-003 does NOT wire any
+ * MCP behavior -- the merge engine lands in US-004/US-005. Declaring it now
+ * makes the table the single source so adding the merge wiring is a code change
+ * against an already-present row, and the parity test guards it from day one.
+ */
+export type WireMode = 'symlink' | 'merge';
+export interface ContributionRow {
+    /** Path inside the pack, with `{item}` substituted for the declared name. */
+    payload: string;
+    /**
+     * `wire: 'symlink'` -> host directory the symlink lives under (HQ-root
+     * relative). `wire: 'merge'` -> a non-path sentinel for the merge target.
+     */
+    host: string;
+    wire: WireMode;
+}
+/**
+ * The 8-key contribution registry. `as const` so `keyof typeof` yields the
+ * exact literal key union consumed by `PackContributeKey`.
+ */
+export declare const CONTRIBUTION_TABLE: {
+    readonly workers: {
+        readonly payload: "workers/{item}";
+        readonly host: "core/workers/public";
+        readonly wire: "symlink";
+    };
+    readonly knowledge: {
+        readonly payload: "knowledge/{item}";
+        readonly host: "core/knowledge/public";
+        readonly wire: "symlink";
+    };
+    readonly skills: {
+        readonly payload: "skills/{item}";
+        readonly host: ".claude/skills";
+        readonly wire: "symlink";
+    };
+    readonly commands: {
+        readonly payload: "commands/{item}.md";
+        readonly host: ".claude/commands";
+        readonly wire: "symlink";
+    };
+    readonly hooks: {
+        readonly payload: "hooks/{item}.sh";
+        readonly host: ".claude/hooks";
+        readonly wire: "symlink";
+    };
+    readonly policies: {
+        readonly payload: "policies/{item}.md";
+        readonly host: "core/policies";
+        readonly wire: "symlink";
+    };
+    readonly scripts: {
+        readonly payload: "scripts/{item}";
+        readonly host: "core/scripts";
+        readonly wire: "symlink";
+    };
+    readonly mcp: {
+        readonly payload: "mcp/{item}.json";
+        readonly host: "merge:claude+codex";
+        readonly wire: "merge";
+    };
+};
+/** The declared contribution keys, derived once from the table. */
+export type ContributionKey = keyof typeof CONTRIBUTION_TABLE;
+/** All contribution keys, in declaration order. */
+export declare const CONTRIBUTION_KEYS: ContributionKey[];
+/**
+ * Expand a row's `payload` template for a concrete item name. Returns the
+ * pack-relative path of the contribution's payload (e.g. `commands/foo.md`).
+ */
+export declare function payloadFor(key: ContributionKey, item: string): string;
+/** Keys whose contributions are wired by a host symlink (skip `merge` rows). */
+export declare const SYMLINK_KEYS: ("workers" | "knowledge" | "skills" | "commands" | "hooks" | "policies" | "scripts" | "mcp")[];
+//# sourceMappingURL=contribution-table.d.ts.map

package/dist/utils/contribution-table.js

@@ -0,0 +1,65 @@
+/**
+ * The contribution registry -- the SINGLE declarative source of truth (US-003)
+ * for the `contributes.* -> host` mapping. Every other surface DERIVES from
+ * this table:
+ *
+ *   - `PackContributeKey` (types.ts)              = `keyof typeof CONTRIBUTION_TABLE`
+ *   - `linkFor` / `contributionLinks`             read `payload` + `host`
+ *   - `validateManifest`'s payload check          reads `payload`
+ *   - `core/scripts/scan-packages.sh`             reads a data block GENERATED
+ *                                                 from this table
+ *                                                 (scripts/generate-scan-packages-table.mjs)
+ *
+ * Adding a contribution type is ONE row here, not a five-site edit. The parity
+ * test (`pack-contributions.test.ts`) asserts every surface agrees on the full
+ * key-set, the payload suffix, and the wire mode.
+ *
+ * Row fields:
+ *   - `payload`: path INSIDE the pack, with the literal token `{item}` for the
+ *     declared name. The suffix after `{item}` (e.g. `.md`, `.json`, or none)
+ *     IS the load-bearing per-key shape.
+ *   - `host`: for `wire: 'symlink'`, the host DIRECTORY (relative to the HQ
+ *     root) the symlink is created under -- the symlink dst is
+ *     `<host>/<expanded-item-basename>`. For `wire: 'merge'`, a non-path
+ *     SENTINEL describing the merge target (e.g. `merge:claude+codex`); it is
+ *     NEVER used as a filesystem path.
+ *   - `wire`: `symlink` (a single `ln -s` into `host`) or `merge` (merged into
+ *     a shared host config; see US-004/US-005). Symlink-only readers MUST skip
+ *     `merge` rows.
+ *
+ * NOTE: the `mcp` row is DECLARED here as data only. US-003 does NOT wire any
+ * MCP behavior -- the merge engine lands in US-004/US-005. Declaring it now
+ * makes the table the single source so adding the merge wiring is a code change
+ * against an already-present row, and the parity test guards it from day one.
+ */
+/**
+ * The 8-key contribution registry. `as const` so `keyof typeof` yields the
+ * exact literal key union consumed by `PackContributeKey`.
+ */
+
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="154fb78d-60ba-508f-b6e7-6889858f1841")}catch(e){}}();
+export const CONTRIBUTION_TABLE = {
+    workers: { payload: 'workers/{item}', host: 'core/workers/public', wire: 'symlink' },
+    knowledge: { payload: 'knowledge/{item}', host: 'core/knowledge/public', wire: 'symlink' },
+    skills: { payload: 'skills/{item}', host: '.claude/skills', wire: 'symlink' },
+    commands: { payload: 'commands/{item}.md', host: '.claude/commands', wire: 'symlink' },
+    hooks: { payload: 'hooks/{item}.sh', host: '.claude/hooks', wire: 'symlink' },
+    policies: { payload: 'policies/{item}.md', host: 'core/policies', wire: 'symlink' },
+    scripts: { payload: 'scripts/{item}', host: 'core/scripts', wire: 'symlink' },
+    // wire:merge -- DECLARED as data (US-003); the merge engine ships in
+    // US-004/US-005. Symlink readers skip this row.
+    mcp: { payload: 'mcp/{item}.json', host: 'merge:claude+codex', wire: 'merge' },
+};
+/** All contribution keys, in declaration order. */
+export const CONTRIBUTION_KEYS = Object.keys(CONTRIBUTION_TABLE);
+/**
+ * Expand a row's `payload` template for a concrete item name. Returns the
+ * pack-relative path of the contribution's payload (e.g. `commands/foo.md`).
+ */
+export function payloadFor(key, item) {
+    return CONTRIBUTION_TABLE[key].payload.replace('{item}', item);
+}
+/** Keys whose contributions are wired by a host symlink (skip `merge` rows). */
+export const SYMLINK_KEYS = CONTRIBUTION_KEYS.filter((k) => CONTRIBUTION_TABLE[k].wire === 'symlink');
+//# sourceMappingURL=contribution-table.js.map
+//# debugId=154fb78d-60ba-508f-b6e7-6889858f1841

package/dist/utils/pack-contributions.d.ts

@@ -1,22 +1,65 @@
 /**
- * Content-pack contribution helpers -- the single source of truth (in TS) for
- * the `contributes.* -> host-path` symlink mapping that `hq install` wires via
+ * Content-pack contribution helpers -- the SINGLE SOURCE OF TRUTH (US-003) for
+ * the `contributes.* -> host` mapping that `hq install` wires via
  * `core/scripts/scan-packages.sh`.
  *
  * `pack-install.ts` only INSTALLS content packs (into `core/packages/<name>/`,
  * tracked by filesystem presence -- there is no registry file). The list /
  * update / uninstall lifecycle in `commands/packs.ts` needs to reason about the
  * SAME mapping so it can report link health and cleanly un-wire a pack without
- * leaving dangling symlinks. That mapping is duplicated today in two places:
+ * leaving dangling symlinks.
  *
- *   - core/scripts/scan-packages.sh  (bash `case`, the wiring authority)
- *   - pack-install.ts validateManifest's `subpaths` record (payload validation)
+ * Historically that mapping was RESTATED in five places (the scan-packages.sh
+ * bash `case`, pack-install.ts:validateManifest's `subpaths` record,
+ * `linkFor`'s switch, `contributionLinks`, and the `PackContributeKey` union),
+ * drift-guarded only by a substring check. US-003 collapses it to ONE
+ * declarative table -- `CONTRIBUTION_TABLE` below -- with a row per key
+ * `{ payload, host, wire }`:
  *
- * This module re-encodes it once for TS callers. A parity test
- * (`pack-contributions.test.ts`) asserts it matches scan-packages.sh's `case`
- * arms so the three copies cannot drift.
+ *   - `PackContributeKey` is DERIVED from the table keys (see types.ts).
+ *   - `linkFor` / `contributionLinks` / the `subpaths` validator READ the table.
+ *   - `core/scripts/scan-packages.sh` reads a generated data block emitted from
+ *     this same table (regenerate via `scripts/generate-scan-packages-table.mjs`).
+ *
+ * A parity test (`pack-contributions.test.ts`) asserts FULL key-set +
+ * payload-suffix + wire-mode equivalence across every surface, so the copies
+ * cannot drift.
+ *
+ * `wire` discriminates HOW a contribution reaches the host:
+ *   - `symlink`: a single `ln -s` into a well-known host directory (every
+ *     contribution type that shipped before MCP).
+ *   - `merge`: the contribution is MERGED into a shared host config rather than
+ *     symlinked (the `mcp` row -- registered into the Claude + Codex agent
+ *     configs). The merge WIRING is delivered in US-004/US-005; US-003 only
+ *     DECLARES the row as data so the table is the single source and the parity
+ *     test guards the real invariant. `symlink`-only readers (linkFor,
+ *     contributionLinks, the symlink validator, scan-packages) must SKIP
+ *     `merge` rows -- they never produce a symlink.
  */
 import type { PackManifest, PackContributeKey } from '../types.js';
+import { CONTRIBUTION_TABLE, type WireMode } from './contribution-table.js';
+import { type UnregisterServerResult, type SafeWriteEnv, type AcquireLockOptions } from '../commands/mcp-registration.js';
+export { CONTRIBUTION_TABLE };
+export type { WireMode };
+/**
+ * Where a contributes key is ROUTED (US-005). Reads the single-source table's
+ * `wire` field — `'symlink'` keys go through `linkFor`/`contributionLinks` (a
+ * host `ln -s`); `'merge'` keys (e.g. `mcp`) go through the `registerMcpServers`
+ * seam in `commands/mcp-registration.ts` and are NEVER symlinked.
+ *
+ * This is the explicit, code-enforced discriminator behind the invariant that
+ * merge keys never reach the symlink path: callers fan out on the return value
+ * rather than relying on `linkFor` happening to return `null`.
+ */
+export declare function routeContribution(key: PackContributeKey): WireMode;
+/**
+ * The subset of a pack's declared `contributes` keys that are `wire: 'merge'`
+ * (e.g. `mcp`) — the keys that MUST be routed to `registerMcpServers` (US-006)
+ * and MUST NOT be symlinked. Unknown keys and non-array/empty values are
+ * ignored, mirroring `contributionLinks`. Returned in `contributes` iteration
+ * order, de-duplicated.
+ */
+export declare function mergeKeys(contributes: Partial<Record<PackContributeKey, string[]>>): PackContributeKey[];
 /** A single symlink a pack contributes: dst (host path) -> src (inside pack). */
 export interface WiredLink {
     key: PackContributeKey;
@@ -26,8 +69,10 @@ export interface WiredLink {
 }
 export type LinkStatus = 'live' | 'broken' | 'missing' | 'foreign';
 /**
- * Every symlink a pack's `contributes` block declares. Empty subfields and
- * non-array values are ignored, mirroring scan-packages.sh.
+ * Every SYMLINK a pack's `contributes` block declares. Empty subfields and
+ * non-array values are ignored, mirroring scan-packages.sh. `wire: 'merge'`
+ * keys (e.g. `mcp`) produce no symlink and are skipped here -- their host
+ * effect (a config merge) is handled separately (US-004/US-005).
  */
 export declare function contributionLinks(hqRoot: string, packDir: string, contributes: Partial<Record<PackContributeKey, string[]>>): WiredLink[];
 /** Classify a host path against the link that should own it. */
@@ -55,6 +100,13 @@ export declare function readPackManifest(packDir: string): {
  * of truth for installed content packs.
  */
 export declare function listInstalledPacks(hqRoot: string): InstalledPack[];
+/**
+ * Installed packs that declare `name` in their `requires.packs` (M0). Pure over
+ * the supplied list — the uninstall dependents guard calls this with
+ * `listInstalledPacks(hqRoot)`. Excludes the pack named `name` itself, so a
+ * self-reference never counts as its own dependent.
+ */
+export declare function findDependentPacks(installed: InstalledPack[], name: string): InstalledPack[];
 export interface UnwireResult {
     unlinked: Array<{
         key: PackContributeKey;
@@ -75,6 +127,37 @@ export interface UnwireResult {
  * uninstall from leaving dangling symlinks behind.
  */
 export declare function unwirePack(hqRoot: string, packDir: string, contributes: Partial<Record<PackContributeKey, string[]>>): UnwireResult;
+/** The result of {@link unwirePackMcp}: the per-server un-registration outcomes (empty when no `mcp` keys). */
+export interface UnwireMcpResult {
+    /** One {@link UnregisterServerResult} per declared `contributes.mcp` server, in declaration order. */
+    servers: UnregisterServerResult[];
+}
+/** Tuning passthrough for {@link unwirePackMcp} (tests inject a tmpdir `env.home` + tiny lock timeouts). */
+export interface UnwirePackMcpOptions {
+    /** Injectable env — tests MUST pass a tmpdir `home` so the real ~/.claude.json / ~/.codex are untouched. */
+    env?: Partial<SafeWriteEnv>;
+    /** Lock tuning (tests use tiny timeouts). */
+    lock?: AcquireLockOptions;
+    /** Backup timestamp override (deterministic tests). */
+    stamp?: string;
+}
+/**
+ * Un-register the `wire: 'merge'` (MCP) servers a pack declares — the parallel to
+ * {@link unwirePack}'s symlink removal. For each name in `mergeKeys(contributes)` →
+ * `contributes.<mergeKey>` (today only `mcp`), this delegates to
+ * {@link unregisterMcpServers}, which removes ONLY entries stamped with THIS pack's
+ * `_hqPack` provenance and SKIPS-AND-WARNS on a foreign/unstamped same-named entry.
+ *
+ * No-ops cleanly when the pack declares no merge keys (returns `{ servers: [] }`),
+ * when the runtime config is absent (Codex-less host → first-class skip; missing
+ * ~/.claude.json → `absent`), and on a re-run (already-removed → `absent`). It does
+ * NOT throw on a foreign entry — uninstall of one pack must not abort on a server
+ * another pack (or the user) owns.
+ *
+ * @param packName    the pack being uninstalled — the provenance to match
+ * @param contributes the pack's `contributes` block (its `mcp` list drives removal)
+ */
+export declare function unwirePackMcp(packName: string, contributes: Partial<Record<PackContributeKey, string[]>>, options?: UnwirePackMcpOptions): UnwireMcpResult;
 export declare function readHqVersion(hqRoot: string): string | null;
 export interface CatalogEntry {
     source: string;