@indigoai-us/hq-cli 5.112.0 → 5.113.0

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ## [Unreleased]
 
+## [5.113.0] — 2026-09-15
+
+### Added
+
+- Search indexing now skips any file larger than 100 KB. HQ indexes every `.md`
+  and `.json` file under your project folders, which pulled in things nobody
+  searches as prose: browser trace dumps, perf captures, scraped datasets,
+  lockfiles. A few of those were large enough that indexing ran out of time
+  before it finished, so the search index never caught up. Set a different limit
+  with `HQ_INDEX_MAX_DOC_BYTES`, or `indexMaxDocBytes` in your HQ root's
+  `.hq/config.json`. Set it to `0` to index everything again.
+
 ## [5.112.0] — 2026-09-15
 
 ### Added

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

@@ -3,6 +3,8 @@ import { type RunQmdOptions, type SearchCollection, type QmdProcessResult } from
 import { type BackgroundDependencies, type BackgroundResult, type BackgroundStatus } from '../lib/search-index/background.js';
 export type SearchIndexDependencies = {
     reconcileCollections: (hqRoot: string) => unknown;
+    /** Apply the per-document size cap to qmd's config before the update reads anything. */
+    applyIndexSizeLimit: (hqRoot: string) => unknown;
     deriveCollections: (hqRoot: string) => SearchCollection[];
     listRegisteredCollections: (hqRoot: string, options?: RunQmdOptions) => Set<string>;
     resolveQmdBin: () => string;

package/dist/commands/index-cmd.js

@@ -1,6 +1,7 @@
 import { Option } from 'commander';
 import { deriveCollections, listRegisteredCollections, packageLocalBin, reconcileCollections, resolveQmdBin, resolveQmdVersion, runQmd, } from '../lib/search-index/index.js';
 import { backgroundStatus, defaultBackgroundDependencies, runBackgroundLauncher, runBackgroundWorker, } from '../lib/search-index/background.js';
+import { applyIndexSizeLimit } from '../lib/search-index/max-doc-bytes.js';
 import { findHqRoot } from '../utils/manifest.js';
 import { QMD_NATIVE_BINDING_REMEDY, isQmdNativeBindingError, } from '../utils/qmd-native-binding-error.js';
 import { isQmdStoreMissingError, qmdStoreMissingMessage, } from '../utils/qmd-store-missing-error.js';
@@ -8,6 +9,7 @@ import { isQmdStoreUnopenableError, qmdStoreUnopenableMessage, } from '../utils/
 import { isQmdWorkdirMissingError, qmdWorkdirMissingMessage, } from '../utils/qmd-workdir-missing-error.js';
 const defaults = {
     reconcileCollections,
+    applyIndexSizeLimit,
     deriveCollections,
     listRegisteredCollections,
     resolveQmdBin,
@@ -20,6 +22,18 @@ const defaults = {
 /** Incrementally update qmd, embedding only when an operator explicitly asks. */
 export function syncSearchIndex(hqRoot, embed, dependencies = defaults) {
     dependencies.reconcileCollections(hqRoot);
+    // Must precede the update: an oversized file is skipped at glob time or not
+    // at all, so capping after the update would still have paid to read it.
+    //
+    // Best-effort, matching the background worker. The cap writes to qmd's config
+    // and to `.hq/`, either of which can be read-only on a locked-down box. An
+    // index that is merely uncapped is far better than no `qmd update` at all.
+    try {
+        dependencies.applyIndexSizeLimit(hqRoot);
+    }
+    catch {
+        /* capping is an optimisation; indexing is the job */
+    }
     dependencies.runQmd(['update'], { cwd: hqRoot });
     if (embed)
         dependencies.runQmd(['embed'], { cwd: hqRoot });
@@ -32,6 +46,7 @@ function makeBackgroundDependencies(hqRoot, dependencies) {
         ...defaultBackgroundDependencies(hqRoot),
         resolveQmdBin: dependencies.resolveQmdBin,
         reconcileCollections: dependencies.reconcileCollections,
+        applyIndexSizeLimit: dependencies.applyIndexSizeLimit,
         runQmd: dependencies.runQmd,
     };
 }

package/dist/lib/core-utils/qmd-reindex-after-sync.d.ts

@@ -10,6 +10,7 @@ export type QmdReindexOptions = UtilityIo & {
         bin: string;
         cwd: string;
     }) => unknown;
+    sizeLimit?: (hqRoot: string) => unknown;
 };
 export declare function qmdReindexAfterSync(args?: string[], options?: QmdReindexOptions): number;
 //# sourceMappingURL=qmd-reindex-after-sync.d.ts.map

package/dist/lib/core-utils/qmd-reindex-after-sync.js

@@ -12,6 +12,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { reconcileCollections, resolveQmdBin, runQmd } from "../search-index/index.js";
+import { applyIndexSizeLimit } from "../search-index/max-doc-bytes.js";
 export function qmdReindexAfterSync(args = [], options = {}) {
     let hqRoot = "";
     let embed = false;
@@ -36,6 +37,7 @@ export function qmdReindexAfterSync(args = [], options = {}) {
         return 0;
     const reconcile = options.reconcile ?? ((root, opts) => reconcileCollections(root, opts));
     const run = options.run ?? ((argv, opts) => runQmd(argv, opts));
+    const sizeLimit = options.sizeLimit ?? ((root) => applyIndexSizeLimit(root));
     // Every qmd interaction is best-effort: the shell suffixed each with `|| true`.
     try {
         reconcile(hqRoot, { bin });
@@ -43,6 +45,16 @@ export function qmdReindexAfterSync(args = [], options = {}) {
     catch {
         /* registration is advisory; an update still helps */
     }
+    // The cap has to land before the update, not after: qmd decides what to read
+    // at glob time, so an ignore entry written afterwards saves nothing on this
+    // pass. This is the post-sync entry point, which reaches `qmd update` without
+    // going through `hq index sync` at all.
+    try {
+        sizeLimit(hqRoot);
+    }
+    catch {
+        /* an uncapped index is worse than none, but still better than a failed sync */
+    }
     try {
         run(["update"], { bin, cwd: hqRoot });
     }

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

@@ -15,6 +15,8 @@ export type BackgroundDependencies = {
     isProcessAlive: (pid: number) => boolean;
     resolveQmdBin: () => string;
     reconcileCollections: (hqRoot: string) => unknown;
+    /** Apply the per-document size cap to qmd's config before the update reads anything. */
+    applyIndexSizeLimit: (hqRoot: string) => unknown;
     runQmd: (args: string[], options?: RunQmdOptions) => QmdProcessResult;
     spawnWorker: (options: {
         logPath: string;

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

@@ -3,6 +3,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { Sentry } from '../../sentry.js';
 import { reconcileCollections as defaultReconcileCollections, resolveQmdBin as defaultResolveQmdBin, runQmd as defaultRunQmd, } from './index.js';
+import { applyIndexSizeLimit as defaultApplyIndexSizeLimit } from './max-doc-bytes.js';
 const LOCK_NAME = 'qmd-reindex-bg.lock';
 const COMPLETE_NAME = 'qmd-reindex-bg.completed';
 function errnoInfo(error) {
@@ -119,6 +120,7 @@ export function defaultBackgroundDependencies(hqRoot) {
         isProcessAlive: alive,
         resolveQmdBin: defaultResolveQmdBin,
         reconcileCollections: defaultReconcileCollections,
+        applyIndexSizeLimit: defaultApplyIndexSizeLimit,
         runQmd: defaultRunQmd,
         spawnWorker: defaultSpawnWorker,
     };
@@ -420,6 +422,21 @@ function capWorkerLog(logPath, env) {
 function stepOutput(result) {
     return `${result.stdout ?? ''}${result.stderr ?? ''}`;
 }
+/**
+ * One worker-log line summarising the size cap, so an operator reading the log
+ * can see WHY a file stopped being indexed. Shaped defensively because the
+ * dependency is typed `unknown` at the seam.
+ */
+function sizeLimitOutput(result) {
+    const r = result;
+    if (typeof r?.maxBytes !== 'number')
+        return '';
+    if (r.maxBytes === 0)
+        return '[qmd-reindex-bg] size cap disabled\n';
+    const collections = r.collections ?? [];
+    const files = collections.reduce((total, collection) => total + collection.ignored.length, 0);
+    return `[qmd-reindex-bg] size cap ${r.maxBytes}B — ${files} file(s) skipped across ${collections.length} collection(s)\n`;
+}
 function errorOutput(error) {
     const e = error;
     return `${e.stdout ?? ''}${e.stderr ?? ''}` || (e.message ?? '');
@@ -500,6 +517,17 @@ export async function runBackgroundWorker(dependencies) {
             // The shell worker has no collection-registration step. Keep this #306
             // integration best-effort so it cannot suppress a later index update.
         }
+        // The size cap rewrites qmd's ignore lists, so it MUST land before the
+        // update below — an oversized file is skipped at glob time or not at all.
+        // Best-effort for the same reason as reconciliation: a capping failure must
+        // not suppress an otherwise healthy index update.
+        try {
+            const capped = dependencies.applyIndexSizeLimit(dependencies.hqRoot);
+            appendWorkerLog(logPath, sizeLimitOutput(capped));
+        }
+        catch (error) {
+            appendWorkerLog(logPath, errorOutput(error));
+        }
         if (await signalWindow())
             return { state: 'terminated' };
         try {

package/dist/lib/search-index/max-doc-bytes.d.ts

@@ -0,0 +1,220 @@
+/**
+ * Document size cap for the local HQ search index.
+ *
+ * WHY THIS EXISTS
+ *
+ * qmd indexes a collection by globbing its mask and reading every match — there
+ * is no size check anywhere on that path (`reindexCollection` in @tobilu/qmd
+ * 2.5.3 goes straight from the glob to `readFileSync`). HQ's project
+ * collections are registered with a `md`/`json` mask, which sweeps in build
+ * artifacts nobody would ever search as prose: browser trace dumps, perf
+ * captures, scraped datasets, lockfiles.
+ *
+ * Embedding is the consumer that makes this expensive. `qmd embed` runs under a
+ * hard 30-minute session cap; once the corpus stops fitting inside that budget
+ * the run aborts and discards its work, so an oversized corpus does not merely
+ * cost CPU — it stops the index ever converging.
+ *
+ * HOW IT WORKS
+ *
+ * qmd has no size option, but it does honour a per-collection `ignore` list of
+ * globs, applied at glob time, so an ignored file is never read, never chunked
+ * and never embedded. That list is not reachable through `qmd collection add`
+ * (there is no flag) and qmd's own YAML writer drops the key — but qmd's READER
+ * passes the parsed YAML collection object straight through to the store, and
+ * `syncConfigToDb` treats external config as authoritative ("External config
+ * always wins"). Writing an `ignore:` key into qmd's `index.yml` is therefore a
+ * durable way to express the cap, and it survives qmd's config resync.
+ *
+ * So: resolve the configured cap, walk each collection the way qmd would, and
+ * rewrite its `ignore` list to the files currently over the cap. The list is
+ * recomputed every run, so a file that shrinks or is deleted stops being
+ * ignored with no manual cleanup.
+ *
+ * OWNERSHIP
+ *
+ * The `ignore` list is shared with whatever an operator hand-wrote into
+ * `index.yml`. We therefore never treat "looks like our output" as proof of
+ * provenance: entries this module INTRODUCED are recorded in
+ * `<hqRoot>/.hq/index-size-ignores.json`, and only entries named in that record
+ * are removed on a later run. Anything else in `ignore` is left untouched.
+ *
+ * "Introduced" is doing real work in that sentence. An operator who already
+ * wrote `big.md` by hand keeps owning it even when our scan independently finds
+ * the same file oversized, so lowering the cap later can never delete their
+ * line. The record is also written BEFORE the config: an entry whose provenance
+ * failed to persist would read as foreign forever, which is to say permanently
+ * un-removable, and skipping the change is the cheaper mistake.
+ */
+import * as fs from "node:fs";
+/**
+ * Default cap: 100 KB. Chosen against a real HQ corpus where the median indexed
+ * document is ~1.2 KB — a 100 KB document is three orders of magnitude off the
+ * median and is, in practice, always generated output rather than prose.
+ */
+export declare const DEFAULT_INDEX_MAX_DOC_BYTES: number;
+/** Where this module records the ignore entries it generated. */
+export declare function sizeIgnoreRecordPath(hqRoot: string): string;
+/**
+ * qmd's config file, resolved the way qmd's own CLI resolves it.
+ *
+ * Mirrors `dist/cli/qmd.js`: with no `--index` flag, a project-local
+ * `.qmd/index.yaml` (then `.qmd/index.yml`), found by walking up from the
+ * directory qmd runs in, overrides the global config entirely. Otherwise the
+ * global ladder applies: `QMD_CONFIG_DIR`, then `XDG_CONFIG_HOME/qmd`, then
+ * `$HOME/.config/qmd`.
+ *
+ * Getting this wrong fails silently in the worst way: we would write a correct
+ * `ignore` list into a file qmd never reads, every test asserting the key would
+ * pass, and nothing would actually be skipped. A `$HOME`-only version of this
+ * function shipped to CI and did exactly that, because GitHub runners set
+ * `XDG_CONFIG_HOME` — the e2e positive control is what caught it.
+ *
+ * Returns undefined when no rung resolves, which callers treat as "no config to
+ * update" rather than inventing a path.
+ */
+export declare function resolveQmdConfigPath(opts: {
+    env: NodeJS.ProcessEnv;
+    /** Directory qmd will run in; hq-cli always invokes it with cwd = hqRoot. */
+    startDir?: string;
+    existsFile?: (p: string) => boolean;
+}): string | undefined;
+/**
+ * Resolve the per-document size cap in bytes. Precedence, first match wins:
+ *
+ *   1. `HQ_INDEX_MAX_DOC_BYTES` env var (integer bytes),
+ *   2. `<hqRoot>/.hq/config.json` → `indexMaxDocBytes` (integer bytes),
+ *   3. `DEFAULT_INDEX_MAX_DOC_BYTES` (100 KB).
+ *
+ * `0` disables the cap — and is honoured rather than ignored, so turning the
+ * setting off also clears any ignore entries a previous run wrote.
+ *
+ * A negative, non-integer or otherwise unparseable override falls through to
+ * the next source rather than throwing: this is operator-facing config and a
+ * typo must not break an index run.
+ */
+export declare function resolveIndexMaxDocBytes(opts?: {
+    hqRoot?: string;
+    /** Test seam — defaults to `process.env.HQ_INDEX_MAX_DOC_BYTES`. */
+    envValue?: string | undefined;
+    readFile?: (p: string) => string;
+    existsFile?: (p: string) => boolean;
+}): number;
+/**
+ * Extensions a qmd mask selects, lowercased and without the dot.
+ *
+ * HQ registers exactly two mask shapes today (see `deriveCollections`), but an
+ * operator's own collection may carry anything. An unrecognised mask returns
+ * `null`, meaning "match every file" — the cap then applies to the whole
+ * collection, which is the safe direction: we may ignore a file qmd would not
+ * have indexed (a no-op) rather than miss one it would.
+ */
+export declare function maskExtensions(mask: string): Set<string> | null;
+/** Injected filesystem seam, so the walk is testable without a real tree. */
+export type OversizedScanIo = {
+    readdirSync: (directory: string) => fs.Dirent[];
+    statSync: (file: string) => {
+        size: number;
+    };
+};
+/**
+ * Escape a relative path so qmd's glob matcher treats it as a literal filename.
+ *
+ * Without this, a file genuinely named `reports/[final].json` becomes a
+ * character class: it fails to ignore itself (so the oversized document is
+ * still indexed) while matching unrelated paths like `reports/f.json` (so a
+ * small document silently disappears from search). Both halves of that are
+ * worse than not having the cap.
+ */
+export declare function escapeGlobLiteral(relativePath: string): string;
+/** Outcome of walking one collection for oversized files. */
+export type OversizedScan = {
+    /** Escaped, sorted glob literals for files over the cap. */
+    oversized: string[];
+    /**
+     * Escaped literals for every file the walk POSITIVELY evaluated, over the cap
+     * or under it. An owned ignore entry missing from this set was not observed,
+     * which is only proof the file is gone when `complete` is true.
+     */
+    evaluated: Set<string>;
+    /** False when any directory or file could not be read, so the walk has gaps. */
+    complete: boolean;
+};
+/**
+ * Walk `collectionPath` for files the mask selects whose size exceeds `maxBytes`.
+ *
+ * Mirrors qmd's own walk: excluded directories are skipped, dot-prefixed files
+ * and directories are skipped at every level, and symlinks are never followed.
+ *
+ * `prunePrefixes` carries directory prefixes already excluded by the
+ * collection's own ignore globs. Descending into them would burn exactly the
+ * CPU this cap exists to save, and qmd is not going to read them anyway.
+ *
+ * A failure to read a directory or stat a file sets `complete = false` rather
+ * than being silently treated as "not oversized". The difference matters: an
+ * unreadable file that is still on disk must keep its existing ignore entry,
+ * because dropping it would let the next update read the very document the cap
+ * was protecting against.
+ */
+export declare function findOversizedFiles(collectionPath: string, mask: string, maxBytes: number, io?: OversizedScanIo, prunePrefixes?: readonly string[]): OversizedScan;
+/**
+ * Directory prefixes an operator's own ignore globs already exclude.
+ *
+ * Only the `dir/**` and `dir/**\/*` shapes are recognised. Any other glob stays
+ * unpruned, which costs a walk we did not need but never changes the result —
+ * the conservative direction for a heuristic whose only job is saving work.
+ */
+export declare function prunablePrefixes(patterns: readonly string[]): string[];
+/** What a single collection ended up ignoring on account of the size cap. */
+export type CappedCollection = {
+    name: string;
+    ignored: string[];
+};
+export type IndexSizeLimitResult = {
+    /** The cap that was applied. `0` means the cap is disabled. */
+    maxBytes: number;
+    /** qmd's config file, or undefined when there was none to update. */
+    configPath?: string;
+    /** Per-collection oversized files, only for collections that have any. */
+    collections: CappedCollection[];
+    /** True when qmd's config was actually rewritten. */
+    changed: boolean;
+};
+export type ApplyIndexSizeLimitOptions = {
+    /** Test seam — defaults to `process.env`. */
+    env?: NodeJS.ProcessEnv;
+    maxBytes?: number;
+    scanIo?: OversizedScanIo;
+    readFile?: (p: string) => string;
+    writeFile?: (p: string, contents: string) => void;
+    existsFile?: (p: string) => boolean;
+    mkdir?: (p: string) => void;
+};
+/**
+ * Apply the size cap to every collection in qmd's config.
+ *
+ * Runs BEFORE `qmd update`, so the update that follows never reads an oversized
+ * file. Rewrites the config only when the resulting ignore lists differ from
+ * what is already on disk, so a steady-state HQ does no config churn.
+ *
+ * ## Concurrency
+ *
+ * qmd's config is shared with `qmd collection add` and with any other HQ
+ * process running an index pass. A naive read, long scan, then full-file dump
+ * would erase a collection registered while the scan was running.
+ *
+ * The order here is read, scan, RE-READ, then write. That re-read is the part
+ * that matters: the scan is slow (it walks every collection), so the config can
+ * easily move while it runs, and comparing the fresh bytes against the ones the
+ * merge was computed from catches exactly that. On a mismatch the whole merge is
+ * recomputed against the newer config, up to {@link CONFIG_WRITE_ATTEMPTS}
+ * times, after which we decline to write rather than guess. The write itself is
+ * a temp-file rename, so no reader ever sees a half-written config.
+ *
+ * This narrows the window to the microseconds between the re-read and the
+ * rename; it is not a mutex. A writer that lands inside that gap still loses.
+ * A lockfile would not close it either, because qmd's own writers would not
+ * take the lock, so the residual race is documented rather than papered over.
+ */
+export declare function applyIndexSizeLimit(hqRoot: string, options?: ApplyIndexSizeLimitOptions): IndexSizeLimitResult;
+//# sourceMappingURL=max-doc-bytes.d.ts.map

package/dist/lib/search-index/max-doc-bytes.js

@@ -0,0 +1,463 @@
+/**
+ * Document size cap for the local HQ search index.
+ *
+ * WHY THIS EXISTS
+ *
+ * qmd indexes a collection by globbing its mask and reading every match — there
+ * is no size check anywhere on that path (`reindexCollection` in @tobilu/qmd
+ * 2.5.3 goes straight from the glob to `readFileSync`). HQ's project
+ * collections are registered with a `md`/`json` mask, which sweeps in build
+ * artifacts nobody would ever search as prose: browser trace dumps, perf
+ * captures, scraped datasets, lockfiles.
+ *
+ * Embedding is the consumer that makes this expensive. `qmd embed` runs under a
+ * hard 30-minute session cap; once the corpus stops fitting inside that budget
+ * the run aborts and discards its work, so an oversized corpus does not merely
+ * cost CPU — it stops the index ever converging.
+ *
+ * HOW IT WORKS
+ *
+ * qmd has no size option, but it does honour a per-collection `ignore` list of
+ * globs, applied at glob time, so an ignored file is never read, never chunked
+ * and never embedded. That list is not reachable through `qmd collection add`
+ * (there is no flag) and qmd's own YAML writer drops the key — but qmd's READER
+ * passes the parsed YAML collection object straight through to the store, and
+ * `syncConfigToDb` treats external config as authoritative ("External config
+ * always wins"). Writing an `ignore:` key into qmd's `index.yml` is therefore a
+ * durable way to express the cap, and it survives qmd's config resync.
+ *
+ * So: resolve the configured cap, walk each collection the way qmd would, and
+ * rewrite its `ignore` list to the files currently over the cap. The list is
+ * recomputed every run, so a file that shrinks or is deleted stops being
+ * ignored with no manual cleanup.
+ *
+ * OWNERSHIP
+ *
+ * The `ignore` list is shared with whatever an operator hand-wrote into
+ * `index.yml`. We therefore never treat "looks like our output" as proof of
+ * provenance: entries this module INTRODUCED are recorded in
+ * `<hqRoot>/.hq/index-size-ignores.json`, and only entries named in that record
+ * are removed on a later run. Anything else in `ignore` is left untouched.
+ *
+ * "Introduced" is doing real work in that sentence. An operator who already
+ * wrote `big.md` by hand keeps owning it even when our scan independently finds
+ * the same file oversized, so lowering the cap later can never delete their
+ * line. The record is also written BEFORE the config: an entry whose provenance
+ * failed to persist would read as foreign forever, which is to say permanently
+ * un-removable, and skipping the change is the cheaper mistake.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import YAML from "js-yaml";
+/**
+ * Default cap: 100 KB. Chosen against a real HQ corpus where the median indexed
+ * document is ~1.2 KB — a 100 KB document is three orders of magnitude off the
+ * median and is, in practice, always generated output rather than prose.
+ */
+export const DEFAULT_INDEX_MAX_DOC_BYTES = 100 * 1024;
+/**
+ * Directories qmd's own reindex never descends into. Mirrored here so our scan
+ * sees exactly the files qmd would index — an ignore entry for a file qmd never
+ * reads is harmless, but it makes the generated list misleading to read.
+ */
+const EXCLUDED_DIRECTORIES = new Set([
+    "node_modules",
+    ".git",
+    ".cache",
+    "vendor",
+    "dist",
+    "build",
+]);
+/** Where this module records the ignore entries it generated. */
+export function sizeIgnoreRecordPath(hqRoot) {
+    return path.join(hqRoot, ".hq", "index-size-ignores.json");
+}
+/** qmd's default index name; the config file and store are both named after it. */
+const QMD_INDEX_NAME = "index";
+/**
+ * qmd's config file, resolved the way qmd's own CLI resolves it.
+ *
+ * Mirrors `dist/cli/qmd.js`: with no `--index` flag, a project-local
+ * `.qmd/index.yaml` (then `.qmd/index.yml`), found by walking up from the
+ * directory qmd runs in, overrides the global config entirely. Otherwise the
+ * global ladder applies: `QMD_CONFIG_DIR`, then `XDG_CONFIG_HOME/qmd`, then
+ * `$HOME/.config/qmd`.
+ *
+ * Getting this wrong fails silently in the worst way: we would write a correct
+ * `ignore` list into a file qmd never reads, every test asserting the key would
+ * pass, and nothing would actually be skipped. A `$HOME`-only version of this
+ * function shipped to CI and did exactly that, because GitHub runners set
+ * `XDG_CONFIG_HOME` — the e2e positive control is what caught it.
+ *
+ * Returns undefined when no rung resolves, which callers treat as "no config to
+ * update" rather than inventing a path.
+ */
+export function resolveQmdConfigPath(opts) {
+    const exists = opts.existsFile ?? fs.existsSync;
+    if (opts.startDir) {
+        const local = findLocalQmdConfig(path.resolve(opts.startDir), exists);
+        if (local)
+            return local;
+    }
+    const configDir = opts.env.QMD_CONFIG_DIR?.trim();
+    if (configDir)
+        return path.join(configDir, `${QMD_INDEX_NAME}.yml`);
+    const xdg = opts.env.XDG_CONFIG_HOME?.trim();
+    if (xdg)
+        return path.join(xdg, "qmd", `${QMD_INDEX_NAME}.yml`);
+    const home = opts.env.HOME?.trim();
+    if (home)
+        return path.join(home, ".config", "qmd", `${QMD_INDEX_NAME}.yml`);
+    return undefined;
+}
+/** Nearest `.qmd/index.{yaml,yml}` at or above `startDir`, matching qmd's walk. */
+function findLocalQmdConfig(startDir, exists) {
+    let dir = startDir;
+    for (;;) {
+        for (const name of ["index.yaml", "index.yml"]) {
+            const candidate = path.join(dir, ".qmd", name);
+            if (exists(candidate))
+                return candidate;
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return undefined;
+        dir = parent;
+    }
+}
+/**
+ * Resolve the per-document size cap in bytes. Precedence, first match wins:
+ *
+ *   1. `HQ_INDEX_MAX_DOC_BYTES` env var (integer bytes),
+ *   2. `<hqRoot>/.hq/config.json` → `indexMaxDocBytes` (integer bytes),
+ *   3. `DEFAULT_INDEX_MAX_DOC_BYTES` (100 KB).
+ *
+ * `0` disables the cap — and is honoured rather than ignored, so turning the
+ * setting off also clears any ignore entries a previous run wrote.
+ *
+ * A negative, non-integer or otherwise unparseable override falls through to
+ * the next source rather than throwing: this is operator-facing config and a
+ * typo must not break an index run.
+ */
+export function resolveIndexMaxDocBytes(opts = {}) {
+    const fromEnv = parseNonNegativeInt(opts.envValue !== undefined ? opts.envValue : process.env.HQ_INDEX_MAX_DOC_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 = parseNonNegativeInt(cfg.indexMaxDocBytes);
+                if (fromCfg !== null)
+                    return fromCfg;
+            }
+            catch {
+                // Malformed config → fall through to the default.
+            }
+        }
+    }
+    return DEFAULT_INDEX_MAX_DOC_BYTES;
+}
+/** A finite, non-negative integer parsed from a string/number, else null. */
+function parseNonNegativeInt(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;
+}
+/**
+ * Extensions a qmd mask selects, lowercased and without the dot.
+ *
+ * HQ registers exactly two mask shapes today (see `deriveCollections`), but an
+ * operator's own collection may carry anything. An unrecognised mask returns
+ * `null`, meaning "match every file" — the cap then applies to the whole
+ * collection, which is the safe direction: we may ignore a file qmd would not
+ * have indexed (a no-op) rather than miss one it would.
+ */
+export function maskExtensions(mask) {
+    const braced = /^\*\*\/\*\.\{([^}]+)\}$/.exec(mask);
+    if (braced) {
+        return new Set(braced[1].split(",").map((ext) => ext.trim().toLowerCase()).filter(Boolean));
+    }
+    const single = /^\*\*\/\*\.([A-Za-z0-9]+)$/.exec(mask);
+    if (single)
+        return new Set([single[1].toLowerCase()]);
+    return null;
+}
+const defaultScanIo = {
+    readdirSync: (directory) => fs.readdirSync(directory, { withFileTypes: true }),
+    statSync: (file) => fs.statSync(file),
+};
+/**
+ * Characters picomatch (via fast-glob, which is what qmd globs with) treats as
+ * pattern syntax rather than literal text. `^` and `$` are deliberately absent:
+ * they are regex syntax, not glob syntax, and escaping them would be a guess.
+ */
+const GLOB_META = /[\\*?[\]{}()!+@|]/g;
+/** Same set, without the `g` flag, so `.test()` carries no `lastIndex` state. */
+const HAS_GLOB_META = /[\\*?[\]{}()!+@|]/;
+/**
+ * Escape a relative path so qmd's glob matcher treats it as a literal filename.
+ *
+ * Without this, a file genuinely named `reports/[final].json` becomes a
+ * character class: it fails to ignore itself (so the oversized document is
+ * still indexed) while matching unrelated paths like `reports/f.json` (so a
+ * small document silently disappears from search). Both halves of that are
+ * worse than not having the cap.
+ */
+export function escapeGlobLiteral(relativePath) {
+    return relativePath.replace(GLOB_META, (character) => `\\${character}`);
+}
+/**
+ * Walk `collectionPath` for files the mask selects whose size exceeds `maxBytes`.
+ *
+ * Mirrors qmd's own walk: excluded directories are skipped, dot-prefixed files
+ * and directories are skipped at every level, and symlinks are never followed.
+ *
+ * `prunePrefixes` carries directory prefixes already excluded by the
+ * collection's own ignore globs. Descending into them would burn exactly the
+ * CPU this cap exists to save, and qmd is not going to read them anyway.
+ *
+ * A failure to read a directory or stat a file sets `complete = false` rather
+ * than being silently treated as "not oversized". The difference matters: an
+ * unreadable file that is still on disk must keep its existing ignore entry,
+ * because dropping it would let the next update read the very document the cap
+ * was protecting against.
+ */
+export function findOversizedFiles(collectionPath, mask, maxBytes, io = defaultScanIo, prunePrefixes = []) {
+    const evaluated = new Set();
+    if (maxBytes <= 0)
+        return { oversized: [], evaluated, complete: true };
+    const extensions = maskExtensions(mask);
+    const pruned = new Set(prunePrefixes);
+    const found = [];
+    let complete = true;
+    const walk = (directory, relative) => {
+        let entries;
+        try {
+            entries = io.readdirSync(directory);
+        }
+        catch {
+            complete = false; // A gap, not an absence.
+            return;
+        }
+        for (const entry of entries) {
+            if (entry.name.startsWith("."))
+                continue;
+            const childRelative = relative ? `${relative}/${entry.name}` : entry.name;
+            if (entry.isDirectory()) {
+                if (EXCLUDED_DIRECTORIES.has(entry.name))
+                    continue;
+                if (pruned.has(childRelative))
+                    continue;
+                walk(path.join(directory, entry.name), childRelative);
+                continue;
+            }
+            if (!entry.isFile())
+                continue;
+            if (extensions) {
+                const ext = path.extname(entry.name).slice(1).toLowerCase();
+                if (!extensions.has(ext))
+                    continue;
+            }
+            const literal = escapeGlobLiteral(childRelative);
+            try {
+                const { size } = io.statSync(path.join(directory, entry.name));
+                evaluated.add(literal);
+                if (size > maxBytes)
+                    found.push(literal);
+            }
+            catch {
+                complete = false; // Unreadable now; it may still be oversized.
+            }
+        }
+    };
+    walk(collectionPath, "");
+    return {
+        oversized: found.sort((left, right) => left.localeCompare(right)),
+        evaluated,
+        complete,
+    };
+}
+/**
+ * Directory prefixes an operator's own ignore globs already exclude.
+ *
+ * Only the `dir/**` and `dir/**\/*` shapes are recognised. Any other glob stays
+ * unpruned, which costs a walk we did not need but never changes the result —
+ * the conservative direction for a heuristic whose only job is saving work.
+ */
+export function prunablePrefixes(patterns) {
+    const prefixes = [];
+    for (const pattern of patterns) {
+        const match = /^(.+?)\/\*\*(?:\/\*)?$/.exec(pattern);
+        if (match && !HAS_GLOB_META.test(match[1]))
+            prefixes.push(match[1]);
+    }
+    return prefixes;
+}
+/** How many times to re-read and re-merge when the config moves under us. */
+const CONFIG_WRITE_ATTEMPTS = 3;
+/**
+ * Apply the size cap to every collection in qmd's config.
+ *
+ * Runs BEFORE `qmd update`, so the update that follows never reads an oversized
+ * file. Rewrites the config only when the resulting ignore lists differ from
+ * what is already on disk, so a steady-state HQ does no config churn.
+ *
+ * ## Concurrency
+ *
+ * qmd's config is shared with `qmd collection add` and with any other HQ
+ * process running an index pass. A naive read, long scan, then full-file dump
+ * would erase a collection registered while the scan was running.
+ *
+ * The order here is read, scan, RE-READ, then write. That re-read is the part
+ * that matters: the scan is slow (it walks every collection), so the config can
+ * easily move while it runs, and comparing the fresh bytes against the ones the
+ * merge was computed from catches exactly that. On a mismatch the whole merge is
+ * recomputed against the newer config, up to {@link CONFIG_WRITE_ATTEMPTS}
+ * times, after which we decline to write rather than guess. The write itself is
+ * a temp-file rename, so no reader ever sees a half-written config.
+ *
+ * This narrows the window to the microseconds between the re-read and the
+ * rename; it is not a mutex. A writer that lands inside that gap still loses.
+ * A lockfile would not close it either, because qmd's own writers would not
+ * take the lock, so the residual race is documented rather than papered over.
+ */
+export function applyIndexSizeLimit(hqRoot, options = {}) {
+    const env = options.env ?? process.env;
+    const maxBytes = options.maxBytes ?? resolveIndexMaxDocBytes({ hqRoot, envValue: env.HQ_INDEX_MAX_DOC_BYTES });
+    const exists = options.existsFile ?? fs.existsSync;
+    const read = options.readFile ?? ((p) => fs.readFileSync(p, "utf-8"));
+    const write = options.writeFile ?? atomicWrite;
+    const mkdir = options.mkdir ?? ((p) => fs.mkdirSync(p, { recursive: true }));
+    const configPath = resolveQmdConfigPath({ env, startDir: hqRoot, existsFile: exists });
+    if (!configPath)
+        return { maxBytes, collections: [], changed: false };
+    if (!exists(configPath))
+        return { maxBytes, configPath, collections: [], changed: false };
+    const previouslyOwned = readIgnoreRecord(hqRoot, { exists, read });
+    for (let attempt = 0; attempt < CONFIG_WRITE_ATTEMPTS; attempt++) {
+        let original;
+        let config;
+        try {
+            original = read(configPath);
+            config = YAML.load(original) ?? {};
+        }
+        catch {
+            // A config we cannot parse is a config we must not rewrite.
+            return { maxBytes, configPath, collections: [], changed: false };
+        }
+        const collections = config.collections;
+        if (!collections || typeof collections !== "object") {
+            return { maxBytes, configPath, collections: [], changed: false };
+        }
+        const nowOwned = {};
+        const capped = [];
+        for (const [name, entry] of Object.entries(collections)) {
+            if (!entry || typeof entry !== "object")
+                continue;
+            const collectionPath = typeof entry.path === "string" ? entry.path : undefined;
+            if (!collectionPath)
+                continue;
+            const mask = typeof entry.pattern === "string" ? entry.pattern : "**/*.md";
+            const existing = Array.isArray(entry.ignore)
+                ? entry.ignore.filter((value) => typeof value === "string")
+                : [];
+            // Provenance: an entry is ours only if a previous run recorded writing it.
+            const ours = new Set(previouslyOwned[name] ?? []);
+            const foreign = existing.filter((value) => !ours.has(value));
+            const foreignSet = new Set(foreign);
+            const scan = exists(collectionPath)
+                ? findOversizedFiles(collectionPath, mask, maxBytes, options.scanIo, prunablePrefixes(foreign))
+                : { oversized: [], evaluated: new Set(), complete: false };
+            // Keep an owned entry the scan could not positively re-evaluate. Dropping
+            // it on an incomplete walk would silently re-expose an oversized file.
+            const unverified = scan.complete
+                ? []
+                : [...ours].filter((value) => !scan.evaluated.has(value));
+            const mine = [...new Set([...scan.oversized, ...unverified])]
+                // Never claim an entry the operator already had: if we recorded it as
+                // ours, a later shrink would delete their line, not ours.
+                .filter((value) => !foreignSet.has(value))
+                .sort((left, right) => left.localeCompare(right));
+            const merged = [...new Set([...foreign, ...scan.oversized, ...unverified])].sort((left, right) => left.localeCompare(right));
+            if (merged.length > 0)
+                entry.ignore = merged;
+            else
+                delete entry.ignore;
+            if (mine.length > 0)
+                nowOwned[name] = mine;
+            if (scan.oversized.length > 0)
+                capped.push({ name, ignored: scan.oversized });
+        }
+        const updated = YAML.dump(config, { lineWidth: 0 });
+        if (updated === original)
+            return { maxBytes, configPath, collections: capped, changed: false };
+        // Provenance first. A config mutation whose record is lost leaves entries
+        // that look foreign forever, so neither a shrinking file nor `0` can clear
+        // them. Better to skip the mutation than to strand it.
+        if (!writeIgnoreRecord(hqRoot, nowOwned, { mkdir, write })) {
+            return { maxBytes, configPath, collections: capped, changed: false };
+        }
+        // Re-read immediately before writing: if another writer landed since the
+        // read above, recompute against their version rather than erasing it.
+        let current;
+        try {
+            current = read(configPath);
+        }
+        catch {
+            return { maxBytes, configPath, collections: capped, changed: false };
+        }
+        if (current !== original)
+            continue;
+        write(configPath, updated);
+        return { maxBytes, configPath, collections: capped, changed: true };
+    }
+    return { maxBytes, configPath, collections: [], changed: false };
+}
+/** Write via temp file + rename, so a concurrent reader never sees a partial config. */
+function atomicWrite(target, contents) {
+    const temporary = `${target}.hq-${process.pid}.tmp`;
+    fs.writeFileSync(temporary, contents, "utf-8");
+    fs.renameSync(temporary, target);
+}
+function readIgnoreRecord(hqRoot, io) {
+    const recordPath = sizeIgnoreRecordPath(hqRoot);
+    if (!io.exists(recordPath))
+        return {};
+    try {
+        const parsed = JSON.parse(io.read(recordPath));
+        const result = {};
+        for (const [name, value] of Object.entries(parsed)) {
+            if (Array.isArray(value)) {
+                result[name] = value.filter((v) => typeof v === "string");
+            }
+        }
+        return result;
+    }
+    catch {
+        return {}; // A corrupt record means we claim nothing, and clobber nothing.
+    }
+}
+/** True when the record landed; false tells the caller not to mutate the config. */
+function writeIgnoreRecord(hqRoot, owned, io) {
+    const recordPath = sizeIgnoreRecordPath(hqRoot);
+    try {
+        io.mkdir(path.dirname(recordPath));
+        io.write(recordPath, `${JSON.stringify(owned, null, 2)}\n`);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=max-doc-bytes.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.112.0",
+  "version": "5.113.0",
   "description": "HQ by Indigo management CLI \u2014 modules and cloud sync",
   "main": "dist/index.js",
   "bin": {