@indigoai-us/hq-cli 5.85.2 → 5.86.0

package/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 ## [Unreleased]
 
+## [5.86.0]
+
+### Added
+
+- Added `hq search` and `hq index` commands for keyword, semantic, and hybrid
+  search across reconciled QMD collections, with explicit opt-in embedding and
+  package-local QMD resolution. Registered unmanaged collections remain
+  untouched and are reported as `registered (unmanaged)`. (#306)
+
+## [5.85.3]
+
+### Changed
+
+- The shared-mode sync nudge is now size-gated: it appears only once a
+  company's local folder crosses ~5 GiB (overridable via
+  `HQ_SYNC_NARROW_HINT_MIN_BYTES` or `.hq/config.json`
+  `syncNarrowHintMinBytes`), instead of nudging every all-mode member toward
+  shared mode. Below the threshold an all-mode membership is left alone — no
+  banner, and in strict mode no refusal. `hq sync mode` now also reports `all`
+  (the effective default) rather than `shared` when a config fetch fails.
+  (#303)
+
 ## [5.85.2]
 
 ### Fixed

package/dist/commands/cloud.js

@@ -17,7 +17,7 @@ import * as fs from "fs";
 import * as path from "path";
 import { share, sync, getStateDir, listJournals, loadCachedTokens, VaultClient, computePersonalVaultPaths, PERSONAL_VAULT_JOURNAL_SLUG, resolvePullScope, } from "@indigoai-us/hq-cloud";
 import { DEFAULT_HQ_ROOT, ensureCognitoToken, buildVaultConfig, } from "../utils/cognito-session.js";
-import { emitNarrowHint, isStrictRefusal, resolveBannerLevel, } from "../lib/narrow-hint-banner.js";
+import { companyFolderExceedsThreshold, emitNarrowHint, isStrictRefusal, resolveBannerLevel, resolveNarrowHintMinBytes, } from "../lib/narrow-hint-banner.js";
 /**
  * Build a loud, human-readable warning when a push dropped files because
  * they fell outside the caller's granted write scope. Returns null when
@@ -116,6 +116,26 @@ function readScopeExcludePrefixes(scope) {
     const prefixes = raw.filter((p) => typeof p === "string" && p.length > 0);
     return prefixes.length > 0 ? prefixes : undefined;
 }
+/**
+ * The size gate for the narrow-mode nudge. `all` is the default sync mode, so
+ * an all-mode membership is nudged toward shared mode ONLY once its local
+ * `companies/<slug>/` folder crosses the configured byte threshold (default
+ * 5 GiB). Below that, all-mode is left alone — no banner, and (in strict mode)
+ * no refusal.
+ *
+ * `ref` is the caller's company selector, which may be a slug OR a `cmp_*` /
+ * `prs_*` uid. The on-disk folder is keyed by SLUG, so a uid selector can't be
+ * measured — it degrades to `false` (no nudge), which is the correct
+ * best-effort: the nudge is a convenience, never load-bearing. A folder that
+ * has never synced (missing directory) likewise measures under threshold.
+ */
+function narrowNudgeExceedsSize(hqRoot, ref) {
+    if (!ref || ref.startsWith("cmp_") || ref.startsWith("prs_"))
+        return false;
+    const companyDir = path.join(hqRoot, "companies", ref);
+    const threshold = resolveNarrowHintMinBytes({ hqRoot });
+    return companyFolderExceedsThreshold(companyDir, threshold);
+}
 export async function pullAll(options, deps) {
     const memberships = await deps.vaultClient.listMyMemberships();
     const persons = await deps.vaultClient.listPersonEntities();
@@ -212,7 +232,13 @@ export async function pullAll(options, deps) {
         if (options.forceScopeShrink && entry.companyUid) {
             entry.syncOptions.forceScopeShrink = true;
         }
+        // Size gate: an all-mode membership is only nudged / strict-refused once
+        // its local folder has grown past the threshold. Computed once per leg.
+        const nudgeExceedsSize = resolvedMode === "all" &&
+            entry.companyUid !== undefined &&
+            narrowNudgeExceedsSize(options.hqRoot, entry.slug);
         if (resolvedMode === "all" &&
+            nudgeExceedsSize &&
             isStrictRefusal(resolvedMode, narrowHintLevel) &&
             !options.modeAllOverride &&
             entry.companyUid) {
@@ -239,8 +265,8 @@ export async function pullAll(options, deps) {
             result.perCompany.push({ slug: entry.slug, result: r });
             // Banner emitted AFTER the leg succeeds so it appears alongside
             // the per-company summary line and doesn't get scrolled off by
-            // sync chatter.
-            if (resolvedMode === "all" && entry.companyUid) {
+            // sync chatter. Size-gated: only a large local folder is nudged.
+            if (resolvedMode === "all" && nudgeExceedsSize && entry.companyUid) {
                 emitNarrowHint({
                     companyUid: entry.companyUid,
                     syncMode: resolvedMode,
@@ -806,11 +832,16 @@ export function registerCloudCommands(program) {
             // thread it into the pull below — not just the banner. Best-effort;
             // degrades to "all" inside the resolver on any failure.
             const pullScope = await resolveCliPullScope(pullClient, options.company, options.hqRoot);
+            // Size gate: only a large local folder is nudged / strict-refused.
+            const nudgeExceedsSize = resolvedMode === "all" &&
+                resolvedCompanyUid !== undefined &&
+                narrowNudgeExceedsSize(options.hqRoot, options.company);
             // Strict-mode refusal: matches runPullAll + runNowSingle behavior.
             // Default banner level is 'hint' which never triggers refusal —
-            // wired now so future hq-core-staging releases can flip the
-            // default to 'strict' without re-touching this command.
+            // wired now so a future release can flip the default to 'strict'
+            // (still size-gated) without re-touching this command.
             if (resolvedMode === "all" &&
+                nudgeExceedsSize &&
                 isStrictRefusal(resolvedMode, narrowHintLevel) &&
                 options.modeAll !== true &&
                 resolvedCompanyUid) {
@@ -820,7 +851,7 @@ export function registerCloudCommands(program) {
                     level: narrowHintLevel,
                 });
                 console.error(chalk.red("\n✗ Pull refused: strict narrow-hint mode is on and this " +
-                    "membership still pulls everything. Run `hq sync narrow --apply` " +
+                    "company's local folder has grown large. Run `hq sync narrow --apply` " +
                     "to migrate, or re-run with --mode-all."));
                 process.exit(1);
             }
@@ -846,10 +877,10 @@ export function registerCloudCommands(program) {
                 process.exit(1);
             }
             console.log(chalk.green(`\n✓ Pulled ${result.filesDownloaded} file(s) (${formatBytes(result.bytesDownloaded)}, ${result.filesSkipped} skipped, ${result.conflicts} conflicts)`));
-            // US-011 (2026-05-21 fix): emit the hint banner after success
-            // so it appears alongside the summary line. Mirrors the wiring
-            // in runPullAll (cloud.ts:331) and runNowSingle (cloud.ts:1371).
-            if (resolvedMode === "all" && resolvedCompanyUid) {
+            // Emit the hint banner after success so it appears alongside the
+            // summary line. Mirrors the wiring in runPullAll and runNowSingle.
+            // Size-gated: only a large local folder is nudged.
+            if (resolvedMode === "all" && nudgeExceedsSize && resolvedCompanyUid) {
                 emitNarrowHint({
                     companyUid: resolvedCompanyUid,
                     syncMode: resolvedMode,
@@ -1304,7 +1335,12 @@ async function runNowSingle(hqRoot, company, personal, message, onConflict, mode
                 resolvedMode = undefined;
             }
         }
+        // Size gate: only a large local folder is nudged / strict-refused.
+        const nudgeExceedsSize = resolvedMode === "all" &&
+            resolvedCompanyUid !== undefined &&
+            narrowNudgeExceedsSize(hqRoot, targetCompany);
         if (resolvedMode === "all" &&
+            nudgeExceedsSize &&
             isStrictRefusal(resolvedMode, narrowHintLevel) &&
             !modeAllOverride &&
             resolvedCompanyUid) {
@@ -1314,7 +1350,7 @@ async function runNowSingle(hqRoot, company, personal, message, onConflict, mode
                 level: narrowHintLevel,
             });
             console.error(chalk.red("\n✗ Sync now refused: strict narrow-hint mode is on and this " +
-                "membership still pulls everything. Run `hq sync narrow --apply` " +
+                "company's local folder has grown large. Run `hq sync narrow --apply` " +
                 "to migrate, or re-run with --mode-all."));
             process.exit(1);
         }
@@ -1358,9 +1394,10 @@ async function runNowSingle(hqRoot, company, personal, message, onConflict, mode
             console.log(chalk.yellow("\n⚠ Sync now finished with pull leg aborted."));
             process.exit(1);
         }
-        // US-011: emit the hint banner after a successful pull so it
-        // appears at the bottom of the summary rather than mid-stream.
-        if (resolvedMode === "all" && resolvedCompanyUid) {
+        // Emit the hint banner after a successful pull so it appears at the
+        // bottom of the summary rather than mid-stream. Size-gated: only a large
+        // local folder is nudged.
+        if (resolvedMode === "all" && nudgeExceedsSize && resolvedCompanyUid) {
             emitNarrowHint({
                 companyUid: resolvedCompanyUid,
                 syncMode: resolvedMode,

package/dist/commands/index-cmd.d.ts

@@ -0,0 +1,16 @@
+import { Command } from 'commander';
+import { type RunQmdOptions, type SearchCollection, type QmdProcessResult } from '../lib/search-index/index.js';
+export type SearchIndexDependencies = {
+    reconcileCollections: (hqRoot: string) => unknown;
+    deriveCollections: (hqRoot: string) => SearchCollection[];
+    listRegisteredCollections: (hqRoot: string, options?: RunQmdOptions) => Set<string>;
+    resolveQmdBin: () => string;
+    resolveQmdVersion: () => string | undefined;
+    runQmd: (args: string[], options?: RunQmdOptions) => QmdProcessResult;
+};
+/** Incrementally update qmd, embedding only when an operator explicitly asks. */
+export declare function syncSearchIndex(hqRoot: string, embed: boolean, dependencies?: SearchIndexDependencies): void;
+export declare function collectionStatusLines(expected: SearchCollection[], registered: ReadonlySet<string>): string[];
+export declare function collectionSummary(expected: SearchCollection[], registered: ReadonlySet<string>): string;
+export declare function registerIndexCommand(program: Command, dependencies?: SearchIndexDependencies): void;
+//# sourceMappingURL=index-cmd.d.ts.map

package/dist/commands/index-cmd.js

@@ -0,0 +1,76 @@
+import { deriveCollections, listRegisteredCollections, reconcileCollections, resolveQmdBin, resolveQmdVersion, runQmd, } from '../lib/search-index/index.js';
+import { findHqRoot } from '../utils/manifest.js';
+const defaults = {
+    reconcileCollections,
+    deriveCollections,
+    listRegisteredCollections,
+    resolveQmdBin,
+    resolveQmdVersion,
+    runQmd,
+};
+/** Incrementally update qmd, embedding only when an operator explicitly asks. */
+export function syncSearchIndex(hqRoot, embed, dependencies = defaults) {
+    dependencies.reconcileCollections(hqRoot);
+    dependencies.runQmd(['update'], { cwd: hqRoot });
+    if (embed)
+        dependencies.runQmd(['embed'], { cwd: hqRoot });
+}
+function resolveRoot(hqRoot) {
+    return hqRoot ?? findHqRoot();
+}
+export function collectionStatusLines(expected, registered) {
+    const expectedNames = new Set(expected.map((collection) => collection.name));
+    const managed = expected.map((collection) => `${registered.has(collection.name) ? 'registered' : 'missing'}  ${collection.name}  ${collection.path}`);
+    const unmanaged = [...registered]
+        .filter((name) => !expectedNames.has(name))
+        .sort((left, right) => left.localeCompare(right))
+        .map((name) => `registered (unmanaged)  ${name}`);
+    return [...managed, ...unmanaged];
+}
+export function collectionSummary(expected, registered) {
+    const expectedNames = new Set(expected.map((collection) => collection.name));
+    const unmanaged = [...registered].filter((name) => !expectedNames.has(name)).length;
+    return `collections: ${registered.size} registered; ${expected.length} expected; ${unmanaged} unmanaged`;
+}
+export function registerIndexCommand(program, dependencies = defaults) {
+    const index = program.command('index').description('Manage the local HQ search index');
+    index
+        .command('sync')
+        .description('Reconcile collections and incrementally update the qmd index')
+        .option('--embed', 'Also rebuild expensive semantic embeddings')
+        .option('--hq-root <path>', 'HQ root to index (defaults to auto-detected root)')
+        .action((options) => {
+        const hqRoot = resolveRoot(options.hqRoot);
+        syncSearchIndex(hqRoot, options.embed === true);
+        console.log(`Updated search index for ${hqRoot}${options.embed ? ' (including embeddings)' : ''}.`);
+    });
+    index
+        .command('collections')
+        .description('Show expected and registered qmd collections')
+        .option('--hq-root <path>', 'HQ root to inspect (defaults to auto-detected root)')
+        .action((options) => {
+        const hqRoot = resolveRoot(options.hqRoot);
+        const registered = dependencies.listRegisteredCollections(hqRoot);
+        for (const line of collectionStatusLines(dependencies.deriveCollections(hqRoot), registered))
+            console.log(line);
+    });
+    index
+        .command('status')
+        .description('Show qmd binary, collection, and index status')
+        .option('--hq-root <path>', 'HQ root to inspect (defaults to auto-detected root)')
+        .action((options) => {
+        const hqRoot = resolveRoot(options.hqRoot);
+        const bin = dependencies.resolveQmdBin();
+        const registered = dependencies.listRegisteredCollections(hqRoot, { bin, cwd: hqRoot });
+        const expected = dependencies.deriveCollections(hqRoot);
+        const qmdStatus = dependencies.runQmd(['status'], { bin, cwd: hqRoot });
+        const qmdVersion = dependencies.resolveQmdVersion();
+        console.log(`qmd: ${bin}${qmdVersion ? ` (version ${qmdVersion})` : ''}`);
+        console.log(collectionSummary(expected, registered));
+        if (qmdStatus.stdout)
+            process.stdout.write(qmdStatus.stdout);
+        if (qmdStatus.stderr)
+            process.stderr.write(qmdStatus.stderr);
+    });
+}
+//# sourceMappingURL=index-cmd.js.map

package/dist/commands/search.d.ts

@@ -0,0 +1,12 @@
+import { Command } from 'commander';
+export type SearchMode = 'keyword' | 'semantic' | 'hybrid';
+export type SearchOptions = {
+    mode?: SearchMode;
+    collection?: string;
+    count?: number;
+    json?: boolean;
+};
+export declare function buildSearchArgs(query: string, options?: SearchOptions): string[];
+export declare function buildGetArgs(document: string, options?: Pick<SearchOptions, 'collection'>): string[];
+export declare function registerSearchCommand(program: Command): void;
+//# sourceMappingURL=search.d.ts.map

package/dist/commands/search.js

@@ -0,0 +1,48 @@
+import { runQmd } from '../lib/search-index/index.js';
+export function buildSearchArgs(query, options = {}) {
+    const command = { keyword: 'search', semantic: 'vsearch', hybrid: 'query' }[options.mode ?? 'keyword'];
+    const args = [command, query];
+    if (options.collection)
+        args.push('-c', options.collection);
+    if (options.count !== undefined)
+        args.push('-n', String(options.count));
+    if (options.json)
+        args.push('--json');
+    return args;
+}
+export function buildGetArgs(document, options = {}) {
+    const args = ['get', document];
+    if (options.collection)
+        args.push('-c', options.collection);
+    return args;
+}
+function relay(result) {
+    if (result.stdout)
+        process.stdout.write(result.stdout);
+    if (result.stderr)
+        process.stderr.write(result.stderr);
+}
+export function registerSearchCommand(program) {
+    const search = program.command('search').description('Search the local HQ qmd index');
+    search
+        .command('get <document>')
+        .description('Retrieve a qmd document by path or document id')
+        .option('-c, --collection <collection>', 'Restrict retrieval to a collection')
+        .action((document, options) => {
+        relay(runQmd(buildGetArgs(document, options)));
+    });
+    search
+        .command('<query>')
+        .description('Search the local HQ qmd index')
+        .option('--mode <mode>', 'Search mode: keyword, semantic, or hybrid', 'keyword')
+        .option('-c, --collection <collection>', 'Restrict search to a collection')
+        .option('-n, --count <count>', 'Maximum result count', (value) => Number(value))
+        .option('--json', 'Request machine-readable qmd output')
+        .action((query, options) => {
+        if (!['keyword', 'semantic', 'hybrid'].includes(options.mode ?? 'keyword')) {
+            throw new Error(`Unknown search mode '${options.mode}'. Expected keyword, semantic, or hybrid.`);
+        }
+        relay(runQmd(buildSearchArgs(query, options)));
+    });
+}
+//# sourceMappingURL=search.js.map

package/dist/commands/sync-mode.js

@@ -139,7 +139,11 @@ export async function showSyncModes(options) {
         const [config, entity] = await Promise.all([
             vaultClient.getMembershipSyncConfig(m.membershipKey).catch(() => ({
                 membershipId: m.membershipKey,
-                syncMode: "shared",
+                // Display fallback when the config fetch fails: show 'all', the
+                // effective default a membership resolves to (see
+                // DEFAULT_MEMBERSHIP_SYNC_MODE / resolveEffectiveSyncMode). Showing
+                // 'shared' here would misreport the default the user is actually on.
+                syncMode: "all",
                 isDefault: true,
             })),
             vaultClient.entity

package/dist/lib/narrow-hint-banner.d.ts

@@ -1,12 +1,24 @@
 /**
- * `narrow-hint-banner` (US-011) — one-time-per-session hint nudging
- * existing all-mode owners to switch to shared-mode sync.
+ * `narrow-hint-banner` — one-time-per-session hint suggesting that a member
+ * whose LOCAL company folder has grown large could switch to shared-mode sync
+ * to pull fewer files.
+ *
+ * `all` is the DEFAULT sync mode (see `DEFAULT_MEMBERSHIP_SYNC_MODE` in
+ * hq-pro): a member who can see a company gets that company's files. Shared
+ * mode is a deliberate, opt-in NARROWING — worth suggesting only once the
+ * folder is big enough that pulling all of it actually costs disk/bandwidth.
+ * So the nudge is SIZE-GATED: below the threshold (default 5 GiB, see
+ * `DEFAULT_NARROW_HINT_MIN_BYTES`) no banner is ever shown, and an all-mode
+ * membership with a small folder is left completely alone.
  *
  * Emitted from `hq sync pull --all` and `hq sync now` after the per-target
  * fanout resolves each membership's sync config. Suppressed when:
  *
  *   - the membership is NOT on `syncMode: 'all'` (shared / custom users
  *     have already opted in to narrowing, so there is nothing to nudge),
+ *   - the local `companies/<slug>/` folder is under the size threshold
+ *     (the primary gate — the call site computes this and only emits when
+ *     it is exceeded),
  *   - the env var `HQ_SYNC_NARROW_HINT=off` is set,
  *   - the per-hqRoot CLI config (`<hqRoot>/.hq/config.json`) has
  *     `syncNarrowHint: 'off'`,
@@ -16,9 +28,9 @@
  *     banner per company per level).
  *
  * Three escalating levels — `'hint' | 'warning' | 'strict'`. Today's
- * default level is `'hint'`; this release ships the plumbing so a future
- * hq-core-staging release can flip the default to `'warning'` and then
- * `'strict'` without re-touching the call sites.
+ * default level is `'hint'`; the plumbing lets an install escalate a large
+ * folder toward shared mode without re-touching the call sites. The size
+ * gate applies to every level: strict never refuses a small folder.
  *
  * - hint    → dim suggestion to stderr, never blocks.
  * - warning → yellow note to stderr, never blocks.
@@ -29,13 +41,18 @@
  *
  * The level is selected by the caller (typically from the
  * `HQ_SYNC_NARROW_HINT_LEVEL` env var). See `resolveBannerLevel` for the
- * default-and-override ladder.
- *
- * TODO(hq-core-staging release N+2): bump default level to 'warning'.
- * TODO(hq-core-staging release N+3): bump default level to 'strict' and
- *   wire `--mode-all` as the only opt-out.
+ * default-and-override ladder. The size threshold is overridable per install
+ * via `HQ_SYNC_NARROW_HINT_MIN_BYTES` or `.hq/config.json`
+ * `syncNarrowHintMinBytes` — see `resolveNarrowHintMinBytes`.
  */
+import * as fs from "node:fs";
 export type BannerLevel = "hint" | "warning" | "strict";
+/**
+ * Default size gate for the narrow-mode nudge: 5 GiB. A local company folder
+ * smaller than this is cheap to keep in full, so all-mode is left alone and no
+ * banner is shown. Overridable per install — see `resolveNarrowHintMinBytes`.
+ */
+export declare const DEFAULT_NARROW_HINT_MIN_BYTES: number;
 export interface BannerInput {
     /** Company UID — used to dedupe per-process so each company emits once. */
     companyUid: string;
@@ -43,6 +60,12 @@ export interface BannerInput {
     syncMode: "shared" | "all" | "custom";
     /** Escalation level — see file header. */
     level: BannerLevel;
+    /**
+     * Measured size of the local `companies/<slug>/` folder, in bytes. Optional
+     * and cosmetic: when present it is rendered into the message ("~6.2 GB") so
+     * the operator sees WHY the nudge fired. Absent → the message omits the size.
+     */
+    folderBytes?: number;
 }
 export interface ShouldShowBannerOpts {
     /**
@@ -78,11 +101,54 @@ export declare function shouldShowBanner(opts?: ShouldShowBannerOpts): boolean;
  * facing and a typo shouldn't break a sync.
  */
 export declare function resolveBannerLevel(envValue?: string | undefined): BannerLevel;
+/**
+ * Resolve the size threshold (in bytes) above which the narrow nudge fires.
+ * Precedence, first match wins:
+ *
+ *   1. `HQ_SYNC_NARROW_HINT_MIN_BYTES` env var (integer bytes),
+ *   2. `<hqRoot>/.hq/config.json` → `syncNarrowHintMinBytes` (integer bytes),
+ *   3. `DEFAULT_NARROW_HINT_MIN_BYTES` (5 GiB).
+ *
+ * A non-integer, negative, or otherwise unparseable override is ignored (falls
+ * through to the next source) rather than throwing — this is operator-facing
+ * config and a typo must not break a sync.
+ */
+export declare function resolveNarrowHintMinBytes(opts?: {
+    hqRoot?: string;
+    /** Test seam — defaults to `process.env.HQ_SYNC_NARROW_HINT_MIN_BYTES`. */
+    envValue?: string | undefined;
+    readFile?: (p: string) => string;
+    existsFile?: (p: string) => boolean;
+}): number;
+/**
+ * Does the on-disk `companies/<slug>/` folder meet or exceed `thresholdBytes`?
+ *
+ * Walks the tree summing regular-file sizes and SHORT-CIRCUITS the instant the
+ * running total reaches the threshold, so a huge folder costs only enough
+ * `stat`s to cross the line rather than a full enumeration. Symlinks are
+ * counted by their own (link) size and never followed, so a symlink cycle
+ * cannot wedge the walk.
+ *
+ * Best-effort: a missing folder (never synced yet), a permission error, or any
+ * other I/O fault resolves to `false`. Not being able to prove a folder is
+ * large means we do NOT nag — the nudge is a convenience, never a blocker.
+ */
+export declare function companyFolderExceedsThreshold(companyDir: string, thresholdBytes: number, deps?: {
+    readdir?: (p: string) => fs.Dirent[];
+    lstat?: (p: string) => {
+        size: number;
+    };
+}): boolean;
 /**
  * Returns `true` when the strict-mode rollout has been opted into AND
  * the membership in question is still on `'all'`. Call sites should
  * refuse to proceed (exit non-zero) when this returns true and the
  * operator hasn't passed `--mode-all`.
+ *
+ * NOTE: this does NOT encode the size gate — the size gate is a separate,
+ * mandatory precondition the call site checks FIRST (see
+ * `companyFolderExceedsThreshold`). A strict-level all-mode membership whose
+ * folder is under the threshold is never refused.
  */
 export declare function isStrictRefusal(syncMode: BannerInput["syncMode"], level: BannerLevel): boolean;
 /**

package/dist/lib/narrow-hint-banner.js

@@ -1,12 +1,24 @@
 /**
- * `narrow-hint-banner` (US-011) — one-time-per-session hint nudging
- * existing all-mode owners to switch to shared-mode sync.
+ * `narrow-hint-banner` — one-time-per-session hint suggesting that a member
+ * whose LOCAL company folder has grown large could switch to shared-mode sync
+ * to pull fewer files.
+ *
+ * `all` is the DEFAULT sync mode (see `DEFAULT_MEMBERSHIP_SYNC_MODE` in
+ * hq-pro): a member who can see a company gets that company's files. Shared
+ * mode is a deliberate, opt-in NARROWING — worth suggesting only once the
+ * folder is big enough that pulling all of it actually costs disk/bandwidth.
+ * So the nudge is SIZE-GATED: below the threshold (default 5 GiB, see
+ * `DEFAULT_NARROW_HINT_MIN_BYTES`) no banner is ever shown, and an all-mode
+ * membership with a small folder is left completely alone.
  *
  * Emitted from `hq sync pull --all` and `hq sync now` after the per-target
  * fanout resolves each membership's sync config. Suppressed when:
  *
  *   - the membership is NOT on `syncMode: 'all'` (shared / custom users
  *     have already opted in to narrowing, so there is nothing to nudge),
+ *   - the local `companies/<slug>/` folder is under the size threshold
+ *     (the primary gate — the call site computes this and only emits when
+ *     it is exceeded),
  *   - the env var `HQ_SYNC_NARROW_HINT=off` is set,
  *   - the per-hqRoot CLI config (`<hqRoot>/.hq/config.json`) has
  *     `syncNarrowHint: 'off'`,
@@ -16,9 +28,9 @@
  *     banner per company per level).
  *
  * Three escalating levels — `'hint' | 'warning' | 'strict'`. Today's
- * default level is `'hint'`; this release ships the plumbing so a future
- * hq-core-staging release can flip the default to `'warning'` and then
- * `'strict'` without re-touching the call sites.
+ * default level is `'hint'`; the plumbing lets an install escalate a large
+ * folder toward shared mode without re-touching the call sites. The size
+ * gate applies to every level: strict never refuses a small folder.
  *
  * - hint    → dim suggestion to stderr, never blocks.
  * - warning → yellow note to stderr, never blocks.
@@ -29,15 +41,33 @@
  *
  * The level is selected by the caller (typically from the
  * `HQ_SYNC_NARROW_HINT_LEVEL` env var). See `resolveBannerLevel` for the
- * default-and-override ladder.
- *
- * TODO(hq-core-staging release N+2): bump default level to 'warning'.
- * TODO(hq-core-staging release N+3): bump default level to 'strict' and
- *   wire `--mode-all` as the only opt-out.
+ * default-and-override ladder. The size threshold is overridable per install
+ * via `HQ_SYNC_NARROW_HINT_MIN_BYTES` or `.hq/config.json`
+ * `syncNarrowHintMinBytes` — see `resolveNarrowHintMinBytes`.
  */
 import chalk from "chalk";
 import * as fs from "node:fs";
 import * as path from "node:path";
+/**
+ * Default size gate for the narrow-mode nudge: 5 GiB. A local company folder
+ * smaller than this is cheap to keep in full, so all-mode is left alone and no
+ * banner is shown. Overridable per install — see `resolveNarrowHintMinBytes`.
+ */
+export const DEFAULT_NARROW_HINT_MIN_BYTES = 5 * 1024 * 1024 * 1024;
+/** Render a byte count as a short human string, e.g. `6.2 GB`. */
+function formatBytes(bytes) {
+    if (!Number.isFinite(bytes) || bytes < 0)
+        return "";
+    const units = ["B", "KB", "MB", "GB", "TB"];
+    let value = bytes;
+    let unit = 0;
+    while (value >= 1024 && unit < units.length - 1) {
+        value /= 1024;
+        unit += 1;
+    }
+    const rounded = unit === 0 ? String(value) : value.toFixed(1);
+    return `${rounded} ${units[unit]}`;
+}
 const SHOWN = new Set();
 /**
  * Decides whether a banner should be printed AT ALL — independent of
@@ -86,11 +116,119 @@ export function resolveBannerLevel(envValue = process.env.HQ_SYNC_NARROW_HINT_LE
         return v;
     return "hint";
 }
+/**
+ * Resolve the size threshold (in bytes) above which the narrow nudge fires.
+ * Precedence, first match wins:
+ *
+ *   1. `HQ_SYNC_NARROW_HINT_MIN_BYTES` env var (integer bytes),
+ *   2. `<hqRoot>/.hq/config.json` → `syncNarrowHintMinBytes` (integer bytes),
+ *   3. `DEFAULT_NARROW_HINT_MIN_BYTES` (5 GiB).
+ *
+ * A non-integer, negative, or otherwise unparseable override is ignored (falls
+ * through to the next source) rather than throwing — this is operator-facing
+ * config and a typo must not break a sync.
+ */
+export function resolveNarrowHintMinBytes(opts = {}) {
+    const fromEnv = parsePositiveInt(opts.envValue !== undefined
+        ? opts.envValue
+        : process.env.HQ_SYNC_NARROW_HINT_MIN_BYTES);
+    if (fromEnv !== null)
+        return fromEnv;
+    if (opts.hqRoot) {
+        const configPath = path.join(opts.hqRoot, ".hq", "config.json");
+        const exists = opts.existsFile ?? fs.existsSync;
+        const read = opts.readFile ?? ((p) => fs.readFileSync(p, "utf-8"));
+        if (exists(configPath)) {
+            try {
+                const cfg = JSON.parse(read(configPath));
+                const fromCfg = parsePositiveInt(cfg.syncNarrowHintMinBytes);
+                if (fromCfg !== null)
+                    return fromCfg;
+            }
+            catch {
+                // Malformed config → fall through to the default.
+            }
+        }
+    }
+    return DEFAULT_NARROW_HINT_MIN_BYTES;
+}
+/** A finite, non-negative integer parsed from a string/number, else null. */
+function parsePositiveInt(value) {
+    if (typeof value === "number") {
+        return Number.isInteger(value) && value >= 0 ? value : null;
+    }
+    if (typeof value !== "string")
+        return null;
+    const trimmed = value.trim();
+    if (!/^\d+$/.test(trimmed))
+        return null;
+    const n = Number(trimmed);
+    return Number.isSafeInteger(n) ? n : null;
+}
+/**
+ * Does the on-disk `companies/<slug>/` folder meet or exceed `thresholdBytes`?
+ *
+ * Walks the tree summing regular-file sizes and SHORT-CIRCUITS the instant the
+ * running total reaches the threshold, so a huge folder costs only enough
+ * `stat`s to cross the line rather than a full enumeration. Symlinks are
+ * counted by their own (link) size and never followed, so a symlink cycle
+ * cannot wedge the walk.
+ *
+ * Best-effort: a missing folder (never synced yet), a permission error, or any
+ * other I/O fault resolves to `false`. Not being able to prove a folder is
+ * large means we do NOT nag — the nudge is a convenience, never a blocker.
+ */
+export function companyFolderExceedsThreshold(companyDir, thresholdBytes, deps = {}) {
+    if (thresholdBytes <= 0)
+        return true;
+    const readdir = deps.readdir ??
+        ((p) => fs.readdirSync(p, { withFileTypes: true }));
+    const lstat = deps.lstat ?? ((p) => fs.lstatSync(p));
+    let total = 0;
+    const stack = [companyDir];
+    while (stack.length > 0) {
+        const dir = stack.pop();
+        let entries;
+        try {
+            entries = readdir(dir);
+        }
+        catch {
+            // Unreadable directory (missing / no permission) — skip it, don't abort
+            // the whole measurement over one bad subtree.
+            continue;
+        }
+        for (const entry of entries) {
+            const full = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                stack.push(full);
+                continue;
+            }
+            // Symlinks and regular files alike: count the link/file's own size,
+            // never follow (isDirectory() above already excluded real dirs; a
+            // symlink-to-dir is intentionally treated as a leaf).
+            try {
+                total += lstat(full).size;
+            }
+            catch {
+                // Vanished between readdir and lstat — ignore.
+                continue;
+            }
+            if (total >= thresholdBytes)
+                return true;
+        }
+    }
+    return false;
+}
 /**
  * Returns `true` when the strict-mode rollout has been opted into AND
  * the membership in question is still on `'all'`. Call sites should
  * refuse to proceed (exit non-zero) when this returns true and the
  * operator hasn't passed `--mode-all`.
+ *
+ * NOTE: this does NOT encode the size gate — the size gate is a separate,
+ * mandatory precondition the call site checks FIRST (see
+ * `companyFolderExceedsThreshold`). A strict-level all-mode membership whose
+ * folder is under the threshold is never refused.
  */
 export function isStrictRefusal(syncMode, level) {
     return level === "strict" && syncMode === "all";
@@ -116,23 +254,28 @@ export function emitNarrowHint(input, opts = {}) {
         return;
     SHOWN.add(key);
     const write = opts.write ?? ((s) => process.stderr.write(s + "\n"));
+    // The nudge only reaches here for a folder past the size gate, so every
+    // message leads with the size fact. `folderBytes` is optional/cosmetic.
+    const sizePhrase = typeof input.folderBytes === "number"
+        ? `has grown to ~${formatBytes(input.folderBytes)}`
+        : "has grown large";
     if (input.level === "hint") {
-        write(chalk.dim("Tip: switch to shared-mode sync — fewer files, same visibility. " +
-            "Run `hq sync narrow --dry-run` to preview."));
+        write(chalk.dim(`Tip: this company's local folder ${sizePhrase}. You can switch to ` +
+            "shared-mode sync to only pull files shared with you — run " +
+            "`hq sync narrow --dry-run` to preview."));
         return;
     }
     if (input.level === "warning") {
-        write(chalk.yellow("Warning: shared-mode sync is the new default; this membership " +
-            "still pulls everything. Run `hq sync narrow --dry-run` to " +
-            "preview the migration before the next release flips the " +
-            "default to strict."));
+        write(chalk.yellow(`Warning: this company's local folder ${sizePhrase} and is syncing in ` +
+            "full. Consider shared-mode sync to pull only what's shared with " +
+            "you — run `hq sync narrow --dry-run` to preview the migration."));
         return;
     }
     // strict — caller is responsible for refusing to proceed unless
     // --mode-all was passed. We only emit the message here.
-    write(chalk.red("Error: shared-mode sync is now strict; pass --mode-all to keep " +
-        "all-mode behavior for this run, or run `hq sync narrow --apply` " +
-        "to migrate this membership."));
+    write(chalk.red(`Error: this company's local folder ${sizePhrase}; all-mode sync is ` +
+        "blocked for it. Pass --mode-all to keep pulling everything this run, " +
+        "or run `hq sync narrow --apply` to switch to shared mode."));
 }
 /** Test-only helper — clears the per-process dedupe set. */
 export function _resetShownForTests() {

package/dist/lib/search-index/index.d.ts

@@ -0,0 +1,58 @@
+export type QmdProcessResult = {
+    status: number | null;
+    stdout: string;
+    stderr: string;
+    error?: Error;
+};
+export type QmdProcessRunner = (bin: string, args: string[], options: {
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+}) => QmdProcessResult;
+export declare class QmdBinaryMissingError extends Error {
+    name: string;
+}
+export declare class QmdExitError extends Error {
+    readonly args: string[];
+    readonly status: number | null;
+    readonly stdout: string;
+    readonly stderr: string;
+    name: string;
+    constructor(message: string, args: string[], status: number | null, stdout: string, stderr: string);
+}
+export declare class QmdCollectionMissingError extends QmdExitError {
+    name: string;
+}
+export type ResolveQmdBinOptions = {
+    env?: Record<string, string | undefined>;
+    isExecutable?: (candidate: string) => boolean;
+    packageBin?: () => string | undefined;
+    pathBin?: () => string | undefined;
+};
+/** Return the pinned package version when qmd is supplied by this CLI. */
+export declare function resolveQmdVersion(): string | undefined;
+/** Resolve qmd without relying on a globally installed copy. */
+export declare function resolveQmdBin(options?: ResolveQmdBinOptions): string;
+export type RunQmdOptions = {
+    bin?: string;
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    runner?: QmdProcessRunner;
+};
+/** Run qmd with captured output and typed failures. */
+export declare function runQmd(args: string[], options?: RunQmdOptions): QmdProcessResult;
+export type SearchCollection = {
+    name: string;
+    path: string;
+    mask: string;
+    context: string;
+};
+/** Derive the local qmd collection policy for one HQ tree. */
+export declare function deriveCollections(hqRoot: string): SearchCollection[];
+export type ReconcileCollectionsOptions = {
+    bin?: string;
+    runner?: QmdProcessRunner;
+};
+/** Register expected collections that qmd does not yet know about. */
+export declare function reconcileCollections(hqRoot: string, options?: ReconcileCollectionsOptions): SearchCollection[];
+export declare function listRegisteredCollections(hqRoot: string, options?: RunQmdOptions): Set<string>;
+//# sourceMappingURL=index.d.ts.map

package/dist/lib/search-index/index.js

@@ -0,0 +1,197 @@
+import { spawnSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import { createRequire } from 'node:module';
+import * as path from 'node:path';
+const require = createRequire(import.meta.url);
+export class QmdBinaryMissingError extends Error {
+    name = 'QmdBinaryMissingError';
+}
+export class QmdExitError extends Error {
+    args;
+    status;
+    stdout;
+    stderr;
+    name = 'QmdExitError';
+    constructor(message, args, status, stdout, stderr) {
+        super(message);
+        this.args = args;
+        this.status = status;
+        this.stdout = stdout;
+        this.stderr = stderr;
+    }
+}
+export class QmdCollectionMissingError extends QmdExitError {
+    name = 'QmdCollectionMissingError';
+}
+function isExecutable(candidate) {
+    try {
+        fs.accessSync(candidate, fs.constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function packageLocalBin() {
+    try {
+        const packageJson = require.resolve('@tobilu/qmd/package.json');
+        return path.join(path.dirname(packageJson), 'qmd');
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Return the pinned package version when qmd is supplied by this CLI. */
+export function resolveQmdVersion() {
+    try {
+        const packageJson = require('@tobilu/qmd/package.json');
+        return typeof packageJson.version === 'string' ? packageJson.version : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function pathBin() {
+    const paths = (process.env.PATH ?? '').split(path.delimiter).filter(Boolean);
+    const names = process.platform === 'win32' ? ['qmd.exe', 'qmd.cmd', 'qmd'] : ['qmd'];
+    for (const directory of paths) {
+        for (const name of names) {
+            const candidate = path.join(directory, name);
+            if (isExecutable(candidate))
+                return candidate;
+        }
+    }
+    return undefined;
+}
+/** Resolve qmd without relying on a globally installed copy. */
+export function resolveQmdBin(options = {}) {
+    const env = options.env ?? process.env;
+    const executable = options.isExecutable ?? isExecutable;
+    const probes = [];
+    const override = env.HQ_QMD_BIN;
+    if (override) {
+        if (executable(override))
+            return override;
+        probes.push(`HQ_QMD_BIN (${override})`);
+    }
+    else {
+        probes.push('HQ_QMD_BIN (not set)');
+    }
+    const installed = (options.packageBin ?? packageLocalBin)();
+    if (installed && executable(installed))
+        return installed;
+    probes.push(`package-local @tobilu/qmd (${installed ?? 'not found'})`);
+    const onPath = (options.pathBin ?? pathBin)();
+    if (onPath && executable(onPath))
+        return onPath;
+    probes.push(`qmd on PATH (${onPath ?? 'not found'})`);
+    throw new QmdBinaryMissingError(`Unable to resolve qmd. Probed ${probes.join('; ')}. Install @tobilu/qmd or set HQ_QMD_BIN to an executable qmd binary.`);
+}
+function defaultRunner(bin, args, options) {
+    const result = spawnSync(bin, args, { cwd: options.cwd, env: options.env, encoding: 'utf8' });
+    return {
+        status: result.status,
+        stdout: result.stdout ?? '',
+        stderr: result.stderr ?? '',
+        error: result.error,
+    };
+}
+/** Run qmd with captured output and typed failures. */
+export function runQmd(args, options = {}) {
+    const bin = options.bin ?? resolveQmdBin({ env: options.env });
+    const result = (options.runner ?? defaultRunner)(bin, args, { cwd: options.cwd, env: options.env });
+    if (result.error) {
+        throw new QmdBinaryMissingError(`Unable to execute qmd at ${bin}: ${result.error.message}`);
+    }
+    if (result.status === 0)
+        return result;
+    const detail = result.stderr || result.stdout || 'qmd returned no diagnostic output';
+    const message = `qmd ${args.join(' ')} exited with ${result.status ?? 'an unknown status'}: ${detail}`;
+    if (/(?:collection|qmd:\/\/).*(?:not found|does not exist|unknown)|(?:not found|does not exist).*collection/i.test(detail)) {
+        throw new QmdCollectionMissingError(message, args, result.status, result.stdout, result.stderr);
+    }
+    throw new QmdExitError(message, args, result.status, result.stdout, result.stderr);
+}
+function containsIndexedMarkdown(directory) {
+    if (!fs.existsSync(directory))
+        return false;
+    for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+        const child = path.join(directory, entry.name);
+        if (entry.isDirectory() && containsIndexedMarkdown(child))
+            return true;
+        if (entry.isFile() && entry.name.endsWith('.md') && entry.name !== 'INDEX.md')
+            return true;
+    }
+    return false;
+}
+function containsProjectSource(directory) {
+    if (!fs.existsSync(directory))
+        return false;
+    for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+        const child = path.join(directory, entry.name);
+        if (entry.isDirectory() && containsProjectSource(child))
+            return true;
+        if (entry.isFile() && (entry.name.endsWith('.md') || entry.name.endsWith('.json')))
+            return true;
+    }
+    return false;
+}
+/** Derive the local qmd collection policy for one HQ tree. */
+export function deriveCollections(hqRoot) {
+    const root = path.resolve(hqRoot);
+    const companiesDir = path.join(root, 'companies');
+    const companies = fs.existsSync(companiesDir)
+        ? fs.readdirSync(companiesDir, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory())
+            .sort((a, b) => a.name.localeCompare(b.name))
+        : [];
+    const collections = [];
+    for (const entry of companies) {
+        const knowledge = path.join(companiesDir, entry.name, 'knowledge');
+        if (!containsIndexedMarkdown(knowledge))
+            continue;
+        collections.push({
+            name: entry.name,
+            path: knowledge,
+            mask: '**/*.md',
+            context: `Knowledge base for ${entry.name}.`,
+        });
+    }
+    for (const entry of companies) {
+        const projects = path.join(companiesDir, entry.name, 'projects');
+        if (!containsProjectSource(projects))
+            continue;
+        collections.push({
+            name: `${entry.name}-projects`,
+            path: projects,
+            mask: '**/*.{md,json}',
+            context: `Project PRDs and documentation for ${entry.name}.`,
+        });
+    }
+    const personalKnowledge = path.join(root, 'personal', 'knowledge');
+    if (containsIndexedMarkdown(personalKnowledge)) {
+        collections.push({
+            name: 'personal-knowledge',
+            path: personalKnowledge,
+            mask: '**/*.md',
+            context: 'Personal knowledge base (owner overlay).',
+        });
+    }
+    return collections;
+}
+/** Register expected collections that qmd does not yet know about. */
+export function reconcileCollections(hqRoot, options = {}) {
+    const runOptions = { bin: options.bin, runner: options.runner, cwd: hqRoot };
+    const registered = listRegisteredCollections(hqRoot, runOptions);
+    const missing = deriveCollections(hqRoot).filter((collection) => !registered.has(collection.name));
+    for (const collection of missing) {
+        runQmd(['collection', 'add', collection.path, '--name', collection.name, '--mask', collection.mask], runOptions);
+        runQmd(['context', 'add', `qmd://${collection.name}`, collection.context], runOptions);
+    }
+    return missing;
+}
+export function listRegisteredCollections(hqRoot, options = {}) {
+    const result = runQmd(['collection', 'list'], { ...options, cwd: options.cwd ?? hqRoot });
+    return new Set([...result.stdout.matchAll(/qmd:\/\/([^/\s]+)/g)].map((match) => match[1]));
+}
+//# sourceMappingURL=index.js.map

package/dist/main.js

@@ -57,6 +57,8 @@ import { registerOutpostsCommand } from "./commands/outposts.js";
 import { registerBillingCommand } from "./commands/billing.js";
 import { registerDbCommand } from "./commands/db.js";
 import { registerCoreCommands } from "./commands/core.js";
+import { registerSearchCommand } from "./commands/search.js";
+import { registerIndexCommand } from "./commands/index-cmd.js";
 import { sanitizeArgv } from "./utils/feedback-diagnostics.js";
 import { environmentalFsErrorMessage } from "./utils/environmental-error.js";
 import { isExpectedUserError } from "./utils/expected-cli-error.js";
@@ -228,6 +230,10 @@ registerBillingCommand(program);
 // the source-root entries are maintainer tools that must never touch a live
 // install. Registered from a manifest in the module, not wired per script here.
 registerCoreCommands(program);
+// Local qmd search and index management. Kept distinct from `hq reindex`,
+// which converges scaffold-owned files and hooks rather than search data.
+registerSearchCommand(program);
+registerIndexCommand(program);
 program.hook("preAction", async () => {
     await emitCliSessionStarted();
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.85.2",
+  "version": "5.86.0",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {
@@ -32,6 +32,7 @@
     "@indigoai-us/hq-cloud": "^6.14.45",
     "@indigoai-us/hq-onboarding": "^0.1.0",
     "@sentry/node": "^10.49.0",
+    "@tobilu/qmd": "1.0.7",
     "better-sqlite3": "^12.11.1",
     "chalk": "^5.3.0",
     "commander": "^12.1.0",